From c3a6d59263039335316c80ebf6aa465a94797fd9 Mon Sep 17 00:00:00 2001 From: Ryan Duve Date: Thu, 18 Jan 2024 23:42:04 -0500 Subject: [PATCH 1/2] Add return types to sqlite methods in docs --- Doc/library/sqlite3.rst | 87 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 6dbb34a84a4c40..f6b5ab2c34b8f6 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -338,6 +338,9 @@ Module functions The default will change to ``False`` in a future Python release. :type autocommit: bool + :raises ProgrammingError: + If the database connection is used by a thread other than the one that created it. + :rtype: ~sqlite3.Connection .. audit-event:: sqlite3.connect database sqlite3.connect @@ -363,6 +366,8 @@ Module functions .. function:: complete_statement(statement) + :rtype: bool + Return ``True`` if the string *statement* appears to contain one or more complete SQL statements. No syntactic verification or parsing of any kind is performed, @@ -388,6 +393,9 @@ Module functions .. function:: enable_callback_tracebacks(flag, /) Enable or disable callback tracebacks. + + :rtype: None + By default you will not get any tracebacks in user-defined functions, aggregates, converters, authorizer callbacks etc. If you want to debug them, you can call this function with *flag* set to ``True``. Afterwards, you @@ -422,6 +430,9 @@ Module functions Register an *adapter* :term:`callable` to adapt the Python type *type* into an SQLite type. + + :rtype: None + The adapter is called with a Python object of type *type* as its sole argument, and must return a value of a :ref:`type that SQLite natively understands `. @@ -430,6 +441,9 @@ Module functions Register the *converter* :term:`callable` to convert SQLite objects of type *typename* into a Python object of a specific type. + + :rtype: None + The converter is invoked for all SQLite values of type *typename*; it is passed a :class:`bytes` object and should return an object of the desired Python type. @@ -641,6 +655,9 @@ Connection objects .. method:: cursor(factory=Cursor) Create and return a :class:`Cursor` object. + + :rtype: ~sqlite3.Connection + The cursor method accepts a single optional parameter *factory*. If supplied, this must be a :term:`callable` returning an instance of :class:`Cursor` or its subclasses. @@ -683,6 +700,9 @@ Connection objects .. method:: commit() Commit any pending transaction to the database. + + :rtype: None + If :attr:`autocommit` is ``True``, or there is no open transaction, this method does nothing. If :attr:`!autocommit` is ``False``, a new transaction is implicitly @@ -691,6 +711,9 @@ Connection objects .. method:: rollback() Roll back to the start of any pending transaction. + + :rtype: None + If :attr:`autocommit` is ``True``, or there is no open transaction, this method does nothing. If :attr:`!autocommit` is ``False``, a new transaction is implicitly @@ -699,6 +722,9 @@ Connection objects .. method:: close() Close the database connection. + + :rtype: None + If :attr:`autocommit` is ``False``, any pending transaction is implicitly rolled back. If :attr:`!autocommit` is ``True`` or :data:`LEGACY_TRANSACTION_CONTROL`, @@ -708,18 +734,24 @@ Connection objects .. method:: execute(sql, parameters=(), /) + :rtype: ~sqlite3.Cursor + Create a new :class:`Cursor` object and call :meth:`~Cursor.execute` on it with the given *sql* and *parameters*. Return the new cursor object. .. method:: executemany(sql, parameters, /) + :rtype: ~sqlite3.Cursor + Create a new :class:`Cursor` object and call :meth:`~Cursor.executemany` on it with the given *sql* and *parameters*. Return the new cursor object. .. method:: executescript(sql_script, /) + :rtype: ~sqlite3.Cursor + Create a new :class:`Cursor` object and call :meth:`~Cursor.executescript` on it with the given *sql_script*. Return the new cursor object. @@ -747,6 +779,8 @@ Connection objects `deterministic `_, which allows SQLite to perform additional optimizations. + :rtype: None + .. versionadded:: 3.8 The *deterministic* parameter. @@ -771,6 +805,8 @@ Connection objects .. method:: create_aggregate(name, n_arg, aggregate_class) + :rtype: None + Create or remove a user-defined SQL aggregate function. :param str name: @@ -830,6 +866,8 @@ Connection objects .. method:: create_window_function(name, num_params, aggregate_class, /) + :rtype: None + Create or remove a user-defined aggregate window function. :param str name: @@ -916,6 +954,8 @@ Connection objects .. method:: create_collation(name, callable, /) + :rtype: None + Create a collation named *name* using the collating function *callable*. *callable* is passed two :class:`string ` arguments, and it should return an :class:`integer `: @@ -961,6 +1001,8 @@ Connection objects .. method:: interrupt() + :rtype: None + Call this method from a different thread to abort any queries that might be executing on the connection. Aborted queries will raise an :exc:`OperationalError`. @@ -968,6 +1010,8 @@ Connection objects .. method:: set_authorizer(authorizer_callback) + :rtype: None + Register :term:`callable` *authorizer_callback* to be invoked for each attempt to access a column of a table in the database. The callback should return one of :const:`SQLITE_OK`, @@ -998,6 +1042,8 @@ Connection objects .. method:: set_progress_handler(progress_handler, n) + :rtype: None + Register :term:`callable` *progress_handler* to be invoked for every *n* instructions of the SQLite virtual machine. This is useful if you want to get called from SQLite during long-running operations, for example to update @@ -1017,6 +1063,8 @@ Connection objects .. method:: set_trace_callback(trace_callback) + :rtype: None + Register :term:`callable` *trace_callback* to be invoked for each SQL statement that is actually executed by the SQLite backend. @@ -1045,6 +1093,8 @@ Connection objects .. method:: enable_load_extension(enabled, /) + :rtype: None + Enable the SQLite engine to load SQLite extensions from shared libraries if *enabled* is ``True``; else, disallow loading SQLite extensions. @@ -1108,6 +1158,8 @@ Connection objects .. method:: load_extension(path, /, *, entrypoint=None) + :rtype: None + Load an SQLite extension from a shared library. Enable extension loading with :meth:`enable_load_extension` before calling this method. @@ -1139,6 +1191,8 @@ Connection objects .. method:: iterdump + :rtype: :term:`iterator` [ str ] + Return an :term:`iterator` to dump the database as SQL source code. Useful when saving an in-memory database for later restoration. Similar to the ``.dump`` command in the :program:`sqlite3` shell. @@ -1161,8 +1215,11 @@ Connection objects .. method:: backup(target, *, pages=-1, progress=None, name="main", sleep=0.250) + Create a backup of an SQLite database. + :rtype: None + Works even if the database is being accessed by other clients or concurrently by the same connection. @@ -1519,6 +1576,8 @@ Cursor objects :raises ProgrammingError: If *sql* contains more than one SQL statement. + :rtype: ~sqlite3.Cursor + If :attr:`~Connection.autocommit` is :data:`LEGACY_TRANSACTION_CONTROL`, :attr:`~Connection.isolation_level` is not ``None``, @@ -1557,6 +1616,8 @@ Cursor objects If *sql* contains more than one SQL statement, or is not a DML statement. + :rtype: ~sqlite3.Cursor + Example: .. testcode:: sqlite3.cursor @@ -1586,6 +1647,8 @@ Cursor objects .. method:: executescript(sql_script, /) + :rtype: ~sqlite3.Cursor + Execute the SQL statements in *sql_script*. If the :attr:`~Connection.autocommit` is :data:`LEGACY_TRANSACTION_CONTROL` @@ -1611,6 +1674,8 @@ Cursor objects .. method:: fetchone() + :rtype: tuple | None + If :attr:`~Cursor.row_factory` is ``None``, return the next row query result set as a :class:`tuple`. Else, pass it to the row factory and return its result. @@ -1619,6 +1684,8 @@ Cursor objects .. method:: fetchmany(size=cursor.arraysize) + :rtype: list [ tuple ] + Return the next set of rows of a query result as a :class:`list`. Return an empty list if no more rows are available. @@ -1635,6 +1702,8 @@ Cursor objects .. method:: fetchall() + :rtype: list [ tuple ] + Return all (remaining) rows of a query result as a :class:`list`. Return an empty list if no rows are available. Note that the :attr:`arraysize` attribute can affect the performance of @@ -1642,6 +1711,8 @@ Cursor objects .. method:: close() + :rtype: None + Close the cursor now (rather than whenever ``__del__`` is called). The cursor will be unusable from this point forward; a :exc:`ProgrammingError` @@ -1649,10 +1720,14 @@ Cursor objects .. method:: setinputsizes(sizes, /) + :rtype: None + Required by the DB-API. Does nothing in :mod:`!sqlite3`. .. method:: setoutputsize(size, column=None, /) + :rtype: None + Required by the DB-API. Does nothing in :mod:`!sqlite3`. .. attribute:: arraysize @@ -1749,6 +1824,8 @@ Row objects .. method:: keys + :rtype: list + Return a :class:`list` of column names as :class:`strings `. Immediately after a query, it is the first member of each tuple in :attr:`Cursor.description`. @@ -1801,6 +1878,8 @@ Blob objects .. method:: close() + :rtype: None + Close the blob. The blob will be unusable from this point onward. An @@ -1809,6 +1888,8 @@ Blob objects .. method:: read(length=-1, /) + :rtype: bytes + Read *length* bytes of data from the blob at the current offset position. If the end of the blob is reached, the data up to :abbr:`EOF (End of File)` will be returned. When *length* is not @@ -1817,16 +1898,22 @@ Blob objects .. method:: write(data, /) + :rtype: None + Write *data* to the blob at the current offset. This function cannot change the blob length. Writing beyond the end of the blob will raise :exc:`ValueError`. .. method:: tell() + :rtype: int + Return the current access position of the blob. .. method:: seek(offset, origin=os.SEEK_SET, /) + :rtype: None + Set the current access position of the blob to *offset*. The *origin* argument defaults to :const:`os.SEEK_SET` (absolute blob positioning). Other values for *origin* are :const:`os.SEEK_CUR` (seek relative to the From 55f63d3df4bd0663ebb7379c6600677c0775912b Mon Sep 17 00:00:00 2001 From: Ryan Duve Date: Fri, 19 Jan 2024 13:14:13 -0500 Subject: [PATCH 2/2] Move return type below Parameter/Raises list if exists --- Doc/library/sqlite3.rst | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index f6b5ab2c34b8f6..9d1453c3296e4d 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -805,8 +805,6 @@ Connection objects .. method:: create_aggregate(name, n_arg, aggregate_class) - :rtype: None - Create or remove a user-defined SQL aggregate function. :param str name: @@ -827,6 +825,9 @@ Connection objects is controlled by *n_arg*. Set to ``None`` to remove an existing SQL aggregate function. + + :rtype: None + :type aggregate_class: :term:`class` | None Example: @@ -866,8 +867,6 @@ Connection objects .. method:: create_window_function(name, num_params, aggregate_class, /) - :rtype: None - Create or remove a user-defined aggregate window function. :param str name: @@ -895,6 +894,8 @@ Connection objects If used with a version of SQLite older than 3.25.0, which does not support aggregate window functions. + :rtype: None + :type aggregate_class: :term:`class` | None .. versionadded:: 3.11 @@ -1158,8 +1159,6 @@ Connection objects .. method:: load_extension(path, /, *, entrypoint=None) - :rtype: None - Load an SQLite extension from a shared library. Enable extension loading with :meth:`enable_load_extension` before calling this method. @@ -1175,6 +1174,8 @@ Connection objects SQLite will come up with an entry point name of its own; see the SQLite docs `Loading an Extension`_ for details. + :rtype: None + :type entrypoint: str | None .. audit-event:: sqlite3.load_extension connection,path sqlite3.Connection.load_extension @@ -1218,8 +1219,6 @@ Connection objects Create a backup of an SQLite database. - :rtype: None - Works even if the database is being accessed by other clients or concurrently by the same connection. @@ -1252,6 +1251,8 @@ Connection objects The number of seconds to sleep between successive attempts to back up remaining pages. + :rtype: None + Example 1, copy an existing database into another: .. testcode:: @@ -1371,6 +1372,8 @@ Connection objects ``True`` if the configuration option should be enabled (default); ``False`` if it should be disabled. + :rtype: bool + .. versionadded:: 3.12 .. method:: serialize(*, name="main")