plotstyle 0.1.0a1__tar.gz → 0.1.0a2__tar.gz

{plotstyle-0.1.0a1 → plotstyle-0.1.0a2}/CHANGELOG.md

@@ -36,7 +36,5 @@ First public alpha release.
 - **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/v0.1.0a1...HEAD
 [0.1.0a1]: https://github.com/rahulkaushal04/plotstyle/releases/tag/v0.1.0a1

{plotstyle-0.1.0a1 → plotstyle-0.1.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plotstyle
-Version: 0.1.0a1
+Version: 0.1.0a2
 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
@@ -11,7 +11,7 @@ Author: Rahul Kaushal
 License: MIT
 License-File: LICENSE
 Keywords: figures,journal,matplotlib,plotting,publication,scientific,seaborn,style
-Classifier: Development Status :: 5 - Production/Stable
+Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
@@ -43,8 +43,8 @@ Requires-Dist: pytest-mpl<1,>=0.18; extra == 'dev'
 Requires-Dist: pytest<10,>=8.3; extra == 'dev'
 Requires-Dist: ruff<1,>=0.15; extra == 'dev'
 Provides-Extra: docs
-Requires-Dist: furo>=2025.9.19; extra == 'docs'
-Requires-Dist: myst-parser<5,>=4.0; extra == 'docs'
+Requires-Dist: furo>=2025.12.19; extra == 'docs'
+Requires-Dist: myst-parser<6,>=5.0; extra == 'docs'
 Requires-Dist: sphinx-autodoc-typehints<4,>=3.0; extra == 'docs'
 Requires-Dist: sphinx-copybutton<1,>=0.5; extra == 'docs'
 Requires-Dist: sphinx<10,>=9.0; extra == 'docs'
@@ -72,7 +72,9 @@ Description-Content-Type: text/markdown
 
 ---
 
-**PlotStyle** configures [Matplotlib](https://matplotlib.org/) (and optionally [Seaborn](https://seaborn.pydata.org/)) so your figures match the typographic, dimensional, and export requirements of major scientific journals — out of the box.
+**PlotStyle** configures [Matplotlib](https://matplotlib.org/) (and optionally [Seaborn](https://seaborn.pydata.org/)) so your figures match the exact typographic, dimensional, and export requirements of major academic journals — out of the box.
+
+Getting a figure accepted often means matching a journal's precise column width, font size range, line weight, DPI, and export format. PlotStyle encodes those requirements as TOML specs and applies them automatically, so you spend time on your science rather than your figure settings.
 
 > **Current release:** `v0.1.0a1` (alpha)
 
@@ -94,16 +96,16 @@ Description-Content-Type: text/markdown
 
 ## Features
 
-- **One-line journal presets** — `plotstyle.use("nature")` sets fonts, sizes, line widths, and export parameters via Matplotlib's `rcParams`.
-- **Correctly-sized figures** — `plotstyle.figure()` / `plotstyle.subplots()` create figures at the exact column width and max height specified by each journal.
-- **Auto panel labels** — multi-panel figures get **(a)**, **(b)**, **(c)**, … labels placed according to the journal's style rules.
-- **Colorblind-safe palettes** — built-in Okabe–Ito, Tol Bright/Vibrant/Muted, and grayscale-safe palettes with optional markers and linestyles.
+- **One-line journal presets** — `plotstyle.use("nature")` sets fonts, sizes, line widths, and export parameters in Matplotlib's `rcParams`. Wrap it in a `with` block and everything is restored automatically when the block exits.
+- **Correctly-sized figures** — `plotstyle.figure()` and `plotstyle.subplots()` create figures at the exact column width and maximum height specified by each journal.
+- **Auto panel labels** — multi-panel figures get **(a)**, **(b)**, **(c)**, … labels placed and styled according to each journal's conventions.
+- **Colorblind-safe palettes** — built-in Okabe–Ito, Tol Bright/Vibrant/Muted, and grayscale-safe palettes via `plotstyle.palette()`.
 - **Accessibility previews** — simulate deuteranopia, protanopia, and tritanopia; preview grayscale rendering.
-- **Pre-submission validation** — check figure dimensions, font sizes, line weights, color accessibility, and export settings against the target journal's spec.
-- **Submission-ready export** — batch-export to all formats a journal accepts (PDF, EPS, TIFF, …) with font embedding and DPI enforcement.
-- **Spec diffing & migration** — compare two journal specs side-by-side; migrate a figure from one journal to another.
-- **Seaborn compatibility** — a monkey-patch layer ensures PlotStyle's `rcParams` survive `sns.set_theme()` calls.
-- **Typed, schema-validated specs** — journal requirements are stored as TOML files validated by immutable dataclasses.
+- **Pre-submission validation** — check figure dimensions, font sizes, line weights, color accessibility, and export settings against the target journal's spec before you submit.
+- **Submission-ready export** — `plotstyle.savefig()` enforces TrueType font embedding and minimum DPI; `plotstyle.export_submission()` batch-exports to every format the journal requires.
+- **Spec diffing & migration** — compare two journal specs side-by-side; re-target a figure from one journal to another with `plotstyle.migrate()`.
+- **Seaborn compatibility** — a patch layer ensures PlotStyle's `rcParams` survive `sns.set_theme()` calls.
+- **Typed, schema-validated specs** — journal requirements are stored as TOML files validated by immutable typed dataclasses.
 - **CLI** — `plotstyle list`, `plotstyle info`, `plotstyle validate`, and more — no Python script needed.
 
 ---
@@ -129,13 +131,13 @@ Description-Content-Type: text/markdown
 
 ## Installation
 
-Requires **Python 3.10+**.
+Requires **Python 3.10+** and **Matplotlib ≥ 3.9**.
 
 ```bash
 pip install plotstyle
 ```
 
-### Extras
+### Optional extras
 
 ```bash
 # Colorblind / grayscale preview (needs Pillow)
@@ -167,7 +169,11 @@ pip install -e ".[dev]"
 import numpy as np
 import plotstyle
 
+# plotstyle.use() applies the journal's rcParams (fonts, sizes, line widths).
+# The `with` block ensures they are restored automatically when plotting is done.
 with plotstyle.use("nature"):
+    # Creates a figure at Nature's exact single-column width (89 mm).
+    # Use columns=2 for double-column (full text width).
     fig, ax = plotstyle.figure("nature", columns=1)
 
     x = np.linspace(0, 2 * np.pi, 200)
@@ -177,54 +183,124 @@ with plotstyle.use("nature"):
     ax.set_ylabel("Amplitude (a.u.)")
     ax.legend()
 
+    # Enforces Nature's minimum DPI (300) and embeds TrueType fonts.
     plotstyle.savefig(fig, "quickstart_nature.pdf", journal="nature")
 ```
 
-`plotstyle.use()` also works as a context manager — `rcParams` are automatically restored on exit:
+The `with` block is the recommended pattern — `rcParams` are always restored on exit, even if an exception occurs inside the block.
+
+If you need to manage the style manually:
 
 ```python
-with plotstyle.use("ieee"):
+style = plotstyle.use("ieee")
+try:
     fig, ax = plotstyle.figure("ieee", columns=1)
     ax.plot([1, 2, 3])
     plotstyle.savefig(fig, "fig_ieee.eps", journal="ieee")
-# rcParams are back to normal here
+finally:
+    style.restore()  # always restore, even on error
 ```
 
 ---
 
 ## Usage
 
-**Multi-panel figures** with auto labels:
+### Multi-panel figures
+
+`plotstyle.subplots()` works like `plt.subplots()` but sizes the figure to the journal spec and adds panel labels automatically.
+
+> **Note:** Unlike `plt.subplots()`, `plotstyle.subplots()` **always** returns a 2-D NumPy array of axes — even for a single panel. Use `axes[0, 0]` to access a single axes, or `axes.flat` to iterate over all panels.
 
 ```python
-fig, axes = plotstyle.subplots("science", nrows=2, ncols=2, columns=2)
-# Axes get (a), (b), (c), (d) labels per journal style
+import plotstyle
+
+with plotstyle.use("science"):
+    fig, axes = plotstyle.subplots("science", nrows=2, ncols=2, columns=2)
+    # axes has shape (2, 2); each panel is labelled (a), (b), (c), (d)
+    for ax in axes.flat:
+        ax.plot([1, 2, 3])
+    plotstyle.savefig(fig, "multipanel.pdf", journal="science")
 ```
 
-**Colorblind-safe palettes** (Okabe–Ito, Tol Bright/Vibrant/Muted, Safe Grayscale):
+Pass `panels=False` to suppress the automatic labels.
+
+### Color palettes
 
 ```python
+# A list of 4 hex color strings from Nature's recommended palette
 colors = plotstyle.palette("nature", n=4)
-styled = plotstyle.palette("ieee", n=3, with_markers=True)  # [(color, linestyle, marker), ...]
+
+# With linestyles and markers — useful for accessible line plots
+styled = plotstyle.palette("ieee", n=3, with_markers=True)
+# styled is a list of (color, linestyle, marker) tuples
+for color, ls, marker in styled:
+    ax.plot(x, y, color=color, linestyle=ls, marker=marker)
 ```
 
-**Validation** — check dimensions, fonts, line weights, colors, and export settings:
+### Validation
 
 ```python
 report = plotstyle.validate(fig, journal="nature")
-print(report.passed)    # True / False
-print(report.failures)  # with fix suggestions
+print(report)           # formatted table of all checks
+print(report.passed)    # True if no checks failed
+
+for failure in report.failures:
+    print(failure.message)          # what failed
+    print(failure.fix_suggestion)   # how to fix it
 ```
 
-**Submission export** — batch-export to all formats a journal accepts:
+### Submission export
+
+`export_submission()` writes the figure in every format the journal requires (PDF, TIFF, EPS, etc.) and applies journal-specific naming conventions.
 
 ```python
-plotstyle.export_submission(fig, "figure1", journal="ieee",
-                            author_surname="Kaushal",
-                            output_dir="submission_ieee")
+paths = plotstyle.export_submission(
+    fig,
+    "figure1",
+    journal="ieee",
+    author_surname="Kaushal",   # IEEE prepends the first 5 chars of the surname
+    output_dir="submission_ieee",
+)
+# Produces: submission_ieee/kaush_figure1.pdf (and any other IEEE-required formats)
 ```
 
-**Accessibility previews**, **spec diffing & migration**, and **Seaborn integration** are also available — see the [`examples/`](examples/) directory for full usage.
+### Spec diffing and migration
+
+```python
+# Compare two journals — useful when retargeting a figure
+result = plotstyle.diff("nature", "science")
+print(result)           # aligned two-column table of differences
+
+# Re-target a figure to a different journal in place
+plotstyle.migrate(fig, from_journal="nature", to_journal="science")
+plotstyle.savefig(fig, "figure_science.pdf", journal="science")
+```
+
+### Accessibility previews
+
+```python
+# Simulate how a figure looks under three types of color blindness
+comp = plotstyle.preview_colorblind(fig)
+comp.savefig("colorblind_check.png", dpi=150)
+
+# Preview grayscale rendering
+gs = plotstyle.preview_grayscale(fig)
+gs.savefig("grayscale_check.png", dpi=150)
+```
+
+### Seaborn integration
+
+`sns.set_theme()` normally overwrites the rcParams that PlotStyle set. Pass `seaborn_compatible=True` to prevent that:
+
+```python
+import seaborn as sns
+import plotstyle
+
+with plotstyle.use("nature", seaborn_compatible=True):
+    fig, ax = plotstyle.figure("nature", columns=1)
+    sns.lineplot(x=[1, 2, 3], y=[4, 5, 6], ax=ax)
+    plotstyle.savefig(fig, "seaborn_figure.pdf", journal="nature")
+```
 
 ---
 

{plotstyle-0.1.0a1 → plotstyle-0.1.0a2}/README.md

@@ -15,7 +15,9 @@
 
 ---
 
-**PlotStyle** configures [Matplotlib](https://matplotlib.org/) (and optionally [Seaborn](https://seaborn.pydata.org/)) so your figures match the typographic, dimensional, and export requirements of major scientific journals — out of the box.
+**PlotStyle** configures [Matplotlib](https://matplotlib.org/) (and optionally [Seaborn](https://seaborn.pydata.org/)) so your figures match the exact typographic, dimensional, and export requirements of major academic journals — out of the box.
+
+Getting a figure accepted often means matching a journal's precise column width, font size range, line weight, DPI, and export format. PlotStyle encodes those requirements as TOML specs and applies them automatically, so you spend time on your science rather than your figure settings.
 
 > **Current release:** `v0.1.0a1` (alpha)
 
@@ -37,16 +39,16 @@
 
 ## Features
 
-- **One-line journal presets** — `plotstyle.use("nature")` sets fonts, sizes, line widths, and export parameters via Matplotlib's `rcParams`.
-- **Correctly-sized figures** — `plotstyle.figure()` / `plotstyle.subplots()` create figures at the exact column width and max height specified by each journal.
-- **Auto panel labels** — multi-panel figures get **(a)**, **(b)**, **(c)**, … labels placed according to the journal's style rules.
-- **Colorblind-safe palettes** — built-in Okabe–Ito, Tol Bright/Vibrant/Muted, and grayscale-safe palettes with optional markers and linestyles.
+- **One-line journal presets** — `plotstyle.use("nature")` sets fonts, sizes, line widths, and export parameters in Matplotlib's `rcParams`. Wrap it in a `with` block and everything is restored automatically when the block exits.
+- **Correctly-sized figures** — `plotstyle.figure()` and `plotstyle.subplots()` create figures at the exact column width and maximum height specified by each journal.
+- **Auto panel labels** — multi-panel figures get **(a)**, **(b)**, **(c)**, … labels placed and styled according to each journal's conventions.
+- **Colorblind-safe palettes** — built-in Okabe–Ito, Tol Bright/Vibrant/Muted, and grayscale-safe palettes via `plotstyle.palette()`.
 - **Accessibility previews** — simulate deuteranopia, protanopia, and tritanopia; preview grayscale rendering.
-- **Pre-submission validation** — check figure dimensions, font sizes, line weights, color accessibility, and export settings against the target journal's spec.
-- **Submission-ready export** — batch-export to all formats a journal accepts (PDF, EPS, TIFF, …) with font embedding and DPI enforcement.
-- **Spec diffing & migration** — compare two journal specs side-by-side; migrate a figure from one journal to another.
-- **Seaborn compatibility** — a monkey-patch layer ensures PlotStyle's `rcParams` survive `sns.set_theme()` calls.
-- **Typed, schema-validated specs** — journal requirements are stored as TOML files validated by immutable dataclasses.
+- **Pre-submission validation** — check figure dimensions, font sizes, line weights, color accessibility, and export settings against the target journal's spec before you submit.
+- **Submission-ready export** — `plotstyle.savefig()` enforces TrueType font embedding and minimum DPI; `plotstyle.export_submission()` batch-exports to every format the journal requires.
+- **Spec diffing & migration** — compare two journal specs side-by-side; re-target a figure from one journal to another with `plotstyle.migrate()`.
+- **Seaborn compatibility** — a patch layer ensures PlotStyle's `rcParams` survive `sns.set_theme()` calls.
+- **Typed, schema-validated specs** — journal requirements are stored as TOML files validated by immutable typed dataclasses.
 - **CLI** — `plotstyle list`, `plotstyle info`, `plotstyle validate`, and more — no Python script needed.
 
 ---
@@ -72,13 +74,13 @@
 
 ## Installation
 
-Requires **Python 3.10+**.
+Requires **Python 3.10+** and **Matplotlib ≥ 3.9**.
 
 ```bash
 pip install plotstyle
 ```
 
-### Extras
+### Optional extras
 
 ```bash
 # Colorblind / grayscale preview (needs Pillow)
@@ -110,7 +112,11 @@ pip install -e ".[dev]"
 import numpy as np
 import plotstyle
 
+# plotstyle.use() applies the journal's rcParams (fonts, sizes, line widths).
+# The `with` block ensures they are restored automatically when plotting is done.
 with plotstyle.use("nature"):
+    # Creates a figure at Nature's exact single-column width (89 mm).
+    # Use columns=2 for double-column (full text width).
     fig, ax = plotstyle.figure("nature", columns=1)
 
     x = np.linspace(0, 2 * np.pi, 200)
@@ -120,54 +126,124 @@ with plotstyle.use("nature"):
     ax.set_ylabel("Amplitude (a.u.)")
     ax.legend()
 
+    # Enforces Nature's minimum DPI (300) and embeds TrueType fonts.
     plotstyle.savefig(fig, "quickstart_nature.pdf", journal="nature")
 ```
 
-`plotstyle.use()` also works as a context manager — `rcParams` are automatically restored on exit:
+The `with` block is the recommended pattern — `rcParams` are always restored on exit, even if an exception occurs inside the block.
+
+If you need to manage the style manually:
 
 ```python
-with plotstyle.use("ieee"):
+style = plotstyle.use("ieee")
+try:
     fig, ax = plotstyle.figure("ieee", columns=1)
     ax.plot([1, 2, 3])
     plotstyle.savefig(fig, "fig_ieee.eps", journal="ieee")
-# rcParams are back to normal here
+finally:
+    style.restore()  # always restore, even on error
 ```
 
 ---
 
 ## Usage
 
-**Multi-panel figures** with auto labels:
+### Multi-panel figures
+
+`plotstyle.subplots()` works like `plt.subplots()` but sizes the figure to the journal spec and adds panel labels automatically.
+
+> **Note:** Unlike `plt.subplots()`, `plotstyle.subplots()` **always** returns a 2-D NumPy array of axes — even for a single panel. Use `axes[0, 0]` to access a single axes, or `axes.flat` to iterate over all panels.
 
 ```python
-fig, axes = plotstyle.subplots("science", nrows=2, ncols=2, columns=2)
-# Axes get (a), (b), (c), (d) labels per journal style
+import plotstyle
+
+with plotstyle.use("science"):
+    fig, axes = plotstyle.subplots("science", nrows=2, ncols=2, columns=2)
+    # axes has shape (2, 2); each panel is labelled (a), (b), (c), (d)
+    for ax in axes.flat:
+        ax.plot([1, 2, 3])
+    plotstyle.savefig(fig, "multipanel.pdf", journal="science")
 ```
 
-**Colorblind-safe palettes** (Okabe–Ito, Tol Bright/Vibrant/Muted, Safe Grayscale):
+Pass `panels=False` to suppress the automatic labels.
+
+### Color palettes
 
 ```python
+# A list of 4 hex color strings from Nature's recommended palette
 colors = plotstyle.palette("nature", n=4)
-styled = plotstyle.palette("ieee", n=3, with_markers=True)  # [(color, linestyle, marker), ...]
+
+# With linestyles and markers — useful for accessible line plots
+styled = plotstyle.palette("ieee", n=3, with_markers=True)
+# styled is a list of (color, linestyle, marker) tuples
+for color, ls, marker in styled:
+    ax.plot(x, y, color=color, linestyle=ls, marker=marker)
 ```
 
-**Validation** — check dimensions, fonts, line weights, colors, and export settings:
+### Validation
 
 ```python
 report = plotstyle.validate(fig, journal="nature")
-print(report.passed)    # True / False
-print(report.failures)  # with fix suggestions
+print(report)           # formatted table of all checks
+print(report.passed)    # True if no checks failed
+
+for failure in report.failures:
+    print(failure.message)          # what failed
+    print(failure.fix_suggestion)   # how to fix it
 ```
 
-**Submission export** — batch-export to all formats a journal accepts:
+### Submission export
+
+`export_submission()` writes the figure in every format the journal requires (PDF, TIFF, EPS, etc.) and applies journal-specific naming conventions.
 
 ```python
-plotstyle.export_submission(fig, "figure1", journal="ieee",
-                            author_surname="Kaushal",
-                            output_dir="submission_ieee")
+paths = plotstyle.export_submission(
+    fig,
+    "figure1",
+    journal="ieee",
+    author_surname="Kaushal",   # IEEE prepends the first 5 chars of the surname
+    output_dir="submission_ieee",
+)
+# Produces: submission_ieee/kaush_figure1.pdf (and any other IEEE-required formats)
 ```
 
-**Accessibility previews**, **spec diffing & migration**, and **Seaborn integration** are also available — see the [`examples/`](examples/) directory for full usage.
+### Spec diffing and migration
+
+```python
+# Compare two journals — useful when retargeting a figure
+result = plotstyle.diff("nature", "science")
+print(result)           # aligned two-column table of differences
+
+# Re-target a figure to a different journal in place
+plotstyle.migrate(fig, from_journal="nature", to_journal="science")
+plotstyle.savefig(fig, "figure_science.pdf", journal="science")
+```
+
+### Accessibility previews
+
+```python
+# Simulate how a figure looks under three types of color blindness
+comp = plotstyle.preview_colorblind(fig)
+comp.savefig("colorblind_check.png", dpi=150)
+
+# Preview grayscale rendering
+gs = plotstyle.preview_grayscale(fig)
+gs.savefig("grayscale_check.png", dpi=150)
+```
+
+### Seaborn integration
+
+`sns.set_theme()` normally overwrites the rcParams that PlotStyle set. Pass `seaborn_compatible=True` to prevent that:
+
+```python
+import seaborn as sns
+import plotstyle
+
+with plotstyle.use("nature", seaborn_compatible=True):
+    fig, ax = plotstyle.figure("nature", columns=1)
+    sns.lineplot(x=[1, 2, 3], y=[4, 5, 6], ax=ax)
+    plotstyle.savefig(fig, "seaborn_figure.pdf", journal="nature")
+```
 
 ---
 

{plotstyle-0.1.0a1 → plotstyle-0.1.0a2}/pyproject.toml

@@ -33,7 +33,7 @@ keywords = [
     "style",
 ]
 classifiers = [
-    "Development Status :: 5 - Production/Stable",
+    "Development Status :: 3 - Alpha",
     "Intended Audience :: Science/Research",
     "License :: OSI Approved :: MIT License",
     "Natural Language :: English",
@@ -90,8 +90,8 @@ dev = [
 # ── Documentation build ───────────────────────────────────────────────────────
 docs = [
     "sphinx>=9.0,<10",
-    "furo>=2025.9.19",
-    "myst-parser>=4.0,<5",
+    "furo>=2025.12.19",
+    "myst-parser>=5.0,<6",
     "sphinx-autodoc-typehints>=3.0,<4",
     "sphinx-copybutton>=0.5,<1",
 ]

{plotstyle-0.1.0a1 → plotstyle-0.1.0a2}/src/plotstyle/__init__.py

@@ -8,20 +8,19 @@ validation, and submission-ready export.
 
 Quick start
 -----------
-    >>> import matplotlib.pyplot as plt
     >>> import plotstyle
     >>>
-    >>> plotstyle.use("nature")
-    >>>
-    >>> fig, ax = plotstyle.subplots(columns=1)
-    >>> ax.plot([0, 1, 2], [0.2, 0.8, 0.4], color=plotstyle.palette("nature")[0])
-    >>> ax.set_xlabel("Time (s)")
-    >>> ax.set_ylabel("Signal (a.u.)")
-    >>>
-    >>> report = plotstyle.validate(fig, journal="nature")
-    >>> print(report)
-    >>>
-    >>> plotstyle.savefig(fig, "figure1.pdf")
+    >>> with plotstyle.use("nature") as style:
+    ...     fig, ax = plotstyle.figure("nature", columns=1)
+    ...     ax.plot([0, 1, 2], [0.2, 0.8, 0.4], color=plotstyle.palette("nature")[0])
+    ...     ax.set_xlabel("Time (s)")
+    ...     ax.set_ylabel("Signal (a.u.)")
+    ...
+    ...     report = plotstyle.validate(fig, journal="nature")
+    ...     print(report)
+    ...
+    ...     plotstyle.savefig(fig, "figure1.pdf", journal="nature")
+    ... # rcParams are restored automatically on exit
 
 Package layout
 --------------

{plotstyle-0.1.0a1 → plotstyle-0.1.0a2}/src/plotstyle/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.0a1'
-__version_tuple__ = version_tuple = (0, 1, 0, 'a1')
+__version__ = version = '0.1.0a2'
+__version_tuple__ = version_tuple = (0, 1, 0, 'a2')
 
 __commit_id__ = commit_id = None

{plotstyle-0.1.0a1 → plotstyle-0.1.0a2}/src/plotstyle/color/accessibility.py

@@ -143,8 +143,9 @@ def simulate_cvd(
 
     Raises
     ------
-        CVDSimulationError: If *image* does not have exactly three channels
-            (last dimension != 3) or if its number of dimensions is not 3.
+        plotstyle.color.accessibility.CVDSimulationError: If *image* does not
+            have exactly three channels (last dimension != 3) or if its number
+            of dimensions is not 3.
 
     Example:
         >>> import numpy as np
@@ -224,8 +225,9 @@ def preview_colorblind(
 
     Raises
     ------
-        CVDSimulationError: Propagated from :func:`simulate_cvd` if the
-            rasterised image has an unexpected shape.
+        plotstyle.color.accessibility.CVDSimulationError: Propagated from
+            :func:`simulate_cvd` if the rasterised image has an unexpected
+            shape.
         AttributeError: If *fig*'s canvas does not support ``buffer_rgba``
             (non-Agg backends).
 

{plotstyle-0.1.0a1 → plotstyle-0.1.0a2}/src/plotstyle/color/grayscale.py

@@ -79,7 +79,8 @@ def rgb_to_luminance(r: float, g: float, b: float) -> float:
     -------
         Relative luminance in ``[0, 1]``.
 
-    Example:
+    Examples
+    --------
         >>> rgb_to_luminance(1.0, 0.0, 0.0)  # pure red
         0.2126
         >>> rgb_to_luminance(1.0, 1.0, 1.0)  # white

{plotstyle-0.1.0a1 → plotstyle-0.1.0a2}/src/plotstyle/color/palettes.py

@@ -49,9 +49,9 @@ from pathlib import Path
 
 _DATA_DIR: Path = Path(__file__).parent / "data"
 
-# Maps lowercase journal identifiers to the palette name whose JSON file lives
-# in _DATA_DIR.  New journals can be added here without touching any other
-# logic in this module.
+#: Maps lowercase journal identifiers to the palette name whose JSON file
+#: lives in ``_DATA_DIR``.  New journals can be added here without touching
+#: any other logic in this module.
 JOURNAL_PALETTE_MAP: dict[str, str] = {
     "acs": "tol_bright",
     "cell": "okabe_ito",
@@ -200,9 +200,9 @@ def palette(
 
     Returns
     -------
-        A :data:`ColorList` (``list[str]``) of hex colour strings when
-        *with_markers* is ``False``, or a :data:`StyledColorList`
-        (``list[tuple[str, str, str]]``) of ``(colour, linestyle, marker)``
+        A ``list[str]`` of hex colour strings when
+        *with_markers* is ``False``, or a ``list[tuple[str, str, str]]``
+        of ``(colour, linestyle, marker)``
         tuples when *with_markers* is ``True``.
 
     Raises

{plotstyle-0.1.0a1 → plotstyle-0.1.0a2}/src/plotstyle/core/export.py

@@ -48,10 +48,8 @@ __all__: list[str] = [
 # Module-level constants
 # ---------------------------------------------------------------------------
 
-# Maps canonical format names to their standard file extensions.  Kept as a
-# module-level constant so callers can introspect supported formats without
-# instantiating any objects.  The dict is typed Final to signal that it must
-# not be mutated at runtime.
+#: Maps canonical format names to their standard file extensions.
+#: The dict is typed ``Final`` to signal that it must not be mutated at runtime.
 FORMAT_EXTENSIONS: Final[dict[str, str]] = {
     "pdf": ".pdf",
     "eps": ".eps",
@@ -237,7 +235,7 @@ def savefig(
         path: Output file path.  The file extension determines the format
             unless *format* is also supplied via *kwargs*.
         journal: Optional journal preset name registered with
-            :mod:`plotstyle.specs`.  When given, the journal's ``min_dpi``
+            the spec registry.  When given, the journal's ``min_dpi``
             overrides ``savefig.dpi`` for this call.
         **kwargs: Additional keyword arguments forwarded verbatim to
             :meth:`~matplotlib.figure.Figure.savefig`.  ``bbox_inches``
@@ -335,7 +333,7 @@ def export_submission(
         formats: Explicit list of output format keys (e.g. ``["pdf", "tiff"]``).
             Overrides the journal spec's preferred formats when supplied.
         journal: Optional journal preset name registered with
-            :mod:`plotstyle.specs`.  Used to resolve default formats, apply
+            the spec registry.  Used to resolve default formats, apply
             DPI constraints, and select naming conventions.
         output_dir: Directory into which all output files are written.
             Created (including any missing parents) if it does not exist.

{plotstyle-0.1.0a1 → plotstyle-0.1.0a2}/src/plotstyle/core/figure.py

@@ -146,13 +146,18 @@ def _format_panel_label(index: int, spec: JournalSpec) -> str:
     Args:
         index: Zero-based panel index.  Index ``0`` maps to the letter
             ``"a"`` (or its styled equivalent), index ``1`` to ``"b"``,
-            and so on.
+            and so on.  Valid range is ``0`` to ``701`` inclusive.
         spec: Journal specification containing panel label formatting rules.
 
     Returns
     -------
         Formatted panel label string (e.g. ``"a"``, ``"(B)"``, ``"A"``).
 
+    Raises
+    ------
+        ValueError: If *index* is >= 702 (beyond the two-character ``"zz"``
+            label).
+
     Notes
     -----
         Supported ``panel_label_case`` values and their output:
@@ -171,13 +176,16 @@ def _format_panel_label(index: int, spec: JournalSpec) -> str:
         Any unrecognised value falls back to ``"lower"``.
     """
     # Derive the base lowercase letter(s) from the zero-based index.
-    # Indices 0-25 map to a-z; indices 26+ produce two-character labels
-    # (aa, ab, ..., az, ba, ...) to support figures with more than 26 panels.
+    # Indices 0-25 map to a-z; indices 26-701 produce two-character labels
+    # (aa, ab, ..., zz).  Index 702+ would overflow beyond 'z' in the first
+    # character, so we reject it explicitly.
     if index < 26:
         letter: str = chr(ord("a") + index)
-    else:
+    elif index < 702:
         i = index - 26
         letter = chr(ord("a") + i // 26) + chr(ord("a") + i % 26)
+    else:
+        raise ValueError(f"Panel index {index} exceeds the maximum supported label range (0-701).")
     case: str = spec.typography.panel_label_case
 
     match case: