Dumper and Loader made abstract classes

diff --git a/docs/adaptation.rst b/docs/adaptation.rst
index 4eaa66faa23854727992317678512e314de177dc..0a560b70c381be90840b8d83021f42ee0fea174f 100644 (file)
--- a/docs/adaptation.rst
+++ b/docs/adaptation.rst
@@ -102,6 +102,12 @@ Objects involved in types adaptation
 
 .. autoclass:: Dumper(src, context=None)
 
+    This is an abstract base class: subclasses *must* implement the `dump()`
+    method. They *may* implement `oid` (as attribute or property) in order to
+    override the oid type oid; if not PostgreSQL will try to infer the type
+    from the context, but this may fail in some contexts and may require a
+    cast.
+
     :param src: The type that will be managed by this dumper.
     :type src: type
     :param context: The context where the transformation is performed. If not
@@ -133,6 +139,10 @@ Objects involved in types adaptation
     .. autoattribute:: oid
         :annotation: int
 
+        .. admonition:: todo
+
+            Document how to find type OIDs in a database.
+
     .. automethod:: register(src, context=None, format=Format.TEXT)
 
         You should call this method on the `Dumper` subclass you create,
@@ -154,6 +164,9 @@ Objects involved in types adaptation
 
 .. autoclass:: Loader(oid, context=None)
 
+    This is an abstract base class: subclasses *must* implement the `load()`
+    method.
+
     :param oid: The type that will be managed by this dumper.
     :type oid: int
     :param context: The context where the transformation is performed. If not

diff --git a/psycopg3/psycopg3/adapt.py b/psycopg3/psycopg3/adapt.py
index 669a2984e08ba242b06f485f6a0d4209898ba275..7938d41182b4a5c0735f3fc3ff626c34ba5f301e 100644 (file)
--- a/psycopg3/psycopg3/adapt.py
+++ b/psycopg3/psycopg3/adapt.py
@@ -4,6 +4,7 @@ Entry point into the adaptation system.
 
 # Copyright (C) 2020 The Psycopg Team
 
+from abc import ABC, abstractmethod
 from typing import Any, cast, Callable, Optional, Type, Union
 
 from . import pq
@@ -17,7 +18,7 @@ from .connection import BaseConnection
 TEXT_OID = builtins["text"].oid
 
 
-class Dumper:
+class Dumper(ABC):
     """
     Convert Python object of the type *src* to PostgreSQL representation.
     """
@@ -30,9 +31,10 @@ class Dumper:
         self.context = context
         self.connection = _connection_from_context(context)
 
+    @abstractmethod
     def dump(self, obj: Any) -> bytes:
         """Convert the object *obj* to PostgreSQL representation."""
-        raise NotImplementedError()
+        ...
 
     def quote(self, obj: Any) -> bytes:
         """Convert the object *obj* to escaped representation."""
@@ -87,7 +89,7 @@ class Dumper:
         return binary_
 
 
-class Loader:
+class Loader(ABC):
     """
     Convert PostgreSQL objects with OID *oid* to Python objects.
     """
@@ -100,9 +102,10 @@ class Loader:
         self.context = context
         self.connection = _connection_from_context(context)
 
+    @abstractmethod
     def load(self, data: bytes) -> Any:
         """Convert a PostgreSQL value to a Python object."""
-        raise NotImplementedError()
+        ...
 
     @classmethod
     def register(

diff --git a/psycopg3/psycopg3/types/singletons.py b/psycopg3/psycopg3/types/singletons.py
index 0c6e04e9553cfbea603c328c23e857e0a94ab5de..dd374b47484b903c775ecea700dc852b1ad98603 100644 (file)
--- a/psycopg3/psycopg3/types/singletons.py
+++ b/psycopg3/psycopg3/types/singletons.py
@@ -36,6 +36,9 @@ class NoneDumper(Dumper):
     quote(), so it can be used in sql composition.
     """
 
+    def dump(self, obj: None) -> bytes:
+        raise NotImplementedError("NULL is passed to Postgres in other ways")
+
     def quote(self, obj: None) -> bytes:
         return b"NULL"