
Psycopg -- PostgreSQL database adapter for Python
*************************************************

Psycopg is a PostgreSQL database adapter for the Python programming
language.  Its main advantages are that it supports the full Python DB
API 2.0 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
'INSERT's or '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 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.

-[ Contents ]-

* Basic module usage
  * Passing parameters to SQL queries
  * Adaptation of Python values to SQL types
  * Transactions control
  * Server side cursors
  * Thread safety
  * Using COPY TO and COPY FROM
  * Access to PostgreSQL large objects
* The 'psycopg2' module content
  * Exceptions
  * Type Objects and Constructors
* The 'connection' class
* The 'cursor' class
* More advanced topics
  * Connection and cursor factories
  * Adapting new Python types to SQL syntax
  * Type casting of SQL types into Python objects
  * Asynchronous notifications
  * Asynchronous queries
* 'psycopg2.extensions' -- Extensions to the DB API
  * SQL adaptation protocol objects
  * Database types casting functions
  * Additional exceptions
  * Isolation level constants
  * Transaction status constants
  * Connection status constants
  * Additional database types
* 'psycopg2.tz' --  'tzinfo' implementations for Psycopg 2
* 'psycopg2.pool' -- Connections pooling
* 'psycopg2.extras' -- Miscellaneous goodies for Psycopg 2
  * Dictionary-like cursor
  * Logging cursor
  * UUID data type
  * 'inet' data type
  * Fractional time zones
* 'psycopg2.errorcodes' -- Error codes defined by PostgreSQL
* Frequently Asked Questions


Basic module usage
******************

The basic Psycopg usage is common to all the database adapters
implementing the DB API 2.0 protocol. Here is an interactive session
showing some of the basic commands:

   >>> import psycopg2

   # Connect to an existing database
   >>> conn = psycopg2.connect("dbname=test user=postgres")

   # Open a cursor to perform database operations
   >>> cur = conn.cursor()

   # Execute a command: this creates a new table
   >>> cur.execute("CREATE TABLE test (id serial PRIMARY KEY, num integer, data varchar);")

   # Pass data to fill a query placeholders and let Psycopg perform
   # the correct conversion (no more SQL injections!)
   >>> cur.execute("INSERT INTO test (num, data) VALUES (%s, %s)",
   ...      (100, "abc'def"))

   # Query the database and obtain data as Python objects
   >>> cur.execute("SELECT * FROM test;")
   >>> cur.fetchone()
   (1, 100, "abc'def")

   # Make the changes to the database persistent
   >>> conn.commit()

   # Close communication with the database
   >>> cur.close()
   >>> conn.close()

The main entry point of Psycopg are:

* The function 'connect()' creates a new database session and
  returns a new 'connection' instance.

* The class 'connection' encapsulates a database session. It allows
  to:

  * create new 'cursor's using the 'cursor()' method to execute
    database commands and queries,

  * terminate the session using the methods 'commit()' or
    'rollback()'.

* The class 'cursor' allows interaction with the database:

  * send commands to the database using methods such as 'execute()'
    and 'executemany()',

  * retrieve data from the database *by iteration* or using methods
    such as 'fetchone()', 'fetchmany()', 'fetchall()'.


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.

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)})

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 'execute()'
  method accepts a tuple or dictionary of values as second parameter.
  **Never** use '%' or '+' to merge values into queries.

* 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.  And remember
  that Python requires a comma to create a single element tuple:

     >>> cur.execute("INSERT INTO foo VALUES (%s)", "bar")    # WRONG
     >>> 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 'execute()'.


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 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 of query strings, e.g. using string
concatenation, is a recipe for terrible problems:

   >>> SQL = "INSERT INTO authors (name) VALUES ('%s');" # NEVER DO THIS
   >>> data = ("O'Reilly", )
   >>> cur.execute(SQL % data) # THIS WILL FAIL MISERABLY
   ProgrammingError: syntax error at or near "Reilly"
   LINE 1: INSERT INTO authors (name) VALUES ('O'Reilly')
                                                 ^

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 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 hang it onto your
desk.

Psycopg can convert automatically Python objects into and from SQL
literals: using this feature your code will result more robust and
reliable. It is really the case to stress this point:

Warning: Never, **never**, **NEVER** use Python string concatenation ('+')
  or string parameters interpolation ('%') to pass variables to a
  SQL query string.  Not even at gunpoint.

The correct way to pass variables in a SQL command is using the second
argument of the 'execute()' method:

   >>> SQL = "INSERT INTO authors (name) VALUES (%s);" # Notice: no quotes
   >>> data = ("O'Reilly", )
   >>> cur.execute(SQL, data) # Notice: no % operator


Adaptation of Python values to SQL types
========================================

Many standards Python types are adapted into SQL and returned as
Python objects when a query is executed.

If you need to convert other Python types to and from PostgreSQL data
types, see *Adapting new Python types to SQL syntax* and *Type casting
of SQL types into Python objects*.  You can also find a few other
specialized adapters in the 'psycopg2.extras' module.

In the following examples the method 'mogrify()' is used to show the
SQL string that would be sent to the database.

* Python 'None' and boolean values are converted into the proper SQL
  literals:

     >>> cur.mogrify("SELECT %s, %s, %s;", (None, True, False))
     >>> 'SELECT NULL, true, false;'

* Numeric objects: 'int', 'long', 'float', 'Decimal' are
  converted in the PostgreSQL numerical representation:

     >>> cur.mogrify("SELECT %s, %s, %s, %s;", (10, 10L, 10.0, Decimal("10.00")))
     >>> 'SELECT 10, 10, 10.0, 10.00;'

* String types: 'str', 'unicode' are converted in SQL string
  syntax.  'buffer' is converted in PostgreSQL binary string syntax,
  suitable for 'bytea' fields. When reading textual fields, either
  'str' or 'unicode' can be received: see *Unicode handling*.

* Date and time objects: builtin 'datetime', 'date', 'time'.
  '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:

     >>> dt = datetime.datetime.now()
     >>> dt
     datetime.datetime(2010, 2, 8, 1, 40, 27, 425337)

     >>> cur.mogrify("SELECT %s, %s, %s;", (dt, dt.date(), dt.time()))
     "SELECT '2010-02-08T01:40:27.425337', '2010-02-08', '01:40:27.425337';"

     >>> cur.mogrify("SELECT %s;", (dt - datetime.datetime(2010,1,1),))
     "SELECT '38 days 6027.425337 seconds';"

* Python lists are converted into PostgreSQL 'ARRAY's:

     >>> cur.mogrify("SELECT %s;", ([10, 20, 30], ))
     'SELECT ARRAY[10, 20, 30];'

* Python tuples are converted in a syntax suitable for the SQL 'IN'
  operator:

     >>> cur.mogrify("SELECT %s IN %s;", (10, (10, 20, 30)))
     'SELECT 10 IN (10, 20, 30);'

  Note: SQL doesn't allow an empty list in the IN operator, so your code
    should guard against empty tuples.

  New in version 2.0.6: the tuple 'IN' adaptation.

  Changed in version 2.0.14: the tuple 'IN' adapter is always
  active.  In previous releases it was necessary to import the
  'extensions' module to have it registered.


Unicode handling
----------------

Psycopg can exchange Unicode data with a PostgreSQL database.  Python
'unicode' objects are automatically *encoded* in the client encoding
defined on the database connection (the PostgreSQL encoding, available
in 'connection.encoding', is translated into a Python codec using
the 'encodings' mapping):

   >>> print u, type(u)
   àèìòù€ <type 'unicode'>

   >>> cur.execute("INSERT INTO test (num, data) VALUES (%s,%s);", (74, u))

When reading data from the database, the strings returned are usually
8 bit 'str' objects encoded in the database client encoding:

   >>> print conn.encoding
   UTF8

   >>> cur.execute("SELECT data FROM test WHERE num = 74")
   >>> x = cur.fetchone()[0]
   >>> print x, type(x), repr(x)
   àèìòù€ <type 'str'> '\xc3\xa0\xc3\xa8\xc3\xac\xc3\xb2\xc3\xb9\xe2\x82\xac'

   >>> conn.set_client_encoding('LATIN9')

   >>> cur.execute("SELECT data FROM test WHERE num = 74")
   >>> x = cur.fetchone()[0]
   >>> print type(x), repr(x)
   <type 'str'> '\xe0\xe8\xec\xf2\xf9\xa4'

In order to obtain 'unicode' objects instead, it is possible to
register a typecaster so that PostgreSQL textual types are
automatically *decoded* using the current client encoding:

   >>> psycopg2.extensions.register_type(psycopg2.extensions.UNICODE, cur)

   >>> cur.execute("SELECT data FROM test WHERE num = 74")
   >>> x = cur.fetchone()[0]
   >>> print x, type(x), repr(x)
   àèìòù€ <type 'unicode'> u'\xe0\xe8\xec\xf2\xf9\u20ac'

In the above example, the 'UNICODE' typecaster is registered only on
the cursor. It is also possible to register typecasters on the
connection or globally: see the function 'register_type()' and *Type
casting of SQL types into Python objects* for details.

Note: If you want to receive uniformly all your database input in Unicode,
  you can register the related typecasters globally as soon as Psycopg
  is imported:

     import psycopg2
     import psycopg2.extensions
     psycopg2.extensions.register_type(psycopg2.extensions.UNICODE)
     psycopg2.extensions.register_type(psycopg2.extensions.UNICODEARRAY)

  and then forget about this story.


Transactions control
====================

In Psycopg transactions are handled by the 'connection' class. By
default, the first time a command is sent to the database (using one
of the 'cursor's created by the connection), a new transaction is
created. The following database commands will be executed in the
context of the same transaction -- not only the commands issued by the
first cursor, but the ones issued by all the cursors created by the
same connection.  Should any command fail, the transaction will be
aborted and no further command will be executed until a call to the
'connection.rollback()' method.

The connection is responsible to terminate its transaction, calling
either the 'commit()' or 'rollback()' method.  Committed changes
are immediately made persistent into the database.  Closing the
connection using the 'close()' method or destroying the connection
object (calling '__del__()' or letting it fall out of scope) will
result in an implicit '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',
'VACUUM'...) 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
'connection.set_isolation_level()' to know how to change the commit
mode.


Server side cursors
===================

When a database query is executed, the Psycopg 'cursor' usually
fetches 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 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.

Psycopg wraps the database server side cursor in *named cursors*. A
named cursor is created using the 'cursor()' method specifying the
'name' parameter. Such cursor will behave mostly like a regular
cursor, allowing the user to move in the dataset using the
'scroll()' method and to read the data using 'fetchone()' and
'fetchmany()' methods.


Thread safety
=============

The Psycopg module is *thread-safe*: threads can access the same
database using separate sessions (by creating a 'connection' per
thread) or using the same session (accessing to the same connection
and creating separate 'cursor's). In DB API 2.0 parlance, Psycopg is
*level 2 thread safe*.


Using COPY TO and COPY FROM
===========================

Psycopg 'cursor' objects provide an interface to the efficient
PostgreSQL 'COPY' command to move data from files to tables and
back. The methods exposed are:

'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.

'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.

'copy_expert()'
   Allows to handle more specific cases and to use all the 'COPY'
   features available in PostgreSQL.

Please refer to the documentation of the single methods for details
and examples.


Access to PostgreSQL large objects
==================================

PostgreSQL offers support to large objects, which provide stream-style
access to user data that is stored in a special large-object
structure. They are useful with data values too large to be
manipulated conveniently as a whole.

Psycopg allows access to the large object using the 'lobject' class.
Objects are generated using the 'connection.lobject()' factory
method.

Psycopg large object support efficient import/export with file system
files using the 'lo_import()' and 'lo_export()' libpq functions.



The 'psycopg2' module content
*******************************

The module interface respects the standard defined in the DB API 2.0.

psycopg2.connect(dsn or params[, connection_factory])

   Create a new database session and return a new 'connection'
   object.

   You can specify the connection parameters either as a string:

      conn = psycopg2.connect("dbname=test user=postgres password=secret")

   or using a set of keyword arguments:

      conn = psycopg2.connect(database="test", user="postgres", password="secret")

   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

   Using the 'connection_factory' parameter a different class or
   connections factory can be specified. It should be a callable
   object taking a 'dsn' argument. See *Connection and cursor
   factories* for details.

   DB API extension: The 'connection_factory' parameter is a Psycopg
   extension to the DB API 2.0.

psycopg2.apilevel

   String constant stating the supported DB API level.  For
   'psycopg2' is '2.0'.

psycopg2.threadsafety

   Integer constant stating the level of thread safety the interface
   supports.  For 'psycopg2' is '2', i.e. threads can share the
   module and the connection. See *Thread safety* for details.

psycopg2.paramstyle

   String constant stating the type of parameter marker formatting
   expected by the interface.  For 'psycopg2' is 'pyformat'.  See
   also *Passing parameters to SQL queries*.


Exceptions
==========

In compliance with the DB API 2.0, the module makes informations about
errors available through the following exceptions:

exception exception psycopg2.Warning

   Exception raised for important warnings like data truncations while
   inserting, etc. It is a subclass of the Python 'StandardError'.

exception exception psycopg2.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 not use this
   class as base. It is a subclass of the Python 'StandardError'.

   pgerror

      String representing the error message returned by the backend,
      'None' if not available.

   pgcode

      String representing the error code returned by the backend,
      'None' if not available.  The 'errorcodes' module contains
      symbolic constants representing PostgreSQL error codes.

   DB API extension: The 'pgerror' and 'pgcode' attributes are
   Psycopg extensions.

      >>> try:
      ...     cur.execute("SELECT * FROM barf")
      ... except Exception, e:
      ...     pass

      >>> e.pgcode
      '42P01'
      >>> print e.pgerror
      ERROR:  relation "barf" does not exist
      LINE 1: SELECT * FROM barf
                            ^

   Changed in version 2.0.7: added 'Error.pgerror' and
   'Error.pgcode' attributes.

exception exception psycopg2.InterfaceError

   Exception raised for errors that are related to the database
   interface rather than the database itself.  It is a subclass of
   'Error'.

exception exception psycopg2.DatabaseError

   Exception raised for errors that are related to the database.  It
   is a subclass of 'Error'.

exception exception psycopg2.DataError

   Exception raised for errors that are due to problems with the
   processed data like division by zero, numeric value out of range,
   etc. It is a subclass of 'DatabaseError'.

exception exception psycopg2.OperationalError

   Exception raised for errors that are related to the database's
   operation and not necessarily under the control of the programmer,
   e.g. an unexpected disconnect occurs, the data source name is not
   found, a transaction could not be processed, a memory allocation
   error occurred during processing, etc.  It is a subclass of
   'DatabaseError'.

exception exception psycopg2.IntegrityError

   Exception raised when the relational integrity of the database is
   affected, e.g. a foreign key check fails.  It is a subclass of
   'DatabaseError'.

exception exception psycopg2.InternalError

   Exception raised when the database encounters an internal error,
   e.g. the cursor is not valid anymore, the transaction is out of
   sync, etc.  It is a subclass of 'DatabaseError'.

exception exception psycopg2.ProgrammingError

   Exception raised for programming errors, e.g. table not found or
   already exists, syntax error in the SQL statement, wrong number of
   parameters specified, etc.  It is a subclass of 'DatabaseError'.

exception exception psycopg2.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 'DatabaseError'.

DB API extension: Psycopg may raise a few other, more specialized,
exceptions: currently 'QueryCanceledError' and
'TransactionRollbackError' are defined. These exceptions are not
exposed by the main 'psycopg2' module but are made available by the
'extensions' module.  All the additional exceptions are subclasses
of standard DB API 2.0 exceptions, so trapping them specifically is
not required.

This is the exception inheritance layout:

   'StandardError'
   |__ 'Warning'
   |__ 'Error'
       |__ 'InterfaceError'
       |__ 'DatabaseError'
           |__ 'DataError'
           |__ 'OperationalError'
           |   |__ 'psycopg2.extensions.QueryCanceledError'
           |   |__ 'psycopg2.extensions.TransactionRollbackError'
           |__ 'IntegrityError'
           |__ 'InternalError'
           |__ 'ProgrammingError'
           |__ 'NotSupportedError'


Type Objects and Constructors
=============================

Note: This section is mostly copied verbatim from the DB API 2.0
  specification.  While these objects are exposed in compliance to the
  DB API, Psycopg offers very accurate tools to convert data between
  Python and PostgreSQL formats.  See *Adapting new Python types to
  SQL syntax* and *Type casting of SQL types into Python objects*

Many databases need to have the input in a particular format for
binding to an operation's input parameters.  For example, if an input
is destined for a DATE column, then it must be bound to the database
in a particular string format.  Similar problems exist for "Row ID"
columns or large binary items (e.g. blobs or RAW columns).  This
presents problems for Python since the parameters to the .execute*()
method are untyped.  When the database module sees a Python string
object, it doesn't know if it should be bound as a simple CHAR column,
as a raw BINARY item, or as a DATE.

To overcome this problem, a module must provide the constructors
defined below to create objects that can hold special values. When
passed to the cursor methods, the module can then detect the proper
type of the input parameter and bind it accordingly.

A Cursor Object's description attribute returns information about each
of the result columns of a query.  The type_code must compare equal to
one of Type Objects defined below. Type Objects may be equal to more
than one type code (e.g. DATETIME could be equal to the type codes for
date, time and timestamp columns; see the Implementation Hints below
for details).

The module exports the following constructors and singletons:

psycopg2.Date(year, month, day)

   This function constructs an object holding a date value.

psycopg2.Time(hour, minute, second)

   This function constructs an object holding a time value.

psycopg2.Timestamp(year, month, day, hour, minute, second)

   This function constructs an object holding a time stamp value.

psycopg2.DateFromTicks(ticks)

   This function constructs an object holding a date value from the
   given ticks value (number of seconds since the epoch; see the
   documentation of the standard Python time module for details).

psycopg2.TimeFromTicks(ticks)

   This function constructs an object holding a time value from the
   given ticks value (number of seconds since the epoch; see the
   documentation of the standard Python time module for details).

psycopg2.TimestampFromTicks(ticks)

   This function constructs an object holding a time stamp value from
   the given ticks value (number of seconds since the epoch; see the
   documentation of the standard Python time module for details).

psycopg2.Binary(string)

   This function constructs an object capable of holding a binary
   (long) string value.

psycopg2.STRING

   This type object is used to describe columns in a database that are
   string-based (e.g. CHAR).

psycopg2.BINARY

   This type object is used to describe (long) binary columns in a
   database (e.g. LONG, RAW, BLOBs).

psycopg2.NUMBER

   This type object is used to describe numeric columns in a database.

psycopg2.DATETIME

   This type object is used to describe date/time columns in a
   database.

psycopg2.ROWID

   This type object is used to describe the "Row ID" column in a
   database.



The 'connection' class
************************

class class connection

   Handles the connection to a PostgreSQL database instance. It
   encapsulates a database session.

   Connections are created using the factory function 'connect()'.

   Connections are thread safe and can be shared among many thread.
   See *Thread safety* for details.

   cursor([name][, cursor_factory])

      Return a new 'cursor' object using the connection.

      If 'name' is specified, the returned cursor will be a *server
      side* (or *named*) cursor. Otherwise the cursor will be *client
      side*. See *Server side cursors* for further details.

      The 'cursor_factory' argument can be used to create non-
      standard cursors. The class returned should be a subclass of
      'psycopg2.extensions.cursor'. See *Connection and cursor
      factories* for details.

      DB API extension: The 'name' and 'cursor_factory' parameters
      are Psycopg extensions to the DB API 2.0.

   commit()

      Commit any pending transaction to the database. Psycopg can be
      set to perform automatic commits at each operation, see
      'set_isolation_level()'.

   rollback()

      Roll back to the start of any pending transaction.  Closing a
      connection without committing the changes first will cause an
      implicit rollback to be performed.

   close()

      Close the connection now (rather than whenever '__del__()' is
      called).  The connection will be unusable from this point
      forward; an '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 'set_isolation_level()').

   -[ Excetptions as connection class attributes ]-

   The 'connection' also exposes as attributes the same exceptions
   available in the 'psycopg2' module.  See *Exceptions*.

   DB API extension: The above methods are the only ones defined by
   the DB API 2.0 protocol. The Psycopg connection objects exports the
   following additional methods and attributes.

   closed

      Read-only attribute reporting whether the database connection is
      open (0) or closed (1).

   reset()

      Reset the connection to the default.

      The method rolls back an eventual pending transaction and
      executes the PostgreSQL 'RESET' and 'SET SESSION
      AUTHORIZATION' to revert the session to the default values.

      New in version 2.0.12.

   dsn

      Read-only string containing the connection string used by the
      connection.

   isolation_level

   set_isolation_level(level)

      Read or set the transaction isolation level for the current
      session. The level defines the different phenomena that can
      happen in the database between concurrent transactions.

      The value set or read is an integer: symbolic constants are
      defined in the module 'psycopg2.extensions': see *Isolation
      level constants* for the available values.

      The default level is 'READ COMMITTED': at this level a
      transaction is automatically started the first time a database
      command is executed.  If you want an *autocommit* mode, switch
      to 'ISOLATION_LEVEL_AUTOCOMMIT' before executing any command:

         >>> conn.set_isolation_level(psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT)

      See also *Transactions control*.

   encoding

   set_client_encoding(enc)

      Read or set the client encoding for the current session. The
      default is the encoding defined by the database. It should be
      one of the characters set supported by PostgreSQL

   notices

      A list containing all the database messages sent to the client
      during the session.

         >>> cur.execute("CREATE TABLE foo (id serial PRIMARY KEY);")
         >>> pprint(conn.notices)
         ['NOTICE:  CREATE TABLE / PRIMARY KEY will create implicit index "foo_pkey" for table "foo"\n',
          'NOTICE:  CREATE TABLE will create implicit sequence "foo_id_seq" for serial column "foo.id"\n']

      To avoid a leak in case excessive notices are generated, only
      the last 50 messages are kept.

      You can configure what messages to receive using PostgreSQL
      logging configuration parameters such as 'log_statement',
      'client_min_messages', 'log_min_duration_statement' etc.

   notifies

      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.

      For other details see *Asynchronous notifications*.

   get_backend_pid()

      Returns the process ID (PID) of the backend server process
      handling this connection.

      Note that the PID belongs to a process executing on the database
      server host, not the local host!

      See also:

         libpq docs for PQbackendPID() for details.

      New in version 2.0.8.

   get_parameter_status(parameter)

      Look up a current parameter setting of the server.

      Potential values for 'parameter' are: 'server_version',
      'server_encoding', 'client_encoding', 'is_superuser',
      'session_authorization', 'DateStyle', 'TimeZone',
      'integer_datetimes', and 'standard_conforming_strings'.

      If server did not report requested parameter, return 'None'.

      See also:

         libpq docs for PQparameterStatus() for details.

      New in version 2.0.12.

   get_transaction_status()

      Return the current session transaction status as an integer.
      Symbolic constants for the values are defined in the module
      'psycopg2.extensions': see *Transaction status constants* for
      the available values.

      See also:

         libpq docs for PQtransactionStatus() for details.

   protocol_version

      A read-only integer representing frontend/backend protocol being
      used. It can be 2 or 3.

      See also:

         libpq docs for PQprotocolVersion() for details.

      New in version 2.0.12.

   server_version

      A read-only integer representing the backend version.

      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'.

      See also:

         libpq docs for PQserverVersion() for details.

      New in version 2.0.12.

   status

      A read-only integer representing the status of the connection.
      Symbolic constants for the values are defined in the module
      'psycopg2.extensions': see *Connection status constants* for
      the available values.

   lobject([oid[, mode[, new_oid[, new_file[, lobject_factory]]]]])

      Return a new database large object. See *Access to PostgreSQL
      large objects* for an overview.

      Parameters:
         * *oid* -- The OID of the object to read or write. 0 to
           create a new large object and and have its OID assigned
           automatically.

         * *mode* -- Access mode to the object: can be 'r', 'w',
           'rw' or 'n' (meaning don't open it).

         * *new_oid* -- Create a new object using the specified OID.
           The function raises 'OperationalError' if the OID is
           already in use. Default is 0, meaning assign a new one
           automatically.

         * *new_file* -- The name of a file to be imported in the the
           database (using the 'lo_import()' function)

         * *lobject_factory* -- Subclass of 'lobject' to be
           instantiated.

      Return type:
         'lobject'

      New in version 2.0.8.



The 'cursor' class
********************

class class cursor

   Allows Python code to execute PostgreSQL command in a database
   session. Cursors are created by the '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
   connections' *isolation level*. See also 'rollback()' and
   'commit()' methods.

   Cursors are *not* thread safe: a multithread application can create
   many cursors from the same connection and should use each cursor
   from a single thread. See *Thread safety* for details.

   description

      This read-only attribute is a sequence of 7-item sequences.

      Each of these sequences contains information describing one
      result column:

      * 'name'

      * 'type_code'

      * 'display_size'

      * 'internal_size'

      * 'precision'

      * 'scale'

      * 'null_ok'

      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 *Type Objects and
      Constructors*. It is also used to register typecasters to
      convert PostgreSQL types to Python objects: see *Type casting of
      SQL types into Python objects*.

   close()

      Close the cursor now (rather than whenever '__del__()' is
      called).  The cursor will be unusable from this point forward;
      an 'InterfaceError' will be raised if any operation is
      attempted with the cursor.

   closed

      Read-only boolean attribute: specifies if the cursor is closed
      ('True') or not ('False').

      DB API extension: The 'closed' attribute is a Psycopg
      extension to the DB API 2.0.

      New in version 2.0.7.

   connection

      Read-only attribute returning a reference to the 'connection'
      object on which the cursor was created.

   name

      Read-only attribute containing the name of the cursor if it was
      creates as named cursor by 'connection.cursor()', or 'None'
      if it is a client side cursor.  See *Server side cursors*.

      DB API extension: The 'name' attribute is a Psycopg extension
      to the DB API 2.0.

   -[ Commands execution methods ]-

   execute(operation[, parameters][, async])

      Prepare and execute a database operation (query or command).

      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 *Passing parameters to SQL queries*.

      The method returns 'None'. If a query was executed, the
      returned values can be retrieved using 'fetch*()' methods.

      If 'async' is 'True', query execution will be asynchronous:
      the function returns immediately while the query is executed by
      the backend.  Use the 'isready()' method to see if the data is
      ready for return via 'fetch*()' methods. See *Asynchronous
      queries*.

      DB API extension: The 'async' parameter is a Psycopg extension
      to the DB API 2.0.

   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 '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')"

      DB API extension: The 'mogrify()' method is a Psycopg
      extension to the DB API 2.0.

   executemany(operation, seq_of_parameters)

      Prepare a database operation (query or command) and then execute
      it against all parameter tuples or mappings found in the
      sequence '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 'execute()' method.

   callproc(procname[, parameters][, async])

      Call a stored database procedure with the given name. The
      sequence of parameters must contain one entry for each argument
      that the procedure expects. The result of the call is returned
      as modified copy of the input sequence. Input parameters are
      left untouched, output and input/output parameters replaced with
      possibly new values.

      The procedure may also provide a result set as output. This must
      then be made available through the standard 'fetch*()'
      methods.

      If 'async' is 'True', procedure execution will be
      asynchronous: the function returns immediately while the
      procedure is executed by the backend.  Use the 'isready()'
      method to see if the data is ready for return via 'fetch*()'
      methods. See *Asynchronous queries*.

      DB API extension: The 'async' parameter is a Psycopg extension
      to the DB API 2.0.

   setinputsizes(sizes)

      This method is exposed in compliance with the DB API 2.0. It
      currently does nothing but it is safe to call it.

   -[ Results retrieval methods ]-

   The following methods are used to read data from the database after
   an 'execute()' call.

   Note: 'cursor' objects are iterable, so, instead of calling
     explicitly 'fetchone()' in a loop, the object itself can be
     used:

     >>> cur.execute("SELECT * FROM test;")
     >>> for record in cur:
     ...     print record
     ...
     (1, 100, "abc'def")
     (2, None, 'dada')
     (3, 42, 'bar')

   fetchone()

      Fetch the next row of a query result set, returning a single
      tuple, or 'None' when no more data is available:

      >>> cur.execute("SELECT * FROM test WHERE id = %s", (3,))
      >>> cur.fetchone()
      (3, 42, 'bar')

      A 'ProgrammingError' is raised if the previous call to
      'execute*()' did not produce any result set or no call was
      issued yet.

   fetchmany([size=cursor.arraysize])

      Fetch the next set of rows of a query result, returning a list
      of 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 '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)
      [(1, 100, "abc'def"), (2, None, 'dada')]
      >>> cur.fetchmany(2)
      [(3, 42, 'bar')]
      >>> cur.fetchmany(2)
      []

      A '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 'arraysize' attribute.  If the size parameter is used,
      then it is best for it to retain the same value from one
      'fetchmany()' call to the next.

   fetchall()

      Fetch all (remaining) rows of a query result, returning them as
      a list 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'), (3, 42, 'bar')]

      A 'ProgrammingError' is raised if the previous call to
      'execute*()' did not produce any result set or no call was
      issued yet.

   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 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
      'ProgrammingError' is raised and the cursor position is not
      changed.

      The method can be used both for client-side cursors and *server-
      side cursors*.

      Note: According to the DB API 2.0, the exception raised for a cursor
        out of bound should have been 'IndexError'.  The best option
        is probably to catch both exceptions in your code:

           try:
               cur.scroll(1000 * 1000)
           except (ProgrammingError, IndexError), exc:
               deal_with_it(exc)

   arraysize

      This read/write attribute specifies the number of rows to fetch
      at a time with 'fetchmany()'. It defaults to 1 meaning to
      fetch a single row at a time.

   rowcount

      This read-only attribute specifies the number of rows that the
      last 'execute*()' produced (for DQL (Data Query Language)
      statements like 'SELECT') or affected (for DML (Data
      Manipulation Language) statements like 'UPDATE' or
      '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 determined by the interface.

      Note: The DB API 2.0 interface reserves to redefine the latter case
        to have the object return 'None' instead of -1 in future
        versions of the specification.

   rownumber

      This read-only attribute provides the current 0-based index of
      the cursor in the result set or 'None' if the index cannot be
      determined.

      The index can be seen as index of the cursor in a sequence (the
      result set). The next fetch operation will fetch the row indexed
      by 'rownumber' in that sequence.

   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 last operation is not a single record insert, the
      attribute is set to 'None'.

      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.

   nextset()

      This method is not supported (PostgreSQL does not have multiple
      data sets) and will raise a 'NotSupportedError' exception.

   setoutputsize(size[, column])

      This method is exposed in compliance with the DB API 2.0. It
      currently does nothing but it is safe to call it.

   query

      Read-only attribute containing the body of the last query sent
      to the backend (including bound arguments). 'None' if no query
      has been executed yet:

      >>> cur.execute("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
      >>> cur.query
      "INSERT INTO test (num, data) VALUES (42, E'bar')"

      DB API extension: The 'query' attribute is a Psycopg extension
      to the DB API 2.0.

   statusmessage

      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
      'INSERT 0 1'

      DB API extension: The 'statusmessage' attribute is a Psycopg
      extension to the DB API 2.0.

   isready()

      Return 'False' if the backend is still processing an
      asynchronous query or 'True' if data is ready to be fetched by
      one of the 'fetch*()' methods.  See *Asynchronous queries*.

      DB API extension: The 'isready()' method is a Psycopg
      extension to the DB API 2.0.

   fileno()

      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 'select()' call).
      See *Asynchronous queries*.

      DB API extension: The 'fileno()' method is a Psycopg extension
      to the DB API 2.0.

   tzinfo_factory

      The time zone factory used to handle data types such as
      'TIMESTAMP WITH TIME ZONE'.  It should be a 'tzinfo' object.
      See also the 'psycopg2.tz' module.

   -[ COPY-related methods ]-

   DB API extension: The 'COPY' command is a PostgreSQL extension to
   the SQL standard. As such, its support is a Psycopg extension to
   the DB API 2.0.

   copy_from(file, table, sep='\t', null='\N', columns=None)

      Read data *from* the file-like object 'file' appending them to
      the table named 'table'.  'file' must have both 'read()'
      and 'readline()' method.  See *Using COPY TO and COPY FROM*
      for an overview.

      The optional argument 'sep' is the columns separator and
      'null' represents 'NULL' values in the file.

      The '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.

      >>> f = StringIO("42\tfoo\n74\tbar\n")
      >>> cur.copy_from(f, 'test', columns=('num', 'data'))
      >>> cur.execute("select * from test where id > 5;")
      >>> cur.fetchall()
      [(6, 42, 'foo'), (7, 74, 'bar')]

      Changed in version 2.0.6: added the 'columns' parameter.

   copy_to(file, table, sep='\t', null='\N', columns=None)

      Write the content of the table named 'table' *to* the file-
      like object 'file'.  'file' must have a 'write()' method.
      See *Using COPY TO and COPY FROM* for an overview.

      The optional argument 'sep' is the columns separator and
      'null' represents 'NULL' values in the file.

      The '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="|")
      1|100|abc'def
      2|\N|dada
      ...

      Changed in version 2.0.6: added the 'columns' parameter.

   copy_expert(sql, file[, size])

      Submit a user-composed 'COPY' statement. The method is useful
      to handle all the parameters that PostgreSQL makes available
      (see 'COPY' command documentation).

      'file' must be an open, readable file for 'COPY FROM' or an
      open, writeable file for 'COPY TO'. The optional 'size'
      argument, when specified for a 'COPY FROM' statement, will be
      passed to '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
      ...

      New in version 2.0.6.



More advanced topics
********************


Connection and cursor factories
===============================

Psycopg exposes two new-style classes that can be sub-classed and
expanded to adapt them to the needs of the programmer:
'psycopg2.extensions.cursor' and 'psycopg2.extensions.connection'.
The 'connection' class is usually sub-classed only to provide an
easy way to create customized cursors but other uses are possible.
'cursor' is much more interesting, because it is the class where
query building, execution and result type-casting into Python
variables happens.

An example of cursor subclass performing logging is:

   import psycopg2
   import psycopg2.extensions
   import logging

   class LoggingCursor(psycopg2.extensions.cursor):
       def execute(self, sql, args=None):
           logger = logging.getLogger('sql_debug')
           logger.info(self.mogrify(sql, args))

           try:
               psycopg2.extensions.cursor.execute(self, sql, args)
           except Exception, exc:
               logger.error("%s: %s" % (exc.__class__.__name__, exc))
               raise

   conn = psycopg2.connect(DSN)
   cur = conn.cursor(cursor_factory=LoggingCursor)
   cur.execute("INSERT INTO mytable VALUES (%s, %s, %s);",
                (10, 20, 30))


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 'psycopg2.extensions.adapt()' function.

The 'execute()' method adapts its arguments to the 'ISQLQuote'
protocol.  Objects that conform to this protocol expose a
'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 '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 'AsIs' wrapper, whose
'getquoted()' result is simply the 'str()'ing conversion of the
wrapped object.

Example: mapping of a 'Point' class into the 'point' PostgreSQL
geometric type:

   >>> from psycopg2.extensions import adapt, register_adapter, AsIs

   >>> class Point(object):
   ...    def __init__(self, x, y):
   ...        self.x = x
   ...        self.y = y

   >>> def adapt_point(point):
   ...     return AsIs("'(%s, %s)'" % (adapt(point.x), adapt(point.y)))

   >>> register_adapter(Point, adapt_point)

   >>> cur.execute("INSERT INTO atable (apoint) VALUES (%s)",
   ...             (Point(1.23, 4.56),))

The above function call results in the SQL command:

   INSERT INTO atable (apoint) VALUES ((1.23, 4.56));


Type casting of SQL types into Python objects
=============================================

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 the PostgreSQL 'point' representation into the previously
defined 'Point' class:

>>> def cast_point(value, cur):
...    if value is None:
...        return 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)))
...    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 'cursor.description':

>>> cur.execute("SELECT NULL::point")
>>> point_oid = cur.description[0][1]
>>> point_oid
600

or by querying the system catalog for the type name and namespace (the
namespace for system objects is 'pg_catalog'):

>>> cur.execute("""
...    SELECT pg_type.oid
...      FROM pg_type JOIN pg_namespace
...             ON typnamespace = pg_namespace.oid
...     WHERE typname = %(typename)s
...       AND nspname = %(namespace)s""",
...    {'typename': 'point', 'namespace': 'pg_catalog'})
>>> point_oid = cur.fetchone()[0]
>>> point_oid
600

After you know the object OID, you can create and register the new
type:

>>> POINT = psycopg2.extensions.new_type((point_oid,), "POINT", cast_point)
>>> psycopg2.extensions.register_type(POINT)

The 'new_type()' function binds the object OIDs (more than one can
be specified) to the adapter function. 'register_type()' completes
the spell.  Conversion is automatically performed when a column whose
type is a registered OID is read:

>>> cur.execute("SELECT '(10.2,20.3)'::point")
>>> point = cur.fetchone()[0]
>>> print type(point), point.x, point.y
<class 'Point'> 10.2 20.3


Asynchronous notifications
==========================

Psycopg allows asynchronous interaction with other database sessions
using the facilities offered by PostgreSQL commands 'LISTEN' and
'NOTIFY'. Please refer to the PostgreSQL documentation for examples
of how to use this form of communications.

Notifications received are made available in the
'connection.notifies' list. Notifications can be sent from Python
code simply using a 'NOTIFY' command in an '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.

Example:

   import sys
   import select
   import psycopg2
   import psycopg2.extensions

   conn = psycopg2.connect(DSN)
   conn.set_isolation_level(psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT)

   curs = conn.cursor()
   curs.execute("LISTEN test;")

   print "Waiting for 'NOTIFY test'"
   while 1:
       if select.select([curs],[],[],5)==([],[],[]):
           print "Timeout"
       else:
           if curs.isready():
               print "Got NOTIFY:", curs.connection.notifies.pop()

Running the script and executing the command 'NOTIFY test' in a
separate **psql** shell, the output may look similar to:

   Waiting for 'NOTIFY test'
   Timeout
   Timeout
   Got NOTIFY: (6535, 'test')
   Timeout
   ...


Asynchronous queries
====================

Warning: Psycopg support for asynchronous queries is still experimental and
  the informations reported here may be out of date.Discussion,
  testing and suggestions are welcome.

Program code can initiate an asynchronous query by passing an
'async=1' flag to the 'execute()' or 'callproc()' cursor
methods. A very simple example, from the connection to the query:

   conn = psycopg2.connect(database='test')
   curs = conn.cursor()
   curs.execute("SELECT * from test WHERE fielda > %s", (1971,), async=1)

From then on any query on other cursors derived from the same
connection is 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 'fetch*()' methods is called, effectively blocking
   until data has been sent from the backend to the client,
   terminating the query.

2. 'connection.cancel()' is called. This method tries to abort the
   current query and will block until the query is aborted or fully
   executed. 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. 'execute()' is called again on the same cursor ('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 '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:

'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 'select()' call).

'isready()'
   Returns 'False' if the backend is still processing the query or
   'True' if data is ready to be fetched (by one of the 'fetch*()'
   methods).

A code snippet that shows how to use the cursor object in a
'select()' call:

   import psycopg2
   import select

   conn = psycopg2.connect(database='test')
   curs = conn.cursor()
   curs.execute("SELECT * from test WHERE fielda > %s", (1971,), async=1)

   # wait for input with a maximum timeout of 5 seconds
   query_ended = False
   while not query_ended:
       rread, rwrite, rspec = select([curs, another_file], [], [], 5)

   if curs.isready():
      query_ended = True

   # manage input from other sources like other_file, etc.

   print "Query Results:"
   for row in curs:
       print row



'psycopg2.extensions' -- Extensions to the DB API
***************************************************

The module contains a few objects and function extending the minimum
set of functionalities defined by the DB API 2.0.

class class psycopg2.extensions.connection

   Is the class usually returned by the 'connect()' function. It is
   exposed by the 'extensions' module in order to allow subclassing
   to extend its behaviour: the subclass should be passed to the
   'connect()' function using the 'connection_factory' parameter.
   See also *Connection and cursor factories*.

   For a complete description of the class, see 'connection'.

class class psycopg2.extensions.cursor

   It is the class usually returnded by the 'connection.cursor()'
   method. It is exposed by the 'extensions' module in order to
   allow subclassing to extend its behaviour: the subclass should be
   passed to the 'cursor()' method using the 'cursor_factory'
   parameter. See also *Connection and cursor factories*.

   For a complete description of the class, see 'cursor'.

class class psycopg2.extensions.lobject(conn[, oid[, mode[, new_oid[, new_file]]]])

   Wrapper for a PostgreSQL large object. See *Access to PostgreSQL
   large objects* for an overview.

   The class can be subclassed: see the 'connection.lobject()' to
   know how to specify a 'lobject' subclass.

   New in version 2.0.8.

   oid

      Database OID of the object.

   mode

      The mode the database was open ('r', 'w', 'rw' or 'n').

   read(bytes=-1)

      Read a chunk of data from the current file position. If -1
      (default) read all the remaining data.

   write(str)

      Write a string to the large object. Return the number of bytes
      written.

   export(file_name)

      Export the large object content to the file system.

      The method uses the efficient 'lo_export()' libpq function.

   seek(offset, whence=0)

      Set the lobject current position.

   tell()

      Return the lobject current position.

   close()

      Close the object.

   closed

      Boolean attribute specifying if the object is closed.

   unlink()

      Close the object and remove it from the database.


SQL adaptation protocol objects
===============================

Psycopg provides a flexible system to adapt Python objects to the SQL
syntax (inspired to the **PEP 246**), allowing serialization in
PostgreSQL. See *Adapting new Python types to SQL syntax* for a
detailed description.  The following objects deal with Python objects
adaptation:

psycopg2.extensions.adapt(obj)

   Return the SQL representation of *obj* as a string.  Raise a
   '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 '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 'adapt()' on its components.

psycopg2.extensions.register_adapter(class, adapter)

   Register a new adapter for the objects of class *class*.

   *adapter* should be a function taking a single argument (the object
   to adapt) and returning an object conforming the 'ISQLQuote'
   protocol (e.g. exposing a 'getquoted()' method).  The 'AsIs' is
   often useful for this task.

   Once an object is registered, it can be safely used in SQL queries
   and by the 'adapt()' function.

class class psycopg2.extensions.ISQLQuote(wrapped_object)

   Represents the SQL adaptation protocol.  Objects conforming this
   protocol should implement a 'getquoted()' method.

   Adapters may subclass 'ISQLQuote', but is not necessary: it is
   enough to expose a 'getquoted()' method to be conforming.

   _wrapped

      The wrapped object passes to the constructor

   getquoted()

      Subclasses or other conforming objects should return a valid SQL
      string representing the wrapped object. The 'ISQLQuote'
      implementation does nothing.

class class psycopg2.extensions.AsIs

   Adapter conform to the 'ISQLQuote' protocol useful for objects
   whose string representation is already valid as SQL representation.

   getquoted()

      Return the 'str()' conversion of the wrapped object.

      >>> AsIs(42).getquoted()
      '42'

class class psycopg2.extensions.QuotedString

   Adapter conform to the 'ISQLQuote' protocol for string-like
   objects.

   getquoted()

      Return the string enclosed in single quotes.  Any single quote
      appearing in the the string is escaped by doubling it according
      to SQL string constants syntax.  Backslashes are escaped too.

      >>> QuotedString(r"O'Reilly").getquoted()
      "'O''Reilly'"

class class psycopg2.extensions.Binary

   Adapter conform to the 'ISQLQuote' protocol for binary objects.

   getquoted()

      Return the string enclosed in single quotes.  It performs the
      same escaping of the 'QuotedString' adapter, plus it knows how
      to escape non-printable chars.

      >>> Binary("\x00\x08\x0F").getquoted()
      "'\\\\000\\\\010\\\\017'"

   Changed in version 2.0.14: previously the adapter was not exposed
   by the 'extensions' module. In older version it can be imported
   from the implementation module 'psycopg2._psycopg'.

class class psycopg2.extensions.Boolean
class class psycopg2.extensions.Float
class class psycopg2.extensions.SQL_IN

   Specialized adapters for builtin objects.

class class psycopg2.extensions.DateFromPy
class class psycopg2.extensions.TimeFromPy
class class psycopg2.extensions.TimestampFromPy
class class psycopg2.extensions.IntervalFromPy

   Specialized adapters for Python datetime objects.

class class psycopg2.extensions.DateFromMx
class class psycopg2.extensions.TimeFromMx
class class psycopg2.extensions.TimestampFromMx
class class psycopg2.extensions.IntervalFromMx

   Specialized adapters for mx.DateTime objects.

psycopg2.extensions.adapters

   Dictionary of the currently registered object adapters.  Use
   'register_adapter()' to add an adapter for a new type.


Database types casting functions
================================

These functions are used to manipulate type casters to convert from
PostgreSQL types to Python objects.  See *Type casting of SQL types
into Python objects* for details.

psycopg2.extensions.new_type(oids, name, adapter)

   Create a new type caster to convert from a PostgreSQL type to a
   Python object.  The created object must be registered using
   'register_type()' to be used.

   Parameters:
      * *oids* -- tuple of OIDs of the PostgreSQL type to convert.

      * *name* -- the name of the new type adapter.

      * *adapter* -- the adaptation function.

   The object OID can be read from the 'cursor.description'
   attribute or by querying from the PostgreSQL catalog.

   *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* will be 'None'. The adapter should return the converted
   object.

   See *Type casting of SQL types into Python objects* for an usage
   example.

psycopg2.extensions.register_type(obj[, scope])

   Register a type caster created using 'new_type()'.

   If *scope* is specified, it should be a 'connection' or a
   'cursor': the type caster will be effective only limited to the
   specified object.  Otherwise it will be globally registered.

psycopg2.extensions.string_types

   The global register of type casters.

psycopg2.extensions.encodings

   Mapping from PostgreSQL encoding names to Python codec names. Used
   by Psycopg when adapting or casting unicode strings. See *Unicode
   handling*.


Additional exceptions
=====================

The module exports a few exceptions in addition to the *standard ones*
defined by the DB API 2.0.

exception exception psycopg2.extensions.QueryCanceledError

   (subclasses 'OperationalError')

   Error related to SQL query cancelation.  It can be trapped
   specifically to detect a timeout.

   New in version 2.0.7.

exception exception psycopg2.extensions.TransactionRollbackError

   (subclasses 'OperationalError')

   Error causing transaction rollback (deadlocks, serialisation
   failures, etc).  It can be trapped specifically to detect a
   deadlock.

   New in version 2.0.7.


Isolation level constants
=========================

Psycopg2 'connection' objects hold informations about the PostgreSQL
transaction isolation level.  The current transaction level can be
read from the 'isolation_level' attribute.  The default isolation
level is 'READ COMMITTED'.  A different isolation level con be set
through the 'set_isolation_level()' method.  The level can be set to
one of the following constants:

psycopg2.extensions.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' or 'VACUUM' can't run into a
   transaction: to run such command use:

      >>> conn.set_isolation_level(ISOLATION_LEVEL_AUTOCOMMIT)

   See also *Transactions control*.

psycopg2.extensions.ISOLATION_LEVEL_READ_UNCOMMITTED

   The 'READ UNCOMMITTED' isolation level is defined in the SQL
   standard but not available in the MVCC (Multiversion concurrency
   control) model of PostgreSQL: it is replaced by the stricter 'READ
   COMMITTED'.

psycopg2.extensions.ISOLATION_LEVEL_READ_COMMITTED

   This is the default value.  A new transaction is started at the
   first 'execute()' command on a cursor and at each new
   'execute()' after a 'commit()' or a 'rollback()'.  The
   transaction runs in the PostgreSQL 'READ COMMITTED' isolation
   level.

psycopg2.extensions.ISOLATION_LEVEL_REPEATABLE_READ

   The 'REPEATABLE READ' isolation level is defined in the SQL
   standard but not available in the MVCC (Multiversion concurrency
   control) model of PostgreSQL: it is replaced by the stricter
   'SERIALIZABLE'.

psycopg2.extensions.ISOLATION_LEVEL_SERIALIZABLE

   Transactions are run at a '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 to serialization failures. See serializable
   isolation level in PostgreSQL documentation.


Transaction status constants
============================

These values represent the possible status of a transaction: the
current value can be read using the
'connection.get_transaction_status()' method.

psycopg2.extensions.TRANSACTION_STATUS_IDLE

   The session is idle and there is no current transaction.

psycopg2.extensions.TRANSACTION_STATUS_ACTIVE

   A command is currently in progress.

psycopg2.extensions.TRANSACTION_STATUS_INTRANS

   The session is idle in a valid transaction block.

psycopg2.extensions.TRANSACTION_STATUS_INERROR

   The session is idle in a failed transaction block.

psycopg2.extensions.TRANSACTION_STATUS_UNKNOWN

   Reported if the connection with the server is bad.


Connection status constants
===========================

These values represent the possible status of a connection: the
current value can be read from the 'status' attribute.

psycopg2.extensions.STATUS_SETUP

   Used internally.

psycopg2.extensions.STATUS_READY

   Connection established.

psycopg2.extensions.STATUS_BEGIN

   Connection established. A transaction is in progress.

psycopg2.extensions.STATUS_IN_TRANSACTION

   An alias for 'STATUS_BEGIN'

psycopg2.extensions.STATUS_SYNC

   Used internally.

psycopg2.extensions.STATUS_ASYNC

   Used internally.


Additional database types
=========================

The 'extensions' module includes typecasters for many standard
PostgreSQL types.  These objects allow the conversion of returned data
into Python objects.  All the typecasters are automatically
registered, except 'UNICODE' and 'UNICODEARRAY': you can register
them using 'register_type()' in order to receive Unicode objects
instead of strings from the database.  See *Unicode handling* for
details.

psycopg2.extensions.BINARYARRAY
psycopg2.extensions.BOOLEAN
psycopg2.extensions.BOOLEANARRAY
psycopg2.extensions.DATE
psycopg2.extensions.DATEARRAY
psycopg2.extensions.DATETIMEARRAY
psycopg2.extensions.DECIMALARRAY
psycopg2.extensions.FLOAT
psycopg2.extensions.FLOATARRAY
psycopg2.extensions.INTEGER
psycopg2.extensions.INTEGERARRAY
psycopg2.extensions.INTERVAL
psycopg2.extensions.INTERVALARRAY
psycopg2.extensions.LONGINTEGER
psycopg2.extensions.LONGINTEGERARRAY
psycopg2.extensions.ROWIDARRAY
psycopg2.extensions.STRINGARRAY
psycopg2.extensions.TIME
psycopg2.extensions.TIMEARRAY
psycopg2.extensions.UNICODE
psycopg2.extensions.UNICODEARRAY



'psycopg2.tz' --  'tzinfo' implementations for Psycopg 2
************************************************************

This module holds two different tzinfo implementations that can be
used as the 'tzinfo' argument to datetime constructors, directly
passed to Psycopg functions or used to set the
'cursor.tzinfo_factory' attribute in cursors.



'psycopg2.pool' -- Connections pooling
****************************************

Creating new PostgreSQL connections can be an expensive operation.
This module offers a few pure Python classes implementing simple
connection pooling directly into the client application.

class class psycopg2.pool.AbstractConnectionPool(minconn, maxconn, *args, **kwargs)

   Base class implementing generic key-based pooling code.

   New *minconn* connections are created automatically. The pool will
   support a maximum of about *maxconn* connections.  **args* and
   ***kwargs* are passed to the 'connect()' function.

   The following methods are expected to be implemented by subclasses:

   getconn(key=None)

      Get a free connection and assign it to *key* if not 'None'.

   putconn(conn, key=None)

      Put away a connection.

   closeall()

      Close all the connections handled by the pool.

      Notice that all the connections are closed, including ones
      eventually in use by the application.

The following classes are 'AbstractConnectionPool' subclasses ready
to be used.



'psycopg2.extras' -- Miscellaneous goodies for Psycopg 2
**********************************************************

This module is a generic place used to hold little helper functions
and classes until a better place in the distribution is found.


Dictionary-like cursor
======================

The dict cursors allow to access to the retrieved records using an
iterface similar to the Python dictionaries instead of the tuples. You
can use it either passing 'DictConnection' as 'connection_factory'
argument to the 'connect()' function or passing 'DictCursor' as
the 'cursor_factory' argument to the 'cursor()' method of a
regular 'connection'.

>>> dict_cur = conn.cursor(cursor_factory=psycopg2.extras.DictCursor)
>>> dict_cur.execute("INSERT INTO test (num, data) VALUES(%s, %s)",
...                  (100, "abc'def"))
>>> dict_cur.execute("SELECT * FROM test")
>>> rec = dict_cur.fetchone()
>>> rec['id']
1
>>> rec['num']
100
>>> rec['data']
"abc'def"

The records still support indexing as the original tuple:

>>> rec[2]
"abc'def"


Real dictionary cursor
----------------------


Logging cursor
==============


UUID data type
==============

New in version 2.0.9.

Changed in version 2.0.13: added UUID array support.

   >>> psycopg2.extras.register_uuid()
   <psycopg2._psycopg.type object at 0x...>

   >>> # Python UUID can be used in SQL queries
   >>> import uuid
   >>> my_uuid = uuid.UUID('{12345678-1234-5678-1234-567812345678}')
   >>> psycopg2.extensions.adapt(my_uuid).getquoted()
   "'12345678-1234-5678-1234-567812345678'::uuid"

   >>> # PostgreSQL UUID are transformed into Python UUID objects.
   >>> cur.execute("SELECT 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11'::uuid")
   >>> cur.fetchone()[0]
   UUID('a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11')


'inet' data type
==================

New in version 2.0.9.

   >>> psycopg2.extras.register_inet()
   <psycopg2._psycopg.type object at 0x...>

   >>> cur.mogrify("SELECT %s", (Inet('127.0.0.1/32'),))
   "SELECT E'127.0.0.1/32'::inet"

   >>> cur.execute("SELECT '192.168.0.1/24'::inet")
   >>> cur.fetchone()[0].addr
   '192.168.0.1/24'


Fractional time zones
=====================



'psycopg2.errorcodes' -- Error codes defined by PostgreSQL
************************************************************

New in version 2.0.6.

This module contains symbolic names for all PostgreSQL error codes and
error classes codes.  Subclasses of 'Error' make the PostgreSQL
error code available in the 'pgcode' attribute.

From PostgreSQL documentation:

   All messages emitted by the PostgreSQL server are assigned five-
   character error codes that follow the SQL standard's conventions
   for 'SQLSTATE' codes.  Applications that need to know which error
   condition has occurred should usually test the error code, rather
   than looking at the textual error message.  The error codes are
   less likely to change across PostgreSQL releases, and also are not
   subject to change due to localization of error messages. Note that
   some, but not all, of the error codes produced by PostgreSQL are
   defined by the SQL standard; some additional error codes for
   conditions not defined by the standard have been invented or
   borrowed from other databases.

   According to the standard, the first two characters of an error
   code denote a class of errors, while the last three characters
   indicate a specific condition within that class. Thus, an
   application that does not recognize the specific error code can
   still be able to infer what to do from the error class.

See also:

   PostgreSQL Error Codes table

An example of the available constants defined in the module:

>>> errorcodes.CLASS_SYNTAX_ERROR_OR_ACCESS_RULE_VIOLATION
'42'
>>> errorcodes.UNDEFINED_TABLE
'42P01'

Constants representing all the error values documented by PostgreSQL
versions between 8.1 and 8.4 are included in the module.



Frequently Asked Questions
**************************

Here are a few gotchas you may encounter using 'psycopg2'.  Feel
free to suggest new entries!

Why does 'psycopg2' leave database sessions "idle in transaction"?
   Psycopg normally starts a new transaction the first time a query is
   executed, e.g. calling 'cursor.execute()', even if the command is
   a 'SELECT'.  The transaction is not closed until an explicit
   'commit()' or 'rollback()'.

   If you are writing a long-living program, you should probably
   ensure to call one of the transaction closing methods before
   leaving the connection unused for a long time (which may also be a
   few seconds, depending on the concurrency level in your database).
   Alternatively you can use a connection in *autocommit* mode to
   avoid a new transaction to be started at the first command.

Why does 'cursor.execute()' raise the exception *can't adapt*?
   Psycopg converts Python objects in a SQL string representation by
   looking at the object class.  The exception is raised when you are
   trying to pass as query parameter an object for which there is no
   adapter registered for its class.  See *Adapting new Python types
   to SQL syntax* for informations.

I can't pass an integer or a float parameter to my query: it says *a
number is required*, but *it is* a number!
   In your query string, you always have to use '%s'  placeholders,
   event when passing a number.  All Python objects are converted by
   Psycopg in their SQL representation, so they get passed to the
   query as strings. See *Passing parameters to SQL queries*.

      >>> cur.execute("INSERT INTO numbers VALUES (%d)", (42,)) # WRONG
      >>> cur.execute("INSERT INTO numbers VALUES (%s)", (42,)) # correct

I try to execute a query but it fails with the error *not all
arguments converted during string formatting* (or *object does not
support indexing*). Why?
   Psycopg always require positional arguments to be passed as a
   tuple, even when the query takes a single parameter.  And remember
   that to make a single item tuple in Python you need a comma!  See
   *Passing parameters to SQL queries*.

      >>> cur.execute("INSERT INTO foo VALUES (%s)", "bar")    # WRONG
      >>> cur.execute("INSERT INTO foo VALUES (%s)", ("bar"))  # WRONG
      >>> cur.execute("INSERT INTO foo VALUES (%s)", ("bar",)) # correct

I receive the error *current transaction is aborted, commands ignored
until end of transaction block* and can't do anything else!
   There was a problem *in the previous* command to the database,
   which resulted in an error.  The database will not recover
   automatically from this condition: you must run a 'rollback()'
   before sending new commands to the session (if this seems too
   harsh, remember that PostgreSQL supports nested transactions using
   the 'SAVEPOINT' command).

Why do i get the error *current transaction is aborted, commands
ignored until end of transaction block* when I use 'multiprocessing'
(or any other forking system) and not when use 'threading'?
   Psycopg's connections can't be shared across processes (but are
   thread safe).  If you are forking the Python process ensure to
   create a new connection in each forked child.

My database is Unicode, but I receive all the strings as UTF-8
'str'. Can I receive 'unicode' objects instead?
   The following magic formula will do the trick:

      psycopg2.extensions.register_type(psycopg2.extensions.UNICODE)
      psycopg2.extensions.register_type(psycopg2.extensions.UNICODEARRAY)

   See *Unicode handling* for the gory details.

I can't compile 'psycopg2': the compiler says *error: Python.h: No
such file or directory*. What am I missing?
   You need to install a Python development package: it is usually
   called 'python-dev'.

I can't compile 'psycopg2': the compiler says *error: libpq-fe.h: No
such file or directory*. What am I missing?
   You need to install the development version of the libpq: the
   package is usually called 'libpq-dev'.

When should I save and re-use a cursor as opposed to creating a new
one as needed?
   Cursors are lightweight objects and creating lots of them should
   not pose any kind of problem. But note that cursors used to fetch
   result sets will cache the data and use memory in proportion to the
   result set size. Our suggestion is to almost always create a new
   cursor and dispose old ones as soon as the data is not required
   anymore (call 'close()' on them.) The only exception are tight
   loops where one usually use the same cursor for a whole bunch of
   'INSERT's or 'UPDATE's.

When should I save and re-use a connection as opposed to creating a
new one as needed?
   Creating a connection can be slow (think of SSL over TCP) so the
   best practice is to create a single connection and keep it open as
   long as required. It is also good practice to rollback or commit
   frequently (even after a single 'SELECT' statement) to make sure
   the backend is never left "idle in transaction".  See also
   'psycopg2.pool' for lightweight connection pooling.

What are the advantages or disadvantages of using named cursors?
   The only disadvantages is that they use up resources on the server
   and that there is a little overhead because a at least two queries
   (one to create the cursor and one to fetch the initial result set)
   are issued to the backend. The advantage is that data is fetched
   one chunk at a time: using small 'fetchmany()' values it is
   possible to use very little memory on the client and to skip or
   discard parts of the result set.


