Skip to main content

mellea.stdlib.requirements.plotting.matplotlib

Matplotlib-specific code generation requirements.

This module validates Python code that uses matplotlib for plotting, ensuring proper headless backend configuration, file I/O, and dependency availability.

Functions​

FUNC python_plotting_requirements ​

python_plotting_requirements(output_path: str, allowed_imports: list[str] | None = None, output_limit_chars: int = 10000, timeout_seconds: int = 5, use_sandbox: bool = False) -> list[Requirement]

Bundle matplotlib-specific requirements for plotting code validation.

Factory function that creates a complete set of requirements for validating matplotlib plotting code, composing general Python code generation requirements with plotting-specific constraints for headless backend configuration, file output, and dependency availability.

Args:

  • output_path: File path where the plot should be saved (e.g., '/tmp/plot.png'). This path must match the savefig() call in the generated code.
  • allowed_imports: Whitelist of importable top-level modules. None allows all. Default None.
  • output_limit_chars: Maximum allowed characters of captured stdout. Default 10,000.
  • timeout_seconds: Maximum execution time in seconds. Default 5.
  • use_sandbox: Use llm-sandbox for Docker-isolated execution. Default False.

Returns:

  • list[Requirement]: Seven requirements in validation order: 1-4. PythonCodeExtraction, PythonSyntaxValid, PythonExecutionReq, ImportRestrictions/NoImportRestrictions (from python_code_generation_requirements)
  1. MatplotlibHeadlessBackend — validates headless backend configuration
  2. PlotFileSaved — validates plot is saved to the specified output_path
  3. PlotDependenciesAvailable — validates matplotlib and numpy are available

Raises:

  • ValueError: If output_path is empty or whitespace-only, or if timeout_seconds or output_limit_chars is not positive.

Examples:

>>> output_path = "/tmp/plot.png"
>>> reqs = python_plotting_requirements(output_path=output_path)
>>> len(reqs)
7
>>> isinstance(reqs[4], MatplotlibHeadlessBackend)
True
>>> isinstance(reqs[5], PlotFileSaved)
True
>>> isinstance(reqs[6], PlotDependenciesAvailable)
True
>>> reqs_restricted = python_plotting_requirements(
...     output_path=output_path,
...     allowed_imports=["matplotlib", "numpy"]
... )
>>> len(reqs_restricted)
7

Classes​

CLASS MatplotlibHeadlessBackend ​

Validates that matplotlib is configured with a headless backend.

Matplotlib must be explicitly configured with a headless backend (e.g., 'Agg') via matplotlib.use() before importing pyplot. Interactive backends like 'TkAgg' will fail because they require a display server.

CLASS PlotFileSaved ​

Validates that a plot is explicitly saved to a file.

The plot must be saved using savefig() with the specified output_path. This prevents interactive plot displays (plt.show()) and ensures output can be captured and verified.

Args:

  • output_path: File path where the plot should be saved (e.g., '/tmp/plot.png').

CLASS PlotDependenciesAvailable ​

Validates that matplotlib and numpy are importable.

Both matplotlib and numpy must be available in the execution environment. This requirement checks import availability but does not execute code.