tomlkit: handle native date objects (#708)

* tomlkit: handle native date and datetime objects

* More history

* Tweak only for dates

* Remove test?

* Improve test

* Add test

Author: Tinche

HISTORY.md

@@ -20,9 +20,14 @@ Our backwards-compatibility policy can be found [here](https://github.com/python
 - Apply the attrs converter to the default value before checking if it is equal to the attribute's value, when `omit_if_default` is true and an attrs converter is specified.
   ([#696](https://github.com/python-attrs/cattrs/pull/696))
 - Use the optional `_value_` type hint to structure and unstructure enums if present.
-  ([##699](https://github.com/python-attrs/cattrs/issues/699))
+  ([#699](https://github.com/python-attrs/cattrs/issues/699))
 - _cattrs_ now tracks performance using [codspeed](https://codspeed.io/python-attrs/cattrs).
   ([#703](https://github.com/python-attrs/cattrs/pull/703))
+- The {mod}`tomlkit <cattrs.preconf.tomlkit>` preconf converter now properly handles native `date` objects when structuring.
+  ([#707](https://github.com/python-attrs/cattrs/issues/707) [#708](https://github.com/python-attrs/cattrs/pull/708))
+- The {mod}`tomlkit <cattrs.preconf.tomlkit>` preconf converter now passes date objects directly to _tomlkit_ for unstructuring.
+  ([#707](https://github.com/python-attrs/cattrs/issues/707) [#708](https://github.com/python-attrs/cattrs/pull/708))
+
 
 ## 25.3.0 (2025-10-07)
 

docs/preconf.md

@@ -55,6 +55,9 @@ Optional install targets should match the name of the {mod}`cattrs.preconf` modu
 # Using pip
 $ pip install cattrs[ujson]
 
+# Usinv uv
+$ uv add cattrs[msgspec]
+
 # Using pdm
 $ pdm add cattrs[orjson]
 
@@ -202,4 +205,6 @@ Found at {mod}`cattrs.preconf.tomlkit`.
 
 Bytes are serialized as base 85 strings. Sets are serialized as lists, and deserialized back into sets.
 Tuples are serialized as lists, and deserialized back into tuples.
-_tomlkit_ only supports mappings with string keys so mappings will have their keys stringified before serialization, and destringified during deserialization. `date` s are serialized as ISO 8601 strings.
+_tomlkit_ only supports mappings with string keys so mappings will have their keys stringified before serialization, and destringified during deserialization.
+[`date`](https://docs.python.org/3/library/datetime.html#datetime.date) and [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) objects are passed through to be unstructured by _tomlkit_ itself.
+

src/cattrs/preconf/tomlkit.py

@@ -12,6 +12,7 @@
 
 from .._compat import is_mapping, is_subclass
 from ..converters import BaseConverter, Converter
+from ..fns import identity
 from ..strategies import configure_union_passthrough
 from . import validate_datetime, wrap
 
@@ -37,6 +38,9 @@ def configure_converter(converter: BaseConverter):
     * sets are serialized as lists
     * tuples are serializas as lists
     * mapping keys are coerced into strings when unstructuring
+
+    .. versionchanged:: NEXT
+        date objects are now passed through to tomlkit without unstructuring.
     """
     converter.register_structure_hook(bytes, lambda v, _: b85decode(v))
     converter.register_unstructure_hook(
@@ -67,10 +71,12 @@ def key_handler(k: bytes):
 
     # datetime inherits from date, so identity unstructure hook used
     # here to prevent the date unstructure hook running.
-    converter.register_unstructure_hook(datetime, lambda v: v)
+    converter.register_unstructure_hook(datetime, identity)
     converter.register_structure_hook(datetime, validate_datetime)
-    converter.register_unstructure_hook(date, lambda v: v.isoformat())
-    converter.register_structure_hook(date, lambda v, _: date.fromisoformat(v))
+    converter.register_unstructure_hook(date, identity)
+    converter.register_structure_hook(
+        date, lambda v, _: v if isinstance(v, date) else date.fromisoformat(v)
+    )
     configure_union_passthrough(
         Union[str, String, bool, int, Integer, float, Float], converter
     )

tests/test_preconf.py

@@ -719,7 +719,12 @@ def test_tomlkit(everything: Everything, detailed_validation: bool):
     converter = tomlkit_make_converter(detailed_validation=detailed_validation)
     unstructured = converter.unstructure(everything)
     raw = tomlkit_dumps(unstructured)
-    assert converter.structure(tomlkit_loads(raw), Everything) == everything
+
+    loaded = tomlkit_loads(raw)
+    # Check if we're unstructuring dates to native toml dates
+    assert isinstance(loaded["a_date"], date)
+
+    assert converter.structure(loaded, Everything) == everything
 
 
 @given(
@@ -767,6 +772,18 @@ def test_tomlkit_unions(union_and_val: tuple, detailed_validation: bool):
     assert converter.structure(val, type) == val
 
 
+def test_tomlkit_date_strings():
+    """Dates represented as strings in toml work."""
+    converter = tomlkit_make_converter()
+
+    @define
+    class A:
+        a_date: date
+
+    data = 'a_date = "2023-01-01"'
+    assert converter.loads(data, A) == A(date(2023, 1, 1))
+
+
 @given(everythings(min_int=-9223372036854775808, max_int=18446744073709551615))
 def test_cbor2(everything: Everything):
     from cbor2 import dumps as cbor2_dumps