Index: library/sqlite3.rst =================================================================== --- library/sqlite3.rst (revision 66816) +++ library/sqlite3.rst (working copy) @@ -27,7 +27,7 @@ You can also supply the special name ``:memory:`` to create a database in RAM. Once you have a :class:`Connection`, you can create a :class:`Cursor` object -and call its :meth:`execute` method to perform SQL commands:: +and call its :meth:`~Cursor.execute` method to perform SQL commands:: c = conn.cursor() @@ -52,7 +52,7 @@ Instead, use the DB-API's parameter substitution. Put ``?`` as a placeholder wherever you want to use a value, and then provide a tuple of values as the -second argument to the cursor's :meth:`execute` method. (Other database modules +second argument to the cursor's :meth:`~Cursor.execute` method. (Other database modules may use a different placeholder, such as ``%s`` or ``:1``.) For example:: # Never do this -- insecure! @@ -71,8 +71,8 @@ c.execute('insert into stocks values (?,?,?,?,?)', t) To retrieve data after executing a SELECT statement, you can either treat the -cursor as an :term:`iterator`, call the cursor's :meth:`fetchone` method to -retrieve a single matching row, or call :meth:`fetchall` to get a list of the +cursor as an :term:`iterator`, call the cursor's :meth:`~Cursor.fetchone` method to +retrieve a single matching row, or call :meth:`~Cursor.fetchall` to get a list of the matching rows. This example uses the iterator form:: @@ -130,7 +130,7 @@ returns. It will look for a string formed [mytype] in there, and then decide that 'mytype' is the type of the column. It will try to find an entry of 'mytype' in the converters dictionary and then use the converter function found - there to return the value. The column name found in :attr:`cursor.description` + there to return the value. The column name found in :attr:`Cursor.description` is only the first word of the column name, i. e. if you use something like ``'as "x [datetime]"'`` in your SQL, then we will parse out everything until the first blank for the column name: the column name would simply be "x". @@ -217,11 +217,13 @@ Connection Objects ------------------ -A :class:`Connection` instance has the following attributes and methods: +.. class:: Connection + A SQLite database connection has the following attributes and methods: + .. attribute:: Connection.isolation_level - Get or set the current isolation level. None for autocommit mode or one of + Get or set the current isolation level. :const:`None` for autocommit mode or one of "DEFERRED", "IMMEDIATE" or "EXLUSIVE". See section :ref:`sqlite3-controlling-transactions` for a more detailed explanation. @@ -236,7 +238,7 @@ .. method:: Connection.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 from + anything you did since the last call to ``commit()`` is not visible from 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. @@ -386,9 +388,9 @@ .. attribute:: Connection.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:`unicode` and the - :mod:`sqlite3` module will return Unicode objects for TEXT. If you want to + Using this attribute you can control what objects are returned for the ``TEXT`` + data type. By default, this attribute is set to :class:`unicode` and the + :mod:`sqlite3` module will return Unicode objects for ``TEXT``. If you want to return bytestrings instead, you can set it to :class:`str`. For efficiency reasons, there's also a way to return Unicode objects only for @@ -435,8 +437,9 @@ Cursor Objects -------------- -A :class:`Cursor` instance has the following attributes and methods: +.. class:: Cursor + A SQLite database cursor has the following attributes and methods: .. method:: Cursor.execute(sql, [parameters]) @@ -475,7 +478,7 @@ .. method:: Cursor.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 + at once. It issues a ``COMMIT`` statement first, then executes the SQL script it gets as a parameter. *sql_script* can be a bytestring or a Unicode string. @@ -488,7 +491,7 @@ .. method:: Cursor.fetchone() Fetches the next row of a query result set, returning a single sequence, - or ``None`` when no more data is available. + or :const:`None` when no more data is available. .. method:: Cursor.fetchmany([size=cursor.arraysize]) @@ -527,8 +530,8 @@ 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". + 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. @@ -540,6 +543,81 @@ method. For operations other than ``INSERT`` or when :meth:`executemany` is called, :attr:`lastrowid` is set to :const:`None`. +.. attribute:: Cursor.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`. + + It is set for ``SELECT`` statements without any matching rows as well. + +.. _sqlite3-row-objects: + +Row Objects +----------- + +.. class:: Row + + A :class:`Row` instance serves as a highly optimized + :attr:`~Connection.row_factory` for :class:`Connection` objects. + It tries to mimic a tuple in most of its features. + + It supports mapping access by column name and index, iteration, + representation, equality testing and :func:`len`. + + If two :class:`Row` objects have exactly the same columns and their + members are equal, they compare equal. + + .. versionchanged:: 2.6 + Added iteration and equality (hashability). + + .. method:: keys + + This method returns a tuple of column names. Immediately after a query, + it is the first member of each tuple in :attr:`Cursor.description`. + + .. versionadded:: 2.6 + +Let's assume we initialize a table as in the example given above:: + + conn = sqlite3.connect(":memory:") + c = conn.cursor() + c.execute('''create table stocks + (date text, trans text, symbol text, + qty real, price real)''') + c.execute("""insert into stocks + values ('2006-01-05','BUY','RHAT',100,35.14)""") + conn.commit() + c.close() + +Now we plug :class:`Row` in:: + + >>> conn.row_factory = sqlite3.Row + >>> c = conn.cursor() + >>> c.execute('select * from stocks') + + >>> r = c.fetchone() + >>> type(r) + + >>> r + (u'2006-01-05', u'BUY', u'RHAT', 100.0, 35.140000000000001) + >>> len(r) + 5 + >>> r[2] + u'RHAT' + >>> r.keys() + ['date', 'trans', 'symbol', 'qty', 'price'] + >>> r['qty'] + 100.0 + >>> for member in r: print member + ... + 2006-01-05 + BUY + RHAT + 100.0 + 35.14 + + .. _sqlite3-types: SQLite and Python types @@ -549,43 +627,46 @@ Introduction ^^^^^^^^^^^^ -SQLite natively supports the following types: NULL, INTEGER, REAL, TEXT, BLOB. +SQLite natively supports the following types: ``NULL``, ``INTEGER``, +``REAL``, ``TEXT``, ``BLOB``. The following Python types can thus be sent to SQLite without any problem: -+------------------------+-------------+ -| Python type | SQLite type | -+========================+=============+ -| ``None`` | NULL | -+------------------------+-------------+ -| ``int`` | INTEGER | -+------------------------+-------------+ -| ``long`` | INTEGER | -+------------------------+-------------+ -| ``float`` | REAL | -+------------------------+-------------+ -| ``str (UTF8-encoded)`` | TEXT | -+------------------------+-------------+ -| ``unicode`` | TEXT | -+------------------------+-------------+ -| ``buffer`` | BLOB | -+------------------------+-------------+ ++-----------------------------+-------------+ +| Python type | SQLite type | ++=============================+=============+ +| :const:`None` | ``NULL`` | ++-----------------------------+-------------+ +| :class:`int` | ``INTEGER`` | ++-----------------------------+-------------+ +| :class:`long` | ``INTEGER`` | ++-----------------------------+-------------+ +| :class:`float` | ``REAL`` | ++-----------------------------+-------------+ +| :class:`str` (UTF8-encoded) | ``TEXT`` | ++-----------------------------+-------------+ +| :class:`unicode` | ``TEXT`` | ++-----------------------------+-------------+ +| :class:`buffer` | ``BLOB`` | ++-----------------------------+-------------+ This is how SQLite types are converted to Python types by default: -+-------------+---------------------------------------------+ -| SQLite type | Python type | -+=============+=============================================+ -| ``NULL`` | None | -+-------------+---------------------------------------------+ -| ``INTEGER`` | int or long, depending on size | -+-------------+---------------------------------------------+ -| ``REAL`` | float | -+-------------+---------------------------------------------+ -| ``TEXT`` | depends on text_factory, unicode by default | -+-------------+---------------------------------------------+ -| ``BLOB`` | buffer | -+-------------+---------------------------------------------+ ++-------------+----------------------------------------------+ +| SQLite type | Python type | ++=============+==============================================+ +| ``NULL`` | :const:`None` | ++-------------+----------------------------------------------+ +| ``INTEGER`` | :class:`int` or :class:`long`, | +| | depending on size | ++-------------+----------------------------------------------+ +| ``REAL`` | :class:`float` | ++-------------+----------------------------------------------+ +| ``TEXT`` | depends on :attr:`~Connection.text_factory`, | +| | :class:`unicode` by default | ++-------------+----------------------------------------------+ +| ``BLOB`` | :class:`buffer` | ++-------------+----------------------------------------------+ The type system of the :mod:`sqlite3` module is extensible in two ways: you can store additional Python types in a SQLite database via object adaptation, and @@ -713,9 +794,10 @@ ------------------------ By default, the :mod:`sqlite3` module opens transactions implicitly before a -Data Modification Language (DML) statement (i.e. INSERT/UPDATE/DELETE/REPLACE), -and commits transactions implicitly before a non-DML, non-query statement (i. e. -anything other than SELECT/INSERT/UPDATE/DELETE/REPLACE). +Data Modification Language (DML) statement (i.e. +``INSERT``/``UPDATE``/``DELETE``/``REPLACE``), and commits transactions +implicitly before a non-DML, non-query statement (i. e. +anything other than ``SELECT`` or the aforementioned). So if you are within a transaction and issue a command like ``CREATE TABLE ...``, ``VACUUM``, ``PRAGMA``, the :mod:`sqlite3` module will commit implicitly @@ -724,7 +806,7 @@ is that pysqlite needs to keep track of the transaction state (if a transaction is active or not). -You can control which kind of "BEGIN" statements pysqlite implicitly executes +You can control which kind of ``BEGIN`` statements pysqlite implicitly executes (or none at all) via the *isolation_level* parameter to the :func:`connect` call, or via the :attr:`isolation_level` property of connections. @@ -748,7 +830,7 @@ be written more concisely because you don't have to create the (often superfluous) :class:`Cursor` objects explicitly. Instead, the :class:`Cursor` objects are created implicitly and these shortcut methods return the cursor -objects. This way, you can execute a SELECT statement and iterate over it +objects. This way, you can execute a ``SELECT`` statement and iterate over it directly using only a single call on the :class:`Connection` object. .. literalinclude:: ../includes/sqlite3/shortcut_methods.py