Added table of sqlstate exceptions in the docs

Note that the column-spanning cells break text docs. I don't think
anybody cares about them, so going to drop them.

.gitignore

@@ -7,10 +7,6 @@ MANIFEST
 *.egg-info/
 dist/*
 build/*
-doc/src/_build/*
-doc/html/*
-doc/psycopg2.txt
-scripts/pypi_docs_upload.py
 env
 env?
 .idea

doc/.gitignore

@@ -0,0 +1,5 @@
+env
+src/_build/*
+html/*
+psycopg2.txt
+src/sqlstate_errors.rst

doc/Makefile

@@ -13,16 +13,19 @@ PYTHON_VERSION ?= $(shell $(PYTHON) -c 'import sys; print ("%d.%d" % sys.version
 SPHINXBUILD ?= $$(pwd)/env/bin/sphinx-build
 SPHOPTS = PYTHONPATH=$$(pwd)/../build/lib.$(PYTHON_VERSION)/ SPHINXBUILD=$(SPHINXBUILD)
 
-html:
+html: src/sqlstate_errors.rst
 	$(MAKE) PYTHON=$(PYTHON) -C .. package
 	$(MAKE) $(SPHOPTS) -C src $@
 	cp -r src/_build/html .
 
-text:
+text: src/sqlstate_errors.rst
 	$(MAKE) PYTHON=$(PYTHON) -C .. package
 	$(MAKE) $(SPHOPTS) -C src $@
 	cd src && tools/stitch_text.py index.rst _build/text > ../psycopg2.txt
 
+src/sqlstate_errors.rst: ../psycopg/sqlstate_errors.h
+	PYTHONPATH=`pwd`/../build/lib.$(PYTHON_VERSION) $(PYTHON) src/tools/make_sqlstate_docs.py $< > $@
+
 doctest:
 	$(MAKE) PYTHON=$(PYTHON) -C .. package
 	$(MAKE) $(SPHOPTS) -C src $@
@@ -33,7 +36,7 @@ upload:
 
 clean:
 	$(MAKE) $(SPHOPTS) -C src $@
-	rm -rf html psycopg2.txt
+	rm -rf html psycopg2.txt src/sqlstate_errors.rst
 
 env: requirements.txt
 	virtualenv env

doc/src/errors.rst

@@ -54,10 +54,6 @@ idiomatic error handler:
     except psycopg2.errors.LockNotAvailable:
         locked = True
 
-For completeness, the module also exposes all the :ref:`DB-API-defined
-exceptions <dbapi-exceptions>` and :ref:`a few psycopg-specific ones
-<extension-exceptions>` exposed by the `!extensions` module.  One stop shop
-for all your mistakes...
 
 .. autofunction:: lookup
 
@@ -67,3 +63,17 @@ for all your mistakes...
             cur.execute("LOCK TABLE mytable IN ACCESS EXCLUSIVE MODE NOWAIT")
         except psycopg2.errors.lookup("55P03"):
             locked = True
+
+
+SQLSTATE exception classes
+==========================
+
+The following table contains the list of all the SQLSTATE classes exposed by
+the module.
+
+Note that, for completeness, the module also exposes all the
+:ref:`DB-API-defined exceptions <dbapi-exceptions>` and :ref:`a few
+psycopg-specific ones <extension-exceptions>` exposed by the `!extensions`
+module, which are not listed here.
+
+.. include:: sqlstate_errors.rst

doc/src/tools/make_sqlstate_docs.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python
+"""Create the docs table of the sqlstate errors.
+"""
+
+from __future__ import print_function
+
+import re
+import sys
+from collections import namedtuple
+
+from psycopg2._psycopg import sqlstate_errors
+
+
+def main():
+    sqlclasses = {}
+    clsfile = sys.argv[1]
+    with open(clsfile) as f:
+        for l in f:
+            m = re.match(r'/\* Class (..) - (.+) \*/', l)
+            if m is not None:
+                sqlclasses[m.group(1)] = m.group(2)
+
+    Line = namedtuple('Line', 'colstate colexc colbase sqlstate')
+
+    lines = [Line('SQLSTATE', 'Exception', 'Base exception', None)]
+    for k in sorted(sqlstate_errors):
+        exc = sqlstate_errors[k]
+        lines.append(Line(
+            "``%s``" % k, "`!%s`" % exc.__name__,
+            "`!%s`" % get_base_exception(exc).__name__, k))
+
+    widths = [max(len(l[c]) for l in lines) for c in range(3)]
+    h = Line(*(['=' * w for w in widths] + [None]))
+    lines.insert(0, h)
+    lines.insert(2, h)
+    lines.append(h)
+
+    h1 = '-' * (sum(widths) + len(widths) - 1)
+    sqlclass = None
+    for l in lines:
+        cls = l.sqlstate[:2] if l.sqlstate else None
+        if cls and cls != sqlclass:
+            print("**Class %s**: %s" % (cls, sqlclasses[cls]))
+            print(h1)
+            sqlclass = cls
+
+        print("%-*s %-*s %-*s" % (
+            widths[0], l.colstate, widths[1], l.colexc, widths[2], l.colbase))
+
+
+def get_base_exception(exc):
+    for cls in exc.__mro__:
+        if cls.__module__ == 'psycopg2':
+            return cls
+
+
+if __name__ == '__main__':
+    sys.exit(main())