Dropped format argument to cursor: use binary= instead

This should make pretty unneeded to import the Format object in client
code.

diff --git a/docs/params.rst b/docs/params.rst
index b596922780099fc16db21433facb484d01279744..07c4e90852f42639cb335833adfc6d5f0df72946 100644 (file)
--- a/docs/params.rst
+++ b/docs/params.rst
@@ -196,5 +196,5 @@ Binary parameters and results
 .. admonition:: TODO
 
     - pass parameters in binary with ``%b``
-    - return parameters in binary with `!cursor(format=BINARY)`
+    - return parameters in binary with `!cursor(binary=True)`
     - cannot pass multiple statements in binary

diff --git a/psycopg3/psycopg3/connection.py b/psycopg3/psycopg3/connection.py
index d22433a8e0f7286b4ec4f407dc80801d75990a01..df221f59c877967e2746d24751ca6426adb4c5ab 100644 (file)
--- a/psycopg3/psycopg3/connection.py
+++ b/psycopg3/psycopg3/connection.py
@@ -440,13 +440,14 @@ class Connection(BaseConnection):
         """Close the database connection."""
         self.pgconn.finish()
 
-    def cursor(self, name: str = "", format: Format = Format.TEXT) -> "Cursor":
+    def cursor(self, name: str = "", binary: bool = False) -> "Cursor":
         """
         Return a new `Cursor` to send commands and queries to the connection.
         """
         if name:
             raise NotImplementedError
 
+        format = Format.BINARY if binary else Format.TEXT
         return self.cursor_factory(self, format=format)
 
     def execute(
@@ -567,7 +568,7 @@ class AsyncConnection(BaseConnection):
         self.pgconn.finish()
 
     async def cursor(
-        self, name: str = "", format: Format = Format.TEXT
+        self, name: str = "", binary: bool = False
     ) -> "AsyncCursor":
         """
         Return a new `AsyncCursor` to send commands and queries to the connection.
@@ -575,6 +576,7 @@ class AsyncConnection(BaseConnection):
         if name:
             raise NotImplementedError
 
+        format = Format.BINARY if binary else Format.TEXT
         return self.cursor_factory(self, format=format)
 
     async def execute(

diff --git a/psycopg3/psycopg3/types/range.py b/psycopg3/psycopg3/types/range.py
index 06fd82989e060a2bbd72e0a1d97af2e4a3b596c7..2ae531ae8cb2e165d5585d2faca33ba242bf19c8 100644 (file)
--- a/psycopg3/psycopg3/types/range.py
+++ b/psycopg3/psycopg3/types/range.py
@@ -370,7 +370,7 @@ class RangeInfo(TypeInfo):
     ) -> Optional["RangeInfo"]:
         if isinstance(name, sql.Composable):
             name = name.as_string(conn)
-        cur = conn.cursor(format=Format.BINARY)
+        cur = conn.cursor(binary=True)
         cur.execute(cls._info_query, {"name": name})
         recs = cur.fetchall()
         return cls._from_records(recs)
@@ -381,7 +381,7 @@ class RangeInfo(TypeInfo):
     ) -> Optional["RangeInfo"]:
         if isinstance(name, sql.Composable):
             name = name.as_string(conn)
-        cur = await conn.cursor(format=Format.BINARY)
+        cur = await conn.cursor(binary=True)
         await cur.execute(cls._info_query, {"name": name})
         recs = await cur.fetchall()
         return cls._from_records(recs)

diff --git a/tests/test_adapt.py b/tests/test_adapt.py
index 9b4ca8de5e4358f503edc2e311b0ea99a516a4b2..6123b98bd697106d0114bf7c93382b59894e9438 100644 (file)
--- a/tests/test_adapt.py
+++ b/tests/test_adapt.py
@@ -131,9 +131,9 @@ def test_load_connection_ctx(conn):
     make_loader("t").register(TEXT_OID, conn)
     make_bin_loader("b").register(TEXT_OID, conn)
 
-    r = conn.cursor().execute("select 'hello'::text").fetchone()
+    r = conn.cursor(binary=False).execute("select 'hello'::text").fetchone()
     assert r == ("hellot",)
-    r = conn.cursor(format=1).execute("select 'hello'::text").fetchone()
+    r = conn.cursor(binary=True).execute("select 'hello'::text").fetchone()
     assert r == ("hellob",)
 
 
@@ -165,7 +165,7 @@ def test_load_cursor_ctx(conn):
 )
 @pytest.mark.parametrize("fmt_out", [pq.Format.TEXT, pq.Format.BINARY])
 def test_load_cursor_ctx_nested(conn, sql, obj, fmt_out):
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out == pq.Format.BINARY)
     if fmt_out == pq.Format.TEXT:
         make_loader("c").register(TEXT_OID, cur)
     else:

diff --git a/tests/test_cursor.py b/tests/test_cursor.py
index d9869f89196768b14202f1f56f8ae601e34937d3..b731ef94cd64c81ab79ad09ab5863c029a1b648c 100644 (file)
--- a/tests/test_cursor.py
+++ b/tests/test_cursor.py
@@ -5,7 +5,6 @@ import weakref
 import pytest
 
 import psycopg3
-from psycopg3 import pq
 from psycopg3.oids import builtins
 from psycopg3.adapt import Format
 
@@ -110,7 +109,7 @@ def test_fetchone(conn):
 
 
 def test_execute_binary_result(conn):
-    cur = conn.cursor(format=pq.Format.BINARY)
+    cur = conn.cursor(binary=True)
     cur.execute("select %s::text, %s::text", ["foo", None])
     assert cur.pgresult.fformat(0) == 1
 
@@ -418,7 +417,7 @@ def test_leak(dsn, faker, fmt, fetch):
     n = []
     for i in range(3):
         with psycopg3.connect(dsn) as conn:
-            with conn.cursor(format=Format.as_pq(fmt)) as cur:
+            with conn.cursor(binary=Format.as_pq(fmt)) as cur:
                 cur.execute(faker.drop_stmt)
                 cur.execute(faker.create_stmt)
                 cur.executemany(faker.insert_stmt, faker.records)

diff --git a/tests/test_cursor_async.py b/tests/test_cursor_async.py
index 03dc59ad10a1deca823da1d3e8f4496ce8929c80..c35e019e08ba69b24b7c7e1804bc6de17bbbb72b 100644 (file)
--- a/tests/test_cursor_async.py
+++ b/tests/test_cursor_async.py
@@ -3,7 +3,6 @@ import pytest
 import weakref
 
 import psycopg3
-from psycopg3 import pq
 from psycopg3.adapt import Format
 
 pytestmark = pytest.mark.asyncio
@@ -112,7 +111,7 @@ async def test_fetchone(aconn):
 
 
 async def test_execute_binary_result(aconn):
-    cur = await aconn.cursor(format=pq.Format.BINARY)
+    cur = await aconn.cursor(binary=True)
     await cur.execute("select %s::text, %s::text", ["foo", None])
     assert cur.pgresult.fformat(0) == 1
 

diff --git a/tests/types/test_array.py b/tests/types/test_array.py
index b9e3b17e698854f965def8f52a405f1da502765e..a54330caef53a5e6b67ab912a786b640f7683993 100644 (file)
--- a/tests/types/test_array.py
+++ b/tests/types/test_array.py
@@ -37,7 +37,7 @@ def test_dump_list_str(conn, obj, want, fmt_in):
 @pytest.mark.parametrize("fmt_out", [pq.Format.TEXT, pq.Format.BINARY])
 @pytest.mark.parametrize("want, obj", tests_str)
 def test_load_list_str(conn, obj, want, fmt_out):
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     cur.execute("select %s::text[]", (obj,))
     assert cur.fetchone()[0] == want
 
@@ -45,7 +45,7 @@ def test_load_list_str(conn, obj, want, fmt_out):
 @pytest.mark.parametrize("fmt_in", fmts_in)
 @pytest.mark.parametrize("fmt_out", [pq.Format.TEXT, pq.Format.BINARY])
 def test_all_chars(conn, fmt_in, fmt_out):
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     for i in range(1, 256):
         c = chr(i)
         cur.execute(f"select %{fmt_in}::text[]", ([c],))
@@ -95,7 +95,7 @@ def test_bad_binary_array(input):
 @pytest.mark.parametrize("fmt_out", [pq.Format.TEXT, pq.Format.BINARY])
 @pytest.mark.parametrize("want, obj", tests_int)
 def test_load_list_int(conn, obj, want, fmt_out):
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     cur.execute("select %s::int[]", (obj,))
     assert cur.fetchone()[0] == want
 

diff --git a/tests/types/test_composite.py b/tests/types/test_composite.py
index 85eb22956892d682b80eda67dea477a2141fafa0..b9aadbd3c6013d0fa8e4437d75fdf662ce4c5705 100644 (file)
--- a/tests/types/test_composite.py
+++ b/tests/types/test_composite.py
@@ -47,7 +47,7 @@ def test_dump_tuple(conn, rec, obj):
 
 @pytest.mark.parametrize("fmt_out", [pq.Format.TEXT, pq.Format.BINARY])
 def test_load_all_chars(conn, fmt_out):
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     for i in range(1, 256):
         res = cur.execute("select row(chr(%s::int))", (i,)).fetchone()[0]
         assert res == (chr(i),)
@@ -86,7 +86,7 @@ def test_load_all_chars(conn, fmt_out):
     ],
 )
 def test_load_record_binary(conn, want, rec):
-    cur = conn.cursor(format=1)
+    cur = conn.cursor(binary=True)
     res = cur.execute(f"select row({rec})").fetchone()[0]
     assert res == want
     for o1, o2 in zip(res, want):
@@ -172,7 +172,7 @@ def test_load_composite(conn, testcomp, fmt_out):
     info = CompositeInfo.fetch(conn, "testcomp")
     info.register(conn)
 
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     res = cur.execute("select row('hello', 10, 20)::testcomp").fetchone()[0]
     assert res.foo == "hello"
     assert res.bar == 10
@@ -197,7 +197,7 @@ def test_load_composite_factory(conn, testcomp, fmt_out):
 
     info.register(conn, factory=MyThing)
 
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     res = cur.execute("select row('hello', 10, 20)::testcomp").fetchone()[0]
     assert isinstance(res, MyThing)
     assert res.baz == 20.0

diff --git a/tests/types/test_date.py b/tests/types/test_date.py
index 75f612c48dd99c62df6f5ed5ae13454863f1351b..71f57b8a1d7b4a9781379c6924047e2040f1e0a4 100644 (file)
--- a/tests/types/test_date.py
+++ b/tests/types/test_date.py
@@ -71,7 +71,7 @@ def test_load_date(conn, val, expr):
 @pytest.mark.xfail  # TODO: binary load
 @pytest.mark.parametrize("val, expr", [("2000,1,1", "2000-01-01")])
 def test_load_date_binary(conn, val, expr):
-    cur = conn.cursor(format=Format.BINARY)
+    cur = conn.cursor(binary=Format.BINARY)
     cur.execute(f"select '{expr}'::date")
     assert cur.fetchone()[0] == as_date(val)
 
@@ -317,7 +317,7 @@ def test_load_time(conn, val, expr):
 @pytest.mark.xfail  # TODO: binary load
 @pytest.mark.parametrize("val, expr", [("0,0", "00:00")])
 def test_load_time_binary(conn, val, expr):
-    cur = conn.cursor(format=Format.BINARY)
+    cur = conn.cursor(binary=Format.BINARY)
     cur.execute(f"select '{expr}'::time")
     assert cur.fetchone()[0] == as_time(val)
 
@@ -382,7 +382,7 @@ def test_load_timetz(conn, val, timezone, expr):
 @pytest.mark.xfail  # TODO: binary load
 @pytest.mark.parametrize("val, expr, timezone", [("0,0~2", "00:00", "-02:00")])
 def test_load_timetz_binary(conn, val, expr, timezone):
-    cur = conn.cursor(format=Format.BINARY)
+    cur = conn.cursor(binary=Format.BINARY)
     cur.execute(f"set timezone to '{timezone}'")
     cur.execute(f"select '{expr}'::time")
     assert cur.fetchone()[0] == as_time(val)

diff --git a/tests/types/test_json.py b/tests/types/test_json.py
index ec8caf47c9778c0d0e71fed082334f3a55a13d7e..8309faee5b85e42ba72983ff6d1b6750f01dba08 100644 (file)
--- a/tests/types/test_json.py
+++ b/tests/types/test_json.py
@@ -43,7 +43,7 @@ def test_jsonb_dump(conn, val, fmt_in):
 @pytest.mark.parametrize("jtype", ["json", "jsonb"])
 @pytest.mark.parametrize("fmt_out", [pq.Format.TEXT, pq.Format.BINARY])
 def test_json_load(conn, val, jtype, fmt_out):
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     cur.execute(f"select %s::{jtype}", (val,))
     assert cur.fetchone()[0] == json.loads(val)
 

diff --git a/tests/types/test_network.py b/tests/types/test_network.py
index 3bb0688d55606a3a4685b3a2908226356214ffd2..ada082eeadf55505cf835772ae348954443b4057 100644 (file)
--- a/tests/types/test_network.py
+++ b/tests/types/test_network.py
@@ -60,7 +60,7 @@ def test_network_dump(conn, fmt_in, val):
 @pytest.mark.parametrize("val", ["127.0.0.1/32", "::ffff:102:300/128"])
 def test_inet_load_address(conn, fmt_out, val):
     binary_check(fmt_out)
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     cur.execute("select %s::inet", (val,))
     addr = ipaddress.ip_address(val.split("/", 1)[0])
     assert cur.fetchone()[0] == addr
@@ -72,7 +72,7 @@ def test_inet_load_address(conn, fmt_out, val):
 @pytest.mark.parametrize("val", ["127.0.0.1/24", "::ffff:102:300/127"])
 def test_inet_load_network(conn, fmt_out, val):
     binary_check(fmt_out)
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     cur.execute("select %s::inet", (val,))
     assert cur.fetchone()[0] == ipaddress.ip_interface(val)
     cur.execute("select array[null, %s::inet]", (val,))
@@ -83,7 +83,7 @@ def test_inet_load_network(conn, fmt_out, val):
 @pytest.mark.parametrize("val", ["127.0.0.0/24", "::ffff:102:300/128"])
 def test_cidr_load(conn, fmt_out, val):
     binary_check(fmt_out)
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     cur.execute("select %s::cidr", (val,))
     assert cur.fetchone()[0] == ipaddress.ip_network(val)
     cur.execute("select array[null, %s::cidr]", (val,))

diff --git a/tests/types/test_numeric.py b/tests/types/test_numeric.py
index 3befe2a3ed982688fed34df964ab6c75d4355f20..a794b789739a91ac6d558bf70d454977ae7d1978 100644 (file)
--- a/tests/types/test_numeric.py
+++ b/tests/types/test_numeric.py
@@ -108,7 +108,7 @@ def test_quote_int(conn, val, expr):
 )
 @pytest.mark.parametrize("fmt_out", [pq.Format.TEXT, pq.Format.BINARY])
 def test_load_int(conn, val, pgtype, want, fmt_out):
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     cur.execute(f"select %s::{pgtype}", (val,))
     assert cur.pgresult.fformat(0) == fmt_out
     assert cur.pgresult.ftype(0) == builtins[pgtype].oid
@@ -225,7 +225,7 @@ def test_dump_float_approx(conn, val, expr):
 )
 @pytest.mark.parametrize("fmt_out", [pq.Format.TEXT, pq.Format.BINARY])
 def test_load_float(conn, val, pgtype, want, fmt_out):
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     cur.execute(f"select %s::{pgtype}", (val,))
     assert cur.pgresult.fformat(0) == fmt_out
     assert cur.pgresult.ftype(0) == builtins[pgtype].oid
@@ -266,7 +266,7 @@ def test_load_float(conn, val, pgtype, want, fmt_out):
 )
 @pytest.mark.parametrize("fmt_out", [pq.Format.TEXT, pq.Format.BINARY])
 def test_load_float_approx(conn, expr, pgtype, want, fmt_out):
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     cur.execute("select %s::%s" % (expr, pgtype))
     assert cur.pgresult.fformat(0) == fmt_out
     result = cur.fetchone()[0]
@@ -336,7 +336,7 @@ def test_dump_numeric_binary():
 @pytest.mark.xfail
 def test_load_numeric_binary(conn):
     # TODO: numeric binary casting
-    cur = conn.cursor(format=1)
+    cur = conn.cursor(binary=1)
     res = cur.execute("select 1::numeric").fetchone()[0]
     assert res == Decimal(1)
 

diff --git a/tests/types/test_singletons.py b/tests/types/test_singletons.py
index 213aa13a2e1aba0e88e7704a6237d2bb5803b98d..03b26d06849032362e5d97414256d45050df36ce 100644 (file)
--- a/tests/types/test_singletons.py
+++ b/tests/types/test_singletons.py
@@ -10,7 +10,7 @@ from psycopg3.adapt import Transformer, Format
 @pytest.mark.parametrize("fmt_out", [pq.Format.TEXT, pq.Format.BINARY])
 @pytest.mark.parametrize("b", [True, False])
 def test_roundtrip_bool(conn, b, fmt_in, fmt_out):
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     result = cur.execute(f"select %{fmt_in}", (b,)).fetchone()[0]
     assert cur.pgresult.fformat(0) == fmt_out
     if b is not None:

diff --git a/tests/types/test_text.py b/tests/types/test_text.py
index d2619e11167083fbf7560f584ba40f2d242acba4..f0fd97ec0b271c67f5f8d54329142483c9483301 100644 (file)
--- a/tests/types/test_text.py
+++ b/tests/types/test_text.py
@@ -65,7 +65,7 @@ def test_quote_percent(conn):
 @pytest.mark.parametrize("typename", ["text", "varchar", "name", "bpchar"])
 @pytest.mark.parametrize("fmt_out", [pq.Format.TEXT, pq.Format.BINARY])
 def test_load_1char(conn, typename, fmt_out):
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     for i in range(1, 256):
         cur.execute(f"select chr(%s::int)::{typename}", (i,))
         res = cur.fetchone()[0]
@@ -106,7 +106,7 @@ def test_dump_utf8_badenc(conn, fmt_in):
 @pytest.mark.parametrize("encoding", ["utf8", "latin9"])
 @pytest.mark.parametrize("typename", ["text", "varchar", "name", "bpchar"])
 def test_load_enc(conn, typename, encoding, fmt_out):
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
 
     conn.client_encoding = encoding
     (res,) = cur.execute(
@@ -118,7 +118,7 @@ def test_load_enc(conn, typename, encoding, fmt_out):
 @pytest.mark.parametrize("fmt_out", [pq.Format.TEXT, pq.Format.BINARY])
 @pytest.mark.parametrize("typename", ["text", "varchar", "name", "bpchar"])
 def test_load_badenc(conn, typename, fmt_out):
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
 
     conn.client_encoding = "latin1"
     with pytest.raises(psycopg3.DatabaseError):
@@ -128,7 +128,7 @@ def test_load_badenc(conn, typename, fmt_out):
 @pytest.mark.parametrize("fmt_out", [pq.Format.TEXT, pq.Format.BINARY])
 @pytest.mark.parametrize("typename", ["text", "varchar", "name", "bpchar"])
 def test_load_ascii(conn, typename, fmt_out):
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
 
     conn.client_encoding = "ascii"
     (res,) = cur.execute(
@@ -141,7 +141,7 @@ def test_load_ascii(conn, typename, fmt_out):
 @pytest.mark.parametrize("fmt_out", [pq.Format.TEXT, pq.Format.BINARY])
 @pytest.mark.parametrize("typename", ["text", "varchar", "name", "bpchar"])
 def test_text_array(conn, typename, fmt_in, fmt_out):
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     a = list(map(chr, range(1, 256))) + [eur]
 
     (res,) = cur.execute(f"select %{fmt_in}::{typename}[]", (a,)).fetchone()
@@ -152,7 +152,7 @@ def test_text_array(conn, typename, fmt_in, fmt_out):
 @pytest.mark.parametrize("fmt_out", [pq.Format.TEXT, pq.Format.BINARY])
 def test_text_array_ascii(conn, fmt_in, fmt_out):
     conn.client_encoding = "ascii"
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     a = list(map(chr, range(1, 256))) + [eur]
     exp = [s.encode("utf8") for s in a]
     (res,) = cur.execute(f"select %{fmt_in}::text[]", (a,)).fetchone()
@@ -184,7 +184,7 @@ def test_quote_1byte(conn):
 
 @pytest.mark.parametrize("fmt_out", [pq.Format.TEXT, pq.Format.BINARY])
 def test_load_1byte(conn, fmt_out):
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     for i in range(0, 256):
         cur.execute("select %s::bytea", (fr"\x{i:02x}",))
         assert cur.fetchone()[0] == bytes([i])
@@ -195,7 +195,7 @@ def test_load_1byte(conn, fmt_out):
 @pytest.mark.parametrize("fmt_in", [Format.AUTO, Format.TEXT, Format.BINARY])
 @pytest.mark.parametrize("fmt_out", [pq.Format.TEXT, pq.Format.BINARY])
 def test_bytea_array(conn, fmt_in, fmt_out):
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     a = [bytes(range(0, 256))]
     (res,) = cur.execute(f"select %{fmt_in}::bytea[]", (a,)).fetchone()
     assert res == a

diff --git a/tests/types/test_uuid.py b/tests/types/test_uuid.py
index 8e1f8e83722efb769d993539b4b0b80a1d4bd4e5..548664668e147da38a268c9edb2844a950748f75 100644 (file)
--- a/tests/types/test_uuid.py
+++ b/tests/types/test_uuid.py
@@ -18,7 +18,7 @@ def test_uuid_dump(conn, fmt_in):
 
 @pytest.mark.parametrize("fmt_out", [pq.Format.TEXT, pq.Format.BINARY])
 def test_uuid_load(conn, fmt_out):
-    cur = conn.cursor(format=fmt_out)
+    cur = conn.cursor(binary=fmt_out)
     val = "12345678123456781234567812345679"
     cur.execute("select %s::uuid", (val,))
     assert cur.fetchone()[0] == UUID(val)