Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
................
r66801 | andrew.kuchling | 2008-10-04 23:51:59 +0200 (Sat, 04 Oct 2008) | 1 line
Punctuation fix; expand dict.update docstring to be clearer
................
r66803 | benjamin.peterson | 2008-10-05 00:15:31 +0200 (Sun, 05 Oct 2008) | 1 line
fix typo
................
r66804 | andrew.kuchling | 2008-10-05 02:11:56 +0200 (Sun, 05 Oct 2008) | 1 line
#1415508 from Rocky Bernstein: add docstrings for enable_interspersed_args(), disable_interspersed_args()
................
r66813 | andrew.kuchling | 2008-10-06 14:07:04 +0200 (Mon, 06 Oct 2008) | 3 lines
Per Greg Ward, optparse is no longer being externally maintained.
I'll look at the bugs in the Optik bug tracker and copy them to the Python bug
tracker if they're still relevant.
................
r66854 | georg.brandl | 2008-10-08 19:20:20 +0200 (Wed, 08 Oct 2008) | 2 lines
#4059: patch up some sqlite docs.
................
r66855 | georg.brandl | 2008-10-08 19:30:55 +0200 (Wed, 08 Oct 2008) | 2 lines
#4058: fix some whatsnew markup.
................
r66856 | georg.brandl | 2008-10-08 20:47:17 +0200 (Wed, 08 Oct 2008) | 3 lines
#3935: properly support list subclasses in the C impl. of bisect.
Patch reviewed by Raymond.
................
r66866 | benjamin.peterson | 2008-10-09 22:54:43 +0200 (Thu, 09 Oct 2008) | 1 line
update paragraph about __future__ for 2.6
................
r66870 | armin.rigo | 2008-10-10 10:40:44 +0200 (Fri, 10 Oct 2008) | 2 lines
Typo: "ThreadError" is the name in the C source.
................
r66871 | benjamin.peterson | 2008-10-10 22:38:49 +0200 (Fri, 10 Oct 2008) | 1 line
fix a small typo
................
r66872 | benjamin.peterson | 2008-10-10 22:51:37 +0200 (Fri, 10 Oct 2008) | 1 line
talk about how you can unzip with zip
................
r66874 | benjamin.peterson | 2008-10-11 00:23:41 +0200 (Sat, 11 Oct 2008) | 1 line
PyGILState_Acquire -> PyGILState_Ensure
................
r66887 | benjamin.peterson | 2008-10-13 23:51:40 +0200 (Mon, 13 Oct 2008) | 1 line
document how to disable fixers
................
r66903 | benjamin.peterson | 2008-10-15 22:34:09 +0200 (Wed, 15 Oct 2008) | 1 line
don't recurse into directories that start with '.'
................
r66905 | benjamin.peterson | 2008-10-15 23:05:55 +0200 (Wed, 15 Oct 2008) | 1 line
support the optional line argument for idle
................
r66911 | benjamin.peterson | 2008-10-16 01:10:28 +0200 (Thu, 16 Oct 2008) | 41 lines
Merged revisions 66805,66841,66860,66884-66886,66893,66907,66910 via svnmerge from
svn+ssh://pythondev@svn.python.org/sandbox/trunk/2to3/lib2to3
........
r66805 | benjamin.peterson | 2008-10-04 20:11:02 -0500 (Sat, 04 Oct 2008) | 1 line
mention what the fixes directory is for
........
r66841 | benjamin.peterson | 2008-10-07 17:48:12 -0500 (Tue, 07 Oct 2008) | 1 line
use assertFalse and assertTrue
........
r66860 | benjamin.peterson | 2008-10-08 16:05:07 -0500 (Wed, 08 Oct 2008) | 1 line
instead of abusing the pattern matcher, use start_tree to find a next binding
........
r66884 | benjamin.peterson | 2008-10-13 15:50:30 -0500 (Mon, 13 Oct 2008) | 1 line
don't print tokens to stdout when -v is given
........
r66885 | benjamin.peterson | 2008-10-13 16:28:57 -0500 (Mon, 13 Oct 2008) | 1 line
add the -x option to disable fixers
........
r66886 | benjamin.peterson | 2008-10-13 16:33:53 -0500 (Mon, 13 Oct 2008) | 1 line
cut down on some crud
........
r66893 | benjamin.peterson | 2008-10-14 17:16:54 -0500 (Tue, 14 Oct 2008) | 1 line
add an optional set literal fixer
........
r66907 | benjamin.peterson | 2008-10-15 16:59:41 -0500 (Wed, 15 Oct 2008) | 1 line
don't write backup files by default
........
r66910 | benjamin.peterson | 2008-10-15 17:43:10 -0500 (Wed, 15 Oct 2008) | 1 line
add the -n option; it stops backupfiles from being written
........
................
r66913 | benjamin.peterson | 2008-10-16 20:52:14 +0200 (Thu, 16 Oct 2008) | 1 line
document that deque indexing is O(n) #4123
................
r66927 | andrew.kuchling | 2008-10-16 22:15:47 +0200 (Thu, 16 Oct 2008) | 1 line
Fix wording (2.6.1 backport candidate)
................
r66932 | benjamin.peterson | 2008-10-16 23:09:28 +0200 (Thu, 16 Oct 2008) | 1 line
check for error conditions in _json #3623
................
r66938 | benjamin.peterson | 2008-10-16 23:27:54 +0200 (Thu, 16 Oct 2008) | 1 line
fix possible ref leak
................
r66942 | benjamin.peterson | 2008-10-16 23:48:06 +0200 (Thu, 16 Oct 2008) | 1 line
fix more possible ref leaks in _json and use Py_CLEAR
................
r66962 | benjamin.peterson | 2008-10-17 22:01:01 +0200 (Fri, 17 Oct 2008) | 1 line
clarify CALL_FUNCTION #4141
................
r66964 | georg.brandl | 2008-10-17 23:41:49 +0200 (Fri, 17 Oct 2008) | 2 lines
Fix duplicate word.
................
r66973 | armin.ronacher | 2008-10-19 10:27:43 +0200 (Sun, 19 Oct 2008) | 3 lines
Fixed #4067 by implementing _attributes and _fields for the AST root node.
................
r66974 | benjamin.peterson | 2008-10-19 15:59:01 +0200 (Sun, 19 Oct 2008) | 1 line
fix compiler warning
................
r66977 | benjamin.peterson | 2008-10-19 21:39:16 +0200 (Sun, 19 Oct 2008) | 1 line
mention -n
................
r66992 | benjamin.peterson | 2008-10-21 22:51:13 +0200 (Tue, 21 Oct 2008) | 1 line
make sure to call iteritems()
................
r66998 | benjamin.peterson | 2008-10-22 22:57:43 +0200 (Wed, 22 Oct 2008) | 1 line
fix a few typos
................
r66999 | benjamin.peterson | 2008-10-22 23:05:30 +0200 (Wed, 22 Oct 2008) | 1 line
and another typo...
................
r67002 | hirokazu.yamamoto | 2008-10-23 02:37:33 +0200 (Thu, 23 Oct 2008) | 1 line
Issue #4183: Some tests didn't run with pickle.HIGHEST_PROTOCOL.
................
r67005 | walter.doerwald | 2008-10-23 15:11:39 +0200 (Thu, 23 Oct 2008) | 2 lines
Use the correct names of the stateless codec functions (Fixes issue 4178).
................
r67007 | benjamin.peterson | 2008-10-23 23:43:48 +0200 (Thu, 23 Oct 2008) | 1 line
only nonempty __slots__ don't work
................
r67028 | benjamin.peterson | 2008-10-26 01:27:07 +0200 (Sun, 26 Oct 2008) | 1 line
don't use a catch-all
................
r67040 | armin.rigo | 2008-10-28 18:01:21 +0100 (Tue, 28 Oct 2008) | 5 lines
Fix one of the tests: it relied on being present in an "output test" in
order to actually test what it was supposed to test, i.e. that the code
in the __del__ method did not crash. Use instead the new helper
test_support.captured_output().
................
r67041 | benjamin.peterson | 2008-10-29 21:33:00 +0100 (Wed, 29 Oct 2008) | 1 line
mention the version gettempdir() was added
................
r67044 | amaury.forgeotdarc | 2008-10-30 00:15:57 +0100 (Thu, 30 Oct 2008) | 3 lines
Correct error message in io.open():
closefd=True is the only accepted value with a file name.
................
r67070 | benjamin.peterson | 2008-10-31 21:41:44 +0100 (Fri, 31 Oct 2008) | 1 line
rephrase has_key doc
................
r67089 | benjamin.peterson | 2008-11-03 21:43:20 +0100 (Mon, 03 Nov 2008) | 1 line
clarify by splitting into multiple paragraphs
................
r67091 | benjamin.peterson | 2008-11-03 23:34:57 +0100 (Mon, 03 Nov 2008) | 1 line
move a FileIO test to test_fileio
................
r67101 | georg.brandl | 2008-11-04 21:49:35 +0100 (Tue, 04 Nov 2008) | 2 lines
#4167: fix markup glitches.
................
r67117 | georg.brandl | 2008-11-06 11:17:58 +0100 (Thu, 06 Nov 2008) | 2 lines
#4268: Use correct module for two toplevel functions.
................
r67118 | georg.brandl | 2008-11-06 11:19:11 +0100 (Thu, 06 Nov 2008) | 2 lines
#4267: small fixes in sqlite3 docs.
................
r67119 | georg.brandl | 2008-11-06 11:20:49 +0100 (Thu, 06 Nov 2008) | 2 lines
#4245: move Thread section to the top.
................
r67123 | georg.brandl | 2008-11-06 19:49:15 +0100 (Thu, 06 Nov 2008) | 2 lines
#4247: add "pass" examples to tutorial.
................
r67124 | andrew.kuchling | 2008-11-06 20:23:02 +0100 (Thu, 06 Nov 2008) | 1 line
Fix grammar error; reword two paragraphs
................
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index 6185a59..6235f9e 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -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!
@@ -64,15 +64,15 @@
c.execute('select * from stocks where symbol=?', t)
# Larger example
- for t in (('2006-03-28', 'BUY', 'IBM', 1000, 45.00),
+ for t in [('2006-03-28', 'BUY', 'IBM', 1000, 45.00),
('2006-04-05', 'BUY', 'MSOFT', 1000, 72.00),
('2006-04-06', 'SELL', 'IBM', 500, 53.00),
- ):
+ ]:
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
@@ -424,10 +426,9 @@
import sqlite3, os
con = sqlite3.connect('existing_db.db')
- full_dump = os.linesep.join(con.iterdump())
- f = open('dump.sql', 'w')
- f.writelines(full_dump)
- f.close()
+ with open('dump.sql', 'w') as f:
+ for line in con.iterdump():
+ f.write('%s\n' % line)
.. _sqlite3-cursor-objects:
@@ -435,8 +436,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 +477,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 +490,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 +529,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 +542,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')
+ <sqlite3.Cursor object at 0x7f4e7dd8fa80>
+ >>> r = c.fetchone()
+ >>> type(r)
+ <type 'sqlite3.Row'>
+ >>> 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 +626,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 +793,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,15 +805,15 @@
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.
If you want **autocommit mode**, then set :attr:`isolation_level` to None.
Otherwise leave it at its default, which will result in a plain "BEGIN"
-statement, or set it to one of SQLite's supported isolation levels: DEFERRED,
-IMMEDIATE or EXCLUSIVE.
+statement, or set it to one of SQLite's supported isolation levels: "DEFERRED",
+"IMMEDIATE" or "EXCLUSIVE".
@@ -748,7 +829,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