From 0e3ede645f7d4529e84466268dd18b144fbfff61 Mon Sep 17 00:00:00 2001
From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Wed, 8 Dec 2021 15:28:13 +0100
Subject: [PATCH] Improve Dumper, Loader documentation

---
 docs/api/abc.rst         | 12 ++----------
 docs/api/adapt.rst       | 30 ++++++++++++++++++++++--------
 psycopg/psycopg/abc.py   | 15 +++++++++++++--
 psycopg/psycopg/adapt.py |  4 ++--
 4 files changed, 39 insertions(+), 22 deletions(-)

diff --git a/docs/api/abc.rst b/docs/api/abc.rst
index 66ee12d12..f40a0596d 100644
--- 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 36bafa97e..e47816ce0 100644
--- 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 56f7dfe47..1899e1437 100644
--- 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 40a94295b..8b90e0c0b 100644
--- 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
-- 
2.47.2