From c8010cfd47d693b2ad03316ae64c422e5d15aa9e Mon Sep 17 00:00:00 2001 From: Daniele Varrazzo Date: Thu, 11 Feb 2010 03:15:14 +0000 Subject: [PATCH] Big documentation cleanup. --- doc/_static/psycopg.css | 6 +- doc/advanced.rst | 99 ++++++++++------- doc/conf.py | 8 +- doc/connection.rst | 67 ++++++------ doc/cursor.rst | 206 ++++++++++++++++++----------------- doc/extensions.rst | 172 ++++++++++++++++++------------ doc/index.rst | 9 +- doc/module.rst | 79 ++++++++------ doc/usage.rst | 231 ++++++++++++++++++++-------------------- 9 files changed, 473 insertions(+), 404 deletions(-) diff --git a/doc/_static/psycopg.css b/doc/_static/psycopg.css index 3f334edb..df52b325 100644 --- a/doc/_static/psycopg.css +++ b/doc/_static/psycopg.css @@ -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 { diff --git a/doc/advanced.rst b/doc/advanced.rst index fca08c73..8bdbb460 100644 --- a/doc/advanced.rst +++ b/doc/advanced.rst @@ -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 +` 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 diff --git a/doc/conf.py b/doc/conf.py index 51212139..a891f8ec 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -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 --------------------------------------------------- diff --git a/doc/connection.rst b/doc/connection.rst index a6a1dcc7..7a6af225 100644 --- a/doc/connection.rst +++ b/doc/connection.rst @@ -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 - - diff --git a/doc/cursor.rst b/doc/cursor.rst index 6b541aeb..062e7d59 100644 --- a/doc/cursor.rst +++ b/doc/cursor.rst @@ -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 + `. 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 `. - 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. + time with :meth:`~cursor.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 - .. 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 diff --git a/doc/extensions.rst b/doc/extensions.rst index b9b298c3..5af5fbe2 100644 --- a/doc/extensions.rst +++ b/doc/extensions.rst @@ -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 +` 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. diff --git a/doc/index.rst b/doc/index.rst index 87a2ba4e..8e1bd518 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -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 ` 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: diff --git a/doc/module.rst b/doc/module.rst index a4ef75b4..e8bcffed 100644 --- a/doc/module.rst +++ b/doc/module.rst @@ -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 diff --git a/doc/usage.rst b/doc/usage.rst index 3ec9d9a3..a5606390 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -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