xdiffly 0.2.6__tar.gz

xdiffly-0.2.6/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.3
+Name: xdiffly
+Version: 0.2.6
+Summary: X-Diff: a general-purpose tool for exploring differences between datasets (netCDF today, more targets to come)
+Author: Antonio Mariani
+Author-email: Antonio Mariani <antonio.mariani@cmcc.it>
+Requires-Dist: xarray>=2024.6.0,<2025.0.0
+Requires-Dist: pandas>=2.2.2,<3.0.0
+Requires-Dist: netcdf4>=1.7.1,<2.0.0
+Requires-Dist: rich>=13.7.1,<14.0.0
+Requires-Dist: click>=8.3.1,<9.0.0
+Requires-Dist: dask>=2024.6.0,<2025.0.0
+Requires-Dist: distributed>=2024.6.0,<2025.0.0
+Requires-Dist: bokeh>=3.1.0,<4.0.0
+Requires-Python: >=3.10, <3.14
+Project-URL: Changelog, https://github.com/anto6715/X-Diff/blob/master/CHANGES.md
+Project-URL: Homepage, https://github.com/anto6715/X-Diff
+Project-URL: Issues, https://github.com/anto6715/X-Diff/issues
+Project-URL: Repository, https://github.com/anto6715/X-Diff
+Description-Content-Type: text/markdown
+
+# X-Diff
+
+`xdiff` is the CLI for **X-Diff**, a general diff tool name where `X` can stand for different comparison targets.
+Today, X-Diff supports detailed comparison of netCDF files and helps users identify differences between datasets stored
+in netCDF format.
+
+![Python](https://img.shields.io/badge/Python-3.10--3.13-blue.svg)
+[![Tests](https://github.com/anto6715/ncCompare/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/anto6715/ncCompare/actions/workflows/tests.yml)
+[![Coverage](https://codecov.io/gh/anto6715/ncCompare/graph/badge.svg?branch=master)](https://codecov.io/gh/anto6715/ncCompare)
+
+![Output](https://github.com/anto6715/ncCompare/raw/master/docs/output.png)
+
+## Installation
+
+### Install uv
+
+Follow the official installer:
+
+```shell
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Install in a local virtual environment (recommended for development)
+
+`xdiff` currently supports Python 3.10 through 3.13. Create the project-local environment and install dependencies from `uv.lock` with:
+
+```shell
+uv sync --python 3.13
+```
+
+Run the CLI through uv:
+
+```shell
+uv run xdiff --help
+```
+
+### Install globally with uv tool
+
+The package is published on PyPI as `xdiffly`; it installs the `xdiff` command.
+
+```shell
+uv tool install --python 3.13 xdiffly
+```
+
+`uv tool install` installs `xdiffly` in uv's global tool environment (similar to `pipx`), not inside this repository's `.venv`. After installation, run it as `xdiff`.
+
+## Usage
+
+From a source checkout, prefix commands with `uv run`. If you installed with `uv tool install`, use `xdiff` directly.
+
+```shell
+uv run xdiff [OPTIONS] COMMAND [ARGS]...
+
+  netCDF comparison tool.
+
+Options:
+  --version   Show the version and exit.
+  -h, --help  Show this message and exit.
+
+Commands:
+  dirs   Compare two directories of netCDF files.
+  files  Compare two netCDF files directly, even if their filenames differ.
+
+```
+
+### Select Variables
+
+It is possible to choose which parameter to compare:
+
+```shell
+uv run xdiff dirs folder1 folder2 -v votemper -v vosaline
+```
+
+![Variables](https://github.com/anto6715/ncCompare/raw/master/docs/variables.png)
+
+### Filter files
+
+By default **xdiff** iterates over all files in **folder1** and expects to find them in **folder2**. Using filters,
+it is possible to select only a subset of input files. For example:
+
+```shell
+uv run xdiff dirs folder1 folder2 -f "*_grid_T.nc"
+```
+
+### Compare files with different filenames
+
+It is possible to compare two files with different filenames directly:
+
+```shell
+uv run xdiff files a/my-simu_19820101_grid_T.nc b/another-exp_19820101_grid_T.nc
+```
+
+For directory comparisons, files with different names can still be matched if they share a common substring.
+For example, given:
+
+- `a/my-simu_19820101_grid_T.nc`
+- `b/another-exp_19820101_grid_T.nc`
+
+Pass the common part as a regex pattern:
+
+```shell
+uv run xdiff dirs folder1 folder2 --common-pattern "\d{8}"
+```
+
+The pattern is matched against both filenames using `re.findall`. Two files are considered a pair when the
+pattern produces the same match in both names — in this case the shared date `19820101`.
+
+### Dask file-level execution
+
+`xdiff` still defaults to serial execution, but Dask support is installed by default. When you want Dask-backed file-level execution, see [docs/dask.md](docs/dask.md) for local-cluster and external-scheduler examples.
+
+## Testing
+
+GitHub Actions runs the test suite on every pull request and on pushes to `master`. Coverage is uploaded from CI to Codecov, which powers the README coverage badge.
+
+To run the same checks locally, install the project and dev dependencies with a single command:
+
+```shell
+uv sync --group dev
+```
+
+Then run the suite:
+
+```shell
+uv run pytest --cov --cov-report=term-missing --cov-report=xml
+```
+
+The Codecov badge will start showing a real percentage after the workflow runs successfully on GitHub and the repository is connected to Codecov.
+
+## Changelog
+
+This repository uses `towncrier` for release notes. Every pull request must include a changelog entry under `changes.d/` for user-facing changes, for example:
+
+```text
+changes.d/123.bugfix.md
+changes.d/124.doc.md
+changes.d/+internal-cleanup.misc.md
+```
+
+Use the pull request number as the filename prefix when you want Towncrier to render a linked PR reference. With the current configuration, `changes.d/123.bugfix.md` will render as `[#123]` in `CHANGES.md`. Use `+` instead of a number when there is no associated PR to link.
+
+Create a changelog entry with the Towncrier CLI:
+
+```shell
+uv run towncrier create 123.bugfix.md --content "Improved CLI filtering so directory comparisons skip unrelated files more reliably."
+```
+
+Create an orphan entry when there is no associated PR:
+
+```shell
+uv run towncrier create +internal-cleanup.misc.md --content "Cleaned up internal comparison helpers and simplified related tests."
+```
+
+If you omit `--content`, `towncrier create` will open your editor so you can write the entry interactively.
+
+Validate or preview changelog entries locally with:
+
+```shell
+uv run towncrier build --draft --version 0.2.6
+```
+
+To mirror the CI-style branch check after committing or staging your changelog entry:
+
+```shell
+git fetch origin master:refs/remotes/origin/master
+uv run towncrier check --compare-with origin/master --staged
+```
+
+Release notes are generated from `release/X.Y.Z` branches. Open a PR from `release/X.Y.Z` to `master`, and CI will:
+
+1. set `pyproject.toml` to version `X.Y.Z`
+2. run `towncrier build --yes --version X.Y.Z`
+3. commit the updated `CHANGES.md` and consumed changelog entries back to the release branch
+
+In normal feature work, contributors should create entries with `towncrier create` and optionally preview them with `towncrier build --draft`. The final non-draft `towncrier build --yes` step is handled by the release workflow in [`.github/workflows/release-changelog.yml`](.github/workflows/release-changelog.yml).
+
+After the release PR is merged, merge `master` back into `develop` so the generated changelog and consumed entry deletions return to the integration branch.
+
+## Author
+
+- Antonio Mariani (antonio.mariani@cmcc.it)
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.
+
+## Contact
+
+For any questions or suggestions, please open an issue on the project's GitHub repository.

xdiffly-0.2.6/README.md

@@ -0,0 +1,189 @@
+# X-Diff
+
+`xdiff` is the CLI for **X-Diff**, a general diff tool name where `X` can stand for different comparison targets.
+Today, X-Diff supports detailed comparison of netCDF files and helps users identify differences between datasets stored
+in netCDF format.
+
+![Python](https://img.shields.io/badge/Python-3.10--3.13-blue.svg)
+[![Tests](https://github.com/anto6715/ncCompare/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/anto6715/ncCompare/actions/workflows/tests.yml)
+[![Coverage](https://codecov.io/gh/anto6715/ncCompare/graph/badge.svg?branch=master)](https://codecov.io/gh/anto6715/ncCompare)
+
+![Output](https://github.com/anto6715/ncCompare/raw/master/docs/output.png)
+
+## Installation
+
+### Install uv
+
+Follow the official installer:
+
+```shell
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Install in a local virtual environment (recommended for development)
+
+`xdiff` currently supports Python 3.10 through 3.13. Create the project-local environment and install dependencies from `uv.lock` with:
+
+```shell
+uv sync --python 3.13
+```
+
+Run the CLI through uv:
+
+```shell
+uv run xdiff --help
+```
+
+### Install globally with uv tool
+
+The package is published on PyPI as `xdiffly`; it installs the `xdiff` command.
+
+```shell
+uv tool install --python 3.13 xdiffly
+```
+
+`uv tool install` installs `xdiffly` in uv's global tool environment (similar to `pipx`), not inside this repository's `.venv`. After installation, run it as `xdiff`.
+
+## Usage
+
+From a source checkout, prefix commands with `uv run`. If you installed with `uv tool install`, use `xdiff` directly.
+
+```shell
+uv run xdiff [OPTIONS] COMMAND [ARGS]...
+
+  netCDF comparison tool.
+
+Options:
+  --version   Show the version and exit.
+  -h, --help  Show this message and exit.
+
+Commands:
+  dirs   Compare two directories of netCDF files.
+  files  Compare two netCDF files directly, even if their filenames differ.
+
+```
+
+### Select Variables
+
+It is possible to choose which parameter to compare:
+
+```shell
+uv run xdiff dirs folder1 folder2 -v votemper -v vosaline
+```
+
+![Variables](https://github.com/anto6715/ncCompare/raw/master/docs/variables.png)
+
+### Filter files
+
+By default **xdiff** iterates over all files in **folder1** and expects to find them in **folder2**. Using filters,
+it is possible to select only a subset of input files. For example:
+
+```shell
+uv run xdiff dirs folder1 folder2 -f "*_grid_T.nc"
+```
+
+### Compare files with different filenames
+
+It is possible to compare two files with different filenames directly:
+
+```shell
+uv run xdiff files a/my-simu_19820101_grid_T.nc b/another-exp_19820101_grid_T.nc
+```
+
+For directory comparisons, files with different names can still be matched if they share a common substring.
+For example, given:
+
+- `a/my-simu_19820101_grid_T.nc`
+- `b/another-exp_19820101_grid_T.nc`
+
+Pass the common part as a regex pattern:
+
+```shell
+uv run xdiff dirs folder1 folder2 --common-pattern "\d{8}"
+```
+
+The pattern is matched against both filenames using `re.findall`. Two files are considered a pair when the
+pattern produces the same match in both names — in this case the shared date `19820101`.
+
+### Dask file-level execution
+
+`xdiff` still defaults to serial execution, but Dask support is installed by default. When you want Dask-backed file-level execution, see [docs/dask.md](docs/dask.md) for local-cluster and external-scheduler examples.
+
+## Testing
+
+GitHub Actions runs the test suite on every pull request and on pushes to `master`. Coverage is uploaded from CI to Codecov, which powers the README coverage badge.
+
+To run the same checks locally, install the project and dev dependencies with a single command:
+
+```shell
+uv sync --group dev
+```
+
+Then run the suite:
+
+```shell
+uv run pytest --cov --cov-report=term-missing --cov-report=xml
+```
+
+The Codecov badge will start showing a real percentage after the workflow runs successfully on GitHub and the repository is connected to Codecov.
+
+## Changelog
+
+This repository uses `towncrier` for release notes. Every pull request must include a changelog entry under `changes.d/` for user-facing changes, for example:
+
+```text
+changes.d/123.bugfix.md
+changes.d/124.doc.md
+changes.d/+internal-cleanup.misc.md
+```
+
+Use the pull request number as the filename prefix when you want Towncrier to render a linked PR reference. With the current configuration, `changes.d/123.bugfix.md` will render as `[#123]` in `CHANGES.md`. Use `+` instead of a number when there is no associated PR to link.
+
+Create a changelog entry with the Towncrier CLI:
+
+```shell
+uv run towncrier create 123.bugfix.md --content "Improved CLI filtering so directory comparisons skip unrelated files more reliably."
+```
+
+Create an orphan entry when there is no associated PR:
+
+```shell
+uv run towncrier create +internal-cleanup.misc.md --content "Cleaned up internal comparison helpers and simplified related tests."
+```
+
+If you omit `--content`, `towncrier create` will open your editor so you can write the entry interactively.
+
+Validate or preview changelog entries locally with:
+
+```shell
+uv run towncrier build --draft --version 0.2.6
+```
+
+To mirror the CI-style branch check after committing or staging your changelog entry:
+
+```shell
+git fetch origin master:refs/remotes/origin/master
+uv run towncrier check --compare-with origin/master --staged
+```
+
+Release notes are generated from `release/X.Y.Z` branches. Open a PR from `release/X.Y.Z` to `master`, and CI will:
+
+1. set `pyproject.toml` to version `X.Y.Z`
+2. run `towncrier build --yes --version X.Y.Z`
+3. commit the updated `CHANGES.md` and consumed changelog entries back to the release branch
+
+In normal feature work, contributors should create entries with `towncrier create` and optionally preview them with `towncrier build --draft`. The final non-draft `towncrier build --yes` step is handled by the release workflow in [`.github/workflows/release-changelog.yml`](.github/workflows/release-changelog.yml).
+
+After the release PR is merged, merge `master` back into `develop` so the generated changelog and consumed entry deletions return to the integration branch.
+
+## Author
+
+- Antonio Mariani (antonio.mariani@cmcc.it)
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.
+
+## Contact
+
+For any questions or suggestions, please open an issue on the project's GitHub repository.

xdiffly-0.2.6/pyproject.toml

@@ -0,0 +1,86 @@
+[project]
+name = "xdiffly"
+version = "0.2.6"
+description = "X-Diff: a general-purpose tool for exploring differences between datasets (netCDF today, more targets to come)"
+authors = [
+    {name = "Antonio Mariani", email = "antonio.mariani@cmcc.it"}
+]
+readme = "README.md"
+requires-python = ">=3.10,<3.14"
+dependencies = [
+    "xarray>=2024.6.0,<2025.0.0",
+    "pandas>=2.2.2,<3.0.0",
+    "netcdf4>=1.7.1,<2.0.0",
+    "rich>=13.7.1,<14.0.0",
+    "click>=8.3.1,<9.0.0",
+    "dask>=2024.6.0,<2025.0.0",
+    "distributed>=2024.6.0,<2025.0.0",
+    "bokeh>=3.1.0,<4.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/anto6715/X-Diff"
+Repository = "https://github.com/anto6715/X-Diff"
+Issues = "https://github.com/anto6715/X-Diff/issues"
+Changelog = "https://github.com/anto6715/X-Diff/blob/master/CHANGES.md"
+
+[project.scripts]
+xdiff = "xdiff.management:start_from_command_line_interface"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0,<9.0.0",
+    "pytest-cov>=5.0,<6.0.0",
+    "towncrier>=25.8,<26.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.5,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "xdiff"
+module-root = ""
+
+[tool.pytest.ini_options]
+filterwarnings = [
+    "ignore:numpy.ndarray size changed, may indicate binary incompatibility.*:RuntimeWarning",
+]
+
+[tool.coverage.run]
+source = ["xdiff"]
+
+[tool.coverage.report]
+show_missing = true
+
+[tool.towncrier]
+directory = "changes.d"
+name = "X-Diff"
+package = "xdiff"
+filename = "CHANGES.md"
+start_string = "<!-- towncrier release notes start -->\n"
+title_format = "## __[xdiff-{version}](https://github.com/anto6715/X-Diff/tree/{version}) - {project_date}__"
+issue_format = "[#{issue}](https://github.com/anto6715/X-Diff/pull/{issue})"
+underlines = ["", "", ""]
+template = "changes.d/changelog_template.jinja"
+changelog_format = "markdown"
+
+[[tool.towncrier.type]]
+directory = "feature"
+name = "🚀 Features"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "bugfix"
+name = "🔧 Bugfixes"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "doc"
+name = "Documentation"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "misc"
+name = "Miscellaneous"
+showcontent = true

xdiffly-0.2.6/xdiff/__init__.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import sys
+
+from xdiff import conf as settings
+from xdiff.utils.log import configure_logging
+
+MIN_SUPPORTED_PYTHON = (3, 10)
+MAX_SUPPORTED_PYTHON = (3, 14)
+
+
+def validate_runtime() -> None:
+    version = sys.version_info[:2]
+    if MIN_SUPPORTED_PYTHON <= version < MAX_SUPPORTED_PYTHON:
+        return
+
+    raise RuntimeError(
+        "xdiff supports Python 3.10 through 3.13. "
+        f"The current interpreter is Python {version[0]}.{version[1]}."
+    )
+
+
+def setup():
+    validate_runtime()
+    configure_logging(settings.LOGGING_CONFIG, settings.LOGGING)

xdiffly-0.2.6/xdiff/comparators/__init__.py

@@ -0,0 +1,19 @@
+"""Comparator implementations for each artifact type."""
+
+from importlib import import_module
+
+from xdiff.comparators.base import ArtifactComparator
+
+__all__ = ["ArtifactComparator", "NetcdfComparator"]
+
+
+def __getattr__(name: str):
+    if name == "NetcdfComparator":
+        comparator = getattr(import_module("xdiff.comparators.netcdf"), name)
+        globals()[name] = comparator
+        return comparator
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

xdiffly-0.2.6/xdiff/comparators/base.py

@@ -0,0 +1,20 @@
+"""Base interfaces for artifact comparators."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from xdiff.model.artifact import ArtifactKind
+from xdiff.model.comparison import Comparison
+from xdiff.model.match import ArtifactMatch
+from xdiff.model.request import CompareRequest
+
+
+class ArtifactComparator(ABC):
+    """Compares a matched pair of artifacts."""
+
+    artifact_kind: ArtifactKind
+
+    @abstractmethod
+    def compare(self, match: ArtifactMatch, request: CompareRequest) -> Comparison:
+        """Return the comparison outcome for a single matched pair."""