Jun 25, 2022 · May 23, 2022 · May 23, 2022 · May 23, 2022 · May 23, 2022 · May 23, 2022
diff --git a/Doc/includes/sqlite3/converter_point.py b/Doc/includes/sqlite3/converter_point.py
        return f"Point({self.x}, {self.y})"

 def adapt_point(point):
    return("%f;%f" % (point.x,point.y)).encode("utf-8")
    returnf"{point.x};{point.y}".encode("utf-8")

 def convert_point(s):
    x, y = list(map(float, s.split(b";")))
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst

 .. data:: PARSE_DECLTYPES

   Use this flag with the *detect_types*keyword of :meth:`connect` to enable
   parsing of declared types for each columnit return.
   Use this flag with the *detect_types*parameter of :meth:`connect` to enable
   parsing of declared types for each columnreturned.
   The types are declared when the database table is created.
 :mod:`sqlite3` will look up a converter function using the first word of the
 ``sqlite3`` will look up a converter function using the first word of the
   declared type as the converter dictionary key.
 The following SQL code results in the following lookups:
 For example, the following SQL code results in the following lookups:

   .. code-block:: sql


 .. data:: PARSE_COLNAMES

   Use this flag with the *detect_types*keyword of :meth:`connect` to enable
   Use this flag with the *detect_types*parameter of :meth:`connect` to enable
   parsing of column names in queries.
 :mod:`sqlite3` will look for strings containing brackets, and will look up a
   converter function using the word inside the brackets as the converter
   dictionary key.
 ``sqlite3`` will look for strings containingsquarebrackets (``[]``),
 and will look up aconverter function using the word inside the brackets as
 the converterdictionary key.

   .. code-block:: sql

   Set it to any combination of :const:`PARSE_DECLTYPES` and
   :const:`PARSE_COLNAMES` to enable type detection.
   Types cannot be detected for generated fields (for example ``max(data)``),
   even when *detect_types* parameter is set. In such cases, the returned type
   is :class:`str`.
   even whenthe*detect_types* parameter is set.
 In such cases, the returned typeis :class:`str`.

   By default, *check_same_thread* is :const:`True` and only the creating thread may
   use the connection. If set :const:`False`, the returned connection may be shared

 .. function:: register_converter(typename, converter)

   Registercallable *converter* to convert SQLitetype name *typename* into a
   Python type. The converter is invoked for all SQLite values of type
   *typename*.Confer the parameter *detect_types* of
   Registerthe *converter*callableto convert SQLiteobjects of type *typename* into a
   Pythonobject of a specifictype. The converter is invoked for all SQLite values of type
   *typename*.Consult the parameter *detect_types* of
   :meth:`Connection.connect` regarding how type detection works.

   Note: *typename* and the name of the type in your query are matched in a

 .. function:: register_adapter(type, adapter)

   Registercallable *adapter* to adapt Python type *type* into an SQLite type.
   Registeran *adapter*callableto adapt the Python type *type* into an SQLite type.
   The adapter is called with a Python object as its sole argument,
   and must return a valid SQLite type:
   :class:`int`, :class:`float`, :class:`str`, :class:`bytes`, or :const:`None`.
 Using adapters to store custom Python types in SQLite databases
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 SQLite supports only a limited set of types natively.
 To store custom Python types in SQLite databases, **adapt** them one of the
 basic types supported by SQLite:
 :class:`int`, :class:`float`, :class:`str`, :class:`bytes`, or :const:`None`.

 There are two ways to adapt Python objects to SQLite types:
 letting your object adapt itself, or using an adapterfunction.
 letting your object adapt itself, or using an*adaptercallable*.
 The latter will take precedence above the former. For a library that exports a
 custom type, it may make sense to let that type be able to adapt itself. As an
 application developer, it may make more sense to take control, and register

 Suppose we have ``Point`` class that represents a pair of coordinates,
 ``x`` and ``y``, in a Cartesian coordinate system.
 We want to store the coordinate pair as a text string in the database,
 The coordinate pair will be stored as a text string in the database,
 using a semicolon to separate the coordinates.
 We implement this by adding a ``__conform__(self, protocol)`` method which
 returns the adapted value. *protocol* will be :class:`PrepareProtocol`.
 This can be implemented by adding a ``__conform__(self, protocol)``
 method which returns the adapted value.
 The object passed to *protocol* will be of type :class:`PrepareProtocol`.

 .. literalinclude:: ../includes/sqlite3/adapter_point_1.py


 Registering an adapter callable
 """""""""""""""""""""""""""""""

 Continuing the above example, let's rewrite it using an adapter function.
 We use :meth:`register_adapter`toaddanadapter function that takes a Python
 type as its argument, and returns an SQLite compatible type.
 The other possibility is to create a function that converts the Python object
 to anSQLite-compatible type.
 This function can then be registered using :meth:`register_adapter`.

 .. literalinclude:: ../includes/sqlite3/adapter_point_2.py

 Converting SQLite values to custom Python types
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 Writing an adapter lets you send custom Python types to SQLite. But to make it
 really useful we need to make the Python to SQLite to Python roundtrip work.
 To be able to convert SQLite value to custom Python types, we use _converters_.

 Let's revisit the ``Point`` class example from above;
 the coordinate pair is stored in the database as a semicolon separated string.
 We define a converter that accept a string, and return a ``Point`` object.
 Let's go back to the :class:`Point` class. We stored the x and y coordinates
 separated via semicolons as strings in SQLite.

 First, we'll define a converter function that accepts the string as a parameter
 and constructs a :class:`Point` object from it.

 .. note::

   Converter functions **always** are passed a :class:`bytes` object,
   Converter functionsare**always** passed a :class:`bytes` object,
   no matter the underlying SQLite data type.

 ::
       x, y = map(float, s.split(b";"))
       return Point(x, y)

 We now need to tell:mod:`sqlite3` when it should convert a given SQLite value.
 This is done when connecting to a database, using the *detect_types*keyword of
 :meth:`connect`. We've got three options:
 We now need to tell``sqlite3`` when it should convert a given SQLite value.
 This is done when connecting to a database, using the *detect_types*parameter
 of:meth:`connect`. We've got three options:

 * Implicit: set *detect_types* to :const:`PARSE_DECLTYPES`
 * Explicit: set *detect_types* to :const:`PARSE_COLNAMES`

   import sqlite3

   # Timezonenaive datetime adapters and converters.
   # Timezone-naive datetime adapters and converters.
   def adapt_date(val):
       return val.isoformat()
Original file line number	Diff line number	Diff line change
Expand Up		@@ -8,7 +8,7 @@ def __repr__(self):
		return f"Point({self.x}, {self.y})"

		def adapt_point(point):
		return("%f;%f" % (point.x,point.y)).encode("utf-8")
		returnf"{point.x};{point.y}".encode("utf-8")

		def convert_point(s):
		x, y = list(map(float, s.split(b";")))
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -199,12 +199,12 @@ Module functions and constants

		.. data:: PARSE_DECLTYPES

		Use this flag with the detect_typeskeyword of :meth:`connect` to enable
		parsing of declared types for each columnit return.
		Use this flag with the detect_typesparameter of :meth:`connect` to enable
		parsing of declared types for each columnreturned.
		The types are declared when the database table is created.
erlend-aasland marked this conversation as resolved. Show resolvedHide resolved
		:mod:`sqlite3` will look up a converter function using the first word of the
		``sqlite3`` will look up a converter function using the first word of the
		declared type as the converter dictionary key.
		The following SQL code results in the following lookups:
		For example, the following SQL code results in the following lookups:
erlend-aasland marked this conversation as resolved. OutdatedShow resolvedHide resolved

		.. code-block:: sql

Expand All		@@ -220,11 +220,11 @@ Module functions and constants

		.. data:: PARSE_COLNAMES

		Use this flag with the detect_typeskeyword of :meth:`connect` to enable
		Use this flag with the detect_typesparameter of :meth:`connect` to enable
		parsing of column names in queries.
		:mod:`sqlite3` will look for strings containing brackets, and will look up a
		converter function using the word inside the brackets as the converter
		dictionary key.
		``sqlite3`` will look for strings containingsquarebrackets (``[]``),
erlend-aasland marked this conversation as resolved. OutdatedShow resolvedHide resolved
		and will look up aconverter function using the word inside the brackets as
erlend-aasland marked this conversation as resolved. OutdatedShow resolvedHide resolved
		the converterdictionary key.

		.. code-block:: sql

Expand DownExpand Up		@@ -262,8 +262,8 @@ Module functions and constants
		Set it to any combination of :const:`PARSE_DECLTYPES` and
erlend-aasland marked this conversation as resolved. OutdatedShow resolvedHide resolved
		:const:`PARSE_COLNAMES` to enable type detection.
		Types cannot be detected for generated fields (for example ``max(data)``),
erlend-aasland marked this conversation as resolved. Show resolvedHide resolved
		even when detect_types parameter is set. In such cases, the returned type
		is :class:`str`.
		even whenthedetect_types parameter is set.
		In such cases, the returned typeis :class:`str`.

		By default, check_same_thread is :const:`True` and only the creating thread may
		use the connection. If set :const:`False`, the returned connection may be shared
Expand DownExpand Up		@@ -320,9 +320,9 @@ Module functions and constants

		.. function:: register_converter(typename, converter)

		Registercallable converter to convert SQLitetype name typename into a
		Python type. The converter is invoked for all SQLite values of type
		typename.Confer the parameter detect_types of
		Registerthe convertercallableto convert SQLiteobjects of type typename into a
		Pythonobject of a specifictype. The converter is invoked for all SQLite values of type
		typename.Consult the parameter detect_types of
		:meth:`Connection.connect` regarding how type detection works.
erlend-aasland marked this conversation as resolved. OutdatedShow resolvedHide resolved

		Note: typename and the name of the type in your query are matched in a
Expand All		@@ -331,7 +331,7 @@ Module functions and constants

		.. function:: register_adapter(type, adapter)

		Registercallable adapter to adapt Python type type into an SQLite type.
		Registeran adaptercallableto adapt the Python type type into an SQLite type.
		The adapter is called with a Python object as its sole argument,
erlend-aasland marked this conversation as resolved. OutdatedShow resolvedHide resolved
		and must return a valid SQLite type:
		:class:`int`, :class:`float`, :class:`str`, :class:`bytes`, or :const:`None`.
Expand DownExpand Up		@@ -1219,12 +1219,13 @@ types via converters.
		Using adapters to store custom Python types in SQLite databases
erlend-aasland marked this conversation as resolved. Show resolvedHide resolved
		^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

		SQLite supports only a limited set of types natively.
		To store custom Python types in SQLite databases, adapt them one of the
erlend-aasland marked this conversation as resolved. OutdatedShow resolvedHide resolved erlend-aasland marked this conversation as resolved. OutdatedShow resolvedHide resolved
		basic types supported by SQLite:
erlend-aasland marked this conversation as resolved. OutdatedShow resolvedHide resolved
		:class:`int`, :class:`float`, :class:`str`, :class:`bytes`, or :const:`None`.

		There are two ways to adapt Python objects to SQLite types:
		letting your object adapt itself, or using an adapterfunction.
		letting your object adapt itself, or using anadaptercallable.
		The latter will take precedence above the former. For a library that exports a
		custom type, it may make sense to let that type be able to adapt itself. As an
erlend-aasland marked this conversation as resolved. OutdatedShow resolvedHide resolved
		application developer, it may make more sense to take control, and register
erlend-aasland marked this conversation as resolved. OutdatedShow resolvedHide resolved
Expand All		@@ -1236,20 +1237,21 @@ Letting your object adapt itself

		Suppose we have ``Point`` class that represents a pair of coordinates,
erlend-aasland marked this conversation as resolved. OutdatedShow resolvedHide resolved
		``x`` and ``y``, in a Cartesian coordinate system.
		We want to store the coordinate pair as a text string in the database,
		The coordinate pair will be stored as a text string in the database,
		using a semicolon to separate the coordinates.
		We implement this by adding a ``__conform__(self, protocol)`` method which
		returns the adapted value. protocol will be :class:`PrepareProtocol`.
		This can be implemented by adding a ``__conform__(self, protocol)``
		method which returns the adapted value.
		The object passed to protocol will be of type :class:`PrepareProtocol`.
erlend-aasland marked this conversation as resolved. Show resolvedHide resolved

		.. literalinclude:: ../includes/sqlite3/adapter_point_1.py


		Registering an adapter callable
		"""""""""""""""""""""""""""""""

		Continuing the above example, let's rewrite it using an adapter function.
		We use :meth:`register_adapter`toaddanadapter function that takes a Python
		type as its argument, and returns an SQLite compatible type.
		The other possibility is to create a function that converts the Python object
		to anSQLite-compatible type.
erlend-aasland marked this conversation as resolved. Show resolvedHide resolved
		This function can then be registered using :meth:`register_adapter`.
erlend-aasland marked this conversation as resolved. OutdatedShow resolvedHide resolved

		.. literalinclude:: ../includes/sqlite3/adapter_point_2.py

Expand All		@@ -1264,15 +1266,19 @@ but as a Unix timestamp.
		Converting SQLite values to custom Python types
		^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

		Writing an adapter lets you send custom Python types to SQLite. But to make it
		really useful we need to make the Python to SQLite to Python roundtrip work.
		To be able to convert SQLite value to custom Python types, we use _converters_.
erlend-aasland marked this conversation as resolved. OutdatedShow resolvedHide resolved

		Let's revisit the ``Point`` class example from above;
		the coordinate pair is stored in the database as a semicolon separated string.
		We define a converter that accept a string, and return a ``Point`` object.
		Let's go back to the :class:`Point` class. We stored the x and y coordinates
		separated via semicolons as strings in SQLite.

		First, we'll define a converter function that accepts the string as a parameter
		and constructs a :class:`Point` object from it.

		.. note::

		Converter functions always are passed a :class:`bytes` object,
		Converter functionsarealways passed a :class:`bytes` object,
		no matter the underlying SQLite data type.

		::
Expand All		@@ -1281,9 +1287,9 @@ We define a converter that accept a string, and return a ``Point`` object.
		x, y = map(float, s.split(b";"))
		return Point(x, y)

		We now need to tell:mod:`sqlite3` when it should convert a given SQLite value.
		This is done when connecting to a database, using the detect_typeskeyword of
		:meth:`connect`. We've got three options:
		We now need to tell``sqlite3`` when it should convert a given SQLite value.
		This is done when connecting to a database, using the detect_typesparameter
		of:meth:`connect`. We've got three options:

		* Implicit: set detect_types to :const:`PARSE_DECLTYPES`
		* Explicit: set detect_types to :const:`PARSE_COLNAMES`
Expand DownExpand Up		@@ -1336,7 +1342,7 @@ This section shows recipes for common adapters and converters.

		import sqlite3

		# Timezonenaive datetime adapters and converters.
		# Timezone-naive datetime adapters and converters.
		def adapt_date(val):
		return val.isoformat()

Expand Down