py-pluto 1.1.5__tar.gz → 1.2.0__tar.gz

py_pluto-1.1.5/README.md → py_pluto-1.2.0/PKG-INFO

@@ -1,3 +1,28 @@
+Metadata-Version: 2.4
+Name: py-pluto
+Version: 1.2.0
+Summary: PyPLUTO: Plotting routines for PLUTO
+Author: D. Crocco, D. Melon Fuksman, M. Bugli, V. Berta, E. Puzzoni, A. Mignone, B. Vaidya
+Author-email: "G. Mattia" <mattia@mpia.de>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: astropy>=7.2.0
+Requires-Dist: contourpy>=1.2.1
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: matplotlib>=3.8.4
+Requires-Dist: scipy>=1.13.0
+Requires-Dist: numexpr>=2.10.0
+Requires-Dist: h5py>=3.11.0
+Requires-Dist: inifix>=7.0.0
+Requires-Dist: PySide6 ; extra == "gui"
+Requires-Dist: pastamarkers ; extra == "pasta"
+Project-URL: Changelog, https://github.com/GiMattia/PyPLUTO/blob/main/CHANGELOG.md
+Project-URL: Examples, https://github.com/GiMattia/PyPLUTO/tree/main/Examples
+Project-URL: Homepage, https://github.com/GiMattia/PyPLUTO
+Provides-Extra: gui
+Provides-Extra: pasta
+
 # PyPLUTO: a data analysis Python package for the PLUTO code
 
 | Category | Badges |
@@ -7,7 +32,7 @@
 | Docs & Community | [![Project Status: Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![Documentation](https://readthedocs.org/projects/pypluto/badge/?version=latest)](https://pypluto.readthedocs.io/en/latest/?badge=latest)  [![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord&logoColor=white)](https://discord.gg/63A3sM9UtX)  [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) |
 | Citation | [![DOI](https://joss.theoj.org/papers/10.21105/joss.08448/status.svg)](https://doi.org/10.21105/joss.08448) [![Arxiv](https://img.shields.io/badge/arXiv-2501.09748-8F1515?style=flat&logo=arxiv&logoColor=red)](https://doi.org/10.48550/arXiv.2501.09748) [![Zenodo](https://zenodo.org/badge/DOI/10.5281/zenodo.19650848.svg)](https://doi.org/10.5281/zenodo.19650848) |
 
-PyPLUTO is a Python library which loads and plots the data obtain from the
+PyPLUTO is a Python library which loads and plots the data obtained from the
 PLUTO code simulations.
 The aim of this package is to simplify some non-trivial python routines in order
 to quickly recover effective plots that are suited for scientific publications.
@@ -20,21 +45,26 @@ The package is structured as follow:
 - the Load class is used to load the data from the PLUTO simulation fluid files.
 - the LoadPart class is used to load the data from the PLUTO simulation particle files.
 - the Image class is used to visualize the loaded data.
-- the GUI subpackage allows for a quic interactive script-free visualization.
+- the GUI subpackage allows for a quick interactive script-free visualization.
+- physical units can be attached to loaded variables via the `astropy` library.
 - additional functions (e.g., to show the images) are included in the package.
 
 The package includes a set of examples in the `Examples` directory.
 
-The package is tested on Python 3.13 (and newer versions) and with the following dependencies:
+The package requires Python 3.11 or newer (CI tests 3.12, 3.13, and 3.14)
+and the following core dependencies:
 
-- `numpy`
+- `astropy`
 - `contourpy`
+- `h5py`
+- `inifix`
 - `matplotlib`
 - `numexpr`
+- `numpy`
 - `scipy`
-- `h5py`
-- `inifix`
-- `PySide6`
+
+The GUI requires the optional dependency `PySide6`, installable via
+`pip install py-pluto[gui]`.
 
 The package is provided with a `LICENSE` file which contains the license terms.
 
@@ -50,7 +80,7 @@ The easiest way to install PyPLUTO is through uv. Open your terminal and run the
 uv add py-pluto
 ```
 
-Ensure that you are using Python 3.12 or newer, as the package is compatible from this version onwards.
+Ensure that you are using Python 3.11 or newer, as the package is compatible from this version onwards.
 Installation through pip is also possible through the command:
 
 ```bash
@@ -74,7 +104,7 @@ print(D)
 ```
 
 Relevant simulations attributes (such as the computational grid, the geometry and the variables to load) are found automatically.
-The data can be plotted through the Image class, which acts as a simplified maptlotlib wrapper.
+The data can be plotted through the Image class, which acts as a simplified matplotlib wrapper.
 An example of 1D plot of the density can be:
 
 ```python
@@ -99,6 +129,36 @@ In this way, PyPLUTO can be explored without any knowledge of the PLUTO code.
 All the tests are located in the `Examples` directory and are aimed at showing
 how to exploit the package capabilities.
 
+From an installed package, examples are available through:
+
+```bash
+pypluto-examples list
+pypluto-examples copy
+pypluto-examples run test01_sod
+```
+
+Equivalent Python API:
+
+```python
+import pyPLUTO as pp
+
+print(pp.examples_path())        # installed examples directory
+pp.copy_examples()               # creates ./pypluto_examples
+pp.run_example("test01_sod")     # runs one example script
+```
+
+### Maintainer notes for examples
+
+- Canonical sources stay in `Examples/` (repo root).
+- Installed users fetch a cached copy from GitHub (matching package version tag when available).
+- Before release, keep `Examples/` in sync with the release tag and verify CLI:
+
+```bash
+python3 -m build
+pip install dist/py_pluto-*.whl
+pypluto-examples list
+```
+
 ## The GUI
 
 A Graphical User Interface has been implemented in order to simplify and enhance the visualization and analysis of simulation data.
@@ -143,4 +203,5 @@ We recommend to put one the following expressions in your manuscript:
 
 If you have any questions, suggestions or find a bug, feel free to open an issue or fork the repository and create a pull request.
 Any contribution aimed at helping the PLUTO code community to have better plots with less efforts will be greatly appreciated.
-If you want to contribute to PyPLUTO please follow the instruction present in the CONTRIBUTING.md file.
+If you want to contribute to PyPLUTO please follow the instruction present in the CONTRIBUTING.md file.
+

py_pluto-1.1.5/PKG-INFO → py_pluto-1.2.0/README.md

@@ -1,25 +1,3 @@
-Metadata-Version: 2.4
-Name: py-pluto
-Version: 1.1.5
-Summary: PyPLUTO: Plotting routines for PLUTO
-Author: D. Crocco, D. Melon Fuksman, M. Bugli, V. Berta, E. Puzzoni, A. Mignone, B. Vaidya
-Author-email: "G. Mattia" <mattia@mpia.de>
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: contourpy>=1.2.1
-Requires-Dist: numpy>=2.0.0
-Requires-Dist: matplotlib>=3.8.4
-Requires-Dist: scipy>=1.13.0
-Requires-Dist: numexpr>=2.10.0
-Requires-Dist: pandas>=2.2.2
-Requires-Dist: h5py>=3.11.0
-Requires-Dist: inifix>=5.1.0
-Requires-Dist: PySide6 ; extra == "gui"
-Requires-Dist: pastamarkers ; extra == "pasta"
-Provides-Extra: gui
-Provides-Extra: pasta
-
 # PyPLUTO: a data analysis Python package for the PLUTO code
 
 | Category | Badges |
@@ -29,7 +7,7 @@ Provides-Extra: pasta
 | Docs & Community | [![Project Status: Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![Documentation](https://readthedocs.org/projects/pypluto/badge/?version=latest)](https://pypluto.readthedocs.io/en/latest/?badge=latest)  [![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord&logoColor=white)](https://discord.gg/63A3sM9UtX)  [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) |
 | Citation | [![DOI](https://joss.theoj.org/papers/10.21105/joss.08448/status.svg)](https://doi.org/10.21105/joss.08448) [![Arxiv](https://img.shields.io/badge/arXiv-2501.09748-8F1515?style=flat&logo=arxiv&logoColor=red)](https://doi.org/10.48550/arXiv.2501.09748) [![Zenodo](https://zenodo.org/badge/DOI/10.5281/zenodo.19650848.svg)](https://doi.org/10.5281/zenodo.19650848) |
 
-PyPLUTO is a Python library which loads and plots the data obtain from the
+PyPLUTO is a Python library which loads and plots the data obtained from the
 PLUTO code simulations.
 The aim of this package is to simplify some non-trivial python routines in order
 to quickly recover effective plots that are suited for scientific publications.
@@ -42,21 +20,26 @@ The package is structured as follow:
 - the Load class is used to load the data from the PLUTO simulation fluid files.
 - the LoadPart class is used to load the data from the PLUTO simulation particle files.
 - the Image class is used to visualize the loaded data.
-- the GUI subpackage allows for a quic interactive script-free visualization.
+- the GUI subpackage allows for a quick interactive script-free visualization.
+- physical units can be attached to loaded variables via the `astropy` library.
 - additional functions (e.g., to show the images) are included in the package.
 
 The package includes a set of examples in the `Examples` directory.
 
-The package is tested on Python 3.13 (and newer versions) and with the following dependencies:
+The package requires Python 3.11 or newer (CI tests 3.12, 3.13, and 3.14)
+and the following core dependencies:
 
-- `numpy`
+- `astropy`
 - `contourpy`
+- `h5py`
+- `inifix`
 - `matplotlib`
 - `numexpr`
+- `numpy`
 - `scipy`
-- `h5py`
-- `inifix`
-- `PySide6`
+
+The GUI requires the optional dependency `PySide6`, installable via
+`pip install py-pluto[gui]`.
 
 The package is provided with a `LICENSE` file which contains the license terms.
 
@@ -72,7 +55,7 @@ The easiest way to install PyPLUTO is through uv. Open your terminal and run the
 uv add py-pluto
 ```
 
-Ensure that you are using Python 3.12 or newer, as the package is compatible from this version onwards.
+Ensure that you are using Python 3.11 or newer, as the package is compatible from this version onwards.
 Installation through pip is also possible through the command:
 
 ```bash
@@ -96,7 +79,7 @@ print(D)
 ```
 
 Relevant simulations attributes (such as the computational grid, the geometry and the variables to load) are found automatically.
-The data can be plotted through the Image class, which acts as a simplified maptlotlib wrapper.
+The data can be plotted through the Image class, which acts as a simplified matplotlib wrapper.
 An example of 1D plot of the density can be:
 
 ```python
@@ -121,6 +104,36 @@ In this way, PyPLUTO can be explored without any knowledge of the PLUTO code.
 All the tests are located in the `Examples` directory and are aimed at showing
 how to exploit the package capabilities.
 
+From an installed package, examples are available through:
+
+```bash
+pypluto-examples list
+pypluto-examples copy
+pypluto-examples run test01_sod
+```
+
+Equivalent Python API:
+
+```python
+import pyPLUTO as pp
+
+print(pp.examples_path())        # installed examples directory
+pp.copy_examples()               # creates ./pypluto_examples
+pp.run_example("test01_sod")     # runs one example script
+```
+
+### Maintainer notes for examples
+
+- Canonical sources stay in `Examples/` (repo root).
+- Installed users fetch a cached copy from GitHub (matching package version tag when available).
+- Before release, keep `Examples/` in sync with the release tag and verify CLI:
+
+```bash
+python3 -m build
+pip install dist/py_pluto-*.whl
+pypluto-examples list
+```
+
 ## The GUI
 
 A Graphical User Interface has been implemented in order to simplify and enhance the visualization and analysis of simulation data.

{py_pluto-1.1.5 → py_pluto-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "flit_core.buildapi"
 
 [project]
 name = "py-pluto"
-dynamic = ["version"]
+version = "1.2.0"
 description = "PyPLUTO: Plotting routines for PLUTO"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -20,14 +20,14 @@ authors = [
     { name = "B. Vaidya" }
 ]
 dependencies = [
+    "astropy>=7.2.0",
     "contourpy>=1.2.1",
     "numpy>=2.0.0",
     "matplotlib>=3.8.4",
     "scipy>=1.13.0",
     "numexpr>=2.10.0",
-    "pandas>=2.2.2",
     "h5py>=3.11.0",
-    "inifix>=5.1.0",
+    "inifix>=7.0.0",
 ]
 
 [project.optional-dependencies]
@@ -54,17 +54,27 @@ test = [
 ] 
 dev = [
     "uv",
+    "auto-walrus",
     "pandas-stubs",
     "h5py-stubs",
     "pre-commit",
     "pyright",
-    "pyrefly",
     "ruff",
-    "ty>=0.0.17",
     "radon",
     "pydata-sphinx-theme",
 ]
 
+# Type checkers we keep installable but do NOT yet use as the source of truth.
+# pyright (in the `dev` group) is the standard checker for PyPLUTO. Every issue
+# these would report is already covered by pyright; they are kept here so we can
+# switch to one of them once they are mature enough to validate the patterns
+# PyPLUTO relies on (Generic + overloaded __new__, Unpack[TypedDict] extra-key
+# rejection, etc.).
+typefuture = [
+    "pyrefly",
+    "ty",
+]
+
 notebook = [
     "ipython>=9.0.0",
 ]
@@ -76,6 +86,7 @@ dev-test = [
 
 dev-docs = [
     { include-group = "dev" },
+
     { include-group = "docs" },
 ]
 
@@ -88,10 +99,16 @@ local-dev = [
 
 [project.scripts]
 pypluto-gui = "pyPLUTO.gui.main:main"
+pypluto-examples = "pyPLUTO.utils.examples_cli:main"
 
 [tool.flit.module]
 name = "pyPLUTO"
 
+[project.urls]
+Homepage = "https://github.com/GiMattia/PyPLUTO"
+Changelog = "https://github.com/GiMattia/PyPLUTO/blob/main/CHANGELOG.md"
+Examples = "https://github.com/GiMattia/PyPLUTO/tree/main/Examples"
+
 [tool.coverage.run]
 source = ["src"]
 branch = true
@@ -147,13 +164,16 @@ convention = "numpy"
 
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401"]
-"tests/*" = ["D", "PLR2004"]
+"Tests/*" = ["D", "PLR2004"]
 
 [tool.ruff.format]
 quote-style = "double"
 indent-style = "space"
 line-ending = "auto"
 
+[tool.setuptools.package-data]
+pyPLUTO = ["py.typed"]
+
 [tool.uv]
 no-build-package = [
     # mandatory deps
@@ -182,10 +202,9 @@ no-build-package = [
     "simplejson",
 ]
 constraint-dependencies = [
-    "jsonschema>=0.3",
-    "pillow>=10.0.0",
+    "jsonschema>=4.26.0",
+    "pillow>=12.2.0",
 ]
-
 [tool.pixi.workspace]
 channels = ["conda-forge"]
 platforms = ["linux-64", "osx-64", "osx-arm64", "win-64"]
@@ -212,9 +231,39 @@ pasta = { features = ["pasta"] }
 full = { features = ["full"] }
 
 dev = { features = ["dev"] }
+typefuture = { features = ["typefuture"] }
 test = { features = ["test"] }
 docs = { features = ["docs"] }
 notebook = { features = ["notebook"] }
 dev-test = { features = ["dev", "test"] }
 dev-docs = { features = ["dev", "docs"] }
 local-dev = { features = ["dev", "test", "docs", "notebook"] }
+
+# pyright is the standard type checker for PyPLUTO (run via the `dev` dependency
+# group). See CONTRIBUTING for the rationale.
+[tool.pyright]
+pythonVersion = "3.11"
+typeCheckingMode = "standard"
+include = ["src"]
+exclude = [
+    "**/__pycache__",
+    "**/node_modules",
+    "**/.*",
+    "**/.venv",
+    "Tests",
+]
+
+# NOTE: pyrefly and ty (the `typefuture` dependency group) are kept available
+# but are NOT the source of truth yet; pyright already covers every issue they
+# would report. We will switch once they mature on the patterns PyPLUTO uses.
+[tool.pyrefly]
+project-includes = [
+    "**/*.py*",
+    "**/*.ipynb",
+]
+project-excludes = [
+    "Tests/**/*.py*",
+    "Tests/**/*.ipynb",
+]
+python-version = "3.11"
+preset = "basic"

py_pluto-1.2.0/src/pyPLUTO/__init__.py

@@ -0,0 +1,44 @@
+"""Top-level package for pyPLUTO."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+from pyPLUTO.image import Image
+from pyPLUTO.load import Load
+from pyPLUTO.loadpart import LoadPart
+from pyPLUTO.utils.configure import Configure, set_text
+from pyPLUTO.utils.examples_api import (
+    copy_examples,
+    examples_path,
+    list_examples,
+    run_example,
+)
+from pyPLUTO.utils.pytools import find_example, ring, savefig, show
+
+try:
+    __version__ = _version("py-pluto")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+colorerr: bool = True
+colorwarn: bool = True
+greet: bool = True
+
+Configure(__version__, colorerr, colorwarn, greet)
+
+__all__ = [
+    "Image",
+    "Load",
+    "LoadPart",
+    "copy_examples",
+    "examples_path",
+    "find_example",
+    "list_examples",
+    "ring",
+    "run_example",
+    "savefig",
+    "set_text",
+    "show",
+]