From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Mon, 12 Jul 2021 17:05:28 +0000 (+0200)
Subject: Add docs for the psycopg module
X-Git-Tag: 3.0.dev1~26
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=63c8dafb244a89f6806c082df0c438c0f245059c;p=thirdparty%2Fpsycopg.git

Add docs for the psycopg module
---

diff --git a/docs/api/adapt.rst b/docs/api/adapt.rst
index c36ea540a..66f8ffbca 100644
--- a/docs/api/adapt.rst
+++ b/docs/api/adapt.rst
@@ -51,15 +51,6 @@ Other objects used in adaptations
     :members:
 
 
-.. data:: psycopg.adapters
-
-   The global, default adapters map establishing how Python and PostgreSQL
-   types are converted into each other. This map is used as template when new
-   connections are created, using `psycopg.connect()`.
-
-   :type: `~psycopg.adapt.AdaptersMap`
-
-
 .. autoclass:: AdaptersMap
 
    .. automethod:: register_dumper
diff --git a/docs/api/errors.rst b/docs/api/errors.rst
index 128dfbd7a..4993357bd 100644
--- a/docs/api/errors.rst
+++ b/docs/api/errors.rst
@@ -81,8 +81,8 @@ derive from the following classes:
             \|__ `ProgrammingError`
             \|__ `NotSupportedError`
 
-These classes are also exposed both by the Psycopg and the
-`!psycopg.errors` module.
+These classes are exposed both by the Psycopg and the `!psycopg.errors`
+module.
 
 .. autoexception:: Warning()
 .. autoexception:: InterfaceError()
@@ -107,8 +107,8 @@ SQLSTATE exceptions
 
 Errors coming from a database server (as opposite as ones generated
 client-side, such as connection failed) usually have a 5-letters error code
-called SQLSTATE (available in the `~Diagnostic.sqlstate` attribute of
-`Error.diag`).
+called SQLSTATE (available in the `~Diagnostic.sqlstate` attribute of the
+error's `~psycopg.Error.diag` attribute).
 
 Psycopg exposes a different class for each SQLSTATE value, allowing to
 write idiomatic error handling code according to specific conditions happening
@@ -126,8 +126,8 @@ classes for every error defined by PostgreSQL in versions between 9.6 and 13.
 Every class in the module is named after what referred as "condition name" `in
 the documentation`__, converted to CamelCase: e.g. the error 22012,
 ``division_by_zero`` is exposed by this module as the class `!DivisionByZero`.
-There is a handful of exception, required for disambiguate clashes: please
-refer to the table below for all the classes defined.
+There is a handful of... exceptions to this rule, required for disambiguate
+name clashes: please refer to the table below for all the classes defined.
 
 .. __: https://www.postgresql.org/docs/current/errcodes-appendix.html#ERRCODES-TABLE
 
diff --git a/docs/api/index.rst b/docs/api/index.rst
index 44263f272..6ff1e157a 100644
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -5,12 +5,13 @@ Psycopg 3 API
     :maxdepth: 2
     :caption: Contents:
 
+    module
     connections
     cursors
     sql
     errors
+    pool
     adapt
     types
     abc
-    pool
     pq
diff --git a/docs/api/module.rst b/docs/api/module.rst
new file mode 100644
index 000000000..aeb70b3fe
--- /dev/null
+++ b/docs/api/module.rst
@@ -0,0 +1,52 @@
+The `!psycopg` module
+=====================
+
+Psycopg implements the `Python Database DB API 2.0 specification`__. As such
+it also exposes the `module-level objects`__ required by the specifications.
+
+.. __: https://www.python.org/dev/peps/pep-0249/
+.. __: https://www.python.org/dev/peps/pep-0249/#module-interface
+
+
+.. currentmodule:: psycopg
+
+.. autofunction:: connect
+
+   This is an alias of the class method `Connection.connect`: see its
+   documentation for details.
+
+   If you need an asynchronous connection use `AsyncConnection.connect`
+   instead.
+
+
+.. rubric:: Exceptions
+
+The standard `DBAPI exceptions`__ are exposed both by the `!psycopg` module
+and by the `psycopg.errors` module. The latter also exposes more specific
+exceptions, mapping to the database error states (see
+:ref:`sqlstate-exceptions`.
+
+.. __: https://www.python.org/dev/peps/pep-0249/#exceptions
+
+.. parsed-literal::
+
+    `!Exception`
+    \|__ `Warning`
+    \|__ `Error`
+        \|__ `InterfaceError`
+        \|__ `DatabaseError`
+            \|__ `DataError`
+            \|__ `OperationalError`
+            \|__ `IntegrityError`
+            \|__ `InternalError`
+            \|__ `ProgrammingError`
+            \|__ `NotSupportedError`
+
+
+.. data:: adapters
+
+   The global, default adapters map establishing how Python and PostgreSQL
+   types are converted into each other. This map is used as template when new
+   connections are created, using `psycopg.connect()`.
+
+   :type: `~psycopg.adapt.AdaptersMap`