crate 2.1.2__tar.gz → 2.2.0__tar.gz

{crate-2.1.2 → crate-2.2.0}/CHANGES.rst

@@ -2,8 +2,23 @@
 Changes for crate
 =================
 
-Unreleased
+2026/06/04 2.2.0
 ==========
+- Added JSON serialization support for Python's ``datetime.time`` type,
+  encoding it as an ISO 8601 string compatible with CrateDB's ``TIMETZ``
+  column type.
+
+- Added gzip compression for outgoing request bodies via the ``compress``
+  parameter (default: ``8192`` bytes).
+  Pass ``True`` to always compress, ``False`` to disable, or an integer
+  as a byte threshold. The driver always sends ``Accept-Encoding: gzip,
+  deflate`` to negotiate compressed responses from the server when
+  compression is enabled.
+
+- Added named parameter support (``pyformat`` paramstyle). Passing a
+  :class:`py:dict` as ``parameters`` to ``cursor.execute()`` now accepts
+  ``%(name)s`` placeholders and converts them to positional ``?`` markers
+  client-side. Positional parameters using ``?`` continue to work unchanged.
 
 2026/03/09 2.1.2
 ================

{crate-2.1.2 → crate-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crate
-Version: 2.1.2
+Version: 2.2.0
 Summary: CrateDB Python Client
 Author-email: "Crate.io" <office@crate.io>
 License-Expression: Apache-2.0

{crate-2.1.2 → crate-2.2.0}/docs/by-example/cursor.rst

@@ -311,8 +311,8 @@ Python data type conversion
 ===========================
 
 The cursor object can optionally convert database types to native Python data
-types. Currently, this is implemented for the CrateDB data types ``IP`` and
-``TIMESTAMP`` on behalf of the ``DefaultTypeConverter``.
+types. Currently, this is implemented for the CrateDB data types ``IP``,
+``TIMESTAMP``, and ``TIMETZ`` on behalf of the ``DefaultTypeConverter``.
 
     >>> cursor = connection.cursor(converter=DefaultTypeConverter())
 
@@ -329,6 +329,24 @@ types. Currently, this is implemented for the CrateDB data types ``IP`` and
     >>> cursor.fetchone()
     ['foo', IPv4Address('10.10.10.1'), datetime.datetime(2022, 7, 18, 18, 10, 36, 758000, tzinfo=datetime.timezone.utc)]
 
+CrateDB's ``TIMETZ`` type is returned over HTTP as ``[microseconds_since_midnight, tz_offset_seconds]`` 
+and decoded to a ``datetime.time`` object with the appropriate timezone:
+
+    >>> cursor = connection.cursor(converter=DefaultTypeConverter())
+
+    >>> connection.client.set_next_response({
+    ...     "col_types": [20],
+    ...     "rows":[ [ [45045000000, 0] ] ],
+    ...     "cols":[ "t" ],
+    ...     "rowcount":1,
+    ...     "duration":1
+    ... })
+
+    >>> cursor.execute('')
+
+    >>> cursor.fetchone()
+    [datetime.time(12, 30, 45, tzinfo=datetime.timezone.utc)]
+
 
 Custom data type conversion
 ===========================

{crate-2.1.2 → crate-2.2.0}/docs/connect.rst

@@ -266,6 +266,32 @@ with the rest of your arguments.
 
    However, you can query any schema you like by specifying it in the query.
 
+.. _compression:
+
+Request and response compression
+=================================
+
+The ``compress`` parameter controls gzip compression of outgoing request
+bodies. The default ``8192`` compresses payloads larger than 8 KB::
+
+    >>> connection = client.connect('localhost:4200')
+    # compress=8192 is the default — payloads > 8 KB are gzip-compressed
+
+To always compress, regardless of payload size::
+
+    >>> connection = client.connect('localhost:4200', compress=True)
+
+To disable compression entirely::
+
+    >>> connection = client.connect('localhost:4200', compress=False)
+
+To use a custom threshold (bytes)::
+
+    >>> connection = client.connect('localhost:4200', compress=4096)
+
+The driver always sends ``Accept-Encoding: gzip, deflate`` so the server
+may return compressed responses if compression is enabled. 
+
 Next steps
 ==========
 

{crate-2.1.2 → crate-2.2.0}/docs/query.rst

@@ -54,6 +54,33 @@ characters appear, in the order they appear.
     Always use the parameter interpolation feature of the client library to
     guard against malicious input, as demonstrated in the example above.
 
+Named parameters
+----------------
+
+For queries with many parameters or repeated values, named parameters improve
+readability. Pass a :class:`py:dict` as the second argument using
+``%(name)s`` placeholders:
+
+    >>> cursor.execute(
+    ...     "INSERT INTO locations (name, date, kind, position) "
+    ...     "VALUES (%(name)s, %(date)s, %(kind)s, %(pos)s)",
+    ...     {"name": "Einstein Cross", "date": "2007-03-11", "kind": "Quasar", "pos": 7})
+
+The same parameter name may appear multiple times in the query:
+
+    >>> cursor.execute(
+    ...     "SELECT * FROM locations WHERE name = %(q)s OR kind = %(q)s",
+    ...     {"q": "Quasar"})
+
+The client converts the ``%(name)s`` placeholders to positional ``?`` markers
+before sending the query to CrateDB, so no server-side changes are required.
+
+.. NOTE::
+
+    Named parameters are not yet supported by ``executemany()``. Use
+    positional ``?`` placeholders with a :class:`py:list` of tuples for bulk
+    operations.
+
 Bulk inserts
 ------------
 

{crate-2.1.2 → crate-2.2.0}/pyproject.toml

@@ -58,7 +58,7 @@ dependencies = [
 dev = [
     "certifi",
     "coverage",
-    "mypy<1.20",
+    "mypy<2.2",
     "pytest<10",
     "pytz",
     "ruff<0.16",

{crate-2.1.2 → crate-2.2.0}/tests/client/test_cursor.py

@@ -293,6 +293,41 @@ def test_execute_custom_converter(mocked_connection):
         ]
 
 
+def test_execute_time_converter(mocked_connection):
+    """
+    Verify that CrateDB's TIMETZ wire format
+    ``[microseconds, tz_offset_seconds]`` is decoded to a ``datetime.time``
+    object by ``DefaultTypeConverter``.
+    """
+    converter = DefaultTypeConverter()
+    cursor = mocked_connection.cursor(converter=converter)
+    response = {
+        "col_types": [20],
+        "cols": ["t"],
+        "rows": [
+            [[45045000000, 0]],       # 12:30:45 UTC
+            [[45045123456, 7200]],    # 12:30:45.123456 +02:00
+            [None],
+        ],
+        "rowcount": 3,
+        "duration": 1,
+    }
+
+    with mock.patch.object(
+        mocked_connection.client, "sql", return_value=response
+    ):
+        cursor.execute("")
+        result = cursor.fetchall()
+
+    assert result == [
+        [datetime.time(12, 30, 45, 0,
+                       tzinfo=datetime.timezone.utc)],
+        [datetime.time(12, 30, 45, 123456,
+                       tzinfo=datetime.timezone(datetime.timedelta(hours=2)))],
+        [None],
+    ]
+
+
 def test_execute_with_converter_and_invalid_data_type(mocked_connection):
     converter = DefaultTypeConverter()
 
@@ -492,6 +527,44 @@ def test_execute_with_timezone(mocked_connection):
         assert result[0][1].tzname() == "UTC"
 
 
+def test_execute_with_named_params(mocked_connection):
+    """
+    Verify that named %(name)s parameters are converted to positional ? markers
+    and the values are passed as an ordered list.
+    """
+    cursor = mocked_connection.cursor()
+    cursor.execute(
+        "SELECT * FROM t WHERE a = %(a)s AND b = %(b)s",
+        {"a": 1, "b": 2},
+    )
+    mocked_connection.client.sql.assert_called_once_with(
+        "SELECT * FROM t WHERE a = $1 AND b = $2", [1, 2], None
+    )
+
+
+def test_execute_with_named_params_repeated(mocked_connection):
+    """
+    Verify that a parameter name used multiple times in the SQL is resolved
+    correctly each time it appears.
+    """
+    cursor = mocked_connection.cursor()
+    cursor.execute("SELECT %(x)s, %(x)s", {"x": 42})
+    mocked_connection.client.sql.assert_called_once_with(
+        "SELECT $1, $1", [42], None
+    )
+
+
+def test_execute_with_named_params_missing(mocked_connection):
+    """
+    Verify that a ProgrammingError is raised when a placeholder name is absent
+    from the parameters dict, and that the client is never called.
+    """
+    cursor = mocked_connection.cursor()
+    with pytest.raises(ProgrammingError, match="Named parameter 'z' not found"):
+        cursor.execute("SELECT %(z)s", {"a": 1})
+    mocked_connection.client.sql.assert_not_called()
+
+
 def test_cursor_close(mocked_connection):
     """
     Verify that a cursor is not closed if not specifically closed.

{crate-2.1.2 → crate-2.2.0}/tests/client/test_http.py

@@ -19,6 +19,7 @@
 # with Crate these terms will supersede the license and you may use the
 # software solely pursuant to the terms of the relevant commercial agreement.
 
+import gzip
 import json
 import os
 import queue
@@ -200,6 +201,48 @@ def test_redirect_handling():
     assert conn_kw == {"socket_options": _get_socket_opts(keepalive=True)}
 
 
+@pytest.mark.parametrize("method,args,success_status", [
+    ("blob_exists", ("blobs", "fake_digest"), 200),
+    ("blob_put",    ("blobs", "fake_digest", b"data"), 201),
+    ("blob_del",    ("blobs", "fake_digest"), 204),
+    ("blob_get",    ("blobs", "fake_digest"), 200),
+])
+def test_redirect_blob_preserves_basic_auth(method, args, success_status):
+    """
+    Verify Basic HTTP auth credentials are forwarded when following blob
+    endpoint redirects.
+    """
+    redirect = fake_redirect("http://localhost:4201/_blobs/blobs/fake_digest")
+    success = fake_response(success_status)
+
+    with patch(REQUEST_PATH, side_effect=[redirect, success]) as mock_req:
+        client = Client(
+            servers="localhost:4200", username="admin", password="secret"
+        )
+        getattr(client, method)(*args)
+
+    assert mock_req.call_count == 2
+    for call in mock_req.call_args_list:
+        assert call.kwargs.get("username") == "admin"
+        assert call.kwargs.get("password") == "secret"
+
+
+def test_redirect_blob_preserves_jwt_auth():
+    """
+    Verify JWT bearer token is forwarded when following blob endpoint redirects.
+    """
+    redirect = fake_redirect("http://localhost:4201/_blobs/blobs/fake_digest")
+    success = fake_response(200)
+
+    with patch(REQUEST_PATH, side_effect=[redirect, success]) as mock_req:
+        client = Client(servers="localhost:4200", jwt_token="my.jwt.token")
+        client.blob_exists("blobs", "fake_digest")
+
+    assert mock_req.call_count == 2
+    for call in mock_req.call_args_list:
+        assert call.kwargs.get("jwt_token") == "my.jwt.token"
+
+
 def test_server_infos():
     """
     Verify that when a `MaxRetryError` is raised, a `ConnectionError` is raised.
@@ -735,3 +778,83 @@ def test_credentials_and_token(serve_http):
         assert excinfo.match(
             "Either JWT tokens are accepted, or user credentials, but not both"
         )
+
+def test_compress_accept_encoding_always_sent():
+    """Accept-Encoding is sent even when compression is disabled."""
+    captured = {}
+
+    def capturing(*_, **kwargs):
+        captured["headers"] = kwargs.get("headers") or {}
+        return fake_response(200)
+
+    with patch(REQUEST_PATH, side_effect=capturing):
+        Client(servers="localhost:4200", compress=False).sql("SELECT 1")
+    assert captured["headers"].get("Accept-Encoding") == "gzip, deflate"
+
+
+def test_compress_false_no_content_encoding():
+    """No Content-Encoding header when compress=False."""
+    captured = {}
+
+    def capturing(*_, **kwargs):
+        captured["headers"] = kwargs.get("headers") or {}
+        return fake_response(200)
+
+    with patch(REQUEST_PATH, side_effect=capturing):
+        Client(servers="localhost:4200", compress=False).sql("SELECT 1")
+    assert "Content-Encoding" not in captured["headers"]
+
+
+def test_compress_true_always_compresses():
+    """compress=True compresses regardless of payload size."""
+    captured = {}
+
+    def capturing(*_, **kwargs):
+        captured["data"] = kwargs.get("data", b"")
+        captured["headers"] = kwargs.get("headers") or {}
+        return fake_response(200)
+
+    with patch(REQUEST_PATH, side_effect=capturing):
+        Client(servers="localhost:4200", compress=True).sql("SELECT 1")
+    assert captured["headers"].get("Content-Encoding") == "gzip"
+    assert b'"stmt"' in gzip.decompress(captured["data"])
+
+
+def test_compress_threshold_above():
+    """Payload above threshold is compressed."""
+    captured = {}
+
+    def capturing(*_, **kwargs):
+        captured["headers"] = kwargs.get("headers") or {}
+        return fake_response(200)
+
+    with patch(REQUEST_PATH, side_effect=capturing):
+        Client(servers="localhost:4200", compress=0).sql("SELECT 1")
+    assert captured["headers"].get("Content-Encoding") == "gzip"
+
+
+def test_compress_threshold_below():
+    """Payload below threshold is not compressed."""
+    captured = {}
+
+    def capturing(*_, **kwargs):
+        captured["headers"] = kwargs.get("headers") or {}
+        return fake_response(200)
+
+    with patch(REQUEST_PATH, side_effect=capturing):
+        Client(servers="localhost:4200", compress=999_999).sql("SELECT 1")
+    assert "Content-Encoding" not in captured["headers"]
+
+
+def test_compress_default():
+    """Default args: Accept-Encoding sent, small payload not compressed."""
+    captured = {}
+
+    def capturing(*_, **kwargs):
+        captured["headers"] = kwargs.get("headers") or {}
+        return fake_response(200)
+
+    with patch(REQUEST_PATH, side_effect=capturing):
+        Client(servers="localhost:4200").sql("SELECT 1")
+    assert captured["headers"].get("Accept-Encoding") == "gzip, deflate"
+    assert "Content-Encoding" not in captured["headers"]

{crate-2.1.2 → crate-2.2.0}/tests/client/test_serialization.py

@@ -125,6 +125,44 @@ def test_date_serialization():
     assert result == b"1461196800000"
 
 
+def test_naive_time_serialization():
+    """
+    Verify that a naive `datetime.time` serializes to an ISO 8601 string.
+    """
+    data = dt.time(12, 30, 45)
+    result = json_dumps(data)
+    assert result == b'"12:30:45"'
+
+
+def test_time_with_microseconds_serialization():
+    """
+    Verify that `datetime.time` with microseconds serializes correctly.
+    """
+    data = dt.time(12, 30, 45, 123456)
+    result = json_dumps(data)
+    assert result == b'"12:30:45.123456"'
+
+
+def test_aware_time_serialization():
+    """
+    Verify that a timezone-aware `datetime.time` serializes to ISO 8601 format,
+    including the UTC offset.
+    """
+    data = dt.time(12, 30, 45, tzinfo=dt.timezone.utc)
+    result = json_dumps(data)
+    assert result == b'"12:30:45+00:00"'
+
+
+def test_aware_time_with_offset_serialization():
+    """
+    Verify that a `datetime.time` with a non-UTC offset serializes correctly.
+    """
+    tz = dt.timezone(dt.timedelta(hours=2))
+    data = dt.time(12, 30, 45, tzinfo=tz)
+    result = json_dumps(data)
+    assert result == b'"12:30:45+02:00"'
+
+
 def test_uuid_serialization():
     """
     Verify that a `uuid.UUID` can be serialized.

{crate-2.1.2 → crate-2.2.0}/tests/testing/test_layer.py

@@ -22,13 +22,11 @@
 import json
 import os
 import tempfile
-import urllib
 from io import BytesIO
 from pathlib import Path
 from unittest import TestCase, mock
 
 import urllib3
-from verlib2 import Version
 
 import crate
 from crate.testing.layer import (
@@ -38,7 +36,7 @@ from crate.testing.layer import (
     wait_for_http_url,
 )
 from tests.client.settings import crate_path
-from tests.conftest import download_cratedb
+from tests.conftest import download_cratedb, get_crate_url
 
 
 class LayerUtilsTest(TestCase):
@@ -86,18 +84,10 @@ class LayerUtilsTest(TestCase):
         The CrateLayer can also be created by providing an URI that points to
         a CrateDB tarball.
         """
-        with urllib.request.urlopen(
-            "https://crate.io/versions.json"
-        ) as response:
-            versions = json.loads(response.read().decode())
-            version = versions["crate_testing"]
-
-        self.assertGreaterEqual(Version(version), Version("4.5.0"))
-
-        uri = "https://cdn.crate.io/downloads/releases/crate-{}.tar.gz".format(
-            version
-        )
-        layer = CrateLayer.from_uri(uri, name="crate-by-uri", http_port=42203)
+        layer = CrateLayer.from_uri(get_crate_url(),
+                                    name="crate-by-uri",
+                                    http_port=42203
+                                    )
         self.assertIsInstance(layer, CrateLayer)
 
     @mock.patch.dict("os.environ", {}, clear=True)