plotstyle 1.2.0__tar.gz → 1.2.2__tar.gz

plotstyle-1.2.2/CHANGELOG.md

@@ -0,0 +1,182 @@
+# Changelog
+
+All notable changes to **plotstyle** will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [PEP 440](https://peps.python.org/pep-0440/) versioning.
+
+---
+
+## [Unreleased]
+
+_Nothing yet._
+
+---
+
+## [1.2.2] - 2026-04-27
+
+Patch release: docs improvements, README example quality, and CI action bump.
+
+### Added
+
+- **`LatexNotFoundError` catch pattern in API docs** (`docs/api/style.md`): new "Catching LaTeX errors" section shows how to import and handle `LatexNotFoundError` directly, with a note on catching the base `RuntimeError` as an alternative.
+- **`examples/output/accessibility_deuteranopia.png`**: new reference output image generated by the `simulate_cvd` section of `04_accessibility_checks.py`.
+
+### Changed
+
+- **README overlay examples use realistic data**: notebook and okabe-ito overlay snippets now use `np.linspace` / `np.sin` / `np.cos` plots instead of trivial `[1, 2, 3]` lists; axes labels updated to match.
+- **README overlay snippet import cleanup**: removed stray `import matplotlib.pyplot as plt` from the minimal overlay example where it was unused.
+- **README validation report output updated**: sample terminal output now reflects a two-column figure width rather than a single-column one.
+- **README `diff` output adds `Avoid: none`**: accessibility block in the `plotstyle diff` sample output now shows the `Avoid` field.
+- **`download-artifact` action bumped to v8** in `.github/workflows/release.yml` (was v4).
+- **Version references bumped to 1.2.2** in `README.md` (citation note) and `docs/installation.md` (version-check snippet).
+
+### Fixed
+
+- **HiDPI/Retina crash in `_fig_to_rgb_array`** (`src/plotstyle/color/_rendering.py`): `get_width_height()` now passes `physical=True` so the returned pixel dimensions match the `buffer_rgba()` byte count on high-DPI displays, preventing a `ValueError` during the reshape.
+- **Same HiDPI fix in `simulate_cvd` example** (`examples/04_accessibility_checks.py`): the inline canvas-to-array snippet now uses `get_width_height(physical=True)` to stay consistent with the library fix above.
+- **Typo in `06_export_submission.py` docstring**: `"smit_"` author prefix corrected to `"smith_"`.
+
+---
+
+## [1.2.1] - 2026-04-26
+
+Patch release: `simulate_cvd` example, warning quality improvements, and docs/example content fixes.
+
+### Added
+
+- **`simulate_cvd` example in `04_accessibility_checks.py`**: demonstrates low-level CVD simulation by rendering a figure to an RGB array and applying a single `CVDType` matrix directly via `simulate_cvd()`.
+
+### Changed
+
+- **`SpecAssumptionWarning` deduplication**: each spec now emits the assumption warning at most once per session. A `_warned_specs` set on `SpecRegistry` tracks which specs have already warned; `reset()` clears it alongside the spec cache.
+- **Clearer `OverlaySizeWarning`**: the message now names the journal, the overlay, the actual width, the limit, and the fix action, replacing the previous vague description.
+- **Improved font-fallback warning**: lists font names in a readable comma-separated form and adds a hint to rebuild the Matplotlib font cache after installing a new font.
+- **FontTools log suppression during PDF export**: `savefig()` temporarily sets the `fontTools` logger to `ERROR` level during `fig.savefig()` to suppress low-level font subsetting noise.
+- **`SpecRegistry.get()` uses `_silent=True` during background style registration**: prevents the assumption warning from firing during the import-time `register_all_styles()` call.
+- **Docs and example content fixes**: factual errors corrected across API reference, guides, CLI docs, and Jupyter notebooks; overlay guide expanded with additional coverage.
+
+---
+
+## [1.2.0] - 2026-04-23
+
+Feature release: **overlays**, **units & conversions**, **Seaborn integration**, improved **font/LaTeX controls**, plus major CLI/docs/example expansion.
+
+### Added
+
+- **Style overlays** (`plotstyle.overlays`, `plotstyle.list_overlays()`): additive layers that can be composed with a base journal preset.
+  - Categories: `color`, `context`, `rendering`, `plot-type`, `script`.
+  - Built-in overlays include `minimal`, `notebook`, `presentation`, `high-vis`, `grid`, `bar`, `scatter`, `no-latex`, `pgf`, `latex-sans`, `okabe-ito`, `safe-grayscale`, and `tol-*` palette overlays, plus CJK/Turkish/Russian script overlays.
+- **New CLI commands for overlays**
+  - `plotstyle overlays [--category <category>]` to list overlays.
+  - `plotstyle overlay-info <overlay>` to inspect overlay metadata and `rcParams`.
+- **Font checks for overlays**: `plotstyle fonts --overlay <overlay>` (in addition to `--journal`).
+- **Seaborn integration**: helpers to keep PlotStyle `rcParams` consistent when using Seaborn themes (`patch_seaborn()`, `plotstyle_theme()`, `unpatch_seaborn()`).
+- **Units & conversions**: new/expanded utilities and docs for consistent size specification across specs and helpers.
+- **Matplotlib-native styles compatibility**: support for registering/using PlotStyle presets as Matplotlib styles where applicable.
+- **New examples & previews**: additional example scripts including overlays, Seaborn integration, units/conversions, print-size preview, Matplotlib native styles, and LaTeX/fonts.
+
+### Changed
+
+- **CLI UX improvements**
+  - `plotstyle fonts` now supports `--journal` *or* `--overlay` (mutually exclusive, required).
+  - More robust argument parsing (e.g. ignores empty entries in `--formats`).
+  - Friendlier output for empty registries (journals/overlays) and clearer reporting for overlay font availability.
+- **Docs & README expansion**: new/expanded guides and API reference for overlays, units, warnings, Seaborn, preview tooling, and updated patterns/examples.
+
+### Fixed
+
+- **CLI stability**: avoid noisy/unclear behavior in edge cases (empty registry listings, malformed format lists) and improve error messaging around missing overlay keys.
+
+---
+
+## [1.1.0] - 2026-04-16
+
+Minor feature release : ergonomics improvements, hardened error handling, and spec updates.
+
+### Added
+
+- **`quiet` parameter on `JournalStyle.export()`** : suppresses compliance summaries and manifest output for scripting workflows.
+- **Pre-computed Type 3 font checks** : compliance summary now accepts a pre-computed result for Type 3 font detection, improving performance when the check has already been run by the caller.
+- **`JournalSpec` key access** : `JournalSpec` now supports key-style access, and the dimension check message has been updated for clarity.
+
+### Fixed
+
+- **`SpecNotFoundError` base classes** : now inherits from both `ValueError` and `KeyError` so existing `except ValueError` and `except KeyError` handlers catch it correctly; a custom `__str__` produces clearer diagnostic messages.
+
+### Changed
+
+- **IEEE Transactions spec updated** : column widths, max height, font family, panel-label properties, and preferred output formats revised to match current IEEE author guidelines.
+- **CI documentation build** : Sphinx `docs` job (`sphinx-build -W -n`) added to the CI workflow; rendered HTML is uploaded as an artifact on every push.
+- **Module docstrings** : expanded and standardised across `__init__.py`, `_utils/`, `color/`, `core/`, and `validation/` for consistent Sphinx rendering.
+- **Context-manager examples** : all `plotstyle.use()` call sites in docs and examples updated to the `with plotstyle.use(...) as style:` form to ensure correct `rcParams` restoration.
+
+---
+
+## [1.0.0] - 2026-04-12
+
+First stable release: production-ready for scientific publication workflows.
+
+### Changed
+
+- **Stable release**: promoted from alpha (`0.1.0a2`) to stable (`1.0.0`); all public APIs are now considered stable and subject to semantic versioning guarantees.
+- **PyPI classifiers** updated to `Development Status :: 5 - Production/Stable`.
+- **Enhanced project metadata**: expanded keywords, classifiers, and project URLs in `pyproject.toml` for better PyPI discoverability.
+- **README improvements**: added more badges (downloads, docs status, code style), expanded feature descriptions, and added star-history / citation section.
+
+---
+
+## [0.1.0a2] - 2026-04-12
+
+Second alpha: full documentation suite, comprehensive test coverage, and hardened validation.
+
+### Added
+
+- **Full documentation suite**: Sphinx/MyST docs covering installation, quickstart, concepts, CLI reference, complete API reference for every public symbol, how-to guides (accessibility, export, migration, multi-panel, palettes, seaborn), FAQ, and a journal comparison index.
+- **ReadTheDocs integration**: `.readthedocs.yaml` added; docs build automatically on every push; Furo theme configured with custom CSS.
+- **Comprehensive test suite**: new test modules added: `test_style`, `test_palettes`, `test_accessibility`, `test_grayscale`, `test_rendering`, `test_gallery`, `test_print_size`, `test_cli`, `test_io`, `test_warnings`, `test_checks`, `test_report`; existing modules `test_figure`, `test_export`, `test_migrate`, `test_fonts`, and `test_registry` substantially expanded.
+- **Export DPI validation**: `validation/checks/export.py` now emits a hard `FAIL` (instead of a `WARN`) when `savefig.dpi` is a numeric value that is provably below the journal's minimum DPI requirement.
+- **Dependabot**: `.github/dependabot.yml` added for automated dependency-update pull requests.
+- **`_format_panel_label()` range guard**: raises `ValueError` for panel indices ≥ 702 (beyond the two-character `"zz"` label); valid range is now explicitly documented as 0–701.
+
+### Changed
+
+- CI workflow extended: a `docs` build job added to `.github/workflows/ci.yml` - runs `sphinx-build -W -n` on every push and uploads the rendered HTML as an artifact.
+- Module docstring quick-start example in `__init__.py` updated to use the context-manager form (`with plotstyle.use(...) as style:`) and `plotstyle.figure()` instead of `plotstyle.subplots()`.
+- Docstrings across `migrate.py`, `report.py`, `style.py`, `figure.py`, `export.py`, and `accessibility.py` converted to NumPy-style attribute sections for consistent Sphinx rendering.
+- `FORMAT_EXTENSIONS` constant in `export.py` annotated as a module-level Sphinx data comment (`#:`) so it appears correctly in the API docs.
+- `pyproject.toml` documentation extras updated: `furo` pinned to `>=2025.12.19` and `myst-parser` bumped to `>=5.0,<6`.
+
+---
+
+## [0.1.0a1] - 2026-04-07
+
+First public alpha release.
+
+### Added
+
+- **Core style engine**: `plotstyle.use()` applies journal presets to Matplotlib's `rcParams`; works as a context manager with automatic restoration on exit.
+- **Figure helpers**: `plotstyle.figure()` and `plotstyle.subplots()` create correctly-sized figures at the exact column width and max height specified by each journal.
+- **Auto panel labels**: multi-panel figures receive **(a)**, **(b)**, **(c)**, … labels placed according to the journal's style rules.
+- **Colorblind-safe palettes**: built-in Okabe–Ito, Tol Bright, Tol Vibrant, Tol Muted, and Safe Grayscale palettes (`plotstyle.palette()`).
+- **Accessibility previews**: `plotstyle.preview_colorblind()` simulates deuteranopia, protanopia, and tritanopia; `plotstyle.preview_grayscale()` previews grayscale rendering.
+- **Pre-submission validation**: `plotstyle.validate()` checks dimensions, typography, line weights, color accessibility, and export settings against a target journal spec.
+- **Submission-ready export**: `plotstyle.savefig()` saves with font embedding and DPI enforcement; `plotstyle.export_submission()` batch-exports to all formats a journal accepts.
+- **Spec diffing & migration**: `plotstyle.diff()` compares two journal specs; `plotstyle.migrate()` re-targets a figure from one journal to another.
+- **Seaborn integration**: `patch_seaborn()` / `plotstyle_theme()` ensure PlotStyle `rcParams` survive `sns.set_theme()` calls.
+- **Gallery & print-size preview**: `plotstyle.gallery()` generates sample figures; `plotstyle.preview_print_size()` opens an interactive scaled preview window.
+- **Journal spec registry**: programmatic access via `plotstyle.registry`; specs are TOML files validated by immutable, typed dataclasses.
+- **CLI**: `plotstyle list`, `plotstyle info`, `plotstyle diff`, `plotstyle fonts`, `plotstyle validate`, and `plotstyle export` sub-commands.
+- **10 journal presets**: ACS, Cell, Elsevier, IEEE, Nature, PLOS, PRL, Science, Springer, Wiley.
+- **10 working examples**: quick start, multi-panel, palettes, accessibility, validation, export, diff/migrate, gallery, registry, context manager patterns.
+- **Dynamic versioning**: version derived from git tags via `hatch-vcs` and `importlib.metadata`.
+- **CI/CD pipeline**: GitHub Actions workflows for lint, type-check, test matrix, and automated PyPI release via OIDC Trusted Publishing.
+
+[Unreleased]: https://github.com/rahulkaushal04/plotstyle/compare/v1.2.2...HEAD
+[1.2.2]: https://github.com/rahulkaushal04/plotstyle/compare/v1.2.1...v1.2.2
+[1.2.1]: https://github.com/rahulkaushal04/plotstyle/compare/v1.2.0...v1.2.1
+[1.2.0]: https://github.com/rahulkaushal04/plotstyle/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/rahulkaushal04/plotstyle/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/rahulkaushal04/plotstyle/compare/v0.1.0a2...v1.0.0
+[0.1.0a2]: https://github.com/rahulkaushal04/plotstyle/compare/v0.1.0a1...v0.1.0a2
+[0.1.0a1]: https://github.com/rahulkaushal04/plotstyle/releases/tag/v0.1.0a1

{plotstyle-1.2.0 → plotstyle-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plotstyle
-Version: 1.2.0
+Version: 1.2.2
 Summary: Matplotlib/seaborn style presets matching scientific journal requirements, with validation, export safety, and preview capabilities.
 Project-URL: Homepage, https://github.com/rahulkaushal04/plotstyle
 Project-URL: Documentation, https://plotstyle.readthedocs.io
@@ -244,21 +244,38 @@ fig.savefig("palette_comparison.png", dpi=150)
 Pass `with_markers=True` to get `(color, linestyle, marker)` tuples, useful for journals like IEEE that print in grayscale:
 
 ```python
-styled = plotstyle.palette("ieee", n=4, with_markers=True)
-for color, ls, marker in styled:
-    ax.plot(x, y, color=color, linestyle=ls, marker=marker)
+import numpy as np
+import plotstyle
+
+x = np.linspace(0, 2 * np.pi, 100)
+curves = [np.sin(x + i * 0.5) for i in range(4)]
+
+with plotstyle.use("ieee") as style:
+    fig, ax = style.figure(columns=1)
+    styled = plotstyle.palette("ieee", n=4, with_markers=True)
+    for i, (color, ls, marker) in enumerate(styled):
+        ax.plot(x, curves[i], color=color, linestyle=ls, marker=marker,
+                markevery=20, label=f"Series {i + 1}")
+    ax.set_xlabel("x")
+    ax.set_ylabel("y")
+    ax.legend()
+    style.savefig(fig, "ieee_markers.pdf")
 ```
 
 ```text
-# styled — one (color, linestyle, marker) tuple per series:
+# styled: one (color, linestyle, marker) tuple per series:
 [('#000000', '-', 'o'), ('#333333', '--', 's'), ('#666666', '-.', '^'), ('#999999', ':', 'D')]
 ```
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rahulkaushal04/plotstyle/main/examples/output/palette_styled_ieee.png" width="55%" alt="IEEE figure with per-series color, linestyle, and marker combinations">
+</p>
+
 ---
 
 ### Overlays
 
-Overlays are additive patches that layer on top of a journal preset. They let you adjust one aspect of a figure — the colour palette, the context, the chart type — without changing the base journal settings.
+Overlays are additive patches that layer on top of a journal preset. They let you adjust one aspect of a figure (the colour palette, the context, the chart type) without changing the base journal settings.
 
 Pass overlay names in the same list as the journal key:
 
@@ -268,21 +285,60 @@ import plotstyle
 # Strip top/right spines for a clean editorial look
 with plotstyle.use(["nature", "minimal"]) as style:
     fig, ax = style.figure(columns=1)
-    ax.plot([1, 2, 3])
-    style.savefig(fig, "figure.pdf")
+    ax.plot([1, 2, 3], label="data")
+    ax.set_xlabel("x")
+    ax.set_ylabel("y")
+    ax.legend()
+    style.savefig(fig, "minimal_figure.pdf")
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rahulkaushal04/plotstyle/main/examples/output/overlay_minimal.png" width="45%" alt="Nature figure with minimal overlay: no top/right spines">
+</p>
+
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+import plotstyle
+
+x = np.linspace(0, 2 * np.pi, 100)
 
 # Larger figure and fonts for Jupyter notebooks
 with plotstyle.use(["nature", "notebook"]) as style:
-    import matplotlib.pyplot as plt
     fig, ax = plt.subplots()   # plt.subplots() picks up the notebook figsize
-    ax.plot([1, 2, 3])
+    ax.plot(x, np.sin(x), label="sin(x)")
+    ax.plot(x, np.cos(x), label="cos(x)")
+    ax.set_xlabel("Phase (rad)")
+    ax.set_ylabel("Amplitude")
+    ax.legend()
+    style.savefig(fig, "notebook_figure.pdf")
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rahulkaushal04/plotstyle/main/examples/output/overlay_notebook.png" width="60%" alt="Nature figure with notebook overlay: larger fonts and figure size">
+</p>
+
+```python
+import numpy as np
+import plotstyle
+
+x = np.linspace(0, 2 * np.pi, 100)
 
 # Swap the colour cycle to a specific palette
 with plotstyle.use(["ieee", "okabe-ito"]) as style:
     fig, ax = style.figure(columns=1)
-    ax.plot([1, 2, 3])
+    for i in range(4):
+        ax.plot(x, np.sin(x + i * 0.5), label=f"Series {i + 1}")
+    ax.set_xlabel("x")
+    ax.set_ylabel("y")
+    ax.legend()
+    style.savefig(fig, "okabe_ito_figure.pdf")
 ```
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rahulkaushal04/plotstyle/main/examples/output/overlay_okabe_ito.png" width="55%" alt="IEEE figure with okabe-ito colorblind-safe palette">
+</p>
+
 | Category | Purpose | Examples |
 |----------|---------|---------|
 | `color` | Swap the colour cycle | `okabe-ito`, `tol-bright`, `safe-grayscale` |
@@ -353,28 +409,54 @@ with plotstyle.use("nature") as style:
 Validate a figure against the journal's requirements, then export in all required formats at once.
 
 ```python
+import numpy as np
+import matplotlib.pyplot as plt
+import plotstyle
+
+x = np.linspace(0, 2 * np.pi, 100)
+
+# Outside plotstyle.use() — some checks will fail
+fig, ax = plt.subplots()
+ax.plot(x, np.sin(x), label="sin(x)")
+ax.set_xlabel("Phase (rad)")
+ax.set_ylabel("Amplitude")
+ax.legend()
+
 report = plotstyle.validate(fig, journal="nature")
 print(report)          # formatted compliance table
-print(report.passed)   # True if everything is OK
+print(report.passed)   # False — rcParams not configured
 
 for failure in report.failures:
     print(failure.message)         # what failed
     print(failure.fix_suggestion)  # how to fix it
+plt.close(fig)
+
+# Inside plotstyle.use() — all checks pass
+with plotstyle.use("nature") as style:
+    fig, ax = style.figure(columns=1)
+    ax.plot(x, np.sin(x), label="sin(x)")
+    ax.set_xlabel("Phase (rad)")
+    ax.set_ylabel("Amplitude")
+    ax.legend()
+
+    report = plotstyle.validate(fig, journal="nature")
+    print(report)
+    print(report.passed)   # True
 ```
 
 ```text
 ┌──────────────────────────────────────────────────────┐
-│         PlotStyle Validation Report — Nature         │
+│         PlotStyle Validation Report: Nature          │
 ├──────────┬───────────────────────────────────────────┤
-│ ✓ PASS   │ Figure width 89.0mm matches single colu...│
-│ ✓ PASS   │ Figure height 55.0mm is within the Natu...│
+│ ✗ FAIL   │ Figure width 162.6mm does not match Nat...│
+│ ✓ PASS   │ Figure height 121.9mm is within the Nat...│
 │ ✗ FAIL   │ pdf.fonttype = 3; must be 42 for TrueTy...│
 │ ✗ FAIL   │ ps.fonttype = 3; must be 42 for TrueTyp...│
 │ ⚠ WARN   │ savefig.dpi = 'figure'; Nature requires...│
 │ ✓ PASS   │ All plotted lines and spines meet the N...│
-│ ✗ FAIL   │ 14 text element(s) outside the Nature r...│
+│ ✗ FAIL   │ 23 text element(s) outside the Nature r...│
 └──────────┴───────────────────────────────────────────┘
-3/7 checks passed, 1 warning(s), 3 failure(s)
+2/7 checks passed, 1 warning(s), 4 failure(s)
 
 passed: False
 
@@ -387,7 +469,7 @@ When called inside `plotstyle.use()`, all checks pass:
 
 ```text
 ┌──────────────────────────────────────────────────────┐
-│         PlotStyle Validation Report — Nature         │
+│         PlotStyle Validation Report: Nature          │
 ├──────────┬───────────────────────────────────────────┤
 │ ✓ PASS   │ Figure width 89.0mm matches single colu...│
 │ ✓ PASS   │ Figure height 55.0mm is within the Natu...│
@@ -403,14 +485,28 @@ passed: True
 ```
 
 ```python
-paths = plotstyle.export_submission(
-    fig,
-    "figure1",
-    journal="ieee",
-    author_surname="Smith",     # IEEE prepends the surname prefix to filenames
-    output_dir="submission/",
-)
-print(paths)
+import numpy as np
+import os
+import plotstyle
+
+os.makedirs("submission", exist_ok=True)
+
+with plotstyle.use("ieee") as style:
+    fig, ax = style.figure(columns=1)
+    x = np.linspace(0, 2 * np.pi, 100)
+    ax.plot(x, np.sin(x), label="sin(x)")
+    ax.set_xlabel("Phase (rad)")
+    ax.set_ylabel("Amplitude")
+    ax.legend()
+
+    paths = plotstyle.export_submission(
+        fig,
+        "figure1",
+        journal="ieee",
+        author_surname="Smith",     # IEEE prepends the surname prefix to filenames
+        output_dir="submission/",
+    )
+    print(paths)
 ```
 
 ```text
@@ -490,6 +586,7 @@ Export:
 Accessibility:
   Colorblind safe: Not required
   Grayscale safe:  Not required
+  Avoid:           none
 ```
 
 **`plotstyle diff nature science`**
@@ -498,7 +595,7 @@ Nature → Science
 ──────────────────────────────────────────────────
 Column Width (single):  89.0mm → 86.4mm
 Column Width (double):  183.0mm → 177.8mm
-Max Height:             247.0mm → —
+Max Height:             247.0mm → -
 Font Family:            Helvetica, Arial → Minion Pro, Benton Sans Condensed
 Min Font Size:          5.0pt → 7.5pt
 Max Font Size:          7.0pt → 10.0pt
@@ -583,7 +680,7 @@ If PlotStyle helps your research, a citation or star is appreciated:
   title   = {PlotStyle: Publication-ready scientific figure presets for Matplotlib},
   year    = {2026},
   url     = {https://github.com/rahulkaushal04/plotstyle},
-  note    = {Version 1.2.0},
+  note    = {Version 1.2.2},
 }
 ```