psycopg/psycopg2
1
1
Fork 0
mirror of https://github.com/psycopg/psycopg2.git synced 2025-01-31 17:34:08 +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 { div.dbapi-extension {
background-color: #f5ffd4; background-color: #eef;
border: 1px solid #bda; border: 1px solid #aaf;
} }
tt.sql { tt.sql {
font-size: 1em; font-size: 1em;
background-color: #fff; background-color: transparent;
} }
a > tt.sql:hover { a > tt.sql:hover {

91
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 it is the class where query building, execution and result type-casting into
Python variables happens. Python variables happens.
.. index::
single: Example; Cursor subclass
An example of cursor subclass performing logging is:: An example of cursor subclass performing logging is::
import psycopg2 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 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 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 The :meth:`~cursor.execute` method adapts its arguments to the
:class:`psycopg2.extensions.ISQLQuote` protocol. Objects that conform to this :class:`~psycopg2.extensions.ISQLQuote` protocol. Objects that conform to this
protocol expose a :meth:`getquoted()` method returning the SQL representation protocol expose a :meth:`!getquoted` method returning the SQL representation
of the object as a string. of the object as a string.
The easiest way to adapt an object to an SQL string is to register an adapter 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 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` conform object. A convenient object is the :class:`~psycopg2.extensions.AsIs`
wrapper, whose :meth:`getquoted()` result is simply the ``str()``\ ing wrapper, whose :meth:`!getquoted` result is simply the :meth:`!str`\ ing
conversion of the wrapped object. 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:: geometric type::
from psycopg2.extensions import adapt, register_adapter, AsIs from psycopg2.extensions import adapt, register_adapter, AsIs
@ -90,7 +96,7 @@ geometric type::
(Point(1.23, 4.56),)) (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 .. _point: http://www.postgresql.org/docs/8.4/static/datatype-geometric.html#AEN6084
The above function call results in the SQL command:: 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 through an user-defined adapting function. An adapter function takes two
arguments: the object string representation as returned by PostgreSQL and the arguments: the object string representation as returned by PostgreSQL and the
cursor currently being read, and should return a new Python object. For cursor currently being read, and should return a new Python object. For
example, the following function parses a PostgreSQL ``point`` into the example, the following function parses the PostgreSQL :sql:`point`
previously defined ``Point`` class:: representation into the previously defined :class:`!Point` class::
def cast_point(value, curs): def cast_point(value, curs):
if value is not None: if value is None:
return None
# Convert from (f1, f2) syntax using a regular expression. # Convert from (f1, f2) syntax using a regular expression.
m = re.match(r"\(([^)]+),([^)]+)\)", value) m = re.match(r"\(([^)]+),([^)]+)\)", value)
if m: if m:
return Point(float(m.group(1)), float(m.group(2))) return Point(float(m.group(1)), float(m.group(2)))
else:
raise InterfaceError("bad point representation: %r" % value)
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 In order to create a mapping from a PostgreSQL type (either standard or
the cursor description:: 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") curs.execute("SELECT NULL::point")
point_oid = curs.description[0][1] # usually returns 600 point_oid = curs.description[0][1] # usually returns 600
or by querying the system catalogs for the type name and namespace (the 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(""" curs.execute("""
SELECT pg_type.oid 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) POINT = psycopg2.extensions.new_type((point_oid,), "POINT", cast_point)
psycopg2.extensions.register_type(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. (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 is automatically performed when a column whose type is a registered OID is
read:: read::
@ -174,18 +185,21 @@ refer to the PostgreSQL documentation for examples of how to use this form of
communications. communications.
Notifications received are made available in the :attr:`connection.notifies` Notifications received are made available in the :attr:`connection.notifies`
list. Notifications can be sent from Python code simply using a ``NOTIFY`` list. Notifications can be sent from Python code simply using a :sql:`NOTIFY`
command in a :meth:`cursor.execute` call. command in an :meth:`~cursor.execute` call.
Because of the way sessions interact with notifications (see |NOTIFY|_ Because of the way sessions interact with notifications (see |NOTIFY|_
documentation), you should keep the connection in autocommit mode while documentation), you should keep the connection in :ref:`autocommit
sending and receiveng notification. <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 .. _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 .. _NOTIFY: http://www.postgresql.org/docs/8.4/static/sql-notify.html
.. index::
single: Example; Asynchronous notification
Example:: Example::
import sys import sys
@ -207,7 +221,7 @@ Example::
if curs.isready(): if curs.isready():
print "Got NOTIFY:", curs.connection.notifies.pop() 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:: :program:`psql` shell, the output may look similar to::
Waiting for 'NOTIFY test' Waiting for 'NOTIFY test'
@ -232,11 +246,11 @@ Asynchronous queries
Psycopg support for asynchronous queries is still experimental and the Psycopg support for asynchronous queries is still experimental and the
informations reported here may be out of date. 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 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 to the :meth:`~cursor.execute` or :meth:`~cursor.callproc` cursor methods. A
simple example, from the connection to the query:: very simple example, from the connection to the query::
conn = psycopg2.connect(database='test') conn = psycopg2.connect(database='test')
curs = conn.cursor() 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 executing the query) complete the asynchronous operation. This can happen in
a number of different ways: 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. 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 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 The return value is ``True`` if the query was successfully aborted or
``False`` if it was executed. Query result are discarded in both cases. ``False`` if it was executed. Query result are discarded in both cases.
3) :meth:`cursor.execute` is called again on the same cursor 3) :meth:`~cursor.execute` is called again on the same cursor
(:obj:`.execute()` on a different cursor will simply raise an exception). (:meth:`!execute` on a different cursor will simply raise an exception).
This waits for the complete execution of the current query, discard any This waits for the complete execution of the current query, discard any
data and execute the new one. 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 former query and will temporarily go to synchronous mode until the first of
the two queries is executed. the two queries is executed.
Cursors now have some extra methods that make them useful during Cursors now have some extra methods that make them useful during
asynchronous queries: asynchronous queries:
:meth:`cursor.fileno` :meth:`~cursor.fileno`
Returns the file descriptor associated with the current connection and 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 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`` 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:: call::
import psycopg2 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 # Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.ifconfig', extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.ifconfig' ]
'dbapi_extension' ]
# Specific extensions for Psycopg documentation.
extensions += [ 'dbapi_extension', 'sql_role' ]
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates'] templates_path = ['_templates']
@ -102,6 +104,8 @@ rst_epilog = """
http://www.postgresql.org/docs/8.4/static/transaction-iso.html#XACT-SERIALIZABLE http://www.postgresql.org/docs/8.4/static/transaction-iso.html#XACT-SERIALIZABLE
.. _mx.DateTime: http://www.egenix.com/products/python/mxBase/mxDateTime/ .. _mx.DateTime: http://www.egenix.com/products/python/mxBase/mxDateTime/
.. |MVCC| replace:: :abbr:`MVCC (Multiversion concurrency control)`
""" """
# -- Options for HTML output --------------------------------------------------- # -- Options for HTML output ---------------------------------------------------

65
doc/connection.rst
View File

@ -9,7 +9,7 @@ The ``connection`` class
a database session. a database session.
Connections are created using the factory function 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 Connections are thread safe and can be shared among many thread. See
:ref:`thread-safety` for details. :ref:`thread-safety` for details.
@ -18,18 +18,19 @@ The ``connection`` class
Return a new :class:`cursor` object using the connection. 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*. side* (or *named*) cursor. Otherwise the cursor will be *client side*.
See :ref:`server-side-cursors` for further details. 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 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:: .. extension::
The :obj:`name` and :obj:`cursor_factory` parameters are Psycopg The :obj:`!name` and :obj:`!cursor_factory` parameters are Psycopg
extensions to the DB API. extensions to the |DBAPI|.
.. index:: .. index::
pair: Transaction; Commit pair: Transaction; Commit
@ -38,7 +39,7 @@ The ``connection`` class
Commit any pending transaction to the database. Psycopg can be set to Commit any pending transaction to the database. Psycopg can be set to
perform automatic commits at each operation, see perform automatic commits at each operation, see
:meth:`connection.set_isolation_level()`. :meth:`~connection.set_isolation_level`.
.. index:: .. index::
@ -53,14 +54,14 @@ The ``connection`` class
.. method:: close() .. method:: close()
Close the connection now (rather than whenever ``__del__`` is called). Close the connection now (rather than whenever :meth:`__del__` is
The connection will be unusable from this point forward; a called). The connection will be unusable from this point forward; an
:exc:`psycopg2.Error` (or subclass) exception will be raised if any :exc:`~psycopg2.InterfaceError` will be raised if any operation is
operation is attempted with the connection. The same applies to all attempted with the connection. The same applies to all cursor objects
cursor objects trying to use the connection. Note that closing a trying to use the connection. Note that closing a connection without
connection without committing the changes first will cause an implicit committing the changes first will cause an implicit rollback to be
rollback to be performed (unless a different isolation level has been performed (unless a different isolation level has been selected: see
selected: see :meth:`connection.set_isolation_level()`). :meth:`~connection.set_isolation_level`).
.. index:: .. index::
@ -68,13 +69,13 @@ The ``connection`` class
.. rubric:: Excetptions as connection class attributes .. rubric:: Excetptions as connection class attributes
The :class:`connection` also exposes the same `Error` classes available in The :class:`!connection` also exposes as attributes the same exceptions
the :mod:`psycopg2` module as attributes. available in the :mod:`psycopg2` module. See :ref:`dbapi-exceptions`.
.. extension:: .. 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 The Psycopg connection objects exports the following additional
methods and attributes. methods and attributes.
@ -95,6 +96,8 @@ The ``connection`` class
pair: Transaction; Autocommit pair: Transaction; Autocommit
pair: Transaction; Isolation level pair: Transaction; Isolation level
.. _autocommit:
.. attribute:: isolation_level .. attribute:: isolation_level
.. method:: set_isolation_level(level) .. method:: set_isolation_level(level)
@ -106,10 +109,11 @@ The ``connection`` class
the module :mod:`psycopg2.extensions`: see the module :mod:`psycopg2.extensions`: see
:ref:`isolation-level-constants` for the available values. :ref:`isolation-level-constants` for the available values.
The default level is ``READ COMMITTED``: in this level a transaction The default level is :sql:`READ COMMITTED`: in this level a transaction
is automatically started every time a database command is executed. If is automatically started every time a database command is executed. If
you want an *autocommit* mode, set the connection in ``AUTOCOMMIT`` you want an *autocommit* mode, switch to
mode before executing any command:: :obj:`~psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT`
before executing any command::
>>> conn.set_isolation_level(psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT) >>> conn.set_isolation_level(psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT)
@ -133,7 +137,7 @@ The ``connection`` class
.. attribute:: notices .. attribute:: notices
A list containing all the database messages sent to the client during 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);") >>> cur.execute("CREATE TABLE foo (id serial PRIMARY KEY);")
>>> conn.notices >>> conn.notices
@ -155,9 +159,9 @@ The ``connection`` class
List containing asynchronous notifications received by the session. List containing asynchronous notifications received by the session.
Received notifications have the form of a 2 items tuple Received notifications have the form of a 2 items tuple
``(pid,name)``, where ``pid`` is the PID of the backend that sent the :samp:`({pid},{name})`, where :samp:`{pid}` is the PID of the backend
notification and ``name`` is the signal name specified in the that sent the notification and :samp:`{name}` is the signal name
``NOTIFY`` command. specified in the :sql:`NOTIFY` command.
For other details see :ref:`async-notify`. 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 The number is formed by converting the major, minor, and revision
numbers into two-decimal-digit numbers and appending them together. 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. .. seealso:: libpq docs for `PQserverVersion()`__ for details.
@ -262,12 +266,3 @@ The ``connection`` class
.. todo:: conn.lobject details .. 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 .. class:: cursor
Allows Python code to execute PostgreSQL command in a database session. Allows Python code to execute PostgreSQL command in a database session.
Cursors are created by the :meth:`connection.cursor`: they are bound to Cursors are created by the :meth:`connection.cursor` method: they are
the connection for the entire lifetime and all the commands are executed bound to the connection for the entire lifetime and all the commands are
in the context of the database session wrapped by the connection. executed in the context of the database session wrapped by the connection.
Cursors created from the same connection are not isolated, i.e., any 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 changes done to the database by a cursor are immediately visible by the
other cursors. Cursors created from different connections can or can not other cursors. Cursors created from different connections can or can not
be isolated, depending on the :attr:`connection.isolation_level`. See also be isolated, depending on the connections' :ref:`isolation level
:meth:`connection.rollback()` and :meth:`connection.commit()` methods. <transactions-control>`. See also :meth:`~connection.rollback` and
:meth:`~connection.commit` methods.
Cursors are *not* thread safe: a multithread application can create Cursors are *not* thread safe: a multithread application can create
many cursors from the same same connection and should use each cursor from many cursors from the same same connection and should use each cursor from
@ -36,24 +37,26 @@ The ``cursor`` class
- ``scale`` - ``scale``
- ``null_ok`` - ``null_ok``
The first two items (``name`` and ``type_code``) are mandatory, the The first two items (``name`` and ``type_code``) are always specified,
other five are optional and are set to ``None`` if no meaningful the other five are optional and are set to ``None`` if no meaningful
values can be provided. values can be provided.
This attribute will be ``None`` for operations that do not return rows This attribute will be ``None`` for operations that do not return rows
or if the cursor has not had an operation invoked via the or if the cursor has not had an operation invoked via the
|execute*|_ methods yet. |execute*|_ methods yet.
The type_code can be interpreted by comparing it to the Type Objects The ``type_code`` can be interpreted by comparing it to the Type
specified in the section :ref:`type-objects-and-constructors`. 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() .. method:: close()
Close the cursor now (rather than whenever ``__del__`` is called). Close the cursor now (rather than whenever :meth:`!__del__` is
The cursor will be unusable from this point forward; an :exc:`Error` (or called). The cursor will be unusable from this point forward; an
subclass) exception will be raised if any operation is attempted with :exc:`~psycopg2.InterfaceError` will be raised if any operation is
the cursor. attempted with the cursor.
.. attribute:: closed .. attribute:: closed
@ -84,7 +87,7 @@ The ``cursor`` class
.. |execute*| replace:: :obj:`execute*()` .. |execute*| replace:: :meth:`execute*`
.. _execute*: .. _execute*:
@ -97,23 +100,15 @@ The ``cursor`` class
Parameters may be provided as sequence or mapping and will be bound to Parameters may be provided as sequence or mapping and will be bound to
variables in the operation. Variables are specified either with 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`. :ref:`query-parameters`.
The method returns `None`. If a query was executed, the returned The method returns `None`. If a query was executed, the returned
values can be retrieved using |fetch*|_ methods. values can be retrieved using |fetch*|_ methods.
A reference to the operation will be retained by the cursor. If the If :obj:`!async` is ``True``, query execution will be asynchronous:
same operation object is passed in again, then the cursor can optimize the function returns immediately while the query is executed by the
its behavior. This is most effective for algorithms where the same backend. Use the :meth:`~cursor.isready` method to see if the data is
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
ready for return via |fetch*|_ methods. See ready for return via |fetch*|_ methods. See
:ref:`asynchronous-queries`. :ref:`asynchronous-queries`.
@ -122,11 +117,14 @@ The ``cursor`` class
The :obj:`async` parameter is a Psycopg extension to the |DBAPI|. 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 Return a query string after arguments binding. The string returned is
exactly the one that would be sent to the database running the 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:: .. extension::
@ -136,14 +134,14 @@ The ``cursor`` class
.. method:: executemany(operation, seq_of_parameters) .. method:: executemany(operation, seq_of_parameters)
Prepare a database operation (query or command) and then execute it Prepare a database operation (query or command) and then execute it
against all parameter sequences or mappings found in the sequence against all parameter tuples or mappings found in the sequence
seq_of_parameters. :obj:`!seq_of_parameters`.
The function is mostly useful for commands that update the database: The function is mostly useful for commands that update the database:
any result set returned by the query is discarded. any result set returned by the query is discarded.
Parameters are bounded to the query using the same rules described in 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]) .. 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 The procedure may also provide a result set as output. This must then
be made available through the standard |fetch*|_ methods. 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 function returns immediately while the procedure is executed by
the backend. Use the :attr:`isready` attribute to see if the data is the backend. Use the :meth:`~cursor.isready` method to see if the
ready for return via |fetch*|_ methods. See data is ready for return via |fetch*|_ methods. See
:ref:`asynchronous-queries`. :ref:`asynchronous-queries`.
.. extension:: .. extension::
@ -170,12 +168,12 @@ The ``cursor`` class
.. method:: setinputsizes(sizes) .. 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. does nothing but it is safe to call it.
.. |fetch*| replace:: :obj:`fetch*()` .. |fetch*| replace:: :meth:`!fetch*`
.. _fetch*: .. _fetch*:
@ -183,13 +181,13 @@ The ``cursor`` class
The following methods are used to read data from the database after an The following methods are used to read data from the database after an
:meth:`execute()` call. :meth:`~cursor.execute` call.
.. note:: .. note::
:class:`cursor` objects are iterable, so, instead of calling :class:`cursor` objects are iterable, so, instead of calling
explicitly :meth:`fetchone()` in a loop, the object itself can be explicitly :meth:`~cursor.fetchone` in a loop, the object itself can
used:: be used::
>>> cur.execute("SELECT * FROM test;") >>> cur.execute("SELECT * FROM test;")
>>> for record in cur: >>> for record in cur:
@ -209,7 +207,7 @@ The ``cursor`` class
>>> cur.fetchone() >>> cur.fetchone()
(4, 42, 'bar') (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 to |execute*|_ did not produce any result set or no call was issued
yet. yet.
@ -220,11 +218,11 @@ The ``cursor`` class
tuples. An empty list is returned when no more rows are available. 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. 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 If it is not given, the cursor's :attr:`~cursor.arraysize` determines
number of rows to be fetched. The method should try to fetch as many the number of rows to be fetched. The method should try to fetch as
rows as indicated by the size parameter. If this is not possible due many rows as indicated by the size parameter. If this is not possible
to the specified number of rows not being available, fewer rows may be due to the specified number of rows not being available, fewer rows
returned:: may be returned::
>>> cur.execute("SELECT * FROM test;") >>> cur.execute("SELECT * FROM test;")
>>> cur.fetchmany(2) >>> cur.fetchmany(2)
@ -234,73 +232,66 @@ The ``cursor`` class
>>> cur.fetchmany(2) >>> cur.fetchmany(2)
[] []
An :exc:`Error` (or subclass) exception is raised if the previous A :exc:`~psycopg2.ProgrammingError` is raised if the previous call to
call to |execute*|_ did not produce any result set or no call was |execute*|_ did not produce any result set or no call was issued yet.
issued yet.
Note there are performance considerations involved with the size Note there are performance considerations involved with the size
parameter. For optimal performance, it is usually best to use the parameter. For optimal performance, it is usually best to use the
:attr:`arraysize` attribute. If the size parameter is used, then it :attr:`~cursor.arraysize` attribute. If the size parameter is used,
is best for it to retain the same value from one :meth:`fetchmany()` then it is best for it to retain the same value from one
call to the next. :meth:`fetchmany` call to the next.
.. method:: fetchall() .. method:: fetchall()
Fetch all (remaining) rows of a query result, returning them as a list Fetch all (remaining) rows of a query result, returning them as a list
of tuples. Note that the cursor's :attr:`arraysize` attribute can of tuples. An empty list is returned if there is no more record to
affect the performance of this operation:: fetch.
>>> cur.execute("SELECT * FROM test;") >>> cur.execute("SELECT * FROM test;")
>>> cur.fetchall() >>> cur.fetchall()
[(1, 100, "abc'def"), (2, None, 'dada'), (4, 42, 'bar')] [(1, 100, "abc'def"), (2, None, 'dada'), (4, 42, 'bar')]
.. todo:: does arraysize influence fetchall()? A :exc:`~psycopg2.ProgrammingError` is raised if the previous call to
|execute*|_ did not produce any result set or no call was issued yet.
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.
.. method:: scroll(value[,mode='relative']) .. method:: scroll(value [, mode='relative'])
Scroll the cursor in the result set to a new position according Scroll the cursor in the result set to a new position according
to mode. 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``, the current position in the result set, if set to ``absolute``,
value states an absolute target position. value states an absolute target position.
If the scroll operation would leave the result set, a If the scroll operation would leave the result set, a
:exc:`ProgrammingError` is raised and the cursor position is not :exc:`~psycopg2.ProgrammingError` is raised and the cursor position is
changed. 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 .. note::
(named) cursors.
According to the |DBAPI|_, the exception raised for a cursor out
of bound should have been :exc:`!IndexError`.
.. attribute:: arraysize .. attribute:: arraysize
This read/write attribute specifies the number of rows to fetch at a 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 time with :meth:`~cursor.fetchmany`. It defaults to 1 meaning to fetch
single row at a time. 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
.. attribute:: rowcount .. attribute:: rowcount
This read-only attribute specifies the number of rows that the last This read-only attribute specifies the number of rows that the last
|execute*|_ produced (for DQL statements like ``SELECT``) or |execute*|_ produced (for :abbr:`DQL (Data Query Language)` statements
affected (for DML statements like ``UPDATE`` or ``INSERT``). 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 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 the cursor or the row count of the last operation if it can't be
@ -327,32 +318,32 @@ The ``cursor`` class
.. attribute:: lastrowid .. attribute:: lastrowid
This read-only attribute provides the *oid* of the last row inserted 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 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 last operation is not a single record insert, the attribute is set to
``None``. ``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 default for |CREATE-TABLE|__ is to not support them. The
|INSERT-RETURNING|__ syntax available from PostgreSQL 8.3 allows more |INSERT-RETURNING|__ syntax available from PostgreSQL 8.3 allows more
flexibility: flexibility:
.. |CREATE-TABLE| replace:: ``CREATE TABLE`` .. |CREATE-TABLE| replace:: :sql:`CREATE TABLE`
.. __: http://www.postgresql.org/docs/8.4/static/sql-createtable.html .. __: 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 .. __: http://www.postgresql.org/docs/8.4/static/sql-insert.html
.. method:: nextset() .. method:: nextset()
This method is not supported (PostgreSQL does not have multiple data 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]) .. 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. does nothing but it is safe to call it.
@ -373,7 +364,8 @@ The ``cursor`` class
.. attribute:: statusmessage .. 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.execute("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
>>> cur.statusmessage >>> cur.statusmessage
@ -400,12 +392,12 @@ The ``cursor`` class
Return the file descriptor associated with the current connection and Return the file descriptor associated with the current connection and
make possible to use a cursor in a context where a file object would 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`. :ref:`asynchronous-queries`.
.. extension:: .. 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:: .. 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) .. method:: copy_from(file, table, sep='\\t', null='\\N', columns=None)
Read data *from* the file-like object :obj:`file` appending them to Read data *from* the file-like object :obj:`!file` appending them to
the table named :obj:`table`. :obj:`file` must have both ``read()`` the table named :obj:`!table`. :obj:`!file` must have both
and ``readline()`` method. See :ref:`copy` for an overview. :meth:`!read` and :meth:`!readline` method. See :ref:`copy` for an
overview.
The optional argument :obj:`sep` is the columns separator and The optional argument :obj:`!sep` is the columns separator and
:obj:`null` represents ``NULL`` values in the file. :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 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 type should match the content of the read file. If not specifies, it
is assumed that the entire table matches the file structure. :: 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) .. 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 Write the content of the table named :obj:`!table` *to* the file-like
:ref:`copy` for an overview. 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 The optional argument :obj:`!sep` is the columns separator and
:obj:`null` represents ``NULL`` values in the file. :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. :: ``None`` only the specified fields will be included in the dump. ::
>>> cur.copy_to(sys.stdout, 'test', sep="|") >>> cur.copy_to(sys.stdout, 'test', sep="|")
@ -461,21 +456,22 @@ The ``cursor`` class
.. method:: copy_expert(sql, file [, size]) .. 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 handle all the parameters that PostgreSQL makes available (see
|COPY|__ command documentation). |COPY|__ command documentation).
:obj:`file` must be an open, readable file for ``COPY FROM`` or an :obj:`!file` must be an open, readable file for :sql:`COPY FROM` or an
open, writeable file for ``COPY TO``. The optional :obj:`size` open, writeable file for :sql:`COPY TO`. The optional :obj:`!size`
argument, when specified for a ``COPY FROM`` statement, will be passed argument, when specified for a :sql:`COPY FROM` statement, will be
to file's read method to control the read buffer size. :: 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) >>> cur.copy_expert("COPY test TO STDOUT WITH CSV HEADER", sys.stdout)
id,num,data id,num,data
1,100,abc'def 1,100,abc'def
2,,dada 2,,dada
.. |COPY| replace:: ``COPY`` .. |COPY| replace:: :sql:`COPY`
.. __: http://www.postgresql.org/docs/8.4/static/sql-copy.html .. __: http://www.postgresql.org/docs/8.4/static/sql-copy.html
.. versionadded:: 2.0.6 .. versionadded:: 2.0.6

170
doc/extensions.rst
View File

@ -6,25 +6,25 @@
.. module:: psycopg2.extensions .. module:: psycopg2.extensions
The module contains a few objects and function extending the minimum set of 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 .. 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 It is exposed by the :mod:`extensions` module in order to allow
subclassing to extend its behaviour: the subclass should be passed to the 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`. See also :ref:`subclassing-connection`.
For a complete description of the class, see :class:`connection`. For a complete description of the class, see :class:`connection`.
.. class:: cursor .. 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 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 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`. also :ref:`subclassing-cursor`.
For a complete description of the class, see :class:`cursor`. For a complete description of the class, see :class:`cursor`.
@ -50,13 +50,13 @@ deal with Python objects adaptation:
.. function:: adapt(obj) .. function:: adapt(obj)
Return the SQL representation of :obj:`obj` as a string. Raise a Return the SQL representation of :obj:`obj` as a string. Raise a
:exc:`ProgrammingError` if how to adapt the object is unknown. In order :exc:`~psycopg2.ProgrammingError` if how to adapt the object is unknown.
to allow new objects to be adapted, register a new adapter for it using In order to allow new objects to be adapted, register a new adapter for it
the :func:`register_adapter` function. using the :func:`register_adapter` function.
The function is the entry point of the adaptation mechanism: it can be The function is the entry point of the adaptation mechanism: it can be
used to write adapters for complex objects by recursively calling 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) .. 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 :data:`adapter` should be a function taking a single argument (the object
to adapt) and returning an object conforming the :class:`ISQLQuote` 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. often useful for this task.
Once an object is registered, it can be safely used in SQL queries and by Once an object is registered, it can be safely used in SQL queries and by
the :func:`adapt` function. the :func:`adapt` function.
.. class:: ISQLQuote .. class:: ISQLQuote(wrapped_object)
Represents the SQL adaptation protocol. Objects conforming this protocol Represents the SQL adaptation protocol. Objects conforming this protocol
should implement a :meth:`getquoted` method. 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:: .. attribute:: _wrapped
what the ISQLQuote methods are for? In my understanding the
class is only used as symbol to dispatch adaptation and not to be The wrapped object passes to the constructor
instantiated.
.. 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 .. class:: AsIs
@ -89,7 +95,7 @@ deal with Python objects adaptation:
.. method:: getquoted() .. method:: getquoted()
Return the ``str()`` conversion of the wrapped object. :: Return the :meth:`str` conversion of the wrapped object. ::
>>> AsIs(42).getquoted() >>> AsIs(42).getquoted()
'42' '42'
@ -121,28 +127,30 @@ deal with Python objects adaptation:
>>> Binary("\x00\x08\x0F").getquoted() >>> Binary("\x00\x08\x0F").getquoted()
"'\\\\000\\\\010\\\\017'" "'\\\\000\\\\010\\\\017'"
.. todo:: .. versionchanged:: 2.0.14(ish)
previously the adapter was not exposed by the :mod:`extensions`
this class is actually not importd in module extensions: I'd say this module. In older version it can be imported from the implementation
is a bug. module :mod:`!psycopg2._psycopg`.
.. data:: Boolean
.. data:: Float .. class:: Boolean
.. class:: Float
.. class:: SQL_IN
Specialized adapters for builtin objects. Specialized adapters for builtin objects.
.. data:: DateFromPy .. class:: DateFromPy
.. data:: TimeFromPy .. class:: TimeFromPy
.. data:: TimestampFromPy .. class:: TimestampFromPy
.. data:: IntervalFromPy .. class:: IntervalFromPy
Specialized adapters for Python datetime objects. Specialized adapters for Python datetime objects.
.. data:: DateFromMx .. class:: DateFromMx
.. data:: TimeFromMx .. class:: TimeFromMx
.. data:: TimestampFromMx .. class:: TimestampFromMx
.. data:: IntervalFromMx .. class:: IntervalFromMx
Specialized adapters for `mx.DateTime`_ objects. Specialized adapters for `mx.DateTime`_ objects.
@ -170,13 +178,14 @@ details.
:param name: the name of the new type adapter. :param name: the name of the new type adapter.
:param adapter: the adaptation function. :param adapter: the adaptation function.
The object OID can be read from the :data:`cursor.description` or directly The object OID can be read from the :data:`cursor.description` attribute
from the PostgreSQL catalog. or by querying from the PostgreSQL catalog.
:data:`adapter` should have signature ``fun(value, cur)`` where :data:`adapter` should have signature :samp:`fun({value}, {cur})` where
``value`` is the string representation returned by PostgreSQL and ``cur`` :samp:`{value}` is the string representation returned by PostgreSQL and
is the cursor from which data are read. In case of ``NULL``, ``value`` is :samp:`{cur}` is the cursor from which data are read. In case of
``None``. The adapter should return the converted object. :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. 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`. 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 :class:`cursor`: the type caster will be effective only limited to the
specified object. Otherwise it will be globally registered. specified object. Otherwise it will be globally registered.
.. todo:: Please confirm the above behaviour.
.. data:: string_types .. data:: string_types
The global register of type casters. 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:: .. index::
@ -208,43 +244,45 @@ details.
Isolation level constants 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 `transaction isolation level`_. The current transaction level can be read
from the :attr:`connection.isolation_level` attribute. The default isolation from the :attr:`~connection.isolation_level` attribute. The default isolation
level is ``READ COMMITTED``. A different isolation level con be set through level is :sql:`READ COMMITTED`. A different isolation level con be set
the :meth:`connection.set_isolation_level()` method. The level can be set to through the :meth:`~connection.set_isolation_level` method. The level can be
one of the following constants: set to one of the following constants:
.. data:: ISOLATION_LEVEL_AUTOCOMMIT .. data:: ISOLATION_LEVEL_AUTOCOMMIT
No transaction is started when command are issued and no ``commit()`` or No transaction is started when command are issued and no
``rollback()`` is required. Some PostgreSQL command such as ``CREATE :meth:`~connection.commit` or :meth:`~connection.rollback` is required.
DATABASE`` can't run into a transaction: to run such command use:: 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) >>> conn.set_isolation_level(ISOLATION_LEVEL_AUTOCOMMIT)
.. data:: ISOLATION_LEVEL_READ_UNCOMMITTED .. data:: ISOLATION_LEVEL_READ_UNCOMMITTED
This isolation level is defined in the SQL standard but not available in 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 ``READ the |MVCC| model of PostgreSQL: it is replaced by the stricter :sql:`READ
COMMITTED``. COMMITTED`.
.. data:: ISOLATION_LEVEL_READ_COMMITTED .. data:: ISOLATION_LEVEL_READ_COMMITTED
This is the default value. A new transaction is started at the first 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()`` :meth:`~cursor.execute` command on a cursor and at each new
after a :meth:`connection.commit()` or a :meth:`connection.rollback()`. :meth:`!execute` after a :meth:`~connection.commit` or a
The transaction runs in the PostgreSQL ``READ COMMITTED`` isolation level. :meth:`~connection.rollback`. The transaction runs in the PostgreSQL
:sql:`READ COMMITTED` isolation level.
.. data:: ISOLATION_LEVEL_REPEATABLE_READ .. data:: ISOLATION_LEVEL_REPEATABLE_READ
This isolation level is defined in the SQL standard but not available in The :sql:`REPEATABLE READ` isolation level is defined in the SQL standard
the MVCC model of PostgreSQL: it is replaced by the stricter but not available in the |MVCC| model of PostgreSQL: it is replaced by the
``SERIALIZABLE``. stricter :sql:`SERIALIZABLE`.
.. data:: ISOLATION_LEVEL_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 strictest transactions isolation level, equivalent to having the
transactions executed serially rather than concurrently. However transactions executed serially rather than concurrently. However
applications using this level must be prepared to retry reansactions due 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 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 .. data:: TRANSACTION_STATUS_IDLE
@ -295,13 +333,11 @@ Connection status constants
--------------------------- ---------------------------
These values represent the possible status of a connection: the current value These values represent the possible status of a connection: the current value
can be read from the :data:`connection.status` attribute. can be read from the :data:`~connection.status` attribute.
.. todo:: check if these values are really useful or not.
.. data:: STATUS_SETUP .. data:: STATUS_SETUP
Defined but not used. Used internally.
.. data:: STATUS_READY .. data:: STATUS_READY
@ -317,10 +353,10 @@ can be read from the :data:`connection.status` attribute.
.. data:: STATUS_SYNC .. data:: STATUS_SYNC
Defined but not used. Used internally.
.. data:: STATUS_ASYNC .. 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|_ 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 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 heavily multi-threaded applications that create and destroy lots of cursors and
make a conspicuous number of concurrent INSERTs or UPDATEs. The psycopg make a conspicuous number of concurrent :sql:`INSERT`\ s or :sql:`UPDATE`\ s.
distribution includes ZPsycopgDA, a Zope_ Database Adapter. 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 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 features complete libpq_ v3 protocol, |COPY-TO-FROM|__ and full :ref:`object
adaptation for all basic Python 2.3 types: strings (including unicode), ints, adaptation <python-types-adaptation>` for all basic Python types: strings (including unicode), ints,
longs, floats, buffers (binary objects), booleans, `mx.DateTime`_ and builtin longs, floats, buffers (binary objects), booleans, `mx.DateTime`_ and builtin
datetime types. It also supports unicode queries and Python lists mapped to datetime types. It also supports unicode queries and Python lists mapped to
PostgreSQL arrays. PostgreSQL arrays.
@ -22,6 +22,7 @@ PostgreSQL arrays.
.. _Python: http://www.python.org/ .. _Python: http://www.python.org/
.. _Zope: http://www.zope.org/ .. _Zope: http://www.zope.org/
.. _libpq: http://www.postgresql.org/docs/8.4/static/libpq.html .. _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 .. __: http://www.postgresql.org/docs/8.4/static/sql-copy.html
Contents: 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: The full list of available parameters is:
- ``dbname`` the database name (only in dsn string) - :obj:`!dbname` -- the database name (only in dsn string)
- ``database`` the database name (only as keyword argument) - :obj:`!database` -- the database name (only as keyword argument)
- ``user`` user name used to authenticate - :obj:`!user` -- user name used to authenticate
- ``password`` password used to authenticate - :obj:`!password` -- password used to authenticate
- ``host`` database host address (defaults to UNIX socket if not provided) - :obj:`!host` -- database host address (defaults to UNIX socket if not provided)
- ``port`` connection port number (defaults to 5432 if not provided) - :obj:`!port` -- connection port number (defaults to 5432 if not provided)
- ``sslmode`` `SSL TCP/IP negotiation`__ mode - :obj:`!sslmode` -- `SSL TCP/IP negotiation`__ mode
.. __: http://www.postgresql.org/docs/8.4/static/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS .. __: 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 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. details.
.. extension:: .. extension::
@ -69,27 +69,29 @@ The module interface respects the standard defined in the |DBAPI|_.
:ref:`query-parameters`. :ref:`query-parameters`.
.. index:: Exceptions
.. index::
single: Exceptions; DB API
.. _dbapi-exceptions:
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: available through the following exceptions:
.. exception:: Warning .. exception:: Warning
Exception raised for important warnings like data truncations while Exception raised for important warnings like data truncations while
inserting, etc. It is a subclass of the Python |StandardError|_ (defined in inserting, etc. It is a subclass of the Python |StandardError|_.
the module exceptions).
.. exception:: Error .. exception:: Error
Exception that is the base class of all other error exceptions. You can 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 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 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 is a subclass of the Python |StandardError|_.
exceptions).
.. exception:: InterfaceError .. exception:: InterfaceError
@ -136,30 +138,43 @@ available through the following exceptions:
.. exception:: NotSupportedError .. exception:: NotSupportedError
Exception raised in case a method or database API was used which is not 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 supported by the database, e.g. requesting a :meth:`!rollback` on a
that does not support transaction or has transactions turned off. It is a connection that does not support transaction or has transactions turned
subclass of :exc:`DatabaseError`. 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: This is the exception inheritance layout:
- |StandardError|_ .. parsed-literal::
- :exc:`Warning` |StandardError|_
- :exc:`Error` \|__ :exc:`Warning`
\|__ :exc:`Error`
- :exc:`InterfaceError` \|__ :exc:`InterfaceError`
- :exc:`DatabaseError` \|__ :exc:`DatabaseError`
\|__ :exc:`DataError`
- :exc:`DataError` \|__ :exc:`OperationalError`
- :exc:`OperationalError` \| \|__ :exc:`psycopg2.extensions.QueryCanceledError`
- :exc:`IntegrityError` \| \|__ :exc:`psycopg2.extensions.TransactionRollbackError`
- :exc:`InternalError` \|__ :exc:`IntegrityError`
- :exc:`ProgrammingError` \|__ :exc:`InternalError`
- :exc:`NotSupportedError` \|__ :exc:`ProgrammingError`
\|__ :exc:`NotSupportedError`
.. |StandardError| replace:: ``StandardError`` .. |StandardError| replace:: :exc:`!StandardError`
.. _StandardError: http://docs.python.org/library/exceptions.html#exceptions.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 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. returns a new :class:`connection` instance.
- The class :class:`connection` encapsulates a database session. It allows to: - The class :class:`connection` encapsulates a database session. It allows to:
- terminate the session using the methods :meth:`connection.commit()` and - terminate the session using the methods :meth:`~connection.commit` and
:meth:`connection.rollback()`, :meth:`~connection.rollback`,
- create new :class:`cursor`\ s to execute database commands and queries - 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: - The class :class:`cursor` allows interaction with the database:
- send command using the methods :meth:`cursor.execute()` and - send command using methods such as :meth:`~cursor.execute` and
:meth:`cursor.executemany()`, :meth:`~cursor.executemany`,
- retrieve data using the methods :meth:`cursor.fetchone()`, - retrieve data using methods such as :meth:`~cursor.fetchone`,
:meth:`cursor.fetchmany()`, :meth:`cursor.fetchall()`. :meth:`~cursor.fetchmany`, :meth:`~cursor.fetchall`.
.. index:: Transaction, Begin, Commit, Rollback, Autocommit .. index:: Transaction, Begin, Commit, Rollback, Autocommit
.. _transactions-control:
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. until a call to the :meth:`connection.rollback` method.
The connection is responsible to terminate its transaction, calling either the The connection is responsible to terminate its transaction, calling either the
:meth:`commit` or :meth:`rollback` method. Committed changes are immediately :meth:`~connection.commit` or :meth:`~connection.rollback` method. Committed
made persistent into the database. Closing the connection using the changes are immediately made persistent into the database. Closing the
:meth:`close` method or destroying the connection object (calling ``del`` or connection using the :meth:`~connection.close` method or destroying the
letting it fall out of scope) will result in an implicit :meth:`rollback` connection object (calling :meth:`!__del__` or letting it fall out of scope)
call. will result in an implicit :meth:`!rollback` call.
It is possible to set the connection in *autocommit* mode: this way all the 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 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 transaction: in order to be able to run these commands from Psycopg, the
session must be in autocommit mode. Read the documentation for session must be in autocommit mode. Read the documentation for
:meth:`connection.set_isolation_level` to know how to change the commit mode. :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 .. index:: Security, SQL injection
.. _sql-injection: .. _sql-injection:
The problem with the query parameters The problem with the query parameters
------------------------------------- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The SQL representation for many data types is often not the same of the Python 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 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 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 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 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 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 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 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 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. string. Not even at gunpoint.
The correct way to pass variables in a SQL command is using the second 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 >>> SQL = "INSERT INTO authors (name) VALUES (%s);" # Notice: no quotes
>>> data = ("O'Reilly", ) >>> 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:: .. index::
pair: Objects; Adaptation pair: Objects; Adaptation
single: Data types; 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, 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`. 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. the SQL string that would be sent to the database.
.. index:: .. 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. - String types: ``str``, ``unicode`` are converted in SQL string syntax.
``buffer`` is converted in PostgreSQL binary string syntax, suitable for ``buffer`` is converted in PostgreSQL binary string syntax, suitable for
``bytea`` fields. :sql:`bytea` fields.
.. todo:: unicode not working? .. todo:: unicode not working?
@ -267,10 +272,10 @@ the SQL string that would be sent to the database.
single: Interval objects; Adaptation single: Interval objects; Adaptation
single: mx.DateTime; Adaptation single: mx.DateTime; Adaptation
- Date and time objects: ``datetime.datetime``, ``datetime.date``, - Date and time objects: builtin ``datetime``, ``date``, ``time``.
``datetime.time``. ``datetime.timedelta`` are converted into PostgreSQL's ``timedelta`` are converted into PostgreSQL's :sql:`timestamp`, :sql:`date`,
``timestamp``, ``date``, ``time``, ``interval`` data types. Time zones are :sql:`time`, :sql:`interval` data types. Time zones are supported too. The
supported too. The Egenix `mx.DateTime`_ objects are adapted the same way:: Egenix `mx.DateTime`_ objects are adapted the same way::
>>> dt = datetime.datetime.now() >>> dt = datetime.datetime.now()
>>> dt >>> dt
@ -286,7 +291,7 @@ the SQL string that would be sent to the database.
single: Array; Adaptation single: Array; Adaptation
single: Lists; 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], )) >>> cur.mogrify("SELECT %s;", ([10, 20, 30], ))
'SELECT ARRAY[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: Tuple; Adaptation
single: IN operator 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:: operator::
>>> cur.mogrify("SELECT %s IN %s;", (10, (10, 20, 30))) >>> 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:: .. note::
In order to use the tuple adapter, your application must import the module The IN adapter is automatically registered when the
:mod:`psycopg2.extensions`. :mod:`~psycopg2.extensions` module is imported. This behaviour may change
in the future and the adapter will probably be always active.
.. todo:: is this a bug or a feature?
.. versionadded:: 2.0.6 .. versionadded:: 2.0.6
the tuple :sql:`IN` adaptation.
.. index:: .. index::
pair: Server side; Cursor pair: Server side; Cursor
@ -328,9 +333,9 @@ Server side cursors
------------------- -------------------
When a database query is executed, the Psycopg :class:`cursor` usually fetches When a database query is executed, the Psycopg :class:`cursor` usually fetches
all the returned records, transferring them to the client process. If the all the records returned by the backend, transferring them to the client
query returned an huge amount of data, a proportionally large amount of memory process. If the query returned an huge amount of data, a proportionally large
will be allocated by the client. 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 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 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. large dataset can be examined without keeping it entirely in memory.
Server side cursor are created in PostgreSQL using the |DECLARE|_ command and 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 Psycopg wraps the database server side cursor in *named cursors*. A name
cursor is created using the :meth:`connection.cursor` method specifying the cursor is created using the :meth:`~connection.cursor` method specifying the
:obj:`name` parameter. Such cursor will behave mostly like a regular cursor, :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` allowing the user to move in the dataset using the :meth:`~cursor.scroll`
methog and to read the data using :meth:`cursor.fetchone` and methog and to read the data using :meth:`~cursor.fetchone` and
:meth:`cursor.fetchmany` methods. :meth:`~cursor.fetchmany` methods.
.. |DECLARE| replace:: ``DECLARE`` .. |DECLARE| replace:: :sql:`DECLARE`
.. _DECLARE: http://www.postgresql.org/docs/8.4/static/sql-declare.html .. _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. PostgreSQL |COPY|__ command to move data from files to tables and back.
The methods exposed are: 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 Reads data *from* a file-like object appending them to a database table
(``COPY table FROM file`` syntax). The source file must have both (:sql:`COPY table FROM file` syntax). The source file must have both
``read()`` and ``readline()`` method. :meth:`!read` and :meth:`!readline` method.
:meth:`cursor.copy_to()` :meth:`~cursor.copy_to`
Writes the content of a table *to* a file-like object (``COPY table TO Writes the content of a table *to* a file-like object (:sql:`COPY table TO
file`` syntax). The target file must have a ``write()`` method. file` syntax). The target file must have a :meth:`write` method.
:meth:`cursor.copy_expert()` :meth:`~cursor.copy_expert`
Allows to handle more specific cases and to use all the |COPY| features Allows to handle more specific cases and to use all the :sql:`COPY`
available in PostgreSQL. features available in PostgreSQL.
Please refer to the documentation of the single methods for details and Please refer to the documentation of the single methods for details and
examples. examples.
.. |COPY| replace:: ``COPY`` .. |COPY| replace:: :sql:`COPY`
.. __: http://www.postgresql.org/docs/8.4/static/sql-copy.html .. __: http://www.postgresql.org/docs/8.4/static/sql-copy.html