plotstyle 0.1.0a1__py3-none-any.whl

plotstyle/validation/checks/export.py

@@ -0,0 +1,205 @@
+"""Export-readiness validation checks.
+
+This module registers :func:`check_export_settings`, which verifies that
+Matplotlib's global ``rcParams`` are configured for publication-quality output.
+
+Checks performed
+----------------
+1. **PDF font embedding** (``pdf.fonttype``) — must be ``42`` (TrueType
+   embedding).  Setting ``3`` embeds fonts as Type 3 outlines, which many
+   journal submission systems reject.
+2. **PostScript font embedding** (``ps.fonttype``) — same requirement as PDF.
+3. **Save DPI** (``savefig.dpi``) — must be at least the minimum DPI
+   specified in the journal's export spec.  A value of ``"figure"`` (the
+   Matplotlib default) is treated as ``WARN`` because the resolution depends
+   on the figure's screen DPI setting, which is typically 72-100 DPI — below
+   the 300+ DPI required for print.
+
+Why rcParams and not Figure properties?
+----------------------------------------
+Font embedding and output DPI are controlled globally via ``rcParams`` in
+Matplotlib, not per-figure.  Checking them here ensures that the entire
+export pipeline is configured correctly, not just the figure layout.
+
+Example
+-------
+    >>> from plotstyle.validation.checks.export import check_export_settings
+    >>> results = check_export_settings(fig, spec)
+    >>> [r.check_name for r in results]
+    ['export.pdf_fonttype', 'export.ps_fonttype', 'export.dpi']
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import matplotlib as mpl
+
+from plotstyle.validation.checks._base import check
+from plotstyle.validation.report import CheckResult, CheckStatus
+
+if TYPE_CHECKING:
+    from matplotlib.figure import Figure
+
+    from plotstyle.specs.schema import JournalSpec
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+# TrueType font embedding value for pdf.fonttype and ps.fonttype.
+# Type 42 embeds complete TrueType outlines; Type 3 embeds bitmaps/outlines
+# that many PDF pre-flight tools and journal submission systems reject.
+_TRUETYPE_FONTTYPE: int = 42
+
+
+# ---------------------------------------------------------------------------
+# Registered check
+# ---------------------------------------------------------------------------
+
+
+@check
+def check_export_settings(fig: Figure, spec: JournalSpec) -> list[CheckResult]:
+    """Validate Matplotlib export rcParams against journal requirements.
+
+    Inspects three global ``rcParams`` that control the quality and
+    compatibility of saved figures:
+
+    - ``pdf.fonttype`` — must be :data:`_TRUETYPE_FONTTYPE` (42).
+    - ``ps.fonttype``  — must be :data:`_TRUETYPE_FONTTYPE` (42).
+    - ``savefig.dpi``  — must be a numeric value ≥ ``spec.export.min_dpi``.
+
+    Args:
+        fig: The :class:`~matplotlib.figure.Figure` being validated.  Not used
+            by this check (export settings are global), but required by the
+            :data:`~plotstyle.validation.checks._base.CheckFunc` interface.
+        spec: Journal specification providing ``export.min_dpi`` and
+            ``metadata.name`` for error messages.
+
+    Returns
+    -------
+        A list of exactly three :class:`~plotstyle.validation.report.CheckResult`
+        objects in the order: ``pdf_fonttype``, ``ps_fonttype``, ``dpi``.
+
+    Example:
+        >>> import matplotlib as mpl
+        >>> mpl.rcParams["pdf.fonttype"] = 42
+        >>> mpl.rcParams["ps.fonttype"] = 42
+        >>> mpl.rcParams["savefig.dpi"] = 300
+        >>> results = check_export_settings(fig, spec)
+        >>> all(r.status.value == "PASS" for r in results)
+        True
+
+    Notes
+    -----
+        - ``fig`` is explicitly discarded (``_ = fig``) to make it clear this
+          is intentional rather than an oversight.  The variable binding is
+          kept to satisfy the :data:`~plotstyle.validation.checks._base.CheckFunc`
+          interface contract.
+        - A ``savefig.dpi`` value of ``"figure"`` — Matplotlib's default —
+          produces a ``WARN`` rather than a ``FAIL`` because the actual DPI
+          is not deterministic at validation time; it depends on the screen or
+          backend DPI when :meth:`~matplotlib.figure.Figure.savefig` is called.
+    """
+    # `fig` is intentionally unused; this check inspects global rcParams only.
+    _ = fig
+
+    results: list[CheckResult] = []
+
+    # ------------------------------------------------------------------
+    # 1. PDF font embedding
+    # ------------------------------------------------------------------
+    pdf_fonttype: Any = mpl.rcParams.get("pdf.fonttype")
+
+    if pdf_fonttype == _TRUETYPE_FONTTYPE:
+        results.append(
+            CheckResult(
+                status=CheckStatus.PASS,
+                check_name="export.pdf_fonttype",
+                message=f"pdf.fonttype = {_TRUETYPE_FONTTYPE} (TrueType fonts will be embedded in PDF output).",
+            )
+        )
+    else:
+        results.append(
+            CheckResult(
+                status=CheckStatus.FAIL,
+                check_name="export.pdf_fonttype",
+                message=(
+                    f"pdf.fonttype = {pdf_fonttype!r}; must be {_TRUETYPE_FONTTYPE} "
+                    "for TrueType font embedding. Type 3 fonts are rejected by "
+                    "many journal submission systems."
+                ),
+                fix_suggestion=(
+                    f"Call plotstyle.use() to apply all required rcParams, or set "
+                    f"mpl.rcParams['pdf.fonttype'] = {_TRUETYPE_FONTTYPE} manually."
+                ),
+            )
+        )
+
+    # ------------------------------------------------------------------
+    # 2. PostScript font embedding
+    # ------------------------------------------------------------------
+    ps_fonttype: Any = mpl.rcParams.get("ps.fonttype")
+
+    if ps_fonttype == _TRUETYPE_FONTTYPE:
+        results.append(
+            CheckResult(
+                status=CheckStatus.PASS,
+                check_name="export.ps_fonttype",
+                message=f"ps.fonttype = {_TRUETYPE_FONTTYPE} (TrueType fonts will be embedded in PostScript output).",
+            )
+        )
+    else:
+        results.append(
+            CheckResult(
+                status=CheckStatus.FAIL,
+                check_name="export.ps_fonttype",
+                message=(
+                    f"ps.fonttype = {ps_fonttype!r}; must be {_TRUETYPE_FONTTYPE} "
+                    "for TrueType font embedding in PostScript/EPS output."
+                ),
+                fix_suggestion=(
+                    f"Call plotstyle.use() to apply all required rcParams, or set "
+                    f"mpl.rcParams['ps.fonttype'] = {_TRUETYPE_FONTTYPE} manually."
+                ),
+            )
+        )
+
+    # ------------------------------------------------------------------
+    # 3. Save DPI
+    # ------------------------------------------------------------------
+    required_dpi: float = spec.export.min_dpi
+    savefig_dpi: Any = mpl.rcParams.get("savefig.dpi", "figure")
+
+    if isinstance(savefig_dpi, (int, float)) and savefig_dpi >= required_dpi:
+        results.append(
+            CheckResult(
+                status=CheckStatus.PASS,
+                check_name="export.dpi",
+                message=(
+                    f"savefig.dpi = {savefig_dpi} meets the "
+                    f"{spec.metadata.name} minimum of {required_dpi} DPI."
+                ),
+            )
+        )
+    else:
+        # A non-numeric value (e.g., "figure") is a warning rather than a
+        # hard failure because the actual DPI is resolved at save time and
+        # may be overridden by an explicit dpi= kwarg in savefig().
+        results.append(
+            CheckResult(
+                status=CheckStatus.WARN,
+                check_name="export.dpi",
+                message=(
+                    f"savefig.dpi = {savefig_dpi!r}; "
+                    f"{spec.metadata.name} requires ≥ {required_dpi} DPI. "
+                    "The figure may be saved at insufficient resolution."
+                ),
+                fix_suggestion=(
+                    f"Use plotstyle.savefig() which enforces {required_dpi} DPI, "
+                    f"or set mpl.rcParams['savefig.dpi'] = {int(required_dpi)}."
+                ),
+            )
+        )
+
+    return results

plotstyle/validation/checks/lines.py

@@ -0,0 +1,147 @@
+"""Line weight validation check.
+
+This module registers :func:`check_line_weights`, which verifies that every
+:class:`~matplotlib.lines.Line2D` object and every axis spine in a figure
+meets the journal's minimum line weight specification.
+
+Why line weights matter
+-----------------------
+Many journals (particularly IEEE and physical-sciences publishers) specify a
+minimum line weight — typically 0.5 pt — to ensure that figure elements remain
+visible after the half-tone or rasterisation processes applied during printing.
+Lines below this threshold can disappear or appear as artefacts in the final
+publication.
+
+Scope
+-----
+The check covers:
+
+- **Line2D objects** — from ``ax.plot``, ``ax.step``, ``ax.axhline``, etc.
+- **Axis spines** — the box borders drawn around each axes (``top``,
+  ``bottom``, ``left``, ``right``).
+
+Intentionally excluded: tick marks, grid lines, legend borders, and
+collection/patch edges, because these are controlled separately and their
+weight requirements vary more across journals.
+
+Example
+-------
+    >>> from plotstyle.validation.checks.lines import check_line_weights
+    >>> results = check_line_weights(fig, spec)
+    >>> results[0].check_name
+    'lines.min_weight'
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from plotstyle.validation.checks._base import check
+from plotstyle.validation.report import CheckResult, CheckStatus
+
+if TYPE_CHECKING:
+    from matplotlib.figure import Figure
+
+    from plotstyle.specs.schema import JournalSpec
+
+# Maximum number of violation examples to include in the result message
+# before truncating with an implicit "and N more…" (not shown; the user is
+# expected to inspect the figure systematically once they know a problem exists).
+_MAX_VIOLATION_EXAMPLES: int = 5
+
+
+@check
+def check_line_weights(fig: Figure, spec: JournalSpec) -> list[CheckResult]:
+    """Validate line and spine widths against the journal's minimum requirement.
+
+    Iterates over every :class:`~matplotlib.lines.Line2D` and axis spine in
+    *fig* and records any whose ``linewidth`` falls below
+    ``spec.line.min_weight_pt``.
+
+    Args:
+        fig: The :class:`~matplotlib.figure.Figure` to inspect.
+        spec: Journal specification providing ``line.min_weight_pt`` and
+            ``metadata.name`` for error messages.
+
+    Returns
+    -------
+        A list containing exactly one :class:`~plotstyle.validation.report.CheckResult`
+        with check name ``"lines.min_weight"``.  The status is:
+
+        - ``PASS`` — all inspected elements meet the minimum line weight.
+        - ``FAIL`` — one or more elements are below the minimum, with up to
+          :data:`_MAX_VIOLATION_EXAMPLES` offending names and widths listed.
+
+    Example:
+        >>> import matplotlib.pyplot as plt
+        >>> fig, ax = plt.subplots()
+        >>> ax.plot([0, 1], [0, 1], lw=0.3)  # below most journal minimums
+        >>> results = check_line_weights(fig, spec)
+        >>> results[0].is_failure
+        True
+
+    Notes
+    -----
+        - Line labels are read from
+          :meth:`~matplotlib.lines.Line2D.get_label`.  Auto-generated legend
+          labels (``"_line0"``, ``"_collection0"``, etc.) start with
+          ``"_"``, but the check reports them as ``"(unlabeled)"`` only when
+          the label is empty or ``None`` — the underscore-prefixed auto-labels
+          are included as-is so the user can identify the artist.
+        - The tolerance applied to width comparisons is strict (``<`` rather
+          than ``<=``) so that a line *exactly* at the minimum passes.
+    """
+    min_linewidth: float = spec.line.min_weight_pt
+    violations: list[str] = []
+
+    for ax in fig.get_axes():
+        # --- Plotted Line2D objects ---
+        for line in ax.get_lines():
+            lw = line.get_linewidth()
+            if lw < min_linewidth:
+                # Prefer the user-set label; fall back to a generic descriptor.
+                label = line.get_label() or "(unlabeled line)"
+                violations.append(f"{label!r}: {lw:.2f}pt")
+
+        # --- Axis spines (frame borders) ---
+        for spine_name, spine in ax.spines.items():
+            lw = spine.get_linewidth()
+            if lw < min_linewidth:
+                violations.append(f"spine '{spine_name}': {lw:.2f}pt")
+
+    if violations:
+        # Show only the first few violations to keep the message readable.
+        truncated = violations[:_MAX_VIOLATION_EXAMPLES]
+        suffix = (
+            f" … and {len(violations) - _MAX_VIOLATION_EXAMPLES} more."
+            if len(violations) > _MAX_VIOLATION_EXAMPLES
+            else ""
+        )
+        return [
+            CheckResult(
+                status=CheckStatus.FAIL,
+                check_name="lines.min_weight",
+                message=(
+                    f"{len(violations)} element(s) below the "
+                    f"{spec.metadata.name} minimum of {min_linewidth}pt: "
+                    f"{'; '.join(truncated)}{suffix}"
+                ),
+                fix_suggestion=(
+                    f"Set linewidth ≥ {min_linewidth}pt on all plotted lines. "
+                    "Apply globally with "
+                    f"mpl.rcParams['lines.linewidth'] = {min_linewidth}, or "
+                    "per-line with the lw= keyword argument."
+                ),
+            )
+        ]
+
+    return [
+        CheckResult(
+            status=CheckStatus.PASS,
+            check_name="lines.min_weight",
+            message=(
+                f"All plotted lines and spines meet the "
+                f"{spec.metadata.name} minimum line weight of {min_linewidth}pt."
+            ),
+        )
+    ]

plotstyle/validation/checks/typography.py

@@ -0,0 +1,200 @@
+"""Typography validation check — font size compliance.
+
+This module registers :func:`check_typography`, which verifies that every
+visible text element in a figure falls within the minimum and maximum font
+sizes specified by the target journal.
+
+Text elements inspected
+-----------------------
+- Figure-level text (``fig.texts`` — suptitle, annotations added directly to
+  the figure).
+- Axes titles (``ax.title``).
+- Axis labels (``ax.xaxis.label``, ``ax.yaxis.label``).
+- Tick labels (``ax.get_xticklabels()``, ``ax.get_yticklabels()``).
+- Legend text entries (from every legend attached to an axes).
+
+Empty and whitespace-only text artists are skipped because they contribute no
+visible content and should not be penalised for having a default font size that
+might fall outside the permitted range.
+
+Why font size matters
+---------------------
+Journals enforce minimum font sizes (typically 6-7 pt) to ensure legibility
+after reduction to column width during typesetting.  Maximum sizes prevent
+labels from dominating the figure area and clashing with the journal's body
+text.
+
+Example
+-------
+    >>> from plotstyle.validation.checks.typography import check_typography
+    >>> results = check_typography(fig, spec)
+    >>> results[0].check_name
+    'typography.font_size'
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from plotstyle.validation.checks._base import check
+from plotstyle.validation.report import CheckResult, CheckStatus
+
+if TYPE_CHECKING:
+    from matplotlib.figure import Figure
+    from matplotlib.text import Text
+
+    from plotstyle.specs.schema import JournalSpec
+
+# Maximum number of violation examples to include in the result message.
+_MAX_VIOLATION_EXAMPLES: int = 5
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _gather_text_artists(fig: Figure) -> list[Text]:
+    """Collect all relevant :class:`~matplotlib.text.Text` artists from *fig*.
+
+    Includes figure-level text and all per-axes text elements that carry
+    meaningful content labels: titles, axis labels, tick labels, and legend
+    entries.
+
+    Args:
+        fig: The figure to inspect.
+
+    Returns
+    -------
+        Flat list of :class:`~matplotlib.text.Text` instances in the order:
+        figure texts → (for each axes) title, x-label, y-label, x-tick
+        labels, y-tick labels, legend texts.
+
+    Notes
+    -----
+        - Axes with empty titles or labels are included; the caller
+          (:func:`check_typography`) is responsible for skipping
+          whitespace-only entries.
+        - The list may contain duplicates if an artist is somehow shared
+          across axes; in practice this does not occur in normal figure
+          construction.
+    """
+    texts: list[Text] = list(fig.texts)  # copy to avoid mutating fig.texts
+
+    for ax in fig.get_axes():
+        texts.append(ax.title)
+        texts.append(ax.xaxis.label)
+        texts.append(ax.yaxis.label)
+        texts.extend(ax.get_xticklabels())
+        texts.extend(ax.get_yticklabels())
+
+        legend = ax.get_legend()
+        if legend is not None:
+            texts.extend(legend.get_texts())
+
+    return texts
+
+
+# ---------------------------------------------------------------------------
+# Registered check
+# ---------------------------------------------------------------------------
+
+
+@check
+def check_typography(fig: Figure, spec: JournalSpec) -> list[CheckResult]:
+    """Validate all visible text elements against journal font size limits.
+
+    Gathers every :class:`~matplotlib.text.Text` artist in *fig* (via
+    :func:`_gather_text_artists`), skips empty/whitespace-only entries, and
+    checks whether each artist's font size is within
+    ``[spec.typography.min_font_pt, spec.typography.max_font_pt]``.
+
+    Args:
+        fig: The :class:`~matplotlib.figure.Figure` to inspect.  Should be
+            fully composed before calling (tick labels may not be finalised
+            until the figure is rendered or the layout engine has run).
+        spec: Journal specification providing ``typography.min_font_pt``,
+            ``typography.max_font_pt``, and ``metadata.name``.
+
+    Returns
+    -------
+        A list containing exactly one :class:`~plotstyle.validation.report.CheckResult`
+        with check name ``"typography.font_size"``.  Status is:
+
+        - ``PASS`` — all non-empty text elements are within the allowed range.
+        - ``FAIL`` — one or more text elements fall outside the range, with
+          up to :data:`_MAX_VIOLATION_EXAMPLES` specific violations reported.
+
+    Example:
+        >>> import matplotlib.pyplot as plt
+        >>> fig, ax = plt.subplots()
+        >>> ax.set_xlabel("Time (s)", fontsize=4)  # below most minimums
+        >>> results = check_typography(fig, spec)
+        >>> results[0].is_failure
+        True
+
+    Notes
+    -----
+        - Font size is read via :meth:`~matplotlib.text.Text.get_fontsize`,
+          which returns the *effective* size in points after resolving any
+          relative size strings (``"small"``, ``"large"``, etc.).
+        - Tick labels are computed from the axes' locator/formatter when the
+          figure is drawn; calling this check before ``fig.canvas.draw()`` may
+          return empty tick-label strings, causing them to be skipped.  For
+          accurate tick-label validation, call ``fig.canvas.draw()`` or use
+          ``constrained_layout=True`` before validation.
+    """
+    min_pt: float = spec.typography.min_font_pt
+    max_pt: float = spec.typography.max_font_pt
+
+    violations: list[str] = []
+
+    for text in _gather_text_artists(fig):
+        content = text.get_text()
+
+        # Skip artists that carry no visible content.
+        if not content or not content.strip():
+            continue
+
+        font_size: float = text.get_fontsize()
+
+        if font_size < min_pt:
+            violations.append(f"{content!r}: {font_size:.1f}pt (< {min_pt}pt min)")
+        elif font_size > max_pt:
+            violations.append(f"{content!r}: {font_size:.1f}pt (> {max_pt}pt max)")
+
+    if violations:
+        truncated = violations[:_MAX_VIOLATION_EXAMPLES]
+        suffix = (
+            f" … and {len(violations) - _MAX_VIOLATION_EXAMPLES} more."
+            if len(violations) > _MAX_VIOLATION_EXAMPLES
+            else ""
+        )
+        return [
+            CheckResult(
+                status=CheckStatus.FAIL,
+                check_name="typography.font_size",
+                message=(
+                    f"{len(violations)} text element(s) outside the "
+                    f"{spec.metadata.name} range of {min_pt}-{max_pt}pt: "
+                    f"{'; '.join(truncated)}{suffix}"
+                ),
+                fix_suggestion=(
+                    f"Set all font sizes to {min_pt}-{max_pt}pt for "
+                    f"{spec.metadata.name} compliance. Apply globally with "
+                    f"mpl.rcParams['font.size'] = {min_pt}, or per-element "
+                    "via the fontsize= keyword argument."
+                ),
+            )
+        ]
+
+    return [
+        CheckResult(
+            status=CheckStatus.PASS,
+            check_name="typography.font_size",
+            message=(
+                f"All text elements are within the "
+                f"{spec.metadata.name} range of {min_pt}-{max_pt}pt."
+            ),
+        )
+    ]