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.

5 files changed, 83 insertions, 11 deletions

diff --git a/.gitignore b/.gitignore
index 4175bb8..9a3bb03 100644
--- a/.gitignore
+++ b/.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
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 0000000..010eeb3
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,5 @@
+env
+src/_build/*
+html/*
+psycopg2.txt
+src/sqlstate_errors.rst
diff --git a/doc/Makefile b/doc/Makefile
index 81ec409..93c2ac8 100644
--- a/doc/Makefile
+++ b/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
diff --git a/doc/src/errors.rst b/doc/src/errors.rst
index d8f4bd4..b4f86f5 100644
--- a/doc/src/errors.rst
+++ b/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
diff --git a/doc/src/tools/make_sqlstate_docs.py b/doc/src/tools/make_sqlstate_docs.py
new file mode 100644
index 0000000..3e1a026
--- /dev/null
+++ b/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())