psycopg/psycopg2
1
1
Fork 0
mirror of https://github.com/psycopg/psycopg2.git synced 2025-01-31 09:24:07 +03:00
Code Issues Packages Projects Releases Wiki Activity

Big documentation cleanup.

Browse Source
This commit is contained in:
Daniele Varrazzo 2010-02-11 03:15:14 +00:00 committed by Federico Di Gregorio
parent 6ea6d48f5d
commit c8010cfd47
9 changed files with 473 additions and 404 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/_static/psycopg.css vendored
View File

@ -6,13 +6,13 @@ div.admonition-todo {
}
div.dbapi-extension {
background-color: #f5ffd4;
border: 1px solid #bda;
background-color: #eef;
border: 1px solid #aaf;
}
tt.sql {
font-size: 1em;
background-color: #fff;
background-color: transparent;
}
a > tt.sql:hover {

99
doc/advanced.rst
View File

@ -21,6 +21,9 @@ but other uses are possible. :class:`cursor` is much more interesting, because
it is the class where query building, execution and result type-casting into
Python variables happens.
.. index::
single: Example; Cursor subclass
An example of cursor subclass performing logging is::
import psycopg2
@ -57,21 +60,24 @@ Adapting new Python types to SQL syntax
Any Python class or type can be adapted to an SQL string. Adaptation mechanism
is similar to the Object Adaptation proposed in the :pep:`246` and is exposed
by the :func:`psycopg2.extensions.adapt()` function.
by the :func:`psycopg2.extensions.adapt` function.
The :meth:`cursor.execute()` method adapts its arguments to the
:class:`psycopg2.extensions.ISQLQuote` protocol. Objects that conform to this
protocol expose a :meth:`getquoted()` method returning the SQL representation
The :meth:`~cursor.execute` method adapts its arguments to the
:class:`~psycopg2.extensions.ISQLQuote` protocol. Objects that conform to this
protocol expose a :meth:`!getquoted` method returning the SQL representation
of the object as a string.
The easiest way to adapt an object to an SQL string is to register an adapter
function via the :func:`psycopg2.extensions.register_adapter()` function. The
function via the :func:`~psycopg2.extensions.register_adapter` function. The
adapter function must take the value to be adapted as argument and return a
conform object. A convenient object is the :func:`psycopg2.extensions.AsIs`
wrapper, whose :meth:`getquoted()` result is simply the ``str()``\ ing
conform object. A convenient object is the :class:`~psycopg2.extensions.AsIs`
wrapper, whose :meth:`!getquoted` result is simply the :meth:`!str`\ ing
conversion of the wrapped object.
Example: mapping of a :data:`Point` class into the |point|_ PostgreSQL
.. index::
single: Example; Types adaptation
Example: mapping of a :class:`!Point` class into the |point|_ PostgreSQL
geometric type::
from psycopg2.extensions import adapt, register_adapter, AsIs
@ -90,7 +96,7 @@ geometric type::
(Point(1.23, 4.56),))
.. |point| replace:: ``point``
.. |point| replace:: :sql:`point`
.. _point: http://www.postgresql.org/docs/8.4/static/datatype-geometric.html#AEN6084
The above function call results in the SQL command::
@ -110,25 +116,30 @@ PostgreSQL objects read from the database can be adapted to Python objects
through an user-defined adapting function. An adapter function takes two
arguments: the object string representation as returned by PostgreSQL and the
cursor currently being read, and should return a new Python object. For
example, the following function parses a PostgreSQL ``point`` into the
previously defined ``Point`` class::
example, the following function parses the PostgreSQL :sql:`point`
representation into the previously defined :class:`!Point` class::
def cast_point(value, curs):
if value is not None:
# Convert from (f1, f2) syntax using a regular expression.
m = re.match(r"\(([^)]+),([^)]+)\)", value)
if m:
return Point(float(m.group(1)), float(m.group(2)))
if value is None:
return None
To create a mapping from the PostgreSQL type (either standard or user-defined),
its OID must be known. It can be retrieved either by the second column of
the cursor description::
# Convert from (f1, f2) syntax using a regular expression.
m = re.match(r"\(([^)]+),([^)]+)\)", value)
if m:
return Point(float(m.group(1)), float(m.group(2)))
else:
raise InterfaceError("bad point representation: %r" % value)
In order to create a mapping from a PostgreSQL type (either standard or
user-defined), its OID must be known. It can be retrieved either by the second
column of the :attr:`cursor.description`::
curs.execute("SELECT NULL::point")
point_oid = curs.description[0][1] # usually returns 600
or by querying the system catalogs for the type name and namespace (the
namespace for system objects is ``pg_catalog``)::
namespace for system objects is :sql:`pg_catalog`)::
curs.execute("""
SELECT pg_type.oid
@ -145,9 +156,9 @@ After you know the object OID, you must can and register the new type::
POINT = psycopg2.extensions.new_type((point_oid,), "POINT", cast_point)
psycopg2.extensions.register_type(POINT)
The :func:`psycopg2.extensions.new_type()` function binds the object oids
The :func:`~psycopg2.extensions.new_type` function binds the object OIDs
(more than one can be specified) to the adapter function.
:func:`psycopg2.extensions.register_type()` completes the spell. Conversion
:func:`~psycopg2.extensions.register_type` completes the spell. Conversion
is automatically performed when a column whose type is a registered OID is
read::
@ -174,18 +185,21 @@ refer to the PostgreSQL documentation for examples of how to use this form of
communications.
Notifications received are made available in the :attr:`connection.notifies`
list. Notifications can be sent from Python code simply using a ``NOTIFY``
command in a :meth:`cursor.execute` call.
list. Notifications can be sent from Python code simply using a :sql:`NOTIFY`
command in an :meth:`~cursor.execute` call.
Because of the way sessions interact with notifications (see |NOTIFY|_
documentation), you should keep the connection in autocommit mode while
sending and receiveng notification.
documentation), you should keep the connection in :ref:`autocommit
<autocommit>` mode while sending and receiveng notification.
.. |LISTEN| replace:: ``LISTEN``
.. |LISTEN| replace:: :sql:`LISTEN`
.. _LISTEN: http://www.postgresql.org/docs/8.4/static/sql-listen.html
.. |NOTIFY| replace:: ``NOTIFY``
.. |NOTIFY| replace:: :sql:`NOTIFY`
.. _NOTIFY: http://www.postgresql.org/docs/8.4/static/sql-notify.html
.. index::
single: Example; Asynchronous notification
Example::
import sys
@ -207,7 +221,7 @@ Example::
if curs.isready():
print "Got NOTIFY:", curs.connection.notifies.pop()
Running the script and executing the command ``NOTIFY test`` in a separate
Running the script and executing the command :sql:`NOTIFY test` in a separate
:program:`psql` shell, the output may look similar to::
Waiting for 'NOTIFY test'
@ -232,11 +246,11 @@ Asynchronous queries
Psycopg support for asynchronous queries is still experimental and the
informations reported here may be out of date.
Discussion testing and suggestions are welcome.
Discussion, testing and suggestions are welcome.
Program code can initiate an asynchronous query by passing an ``async=1`` flag
to the :meth:`cursor.execute` or :meth:`cursor.callproc` methods. A very
simple example, from the connection to the query::
to the :meth:`~cursor.execute` or :meth:`~cursor.callproc` cursor methods. A
very simple example, from the connection to the query::
conn = psycopg2.connect(database='test')
curs = conn.cursor()
@ -247,7 +261,7 @@ doomed to fail (and raise an exception) until the original cursor (the one
executing the query) complete the asynchronous operation. This can happen in
a number of different ways:
1) one of the :obj:`.fetch*()` methods is called, effectively blocking until
1) one of the :meth:`!fetch*` methods is called, effectively blocking until
data has been sent from the backend to the client, terminating the query.
2) :meth:`connection.cancel` is called. This method tries to abort the
@ -255,28 +269,31 @@ a number of different ways:
The return value is ``True`` if the query was successfully aborted or
``False`` if it was executed. Query result are discarded in both cases.
3) :meth:`cursor.execute` is called again on the same cursor
(:obj:`.execute()` on a different cursor will simply raise an exception).
3) :meth:`~cursor.execute` is called again on the same cursor
(:meth:`!execute` on a different cursor will simply raise an exception).
This waits for the complete execution of the current query, discard any
data and execute the new one.
Note that calling :obj:`.execute()` two times in a row will not abort the
Note that calling :meth:`!execute` two times in a row will not abort the
former query and will temporarily go to synchronous mode until the first of
the two queries is executed.
Cursors now have some extra methods that make them useful during
asynchronous queries:
:meth:`cursor.fileno`
:meth:`~cursor.fileno`
Returns the file descriptor associated with the current connection and
make possible to use a cursor in a context where a file object would be
expected (like in a :func:`select()` call).
expected (like in a :func:`select` call).
:meth:`cursor.isready`
:meth:`~cursor.isready`
Returns ``False`` if the backend is still processing the query or ``True``
if data is ready to be fetched (by one of the :obj:`.fetch*()` methods).
if data is ready to be fetched (by one of the :meth:`!fetch*` methods).
A code snippet that shows how to use the cursor object in a :func:`select()`
.. index::
single: Example; Asynchronous query
A code snippet that shows how to use the cursor object in a :func:`!select`
call::
import psycopg2

8
doc/conf.py
View File

@ -22,8 +22,10 @@ import sys, os
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.ifconfig',
'dbapi_extension' ]
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.ifconfig' ]
# Specific extensions for Psycopg documentation.
extensions += [ 'dbapi_extension', 'sql_role' ]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@ -102,6 +104,8 @@ rst_epilog = """
http://www.postgresql.org/docs/8.4/static/transaction-iso.html#XACT-SERIALIZABLE
.. _mx.DateTime: http://www.egenix.com/products/python/mxBase/mxDateTime/
.. |MVCC| replace:: :abbr:`MVCC (Multiversion concurrency control)`
"""
# -- Options for HTML output ---------------------------------------------------

67
doc/connection.rst
View File

@ -9,7 +9,7 @@ The ``connection`` class
a database session.
Connections are created using the factory function
:func:`psycopg2.connect()`.
:func:`~psycopg2.connect`.
Connections are thread safe and can be shared among many thread. See
:ref:`thread-safety` for details.
@ -18,18 +18,19 @@ The ``connection`` class
Return a new :class:`cursor` object using the connection.
If :obj:`name` is specified, the returned cursor will be a *server
If :obj:`!name` is specified, the returned cursor will be a *server
side* (or *named*) cursor. Otherwise the cursor will be *client side*.
See :ref:`server-side-cursors` for further details.
The ``cursor_factory`` argument can be used to create non-standard
The :obj:`!cursor_factory` argument can be used to create non-standard
cursors. The class returned should be a subclass of
:class:`extensions.cursor`. See :ref:`subclassing-cursor` for details.
:class:`psycopg2.extensions.cursor`. See :ref:`subclassing-cursor` for
details.
.. extension::
The :obj:`name` and :obj:`cursor_factory` parameters are Psycopg
extensions to the DB API.
The :obj:`!name` and :obj:`!cursor_factory` parameters are Psycopg
extensions to the |DBAPI|.
.. index::
pair: Transaction; Commit
@ -38,7 +39,7 @@ The ``connection`` class
Commit any pending transaction to the database. Psycopg can be set to
perform automatic commits at each operation, see
:meth:`connection.set_isolation_level()`.
:meth:`~connection.set_isolation_level`.
.. index::
@ -53,14 +54,14 @@ The ``connection`` class
.. method:: close()
Close the connection now (rather than whenever ``__del__`` is called).
The connection will be unusable from this point forward; a
:exc:`psycopg2.Error` (or subclass) exception will be raised if any
operation is attempted with the connection. The same applies to all
cursor objects trying to use the connection. Note that closing a
connection without committing the changes first will cause an implicit
rollback to be performed (unless a different isolation level has been
selected: see :meth:`connection.set_isolation_level()`).
Close the connection now (rather than whenever :meth:`__del__` is
called). The connection will be unusable from this point forward; an
:exc:`~psycopg2.InterfaceError` will be raised if any operation is
attempted with the connection. The same applies to all cursor objects
trying to use the connection. Note that closing a connection without
committing the changes first will cause an implicit rollback to be
performed (unless a different isolation level has been selected: see
:meth:`~connection.set_isolation_level`).
.. index::
@ -68,13 +69,13 @@ The ``connection`` class
.. rubric:: Excetptions as connection class attributes
The :class:`connection` also exposes the same `Error` classes available in
the :mod:`psycopg2` module as attributes.
The :class:`!connection` also exposes as attributes the same exceptions
available in the :mod:`psycopg2` module. See :ref:`dbapi-exceptions`.
.. extension::
The above methods are the only ones defined by the |DBAPI|_ protocol.
The above methods are the only ones defined by the |DBAPI| protocol.
The Psycopg connection objects exports the following additional
methods and attributes.
@ -95,6 +96,8 @@ The ``connection`` class
pair: Transaction; Autocommit
pair: Transaction; Isolation level
.. _autocommit:
.. attribute:: isolation_level
.. method:: set_isolation_level(level)
@ -106,10 +109,11 @@ The ``connection`` class
the module :mod:`psycopg2.extensions`: see
:ref:`isolation-level-constants` for the available values.
The default level is ``READ COMMITTED``: in this level a transaction
is automatically started every time a database command is executed. If
you want an *autocommit* mode, set the connection in ``AUTOCOMMIT``
mode before executing any command::
The default level is :sql:`READ COMMITTED`: in this level a transaction
is automatically started every time a database command is executed. If
you want an *autocommit* mode, switch to
:obj:`~psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT`
before executing any command::
>>> conn.set_isolation_level(psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT)
@ -133,7 +137,7 @@ The ``connection`` class
.. attribute:: notices
A list containing all the database messages sent to the client during
the session.::
the session. ::
>>> cur.execute("CREATE TABLE foo (id serial PRIMARY KEY);")
>>> conn.notices
@ -155,9 +159,9 @@ The ``connection`` class
List containing asynchronous notifications received by the session.
Received notifications have the form of a 2 items tuple
``(pid,name)``, where ``pid`` is the PID of the backend that sent the
notification and ``name`` is the signal name specified in the
``NOTIFY`` command.
:samp:`({pid},{name})`, where :samp:`{pid}` is the PID of the backend
that sent the notification and :samp:`{name}` is the signal name
specified in the :sql:`NOTIFY` command.
For other details see :ref:`async-notify`.
@ -233,7 +237,7 @@ The ``connection`` class
The number is formed by converting the major, minor, and revision
numbers into two-decimal-digit numbers and appending them together.
For example, version 8.1.5 will be returned as 80105,
For example, version 8.1.5 will be returned as ``80105``.
.. seealso:: libpq docs for `PQserverVersion()`__ for details.
@ -262,12 +266,3 @@ The ``connection`` class
.. todo:: conn.lobject details
.. attribute:: binary_types
.. todo:: describe binary_types
.. attribute:: string_types
.. todo:: describe string_types

206
doc/cursor.rst
View File

@ -6,15 +6,16 @@ The ``cursor`` class
.. class:: cursor
Allows Python code to execute PostgreSQL command in a database session.
Cursors are created by the :meth:`connection.cursor`: they are bound to
the connection for the entire lifetime and all the commands are executed
in the context of the database session wrapped by the connection.
Cursors are created by the :meth:`connection.cursor` method: they are
bound to the connection for the entire lifetime and all the commands are
executed in the context of the database session wrapped by the connection.
Cursors created from the same connection are not isolated, i.e., any
changes done to the database by a cursor are immediately visible by the
other cursors. Cursors created from different connections can or can not
be isolated, depending on the :attr:`connection.isolation_level`. See also
:meth:`connection.rollback()` and :meth:`connection.commit()` methods.
be isolated, depending on the connections' :ref:`isolation level
<transactions-control>`. See also :meth:`~connection.rollback` and
:meth:`~connection.commit` methods.
Cursors are *not* thread safe: a multithread application can create
many cursors from the same same connection and should use each cursor from
@ -36,24 +37,26 @@ The ``cursor`` class
- ``scale``
- ``null_ok``
The first two items (``name`` and ``type_code``) are mandatory, the
other five are optional and are set to ``None`` if no meaningful
The first two items (``name`` and ``type_code``) are always specified,
the other five are optional and are set to ``None`` if no meaningful
values can be provided.
This attribute will be ``None`` for operations that do not return rows
or if the cursor has not had an operation invoked via the
|execute*|_ methods yet.
The type_code can be interpreted by comparing it to the Type Objects
specified in the section :ref:`type-objects-and-constructors`.
The ``type_code`` can be interpreted by comparing it to the Type
Objects specified in the section :ref:`type-objects-and-constructors`.
It is also used to register typecasters to convert PostgreSQL types to
Python objects: see :ref:`type-casting-from-sql-to-python`.
.. method:: close()
Close the cursor now (rather than whenever ``__del__`` is called).
The cursor will be unusable from this point forward; an :exc:`Error` (or
subclass) exception will be raised if any operation is attempted with
the cursor.
Close the cursor now (rather than whenever :meth:`!__del__` is
called). The cursor will be unusable from this point forward; an
:exc:`~psycopg2.InterfaceError` will be raised if any operation is
attempted with the cursor.
.. attribute:: closed
@ -84,7 +87,7 @@ The ``cursor`` class
.. |execute*| replace:: :obj:`execute*()`
.. |execute*| replace:: :meth:`execute*`
.. _execute*:
@ -97,23 +100,15 @@ The ``cursor`` class
Parameters may be provided as sequence or mapping and will be bound to
variables in the operation. Variables are specified either with
positional (``%s``) or named (``%(name)s``) placeholders. See
positional (``%s``) or named (:samp:`%({name})s`) placeholders. See
:ref:`query-parameters`.
The method returns `None`. If a query was executed, the returned
values can be retrieved using |fetch*|_ methods.
A reference to the operation will be retained by the cursor. If the
same operation object is passed in again, then the cursor can optimize
its behavior. This is most effective for algorithms where the same
operation is used, but different parameters are bound to it (many
times).
.. todo:: does Psycopg2 do the above?
If :obj:`async` is ``True``, query execution will be asynchronous: the
function returns immediately while the query is executed by the
backend. Use the :attr:`isready` attribute to see if the data is
If :obj:`!async` is ``True``, query execution will be asynchronous:
the function returns immediately while the query is executed by the
backend. Use the :meth:`~cursor.isready` method to see if the data is
ready for return via |fetch*|_ methods. See
:ref:`asynchronous-queries`.
@ -122,11 +117,14 @@ The ``cursor`` class
The :obj:`async` parameter is a Psycopg extension to the |DBAPI|.
.. method:: mogrify(operation [, parameters)
.. method:: mogrify(operation [, parameters])
Return a query string after arguments binding. The string returned is
exactly the one that would be sent to the database running the
:meth:`execute()` method or similar.
:meth:`~cursor.execute` method or similar. ::
>>> cur.mogrify("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
"INSERT INTO test (num, data) VALUES (42, E'bar')"
.. extension::
@ -136,14 +134,14 @@ The ``cursor`` class
.. method:: executemany(operation, seq_of_parameters)
Prepare a database operation (query or command) and then execute it
against all parameter sequences or mappings found in the sequence
seq_of_parameters.
against all parameter tuples or mappings found in the sequence
:obj:`!seq_of_parameters`.
The function is mostly useful for commands that update the database:
any result set returned by the query is discarded.
Parameters are bounded to the query using the same rules described in
the :meth:`execute()` method.
the :meth:`~cursor.execute` method.
.. method:: callproc(procname [, parameters] [, async])
@ -157,10 +155,10 @@ The ``cursor`` class
The procedure may also provide a result set as output. This must then
be made available through the standard |fetch*|_ methods.
If :obj:`async` is ``True``, procedure execution will be asynchronous:
If :obj:`!async` is ``True``, procedure execution will be asynchronous:
the function returns immediately while the procedure is executed by
the backend. Use the :attr:`isready` attribute to see if the data is
ready for return via |fetch*|_ methods. See
the backend. Use the :meth:`~cursor.isready` method to see if the
data is ready for return via |fetch*|_ methods. See
:ref:`asynchronous-queries`.
.. extension::
@ -170,12 +168,12 @@ The ``cursor`` class
.. method:: setinputsizes(sizes)
This method is exported in compliance with the |DBAPI|. It currently
This method is exposed in compliance with the |DBAPI|. It currently
does nothing but it is safe to call it.
.. |fetch*| replace:: :obj:`fetch*()`
.. |fetch*| replace:: :meth:`!fetch*`
.. _fetch*:
@ -183,13 +181,13 @@ The ``cursor`` class
The following methods are used to read data from the database after an
:meth:`execute()` call.
:meth:`~cursor.execute` call.
.. note::
:class:`cursor` objects are iterable, so, instead of calling
explicitly :meth:`fetchone()` in a loop, the object itself can be
used::
explicitly :meth:`~cursor.fetchone` in a loop, the object itself can
be used::
>>> cur.execute("SELECT * FROM test;")
>>> for record in cur:
@ -209,7 +207,7 @@ The ``cursor`` class
>>> cur.fetchone()
(4, 42, 'bar')
An :exc:`Error` (or subclass) exception is raised if the previous call
A :exc:`~psycopg2.ProgrammingError` is raised if the previous call
to |execute*|_ did not produce any result set or no call was issued
yet.
@ -220,11 +218,11 @@ The ``cursor`` class
tuples. An empty list is returned when no more rows are available.
The number of rows to fetch per call is specified by the parameter.
If it is not given, the cursor's :attr:`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::
If it is not given, the cursor's :attr:`~cursor.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::
>>> cur.execute("SELECT * FROM test;")
>>> cur.fetchmany(2)
@ -234,73 +232,66 @@ The ``cursor`` class
>>> cur.fetchmany(2)
[]
An :exc:`Error` (or subclass) exception is raised if the previous
call to |execute*|_ did not produce any result set or no call was
issued yet.
A :exc:`~psycopg2.ProgrammingError` is raised if the previous call to
|execute*|_ did not produce any result set or no call was issued yet.
Note there are performance considerations involved with the size
parameter. For optimal performance, it is usually best to use the
:attr:`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.
:attr:`~cursor.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:: fetchall()
Fetch all (remaining) rows of a query result, returning them as a list
of tuples. Note that the cursor's :attr:`arraysize` attribute can
affect the performance of this operation::
of tuples. An empty list is returned if there is no more record to
fetch.
>>> cur.execute("SELECT * FROM test;")
>>> cur.fetchall()
[(1, 100, "abc'def"), (2, None, 'dada'), (4, 42, 'bar')]
.. todo:: does arraysize influence fetchall()?
An :exc:`Error` (or subclass) exception is raised if the previous call
to |execute*|_ did not produce any result set or no call was issued
yet.
A :exc:`~psycopg2.ProgrammingError` is raised if the previous call to
|execute*|_ did not produce any result set or no call was issued yet.
.. method:: scroll(value[,mode='relative'])
.. method:: scroll(value [, mode='relative'])
Scroll the cursor in the result set to a new position according
to mode.
If mode is ``relative`` (default), value is taken as offset to
If :obj:`!mode` is ``relative`` (default), value is taken as offset to
the current position in the result set, if set to ``absolute``,
value states an absolute target position.
If the scroll operation would leave the result set, a
:exc:`ProgrammingError` is raised and the cursor position is not
changed.
:exc:`~psycopg2.ProgrammingError` is raised and the cursor position is
not changed.
.. todo:: DB API says should have been IndexError...
The method can be used both for client-side cursors and
:ref:`server-side cursors <server-side-cursors>`.
The method can be used both for client-side cursors and server-side
(named) cursors.
.. note::
According to the |DBAPI|_, the exception raised for a cursor out
of bound should have been :exc:`!IndexError`.
.. attribute:: arraysize
This read/write attribute specifies the number of rows to fetch at a
time with :meth:`fetchmany()`. It defaults to 1 meaning to fetch a
single row at a time.
Implementations must observe this value with respect to the
:meth:`fetchmany()` method, but are free to interact with the database
a single row at a time. It may also be used in the implementation of
:meth:`executemany()`.
.. todo:: copied from DB API: better specify what psycopg2 does with
arraysize
time with :meth:`~cursor.fetchmany`. It defaults to 1 meaning to fetch
a single row at a time.
.. attribute:: rowcount
This read-only attribute specifies the number of rows that the last
|execute*|_ produced (for DQL statements like ``SELECT``) or
affected (for DML statements like ``UPDATE`` or ``INSERT``).
|execute*|_ produced (for :abbr:`DQL (Data Query Language)` statements
like :sql:`SELECT`) or affected (for
:abbr:`DML (Data Manipulation Language)` statements like :sql:`UPDATE`
or :sql:`INSERT`).
The attribute is -1 in case no |execute*| has been performed on
the cursor or the row count of the last operation if it can't be
@ -327,32 +318,32 @@ The ``cursor`` class
.. attribute:: lastrowid
This read-only attribute provides the *oid* of the last row inserted
by the cursor. If the table wasn't created with oid support or the
This read-only attribute provides the OID of the last row inserted
by the cursor. If the table wasn't created with OID support or the
last operation is not a single record insert, the attribute is set to
``None``.
PostgreSQL currently advises to not create oid on the tables and the
PostgreSQL currently advices to not create OIDs on the tables and the
default for |CREATE-TABLE|__ is to not support them. The
|INSERT-RETURNING|__ syntax available from PostgreSQL 8.3 allows more
flexibility:
.. |CREATE-TABLE| replace:: ``CREATE TABLE``
.. |CREATE-TABLE| replace:: :sql:`CREATE TABLE`
.. __: http://www.postgresql.org/docs/8.4/static/sql-createtable.html
.. |INSERT-RETURNING| replace:: ``INSERT ... RETURNING``
.. |INSERT-RETURNING| replace:: :sql:`INSERT ... RETURNING`
.. __: http://www.postgresql.org/docs/8.4/static/sql-insert.html
.. method:: nextset()
This method is not supported (PostgreSQL does not have multiple data
sets) and will raise a :exc:`NotSupportedError` exception.
sets) and will raise a :exc:`~psycopg2.NotSupportedError` exception.
.. method:: setoutputsize(size [, column])
This method is exported in compliance with the |DBAPI|. It currently
This method is exposed in compliance with the |DBAPI|. It currently
does nothing but it is safe to call it.
@ -373,7 +364,8 @@ The ``cursor`` class
.. attribute:: statusmessage
Return the message returned by the last command::
Read-only attribute containing the message returned by the last
command::
>>> cur.execute("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
>>> cur.statusmessage
@ -400,12 +392,12 @@ The ``cursor`` class
Return the file descriptor associated with the current connection and
make possible to use a cursor in a context where a file object would
be expected (like in a :func:`select()` call). See
be expected (like in a :func:`select` call). See
:ref:`asynchronous-queries`.
.. extension::
The :meth:`isready` method is a Psycopg extension to the |DBAPI|.
The :meth:`fileno` method is a Psycopg extension to the |DBAPI|.
@ -413,18 +405,20 @@ The ``cursor`` class
.. extension::
The ``COPY`` support is a Psycopg extension to the |DBAPI|.
The :sql:`COPY` command is a PostgreSQL extension to the SQL standard.
As such, its support is a Psycopg extension to the |DBAPI|.
.. method:: copy_from(file, table, sep='\\t', null='\\N', columns=None)
Read data *from* the file-like object :obj:`file` appending them to
the table named :obj:`table`. :obj:`file` must have both ``read()``
and ``readline()`` method. See :ref:`copy` for an overview.
Read data *from* the file-like object :obj:`!file` appending them to
the table named :obj:`!table`. :obj:`!file` must have both
:meth:`!read` and :meth:`!readline` method. See :ref:`copy` for an
overview.
The optional argument :obj:`sep` is the columns separator and
:obj:`null` represents ``NULL`` values in the file.
The optional argument :obj:`!sep` is the columns separator and
:obj:`!null` represents :sql:`NULL` values in the file.
The :obj:`columns` argument is a sequence containing the name of the
The :obj:`!columns` argument is a sequence containing the name of the
fields where the read data will be entered. Its length and column
type should match the content of the read file. If not specifies, it
is assumed that the entire table matches the file structure. ::
@ -442,13 +436,14 @@ The ``cursor`` class
.. method:: copy_to(file, table, sep='\\t', null='\\N', columns=None)
Write the content of the table named :obj:`table` *to* the file-like object :obj:`file`. :obj:`file` must have a ``write()`` method. See
:ref:`copy` for an overview.
Write the content of the table named :obj:`!table` *to* the file-like
object :obj:`!file`. :obj:`!file` must have a :meth:`!write` method.
See :ref:`copy` for an overview.
The optional argument :obj:`sep` is the columns separator and
:obj:`null` represents ``NULL`` values in the file.
The optional argument :obj:`!sep` is the columns separator and
:obj:`!null` represents :sql:`NULL` values in the file.
The :obj:`columns` argument is a sequence of field names: if not
The :obj:`!columns` argument is a sequence of field names: if not
``None`` only the specified fields will be included in the dump. ::
>>> cur.copy_to(sys.stdout, 'test', sep="|")
@ -461,21 +456,22 @@ The ``cursor`` class
.. method:: copy_expert(sql, file [, size])
Submit a user-composed ``COPY`` statement. The method is useful to
Submit a user-composed :sql:`COPY` statement. The method is useful to
handle all the parameters that PostgreSQL makes available (see
|COPY|__ command documentation).
:obj:`file` must be an open, readable file for ``COPY FROM`` or an
open, writeable file for ``COPY TO``. The optional :obj:`size`
argument, when specified for a ``COPY FROM`` statement, will be passed
to file's read method to control the read buffer size. ::
:obj:`!file` must be an open, readable file for :sql:`COPY FROM` or an
open, writeable file for :sql:`COPY TO`. The optional :obj:`!size`
argument, when specified for a :sql:`COPY FROM` statement, will be
passed to :obj:`!file`\ 's read method to control the read buffer
size. ::
>>> cur.copy_expert("COPY test TO STDOUT WITH CSV HEADER", sys.stdout)
id,num,data
1,100,abc'def
2,,dada
.. |COPY| replace:: ``COPY``
.. |COPY| replace:: :sql:`COPY`
.. __: http://www.postgresql.org/docs/8.4/static/sql-copy.html
.. versionadded:: 2.0.6

172
doc/extensions.rst
View File

@ -6,25 +6,25 @@
.. module:: psycopg2.extensions
The module contains a few objects and function extending the minimum set of
functionalities defined by the |DBAPI|.
functionalities defined by the |DBAPI|_.
.. class:: connection
Is the class usually returned by the :func:`psycopg2.connect()` function.
Is the class usually returned by the :func:`~psycopg2.connect` function.
It is exposed by the :mod:`extensions` module in order to allow
subclassing to extend its behaviour: the subclass should be passed to the
:func:`connect()` function using the :obj:`connection_factory` parameter.
:func:`!connect` function using the :obj:`!connection_factory` parameter.
See also :ref:`subclassing-connection`.
For a complete description of the class, see :class:`connection`.
.. class:: cursor
It is the class usually returnded by the :meth:`connection.cursor()`
It is the class usually returnded by the :meth:`connection.cursor`
method. It is exposed by the :mod:`extensions` module in order to allow
subclassing to extend its behaviour: the subclass should be passed to the
``cursor()`` method using the :obj:`cursor_factory` parameter. See
:meth:`!cursor` method using the :obj:`!cursor_factory` parameter. See
also :ref:`subclassing-cursor`.
For a complete description of the class, see :class:`cursor`.
@ -50,13 +50,13 @@ deal with Python objects adaptation:
.. function:: adapt(obj)
Return the SQL representation of :obj:`obj` as a string. Raise a
:exc:`ProgrammingError` if how to adapt the object is unknown. In order
to allow new objects to be adapted, register a new adapter for it using
the :func:`register_adapter` function.
:exc:`~psycopg2.ProgrammingError` if how to adapt the object is unknown.
In order to allow new objects to be adapted, register a new adapter for it
using the :func:`register_adapter` function.
The function is the entry point of the adaptation mechanism: it can be
used to write adapters for complex objects by recursively calling
:func:`adapt` on its components.
:func:`!adapt` on its components.
.. function:: register_adapter(class, adapter)
@ -64,23 +64,29 @@ deal with Python objects adaptation:
:data:`adapter` should be a function taking a single argument (the object
to adapt) and returning an object conforming the :class:`ISQLQuote`
protocol (e.g. exposing a :meth:`getquoted` method). The :class:`AsIs` is
protocol (e.g. exposing a :meth:`!getquoted` method). The :class:`AsIs` is
often useful for this task.
Once an object is registered, it can be safely used in SQL queries and by
the :func:`adapt` function.
.. class:: ISQLQuote
.. class:: ISQLQuote(wrapped_object)
Represents the SQL adaptation protocol. Objects conforming this protocol
should implement a :meth:`getquoted` method.
Represents the SQL adaptation protocol. Objects conforming this protocol
should implement a :meth:`!getquoted` method.
.. todo:: has Psycopg user ever to explicitely use this object?
Adapters may subclass :class:`!ISQLQuote`, but is not necessary: it is
enough to expose a :meth:`!getquoted` method to be conforming.
.. todo::
what the ISQLQuote methods are for? In my understanding the
class is only used as symbol to dispatch adaptation and not to be
instantiated.
.. attribute:: _wrapped
The wrapped object passes to the constructor
.. method:: getquoted()
Subclasses or other conforming objects should return a valid SQL
string representing the wrapped object. The :class:`!ISQLQuote`
implementation does nothing.
.. class:: AsIs
@ -89,7 +95,7 @@ deal with Python objects adaptation:
.. method:: getquoted()
Return the ``str()`` conversion of the wrapped object. ::
Return the :meth:`str` conversion of the wrapped object. ::
>>> AsIs(42).getquoted()
'42'
@ -121,28 +127,30 @@ deal with Python objects adaptation:
>>> Binary("\x00\x08\x0F").getquoted()
"'\\\\000\\\\010\\\\017'"
.. todo::
this class is actually not importd in module extensions: I'd say this
is a bug.
.. versionchanged:: 2.0.14(ish)
previously the adapter was not exposed by the :mod:`extensions`
module. In older version it can be imported from the implementation
module :mod:`!psycopg2._psycopg`.
.. data:: Boolean
.. data:: Float
.. class:: Boolean
.. class:: Float
.. class:: SQL_IN
Specialized adapters for builtin objects.
.. data:: DateFromPy
.. data:: TimeFromPy
.. data:: TimestampFromPy
.. data:: IntervalFromPy
.. class:: DateFromPy
.. class:: TimeFromPy
.. class:: TimestampFromPy
.. class:: IntervalFromPy
Specialized adapters for Python datetime objects.
.. data:: DateFromMx
.. data:: TimeFromMx
.. data:: TimestampFromMx
.. data:: IntervalFromMx
.. class:: DateFromMx
.. class:: TimeFromMx
.. class:: TimestampFromMx
.. class:: IntervalFromMx
Specialized adapters for `mx.DateTime`_ objects.
@ -170,13 +178,14 @@ details.
:param name: the name of the new type adapter.
:param adapter: the adaptation function.
The object OID can be read from the :data:`cursor.description` or directly
from the PostgreSQL catalog.
The object OID can be read from the :data:`cursor.description` attribute
or by querying from the PostgreSQL catalog.
:data:`adapter` should have signature ``fun(value, cur)`` where
``value`` is the string representation returned by PostgreSQL and ``cur``
is the cursor from which data are read. In case of ``NULL``, ``value`` is
``None``. The adapter should return the converted object.
:data:`adapter` should have signature :samp:`fun({value}, {cur})` where
:samp:`{value}` is the string representation returned by PostgreSQL and
:samp:`{cur}` is the cursor from which data are read. In case of
:sql:`NULL`, :samp:`{value}` is ``None``. The adapter should return the
converted object.
See :ref:`type-casting-from-sql-to-python` for an usage example.
@ -184,20 +193,47 @@ details.
Register a type caster created using :func:`new_type`.
If :obj:`scope` is specified, it should be a :class:`connection` or a
If :obj:`!scope` is specified, it should be a :class:`connection` or a
:class:`cursor`: the type caster will be effective only limited to the
specified object. Otherwise it will be globally registered.
.. todo:: Please confirm the above behaviour.
.. data:: string_types
The global register of type casters.
.. data:: binary_types
.. todo:: is this used?
.. index::
single: Encoding; Mapping
.. data:: encodings
Mapping from `PostgreSQL encoding`__ names to `Python codec`__ names.
Used by Psycopg when adapting or casting unicode strings.
.. __: http://www.postgresql.org/docs/8.4/static/multibyte.html
.. __: http://docs.python.org/library/codecs.html#standard-encodings
.. index::
single: Exceptions; Additional
Additional exceptions
---------------------
The module exports a few exceptions in addition to the :ref:`standard ones
<dbapi-exceptions>` defined by the |DBAPI|_.
.. exception:: QueryCanceledError
Error related to database operation (disconnect, memory allocation etc).
It is a subclass of :exc:`~psycopg2.OperationalError`
.. exception:: TransactionRollbackError
Error causing transaction rollback (deadlocks, serialisation failures, etc).
It is a subclass of :exc:`~psycopg2.OperationalError`
.. index::
@ -208,43 +244,45 @@ details.
Isolation level constants
-------------------------
Psycopg2 connection objects hold informations about the PostgreSQL
Psycopg2 :class:`connection` objects hold informations about the PostgreSQL
`transaction isolation level`_. The current transaction level can be read
from the :attr:`connection.isolation_level` attribute. The default isolation
level is ``READ COMMITTED``. A different isolation level con be set through
the :meth:`connection.set_isolation_level()` method. The level can be set to
one of the following constants:
from the :attr:`~connection.isolation_level` attribute. The default isolation
level is :sql:`READ COMMITTED`. A different isolation level con be set
through the :meth:`~connection.set_isolation_level` method. The level can be
set to one of the following constants:
.. data:: ISOLATION_LEVEL_AUTOCOMMIT
No transaction is started when command are issued and no ``commit()`` or
``rollback()`` is required. Some PostgreSQL command such as ``CREATE
DATABASE`` can't run into a transaction: to run such command use::
No transaction is started when command are issued and no
:meth:`~connection.commit` or :meth:`~connection.rollback` is required.
Some PostgreSQL command such as :sql:`CREATE DATABASE` can't run into a
transaction: to run such command use::
>>> conn.set_isolation_level(ISOLATION_LEVEL_AUTOCOMMIT)
.. data:: ISOLATION_LEVEL_READ_UNCOMMITTED
This isolation level is defined in the SQL standard but not available in
the MVCC model of PostgreSQL: it is replaced by the stricter ``READ
COMMITTED``.
The :sql:`READ UNCOMMITTED` isolation level is defined in the SQL standard but not available in
the |MVCC| model of PostgreSQL: it is replaced by the stricter :sql:`READ
COMMITTED`.
.. data:: ISOLATION_LEVEL_READ_COMMITTED
This is the default value. A new transaction is started at the first
:meth:`cursor.execute()` command on a cursor and at each new ``execute()``
after a :meth:`connection.commit()` or a :meth:`connection.rollback()`.
The transaction runs in the PostgreSQL ``READ COMMITTED`` isolation level.
:meth:`~cursor.execute` command on a cursor and at each new
:meth:`!execute` after a :meth:`~connection.commit` or a
:meth:`~connection.rollback`. The transaction runs in the PostgreSQL
:sql:`READ COMMITTED` isolation level.
.. data:: ISOLATION_LEVEL_REPEATABLE_READ
This isolation level is defined in the SQL standard but not available in
the MVCC model of PostgreSQL: it is replaced by the stricter
``SERIALIZABLE``.
The :sql:`REPEATABLE READ` isolation level is defined in the SQL standard
but not available in the |MVCC| model of PostgreSQL: it is replaced by the
stricter :sql:`SERIALIZABLE`.
.. data:: ISOLATION_LEVEL_SERIALIZABLE
Transactions are run at a ``SERIALIZABLE`` isolation level. This is the
Transactions are run at a :sql:`SERIALIZABLE` isolation level. This is the
strictest transactions isolation level, equivalent to having the
transactions executed serially rather than concurrently. However
applications using this level must be prepared to retry reansactions due
@ -262,7 +300,7 @@ Transaction status constants
----------------------------
These values represent the possible status of a transaction: the current value
can be read using the :meth:`connection.get_transaction_status()` method.
can be read using the :meth:`connection.get_transaction_status` method.
.. data:: TRANSACTION_STATUS_IDLE
@ -295,13 +333,11 @@ Connection status constants
---------------------------
These values represent the possible status of a connection: the current value
can be read from the :data:`connection.status` attribute.
.. todo:: check if these values are really useful or not.
can be read from the :data:`~connection.status` attribute.
.. data:: STATUS_SETUP
Defined but not used.
Used internally.
.. data:: STATUS_READY
@ -317,10 +353,10 @@ can be read from the :data:`connection.status` attribute.
.. data:: STATUS_SYNC
Defined but not used.
Used internally.
.. data:: STATUS_ASYNC
Defined but not used.
Used internally.

9
doc/index.rst
View File

@ -8,12 +8,12 @@ Psycopg is a PostgreSQL_ database adapter for the Python_ programming
language. Its main advantages are that it supports the full Python |DBAPI|_
and it is thread safe (threads can share the connections). It was designed for
heavily multi-threaded applications that create and destroy lots of cursors and
make a conspicuous number of concurrent INSERTs or UPDATEs. The psycopg
distribution includes ZPsycopgDA, a Zope_ Database Adapter.
make a conspicuous number of concurrent :sql:`INSERT`\ s or :sql:`UPDATE`\ s.
The psycopg distribution includes ZPsycopgDA, a Zope_ Database Adapter.
Psycopg 2 is an almost complete rewrite of the Psycopg 1.1.x branch. Psycopg 2
features complete libpq_ v3 protocol, `COPY TO/COPY FROM`__ and full object
adaptation for all basic Python 2.3 types: strings (including unicode), ints,
features complete libpq_ v3 protocol, |COPY-TO-FROM|__ and full :ref:`object
adaptation <python-types-adaptation>` for all basic Python types: strings (including unicode), ints,
longs, floats, buffers (binary objects), booleans, `mx.DateTime`_ and builtin
datetime types. It also supports unicode queries and Python lists mapped to
PostgreSQL arrays.
@ -22,6 +22,7 @@ PostgreSQL arrays.
.. _Python: http://www.python.org/
.. _Zope: http://www.zope.org/
.. _libpq: http://www.postgresql.org/docs/8.4/static/libpq.html
.. |COPY-TO-FROM| replace:: :sql:`COPY TO/COPY FROM`
.. __: http://www.postgresql.org/docs/8.4/static/sql-copy.html
Contents:

79
doc/module.rst
View File

@ -30,19 +30,19 @@ The module interface respects the standard defined in the |DBAPI|_.
The full list of available parameters is:
- ``dbname`` the database name (only in dsn string)
- ``database`` the database name (only as keyword argument)
- ``user`` user name used to authenticate
- ``password`` password used to authenticate
- ``host`` database host address (defaults to UNIX socket if not provided)
- ``port`` connection port number (defaults to 5432 if not provided)
- ``sslmode`` `SSL TCP/IP negotiation`__ mode
- :obj:`!dbname` -- the database name (only in dsn string)
- :obj:`!database` -- the database name (only as keyword argument)
- :obj:`!user` -- user name used to authenticate
- :obj:`!password` -- password used to authenticate
- :obj:`!host` -- database host address (defaults to UNIX socket if not provided)
- :obj:`!port` -- connection port number (defaults to 5432 if not provided)
- :obj:`!sslmode` -- `SSL TCP/IP negotiation`__ mode
.. __: http://www.postgresql.org/docs/8.4/static/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS
Using the :obj:`connection_factory` parameter a different class or
Using the :obj:`!connection_factory` parameter a different class or
connections factory can be specified. It should be a callable object
taking a :obj:`dsn` argument. See :ref:`subclassing-connection` for
taking a :obj:`!dsn` argument. See :ref:`subclassing-connection` for
details.
.. extension::
@ -69,27 +69,29 @@ The module interface respects the standard defined in the |DBAPI|_.
:ref:`query-parameters`.
.. index:: Exceptions
.. index::
single: Exceptions; DB API
.. _dbapi-exceptions:
Exceptions
----------
In compliance with the |DBAPI|, the module makes informations about errors
In compliance with the |DBAPI|_, the module makes informations about errors
available through the following exceptions:
.. exception:: Warning
Exception raised for important warnings like data truncations while
inserting, etc. It is a subclass of the Python |StandardError|_ (defined in
the module exceptions).
inserting, etc. It is a subclass of the Python |StandardError|_.
.. exception:: Error
Exception that is the base class of all other error exceptions. You can
use this to catch all errors with one single ``except`` statement. Warnings
are not considered errors and thus should not use this class as base. It
is a subclass of the Python |StandardError|_ (defined in the module
exceptions).
is a subclass of the Python |StandardError|_.
.. exception:: InterfaceError
@ -136,30 +138,43 @@ available through the following exceptions:
.. exception:: NotSupportedError
Exception raised in case a method or database API was used which is not
supported by the database, e.g. requesting a .rollback() on a connection
that does not support transaction or has transactions turned off. It is a
subclass of :exc:`DatabaseError`.
supported by the database, e.g. requesting a :meth:`!rollback` on a
connection that does not support transaction or has transactions turned
off. It is a subclass of :exc:`DatabaseError`.
.. extension::
The :mod:`psycopg2.extensions` module exports a few other exception that
may be raised by Psycopg: currently
:exc:`~psycopg2.extensions.QueryCanceledError` and
:exc:`~psycopg2.extensions.TransactionRollbackError`. These exceptions are
not exposed by the main :mod:`!psycopg2` module but can be imported by the
:mod:`~psycopg2.extensions` module. All the additional exceptions are
subclasses of standard |DBAPI| exceptions, so trapping them specifically
is not required.
This is the exception inheritance layout:
- |StandardError|_
.. parsed-literal::
- :exc:`Warning`
- :exc:`Error`
- :exc:`InterfaceError`
- :exc:`DatabaseError`
- :exc:`DataError`
- :exc:`OperationalError`
- :exc:`IntegrityError`
- :exc:`InternalError`
- :exc:`ProgrammingError`
- :exc:`NotSupportedError`
|StandardError|_
\|__ :exc:`Warning`
\|__ :exc:`Error`
\|__ :exc:`InterfaceError`
\|__ :exc:`DatabaseError`
\|__ :exc:`DataError`
\|__ :exc:`OperationalError`
\| \|__ :exc:`psycopg2.extensions.QueryCanceledError`
\| \|__ :exc:`psycopg2.extensions.TransactionRollbackError`
\|__ :exc:`IntegrityError`
\|__ :exc:`InternalError`
\|__ :exc:`ProgrammingError`
\|__ :exc:`NotSupportedError`
.. |StandardError| replace:: ``StandardError``
.. |StandardError| replace:: :exc:`!StandardError`
.. _StandardError: http://docs.python.org/library/exceptions.html#exceptions.StandardError

231
doc/usage.rst
View File

@ -41,29 +41,31 @@ basic commands::
The main entry point of Psycopg are:
- The function :func:`psycopg2.connect()` creates a new database session and
- The function :func:`~psycopg2.connect` creates a new database session and
returns a new :class:`connection` instance.
- The class :class:`connection` encapsulates a database session. It allows to:
- terminate the session using the methods :meth:`connection.commit()` and
:meth:`connection.rollback()`,
- terminate the session using the methods :meth:`~connection.commit` and
:meth:`~connection.rollback`,
- create new :class:`cursor`\ s to execute database commands and queries
using the method :meth:`connection.cursor()`.
using the method :meth:`~connection.cursor`.
- The class :class:`cursor` allows interaction with the database:
- send command using the methods :meth:`cursor.execute()` and
:meth:`cursor.executemany()`,
- send command using methods such as :meth:`~cursor.execute` and
:meth:`~cursor.executemany`,
- retrieve data using the methods :meth:`cursor.fetchone()`,
:meth:`cursor.fetchmany()`, :meth:`cursor.fetchall()`.
- retrieve data using methods such as :meth:`~cursor.fetchone`,
:meth:`~cursor.fetchmany`, :meth:`~cursor.fetchall`.
.. index:: Transaction, Begin, Commit, Rollback, Autocommit
.. _transactions-control:
Transactions control
--------------------
@ -77,29 +79,95 @@ fail, the transaction will be aborted and no further command will be executed
until a call to the :meth:`connection.rollback` method.
The connection is responsible to terminate its transaction, calling either the
:meth:`commit` or :meth:`rollback` method. Committed changes are immediately
made persistent into the database. Closing the connection using the
:meth:`close` method or destroying the connection object (calling ``del`` or
letting it fall out of scope) will result in an implicit :meth:`rollback`
call.
:meth:`~connection.commit` or :meth:`~connection.rollback` method. Committed
changes are immediately made persistent into the database. Closing the
connection using the :meth:`~connection.close` method or destroying the
connection object (calling :meth:`!__del__` or letting it fall out of scope)
will result in an implicit :meth:`!rollback` call.
It is possible to set the connection in *autocommit* mode: this way all the
commands executed will be immediately committed and no rollback is possible. A
few commands (e.g. ``CREATE DATABASE``) require to be run outside any
few commands (e.g. :sql:`CREATE DATABASE`) require to be run outside any
transaction: in order to be able to run these commands from Psycopg, the
session must be in autocommit mode. Read the documentation for
:meth:`connection.set_isolation_level` to know how to change the commit mode.
.. index::
pair: Query; Parameters
.. _query-parameters:
Passing parameters to SQL queries
---------------------------------
Psycopg casts Python variables to SQL literals by type. Many standard Python types
are already `adapted to the correct SQL representation`__.
.. __: python-types-adaptation_
Example: the Python function call::
>>> cur.execute(
... """INSERT INTO some_table (an_int, a_date, a_string)
... VALUES (%s, %s, %s);""",
... (10, datetime.date(2005, 11, 18), "O'Reilly"))
is converted into the SQL command::
INSERT INTO some_table (an_int, a_date, a_string)
VALUES (10, '2005-11-18', 'O''Reilly');
Named arguments are supported too using :samp:`%({name})s` placeholders.
Using named arguments the values can be passed to the query in any order and
many placeholder can use the same values::
>>> cur.execute(
... """INSERT INTO some_table (an_int, a_date, another_date, a_string)
... VALUES (%(int)s, %(date)s, %(date)s, %(str)s);""",
... {'int': 10, 'str': "O'Reilly", 'date': datetime.date(2005, 11, 18)})
While the mechanism resembles regular Python strings manipulation, there are a
few subtle differences you should care about when passing parameters to a
query:
- The Python string operator ``%`` is not used: the :meth:`~cursor.execute`
method accepts a tuple or dictionary of values as second parameter.
|sql-warn|__.
.. |sql-warn| replace:: **Never** use ``%`` or ``+`` to merge values
into queries
.. __: sql-injection_
- The variables placeholder must *always be a* ``%s``, even if a different
placeholder (such as a ``%d`` for integers or ``%f`` for floats) may look
more appropriate::
>>> cur.execute("INSERT INTO numbers VALUES (%d)", (42,)) # WRONG
>>> cur.execute("INSERT INTO numbers VALUES (%s)", (42,)) # correct
- For positional variables binding, *the second argument must always be a
tuple*, even if it contains a single variable::
>>> cur.execute("INSERT INTO foo VALUES (%s)", "bar") # WRONG
>>> cur.execute("INSERT INTO foo VALUES (%s)", ("bar",)) # correct
- Only variable values should be bound via this method: it shouldn't be used
to set table or field names. For these elements, ordinary string formatting
should be used before running :meth:`~cursor.execute`.
.. index:: Security, SQL injection
.. _sql-injection:
The problem with the query parameters
-------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The SQL representation for many data types is often not the same of the Python
string representation. The classic example is with single quotes in the
string representation. The classic example is with single quotes in
strings: SQL uses them as string constants bounds and requires them to be
escaped, whereas in Python single quotes can be left unescaped in strings
bounded by double quotes. For this reason a naïve approach to the composition
@ -115,7 +183,7 @@ problems::
If the variable containing the data to be sent to the database comes from an
untrusted source (e.g. a form published on a web site) an attacker could
easily craft a malformed string either gaining access to unauthorized data or
easily craft a malformed string, either gaining access to unauthorized data or
performing destructive operations on the database. This form of attack is
called `SQL injection`_ and is known to be one of the most widespread forms of
attack to servers. Before continuing, please print `this page`__ as a memo and
@ -137,7 +205,7 @@ reliable. It is really the case to stress this point:
string. Not even at gunpoint.
The correct way to pass variables in a SQL command is using the second
argument of the :meth:`cursor.execute()` method::
argument of the :meth:`~cursor.execute` method::
>>> SQL = "INSERT INTO authors (name) VALUES (%s);" # Notice: no quotes
>>> data = ("O'Reilly", )
@ -145,69 +213,6 @@ argument of the :meth:`cursor.execute()` method::
.. index::
pair: Query; Parameters
.. _query-parameters:
Passing parameters to SQL queries
---------------------------------
Psycopg casts Python variables to SQL literals by type. `Standard Python types
are already adapted to the proper SQL literal`__.
.. __: python-types-adaptation_
Example: the Python function call::
>>> cur.execute(
... """INSERT INTO some_table (an_int, a_date, a_string)
... VALUES (%s, %s, %s);""",
... (10, datetime.date(2005, 11, 18), "O'Reilly"))
is converted into the SQL command::
INSERT INTO some_table (an_int, a_date, a_string)
VALUES (10, '2005-11-18', 'O''Reilly');
Named arguments are supported too using ``%(name)s`` placeholders. Using named
arguments the values can be passed to the query in any order and many
placeholder can use the same values::
>>> cur.execute(
... """INSERT INTO some_table (an_int, a_date, another_date, a_string)
... VALUES (%(int)s, %(date)s, %(date)s, %(str)s);""",
... {'int': 10, 'str': "O'Reilly", 'date': datetime.date(2005, 11, 18)})
Notice that:
- The Python string operator ``%`` is not used: the :meth:`cursor.execute()`
method accepts a tuple or dictionary of values as second parameter.
|sql-warn|__.
.. |sql-warn| replace:: **Never** use ``%`` or ``+`` to merge values
into queries
.. __: sql-injection_
- The variables placeholder must always be a ``%s``, even if a different
placeholder (such as a ``%d`` for an integer) may look more appropriate::
>>> cur.execute("INSERT INTO numbers VALUES (%d)", (42,)) # WRONG
>>> cur.execute("INSERT INTO numbers VALUES (%s)", (42,)) # correct
- For positional variables binding, the second argument must always be a
tuple, even if it contains a single variable::
>>> cur.execute("INSERT INTO foo VALUES (%s)", "bar") # WRONG
>>> cur.execute("INSERT INTO foo VALUES (%s)", ("bar",)) # correct
- Only variable values should be bound via this method: it shouldn't be used
to set table or field names. For these elements, ordinary string formatting
should be used before running :meth:`cursor.execute()`.
.. index::
pair: Objects; Adaptation
single: Data types; Adaptation
@ -223,7 +228,7 @@ objects when a query is executed.
If you need to convert other Python types to and from PostgreSQL data types,
see :ref:`adapting-new-types` and :ref:`type-casting-from-sql-to-python`.
In the following examples the method :meth:`cursor.mogrify()` is used to show
In the following examples the method :meth:`~cursor.mogrify` is used to show
the SQL string that would be sent to the database.
.. index::
@ -257,7 +262,7 @@ the SQL string that would be sent to the database.
- String types: ``str``, ``unicode`` are converted in SQL string syntax.
``buffer`` is converted in PostgreSQL binary string syntax, suitable for
``bytea`` fields.
:sql:`bytea` fields.
.. todo:: unicode not working?
@ -267,10 +272,10 @@ the SQL string that would be sent to the database.
single: Interval objects; Adaptation
single: mx.DateTime; Adaptation
- Date and time objects: ``datetime.datetime``, ``datetime.date``,
``datetime.time``. ``datetime.timedelta`` are converted into PostgreSQL's
``timestamp``, ``date``, ``time``, ``interval`` data types. Time zones are
supported too. The Egenix `mx.DateTime`_ objects are adapted the same way::
- Date and time objects: builtin ``datetime``, ``date``, ``time``.
``timedelta`` are converted into PostgreSQL's :sql:`timestamp`, :sql:`date`,
:sql:`time`, :sql:`interval` data types. Time zones are supported too. The
Egenix `mx.DateTime`_ objects are adapted the same way::
>>> dt = datetime.datetime.now()
>>> dt
@ -286,7 +291,7 @@ the SQL string that would be sent to the database.
single: Array; Adaptation
single: Lists; Adaptation
- Python lists are converted into PostgreSQL arrays::
- Python lists are converted into PostgreSQL :sql:`ARRAY`\ s::
>>> cur.mogrify("SELECT %s;", ([10, 20, 30], ))
'SELECT ARRAY[10, 20, 30];'
@ -295,7 +300,7 @@ the SQL string that would be sent to the database.
single: Tuple; Adaptation
single: IN operator
- Python tuples are converted in a syntax suitable for the SQL ``IN``
- Python tuples are converted in a syntax suitable for the SQL :sql:`IN`
operator::
>>> cur.mogrify("SELECT %s IN %s;", (10, (10, 20, 30)))
@ -308,12 +313,12 @@ the SQL string that would be sent to the database.
.. note::
In order to use the tuple adapter, your application must import the module
:mod:`psycopg2.extensions`.
.. todo:: is this a bug or a feature?
The IN adapter is automatically registered when the
:mod:`~psycopg2.extensions` module is imported. This behaviour may change
in the future and the adapter will probably be always active.
.. versionadded:: 2.0.6
the tuple :sql:`IN` adaptation.
.. index::
pair: Server side; Cursor
@ -328,9 +333,9 @@ Server side cursors
-------------------
When a database query is executed, the Psycopg :class:`cursor` usually fetches
all the returned records, transferring them to the client process. If the
query returned an huge amount of data, a proportionally large amount of memory
will be allocated by the client.
all the records returned by the backend, transferring them to the client
process. If the query returned an huge amount of data, a proportionally large
amount of memory will be allocated by the client.
If the dataset is too large to be practically handled on the client side, it is
possible to create a *server side* cursor. Using this kind of cursor it is
@ -338,16 +343,16 @@ possible to transfer to the client only a controlled amount of data, so that a
large dataset can be examined without keeping it entirely in memory.
Server side cursor are created in PostgreSQL using the |DECLARE|_ command and
subsequently handled using ``MOVE``, ``FETCH`` and ``CLOSE`` commands.
subsequently handled using :sql:`MOVE`, :sql:`FETCH` and :sql:`CLOSE` commands.
Psycopg wraps the database server side cursor in *named cursors*. A name
cursor is created using the :meth:`connection.cursor` method specifying the
:obj:`name` parameter. Such cursor will behave mostly like a regular cursor,
allowing the user to move in the dataset using the :meth:`cursor.scroll`
methog and to read the data using :meth:`cursor.fetchone` and
:meth:`cursor.fetchmany` methods.
cursor is created using the :meth:`~connection.cursor` method specifying the
:obj:`!name` parameter. Such cursor will behave mostly like a regular cursor,
allowing the user to move in the dataset using the :meth:`~cursor.scroll`
methog and to read the data using :meth:`~cursor.fetchone` and
:meth:`~cursor.fetchmany` methods.
.. |DECLARE| replace:: ``DECLARE``
.. |DECLARE| replace:: :sql:`DECLARE`
.. _DECLARE: http://www.postgresql.org/docs/8.4/static/sql-declare.html
@ -378,23 +383,23 @@ Psycopg :class:`cursor` objects provide an interface to the efficient
PostgreSQL |COPY|__ command to move data from files to tables and back.
The methods exposed are:
:meth:`cursor.copy_from()`
:meth:`~cursor.copy_from`
Reads data *from* a file-like object appending them to a database table
(``COPY table FROM file`` syntax). The source file must have both
``read()`` and ``readline()`` method.
(:sql:`COPY table FROM file` syntax). The source file must have both
:meth:`!read` and :meth:`!readline` method.
:meth:`cursor.copy_to()`
Writes the content of a table *to* a file-like object (``COPY table TO
file`` syntax). The target file must have a ``write()`` method.
:meth:`~cursor.copy_to`
Writes the content of a table *to* a file-like object (:sql:`COPY table TO
file` syntax). The target file must have a :meth:`write` method.
:meth:`cursor.copy_expert()`
Allows to handle more specific cases and to use all the |COPY| features
available in PostgreSQL.
:meth:`~cursor.copy_expert`
Allows to handle more specific cases and to use all the :sql:`COPY`
features available in PostgreSQL.
Please refer to the documentation of the single methods for details and
examples.
.. |COPY| replace:: ``COPY``
.. |COPY| replace:: :sql:`COPY`
.. __: http://www.postgresql.org/docs/8.4/static/sql-copy.html