]> git.ipfire.org Git - thirdparty/psycopg.git/commitdiff
Dropped register_binary() method from Loader and Dumper
authorDaniele Varrazzo <daniele.varrazzo@gmail.com>
Tue, 1 Dec 2020 00:20:51 +0000 (00:20 +0000)
committerDaniele Varrazzo <daniele.varrazzo@gmail.com>
Tue, 1 Dec 2020 00:20:51 +0000 (00:20 +0000)
Use the format parameter on register(): documented and made public.

docs/adaptation.rst
psycopg3/psycopg3/adapt.py
psycopg3_c/psycopg3_c/adapt.pyx
psycopg3_c/psycopg3_c/types/numeric.pyx
psycopg3_c/psycopg3_c/types/singletons.pyx
psycopg3_c/psycopg3_c/types/text.pyx
tests/test_adapt.py

index b12218a2bb451fc3fd2b83b00ee14fc54b7b1900..4eaa66faa23854727992317678512e314de177dc 100644 (file)
@@ -39,13 +39,20 @@ Dumpers and loaders configuration
 Dumpers and loaders can be registered on different scopes: globally, per
 `~psycopg3.Connection`, per `~psycopg3.Cursor`, so that adaptation rules can
 be customised for specific needs within the same application: in order to do
-so you can use the *context* parameter of `~Dumper.register()` and similar
-methods.
+so you can use the *context* parameter of `Dumper.register()` and
+`Loader.register()`.
 
-Dumpers and loaders might need to handle data in text and binary format,
-according to how they are registered (e.g. with `~Dumper.register()` or
-`~Dumper.register_binary()`). For most types the format is different so there
-will have to be two different classes.
+.. note::
+
+    `!register()` is a class method on the base class, so if you
+    subclass `!Dumper` or `!Loader` you should call the ``.register()`` on the
+    class you created.
+
+If the data type has also a distinct binary format which you may want to use
+from psycopg (as documented in :ref:`binary-data`) you may want to implement
+binary loaders and dumpers, whose only difference from text dumper is that
+they must be registered using ``format=Format.BINARY`` in `Dumper.register()`
+and `Loader.register()`.
 
 .. admonition:: TODO
 
@@ -109,10 +116,15 @@ Objects involved in types adaptation
 
     .. automethod:: quote
 
-        By default will return the `dump()` value quoted and sanitised, so
-        that the result can be used to build a SQL string. For instance, the
-        method will be used by `~psycopg3.sql.Literal` to convert a value
-        client-side.
+        By default return the `dump()` value quoted and sanitised, so
+        that the result can be used to build a SQL string. This works well
+        for most types and you won't likely have to implement this method in a
+        subclass.
+
+        .. tip::
+
+            This method will be used by `~psycopg3.sql.Literal` to convert a
+            value client-side.
 
         This method only makes sense for text dumpers; the result of calling
         it on a binary dumper is undefined. It might scratch your car, or burn
@@ -121,26 +133,24 @@ Objects involved in types adaptation
     .. autoattribute:: oid
         :annotation: int
 
-    .. automethod:: register(src, context=None)
+    .. automethod:: register(src, context=None, format=Format.TEXT)
+
+        You should call this method on the `Dumper` subclass you create,
+        passing the Python type you want to dump as *src*.
 
         :param src: The type to manage.
         :type src: `!type` or `!str`
         :param context: Where the dumper should be used. If `!None` the dumper
             will be used globally.
         :type context: `~psycopg3.Connection`, `~psycopg3.Cursor`, or `Transformer`
+        :param format: Register the dumper for text or binary adaptation
+        :type format: `~psycopg3.pq.Format`
 
         If *src* is specified as string it will be lazy-loaded, so that it
         will be possible to register it without importing it before. In this
         case it should be the fully qualified name of the object (e.g.
         ``"uuid.UUID"``).
 
-    .. automethod:: register_binary(src, context=None)
-
-        In order to convert a value in binary you can use a ``%b`` placeholder
-        in the query instead of ``%s``.
-
-        Parameters as the same as in `register()`.
-
 
 .. autoclass:: Loader(oid, context=None)
 
@@ -153,17 +163,18 @@ Objects involved in types adaptation
 
     .. automethod:: load
 
-    .. automethod:: register(oid, context=None)
+    .. automethod:: register(oid, context=None, format=Format.TEXT)
+
+        You should call this method on the `Loader` subclass you create,
+        passing the OID of the type you want to load as *oid* parameter.
 
         :param oid: The PostgreSQL OID to manage.
         :type oid: `!int`
         :param context: Where the loader should be used. If `!None` the loader
             will be used globally.
         :type context: `~psycopg3.Connection`, `~psycopg3.Cursor`, or `Transformer`
-
-    .. automethod:: register_binary(oid, context=None)
-
-        Parameters as the same as in `register()`.
+        :param format: Register the loader for text or binary adaptation
+        :type format: `~psycopg3.pq.Format`
 
 
 .. autoclass:: Transformer(context=None)
index ddb763a4db750305bb360b6baba2bde839a2eb6a..669a2984e08ba242b06f485f6a0d4209898ba275 100644 (file)
@@ -68,15 +68,6 @@ class Dumper:
         where = context.dumpers if context else Dumper.globals
         where[src, format] = cls
 
-    @classmethod
-    def register_binary(
-        cls, src: Union[type, str], context: AdaptContext = None
-    ) -> None:
-        """
-        Configure *context* to use this dumper for binary format conversion.
-        """
-        cls.register(src, context, format=Format.BINARY)
-
     @classmethod
     def text(cls, src: Union[type, str]) -> Callable[[DumperType], DumperType]:
         def text_(dumper: DumperType) -> DumperType:
@@ -90,7 +81,7 @@ class Dumper:
         cls, src: Union[type, str]
     ) -> Callable[[DumperType], DumperType]:
         def binary_(dumper: DumperType) -> DumperType:
-            dumper.register_binary(src)
+            dumper.register(src, format=Format.BINARY)
             return dumper
 
         return binary_
@@ -131,13 +122,6 @@ class Loader:
         where = context.loaders if context else Loader.globals
         where[oid, format] = cls
 
-    @classmethod
-    def register_binary(cls, oid: int, context: AdaptContext = None) -> None:
-        """
-        Configure *context* to use this loader to convert binary values.
-        """
-        cls.register(oid, context, format=Format.BINARY)
-
     @classmethod
     def text(cls, oid: int) -> Callable[[LoaderType], LoaderType]:
         def text_(loader: LoaderType) -> LoaderType:
@@ -149,7 +133,7 @@ class Loader:
     @classmethod
     def binary(cls, oid: int) -> Callable[[LoaderType], LoaderType]:
         def binary_(loader: LoaderType) -> LoaderType:
-            loader.register_binary(oid)
+            loader.register(oid, format=Format.BINARY)
             return loader
 
         return binary_
index a61d3eacd24a25a21b6c7a8b117946a176db2d4f..fb18831e6af671891470bf8ad1fc494091986c36 100644 (file)
@@ -87,12 +87,6 @@ cdef class CDumper:
         where = context.dumpers if context else Dumper.globals
         where[src, format] = cls
 
-    @classmethod
-    def register_binary(
-        cls, src: Union[type, str], context: AdaptContext = None
-    ) -> None:
-        cls.register(src, context, format=Format.BINARY)
-
 
 cdef class CLoader:
     cdef impl.Oid _oid
@@ -142,12 +136,6 @@ cdef class CLoader:
         where = context.loaders if context else Loader.globals
         where[oid, format] = cls
 
-    @classmethod
-    def register_binary(
-        cls, oid: int, context: AdaptContext = None
-    ) -> None:
-        cls.register(oid, context, format=Format.BINARY)
-
 
 cdef _connection_from_context(object context):
     from psycopg3.adapt import _connection_from_context
index fe97209e4b19d75ddbc4bf1012b4bdbf00400ca2..4a797d8356d7d016b09111dc3028f4c08a4c9404 100644 (file)
@@ -101,7 +101,7 @@ cdef void register_numeric_c_adapters():
     logger.debug("registering optimised numeric c adapters")
 
     IntDumper.register(int)
-    IntBinaryDumper.register_binary(int)
+    IntBinaryDumper.register(int, format=Format.BINARY)
 
     IntLoader.register(oids.INT2_OID)
     IntLoader.register(oids.INT4_OID)
@@ -110,9 +110,9 @@ cdef void register_numeric_c_adapters():
     FloatLoader.register(oids.FLOAT4_OID)
     FloatLoader.register(oids.FLOAT8_OID)
 
-    Int2BinaryLoader.register_binary(oids.INT2_OID)
-    Int4BinaryLoader.register_binary(oids.INT4_OID)
-    Int8BinaryLoader.register_binary(oids.INT8_OID)
-    OidBinaryLoader.register_binary(oids.OID_OID)
-    Float4BinaryLoader.register_binary(oids.FLOAT4_OID)
-    Float8BinaryLoader.register_binary(oids.FLOAT8_OID)
+    Int2BinaryLoader.register(oids.INT2_OID, format=Format.BINARY)
+    Int4BinaryLoader.register(oids.INT4_OID, format=Format.BINARY)
+    Int8BinaryLoader.register(oids.INT8_OID, format=Format.BINARY)
+    OidBinaryLoader.register(oids.OID_OID, format=Format.BINARY)
+    Float4BinaryLoader.register(oids.FLOAT4_OID, format=Format.BINARY)
+    Float8BinaryLoader.register(oids.FLOAT8_OID, format=Format.BINARY)
index 32aa1206b49564c66c08a6b40b940486cd20fa5d..70295d898e1e0fc723c43ea8c9890f950e14be6f 100644 (file)
@@ -4,6 +4,7 @@ Cython adapters for boolean.
 
 # Copyright (C) 2020 The Psycopg Team
 
+from psycopg3.pq import Format
 from psycopg3_c cimport oids
 
 
@@ -53,7 +54,7 @@ cdef void register_singletons_c_adapters():
     logger.debug("registering optimised singletons c adapters")
 
     BoolDumper.register(bool)
-    BoolBinaryDumper.register_binary(bool)
+    BoolBinaryDumper.register(bool, format=Format.BINARY)
 
     BoolLoader.register(oids.BOOL_OID)
-    BoolBinaryLoader.register_binary(oids.BOOL_OID)
+    BoolBinaryLoader.register(oids.BOOL_OID, format=Format.BINARY)
index b633ec08d1b5aef93197b7ddde0e9c579fdaac60..2bcd6e463e1a727130d950a258d3600507f03133 100644 (file)
@@ -118,13 +118,13 @@ cdef void register_text_c_adapters():
     logger.debug("registering optimised text c adapters")
 
     StringDumper.register(str)
-    StringBinaryDumper.register_binary(str)
+    StringBinaryDumper.register(str, format=Format.BINARY)
 
     TextLoader.register(oids.INVALID_OID)
     TextLoader.register(oids.TEXT_OID)
-    TextLoader.register_binary(oids.TEXT_OID)
+    TextLoader.register(oids.TEXT_OID, format=Format.BINARY)
     TextLoader.register(oids.VARCHAR_OID)
-    TextLoader.register_binary(oids.VARCHAR_OID)
+    TextLoader.register(oids.VARCHAR_OID, format=Format.BINARY)
 
     ByteaLoader.register(oids.BYTEA_OID)
-    ByteaBinaryLoader.register_binary(oids.BYTEA_OID)
+    ByteaBinaryLoader.register(oids.BYTEA_OID, format=Format.BINARY)
index 6b5b4b202c992376da901d64f6e96a3b95332a07..745421445fd1cc752a98f506564ada78abd7d505 100644 (file)
@@ -40,7 +40,7 @@ def test_quote(data, result):
 
 def test_dump_connection_ctx(conn):
     make_dumper("t").register(str, conn)
-    make_dumper("b").register_binary(str, conn)
+    make_dumper("b").register(str, conn, format=Format.BINARY)
 
     cur = conn.cursor()
     cur.execute("select %s, %b", ["hello", "world"])
@@ -49,11 +49,11 @@ def test_dump_connection_ctx(conn):
 
 def test_dump_cursor_ctx(conn):
     make_dumper("t").register(str, conn)
-    make_dumper("b").register_binary(str, conn)
+    make_dumper("b").register(str, conn, format=Format.BINARY)
 
     cur = conn.cursor()
     make_dumper("tc").register(str, cur)
-    make_dumper("bc").register_binary(str, cur)
+    make_dumper("bc").register(str, cur, format=Format.BINARY)
 
     cur.execute("select %s, %b", ["hello", "world"])
     assert cur.fetchone() == ("hellotc", "worldbc")
@@ -91,7 +91,7 @@ def test_cast(data, format, type, result):
 
 def test_load_connection_ctx(conn):
     make_loader("t").register(TEXT_OID, conn)
-    make_loader("b").register_binary(TEXT_OID, conn)
+    make_loader("b").register(TEXT_OID, conn, format=Format.BINARY)
 
     r = conn.cursor().execute("select 'hello'::text").fetchone()
     assert r == ("hellot",)
@@ -101,11 +101,11 @@ def test_load_connection_ctx(conn):
 
 def test_load_cursor_ctx(conn):
     make_loader("t").register(TEXT_OID, conn)
-    make_loader("b").register_binary(TEXT_OID, conn)
+    make_loader("b").register(TEXT_OID, conn, format=Format.BINARY)
 
     cur = conn.cursor()
     make_loader("tc").register(TEXT_OID, cur)
-    make_loader("bc").register_binary(TEXT_OID, cur)
+    make_loader("bc").register(TEXT_OID, cur, format=Format.BINARY)
 
     r = cur.execute("select 'hello'::text").fetchone()
     assert r == ("hellotc",)