[Python-checkins] cpython (merge 3.2 -> 3.3): Merge: Fix sqlite3 class markup.
r.david.murray
python-checkins at python.org
Mon Oct 1 02:50:45 CEST 2012
http://hg.python.org/cpython/rev/2299ebc0698b
changeset: 79354:2299ebc0698b
branch: 3.3
parent: 79351:5242ccd0a3f6
parent: 79353:c8b94273c5ee
user: R David Murray <rdmurray at bitdance.com>
date: Sun Sep 30 20:49:19 2012 -0400
summary:
Merge: Fix sqlite3 class markup.
files:
Doc/library/sqlite3.rst | 448 ++++++++++++++-------------
1 files changed, 226 insertions(+), 222 deletions(-)
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -222,250 +222,254 @@
A SQLite database connection has the following attributes and methods:
-.. attribute:: Connection.isolation_level
+ .. attribute:: isolation_level
- Get or set the current isolation level. :const:`None` for autocommit mode or
- one of "DEFERRED", "IMMEDIATE" or "EXCLUSIVE". See section
- :ref:`sqlite3-controlling-transactions` for a more detailed explanation.
+ Get or set the current isolation level. :const:`None` for autocommit mode or
+ one of "DEFERRED", "IMMEDIATE" or "EXCLUSIVE". See section
+ :ref:`sqlite3-controlling-transactions` for a more detailed explanation.
-.. attribute:: Connection.in_transaction
+ .. attribute:: in_transaction
- :const:`True` if a transaction is active (there are uncommitted changes),
- :const:`False` otherwise. Read-only attribute.
+ :const:`True` if a transaction is active (there are uncommitted changes),
+ :const:`False` otherwise. Read-only attribute.
- .. versionadded:: 3.2
+ .. versionadded:: 3.2
-.. method:: Connection.cursor([cursorClass])
+ .. method:: cursor([cursorClass])
- The cursor method accepts a single optional parameter *cursorClass*. If
- supplied, this must be a custom cursor class that extends
- :class:`sqlite3.Cursor`.
+ The cursor method accepts a single optional parameter *cursorClass*. If
+ supplied, this must be a custom cursor class that extends
+ :class:`sqlite3.Cursor`.
-.. method:: Connection.commit()
+ .. method:: commit()
- This method commits the current transaction. If you don't call this method,
- anything you did since the last call to ``commit()`` is not visible from
- other database connections. If you wonder why you don't see the data you've
- written to the database, please check you didn't forget to call this method.
+ This method commits the current transaction. If you don't call this method,
+ anything you did since the last call to ``commit()`` is not visible from
+ other database connections. If you wonder why you don't see the data you've
+ written to the database, please check you didn't forget to call this method.
-.. method:: Connection.rollback()
+ .. method:: rollback()
- This method rolls back any changes to the database since the last call to
- :meth:`commit`.
+ This method rolls back any changes to the database since the last call to
+ :meth:`commit`.
-.. method:: Connection.close()
+ .. method:: close()
- This closes the database connection. Note that this does not automatically
- call :meth:`commit`. If you just close your database connection without
- calling :meth:`commit` first, your changes will be lost!
+ This closes the database connection. Note that this does not automatically
+ call :meth:`commit`. If you just close your database connection without
+ calling :meth:`commit` first, your changes will be lost!
-.. method:: Connection.execute(sql, [parameters])
+ .. method:: execute(sql, [parameters])
- This is a nonstandard shortcut that creates an intermediate cursor object by
- calling the cursor method, then calls the cursor's :meth:`execute
- <Cursor.execute>` method with the parameters given.
+ This is a nonstandard shortcut that creates an intermediate cursor object by
+ calling the cursor method, then calls the cursor's :meth:`execute
+ <Cursor.execute>` method with the parameters given.
-.. method:: Connection.executemany(sql, [parameters])
+ .. method:: executemany(sql, [parameters])
- This is a nonstandard shortcut that creates an intermediate cursor object by
- calling the cursor method, then calls the cursor's :meth:`executemany
- <Cursor.executemany>` method with the parameters given.
+ This is a nonstandard shortcut that creates an intermediate cursor object by
+ calling the cursor method, then calls the cursor's :meth:`executemany
+ <Cursor.executemany>` method with the parameters given.
-.. method:: Connection.executescript(sql_script)
+ .. method:: executescript(sql_script)
- This is a nonstandard shortcut that creates an intermediate cursor object by
- calling the cursor method, then calls the cursor's :meth:`executescript
- <Cursor.executescript>` method with the parameters given.
+ This is a nonstandard shortcut that creates an intermediate cursor object by
+ calling the cursor method, then calls the cursor's :meth:`executescript
+ <Cursor.executescript>` method with the parameters given.
-.. method:: Connection.create_function(name, num_params, func)
+ .. method:: create_function(name, num_params, func)
- Creates a user-defined function that you can later use from within SQL
- statements under the function name *name*. *num_params* is the number of
- parameters the function accepts, and *func* is a Python callable that is called
- as the SQL function.
+ Creates a user-defined function that you can later use from within SQL
+ statements under the function name *name*. *num_params* is the number of
+ parameters the function accepts, and *func* is a Python callable that is called
+ as the SQL function.
- The function can return any of the types supported by SQLite: bytes, str, int,
- float and None.
+ The function can return any of the types supported by SQLite: bytes, str, int,
+ float and None.
- Example:
+ Example:
- .. literalinclude:: ../includes/sqlite3/md5func.py
+ .. literalinclude:: ../includes/sqlite3/md5func.py
-.. method:: Connection.create_aggregate(name, num_params, aggregate_class)
+ .. method:: create_aggregate(name, num_params, aggregate_class)
- Creates a user-defined aggregate function.
+ Creates a user-defined aggregate function.
- The aggregate class must implement a ``step`` method, which accepts the number
- of parameters *num_params*, and a ``finalize`` method which will return the
- final result of the aggregate.
+ The aggregate class must implement a ``step`` method, which accepts the number
+ of parameters *num_params*, and a ``finalize`` method which will return the
+ final result of the aggregate.
- The ``finalize`` method can return any of the types supported by SQLite:
- bytes, str, int, float and None.
+ The ``finalize`` method can return any of the types supported by SQLite:
+ bytes, str, int, float and None.
- Example:
+ Example:
- .. literalinclude:: ../includes/sqlite3/mysumaggr.py
+ .. literalinclude:: ../includes/sqlite3/mysumaggr.py
-.. method:: Connection.create_collation(name, callable)
+ .. method:: create_collation(name, callable)
- Creates a collation with the specified *name* and *callable*. The callable will
- be passed two string arguments. It should return -1 if the first is ordered
- lower than the second, 0 if they are ordered equal and 1 if the first is ordered
- higher than the second. Note that this controls sorting (ORDER BY in SQL) so
- your comparisons don't affect other SQL operations.
+ Creates a collation with the specified *name* and *callable*. The callable will
+ be passed two string arguments. It should return -1 if the first is ordered
+ lower than the second, 0 if they are ordered equal and 1 if the first is ordered
+ higher than the second. Note that this controls sorting (ORDER BY in SQL) so
+ your comparisons don't affect other SQL operations.
- Note that the callable will get its parameters as Python bytestrings, which will
- normally be encoded in UTF-8.
+ Note that the callable will get its parameters as Python bytestrings, which will
+ normally be encoded in UTF-8.
- The following example shows a custom collation that sorts "the wrong way":
+ The following example shows a custom collation that sorts "the wrong way":
- .. literalinclude:: ../includes/sqlite3/collation_reverse.py
+ .. literalinclude:: ../includes/sqlite3/collation_reverse.py
- To remove a collation, call ``create_collation`` with None as callable::
+ To remove a collation, call ``create_collation`` with None as callable::
- con.create_collation("reverse", None)
+ con.create_collation("reverse", None)
-.. method:: Connection.interrupt()
+ .. method:: interrupt()
- You can call this method from a different thread to abort any queries that might
- be executing on the connection. The query will then abort and the caller will
- get an exception.
+ You can call this method from a different thread to abort any queries that might
+ be executing on the connection. The query will then abort and the caller will
+ get an exception.
-.. method:: Connection.set_authorizer(authorizer_callback)
+ .. method:: set_authorizer(authorizer_callback)
- This routine registers a callback. The callback is invoked for each attempt to
- access a column of a table in the database. The callback should return
- :const:`SQLITE_OK` if access is allowed, :const:`SQLITE_DENY` if the entire SQL
- statement should be aborted with an error and :const:`SQLITE_IGNORE` if the
- column should be treated as a NULL value. These constants are available in the
- :mod:`sqlite3` module.
+ This routine registers a callback. The callback is invoked for each attempt to
+ access a column of a table in the database. The callback should return
+ :const:`SQLITE_OK` if access is allowed, :const:`SQLITE_DENY` if the entire SQL
+ statement should be aborted with an error and :const:`SQLITE_IGNORE` if the
+ column should be treated as a NULL value. These constants are available in the
+ :mod:`sqlite3` module.
- The first argument to the callback signifies what kind of operation is to be
- authorized. The second and third argument will be arguments or :const:`None`
- depending on the first argument. The 4th argument is the name of the database
- ("main", "temp", etc.) if applicable. The 5th argument is the name of the
- inner-most trigger or view that is responsible for the access attempt or
- :const:`None` if this access attempt is directly from input SQL code.
+ The first argument to the callback signifies what kind of operation is to be
+ authorized. The second and third argument will be arguments or :const:`None`
+ depending on the first argument. The 4th argument is the name of the database
+ ("main", "temp", etc.) if applicable. The 5th argument is the name of the
+ inner-most trigger or view that is responsible for the access attempt or
+ :const:`None` if this access attempt is directly from input SQL code.
- Please consult the SQLite documentation about the possible values for the first
- argument and the meaning of the second and third argument depending on the first
- one. All necessary constants are available in the :mod:`sqlite3` module.
+ Please consult the SQLite documentation about the possible values for the first
+ argument and the meaning of the second and third argument depending on the first
+ one. All necessary constants are available in the :mod:`sqlite3` module.
-.. method:: Connection.set_progress_handler(handler, n)
+ .. method:: set_progress_handler(handler, n)
- This routine registers a callback. The callback is 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
- a GUI.
+ This routine registers a callback. The callback is 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
+ a GUI.
- If you want to clear any previously installed progress handler, call the
- method with :const:`None` for *handler*.
+ If you want to clear any previously installed progress handler, call the
+ method with :const:`None` for *handler*.
-.. method:: Connection.set_trace_callback(trace_callback)
+ .. method:: set_trace_callback(trace_callback)
- Registers *trace_callback* to be called for each SQL statement that is
- actually executed by the SQLite backend.
+ Registers *trace_callback* to be called for each SQL statement that is
+ actually executed by the SQLite backend.
- The only argument passed to the callback is the statement (as string) that
- is being executed. The return value of the callback is ignored. Note that
- the backend does not only run statements passed to the :meth:`Cursor.execute`
- methods. Other sources include the transaction management of the Python
- module and the execution of triggers defined in the current database.
+ The only argument passed to the callback is the statement (as string) that
+ is being executed. The return value of the callback is ignored. Note that
+ the backend does not only run statements passed to the :meth:`Cursor.execute`
+ methods. Other sources include the transaction management of the Python
+ module and the execution of triggers defined in the current database.
- Passing :const:`None` as *trace_callback* will disable the trace callback.
+ Passing :const:`None` as *trace_callback* will disable the trace callback.
- .. versionadded:: 3.3
+ .. versionadded:: 3.3
-.. method:: Connection.enable_load_extension(enabled)
+ .. method:: enable_load_extension(enabled)
- This routine allows/disallows the SQLite engine to load SQLite extensions
- from shared libraries. SQLite extensions can define new functions,
- aggregates or whole new virtual table implementations. One well-known
- extension is the fulltext-search extension distributed with SQLite.
+ This routine allows/disallows the SQLite engine to load SQLite extensions
+ from shared libraries. SQLite extensions can define new functions,
+ aggregates or whole new virtual table implementations. One well-known
+ extension is the fulltext-search extension distributed with SQLite.
- Loadable extensions are disabled by default. See [#f1]_.
+ Loadable extensions are disabled by default. See [#f1]_.
- .. versionadded:: 3.2
+ .. versionadded:: 3.2
- .. literalinclude:: ../includes/sqlite3/load_extension.py
+ .. literalinclude:: ../includes/sqlite3/load_extension.py
-.. method:: Connection.load_extension(path)
+ .. method:: load_extension(path)
- This routine loads a SQLite extension from a shared library. You have to
- enable extension loading with :meth:`enable_load_extension` before you can
- use this routine.
+ This routine loads a SQLite extension from a shared library. You have to
+ enable extension loading with :meth:`enable_load_extension` before you can
+ use this routine.
- Loadable extensions are disabled by default. See [#f1]_.
+ Loadable extensions are disabled by default. See [#f1]_.
- .. versionadded:: 3.2
+ .. versionadded:: 3.2
-.. attribute:: Connection.row_factory
+ .. attribute:: row_factory
- You can change this attribute to a callable that accepts the cursor and the
- original row as a tuple and will return the real result row. This way, you can
- implement more advanced ways of returning results, such as returning an object
- that can also access columns by name.
+ You can change this attribute to a callable that accepts the cursor and the
+ original row as a tuple and will return the real result row. This way, you can
+ implement more advanced ways of returning results, such as returning an object
+ that can also access columns by name.
- Example:
+ Example:
- .. literalinclude:: ../includes/sqlite3/row_factory.py
+ .. literalinclude:: ../includes/sqlite3/row_factory.py
- If returning a tuple doesn't suffice and you want name-based access to
- columns, you should consider setting :attr:`row_factory` to the
- highly-optimized :class:`sqlite3.Row` type. :class:`Row` provides both
- index-based and case-insensitive name-based access to columns with almost no
- memory overhead. It will probably be better than your own custom
- dictionary-based approach or even a db_row based solution.
+ If returning a tuple doesn't suffice and you want name-based access to
+ columns, you should consider setting :attr:`row_factory` to the
+ highly-optimized :class:`sqlite3.Row` type. :class:`Row` provides both
+ index-based and case-insensitive name-based access to columns with almost no
+ memory overhead. It will probably be better than your own custom
+ dictionary-based approach or even a db_row based solution.
- .. XXX what's a db_row-based solution?
+ .. XXX what's a db_row-based solution?
-.. attribute:: Connection.text_factory
+ .. attribute:: text_factory
- Using this attribute you can control what objects are returned for the ``TEXT``
- data type. By default, this attribute is set to :class:`str` and the
- :mod:`sqlite3` module will return Unicode objects for ``TEXT``. If you want to
- return bytestrings instead, you can set it to :class:`bytes`.
+ Using this attribute you can control what objects are returned for the ``TEXT``
+ data type. By default, this attribute is set to :class:`str` and the
+ :mod:`sqlite3` module will return Unicode objects for ``TEXT``. If you want to
+ return bytestrings instead, you can set it to :class:`bytes`.
- You can also set it to any other callable that accepts a single bytestring
- parameter and returns the resulting object.
+ For efficiency reasons, there's also a way to return :class:`str` objects
+ only for non-ASCII data, and :class:`bytes` otherwise. To activate it, set
+ this attribute to :const:`sqlite3.OptimizedUnicode`.
- See the following example code for illustration:
+ You can also set it to any other callable that accepts a single bytestring
+ parameter and returns the resulting object.
- .. literalinclude:: ../includes/sqlite3/text_factory.py
+ See the following example code for illustration:
+ .. literalinclude:: ../includes/sqlite3/text_factory.py
-.. attribute:: Connection.total_changes
- Returns the total number of database rows that have been modified, inserted, or
- deleted since the database connection was opened.
+ .. attribute:: total_changes
+ Returns the total number of database rows that have been modified, inserted, or
+ deleted since the database connection was opened.
-.. attribute:: Connection.iterdump
- Returns an iterator to dump the database in an SQL text format. Useful when
- saving an in-memory database for later restoration. This function provides
- the same capabilities as the :kbd:`.dump` command in the :program:`sqlite3`
- shell.
+ .. attribute:: iterdump
- Example::
+ Returns an iterator to dump the database in an SQL text format. Useful when
+ saving an in-memory database for later restoration. This function provides
+ the same capabilities as the :kbd:`.dump` command in the :program:`sqlite3`
+ shell.
- # Convert file existing_db.db to SQL dump file dump.sql
- import sqlite3, os
+ Example::
- con = sqlite3.connect('existing_db.db')
- with open('dump.sql', 'w') as f:
- for line in con.iterdump():
- f.write('%s\n' % line)
+ # Convert file existing_db.db to SQL dump file dump.sql
+ import sqlite3, os
+
+ con = sqlite3.connect('existing_db.db')
+ with open('dump.sql', 'w') as f:
+ for line in con.iterdump():
+ f.write('%s\n' % line)
.. _sqlite3-cursor-objects:
@@ -477,110 +481,110 @@
A :class:`Cursor` instance has the following attributes and methods.
-.. method:: Cursor.execute(sql, [parameters])
+ .. method:: execute(sql, [parameters])
- Executes an SQL statement. The SQL statement may be parametrized (i. e.
- placeholders instead of SQL literals). The :mod:`sqlite3` module supports two
- kinds of placeholders: question marks (qmark style) and named placeholders
- (named style).
+ Executes an SQL statement. The SQL statement may be parametrized (i. e.
+ placeholders instead of SQL literals). The :mod:`sqlite3` module supports two
+ kinds of placeholders: question marks (qmark style) and named placeholders
+ (named style).
- Here's an example of both styles:
+ Here's an example of both styles:
- .. literalinclude:: ../includes/sqlite3/execute_1.py
+ .. literalinclude:: ../includes/sqlite3/execute_1.py
- :meth:`execute` will only execute a single SQL statement. If you try to execute
- more than one statement with it, it will raise a Warning. Use
- :meth:`executescript` if you want to execute multiple SQL statements with one
- call.
+ :meth:`execute` will only execute a single SQL statement. If you try to execute
+ more than one statement with it, it will raise a Warning. Use
+ :meth:`executescript` if you want to execute multiple SQL statements with one
+ call.
-.. method:: Cursor.executemany(sql, seq_of_parameters)
+ .. method:: executemany(sql, seq_of_parameters)
- Executes an SQL command against all parameter sequences or mappings found in
- the sequence *sql*. The :mod:`sqlite3` module also allows using an
- :term:`iterator` yielding parameters instead of a sequence.
+ Executes an SQL command against all parameter sequences or mappings found in
+ the sequence *sql*. The :mod:`sqlite3` module also allows using an
+ :term:`iterator` yielding parameters instead of a sequence.
- .. literalinclude:: ../includes/sqlite3/executemany_1.py
+ .. literalinclude:: ../includes/sqlite3/executemany_1.py
- Here's a shorter example using a :term:`generator`:
+ Here's a shorter example using a :term:`generator`:
- .. literalinclude:: ../includes/sqlite3/executemany_2.py
+ .. literalinclude:: ../includes/sqlite3/executemany_2.py
-.. method:: Cursor.executescript(sql_script)
+ .. method:: executescript(sql_script)
- This is a nonstandard convenience method for executing multiple SQL statements
- at once. It issues a ``COMMIT`` statement first, then executes the SQL script it
- gets as a parameter.
+ This is a nonstandard convenience method for executing multiple SQL statements
+ at once. It issues a ``COMMIT`` statement first, then executes the SQL script it
+ gets as a parameter.
- *sql_script* can be an instance of :class:`str` or :class:`bytes`.
+ *sql_script* can be an instance of :class:`str` or :class:`bytes`.
- Example:
+ Example:
- .. literalinclude:: ../includes/sqlite3/executescript.py
+ .. literalinclude:: ../includes/sqlite3/executescript.py
-.. method:: Cursor.fetchone()
+ .. method:: fetchone()
- Fetches the next row of a query result set, returning a single sequence,
- or :const:`None` when no more data is available.
+ Fetches the next row of a query result set, returning a single sequence,
+ or :const:`None` when no more data is available.
-.. method:: Cursor.fetchmany(size=cursor.arraysize)
+ .. method:: fetchmany(size=cursor.arraysize)
- Fetches the next set of rows of a query result, returning a list. An empty
- list is returned when no more rows are available.
+ Fetches the next set of rows of a query result, returning a list. An empty
+ list is returned when no more rows are available.
- The number of rows to fetch per call is specified by the *size* parameter.
- If it is not given, the cursor's arraysize determines the number of rows
- to be fetched. The method should try to fetch as many rows as indicated by
- the size parameter. If this is not possible due to the specified number of
- rows not being available, fewer rows may be returned.
+ The number of rows to fetch per call is specified by the *size* parameter.
+ If it is not given, the cursor's arraysize determines the number of rows
+ to be fetched. The method should try to fetch as many rows as indicated by
+ the size parameter. If this is not possible due to the specified number of
+ rows not being available, fewer rows may be returned.
- Note there are performance considerations involved with the *size* parameter.
- For optimal performance, it is usually best to use the arraysize attribute.
- If the *size* parameter is used, then it is best for it to retain the same
- value from one :meth:`fetchmany` call to the next.
+ Note there are performance considerations involved with the *size* parameter.
+ For optimal performance, it is usually best to use the arraysize attribute.
+ If the *size* parameter is used, then it is best for it to retain the same
+ value from one :meth:`fetchmany` call to the next.
-.. method:: Cursor.fetchall()
+ .. method:: fetchall()
- Fetches all (remaining) rows of a query result, returning a list. Note that
- the cursor's arraysize attribute can affect the performance of this operation.
- An empty list is returned when no rows are available.
+ Fetches all (remaining) rows of a query result, returning a list. Note that
+ the cursor's arraysize attribute can affect the performance of this operation.
+ An empty list is returned when no rows are available.
-.. attribute:: Cursor.rowcount
+ .. attribute:: rowcount
- Although the :class:`Cursor` class of the :mod:`sqlite3` module implements this
- attribute, the database engine's own support for the determination of "rows
- affected"/"rows selected" is quirky.
+ Although the :class:`Cursor` class of the :mod:`sqlite3` module implements this
+ attribute, the database engine's own support for the determination of "rows
+ affected"/"rows selected" is quirky.
- For :meth:`executemany` statements, the number of modifications are summed up
- into :attr:`rowcount`.
+ For :meth:`executemany` statements, the number of modifications are summed up
+ into :attr:`rowcount`.
- As required by the Python DB API Spec, the :attr:`rowcount` attribute "is -1 in
- case no ``executeXX()`` has been performed on the cursor or the rowcount of the
- last operation is not determinable by the interface". This includes ``SELECT``
- statements because we cannot determine the number of rows a query produced
- until all rows were fetched.
+ As required by the Python DB API Spec, the :attr:`rowcount` attribute "is -1 in
+ case no ``executeXX()`` has been performed on the cursor or the rowcount of the
+ last operation is not determinable by the interface". This includes ``SELECT``
+ statements because we cannot determine the number of rows a query produced
+ until all rows were fetched.
- With SQLite versions before 3.6.5, :attr:`rowcount` is set to 0 if
- you make a ``DELETE FROM table`` without any condition.
+ With SQLite versions before 3.6.5, :attr:`rowcount` is set to 0 if
+ you make a ``DELETE FROM table`` without any condition.
-.. attribute:: Cursor.lastrowid
+ .. attribute:: lastrowid
- This read-only attribute provides the rowid of the last modified row. It is
- only set if you issued a ``INSERT`` statement using the :meth:`execute`
- method. For operations other than ``INSERT`` or when :meth:`executemany` is
- called, :attr:`lastrowid` is set to :const:`None`.
+ This read-only attribute provides the rowid of the last modified row. It is
+ only set if you issued a ``INSERT`` statement using the :meth:`execute`
+ method. For operations other than ``INSERT`` or when :meth:`executemany` is
+ called, :attr:`lastrowid` is set to :const:`None`.
-.. attribute:: Cursor.description
+ .. attribute:: description
- This read-only attribute provides the column names of the last query. To
- remain compatible with the Python DB API, it returns a 7-tuple for each
- column where the last six items of each tuple are :const:`None`.
+ This read-only attribute provides the column names of the last query. To
+ remain compatible with the Python DB API, it returns a 7-tuple for each
+ column where the last six items of each tuple are :const:`None`.
- It is set for ``SELECT`` statements without any matching rows as well.
+ It is set for ``SELECT`` statements without any matching rows as well.
.. _sqlite3-row-objects:
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list