first commit based on psycopg2 2.9 version

doc/src/errorcodes.rst

@@ -0,0 +1,76 @@
+`psycopg2.errorcodes` -- Error codes defined by PostgreSQL
+===============================================================
+
+.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
+
+.. index::
+    single: Error; Codes
+
+.. module:: psycopg2.errorcodes
+
+.. testsetup:: *
+
+    from psycopg2 import errorcodes
+
+.. versionadded:: 2.0.6
+
+This module contains symbolic names for all PostgreSQL error codes and error
+classes codes.  Subclasses of `~psycopg2.Error` make the PostgreSQL error
+code available in the `~psycopg2.Error.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 :sql:`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.
+
+.. seealso:: `PostgreSQL Error Codes table`__
+
+    .. __: https://www.postgresql.org/docs/current/static/errcodes-appendix.html#ERRCODES-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 defined by PostgreSQL versions
+between 8.1 and 13 are included in the module.
+
+
+.. autofunction:: lookup(code)
+
+    .. doctest::
+
+        >>> try:
+        ...     cur.execute("SELECT ouch FROM aargh;")
+        ... except Exception as e:
+        ...     pass
+        ...
+        >>> errorcodes.lookup(e.pgcode[:2])
+        'CLASS_SYNTAX_ERROR_OR_ACCESS_RULE_VIOLATION'
+        >>> errorcodes.lookup(e.pgcode)
+        'UNDEFINED_TABLE'
+
+    .. versionadded:: 2.0.14
+
+
+.. testcode::
+    :hide:
+
+    conn.rollback()