From: R David Murray Date: Mon, 1 Oct 2012 00:49:19 +0000 (-0400) Subject: Merge: Fix sqlite3 class markup. X-Git-Tag: v3.4.0a1~2430^2 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=842ca5f15d01a0b454299c933b42f5f31873d19f;p=python Merge: Fix sqlite3 class markup. --- 842ca5f15d01a0b454299c933b42f5f31873d19f diff --cc Doc/library/sqlite3.rst index e0fd50e231,93f6d825f2..7d156def45 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@@ -222,250 -222,238 +222,254 @@@ Connection Object 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 - ` 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 + ` 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 - ` 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 + ` 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 - ` 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 + ` 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: