FAQs grouped in themes.

doc/src/faq.rst

@@ -7,6 +7,9 @@ Here are a few gotchas you may encounter using `psycopg2`.  Feel free to
 suggest new entries!
 
 
+Problems with transactions handling
+-----------------------------------
+
 .. cssclass:: faq
 
 Why does `!psycopg2` leave database sessions "idle in transaction"?
@@ -22,6 +25,27 @@ Why does `!psycopg2` leave database sessions "idle in transaction"?
     connection in :ref:`autocommit <autocommit>` mode to avoid a new
     transaction to be started at the first command.
 
+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 `~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 `!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.
+
+
+Problems with type conversions
+------------------------------
+
+.. cssclass:: faq
+
 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
@@ -47,21 +71,6 @@ I try to execute a query but it fails with the error *not all arguments converte
         >>> 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 `~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 `!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::
 
@@ -84,13 +93,11 @@ Psycopg converts :sql:`decimal`\/\ :sql:`numeric` database types into Python `!D
     documentation. If you find `!psycopg2.extensions.DECIMAL` not avalable, use
     `!psycopg2._psycopg.DECIMAL` instead.
 
-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?
+Best practices
-    You need to install the development version of the libpq: the package is
+--------------
-    usually called ``libpq-dev``.
+
+.. cssclass:: faq
 
 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
@@ -116,3 +123,18 @@ What are the advantages or disadvantages of using named cursors?
     the backend. The advantage is that data is fetched one chunk at a time:
     using small `~cursor.fetchmany()` values it is possible to use very
     little memory on the client and to skip or discard parts of the result set.
+
+
+Problems compiling Psycopg from source
+--------------------------------------
+
+.. cssclass:: faq
+
+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``.
+