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.
This commit is contained in:
Daniele Varrazzo 2019-02-17 01:41:29 +01:00
parent d08be18671
commit e5e8cec350
5 changed files with 83 additions and 11 deletions

4
.gitignore vendored
View File

@ -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

5
doc/.gitignore vendored Normal file
View File

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

View File

@ -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

View File

@ -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

View File

@ -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())