gh-90016: Deprecate default sqlite3 adapters and converters (#94276)

Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>

3 files changed, 29 insertions, 38 deletions

diff --git a/Doc/includes/sqlite3/pysqlite_datetime.py b/Doc/includes/sqlite3/pysqlite_datetime.py
deleted file mode 100644
index 5d843f9..0000000
--- a/Doc/includes/sqlite3/pysqlite_datetime.py
+++ /dev/null
@@ -1,22 +0,0 @@
-import sqlite3
-import datetime
-
-con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES)
-cur = con.cursor()
-cur.execute("create table test(d date, ts timestamp)")
-
-today = datetime.date.today()
-now = datetime.datetime.now()
-
-cur.execute("insert into test(d, ts) values (?, ?)", (today, now))
-cur.execute("select d, ts from test")
-row = cur.fetchone()
-print(today, "=>", row[0], type(row[0]))
-print(now, "=>", row[1], type(row[1]))
-
-cur.execute('select current_date as "d [date]", current_timestamp as "ts [timestamp]"')
-row = cur.fetchone()
-print("current_date", row[0], type(row[0]))
-print("current_timestamp", row[1], type(row[1]))
-
-con.close()
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index d2997dc..a7581f2 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -1333,6 +1333,8 @@ This function can then be registered using :func:`register_adapter`.
 .. literalinclude:: ../includes/sqlite3/adapter_point_2.py
 
 
+.. _sqlite3-converters:
+
 Converting SQLite values to custom Python types
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1373,27 +1375,28 @@ The following example illustrates the implicit and explicit approaches:
 .. literalinclude:: ../includes/sqlite3/converter_point.py
 
 
-Default adapters and converters
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-There are default adapters for the date and datetime types in the datetime
-module. They will be sent as ISO dates/ISO timestamps to SQLite.
+.. _sqlite3-default-converters:
 
-The default converters are registered under the name "date" for
-:class:`datetime.date` and under the name "timestamp" for
-:class:`datetime.datetime`.
+Default adapters and converters (deprecated)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This way, you can use date/timestamps from Python without any additional
-fiddling in most cases. The format of the adapters is also compatible with the
-experimental SQLite date/time functions.
+.. note::
 
-The following example demonstrates this.
+   The default adapters and converters are deprecated as of Python 3.12.
+   Instead, use the :ref:`sqlite3-adapter-converter-recipes`
+   and tailor them to your needs.
 
-.. literalinclude:: ../includes/sqlite3/pysqlite_datetime.py
+The deprecated default adapters and converters consist of:
 
-If a timestamp stored in SQLite has a fractional part longer than 6
-numbers, its value will be truncated to microsecond precision by the
-timestamp converter.
+* An adapter for :class:`datetime.date` objects to :class:`strings <str>` in
+  `ISO 8601`_ format.
+* An adapter for :class:`datetime.datetime` objects to strings in
+  ISO 8601 format.
+* A converter for :ref:`declared <sqlite3-converters>` "date" types to
+  :class:`datetime.date` objects.
+* A converter for declared "timestamp" types to
+  :class:`datetime.datetime` objects.
+  Fractional parts will be truncated to 6 digits (microsecond precision).
 
 .. note::
 
@@ -1402,6 +1405,10 @@ timestamp converter.
    offsets in timestamps, either leave converters disabled, or register an
    offset-aware converter with :func:`register_converter`.
 
+.. deprecated:: 3.12
+
+.. _ISO 8601: https://en.wikipedia.org/wiki/ISO_8601
+
 
 .. _sqlite3-adapter-converter-recipes:
 
diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst
index 942196c..15282a7 100644
--- a/Doc/whatsnew/3.12.rst
+++ b/Doc/whatsnew/3.12.rst
@@ -135,6 +135,12 @@ Deprecated
 * :class:`typing.Hashable` and :class:`typing.Sized` aliases for :class:`collections.abc.Hashable`
   and :class:`collections.abc.Sized`. (:gh:`94309`)
 
+* The :mod:`sqlite3` :ref:`default adapters and converters
+  <sqlite3-default-converters>` are now deprecated.
+  Instead, use the :ref:`sqlite3-adapter-converter-recipes`
+  and tailor them to your needs.
+  (Contributed by Erlend E. Aasland in :gh:`90016`.)
+
 
 Pending Removal in Python 3.13
 ------------------------------