Improve Dumper, Loader documentation

diff --git a/docs/api/abc.rst b/docs/api/abc.rst
index 66ee12d129c1224ede9c787b5fe7b5c62bc7b279..f40a0596d797ff2f7f71114d47d430ecb4fc95a7 100644 (file)
--- a/docs/api/abc.rst
+++ b/docs/api/abc.rst
@@ -18,11 +18,7 @@ checking.
     A partial implementation of this protocol (implementing everyting except
     `dump()`) is available as `psycopg.adapt.Dumper`.
 
-    .. attribute:: format
-        :type: pq.Format
-
-        The format this class dumps, `~Format.TEXT` or `~Format.BINARY`.
-        This is a class attribute.
+    .. autoattribute:: format
 
     .. automethod:: dump
 
@@ -67,11 +63,7 @@ checking.
     A partial implementation of this protocol (implementing everyting except
     `load()`) is available as `psycopg.adapt.Loader`.
 
-    .. attribute:: format
-        :type: Format
-
-        The format this class can load, `~Format.TEXT` or `~Format.BINARY`.
-        This is a class attribute.
+    .. autoattribute:: format
 
     .. automethod:: load
 

diff --git a/docs/api/adapt.rst b/docs/api/adapt.rst
index 36bafa97ea80590411cedfc785008e4acccf8d8a..e47816ce03189770e48d3ad982e31d9a51cc4f12 100644 (file)
--- a/docs/api/adapt.rst
+++ b/docs/api/adapt.rst
@@ -14,19 +14,27 @@ in the normal use of Psycopg.
 
 See :ref:`adaptation` for an overview of the Psycopg adaptation system.
 
+.. _abstract base class: https://docs.python.org/glossary.html#term-abstract-base-class
+
 
 Dumpers and loaders
 -------------------
 
 .. autoclass:: Dumper(cls, context=None)
 
-    This is an abstract base class: subclasses *must* at least implement the
-    `dump()` method and specify the `format`.
-
-    The class implements the `~psycopg.abc.Dumper` protocol.
+    This is an `abstract base class`_, partially implementing the
+    `~psycopg.abc.Dumper` protocol. Subclasses *must* at least implement the
+    `.dump()` method and optionally override other members.
 
     .. automethod:: dump
 
+    .. attribute:: format
+        :type: psycopg.pq.Format
+        :value: TEXT
+
+        Class attribute. Set it to `~psycopg.pq.Format.BINARY` if the class
+        `dump()` methods converts the object to binary format.
+
     .. automethod:: quote
 
     .. automethod:: get_key
@@ -36,13 +44,19 @@ Dumpers and loaders
 
 .. autoclass:: Loader(oid, context=None)
 
-    This is an abstract base class: subclasses *must* at least implement the
-    `!load()` method and specify a `format`.
-
-    The class implements the `~psycopg.abc.Loader` protocol.
+    This is an `abstract base class`_, partially implementing the
+    `~psycopg.abc.Loader` protocol. Subclasses *must* at least implement the
+    `.load()` method and optionally override other members.
 
     .. automethod:: load
 
+    .. attribute:: format
+        :type: psycopg.pq.Format
+        :value: TEXT
+
+        Class attribute. Set it to `~psycopg.pq.Format.BINARY` if the class
+        `load()` methods converts the object from binary format.
+
 
 Other objects used in adaptations
 ---------------------------------

diff --git a/psycopg/psycopg/abc.py b/psycopg/psycopg/abc.py
index 56f7dfe47920bf9ba8bbf2705c15d8b20a8f7b4a..1899e1437bddf0fc2787b92a681ef476946e1351 100644 (file)
--- a/psycopg/psycopg/abc.py
+++ b/psycopg/psycopg/abc.py
@@ -87,7 +87,12 @@ class Dumper(Protocol):
     """
 
     format: pq.Format
-    """The format this dumper produces (class attirbute)."""
+    """
+    The format that this class `dump()` method produces,
+    `~psycopg.pq.Format.TEXT` or `~psycopg.pq.Format.BINARY`.
+
+    This is a class attribute.
+    """
 
     oid: int
     """The oid to pass to the server, if known; 0 otherwise (class attribute)."""
@@ -162,10 +167,16 @@ class Dumper(Protocol):
 
 class Loader(Protocol):
     """
-    Convert PostgreSQL objects with OID *oid* to Python objects.
+    Convert PostgreSQL values with type OID *oid* to Python objects.
     """
 
     format: pq.Format
+    """
+    The format that this class `load()` method can convert,
+    `~psycopg.pq.Format.TEXT` or `~psycopg.pq.Format.BINARY`.
+
+    This is a class attribute.
+    """
 
     def __init__(self, oid: int, context: Optional[AdaptContext] = None):
         ...

diff --git a/psycopg/psycopg/adapt.py b/psycopg/psycopg/adapt.py
index 40a94295bfce47957870ca8917f293efdc0bef9b..8b90e0c0baf697b7de6551bc7ac71d402b8604e7 100644 (file)
--- a/psycopg/psycopg/adapt.py
+++ b/psycopg/psycopg/adapt.py
@@ -117,9 +117,9 @@ class Dumper(abc.Dumper, ABC):
         return self
 
 
-class Loader(ABC):
+class Loader(abc.Loader, ABC):
     """
-    Convert PostgreSQL objects with OID *oid* to Python objects.
+    Convert PostgreSQL values with type OID *oid* to Python objects.
     """
 
     format: pq.Format = pq.Format.TEXT