mirror of https://github.com/python/cpython
Merge: Fix sqlite3 class markup.
This commit is contained in:
R David Murray
commit
b2bb60e401
|
|
@ -222,250 +222,254 @@ Connection Objects
|
|||
|
||||
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 @@ Cursor Objects
|
|||
|
||||
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:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue