Correct _datetime_from_iso8601 docstring to match two-step fallback

The docstring enumerated three fallback steps (datetime → time →
date) but the body only runs two (datetime.fromisoformat then
time.fromisoformat); there is no third date.fromisoformat call.
Bare YYYY-MM-DD input lands on step 1 — Python 3.11+'s
datetime.fromisoformat widened to accept every shape
date.fromisoformat accepts, including the bare date.

A secondary paragraph reinforced the same inaccuracy by claiming
"the decoder's fallback path parses the string with
datetime.date.fromisoformat". Rewrite both to describe the actual
two-step shape and explain that step 1's auto-widen serves the
bare-date round-trip. Also note that ordinal-date form YYYY-OOO is
rejected as a consequence of step 1 covering everything (no
upstream emits ordinals today, so the asymmetry is benign).

Documentation-only; no behaviour change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: antoineleclair

src/dqlitedbapi/types.py

@@ -519,30 +519,40 @@ def _datetime_from_iso8601(text: str) -> datetime.datetime | datetime.time | Non
     server still tolerates empty ISO8601 values. Returning None matches
     PEP 249 NULL semantics.
 
-    Tries, in order:
-
-    1. ``datetime.datetime.fromisoformat`` — ``YYYY-MM-DD HH:MM:SS[…]``
+    Two-step fallback (in order):
+
+    1. ``datetime.datetime.fromisoformat`` — covers full
+       ``YYYY-MM-DD HH:MM:SS[.ffffff][±HH:MM]`` plus bare
+       ``YYYY-MM-DD``. On Python 3.11+ ``datetime.fromisoformat``
+       widened to accept every shape ``date.fromisoformat`` accepts,
+       so a bare-date input lands here (returning midnight datetime
+       — see the date-widens paragraph below).
     2. ``datetime.time.fromisoformat`` — ``HH:MM:SS[.ffffff][±HH:MM]``,
        matching the ``_iso8601_from_time`` bind-path encoder so a
        ``datetime.time`` bound via the driver round-trips as
        ``datetime.time`` on readback rather than raising ``DataError``.
-    3. ``datetime.date.fromisoformat`` — ``YYYY-MM-DD`` (widened to
-       ``datetime.datetime`` on return; see below).
+
+    There is intentionally NO third ``date.fromisoformat`` arm — step 1
+    already covers bare ``YYYY-MM-DD`` on every supported Python.
+    Ordinal-date form ``YYYY-OOO`` (which ``date.fromisoformat``
+    accepts but ``datetime.fromisoformat`` rejects) is therefore
+    rejected here too; no upstream emits ordinal dates today, so the
+    asymmetry is benign.
 
     Naive input round-trips as naive; aware input preserves the offset.
     Python 3.11+ ``datetime.fromisoformat`` accepts a trailing ``Z``
     natively; no pre-substitution is needed.
 
     **``date`` widens to ``datetime`` on round-trip.** A ``datetime.date``
     passed to PEP 249 ``Date()`` serializes via ``isoformat()`` as
-    ``"YYYY-MM-DD"`` (no time component). The decoder's fallback path
-    parses the string with ``datetime.date.fromisoformat`` and returns
-    a ``datetime.datetime(year, month, day)`` — the value widens from
-    date to datetime. This matches pysqlite's default behaviour (stdlib
-    ``sqlite3`` with ``detect_types`` does the same widen). Callers who
-    need a strict ``date`` on readback should narrow via ``.date()`` or
-    use the SQLAlchemy ``_DqliteDate`` type that does the narrowing at
-    the ORM layer.
+    ``"YYYY-MM-DD"`` (no time component). Step 1 above parses that
+    bare-date string and returns ``datetime.datetime(year, month, day)``
+    at midnight — the value widens from date to datetime. This matches
+    pysqlite's default behaviour (stdlib ``sqlite3`` with
+    ``detect_types`` does the same widen). Callers who need a strict
+    ``date`` on readback should narrow via ``.date()`` or use the
+    SQLAlchemy ``_DqliteDate`` type that does the narrowing at the
+    ORM layer.
 
     ``datetime.time`` does NOT widen — ``HH:MM:SS`` has no date
     component so widening would require an arbitrary sentinel date.

tests/test_datetime_from_iso8601_docstring_two_step_fallback.py

@@ -0,0 +1,47 @@
+"""Doc-pin: ``_datetime_from_iso8601``'s docstring lists the two
+fallback steps that the implementation actually runs, not three.
+
+The body at ``types.py`` only tries ``datetime.datetime.fromisoformat``
+followed by ``datetime.time.fromisoformat`` and raises ``DataError``.
+There is no third ``date.fromisoformat`` arm — the bare-date case is
+served by step 1 on Python 3.11+ (``datetime.fromisoformat("YYYY-MM-DD")``
+returns midnight). The previous docstring enumerated a third step and
+asserted "the fallback path parses the string with
+``datetime.date.fromisoformat``" — neither claim was true. This pin
+locks the docstring to the actual two-step shape so future readers
+trust what's written.
+
+Documentation-only; no behaviour change.
+"""
+
+from __future__ import annotations
+
+from dqlitedbapi.types import _datetime_from_iso8601
+
+
+def test_docstring_does_not_claim_three_fallback_steps() -> None:
+    doc = _datetime_from_iso8601.__doc__ or ""
+    # The old wording numbered "3. ``datetime.date.fromisoformat``"
+    # as a fallback step that the body never runs. The new wording
+    # must not contain a numbered "3." fallback step.
+    assert "3. ``datetime.date.fromisoformat``" not in doc, (
+        "_datetime_from_iso8601 docstring still lists a numbered third "
+        "fallback step (``datetime.date.fromisoformat``) that the "
+        "implementation never runs."
+    )
+    # The old "fallback path parses the string with
+    # ``datetime.date.fromisoformat``" claim must also be gone.
+    assert "parses the string with ``datetime.date.fromisoformat``" not in doc, (
+        "_datetime_from_iso8601 docstring still asserts that the "
+        "fallback parses with ``datetime.date.fromisoformat`` — the "
+        "body has no such call (the bare-date case is handled by "
+        "step 1's auto-widen on Python 3.11+)."
+    )
+
+
+def test_docstring_enumerates_two_step_fallback() -> None:
+    doc = _datetime_from_iso8601.__doc__ or ""
+    assert "Two-step fallback" in doc or "two-step fallback" in doc, (
+        "_datetime_from_iso8601 docstring must explicitly state that "
+        "the fallback is two-step (datetime → time)."
+    )