Added documentation about the Diagnostics object

doc/src/extensions.rst

@@ -139,6 +139,37 @@ functionalities defined by the |DBAPI|_.
     .. automethod:: from_string(s)
 
 
+.. autoclass:: Diagnostics(exception)
+
+    .. versionadded:: 2.5
+
+    The attributes currently available are:
+
+    .. attribute::
+        column_name
+        constraint_name
+        context
+        datatype_name
+        internal_position
+        internal_query
+        message_detail
+        message_hint
+        message_primary
+        schema_name
+        severity
+        source_file
+        source_function
+        source_line
+        sqlstate
+        statement_position
+        table_name
+
+        A string with the error field if available; `!None` if not available.
+        The attribute value is available only if the error sent by the server
+        includes the specified field and should remain available until the
+        cursor that generated the exception executes another query.
+
+
 .. autofunction:: set_wait_callback(f)
 
     .. versionadded:: 2.2.0

doc/src/module.rst

@@ -157,10 +157,27 @@ available through the following exceptions:
 
         The cursor the exception was raised from; `None` if not applicable.
 
+    .. attribute:: diag
+
+        A `~psycopg2.extensions.Diagnostics` object containing further
+        information about the error. ::
+
+            >>> try:
+            ...     cur.execute("SELECT * FROM barf")
+            ... except Exception, e:
+            ...     pass
+
+            >>> e.diag.severity
+            'ERROR'
+            >>> e.diag.message_primary
+            'relation "barf" does not exist'
+
+        .. versionadded:: 2.5
+
     .. extension::
 
-        The `~Error.pgerror`, `~Error.pgcode`, and `~Error.cursor` attributes
+        The `~Error.pgerror`, `~Error.pgcode`, `~Error.cursor`, and
-        are Psycopg extensions.
+        `~Error.diag` attributes are Psycopg extensions.
 
 
 .. exception:: InterfaceError

psycopg/diagnostics_type.c

@@ -165,8 +165,19 @@ diagnostics_del(PyObject* self)
 
 /* object type */
 
-#define diagnosticsType_doc \
+static const char diagnosticsType_doc[] =
-"Details from a database error report."
+    "Details from a database error report.\n\n"
+    "The object is returned by the `~psycopg2.Error.diag` attribute of the\n"
+    "`!Error` object.\n"
+    "All the information available from the |PQresultErrorField|_ function\n"
+    "are exposed as attributes by the object, e.g. the `!severity` attribute\n"
+    "returns the `!PG_DIAG_SEVERITY` code. "
+    "Please refer to the `PostgreSQL documentation`__ for the meaning of all"
+        " the attributes.\n\n"
+    ".. |PQresultErrorField| replace:: `!PQresultErrorField()`\n"
+    ".. _PQresultErrorField: http://www.postgresql.org/docs/current/static/"
+        "libpq-exec.html#LIBPQ-PQRESULTERRORFIELD\n"
+    ".. __: PQresultErrorField_\n";
 
 PyTypeObject diagnosticsType = {
     PyVarObject_HEAD_INIT(NULL, 0)