Merge remote branch 'remotes/piro/python2' into python2

doc/src/_static/psycopg.css

@@ -23,3 +23,6 @@ a > tt.sql:hover {
     text-decoration: underline;
 }
 
+dl.faq dt {
+    font-weight: bold;
+}

doc/src/connection.rst

@@ -25,18 +25,18 @@ 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 `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 :obj:`!cursor_factory` argument can be used to create non-standard
+        The `cursor_factory` argument can be used to create non-standard
         cursors. The class returned should be a subclass of
         :class:`psycopg2.extensions.cursor`. See :ref:`subclassing-cursor` for
         details.
 
         .. extension::
 
-            The :obj:`!name` and :obj:`!cursor_factory` parameters are Psycopg
+            The `name` and `cursor_factory` parameters are Psycopg
             extensions to the |DBAPI|.
 
 
@@ -134,14 +134,15 @@ The ``connection`` class
         the module :mod:`psycopg2.extensions`: see
         :ref:`isolation-level-constants` for the available values.
 
-        The default level is :sql:`READ COMMITTED`: in this level a transaction
+        The default level is :sql:`READ COMMITTED`: at this level a
-        is automatically started every time a database command is executed.  If
+        transaction is automatically started the first time a database command
-        you want an *autocommit* mode,  switch to
+        is executed.  If you want an *autocommit* mode, switch to
-        :obj:`~psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT`
+        :const:`~psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT` before
-        before executing any command::
+        executing any command::
 
             >>> conn.set_isolation_level(psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT)
 
+        See also :ref:`transactions-control`.
 
     .. index::
         pair: Client; Encoding
@@ -307,7 +308,7 @@ The ``connection`` class
             (using the |lo_import|_ function)
         :param lobject_factory: Subclass of
             :class:`~psycopg2.extensions.lobject` to be instantiated.
-        :rtype: :obj:`~psycopg2.extensions.lobject`
+        :rtype: :class:`~psycopg2.extensions.lobject`
 
         .. |lo_import| replace:: :func:`!lo_import`
         .. _lo_import: http://www.postgresql.org/docs/8.4/static/lo-interfaces.html#AEN36307

doc/src/cursor.rst

@@ -31,7 +31,7 @@ The ``cursor`` class
     :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
+    many cursors from the same connection and should use each cursor from
     a single thread. See :ref:`thread-safety` for details.
 
  
@@ -121,7 +121,7 @@ The ``cursor`` class
         The method returns `None`. If a query was executed, the returned
         values can be retrieved using |fetch*|_ methods.
 
-        If :obj:`!async` is ``True``, query execution will be asynchronous:
+        If `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
@@ -129,7 +129,7 @@ The ``cursor`` class
 
         .. extension::
 
-            The :obj:`async` parameter is a Psycopg extension to the |DBAPI|.
+            The `async` parameter is a Psycopg extension to the |DBAPI|.
 
 
     .. method:: mogrify(operation [, parameters])
@@ -150,7 +150,7 @@ The ``cursor`` class
       
         Prepare a database operation (query or command) and then execute it
         against all parameter tuples or mappings found in the sequence
-        :obj:`!seq_of_parameters`.
+        `seq_of_parameters`.
         
         The function is mostly useful for commands that update the database:
         any result set returned by the query is discarded.
@@ -170,7 +170,7 @@ 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 `async` is ``True``, procedure execution will be asynchronous:
         the function returns immediately while the procedure is executed by
         the backend.  Use the :meth:`~cursor.isready` method to see if the
         data is ready for return via |fetch*|_ methods. See
@@ -178,7 +178,7 @@ The ``cursor`` class
 
         .. extension::
 
-            The :obj:`async` parameter is a Psycopg extension to the |DBAPI|.
+            The `async` parameter is a Psycopg extension to the |DBAPI|.
 
 
     .. method:: setinputsizes(sizes)
@@ -276,7 +276,7 @@ The ``cursor`` class
         Scroll the cursor in the result set to a new position according
         to mode.
 
-        If :obj:`!mode` is ``relative`` (default), value is taken as offset to
+        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.
 
@@ -347,7 +347,7 @@ The ``cursor`` class
         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:
+        flexibility.
 
         .. |CREATE-TABLE| replace:: :sql:`CREATE TABLE`
         .. __: http://www.postgresql.org/docs/8.4/static/sql-createtable.html
@@ -441,15 +441,15 @@ The ``cursor`` class
 
     .. method:: copy_from(file, table, sep='\\t', null='\\N', columns=None)
  
-        Read data *from* the file-like object :obj:`!file` appending them to
+        Read data *from* the file-like object `file` appending them to
-        the table named :obj:`!table`.  :obj:`!file` must have both
+        the table named `table`.  `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
+        The optional argument `sep` is the columns separator and
-        :obj:`!null` represents :sql:`NULL` values in the file.
+        `null` represents :sql:`NULL` values in the file.
 
-        The :obj:`!columns` argument is a sequence containing the name of the
+        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.
@@ -461,19 +461,19 @@ The ``cursor`` class
             [(6, 42, 'foo'), (7, 74, 'bar')]
 
         .. versionchanged:: 2.0.6
-            added the :obj:`columns` parameter.
+            added the `columns` parameter.
 
 
     .. method:: copy_to(file, table, sep='\\t', null='\\N', columns=None)
 
-        Write the content of the table named :obj:`!table` *to* the file-like
+        Write the content of the table named `table` *to* the file-like
-        object :obj:`!file`.  :obj:`!file` must have a :meth:`!write` method.
+        object `file`.  `file` must have a :meth:`!write` method.
         See :ref:`copy` for an overview.
 
-        The optional argument :obj:`!sep` is the columns separator and
+        The optional argument `sep` is the columns separator and
-        :obj:`!null` represents :sql:`NULL` values in the file.
+        `null` represents :sql:`NULL` values in the file.
 
-        The :obj:`!columns` argument is a sequence of field names: if not
+        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="|")
@@ -482,7 +482,7 @@ The ``cursor`` class
             ...
 
         .. versionchanged:: 2.0.6
-            added the :obj:`columns` parameter.
+            added the `columns` parameter.
 
 
     .. method:: copy_expert(sql, file [, size])
@@ -491,10 +491,10 @@ The ``cursor`` class
         handle all the parameters that PostgreSQL makes available (see
         |COPY|__ command documentation).
 
-        :obj:`!file` must be an open, readable file for :sql:`COPY FROM` or an
+        `file` must be an open, readable file for :sql:`COPY FROM` or an
-        open, writeable file for :sql:`COPY TO`. The optional :obj:`!size`
+        open, writeable file for :sql:`COPY TO`. The optional `size`
         argument, when specified for a :sql:`COPY FROM` statement, will be
-        passed to :obj:`!file`\ 's read method to control the read buffer
+        passed to `file`\ 's read method to control the read buffer
         size.
 
             >>> cur.copy_expert("COPY test TO STDOUT WITH CSV HEADER", sys.stdout)

doc/src/extensions.rst

@@ -18,7 +18,7 @@ functionalities defined by the |DBAPI|_.
     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 `connection_factory` parameter.
     See also :ref:`subclassing-connection`.
 
     For a complete description of the class, see :class:`connection`.
@@ -28,7 +28,7 @@ functionalities defined by the |DBAPI|_.
     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
-    :meth:`!cursor` method using the :obj:`!cursor_factory` parameter. See
+    :meth:`!cursor` method using the `cursor_factory` parameter. See
     also :ref:`subclassing-cursor`.
 
     For a complete description of the class, see :class:`cursor`.
@@ -104,7 +104,7 @@ deal with Python objects adaptation:
 
 .. function:: adapt(obj)
 
-    Return the SQL representation of :obj:`obj` as a string.  Raise a
+    Return the SQL representation of `obj` as a string.  Raise a
     :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.
@@ -115,9 +115,9 @@ deal with Python objects adaptation:
 
 .. function:: register_adapter(class, adapter)
 
-    Register a new adapter for the objects of class :data:`class`.
+    Register a new adapter for the objects of class `class`.
 
-    :data:`adapter` should be a function taking a single argument (the object
+    `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
     often useful for this task.
@@ -233,10 +233,10 @@ 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` attribute
+    The object OID can be read from the :attr:`cursor.description` attribute
     or by querying from the PostgreSQL catalog.
 
-    :data:`adapter` should have signature :samp:`fun({value}, {cur})` where
+    `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
@@ -248,7 +248,7 @@ details.
 
     Register a type caster created using :func:`new_type`.
 
-    If :obj:`!scope` is specified, it should be a :class:`connection` or a
+    If `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.
 
@@ -321,11 +321,13 @@ set to one of the following constants:
 
     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
+    Some PostgreSQL command such as :sql:`CREATE DATABASE` or :sql:`VACUUM`
-    transaction: to run such command use::
+    can't run into a transaction: to run such command use::
 
         >>> conn.set_isolation_level(ISOLATION_LEVEL_AUTOCOMMIT)
 
+    See also :ref:`transactions-control`.
+
 .. data:: ISOLATION_LEVEL_READ_UNCOMMITTED
 
     The :sql:`READ UNCOMMITTED` isolation level is defined in the SQL standard but not available in
@@ -399,7 +401,7 @@ Connection status constants
 ---------------------------
 
 These values represent the possible status of a connection: the current value
-can be read from the :data:`~connection.status` attribute.
+can be read from the :attr:`~connection.status` attribute.
 
 .. data:: STATUS_SETUP
 
@@ -415,7 +417,7 @@ can be read from the :data:`~connection.status` attribute.
 
 .. data:: STATUS_IN_TRANSACTION
 
-    An alias for :data:`STATUS_BEGIN`
+    An alias for :const:`STATUS_BEGIN`
 
 .. data:: STATUS_SYNC
 

doc/src/extras.rst

@@ -26,7 +26,7 @@ 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 :class:`DictConnection` as :obj:`!connection_factory` argument
+either passing :class:`DictConnection` as `connection_factory` argument
 to the :func:`~psycopg2.connect` function or passing :class:`DictCursor` as
 the :class:`!cursor_factory` argument to the :meth:`~connection.cursor` method
 of a regular :class:`connection`.

doc/src/faq.rst

@@ -0,0 +1,81 @@
+Frequently Asked Questions
+==========================
+
+.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
+
+Here are a few gotchas you may encounter using :mod:`psycopg2`.  Feel free to
+suggest new entries!
+
+
+.. cssclass:: faq
+
+Why does :mod:`!psycopg2` leave database sessions "idle in transaction"?
+    Psycopg normally starts a new transaction the first time a query is
+    executed, e.g. calling :meth:`cursor.execute`, even if the command is a
+    :sql:`SELECT`.  The transaction is not closed until an explicit
+    :meth:`~connection.commit` or :meth:`~connection.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 :ref:`autocommit <autocommit>` mode to avoid a new
+    transaction to be started at the first command.
+
+Why does :meth:`!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 :ref:`adapting-new-types` 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 :ref:`query-parameters`. ::
+
+        >>> 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 :ref:`query-parameters`.
+    ::
+
+        >>> 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 :meth:`~connection.rollback` before sending
+    new commands to the session (if this seems too harsh, remember that
+    PostgreSQL supports nested transactions using the |SAVEPOINT|_ command).
+
+    .. |SAVEPOINT| replace:: :sql:`SAVEPOINT`
+    .. _SAVEPOINT: http://www.postgresql.org/docs/8.4/static/sql-savepoint.html
+
+Why do i get the error *current transaction is aborted, commands ignored until end of transaction block* when I use :mod:`!multiprocessing` (or any other forking system) and not when use :mod:`!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 :class:`str`. Can I receive :class:`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 :ref:`unicode-handling` for the gory details.
+
+I can't compile :mod:`!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 :mod:`!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``.
+
+

doc/src/index.rst

@@ -40,6 +40,7 @@ PostgreSQL arrays.
    tz
    extras
    errorcodes
+   faq
 
 
 .. ifconfig:: builder != 'text'

doc/src/module.rst

@@ -30,24 +30,24 @@ The module interface respects the standard defined in the |DBAPI|_.
 
     The full list of available parameters is:
     
-    - :obj:`!dbname` -- the database name (only in dsn string)
+    - `dbname` -- the database name (only in dsn string)
-    - :obj:`!database` -- the database name (only as keyword argument)
+    - `database` -- the database name (only as keyword argument)
-    - :obj:`!user` -- user name used to authenticate
+    - `user` -- user name used to authenticate
-    - :obj:`!password` -- password used to authenticate
+    - `password` -- password used to authenticate
-    - :obj:`!host` -- database host address (defaults to UNIX socket if not provided)
+    - `host` -- database host address (defaults to UNIX socket if not provided)
-    - :obj:`!port` -- connection port number (defaults to 5432 if not provided)
+    - `port` -- connection port number (defaults to 5432 if not provided)
-    - :obj:`!sslmode` -- `SSL TCP/IP negotiation`__ mode
+    - `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 `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 `dsn` argument. See :ref:`subclassing-connection` for
     details.
 
     .. extension::
 
-        The :obj:`connection_factory` parameter is a Psycopg extension to the
+        The `connection_factory` parameter is a Psycopg extension to the
         |DBAPI|.
 
 

doc/src/tz.rst

@@ -6,7 +6,7 @@
 .. module:: psycopg2.tz
 
 This module holds two different tzinfo implementations that can be used as the
-:obj:`tzinfo` argument to datetime constructors, directly passed to Psycopg
+`tzinfo` argument to datetime constructors, directly passed to Psycopg
 functions or used to set the :attr:`cursor.tzinfo_factory` attribute in
 cursors. 
 

doc/src/usage.rst

@@ -118,9 +118,11 @@ query:
     >>> 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::
+  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
@@ -374,7 +376,7 @@ Transactions control
 --------------------
 
 In Psycopg transactions are handled by the :class:`connection` class. By
-default, every time a command is sent to the database (using one of the
+default, the first time a command is sent to the database (using one of the
 :class:`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
@@ -391,9 +393,9 @@ 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. :sql:`CREATE DATABASE`) require to be run outside any
+few commands (e.g. :sql:`CREATE DATABASE`, :sql:`VACUUM`...) require to be run
-transaction: in order to be able to run these commands from Psycopg, the
+outside any transaction: in order to be able to run these commands from
-session must be in autocommit mode.  Read the documentation for
+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.
 
 
@@ -425,7 +427,7 @@ subsequently handled using :sql:`MOVE`, :sql:`FETCH` and :sql:`CLOSE` commands.
 
 Psycopg wraps the database server side cursor in *named cursors*. A named
 cursor is created using the :meth:`~connection.cursor` method specifying the
-:obj:`!name` parameter. Such cursor will behave mostly like a regular cursor,
+`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.