pytest-ditto-polars 2.0.0rc1__tar.gz

pytest_ditto_polars-2.0.0rc1/.gitignore

@@ -0,0 +1,49 @@
+# tests/ci/.ditto and the root ditto.lock are pytest-ditto's own committed,
+# PR-reviewed baseline (see docs/src/guides/lock-file.md), and each first-party
+# plugin has its own under plugins/<name>/ — everywhere else .ditto/ditto.lock
+# are ephemeral local test-run artifacts.
+.ditto
+!/tests/ci/.ditto/
+!/plugins/*/tests/ci/.ditto/
+ditto.lock
+!/ditto.lock
+!/plugins/*/ditto.lock
+.tmp/
+tmp.py
+ditto-tui.html
+
+# Python
+__pycache__
+# Written by the hatch-vcs build hook on every build and editable install.
+src/ditto/_version.py
+*.egg-info
+*.pyc
+
+# Testing
+.pytest_cache
+.pytest
+.coverage
+.hypothesis
+
+# Linting
+.ruff_cache
+
+# IDE
+.idea/
+.vscode/
+.claude/
+
+# Build artifacts
+dist/
+archive/
+docs/site/
+
+# pixi environments
+.pixi/*
+!.pixi/config.toml
+
+# Dev
+.designs/
+.issues/
+.impl/
+/tests/release/synthetic_plugin/build/

pytest_ditto_polars-2.0.0rc1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 pytest-ditto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytest_ditto_polars-2.0.0rc1/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: pytest-ditto-polars
+Version: 2.0.0rc1
+Summary: pytest-ditto plugin for polars DataFrame snapshots.
+Project-URL: Homepage, https://github.com/owlowlyowl/pytest-ditto
+Project-URL: Source, https://github.com/owlowlyowl/pytest-ditto/tree/main/plugins/polars
+Author-email: Lachlan Taylor <95459213+owlowlyowl@users.noreply.github.com>
+Maintainer-email: Lachlan Taylor <95459213+owlowlyowl@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: polars,pytest,snapshot,testing
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Requires-Dist: polars>=1.0
+Requires-Dist: pytest-ditto<3,>=2.0.0rc1
+Description-Content-Type: text/markdown
+
+# pytest-ditto-polars
+
+Extension plugin for [`pytest-ditto`](https://github.com/owlowlyowl/pytest-ditto) for `polars` DataFrame snapshots.
+
+Use the following marks for their associated recorder:
+- `@ditto.polars.parquet`
+- `@ditto.polars.ipc`
+- `@ditto.polars.csv`
+- `@ditto.polars.ndjson`
+
+Each mark is shorthand for `@ditto.record("polars.<format>")`.
+
+## Installation
+```bash
+pip install pytest-ditto[polars]
+```
+
+## Usage
+
+```python
+import polars as pl
+import polars.testing
+
+import ditto
+
+
+def awesome_fn_to_test(df: pl.DataFrame) -> pl.DataFrame:
+    return df.with_columns(pl.col("a") * 2)
+
+
+# The following test uses polars.DataFrame.write_parquet to write the data snapshot
+# to the `.ditto` directory with filename:
+# `<module>.test_fn_with_parquet_dataframe_snapshot@ab_dataframe.polars.parquet`.
+
+
+@ditto.polars.parquet
+def test_fn_with_parquet_dataframe_snapshot(snapshot):
+    input_data = pl.DataFrame({"a": [1, 2, 3], "b": [4, 5, 9]})
+    result = awesome_fn_to_test(input_data)
+    pl.testing.assert_frame_equal(result, snapshot(result, key="ab_dataframe"))
+```
+
+### Format notes
+
+Prefer `@ditto.polars.parquet`. It round-trips a DataFrame's values and dtypes.
+The other formats are available when you need them, with these limits:
+
+| Format | Values and dtypes |
+|--------|-------------------|
+| parquet | preserved |
+| ipc | preserved; Polars marks `write_ipc` unstable, so snapshots can break across Polars versions |
+| csv | re-inferred from text |
+| ndjson | re-inferred from JSON |
+
+**IPC** uses Polars' Arrow IPC writer. Polars documents `write_ipc` as
+unstable, so a snapshot recorded on one Polars version may fail to load or
+compare on another even if the DataFrame under test did not change.
+
+**CSV** and **NDJSON** keep no type metadata, so dtypes are inferred again on
+load. Frames of ints, floats, and strings round-trip in the plugin tests.
+Do not use these formats for categoricals, enums, nested, or temporal columns.

pytest_ditto_polars-2.0.0rc1/README.md

@@ -0,0 +1,61 @@
+# pytest-ditto-polars
+
+Extension plugin for [`pytest-ditto`](https://github.com/owlowlyowl/pytest-ditto) for `polars` DataFrame snapshots.
+
+Use the following marks for their associated recorder:
+- `@ditto.polars.parquet`
+- `@ditto.polars.ipc`
+- `@ditto.polars.csv`
+- `@ditto.polars.ndjson`
+
+Each mark is shorthand for `@ditto.record("polars.<format>")`.
+
+## Installation
+```bash
+pip install pytest-ditto[polars]
+```
+
+## Usage
+
+```python
+import polars as pl
+import polars.testing
+
+import ditto
+
+
+def awesome_fn_to_test(df: pl.DataFrame) -> pl.DataFrame:
+    return df.with_columns(pl.col("a") * 2)
+
+
+# The following test uses polars.DataFrame.write_parquet to write the data snapshot
+# to the `.ditto` directory with filename:
+# `<module>.test_fn_with_parquet_dataframe_snapshot@ab_dataframe.polars.parquet`.
+
+
+@ditto.polars.parquet
+def test_fn_with_parquet_dataframe_snapshot(snapshot):
+    input_data = pl.DataFrame({"a": [1, 2, 3], "b": [4, 5, 9]})
+    result = awesome_fn_to_test(input_data)
+    pl.testing.assert_frame_equal(result, snapshot(result, key="ab_dataframe"))
+```
+
+### Format notes
+
+Prefer `@ditto.polars.parquet`. It round-trips a DataFrame's values and dtypes.
+The other formats are available when you need them, with these limits:
+
+| Format | Values and dtypes |
+|--------|-------------------|
+| parquet | preserved |
+| ipc | preserved; Polars marks `write_ipc` unstable, so snapshots can break across Polars versions |
+| csv | re-inferred from text |
+| ndjson | re-inferred from JSON |
+
+**IPC** uses Polars' Arrow IPC writer. Polars documents `write_ipc` as
+unstable, so a snapshot recorded on one Polars version may fail to load or
+compare on another even if the DataFrame under test did not change.
+
+**CSV** and **NDJSON** keep no type metadata, so dtypes are inferred again on
+load. Frames of ints, floats, and strings round-trip in the plugin tests.
+Do not use these formats for categoricals, enums, nested, or temporal columns.

pytest_ditto_polars-2.0.0rc1/hatch_build.py

@@ -0,0 +1,30 @@
+"""Add the plugin's requirement on pytest-ditto to its dependencies.
+
+Plugins are released in lockstep with pytest-ditto, from the same git tag, so each
+requires at least the core it was released with: plugin X.Y.Z requires
+``pytest-ditto>=X.Y.Z,<3``. The local segment (``+sha`` on untagged commits) is
+dropped because PEP 440 doesn't allow it in a ``>=`` specifier. ``<3`` is the plugin
+contract's major version.
+
+The plugin's other dependencies are listed under
+``[tool.hatch.metadata.hooks.custom]`` in its ``pyproject.toml``. A wheel built from
+the sdist takes all of them from ``PKG-INFO`` and doesn't run this hook.
+
+Every plugin carries an identical copy of this file, so it ships in each sdist.
+"""
+
+from typing import Any
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+from packaging.version import Version
+
+CORE_MAJOR = 2
+
+
+class CoreFloorHook(MetadataHookInterface):
+    def update(self, metadata: dict[str, Any]) -> None:
+        floor = Version(metadata["version"]).public
+        metadata["dependencies"] = [
+            f"pytest-ditto>={floor},<{CORE_MAJOR + 1}",
+            *self.config.get("dependencies", []),
+        ]

pytest_ditto_polars-2.0.0rc1/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "pytest-ditto-polars"
+dynamic = ["version", "dependencies"]
+description = "pytest-ditto plugin for polars DataFrame snapshots."
+keywords = ["pytest", "testing", "polars", "snapshot"]
+authors = [{ name = "Lachlan Taylor", email = "95459213+owlowlyowl@users.noreply.github.com" }]
+maintainers = [{ name = "Lachlan Taylor", email = "95459213+owlowlyowl@users.noreply.github.com" }]
+requires-python = ">=3.12"
+license = "MIT"
+readme = "README.md"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Software Development :: Testing",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/owlowlyowl/pytest-ditto"
+Source = "https://github.com/owlowlyowl/pytest-ditto/tree/main/plugins/polars"
+
+[project.entry-points.ditto_recorders]
+"polars.parquet" = "ditto_polars.recorders:parquet"
+"polars.ipc" = "ditto_polars.recorders:ipc"
+"polars.csv" = "ditto_polars.recorders:csv"
+"polars.ndjson" = "ditto_polars.recorders:ndjson"
+
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[tool.hatch.build]
+targets.wheel.packages = ["src/ditto_polars"]
+targets.sdist.only-include = ["src", "README.md", "LICENSE", "hatch_build.py"]
+
+# hatch_build.py adds pytest-ditto>=<this version>,<3 to these.
+[tool.hatch.metadata.hooks.custom]
+dependencies = [
+    "polars>=1.0",
+]
+
+# Versioned in lockstep with pytest-ditto, from the same git tag.
+[tool.hatch.version]
+source = "code"
+path = "../../version_builder.py"
+expression = "_version()"
+
+
+[tool.pytest.ini_options]
+minversion = "8.3"
+testpaths = "tests/ci"
+addopts = [
+  "-lv",
+  "--tb=short",
+  "--color=yes",
+  "--code-highlight=yes",
+  "--junit-xml=.pytest/test-results.xml",
+]
+junit_family = "xunit2"
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]

pytest_ditto_polars-2.0.0rc1/src/ditto_polars/recorders.py

@@ -0,0 +1,56 @@
+import io
+
+import polars as pl
+
+from ditto.recorders import Recorder
+
+
+__all__ = ("parquet", "ipc", "csv", "ndjson")
+
+
+def _parquet_dumps(data: pl.DataFrame) -> bytes:
+    buffer = io.BytesIO()
+    data.write_parquet(buffer)
+    return buffer.getvalue()
+
+
+def _parquet_loads(raw: bytes) -> pl.DataFrame:
+    return pl.read_parquet(raw)
+
+
+parquet: Recorder[pl.DataFrame] = Recorder(dumps=_parquet_dumps, loads=_parquet_loads)
+
+
+def _ipc_dumps(data: pl.DataFrame) -> bytes:
+    buffer = io.BytesIO()
+    data.write_ipc(buffer)
+    return buffer.getvalue()
+
+
+def _ipc_loads(raw: bytes) -> pl.DataFrame:
+    return pl.read_ipc(raw)
+
+
+ipc: Recorder[pl.DataFrame] = Recorder(dumps=_ipc_dumps, loads=_ipc_loads)
+
+
+def _csv_dumps(data: pl.DataFrame) -> bytes:
+    return data.write_csv().encode("utf-8")
+
+
+def _csv_loads(raw: bytes) -> pl.DataFrame:
+    return pl.read_csv(raw)
+
+
+csv: Recorder[pl.DataFrame] = Recorder(dumps=_csv_dumps, loads=_csv_loads)
+
+
+def _ndjson_dumps(data: pl.DataFrame) -> bytes:
+    return data.write_ndjson().encode("utf-8")
+
+
+def _ndjson_loads(raw: bytes) -> pl.DataFrame:
+    return pl.read_ndjson(raw)
+
+
+ndjson: Recorder[pl.DataFrame] = Recorder(dumps=_ndjson_dumps, loads=_ndjson_loads)