Mailman 3 October 2012 - Python-checkins

cpython (3.3): More additions to whatsnew.
by r.david.murray 01 Oct '12

01 Oct '12

http://hg.python.org/cpython/rev/0ab4257e685d changeset: 79357:0ab4257e685d branch: 3.3 parent: 79354:2299ebc0698b user: R David Murray <rdmurray(a)bitdance.com> date: Sun Sep 30 21:59:56 2012 -0400 summary: More additions to whatsnew. files: Doc/whatsnew/3.3.rst | 72 ++++++++++++++++++++++++------- Misc/NEWS | 8 +- 2 files changed, 60 insertions(+), 20 deletions(-) diff --git a/Doc/whatsnew/3.3.rst b/Doc/whatsnew/3.3.rst --- a/Doc/whatsnew/3.3.rst +++ b/Doc/whatsnew/3.3.rst @@ -1325,6 +1325,11 @@ package transparently encodes and decodes the unicode to and from the RFC standard Content Transfer Encodings. +Other API Changes +~~~~~~~~~~~~~~~~~ + +Added :class:`email.parser.BytesHeaderParser`. + ftplib ------ @@ -1371,6 +1376,16 @@ (Contributed by Ezio Melotti in :issue:`11113` and :issue:`15156`) +http +---- + +:class:`http.server.BaseHTTPRequestHandler` now buffers the headers and writes +them all at once when :meth:`~http.server.BaseHTTPRequestHandler.end_headers` is +called. A new method :meth:`~http.server.BaseHTTPRequestHandler.flush_headers` +can be used to directly manage when the accumlated headers are sent. +(Contributed by Andrew Schaaf in :issue:`3709`.) + + html.parser ----------- @@ -1385,6 +1400,7 @@ :issue:`755670`, :issue:`13357`, :issue:`12629`, :issue:`1200313`, :issue:`670664`, :issue:`13273`, :issue:`12888`, :issue:`7311`) + imaplib ------- @@ -1427,6 +1443,20 @@ underlying binary buffer. +itertools +--------- + +:func:`~itertools.accumulate` now takes an optional ``func`` argument for +providing a user-supplied binary function. + + +logging +------- + +:func:`~logging.basicConfig` now supports an optional ``handlers`` argument +taking an iterable of handlers to be added to the root logger. + + math ---- @@ -1775,6 +1805,15 @@ (Contributed by Ross Lagerwall in :issue:`10866`.) +sqlite3 +------- + +New :class:`sqlite3.Connection` method +:meth:`~sqlite3.Connection.set_trace_callback` can be used to capture a trace of +all sql commands processed by sqlite. (Contributed by Torsten Landschoff +in :issue:`11688`.) + + ssl --- @@ -1788,41 +1827,37 @@ * The :mod:`ssl` module now exposes a finer-grained exception hierarchy in order to make it easier to inspect the various kinds of errors. - (Contributed by Antoine Pitrou in :issue:`11183`) * :meth:`~ssl.SSLContext.load_cert_chain` now accepts a *password* argument to be used if the private key is encrypted. - (Contributed by Adam Simpkins in :issue:`12803`) * Diffie-Hellman key exchange, both regular and Elliptic Curve-based, is now supported through the :meth:`~ssl.SSLContext.load_dh_params` and :meth:`~ssl.SSLContext.set_ecdh_curve` methods. - (Contributed by Antoine Pitrou in :issue:`13626` and :issue:`13627`) * SSL sockets have a new :meth:`~ssl.SSLSocket.get_channel_binding` method allowing the implementation of certain authentication mechanisms such as - SCRAM-SHA-1-PLUS. - - (Contributed by Jacek Konieczny in :issue:`12551`) + SCRAM-SHA-1-PLUS. (Contributed by Jacek Konieczny in :issue:`12551`) * You can query the SSL compression algorithm used by an SSL socket, thanks to its new :meth:`~ssl.SSLSocket.compression` method. - (Contributed by Antoine Pitrou in :issue:`13634`) * Support has been added for the Next Procotol Negotiation extension using the :meth:`ssl.SSLContext.set_npn_protocols` method. - (Contributed by Colin Marc in :issue:`14204`) * SSL errors can now be introspected more easily thanks to :attr:`~ssl.SSLError.library` and :attr:`~ssl.SSLError.reason` attributes. - (Contributed by Antoine Pitrou in :issue:`14837`) +* The :func:`~ssl.get_server_certificate` function now supports IPv6. + (Contributed by Charles-François Natali in :issue:`11811`.) + + stat ---- @@ -1837,7 +1872,7 @@ ---------- Command strings can now be bytes objects on posix platforms. (Contributed by -Victor Stiner in :issue:`8513`.) +Victor Stinner in :issue:`8513`.) A new constant :data:`~subprocess.DEVNULL` allows suppressing output in a platform-independent fashion. (Contributed by Ross Lagerwall in @@ -1848,18 +1883,15 @@ --- The :mod:`sys` module has a new :data:`~sys.thread_info` :term:`struct -sequence` holding informations about the thread implementation. - -(:issue:`11223`) +sequence` holding informations about the thread implementation +(:issue:`11223`). textwrap -------- The :mod:`textwrap` module has a new :func:`~textwrap.indent` that makes it straightforward to add a common prefix to selected lines in a block -of text. - -(:issue:`13857`) +of text (:issue:`13857`). threading @@ -2222,6 +2254,14 @@ :exc:`poplib.error_proto` errors may need to be changed if errors on ``quit`` are encountered by a particular application (:issue:`11291`). +* The ``strict`` argument to :class:`email.parser.Parser`, deprecated since + Python 2.4, has finally been removed. + +* The deprecated method ``unittest.TestCase.assertSameElements`` has been + removed. + +* The deprecated variable ``time.accept2dyear`` has been removed. + Porting C code -------------- diff --git a/Misc/NEWS b/Misc/NEWS --- a/Misc/NEWS +++ b/Misc/NEWS @@ -3386,9 +3386,9 @@ - Issue #12011: signal.signal() and signal.siginterrupt() raise an OSError, instead of a RuntimeError: OSError has an errno attribute. -- Issue #3709: a flush_headers method to BaseHTTPRequestHandler which manages - the sending of headers to output stream and flushing the internal headers - buffer. Patch contribution by Andrew Schaaf +- Issue #3709: add a flush_headers method to BaseHTTPRequestHandler, which + manages the sending of headers to output stream and flushing the internal + headers buffer. Patch contribution by Andrew Schaaf - Issue #11743: Rewrite multiprocessing connection classes in pure Python. @@ -4982,7 +4982,7 @@ - Issue #3709: BaseHTTPRequestHandler will buffer the headers and write to output stream only when end_headers is invoked. This is a speedup and an - internal optimization. Patch by endian. + internal optimization. Patch by Andrew Shaaf. - Issue #10220: Added inspect.getgeneratorstate. Initial patch by Rodolpho Eckhardt. -- Repository URL: http://hg.python.org/cpython

1 0

cpython (2.7): Fix sqlite3 class markup.
by r.david.murray 01 Oct '12

01 Oct '12

http://hg.python.org/cpython/rev/bf8f92580c54 changeset: 79356:bf8f92580c54 branch: 2.7 parent: 79343:8f07ab82de92 user: R David Murray <rdmurray(a)bitdance.com> date: Sun Sep 30 21:04:46 2012 -0400 summary: Fix sqlite3 class markup. files: Doc/library/sqlite3.rst | 426 ++++++++++++++-------------- 1 files changed, 213 insertions(+), 213 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -231,236 +231,236 @@ 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. -.. 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: unicode, str, int, - long, float, buffer and None. + The function can return any of the types supported by SQLite: unicode, str, int, + long, float, buffer 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: - unicode, str, int, long, float, buffer and None. + The ``finalize`` method can return any of the types supported by SQLite: + unicode, str, int, long, float, buffer 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*. - .. versionadded:: 2.6 + .. versionadded:: 2.6 -.. 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:: 2.7 + .. versionadded:: 2.7 - .. 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:: 2.7 + .. versionadded:: 2.7 -.. 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:`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`. + 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 - non-ASCII data, and bytestrings otherwise. To activate it, set this attribute to - :const:`sqlite3.OptimizedUnicode`. + For efficiency reasons, there's also a way to return Unicode objects only for + non-ASCII data, and bytestrings otherwise. To activate it, set this attribute to + :const:`sqlite3.OptimizedUnicode`. - You can also set it to any other callable that accepts a single bytestring - parameter and returns the resulting object. + You can also set it to any other callable that accepts a single bytestring + parameter and returns the resulting object. - See the following example code for illustration: + See the following example code for illustration: - .. literalinclude:: ../includes/sqlite3/text_factory.py + .. literalinclude:: ../includes/sqlite3/text_factory.py -.. attribute:: Connection.total_changes + .. attribute:: total_changes - Returns the total number of database rows that have been modified, inserted, or - deleted since the database connection was opened. + Returns the total number of database rows that have been modified, inserted, or + deleted since the database connection was opened. -.. attribute:: Connection.iterdump + .. attribute:: 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. + 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. - .. versionadded:: 2.6 + .. versionadded:: 2.6 - Example:: + Example:: - # Convert file existing_db.db to SQL dump file dump.sql - import sqlite3, os + # 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) + 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: @@ -472,110 +472,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 parameterized (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 parameterized (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 a bytestring or a Unicode string. + *sql_script* can be a bytestring or a Unicode string. - 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

1 0

cpython (merge 3.3 -> default): Merge: Fix sqlite3 class markup.
by r.david.murray 01 Oct '12

01 Oct '12

http://hg.python.org/cpython/rev/da6310c5da09 changeset: 79355:da6310c5da09 parent: 79352:cc79da8c8970 parent: 79354:2299ebc0698b user: R David Murray <rdmurray(a)bitdance.com> date: Sun Sep 30 20:50:12 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

1 0

cpython (merge 3.2 -> 3.3): Merge: Fix sqlite3 class markup.
by r.david.murray 01 Oct '12

01 Oct '12

http://hg.python.org/cpython/rev/2299ebc0698b changeset: 79354:2299ebc0698b branch: 3.3 parent: 79351:5242ccd0a3f6 parent: 79353:c8b94273c5ee user: R David Murray <rdmurray(a)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

1 0

cpython (3.2): Fix sqlite3 class markup.
by r.david.murray 01 Oct '12

01 Oct '12

http://hg.python.org/cpython/rev/c8b94273c5ee changeset: 79353:c8b94273c5ee branch: 3.2 parent: 79344:cb988d601803 user: R David Murray <rdmurray(a)bitdance.com> date: Sun Sep 30 20:44:43 2012 -0400 summary: Fix sqlite3 class markup. files: Doc/library/sqlite3.rst | 430 ++++++++++++++-------------- 1 files changed, 215 insertions(+), 215 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -222,238 +222,238 @@ 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.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`. - 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`. + 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`. - You can also set it to any other callable that accepts a single bytestring - parameter and returns the resulting object. + You can also set it to any other callable that accepts a single bytestring + parameter and returns the resulting object. - See the following example code for illustration: + See the following example code for illustration: - .. literalinclude:: ../includes/sqlite3/text_factory.py + .. literalinclude:: ../includes/sqlite3/text_factory.py -.. attribute:: Connection.total_changes + .. attribute:: total_changes - Returns the total number of database rows that have been modified, inserted, or - deleted since the database connection was opened. + Returns the total number of database rows that have been modified, inserted, or + deleted since the database connection was opened. -.. attribute:: Connection.iterdump + .. attribute:: 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. + 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. - Example:: + Example:: - # Convert file existing_db.db to SQL dump file dump.sql - import sqlite3, os + # 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) + 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: @@ -465,110 +465,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

1 0

cpython (merge 3.3 -> default): Merge: More whatsnew adds, especially the os module.
by r.david.murray 01 Oct '12

01 Oct '12

http://hg.python.org/cpython/rev/cc79da8c8970 changeset: 79352:cc79da8c8970 parent: 79350:abb5c5bde872 parent: 79351:5242ccd0a3f6 user: R David Murray <rdmurray(a)bitdance.com> date: Sun Sep 30 20:09:04 2012 -0400 summary: Merge: More whatsnew adds, especially the os module. I went through all the versionchanged/versionadded tags in the os doc page for this changeset. files: Doc/whatsnew/3.3.rst | 51 ++++++++++++++++++++++++++----- Misc/NEWS | 4 +- 2 files changed, 45 insertions(+), 10 deletions(-) diff --git a/Doc/whatsnew/3.3.rst b/Doc/whatsnew/3.3.rst --- a/Doc/whatsnew/3.3.rst +++ b/Doc/whatsnew/3.3.rst @@ -1504,12 +1504,20 @@ :func:`~os.link`, :func:`~os.lstat`, :func:`~os.mkdir`, :func:`~os.mkfifo`, :func:`~os.mknod`, :func:`~os.open`, :func:`~os.readlink`, :func:`~os.remove`, :func:`~os.rename`, :func:`~os.replace`, :func:`~os.rmdir`, :func:`~os.stat`, - :func:`~os.symlink`, :func:`~os.unlink`, :func:`~os.utime`. + :func:`~os.symlink`, :func:`~os.unlink`, :func:`~os.utime`. Platform + support for using these parameters can be checked via the sets + :data:`os.supports_dir_fd` and :data:`os.supports_follows_symlinks`. - The following functions now support a file descriptor for their path argument: :func:`~os.chdir`, :func:`~os.chmod`, :func:`~os.chown`, :func:`~os.execve`, :func:`~os.listdir`, :func:`~os.pathconf`, :func:`~os.path.exists`, - :func:`~os.stat`, :func:`~os.statvfs`, :func:`~os.utime`. + :func:`~os.stat`, :func:`~os.statvfs`, :func:`~os.utime`. Platform support + for this can be checked via the :data:`os.supports_fd` set. + +* :func:`~os.access` accepts an ``effective_ids`` keyword argument to turn on + using the effective uid/gid rather than the real uid/gid in the access check. + Platform support for this can be checked via the + :data:`~os.supports_effective_ids` set. * The :mod:`os` module has two new functions: :func:`~os.getpriority` and :func:`~os.setpriority`. They can be used to get or set process @@ -1558,7 +1566,7 @@ for a file. * :func:`~os.sync`: Force write of everything to disk. -* Add some extra posix functions to the os module: +* Additional new posix functions: * :func:`~os.lockf`: Apply, test or remove a POSIX lock on an open file descriptor. * :func:`~os.pread`: Read from a file descriptor at an offset, the file @@ -1577,6 +1585,12 @@ * :func:`~os.times` and :func:`~os.uname`: Return type changed from a tuple to a tuple-like object with named attributes. +* Some platforms now support additional constants for the :func:`~os.lseek` + function, such as ``os.SEEK_HOLE`` and ``os.SEEK_DATA``. + +* :func:`os.symlink` now accepts (and ignores) the ``target_is_directory`` + keyword argument on non-Windows platforms, to ease cross-platform support. + pdb --- @@ -1703,6 +1717,14 @@ instead of a RuntimeError: OSError has an errno attribute. +smtp +---- + +:class:`~smtplib.SMTP` now supports the context manager protocol, allowing an +``SMTP`` instance to be used in a ``with`` statement. (Contributed +by Giampaolo Rodolà in :issue:`11289`.) + + smtpd ----- @@ -1810,6 +1832,18 @@ (Contributed by Giampaolo Rodolà in :issue:`14807`) + +subprocess +---------- + +Command strings can now be bytes objects on posix platforms. (Contributed by +Victor Stiner in :issue:`8513`.) + +A new constant :data:`~subprocess.DEVNULL` allows suppressing output in a +platform-independent fashion. (Contributed by Ross Lagerwall in +:issue:`5870`.) + + sys --- @@ -1872,10 +1906,11 @@ :meth:`.assertRaises`, :meth:`.assertRaisesRegex`, :meth:`.assertWarns`, and :meth:`.assertWarnsRegex` now accept a keyword argument *msg* when used as -context managers. - -(Contributed by Ezio Melotti and Winston Ewert in :issue:`10775`) - +context managers. (Contributed by Ezio Melotti and Winston Ewert in +:issue:`10775`) + +:meth:`unittest.TestCase.run` now returns the :class:`~unittest.TestResult` +object. urllib ------ @@ -1993,7 +2028,7 @@ * :meth:`ftplib.FTP.nlst` and :meth:`ftplib.FTP.dir`: use :meth:`ftplib.FTP.mlsd` * :func:`platform.popen`: use the :mod:`subprocess` module. Check especially - the :ref:`subprocess-replacements` section. + the :ref:`subprocess-replacements` section (:issue:`11377`). * :issue:`13374`: The Windows bytes API has been deprecated in the :mod:`os` module. Use Unicode filenames, instead of bytes filenames, to not depend on the ANSI code page anymore and to support any filename. diff --git a/Misc/NEWS b/Misc/NEWS --- a/Misc/NEWS +++ b/Misc/NEWS @@ -3700,7 +3700,7 @@ not installed. Instead, the zipfile.ZIP_STORED compression is used to create the ZipFile. Patch by Natalia B. Bidart. -- Issue #11289: `smtp.SMTP` class becomes a context manager so it can be used +- Issue #11289: `smtp.SMTP` class is now a context manager so it can be used in a `with` statement. Contributed by Giampaolo Rodola. - Issue #11554: Fixed support for Japanese codecs; previously the body output @@ -3712,7 +3712,7 @@ - Issue #11407: `TestCase.run` returns the result object used or created. Contributed by Janathan Hartley. -- Issue #11500: Fixed a bug in the os x proxy bypass code for fully qualified +- Issue #11500: Fixed a bug in the OS X proxy bypass code for fully qualified IP addresses in the proxy exception list. - Issue #11491: dbm.error is no longer raised when dbm.open is called with -- Repository URL: http://hg.python.org/cpython

1 0

cpython (3.3): More whatsnew adds, especially the os module.
by r.david.murray 01 Oct '12

01 Oct '12

http://hg.python.org/cpython/rev/5242ccd0a3f6 changeset: 79351:5242ccd0a3f6 branch: 3.3 parent: 79349:4258248a44c7 user: R David Murray <rdmurray(a)bitdance.com> date: Sun Sep 30 20:07:42 2012 -0400 summary: More whatsnew adds, especially the os module. I went through all the versionchanged/versionadded tags in the os doc page for this changeset. files: Doc/whatsnew/3.3.rst | 51 ++++++++++++++++++++++++++----- Misc/NEWS | 4 +- 2 files changed, 45 insertions(+), 10 deletions(-) diff --git a/Doc/whatsnew/3.3.rst b/Doc/whatsnew/3.3.rst --- a/Doc/whatsnew/3.3.rst +++ b/Doc/whatsnew/3.3.rst @@ -1504,12 +1504,20 @@ :func:`~os.link`, :func:`~os.lstat`, :func:`~os.mkdir`, :func:`~os.mkfifo`, :func:`~os.mknod`, :func:`~os.open`, :func:`~os.readlink`, :func:`~os.remove`, :func:`~os.rename`, :func:`~os.replace`, :func:`~os.rmdir`, :func:`~os.stat`, - :func:`~os.symlink`, :func:`~os.unlink`, :func:`~os.utime`. + :func:`~os.symlink`, :func:`~os.unlink`, :func:`~os.utime`. Platform + support for using these parameters can be checked via the sets + :data:`os.supports_dir_fd` and :data:`os.supports_follows_symlinks`. - The following functions now support a file descriptor for their path argument: :func:`~os.chdir`, :func:`~os.chmod`, :func:`~os.chown`, :func:`~os.execve`, :func:`~os.listdir`, :func:`~os.pathconf`, :func:`~os.path.exists`, - :func:`~os.stat`, :func:`~os.statvfs`, :func:`~os.utime`. + :func:`~os.stat`, :func:`~os.statvfs`, :func:`~os.utime`. Platform support + for this can be checked via the :data:`os.supports_fd` set. + +* :func:`~os.access` accepts an ``effective_ids`` keyword argument to turn on + using the effective uid/gid rather than the real uid/gid in the access check. + Platform support for this can be checked via the + :data:`~os.supports_effective_ids` set. * The :mod:`os` module has two new functions: :func:`~os.getpriority` and :func:`~os.setpriority`. They can be used to get or set process @@ -1558,7 +1566,7 @@ for a file. * :func:`~os.sync`: Force write of everything to disk. -* Add some extra posix functions to the os module: +* Additional new posix functions: * :func:`~os.lockf`: Apply, test or remove a POSIX lock on an open file descriptor. * :func:`~os.pread`: Read from a file descriptor at an offset, the file @@ -1577,6 +1585,12 @@ * :func:`~os.times` and :func:`~os.uname`: Return type changed from a tuple to a tuple-like object with named attributes. +* Some platforms now support additional constants for the :func:`~os.lseek` + function, such as ``os.SEEK_HOLE`` and ``os.SEEK_DATA``. + +* :func:`os.symlink` now accepts (and ignores) the ``target_is_directory`` + keyword argument on non-Windows platforms, to ease cross-platform support. + pdb --- @@ -1703,6 +1717,14 @@ instead of a RuntimeError: OSError has an errno attribute. +smtp +---- + +:class:`~smtplib.SMTP` now supports the context manager protocol, allowing an +``SMTP`` instance to be used in a ``with`` statement. (Contributed +by Giampaolo Rodolà in :issue:`11289`.) + + smtpd ----- @@ -1810,6 +1832,18 @@ (Contributed by Giampaolo Rodolà in :issue:`14807`) + +subprocess +---------- + +Command strings can now be bytes objects on posix platforms. (Contributed by +Victor Stiner in :issue:`8513`.) + +A new constant :data:`~subprocess.DEVNULL` allows suppressing output in a +platform-independent fashion. (Contributed by Ross Lagerwall in +:issue:`5870`.) + + sys --- @@ -1872,10 +1906,11 @@ :meth:`.assertRaises`, :meth:`.assertRaisesRegex`, :meth:`.assertWarns`, and :meth:`.assertWarnsRegex` now accept a keyword argument *msg* when used as -context managers. - -(Contributed by Ezio Melotti and Winston Ewert in :issue:`10775`) - +context managers. (Contributed by Ezio Melotti and Winston Ewert in +:issue:`10775`) + +:meth:`unittest.TestCase.run` now returns the :class:`~unittest.TestResult` +object. urllib ------ @@ -1993,7 +2028,7 @@ * :meth:`ftplib.FTP.nlst` and :meth:`ftplib.FTP.dir`: use :meth:`ftplib.FTP.mlsd` * :func:`platform.popen`: use the :mod:`subprocess` module. Check especially - the :ref:`subprocess-replacements` section. + the :ref:`subprocess-replacements` section (:issue:`11377`). * :issue:`13374`: The Windows bytes API has been deprecated in the :mod:`os` module. Use Unicode filenames, instead of bytes filenames, to not depend on the ANSI code page anymore and to support any filename. diff --git a/Misc/NEWS b/Misc/NEWS --- a/Misc/NEWS +++ b/Misc/NEWS @@ -3690,7 +3690,7 @@ not installed. Instead, the zipfile.ZIP_STORED compression is used to create the ZipFile. Patch by Natalia B. Bidart. -- Issue #11289: `smtp.SMTP` class becomes a context manager so it can be used +- Issue #11289: `smtp.SMTP` class is now a context manager so it can be used in a `with` statement. Contributed by Giampaolo Rodola. - Issue #11554: Fixed support for Japanese codecs; previously the body output @@ -3702,7 +3702,7 @@ - Issue #11407: `TestCase.run` returns the result object used or created. Contributed by Janathan Hartley. -- Issue #11500: Fixed a bug in the os x proxy bypass code for fully qualified +- Issue #11500: Fixed a bug in the OS X proxy bypass code for fully qualified IP addresses in the proxy exception list. - Issue #11491: dbm.error is no longer raised when dbm.open is called with -- Repository URL: http://hg.python.org/cpython

1 0