patch last docs/test gaps

Author: ariebovenberg

.agents/skills/rust-ffi/SKILL.md

@@ -114,7 +114,7 @@ let relative_to = handle_one_kwarg("total", state.str_relative_to, kwargs)?;
 ```
 
 **Building deltas from kwargs (shift/add/subtract methods):**
-Use `common::shift::parse_datetime_shift_kwargs()` for full datetime units or
+Use `common::shift_args::parse_datetime_shift_kwargs()` for full datetime units or
 `parse_calendar_shift_kwargs()` for calendar-only units. They return a typed
 `DateTimeShift` or `CalendarShift`; the datetime parser's callback retains
 class-specific kwargs such as `disambiguate` and warning suppression. For a
@@ -161,8 +161,8 @@ perform Unicode comparison before later subsets have had their pointer-equality
   Has `.in_single_unit()` and `.in_exact_units()` for unit decomposition, and owns the pure
   `parse_iso()` implementation; map its parse errors to Python exceptions in the binding.
 - Unit types name their role: `fmt::Precision`, `round::RoundUnit`, and
-  `CalendarUnit`/`DifferenceUnit`/`ExactUnit` in `common::math`. Keep these domains distinct unless
-  their parsing and behavior are demonstrably identical. Keep `common::fmt` free of Python
+  `CalendarUnit`/`DifferenceUnit`/`ExactUnit` in `domain::difference`. Keep these domains distinct
+  unless their parsing and behavior are demonstrably identical. Keep `common::fmt` free of Python
   argument parsing; `common::format_args` adapts Python `format_iso` arguments to its pure types.
 - **ItemizedDelta/ItemizedDateDelta** use `DeltaField<T>` with the integer type's `MIN` value as
   the UNSET sentinel. `DeltaField` has custom `Debug` showing `<unset>` for sentinel values and

CHANGELOG.md

@@ -24,6 +24,11 @@
   `ItemizedDateDelta` values from Rust-backed operations.
 - Drop support for PyPy 3.10. PyPy 3.11 remains supported.
 
+**Fixed**
+
+- Fixed an overflow when validating extremely large rounding increments in the
+  Rust extension. They now raise `ValueError`.
+
 ## 0.10.3 (2026-07-17)
 
 - Fixed the pure Python implementation accepting invalid basic-format times

docs/faq.md

@@ -362,27 +362,27 @@ out [Ry](https://pypi.org/project/ry/).
 ## Why aren't all operators supported for all types?
 
 Some operators may be conspicuously missing for certain types, even
-though they could be implemented. For example:
+though they could be implemented. Whenever provides operators where their
+meaning is useful and can be documented clearly.
+
+For example, dates and datetimes support applying itemized deltas with `+`
+and `-`:
 
 ```python
->>> Date(2024, 1, 31) + ItemizedDateDelta(months=1) # Error
+>>> Date(2024, 1, 31) + ItemizedDateDelta(months=1)
+Date("2024-02-29")
 ```
 
-This is because operators are only implemented where they are *mathematically
-intuitive*. For example, when `a + (b + c) = (a + b) + c` and `(a + b) - b = a`.
-This isn't the case when working with months
-or years, since adding a month to January 31st gives a different result
-than adding a month to February 28th. To avoid confusion, these
-operators are simply not implemented. There are methods like
-`add()` and `subtract()` that can be used
-instead, which don't come with the same mathematical expectations:
+These operators use the same calendar clamping rules as `add()` and
+`subtract()`. As a result, adding and then subtracting the same delta is not
+always reversible. Itemized deltas also support `+` and `-` with each other;
+these perform field-wise composition and warn by default because applying the
+combined delta may differ from applying its parts sequentially.
 
-```python
->>> Date(2024, 1, 31).add(months=1)
->>> Date(2024, 1, 31).add(ItemizedDateDelta(months=1))
-```
+Operators without a generally useful interpretation remain unavailable. For
+example, itemized deltas cannot be multiplied or divided.
 
-For the same reason, the `-` operator between two datetimes always
+The `-` operator between two datetimes always
 returns a {class}`~whenever.TimeDelta`—an exact elapsed duration where
 subtraction is unambiguous.
 If you need a difference in calendar units like years, months, or days,

docs/reference/deltas.md

@@ -60,8 +60,8 @@ and their key differences. Click on the features to learn more about them.
 | {ref}`Convert to units <delta-in-units>`     | {meth}`~TimeDelta.in_units` | {meth}`~ItemizedDateDelta.in_units` [^1] | {meth}`~ItemizedDelta.in_units` [^1] |
 | {ref}`Summing into one unit <delta-total>`     | {meth}`~TimeDelta.total` | {meth}`~ItemizedDateDelta.total` [^1] | {meth}`~ItemizedDelta.total` [^1] |
 | {ref}`Comparison <delta-cmp>`           | {meth}`> <TimeDelta.__gt__>` , {meth}`< <TimeDelta.__lt__>` , {meth}`>= <TimeDelta.__ge__>` , {meth}`<= <TimeDelta.__le__>` | n/a                   | n/a                    |
-| {ref}`Addition/subtraction <delta-add-sub>`  | {meth}`~TimeDelta.add` / {meth}`~TimeDelta.subtract` | {meth}`~ItemizedDateDelta.add` / {meth}`~ItemizedDateDelta.subtract` [^1] | {meth}`~ItemizedDelta.add` / {meth}`~ItemizedDelta.subtract` [^1] |
-| {ref}`Operators <delta-operators>` | {meth}`+ <TimeDelta.__add__>` , {meth}`- <TimeDelta.__sub__>` , {meth}`* <TimeDelta.__mul__>` , {meth}`/ <TimeDelta.__truediv__>` , {meth}`// <TimeDelta.__floordiv__>` , {meth}`% <TimeDelta.__mod__>` | n/a                   | n/a                    |
+| {ref}`Addition/subtraction <delta-add-sub>`  | {meth}`~TimeDelta.add` / {meth}`~TimeDelta.subtract` | {meth}`~ItemizedDateDelta.add` / {meth}`~ItemizedDateDelta.subtract` | {meth}`~ItemizedDelta.add` / {meth}`~ItemizedDelta.subtract` |
+| {ref}`Operators <delta-operators>` | {meth}`+ <TimeDelta.__add__>` , {meth}`- <TimeDelta.__sub__>` , {meth}`* <TimeDelta.__mul__>` , {meth}`/ <TimeDelta.__truediv__>` , {meth}`// <TimeDelta.__floordiv__>` , {meth}`% <TimeDelta.__mod__>` | `+`, `-` | `+`, `-` |
 | {ref}`Rounding <delta-rounding>` | {meth}`~TimeDelta.round`  | with {meth}`~ItemizedDateDelta.in_units`          | with {meth}`~ItemizedDelta.in_units`          |
 | Applies to...     | {class}`ZonedDateTime` <br> {class}`OffsetDateTime` <br> {class}`PlainDateTime` <br> {class}`Instant` | {class}`ZonedDateTime` <br> {class}`OffsetDateTime` <br> {class}`PlainDateTime` <br> {class}`Date` | {class}`ZonedDateTime` <br> {class}`OffsetDateTime` <br> {class}`PlainDateTime` |
 | Similar to... | {class}`~datetime.timedelta` | {class}`~collections.Counter` | {class}`~collections.Counter` |
@@ -282,10 +282,10 @@ of the two deltas:
 TimeDelta("PT3h30m")
 ```
 
-"Itemized" deltas do require a relative date or datetime context
+"Itemized" delta composition can use a relative date or datetime context
 to resolve calendar units when adding or subtracting.
-For example, adding "1 month" to "30 days" requires knowing the starting date
-to determine the resulting duration:
+For example, the calendar-aware composition of "1 month" and "30 days"
+depends on the starting date:
 
 ```python
 >>> one_month = ItemizedDateDelta(months=1)

tests/test_plain_datetime.py

@@ -1714,6 +1714,21 @@ def test_century_leap(self):
 
 
 class TestStartOf:
+    @pytest.mark.parametrize(
+        ("unit", "expected"),
+        [
+            ("year", PlainDateTime(2024, 1, 1)),
+            ("day", PlainDateTime(2024, 8, 15)),
+            ("hour", PlainDateTime(2024, 8, 15, 14)),
+        ],
+    )
+    def test_str_subclass(self, unit, expected):
+        class StrSubclass(str):
+            pass
+
+        dt = PlainDateTime(2024, 8, 15, 14, 30, 45, nanosecond=123)
+        assert dt.start_of(StrSubclass(unit)) == expected  # type: ignore[arg-type]
+
     def test_year(self):
         dt = PlainDateTime(2024, 8, 15, 14, 30, 45, nanosecond=123)
         result = dt.start_of("year")