deepdiff-rs 0.3.0__tar.gz → 0.4.0__tar.gz

{deepdiff_rs-0.3.0 → deepdiff_rs-0.4.0}/Cargo.lock

@@ -127,7 +127,7 @@ checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
 [[package]]
 name = "onix-cli"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "onix-core",
  "serde_json",
@@ -135,7 +135,7 @@ dependencies = [
 
 [[package]]
 name = "onix-core"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "proptest",
  "serde",
@@ -145,7 +145,7 @@ dependencies = [
 
 [[package]]
 name = "onix-py"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "onix-core",
  "pyo3",

{deepdiff_rs-0.3.0 → deepdiff_rs-0.4.0}/Cargo.toml

@@ -3,7 +3,7 @@ resolver = "3"
 members = ["crates/onix-core", "crates/onix-py"]
 
 [workspace.package]
-version = "0.3.0"
+version = "0.4.0"
 edition = "2024"
 license = "MIT"
 

{deepdiff_rs-0.3.0 → deepdiff_rs-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepdiff-rs
-Version: 0.3.0
+Version: 0.4.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Rust
 Classifier: License :: OSI Approved :: MIT License
@@ -17,7 +17,9 @@ Project-URL: Repository, https://github.com/ksco92/onix
 # deepdiff-rs
 
 [![CI](https://img.shields.io/github/actions/workflow/status/ksco92/onix/check.yml?branch=main&label=CI)](https://github.com/ksco92/onix/actions/workflows/check.yml)
+[![coverage](https://codecov.io/gh/ksco92/onix/branch/main/graph/badge.svg)](https://codecov.io/gh/ksco92/onix)
 [![PyPI](https://img.shields.io/pypi/v/deepdiff-rs.svg)](https://pypi.org/project/deepdiff-rs/)
+[![downloads](https://img.shields.io/pypi/dm/deepdiff-rs.svg)](https://pypi.org/project/deepdiff-rs/)
 [![license](https://img.shields.io/github/license/ksco92/onix.svg)](LICENSE)
 [![last commit](https://img.shields.io/github/last-commit/ksco92/onix.svg)](https://github.com/ksco92/onix/commits/main)
 
@@ -25,7 +27,7 @@ Project-URL: Repository, https://github.com/ksco92/onix
 
 `deepdiff-rs` reads live Python objects (or JSON) and produces the exact same report [DeepDiff](https://github.com/seperman/deepdiff) does at `verbose_level=2`, so it slots into code that already parses DeepDiff output while running dramatically faster on large or deeply nested inputs.
 
-Status (September 2026): pre-alpha proof of concept. Ordered and `ignore_order` diffing are complete, differentially tested against real DeepDiff 9.1.0, and [benchmarked](perf/RESULTS.md); `deepdiff-rs` is published to PyPI, the `onix` CLI builds and runs from source, and nothing is on crates.io yet.
+Status (September 2026): `deepdiff-rs` 0.x is live on PyPI (Python 3.9+, wheels for Linux x86_64/aarch64, macOS arm64/x86_64, and Windows x64, plus an sdist); the `onix` CLI builds from source, and nothing is on crates.io yet. Ordered and `ignore_order` diffing are complete, differentially tested against real DeepDiff 9.1.0, and [benchmarked](perf/RESULTS.md). It is 0.x, not stable or 1.0: the API may still change before 1.0.
 
 ## Table of contents
 
@@ -112,10 +114,15 @@ Pass `--ignore-order` to compare every list by value instead of by position, mir
 ## Known limitations
 
 - Only the core diff is implemented: `exclude_paths`, `significant_digits`, custom operators, `verbose_level != 2`, and delta/patch are not (yet) supported.
-- Supported value types are `None`, `bool`, `int`, `float`, `str`, `dict` (with `str` keys), and `list`; `int`s must fit in `i64`/`u64`, `float`s must be finite, and anything else (tuple, set, date, custom object, non-`str` dict key) raises `TypeError` or `ValueError` naming the exact path it was found at. See [`crates/onix-py/src/convert.rs`](crates/onix-py/src/convert.rs).
+- Supported value types are `None`, `bool`, `int`, `float`, `str`, `dict` (with `str` keys), `list`, `tuple`, `set`, `frozenset`, `datetime.datetime`, and `datetime.date`; a `set`/`frozenset` member may be any of these except a `list`, `dict` or `set`, matching Python's own hashability rule, transitively through whatever the member nests. `int`s must fit in `i64`/`u64`, `float`s must be finite, and anything else — `time`, `timedelta`, a non-`str` dict key, a custom object, an arbitrary-precision `int`, or a non-finite `float` — raises `TypeError`/`ValueError` naming the exact path it was found at. The **Datetimes** and **Sets** bullets below cover the deliberate divergences for those two types. See [`crates/onix-py/src/convert.rs`](crates/onix-py/src/convert.rs) and [`tests/golden/README.md`](tests/golden/README.md).
+- A subclass of a supported type (a `tuple`, `set` or `frozenset` subclass including `namedtuple`, a `datetime`/`date` subclass such as pandas' `Timestamp`) raises `TypeError` rather than being diffed as its base type, because DeepDiff reports each value's own type name. A `type_changes` entry's `old_type`/`new_type` are type *names* in `to_dict()`, where DeepDiff returns the type objects. Both are described in [`tests/golden/README.md`](tests/golden/README.md).
+- **Datetimes** compare by instant, with a naive value read as UTC, matching DeepDiff. A changed pair is reported normalized to UTC (`to_json()` renders `...+00:00`, `to_dict()` returns UTC-aware `datetime`s); everywhere else a datetime keeps its raw value. Three deliberate departures: `to_json()` renders a `date` as `YYYY-MM-DD` where DeepDiff's own `to_json()` raises `TypeError` (a documented superset); a `zoneinfo`/`pytz` tzinfo comes back from `to_dict()` as a fixed-offset `datetime.timezone` carrying the offset it was in force at, not the original zone object; and a set holding both a naive and an aware value at one instant reports both as members, where DeepDiff's own digest cache can report only one (see [`crates/onix-py/src/convert.rs`](crates/onix-py/src/convert.rs)). Comparing two datetimes whose UTC form would leave year 1..=9999 raises `ValueError` naming the path, where DeepDiff raises `OverflowError`; under `ignore_order` DeepDiff's hasher normalizes every datetime and so raises for such a value even when it is only added, removed, or shuffled, where onix hashes by instant and reports it normally (see [`tests/golden/README.md`](tests/golden/README.md)). `truncate_datetime`, `time` and `timedelta` are not supported. The normalized-versus-raw split is documented in [`tests/golden/README.md`](tests/golden/README.md).
+- **Sets** are diffed deterministically, where DeepDiff's own answers depend on the order the running process happens to iterate a set in (hash order, and `PYTHONHASHSEED`-dependent for `str` members) or on how its digest cache/computation handles a tuple, frozenset, or calendar member independently of Python's own `==`. Each consequence — entry order, which member of an equality class is reported, set-versus-sequence coercion, and a tuple/frozenset member's own (positional, not order-/repetition-insensitive) matching rule — is shown with both tools' output in [`tests/golden/README.md`](tests/golden/README.md)'s "Set iteration order" section. A report holding a `frozenset` value also serializes to JSON here, where DeepDiff's own `to_json()` raises `TypeError` — a superset, not a difference in the findings.
+- Two distinct `str` values that differ only in lone surrogates (`'\ud800'` and `'\udc00'`) convert to the same string, so a set holding both loses a member and with it a finding. Tracked as [issue #27](https://github.com/ksco92/onix/issues/27).
+- A `str` inside a `tuple` or `frozenset` set item is rendered with Python's `repr()`, which escapes every non-printable character; onix escapes those below `U+0100` (the complete set in that range) and passes higher non-printable code points through literally, since escaping them would mean carrying a Unicode category table. Exact for all of ASCII and all printable text. See [`crates/onix-core/src/path.rs`](crates/onix-core/src/path.rs).
 - Adversarially deep input raises `MaxDepthError` instead of crashing: the default `max_depth` is 512 and the hard ceiling is `MAX_DEPTH_CEILING` (20,000). See [`crates/onix-py/src/guard.rs`](crates/onix-py/src/guard.rs).
 - `ignore_order` pairing is `O(N^2)` in unpaired elements per side and carries a polynomial cost in both time and memory with input depth; it has no `max_passes`/`max_diffs` cutoff, so bound the size and depth of untrusted input yourself. See [`crates/onix-core/src/ignore_order/mod.rs`](crates/onix-core/src/ignore_order/mod.rs).
-- Output is byte-identical to DeepDiff except for one boundary case: integers past `2^53` (the limit of exact `f64` representation) inside ordered scalar lists. See [`tests/golden/README.md`](tests/golden/README.md).
+- Output is byte-identical to DeepDiff except for the cases listed above and two path-rendering quirks; [`tests/golden/README.md`](tests/golden/README.md) enumerates every accepted exception, including integers past `2^53` (the limit of exact `f64` representation) inside ordered scalar lists and `ignore_order` pairing among naive datetimes, which DeepDiff ranks using the *process's local timezone* while onix reads a naive value as UTC everywhere.
 
 ## Performance
 
@@ -162,14 +169,14 @@ Both reports carry their full methodology, fairness rules, and the reproduce com
 
 **Python API.** The public surface is `DeepDiff`, `diff_json`, `MaxDepthError`, and `MAX_DEPTH_CEILING`.
 
-- `DeepDiff(t1, t2, ignore_order=False, max_depth=None)`: diffs two live Python objects; `.to_json()` returns the DeepDiff-compatible JSON string, `.to_dict()` the same report as a dict, and the instance is falsy when there is no difference.
+- `DeepDiff(t1, t2, ignore_order=False, max_depth=None)`: diffs two live Python objects of supported value types — `None`, `bool`, `int`, `float`, `str`, `dict` (with `str` keys), `list`, `tuple`, `set`, `frozenset`, `datetime.datetime`, and `datetime.date` (see [Known limitations](#known-limitations) for the exact restrictions and exclusions); `.to_json()` returns the DeepDiff-compatible JSON string, `.to_dict()` the same report as a dict — with Python types preserved, so a value the diff found in a `tuple`, `set` or `frozenset` comes back as one and a `datetime`/`date` comes back as a real `datetime`/`date` — and the instance is falsy when there is no difference. The `set_item_added`/`set_item_removed` categories are lists of path strings, each ending in the item itself (`root['a'][2]`, `root['x']`, `root[(1, 2)]`).
 - `diff_json(a, b, ignore_order=False, max_depth=None) -> str`: diffs two JSON strings entirely in Rust and returns the report as a JSON string.
 - `MaxDepthError` (a `ValueError` subclass) is raised when input exceeds `max_depth`; `MAX_DEPTH_CEILING` (20,000) is the hard upper bound on `max_depth`.
 
 **CLI.** `onix diff <a.json> <b.json> [--max-depth N] [--ignore-order] [--timing]` reads both files as JSON and prints a compact, single-line DeepDiff-compatible report to stdout (`{}` when there is no difference).
 
 - `--max-depth N` overrides the recursion-depth bound (default: the `ONIX_MAX_DEPTH` environment variable if set, else 512).
-- `--ignore-order` compares every list/tuple by hash-based matching instead of by position, mirroring `DeepDiff(..., ignore_order=True)`.
+- `--ignore-order` compares every list by hash-based matching instead of by position, mirroring `DeepDiff(..., ignore_order=True)`.
 - `--timing` prints one line of JSON (`{"parse_ns": N, "diff_ns": N}`) to stderr.
 
 Exit codes:
@@ -194,7 +201,7 @@ perf/              # cross-language benchmark harness and RESULTS.md
 
 ## Contributing
 
-This is a pre-alpha proof of concept and issues and pull requests are welcome. Open an issue to report a bug, a DeepDiff divergence (include both inputs and the report each engine produces), or a question. Building from source, the quality gates, the golden corpus, benchmarking, mutation testing, and publishing are all in [CONTRIBUTING.md](CONTRIBUTING.md).
+Issues and pull requests are welcome. Open an issue to report a bug, a DeepDiff divergence (include both inputs and the report each engine produces), or a question. Building from source, the quality gates, the golden corpus, benchmarking, mutation testing, and publishing are all in [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

{deepdiff_rs-0.3.0 → deepdiff_rs-0.4.0}/README.md

@@ -1,7 +1,9 @@
 # deepdiff-rs
 
 [![CI](https://img.shields.io/github/actions/workflow/status/ksco92/onix/check.yml?branch=main&label=CI)](https://github.com/ksco92/onix/actions/workflows/check.yml)
+[![coverage](https://codecov.io/gh/ksco92/onix/branch/main/graph/badge.svg)](https://codecov.io/gh/ksco92/onix)
 [![PyPI](https://img.shields.io/pypi/v/deepdiff-rs.svg)](https://pypi.org/project/deepdiff-rs/)
+[![downloads](https://img.shields.io/pypi/dm/deepdiff-rs.svg)](https://pypi.org/project/deepdiff-rs/)
 [![license](https://img.shields.io/github/license/ksco92/onix.svg)](LICENSE)
 [![last commit](https://img.shields.io/github/last-commit/ksco92/onix.svg)](https://github.com/ksco92/onix/commits/main)
 
@@ -9,7 +11,7 @@
 
 `deepdiff-rs` reads live Python objects (or JSON) and produces the exact same report [DeepDiff](https://github.com/seperman/deepdiff) does at `verbose_level=2`, so it slots into code that already parses DeepDiff output while running dramatically faster on large or deeply nested inputs.
 
-Status (September 2026): pre-alpha proof of concept. Ordered and `ignore_order` diffing are complete, differentially tested against real DeepDiff 9.1.0, and [benchmarked](perf/RESULTS.md); `deepdiff-rs` is published to PyPI, the `onix` CLI builds and runs from source, and nothing is on crates.io yet.
+Status (September 2026): `deepdiff-rs` 0.x is live on PyPI (Python 3.9+, wheels for Linux x86_64/aarch64, macOS arm64/x86_64, and Windows x64, plus an sdist); the `onix` CLI builds from source, and nothing is on crates.io yet. Ordered and `ignore_order` diffing are complete, differentially tested against real DeepDiff 9.1.0, and [benchmarked](perf/RESULTS.md). It is 0.x, not stable or 1.0: the API may still change before 1.0.
 
 ## Table of contents
 
@@ -96,10 +98,15 @@ Pass `--ignore-order` to compare every list by value instead of by position, mir
 ## Known limitations
 
 - Only the core diff is implemented: `exclude_paths`, `significant_digits`, custom operators, `verbose_level != 2`, and delta/patch are not (yet) supported.
-- Supported value types are `None`, `bool`, `int`, `float`, `str`, `dict` (with `str` keys), and `list`; `int`s must fit in `i64`/`u64`, `float`s must be finite, and anything else (tuple, set, date, custom object, non-`str` dict key) raises `TypeError` or `ValueError` naming the exact path it was found at. See [`crates/onix-py/src/convert.rs`](crates/onix-py/src/convert.rs).
+- Supported value types are `None`, `bool`, `int`, `float`, `str`, `dict` (with `str` keys), `list`, `tuple`, `set`, `frozenset`, `datetime.datetime`, and `datetime.date`; a `set`/`frozenset` member may be any of these except a `list`, `dict` or `set`, matching Python's own hashability rule, transitively through whatever the member nests. `int`s must fit in `i64`/`u64`, `float`s must be finite, and anything else — `time`, `timedelta`, a non-`str` dict key, a custom object, an arbitrary-precision `int`, or a non-finite `float` — raises `TypeError`/`ValueError` naming the exact path it was found at. The **Datetimes** and **Sets** bullets below cover the deliberate divergences for those two types. See [`crates/onix-py/src/convert.rs`](crates/onix-py/src/convert.rs) and [`tests/golden/README.md`](tests/golden/README.md).
+- A subclass of a supported type (a `tuple`, `set` or `frozenset` subclass including `namedtuple`, a `datetime`/`date` subclass such as pandas' `Timestamp`) raises `TypeError` rather than being diffed as its base type, because DeepDiff reports each value's own type name. A `type_changes` entry's `old_type`/`new_type` are type *names* in `to_dict()`, where DeepDiff returns the type objects. Both are described in [`tests/golden/README.md`](tests/golden/README.md).
+- **Datetimes** compare by instant, with a naive value read as UTC, matching DeepDiff. A changed pair is reported normalized to UTC (`to_json()` renders `...+00:00`, `to_dict()` returns UTC-aware `datetime`s); everywhere else a datetime keeps its raw value. Three deliberate departures: `to_json()` renders a `date` as `YYYY-MM-DD` where DeepDiff's own `to_json()` raises `TypeError` (a documented superset); a `zoneinfo`/`pytz` tzinfo comes back from `to_dict()` as a fixed-offset `datetime.timezone` carrying the offset it was in force at, not the original zone object; and a set holding both a naive and an aware value at one instant reports both as members, where DeepDiff's own digest cache can report only one (see [`crates/onix-py/src/convert.rs`](crates/onix-py/src/convert.rs)). Comparing two datetimes whose UTC form would leave year 1..=9999 raises `ValueError` naming the path, where DeepDiff raises `OverflowError`; under `ignore_order` DeepDiff's hasher normalizes every datetime and so raises for such a value even when it is only added, removed, or shuffled, where onix hashes by instant and reports it normally (see [`tests/golden/README.md`](tests/golden/README.md)). `truncate_datetime`, `time` and `timedelta` are not supported. The normalized-versus-raw split is documented in [`tests/golden/README.md`](tests/golden/README.md).
+- **Sets** are diffed deterministically, where DeepDiff's own answers depend on the order the running process happens to iterate a set in (hash order, and `PYTHONHASHSEED`-dependent for `str` members) or on how its digest cache/computation handles a tuple, frozenset, or calendar member independently of Python's own `==`. Each consequence — entry order, which member of an equality class is reported, set-versus-sequence coercion, and a tuple/frozenset member's own (positional, not order-/repetition-insensitive) matching rule — is shown with both tools' output in [`tests/golden/README.md`](tests/golden/README.md)'s "Set iteration order" section. A report holding a `frozenset` value also serializes to JSON here, where DeepDiff's own `to_json()` raises `TypeError` — a superset, not a difference in the findings.
+- Two distinct `str` values that differ only in lone surrogates (`'\ud800'` and `'\udc00'`) convert to the same string, so a set holding both loses a member and with it a finding. Tracked as [issue #27](https://github.com/ksco92/onix/issues/27).
+- A `str` inside a `tuple` or `frozenset` set item is rendered with Python's `repr()`, which escapes every non-printable character; onix escapes those below `U+0100` (the complete set in that range) and passes higher non-printable code points through literally, since escaping them would mean carrying a Unicode category table. Exact for all of ASCII and all printable text. See [`crates/onix-core/src/path.rs`](crates/onix-core/src/path.rs).
 - Adversarially deep input raises `MaxDepthError` instead of crashing: the default `max_depth` is 512 and the hard ceiling is `MAX_DEPTH_CEILING` (20,000). See [`crates/onix-py/src/guard.rs`](crates/onix-py/src/guard.rs).
 - `ignore_order` pairing is `O(N^2)` in unpaired elements per side and carries a polynomial cost in both time and memory with input depth; it has no `max_passes`/`max_diffs` cutoff, so bound the size and depth of untrusted input yourself. See [`crates/onix-core/src/ignore_order/mod.rs`](crates/onix-core/src/ignore_order/mod.rs).
-- Output is byte-identical to DeepDiff except for one boundary case: integers past `2^53` (the limit of exact `f64` representation) inside ordered scalar lists. See [`tests/golden/README.md`](tests/golden/README.md).
+- Output is byte-identical to DeepDiff except for the cases listed above and two path-rendering quirks; [`tests/golden/README.md`](tests/golden/README.md) enumerates every accepted exception, including integers past `2^53` (the limit of exact `f64` representation) inside ordered scalar lists and `ignore_order` pairing among naive datetimes, which DeepDiff ranks using the *process's local timezone* while onix reads a naive value as UTC everywhere.
 
 ## Performance
 
@@ -146,14 +153,14 @@ Both reports carry their full methodology, fairness rules, and the reproduce com
 
 **Python API.** The public surface is `DeepDiff`, `diff_json`, `MaxDepthError`, and `MAX_DEPTH_CEILING`.
 
-- `DeepDiff(t1, t2, ignore_order=False, max_depth=None)`: diffs two live Python objects; `.to_json()` returns the DeepDiff-compatible JSON string, `.to_dict()` the same report as a dict, and the instance is falsy when there is no difference.
+- `DeepDiff(t1, t2, ignore_order=False, max_depth=None)`: diffs two live Python objects of supported value types — `None`, `bool`, `int`, `float`, `str`, `dict` (with `str` keys), `list`, `tuple`, `set`, `frozenset`, `datetime.datetime`, and `datetime.date` (see [Known limitations](#known-limitations) for the exact restrictions and exclusions); `.to_json()` returns the DeepDiff-compatible JSON string, `.to_dict()` the same report as a dict — with Python types preserved, so a value the diff found in a `tuple`, `set` or `frozenset` comes back as one and a `datetime`/`date` comes back as a real `datetime`/`date` — and the instance is falsy when there is no difference. The `set_item_added`/`set_item_removed` categories are lists of path strings, each ending in the item itself (`root['a'][2]`, `root['x']`, `root[(1, 2)]`).
 - `diff_json(a, b, ignore_order=False, max_depth=None) -> str`: diffs two JSON strings entirely in Rust and returns the report as a JSON string.
 - `MaxDepthError` (a `ValueError` subclass) is raised when input exceeds `max_depth`; `MAX_DEPTH_CEILING` (20,000) is the hard upper bound on `max_depth`.
 
 **CLI.** `onix diff <a.json> <b.json> [--max-depth N] [--ignore-order] [--timing]` reads both files as JSON and prints a compact, single-line DeepDiff-compatible report to stdout (`{}` when there is no difference).
 
 - `--max-depth N` overrides the recursion-depth bound (default: the `ONIX_MAX_DEPTH` environment variable if set, else 512).
-- `--ignore-order` compares every list/tuple by hash-based matching instead of by position, mirroring `DeepDiff(..., ignore_order=True)`.
+- `--ignore-order` compares every list by hash-based matching instead of by position, mirroring `DeepDiff(..., ignore_order=True)`.
 - `--timing` prints one line of JSON (`{"parse_ns": N, "diff_ns": N}`) to stderr.
 
 Exit codes:
@@ -178,7 +185,7 @@ perf/              # cross-language benchmark harness and RESULTS.md
 
 ## Contributing
 
-This is a pre-alpha proof of concept and issues and pull requests are welcome. Open an issue to report a bug, a DeepDiff divergence (include both inputs and the report each engine produces), or a question. Building from source, the quality gates, the golden corpus, benchmarking, mutation testing, and publishing are all in [CONTRIBUTING.md](CONTRIBUTING.md).
+Issues and pull requests are welcome. Open an issue to report a bug, a DeepDiff divergence (include both inputs and the report each engine produces), or a question. Building from source, the quality gates, the golden corpus, benchmarking, mutation testing, and publishing are all in [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

deepdiff_rs-0.4.0/crates/onix-core/src/datetime.rs

@@ -0,0 +1,437 @@
+//! The two calendar values [`crate::Value`] carries beyond JSON's own
+//! shapes: [`Date`] (a Python `datetime.date`) and [`DateTime`] (a Python
+//! `datetime.datetime`, naive or with a fixed UTC offset).
+//!
+//! # Representation
+//!
+//! Both hold plain wall-clock fields — a [`Date`] is a year/month/day, a
+//! [`DateTime`] adds hour/minute/second/microsecond plus an optional UTC
+//! offset in whole seconds (`None` is Python's *naive* datetime). Nothing
+//! here needs a calendar crate: the only arithmetic the engine performs is
+//! civil-date to day-number conversion in both directions
+//! ([`Date::ordinal`] and [`Date::from_ordinal`], Howard Hinnant's
+//! `days_from_civil`/`civil_from_days`), which is a few lines of integer
+//! math and no lookup tables.
+//!
+//! # Comparison: by instant, naive as UTC
+//!
+//! `DeepDiff` compares two datetimes by *instant*, after normalizing each
+//! through `helper.py::datetime_normalize`: an aware value is converted with
+//! `astimezone(timezone.utc)`, a naive one is *stamped* with UTC
+//! (`replace(tzinfo=utc)`) rather than interpreted in local time. So
+//! `datetime(2024, 1, 1, 10)` and `datetime(2024, 1, 1, 10, tzinfo=utc)` are
+//! one instant, and `10:00+00:00` equals `12:00+02:00`. [`DateTime::instant`]
+//! is that rule as one integer, and [`DateTime::to_utc`] is
+//! `datetime_normalize` itself.
+//!
+//! Two [`Date`]s compare by value, and a [`Date`] never equals a
+//! [`DateTime`] — matching Python, where `date(2024, 1, 1) ==
+//! datetime(2024, 1, 1)` is `False` in both directions
+//! (`datetime.__eq__` returns `False`, not `NotImplemented`, for a plain
+//! `date`, and its subclass position gives it first refusal).
+//!
+//! # Rendering
+//!
+//! [`Date::isoformat`] and [`DateTime::isoformat`] reproduce Python's own
+//! `isoformat()` byte for byte: microseconds only when non-zero, an offset
+//! suffix only when the value is aware, and that suffix widening from
+//! `+HH:MM` to `+HH:MM:SS` when the offset is not a whole number of minutes.
+//! `DeepDiff`'s `to_json()` renders a datetime through exactly this method
+//! (`serialization.py`'s `JSON_CONVERTOR` maps `datetime.datetime` to
+//! `lambda x: x.isoformat()`); it has no entry for `date` at all and raises
+//! `TypeError` on one, which this crate renders as `YYYY-MM-DD` instead — a
+//! documented superset, see `tests/golden/README.md`.
+
+use std::fmt::Write as _;
+
+/// Microseconds in one second.
+const MICROS_PER_SECOND: i64 = 1_000_000;
+/// Seconds in one day.
+pub(crate) const SECONDS_PER_DAY: i64 = 86_400;
+/// Days from `0001-01-01` to the Unix epoch — the shift between Python's
+/// `date.toordinal()` origin and this module's civil-date arithmetic.
+const DAYS_FROM_YEAR_ONE_TO_EPOCH: i64 = 719_162;
+/// The first year Python's `date`/`datetime` can represent.
+const MIN_YEAR: i32 = 1;
+/// The last year Python's `date`/`datetime` can represent.
+const MAX_YEAR: i32 = 9999;
+/// `Date::new(MIN_YEAR, 1, 1).ordinal()`, i.e. Python's `date.min.toordinal()`.
+const MIN_ORDINAL: i64 = 1;
+/// `Date::new(MAX_YEAR, 12, 31).ordinal()`, i.e. Python's `date.max.toordinal()`.
+const MAX_ORDINAL: i64 = 3_652_059;
+
+/// A Python `datetime.date`: a proleptic-Gregorian year, month and day.
+///
+/// # Examples
+///
+/// ```
+/// use onix_core::datetime::Date;
+///
+/// let date = Date::new(2024, 2, 29).expect("2024 is a leap year");
+/// assert_eq!(date.isoformat(), "2024-02-29");
+/// assert!(Date::new(2023, 2, 29).is_none());
+/// ```
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct Date {
+    year: i32,
+    month: u8,
+    day: u8,
+}
+
+impl Date {
+    /// Builds a date, returning `None` unless `year`/`month`/`day` are a real
+    /// calendar date (leap years included) inside Python's own year range,
+    /// `1..=9999`. An out-of-range month has no days at all
+    /// (`days_in_month` returns `0` for one), so the `day` bound rejects it
+    /// without a separate month check.
+    ///
+    /// Enforcing the year range here is what lets every other method on this
+    /// type be total: the ordinal arithmetic stays far inside [`i64`], and
+    /// the field widths in [`Date::from_ordinal`] are guaranteed.
+    #[must_use]
+    pub fn new(year: i32, month: u8, day: u8) -> Option<Self> {
+        ((MIN_YEAR..=MAX_YEAR).contains(&year) && day >= 1 && day <= days_in_month(year, month))
+            .then_some(Self { year, month, day })
+    }
+
+    /// The year.
+    #[must_use]
+    pub fn year(self) -> i32 {
+        self.year
+    }
+
+    /// The month, `1..=12`.
+    #[must_use]
+    pub fn month(self) -> u8 {
+        self.month
+    }
+
+    /// The day of the month, `1..=31`.
+    #[must_use]
+    pub fn day(self) -> u8 {
+        self.day
+    }
+
+    /// Days since `0001-01-01`, counting that day as `1` — Python's
+    /// `date.toordinal()`, which is what `DeepDiff` measures a date-pair
+    /// distance with (`distance.py::_get_date_distance`).
+    #[must_use]
+    pub fn ordinal(self) -> i64 {
+        days_from_civil(self.year, self.month, self.day) + DAYS_FROM_YEAR_ONE_TO_EPOCH + 1
+    }
+
+    /// The inverse of [`Date::ordinal`], or `None` for an ordinal outside
+    /// the representable range (`1..=3_652_059`, Python's
+    /// `date.min`/`date.max`).
+    #[must_use]
+    pub fn from_ordinal(ordinal: i64) -> Option<Self> {
+        if !(MIN_ORDINAL..=MAX_ORDINAL).contains(&ordinal) {
+            return None;
+        }
+        let (year, month, day) = civil_from_days(ordinal - DAYS_FROM_YEAR_ONE_TO_EPOCH - 1);
+
+        Some(Self { year, month, day })
+    }
+
+    /// Python's `date.isoformat()`: `YYYY-MM-DD`.
+    #[must_use]
+    pub fn isoformat(self) -> String {
+        format!("{:04}-{:02}-{:02}", self.year, self.month, self.day)
+    }
+
+    /// Python's `str(date)`, which for a date is exactly its
+    /// [`isoformat`](Date::isoformat) — the two differ only for a datetime.
+    /// See [`DateTime::python_str`] for why `str()` is worth a method of its
+    /// own at all.
+    #[must_use]
+    pub fn python_str(self) -> String {
+        self.isoformat()
+    }
+}
+
+/// A Python `datetime.datetime`: a [`Date`] plus a wall-clock time to
+/// microsecond precision, and an optional fixed UTC offset in whole seconds
+/// (`None` is a *naive* datetime).
+///
+/// See the [module documentation](self) for the instant-comparison rule and
+/// the exact `isoformat()` reproduction.
+///
+/// # Examples
+///
+/// ```
+/// use onix_core::datetime::{Date, DateTime};
+///
+/// let date = Date::new(2024, 1, 1).expect("a real date");
+/// let naive = DateTime::new(date, 10, 0, 0, 0, None).expect("in range");
+/// let aware = DateTime::new(date, 12, 0, 0, 0, Some(2 * 3600)).expect("in range");
+///
+/// assert_eq!(naive.isoformat(), "2024-01-01T10:00:00");
+/// assert_eq!(aware.isoformat(), "2024-01-01T12:00:00+02:00");
+/// // Naive counts as UTC, so these are the same instant.
+/// assert_eq!(naive.instant(), aware.instant());
+/// ```
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct DateTime {
+    date: Date,
+    hour: u8,
+    minute: u8,
+    second: u8,
+    microsecond: u32,
+    utc_offset_seconds: Option<i32>,
+}
+
+/// The exclusive bound Python puts on a `timezone` offset: strictly less
+/// than one day, in either direction.
+const SECONDS_PER_DAY_U32: u32 = 86_400;
+
+impl DateTime {
+    /// Builds a datetime, returning `None` if the time fields are out of
+    /// range (`hour <= 23`, `minute`/`second <= 59`, `microsecond <=
+    /// 999_999`) or the offset is not strictly within ±1 day — the same
+    /// bounds Python's own `datetime`/`timezone` constructors enforce.
+    #[must_use]
+    pub fn new(
+        date: Date,
+        hour: u8,
+        minute: u8,
+        second: u8,
+        microsecond: u32,
+        utc_offset_seconds: Option<i32>,
+    ) -> Option<Self> {
+        let in_range = hour <= 23
+            && minute <= 59
+            && second <= 59
+            && microsecond <= 999_999
+            && utc_offset_seconds.is_none_or(|offset| offset.unsigned_abs() < SECONDS_PER_DAY_U32);
+
+        in_range.then_some(Self {
+            date,
+            hour,
+            minute,
+            second,
+            microsecond,
+            utc_offset_seconds,
+        })
+    }
+
+    /// The calendar date part.
+    #[must_use]
+    pub fn date(self) -> Date {
+        self.date
+    }
+
+    /// The hour, `0..=23`.
+    #[must_use]
+    pub fn hour(self) -> u8 {
+        self.hour
+    }
+
+    /// The minute, `0..=59`.
+    #[must_use]
+    pub fn minute(self) -> u8 {
+        self.minute
+    }
+
+    /// The second, `0..=59`.
+    #[must_use]
+    pub fn second(self) -> u8 {
+        self.second
+    }
+
+    /// The microsecond, `0..=999_999`.
+    #[must_use]
+    pub fn microsecond(self) -> u32 {
+        self.microsecond
+    }
+
+    /// The fixed UTC offset in whole seconds, or `None` for a naive value.
+    #[must_use]
+    pub fn utc_offset_seconds(self) -> Option<i32> {
+        self.utc_offset_seconds
+    }
+
+    /// This value's instant, as microseconds from `1970-01-01T00:00:00Z`,
+    /// with a naive value counted as UTC — `DeepDiff`'s comparison key (see
+    /// the [module documentation](self)).
+    ///
+    /// Exact across the whole Python-representable range: year `9999`'s
+    /// microsecond count is under `2.6e17`, three orders of magnitude inside
+    /// [`i64`].
+    #[must_use]
+    pub fn instant(self) -> i64 {
+        let seconds_of_day =
+            i64::from(self.hour) * 3600 + i64::from(self.minute) * 60 + i64::from(self.second)
+                - i64::from(self.utc_offset_seconds.unwrap_or(0));
+
+        ((self.date.ordinal() - 1) * SECONDS_PER_DAY + seconds_of_day) * MICROS_PER_SECOND
+            + i64::from(self.microsecond)
+            - DAYS_FROM_YEAR_ONE_TO_EPOCH * SECONDS_PER_DAY * MICROS_PER_SECOND
+    }
+
+    /// This value normalized to UTC — `helper.py::datetime_normalize` with
+    /// the default `default_timezone=timezone.utc`, i.e. the values
+    /// `DeepDiff` puts in a `values_changed` entry for a datetime pair.
+    ///
+    /// The result is always aware with offset `0`, so two normalized values
+    /// are equal exactly when the originals are the same instant.
+    ///
+    /// Returns `None` for the one case that has no answer: an extreme aware
+    /// value whose UTC wall clock falls outside Python's own `1..=9999` year
+    /// range, by at most one day (`9999-12-31T23:00-01:00`, say). Real
+    /// `astimezone(timezone.utc)` raises `OverflowError: date value out of
+    /// range` there, and so `DeepDiff` raises rather than reporting anything.
+    ///
+    /// *When* each tool reaches that point differs, verified live. On the
+    /// ordered path only `_diff_datetime` normalizes, so both raise only when
+    /// two datetimes are actually compared. Under `ignore_order`,
+    /// `deephash.py::_prep_datetime` normalizes every datetime it hashes, so
+    /// real `DeepDiff` raises for such a value even when it is merely added,
+    /// removed, or shuffled, where onix hashes by instant (see
+    /// `crate::ignore_order`) and reports it raw.
+    #[must_use]
+    pub fn to_utc(self) -> Option<Self> {
+        let instant =
+            self.instant() + DAYS_FROM_YEAR_ONE_TO_EPOCH * SECONDS_PER_DAY * MICROS_PER_SECOND;
+        let (days, micros_of_day) = div_rem_euclid(instant, SECONDS_PER_DAY * MICROS_PER_SECOND);
+        let seconds_of_day = micros_of_day / MICROS_PER_SECOND;
+
+        #[allow(
+            clippy::cast_possible_truncation,
+            clippy::cast_sign_loss,
+            reason = "`div_rem_euclid` makes `micros_of_day` non-negative and strictly under one \
+                      day, so every component below is non-negative and inside its own field"
+        )]
+        Some(Self {
+            date: Date::from_ordinal(days + 1)?,
+            hour: (seconds_of_day / 3600) as u8,
+            minute: (seconds_of_day / 60 % 60) as u8,
+            second: (seconds_of_day % 60) as u8,
+            microsecond: (micros_of_day % MICROS_PER_SECOND) as u32,
+            utc_offset_seconds: Some(0),
+        })
+    }
+
+    /// Python's `datetime.isoformat()`: `YYYY-MM-DDTHH:MM:SS`, plus
+    /// `.ffffff` when the microsecond is non-zero and an offset suffix when
+    /// the value is aware — see the [module documentation](self).
+    #[must_use]
+    pub fn isoformat(self) -> String {
+        self.rendered('T')
+    }
+
+    /// Python's `str(datetime)`, which is `isoformat(sep=" ")` — the same
+    /// rendering with a space where the `T` goes.
+    ///
+    /// This is the one place the `str()`-versus-`isoformat()` distinction is
+    /// explained, for both calendar types. They are kept apart because they
+    /// have different jobs: `isoformat()` is what `to_json()` prints, while
+    /// `str()` is what `DeepDiff` reproduces when it tests whether a
+    /// `type_changes` pair's new value is reachable by coercion
+    /// (`model.py`'s `new_t1 = new_type(change.t1)`), and what `DeepHash`
+    /// embeds in a `frozenset` member's digest.
+    #[must_use]
+    pub fn python_str(self) -> String {
+        self.rendered(' ')
+    }
+
+    /// The shared rendering behind [`isoformat`](DateTime::isoformat) and
+    /// [`python_str`](DateTime::python_str), which differ only in the
+    /// separator between the date and the time.
+    fn rendered(self, separator: char) -> String {
+        let mut rendered = format!(
+            "{}{separator}{:02}:{:02}:{:02}",
+            self.date.isoformat(),
+            self.hour,
+            self.minute,
+            self.second
+        );
+
+        if self.microsecond != 0 {
+            let _ = write!(rendered, ".{:06}", self.microsecond);
+        }
+
+        if let Some(offset) = self.utc_offset_seconds {
+            let sign = if offset < 0 { '-' } else { '+' };
+            let magnitude = i64::from(offset.abs());
+            let _ = write!(
+                rendered,
+                "{sign}{:02}:{:02}",
+                magnitude / 3600,
+                magnitude / 60 % 60
+            );
+            if magnitude % 60 != 0 {
+                let _ = write!(rendered, ":{:02}", magnitude % 60);
+            }
+        }
+
+        rendered
+    }
+}
+
+/// Floored division and its remainder, both taken toward negative infinity —
+/// the split [`DateTime::to_utc`] needs to turn a possibly-negative
+/// microsecond count into a whole day plus a non-negative offset into it.
+pub(crate) fn div_rem_euclid(value: i64, divisor: i64) -> (i64, i64) {
+    (value.div_euclid(divisor), value.rem_euclid(divisor))
+}
+
+/// Days from `1970-01-01` to `year-month-day`, negative before the epoch —
+/// Howard Hinnant's `days_from_civil`, valid for any proleptic-Gregorian
+/// date.
+fn days_from_civil(year: i32, month: u8, day: u8) -> i64 {
+    let year = i64::from(year) - i64::from(month <= 2);
+    let era = year.div_euclid(400);
+    let year_of_era = year - era * 400;
+    let month = i64::from(month);
+    let day_of_year = (153 * (month + if month > 2 { -3 } else { 9 }) + 2) / 5 + i64::from(day) - 1;
+    let day_of_era = year_of_era * 365 + year_of_era / 4 - year_of_era / 100 + day_of_year;
+
+    era * 146_097 + day_of_era - 719_468
+}
+
+/// The inverse of [`days_from_civil`] — Hinnant's `civil_from_days`.
+#[allow(
+    clippy::cast_possible_truncation,
+    clippy::cast_sign_loss,
+    reason = "the day count this crate reaches spans years 1..=9999, so the year fits an i32 \
+              and the month and day are always positive and inside a u8"
+)]
+fn civil_from_days(days: i64) -> (i32, u8, u8) {
+    let days = days + 719_468;
+    let era = days.div_euclid(146_097);
+    let day_of_era = days - era * 146_097;
+    let year_of_era =
+        (day_of_era - day_of_era / 1460 + day_of_era / 36_524 - day_of_era / 146_096) / 365;
+    let year = year_of_era + era * 400;
+    let day_of_year = day_of_era - (365 * year_of_era + year_of_era / 4 - year_of_era / 100);
+    let month_position = (5 * day_of_year + 2) / 153;
+    let day = day_of_year - (153 * month_position + 2) / 5 + 1;
+    let month = month_position + if month_position < 10 { 3 } else { -9 };
+
+    (
+        (year + i64::from(month <= 2)) as i32,
+        month as u8,
+        day as u8,
+    )
+}
+
+/// The number of days in `month` of `year`, or `0` if `month` is not a real
+/// month — which is what makes it [`Date::new`]'s only bound.
+fn days_in_month(year: i32, month: u8) -> u8 {
+    match month {
+        1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
+        4 | 6 | 9 | 11 => 30,
+        2 if is_leap_year(year) => 29,
+        2 => 28,
+        _ => 0,
+    }
+}
+
+/// Whether `year` is a proleptic-Gregorian leap year.
+fn is_leap_year(year: i32) -> bool {
+    year % 4 == 0 && (year % 100 != 0 || year % 400 == 0)
+}
+
+#[cfg(test)]
+#[path = "datetime_tests.rs"]
+mod tests;