From 7c148ecee43ae2a9045d97f1451ee92beb827784 Mon Sep 17 00:00:00 2001
From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Mon, 11 Feb 2019 01:09:20 +0000
Subject: [PATCH] Improvements to errors module docs

---
 doc/src/errors.rst | 19 ++++++++++++++-----
 doc/src/module.rst |  5 +++--
 2 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/doc/src/errors.rst b/doc/src/errors.rst
index 061999b1..d8f4bd4a 100644
--- a/doc/src/errors.rst
+++ b/doc/src/errors.rst
@@ -10,8 +10,9 @@
 
 .. versionadded:: 2.8
 
-This module contains the classes psycopg raises upon receiving an error from
-the database with a :sql:`SQLSTATE` value attached. The module is generated
+This module exposes the classes psycopg raises upon receiving an error from
+the database with a :sql:`SQLSTATE` value attached (available in the
+`~psycopg2.Error.pgcode` attribute). The content of the module is generated
 from the PostgreSQL source code and includes classes for every error defined
 by PostgreSQL in versions between 9.1 and 11.
 
@@ -53,8 +54,16 @@ idiomatic error handler:
     except psycopg2.errors.LockNotAvailable:
         locked = True
 
-For completeness, the module also exposes all the DB-API-defined classes and
-:ref:`a few psycopg-specific exceptions <extension-exceptions>` previously
-exposed by the `!extensions` module.  One stop shop for all your mistakes...
+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
+
+    .. code-block:: python
+
+        try:
+            cur.execute("LOCK TABLE mytable IN ACCESS EXCLUSIVE MODE NOWAIT")
+        except psycopg2.errors.lookup("55P03"):
+            locked = True
diff --git a/doc/src/module.rst b/doc/src/module.rst
index c6944f8f..f17f3ae4 100644
--- a/doc/src/module.rst
+++ b/doc/src/module.rst
@@ -137,14 +137,15 @@ available through the following exceptions:
 .. exception:: Warning
 
     Exception raised for important warnings like data truncations while
-    inserting, etc. It is a subclass of the Python `~exceptions.StandardError`.
+    inserting, etc. It is a subclass of the Python `StandardError`
+    (`Exception` on Python 3).
 
 .. exception:: Error
 
     Exception that is the base class of all other error exceptions. You can
     use this to catch all errors with one single `!except` statement. Warnings
     are not considered errors and thus not use this class as base. It
-    is a subclass of the Python `!StandardError`.
+    is a subclass of the Python `StandardError` (`Exception` on Python 3).
 
     .. attribute:: pgerror