plotstyle 0.1.0a2__tar.gz → 1.1.0__tar.gz

{plotstyle-0.1.0a2 → plotstyle-1.1.0}/.gitignore

@@ -157,3 +157,6 @@ celerybeat-schedule
 
 # secrets (just in case)
 secrets.json
+
+# local files
+local/

plotstyle-1.1.0/CHANGELOG.md

@@ -0,0 +1,102 @@
+# 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.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.1.0...HEAD
+[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.1.0/PKG-INFO

@@ -0,0 +1,367 @@
+Metadata-Version: 2.4
+Name: plotstyle
+Version: 1.1.0
+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
+Project-URL: Repository, https://github.com/rahulkaushal04/plotstyle
+Project-URL: Issues, https://github.com/rahulkaushal04/plotstyle/issues
+Project-URL: Changelog, https://github.com/rahulkaushal04/plotstyle/blob/main/CHANGELOG.md
+Project-URL: Download, https://pypi.org/project/plotstyle/
+Author: Rahul Kaushal
+License: MIT
+License-File: LICENSE
+Keywords: academic,accessibility,colorblind,export,figures,ieee,journal,matplotlib,nature,plotting,publication,rcParams,research,science,scientific,seaborn,style,typesetting,validation,visualization
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Matplotlib
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: matplotlib<4,>=3.9
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: all
+Requires-Dist: fonttools<5,>=4.55; extra == 'all'
+Requires-Dist: pandas<3,>=2.2; extra == 'all'
+Requires-Dist: pillow<13,>=11.0; extra == 'all'
+Requires-Dist: seaborn<1,>=0.13.2; extra == 'all'
+Provides-Extra: color
+Requires-Dist: pillow<13,>=11.0; extra == 'color'
+Provides-Extra: dev
+Requires-Dist: mypy<2,>=1.15; extra == 'dev'
+Requires-Dist: pillow<13,>=11.0; extra == 'dev'
+Requires-Dist: pre-commit<5,>=4.0; extra == 'dev'
+Requires-Dist: pytest-cov<8,>=6.0; extra == 'dev'
+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.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'
+Provides-Extra: fonttools
+Requires-Dist: fonttools<5,>=4.55; extra == 'fonttools'
+Provides-Extra: seaborn
+Requires-Dist: pandas<3,>=2.2; extra == 'seaborn'
+Requires-Dist: seaborn<1,>=0.13.2; extra == 'seaborn'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <strong>plotstyle</strong>
+</p>
+
+<p align="center">
+  <em>Matplotlib figures formatted for journal submission, automatically.</em>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/plotstyle/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/plotstyle?color=blue"></a>
+  <a href="https://pypi.org/project/plotstyle/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/plotstyle"></a>
+  <a href="https://github.com/rahulkaushal04/plotstyle/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/github/license/rahulkaushal04/plotstyle"></a>
+  <a href="https://github.com/rahulkaushal04/plotstyle/actions"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/rahulkaushal04/plotstyle/ci.yml?label=CI"></a>
+  <a href="https://plotstyle.readthedocs.io/en/stable/"><img alt="Docs" src="https://img.shields.io/readthedocs/plotstyle/stable?label=docs"></a>
+</p>
+
+---
+
+**PlotStyle** makes it easy to produce Matplotlib figures that meet the exact typographic, dimensional, and export requirements of major academic journals. It also integrates with Seaborn, with more integrations planned. Pick a journal, create your figure, save it. PlotStyle handles the rest.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Examples](#examples)
+  - [Multi-panel figures](#multi-panel-figures)
+  - [Color palettes](#color-palettes)
+  - [Colorblind and grayscale previews](#colorblind-and-grayscale-previews)
+  - [Validation and submission export](#validation-and-submission-export)
+- [Supported Journals](#supported-journals)
+- [CLI](#cli)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [Citation](#citation)
+- [License](#license)
+
+---
+
+## Installation
+
+Requires **Python 3.10+** and **Matplotlib >= 3.9**.
+
+```bash
+pip install plotstyle
+```
+
+Optional extras:
+
+```bash
+pip install "plotstyle[color]"     # colorblind / grayscale previews
+pip install "plotstyle[seaborn]"   # seaborn integration
+pip install "plotstyle[all]"       # everything
+```
+
+---
+
+## Quick Start
+
+```python
+import numpy as np
+import plotstyle
+
+with plotstyle.use("nature") as style:
+    fig, ax = style.figure(columns=1)   # sized to Nature's single-column width (89 mm)
+
+    x = np.linspace(0, 2 * np.pi, 200)
+    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 (a.u.)")
+    ax.legend()
+
+    style.savefig(fig, "figure.pdf")    # 300 DPI minimum, TrueType fonts embedded
+```
+
+<p align="center">
+  <img src="examples/output/quickstart_nature.png" width="55%" alt="Quickstart output: sin and cos figure styled for Nature">
+</p>
+
+The `with` block is the recommended pattern. Matplotlib's `rcParams` are restored automatically when it exits, even if an exception occurs.
+
+---
+
+## Examples
+
+### Multi-panel figures
+
+`style.subplots()` works like `plt.subplots()` but sizes the figure to the journal spec and adds panel labels automatically, styled to each journal's convention (**A**, **B**, **C** for Science; **a**, **b**, **c** for Nature; **(a)**, **(b)**, **(c)** for IEEE).
+
+```python
+import numpy as np
+import plotstyle
+
+rng = np.random.default_rng(42)
+
+with plotstyle.use("science") as style:
+    fig, axes = style.subplots(nrows=2, ncols=2, columns=2)
+
+    x = np.linspace(0, 10, 100)
+    axes[0, 0].plot(x, np.sin(x), label="sin")
+    axes[0, 0].plot(x, np.cos(x), label="cos")
+    axes[0, 0].set_xlabel("x")
+    axes[0, 0].set_ylabel("f(x)")
+    axes[0, 0].legend()
+
+    xs = rng.normal(0, 1, 60)
+    ys = 0.7 * xs + rng.normal(0, 0.3, 60)
+    axes[0, 1].scatter(xs, ys, s=12, alpha=0.7)
+    axes[0, 1].set_xlabel("Variable X")
+    axes[0, 1].set_ylabel("Variable Y")
+
+    axes[1, 0].bar(["A", "B", "C", "D"], [3.2, 5.8, 4.1, 6.5])
+    axes[1, 0].set_xlabel("Category")
+    axes[1, 0].set_ylabel("Count")
+
+    axes[1, 1].hist(rng.normal(0, 1, 500), bins=25, edgecolor="white", linewidth=0.5)
+    axes[1, 1].set_xlabel("Value")
+    axes[1, 1].set_ylabel("Frequency")
+
+    style.savefig(fig, "multi_panel.pdf")
+```
+
+<p align="center">
+  <img src="examples/output/multi_panel_science.png" width="70%" alt="2x2 multi-panel Science figure with automatic panel labels A B C D">
+</p>
+
+> `axes` is always a 2-D NumPy array. Use `axes[0, 0]` to access a single panel or `axes.flat` to iterate. Pass `panels=False` to suppress the automatic labels.
+
+---
+
+### Color palettes
+
+Each journal has a recommended colorblind-safe palette. `plotstyle.palette()` returns hex color strings, cycling if you need more than the palette length.
+
+```python
+import matplotlib.pyplot as plt
+import plotstyle
+
+journals = ["nature", "science", "ieee", "acs"]
+fig, axes = plt.subplots(len(journals), 1, figsize=(6, 0.6 * len(journals)))
+
+for ax, journal in zip(axes, journals):
+    pal = plotstyle.palette(journal, n=8)
+    for i, color in enumerate(pal):
+        ax.barh(0, 1, left=i, color=color, edgecolor="none", height=0.8)
+    ax.set_xlim(0, 8)
+    ax.set_yticks([])
+    ax.set_ylabel(journal, rotation=0, ha="right", va="center")
+    ax.set_xticks([])
+
+fig.suptitle("Journal Color Palettes")
+fig.tight_layout()
+fig.savefig("palette_comparison.png", dpi=150)
+```
+
+<p align="center">
+  <img src="examples/output/palette_comparison.png" width="70%" alt="Color swatch comparison for Nature, Science, IEEE, and ACS palettes">
+</p>
+
+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)
+```
+
+---
+
+### Colorblind and grayscale previews
+
+Build a figure, then simulate how it looks under color vision deficiency or grayscale printing before you submit.
+
+```python
+import numpy as np
+import plotstyle
+
+with plotstyle.use("nature") as style:
+    colors = style.palette(n=4)
+    fig, ax = style.figure(columns=1)
+    x = np.linspace(0, 5, 80)
+    for i, c in enumerate(colors):
+        ax.plot(x, np.sin(x + i), color=c, linewidth=1.5, label=f"Series {i + 1}")
+    ax.set_xlabel("Time (s)")
+    ax.set_ylabel("Signal")
+    ax.legend()
+
+    cvd_fig = plotstyle.preview_colorblind(fig)
+    cvd_fig.savefig("accessibility_colorblind.png", dpi=150, bbox_inches="tight")
+```
+
+<p align="center">
+  <img src="examples/output/accessibility_colorblind.png" width="90%" alt="Colorblind simulation: original, deuteranopia, protanopia, tritanopia">
+</p>
+
+```python
+    gray_fig = plotstyle.preview_grayscale(fig)
+    gray_fig.savefig("accessibility_grayscale.png", dpi=150, bbox_inches="tight")
+```
+
+<p align="center">
+  <img src="examples/output/accessibility_grayscale.png" width="60%" alt="Grayscale simulation: original vs grayscale rendering">
+</p>
+
+---
+
+### Validation and submission export
+
+Validate a figure against the journal's requirements, then export in all required formats at once.
+
+```python
+report = plotstyle.validate(fig, journal="nature")
+print(report)          # formatted compliance table
+print(report.passed)   # True if everything is OK
+
+for failure in report.failures:
+    print(failure.message)         # what failed
+    print(failure.fix_suggestion)  # how to fix it
+```
+
+```python
+paths = plotstyle.export_submission(
+    fig,
+    "figure1",
+    journal="ieee",
+    author_surname="Smith",     # IEEE prepends the surname prefix to filenames
+    output_dir="submission/",
+)
+# Produces: submission/smith_figure1.pdf (and any other IEEE-required formats)
+```
+
+---
+
+## Supported Journals
+
+| Key | Journal | Publisher |
+|-----|---------|-----------|
+| `acs` | ACS (JACS) | American Chemical Society |
+| `cell` | Cell | Cell Press |
+| `elsevier` | Elsevier | Elsevier |
+| `ieee` | IEEE Transactions | IEEE |
+| `nature` | Nature | Springer Nature |
+| `plos` | PLOS ONE | Public Library of Science |
+| `prl` | Physical Review Letters | American Physical Society |
+| `science` | Science | AAAS |
+| `springer` | Springer | Springer |
+| `wiley` | Wiley | Wiley |
+
+> Need another journal? See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## CLI
+
+```
+plotstyle list                                 # list all journal presets
+plotstyle info <journal>                       # show spec details
+plotstyle diff <journal_a> <journal_b>         # compare two journals
+plotstyle fonts --journal <journal>            # check font availability
+plotstyle validate <file> --journal <journal>  # validate a saved figure
+plotstyle export <file> --journal <journal>    # print snippet for re-exporting
+```
+
+---
+
+## Documentation
+
+Full documentation at **[plotstyle.readthedocs.io](https://plotstyle.readthedocs.io)**:
+
+- [Installation guide](https://plotstyle.readthedocs.io/en/stable/installation.html)
+- [Quick start tutorial](https://plotstyle.readthedocs.io/en/stable/quickstart.html)
+- [API reference](https://plotstyle.readthedocs.io/en/stable/api/index.html)
+- [CLI reference](https://plotstyle.readthedocs.io/en/stable/cli.html)
+- [FAQ](https://plotstyle.readthedocs.io/en/stable/faq.html)
+
+Working examples are in the [`examples/`](examples/) directory.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, adding journal specs, and pull request guidelines.
+
+---
+
+## Citation
+
+If PlotStyle helps your research, a citation or star is appreciated:
+
+```bibtex
+@misc{plotstyle,
+  author  = {Kaushal, Rahul},
+  title   = {PlotStyle: Publication-ready scientific figure presets for Matplotlib},
+  year    = {2026},
+  url     = {https://github.com/rahulkaushal04/plotstyle},
+  note    = {Version 1.1.0},
+}
+```
+
+---
+
+## License
+
+[MIT](LICENSE) © 2026 Rahul Kaushal