Visual Validation¶

Automatic detection of common rendering issues that are invisible in stdout-only environments (e.g. AI agent pipelines). Every check emits structured [VISUAL] log lines so agents can grep and auto-correct.

validate_figure runs all checks by default and is integrated into save_formats() (enabled via validate=True).

Available Checks¶

Check ID	Description	Severity
`OVERFLOW`	Text, tick labels, or figure-level text extend past the canvas	WARNING
`OVERLAP`	Text labels overlap within a single axes	WARNING
`UNIT_DUP`	Axis label declares a unit also shown as a tick affix	WARNING
`CROSS_AXES_OVERLAP`	Labels from different axes overlap in multi-panel figures	WARNING
`LEGEND_OVERFLOW`	Legends dominate the axes or spill past the figure	WARNING
`TICK_CROWD`	Tick labels consume more space than the axis can comfortably hold	INFO
`TICK_ROTATION`	X tick labels are rotated needlessly or overlap when horizontal	INFO
`TICK_DECIMAL`	Numeric tick labels are mixed, ambiguous, or over-precise for their step	WARNING / INFO
`EMPTY_AXES`	Axes contain no visible plotted artist or annotation	INFO
`MARGIN_ASYMMETRY`	Opposite outer margins differ by more than the threshold	WARNING
`PIE_LABEL_OFFSET`	Donut-chart percentage labels are not centered in the ring	INFO
`CLIPPED_TEXT`	Text is clipped at an axes or canvas boundary	WARNING

Example¶

import matplotlib.pyplot as plt
import dartwork_mpl as dm

fig, ax = plt.subplots()
ax.plot([0, 1], [0, 1])

# Run all checks
warnings = dm.validate_figure(fig)
for w in warnings:
    print(w)

# Run specific checks only
warnings = dm.validate_figure(fig, checks=('OVERLAP', 'TICK_CROWD'))

# Integrated in save_formats (on by default)
dm.save_formats(fig, 'output/fig', validate=True)

API¶

Core Validation¶

dartwork_mpl.validate_figure(fig: Figure, *, checks: tuple[str, ...] | None = None, quiet: bool = False) → list[VisualWarning][source]¶

Run comprehensive visual validation on a Matplotlib figure.

Parameters:

fig (matplotlib.figure.Figure) – The figure to inspect for visual defects.
checks (tuple[str, ...] | None, optional) – Check IDs to run. If None, all registered checks are executed. Supported IDs: OVERFLOW, OVERLAP, UNIT_DUP, CROSS_AXES_OVERLAP, LEGEND_OVERFLOW, TICK_CROWD, TICK_ROTATION, TICK_DECIMAL, EMPTY_AXES, MARGIN_ASYMMETRY, PIE_LABEL_OFFSET, CLIPPED_TEXT.
quiet (bool, optional) – If True, suppresses stdout output. Default is False.

Returns:

List of detected visual issues.

Return type:

list[VisualWarning]

Enhanced Validation with Auto-Fix¶

The validate_fixes module provides advanced validation with automatic fix suggestions, particularly useful for AI agents and automated pipelines.

Enhanced validation with auto-fix suggestions for agents.

Extends the base validation with actionable fixes that agents can apply.

dartwork_mpl.validate_fixes.check_agent_requirements(fig: Figure) → dict[str, bool][source]

Check if figure meets agent coding requirements.

Parameters:: fig (Figure) – Figure to check
Returns:: Requirement name -> pass/fail
Return type:: dict[str, bool]

dartwork_mpl.validate_fixes.generate_validation_report(fig: Figure) → str[source]

Generate a comprehensive validation report for agents.

Parameters:: fig (Figure) – Figure to validate
Returns:: Formatted validation report
Return type:: str

dartwork_mpl.validate_fixes.get_fix_suggestions(warning: VisualWarning) → list[str][source]

Generate fix suggestions for a visual warning.

Looks up warning.check_id in the handler registry above and delegates to the matching handler. Unknown check IDs return [] so callers don’t have to special-case them.

Parameters:: warning (VisualWarning) – The warning to generate fixes for
Returns:: List of suggested fixes (code snippets). Empty if no handler is registered for warning.check_id.
Return type:: list[str]

dartwork_mpl.validate_fixes.validate_with_fixes(fig: Figure, auto_apply: bool = False, verbose: bool = True) → tuple[list[VisualWarning], list[str]][source]

Validate figure and provide fix suggestions.

Parameters:

fig (Figure) – Figure to validate
auto_apply (bool) – Whether to attempt automatic fixes
verbose (bool) – Whether to print suggestions

Returns:

Warnings and applied fixes

Return type:

tuple[list[VisualWarning], list[str]]

Example with Auto-Fix¶

import dartwork_mpl as dm
from dartwork_mpl.validate_fixes import (
    generate_validation_report,
    get_fix_suggestions,
    validate_with_fixes,
)

# Validate and get fix suggestions
issues, fixes = validate_with_fixes(fig)

# `fixes` is a list[str] of auto-applied changes. To inspect
# suggestions without mutating the figure, ask for each issue.
for issue in issues:
    for suggestion in get_fix_suggestions(issue):
        print(suggestion)

# Or ask validate_with_fixes to apply its safe layout fix once.
issues_after, applied = validate_with_fixes(fig, auto_apply=True)
print(applied)

# Generate report for logging
report = generate_validation_report(fig)
print(report)