crate 2.2.1b2__tar.gz → 2.3.0__tar.gz

{crate-2.2.1b2 → crate-2.3.0}/CHANGES.rst

@@ -2,6 +2,33 @@
 Changes for crate
 =================
 
+2026/09/17 2.3.0
+================
+- Added ``DefaultTypeConverter`` support that decodes ``DataType.UUID``
+  columns to Python ``uuid.UUID`` objects instead of returning the raw string.
+- Added CrateDB column type identifiers to ``DataType``: ``INTERVAL`` (17),
+  ``ROW`` (18), ``FLOAT_VECTOR`` (28), ``UUID`` (29), and ``REGTYPE`` (30).
+  Fixed ``Converter.get()`` raising ``ValueError`` for column type identifiers
+  it does not know. Unknown identifiers now fall back to the default converter.
+
+- Breaking change: ``connect()`` now raises
+  ``crate.client.exceptions.ConnectionError`` immediately if no configured
+  server node responds.
+
+- Breaking change: ``DefaultTypeConverter`` now decodes ``DataType.BIT``
+  columns, converting CrateDB's ``B'0110'`` wire format to a plain string of
+  ``0``/``1`` digits. Code that stripped the wrapper itself needs to be
+  adjusted, or can restore the previous behaviour by mapping
+  ``DataType.BIT`` to a converter of its own.
+
+2026/06/17 2.2.1
+================
+
+- Fixed ``cursor.execute()`` with ``bulk_parameters`` and pyformat SQL: when
+  rows are dicts, both the SQL template and the rows are now converted to
+  positional format before sending to CrateDB. Positional-list rows
+  continue to work as before.
+
 2026/06/04 2.2.0
 ==========
 - Added JSON serialization support for Python's ``datetime.time`` type,

{crate-2.2.1b2 → crate-2.3.0}/PKG-INFO

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

{crate-2.2.1b2 → crate-2.3.0}/docs/by-example/client.rst

@@ -29,12 +29,8 @@ respond, the request is automatically routed to the next server:
     >>> connection = client.connect([invalid_host, crate_host])
     >>> connection.close()
 
-If no ``servers`` are given, the default one ``http://127.0.0.1:4200`` is used:
-
-    >>> connection = client.connect()
-    >>> connection.client._active_servers
-    ['http://127.0.0.1:4200']
-    >>> connection.close()
+If no ``servers`` are supplied to the ``connect`` method, the default address
+``http://127.0.0.1:4200`` is used.
 
 If the option ``error_trace`` is set to ``True``, the client will print a whole
 traceback if a server error occurs:
@@ -77,7 +73,7 @@ connect:
 
 The username for trusted users can also be provided in the URL:
 
-    >>> connection = client.connect(['http://trusted_me@' + crate_host])
+    >>> connection = client.connect([crate_host.replace('://', '://trusted_me@')])
     >>> connection.client.username
     'trusted_me'
     >>> connection.client.password
@@ -97,7 +93,7 @@ also need to provide ``password`` as argument for the ``connect()`` call:
 
 The authentication credentials can also be provided in the URL:
 
-    >>> connection = client.connect(['http://me:my_secret_pw@' + crate_host])
+    >>> connection = client.connect([crate_host.replace('://', '://me:my_secret_pw@')])
     >>> connection.client.username
     'me'
     >>> connection.client.password

{crate-2.2.1b2 → crate-2.3.0}/docs/by-example/cursor.rst

@@ -266,6 +266,37 @@ For completeness' sake the cursor description is updated nonetheless:
     >>> [ desc[0] for desc in cursor.description ]
     ['name', 'position']
 
+executemany() with named parameters
+====================================
+
+``executemany()`` also accepts a :class:`py:list` of :class:`py:dict` when
+the SQL statement contains ``%(name)s`` placeholders. The client converts both the SQL
+template and all rows to positional format before sending them to CrateDB:
+
+.. Hidden: set up mocked response
+
+    >>> connection.client.set_next_response({
+    ...     "results": [
+    ...         {"rowcount": 1},
+    ...         {"rowcount": 1}
+    ...     ],
+    ...     "duration": 123,
+    ...     "cols": [],
+    ... })
+
+    >>> cursor = connection.cursor()
+
+    >>> cursor.executemany(
+    ...     "INSERT INTO t (id, val) VALUES (%(id)s, %(val)s)",
+    ...     [{"id": 1, "val": "foo"}, {"id": 2, "val": "bar"}])
+    [{'rowcount': 1}, {'rowcount': 1}]
+
+    >>> cursor.rowcount
+    2
+
+    >>> cursor.duration
+    123
+
     >>> connection.client.set_next_response({
     ...     "rows":[ [ "North West Ripple", 1 ], [ "Arkintoofle Minor", 3 ], [ "Alpha Centauri", 3 ] ],
     ...     "cols":[ "name", "position" ],
@@ -312,7 +343,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``,
-``TIMESTAMP``, and ``TIMETZ`` on behalf of the ``DefaultTypeConverter``.
+``TIMESTAMP``, ``TIMETZ``, ``BIT``, and ``UUID`` on behalf of the
+``DefaultTypeConverter``.
 
     >>> cursor = connection.cursor(converter=DefaultTypeConverter())
 
@@ -348,6 +380,52 @@ and decoded to a ``datetime.time`` object with the appropriate timezone:
     [datetime.time(12, 30, 45, tzinfo=datetime.timezone.utc)]
 
 
+CrateDB's ``BIT`` type is returned over HTTP in its SQL literal form,
+``B'0110'``. It is decoded to a plain string of ``0``/``1`` digits.
+
+    >>> cursor = connection.cursor(converter=DefaultTypeConverter())
+
+.. hide: set up the mocked response::
+
+    >>> connection.client.set_next_response({
+    ...     "col_types": [25],
+    ...     "rows":[ [ "B'0110'" ] ],
+    ...     "cols":[ "flags" ],
+    ...     "rowcount":1,
+    ...     "duration":1
+    ... })
+
+Executing the query and fetching the decoded result:
+
+    >>> cursor.execute("select b'0110'")
+
+    >>> cursor.fetchone()
+    ['0110']
+
+
+CrateDB's ``UUID`` type is returned over HTTP as a string. It is decoded to a
+Python ``uuid.UUID`` object.
+
+    >>> cursor = connection.cursor(converter=DefaultTypeConverter())
+
+.. hide: set up the mocked response::
+
+    >>> connection.client.set_next_response({
+    ...     "col_types": [29],
+    ...     "rows":[ [ "a5b3c1e0-1b7f-4f3e-9a2d-6c4e8f0a1b2c" ] ],
+    ...     "cols":[ "id" ],
+    ...     "rowcount":1,
+    ...     "duration":1
+    ... })
+
+Executing the query and fetching the decoded result:
+
+    >>> cursor.execute("select 'a5b3c1e0-1b7f-4f3e-9a2d-6c4e8f0a1b2c'::uuid")
+
+    >>> cursor.fetchone()
+    [UUID('a5b3c1e0-1b7f-4f3e-9a2d-6c4e8f0a1b2c')]
+
+
 Custom data type conversion
 ===========================
 

{crate-2.2.1b2 → crate-2.3.0}/docs/connect.rst

@@ -73,13 +73,32 @@ You can pass in as many node URLs as you like.
 
 .. TIP::
 
-    For every query, the client will attempt to connect to each node in sequence
+    When ``connect()`` is called, the client contacts each node to check
+    availability and determine the lowest server version. If no node responds,
+    a ``ConnectionError`` is raised immediately.
+
+    For every subsequent query, the client will attempt each node in sequence
     until a successful connection is made. Nodes are moved to the end of the
     list each time they are tried.
 
     Over multiple query executions, this behaviour functions as client-side
     *round-robin* load balancing. (This is analogous to `round-robin DNS`_.)
 
+.. NOTE::
+
+    Wrap ``connect()`` in a ``try/except`` block to handle an unreachable
+    cluster gracefully:
+
+    .. code-block:: python
+
+        from crate import client
+        from crate.client.exceptions import ConnectionError
+
+        try:
+            connection = client.connect(["node-1:4200", "node-2:4200"])
+        except ConnectionError as e:
+            print(f"Could not reach CrateDB cluster: {e}")
+
 .. _connection-options:
 
 Connection options

{crate-2.2.1b2 → crate-2.3.0}/docs/query.rst

@@ -72,20 +72,19 @@ The same parameter name may appear multiple times in the query:
     ...     "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.
+The client converts the ``%(name)s`` placeholders to ``$N`` positional
+markers before sending the query to CrateDB.
 
 Bulk inserts
 ------------
 
 :ref:`Bulk inserts <crate-reference:http-bulk-ops>` are possible with the
-``executemany()`` method, which takes a :class:`py:list` of tuples to insert:
+``executemany()`` method.
+
+Positional parameters
+.....................
+
+Pass a :class:`py:list` of sequences using ``?`` placeholders:
 
     >>> cursor.executemany(
     ...     "INSERT INTO locations (name, date, kind, position) VALUES (?, ?, ?, ?)",
@@ -94,10 +93,58 @@ Bulk inserts
     [{'rowcount': 1}, {'rowcount': 1}]
 
 The ``executemany()`` method returns a result :class:`dictionary <py:dict>`
-for every tuple. This dictionary always has a ``rowcount`` key, indicating
+for every row. This dictionary always has a ``rowcount`` key, indicating
 how many rows were inserted. If an error occurs, the ``rowcount`` value is
 ``-2``, and the dictionary may additionally have an ``error_message`` key.
 
+Named parameters
+................
+
+``executemany()`` also accepts a :class:`py:list` of :class:`py:dict` using
+``%(name)s`` placeholders. The client converts both the SQL template and all
+rows to positional format before sending to CrateDB:
+
+    >>> cursor.executemany(
+    ...     "INSERT INTO locations (name, date, kind, position) "
+    ...     "VALUES (%(name)s, %(date)s, %(kind)s, %(pos)s)",
+    ...     [{"name": "Cloverleaf", "date": "2007-03-11", "kind": "Quasar", "pos": 7},
+    ...      {"name": "Old Faithful", "date": "2007-03-11", "kind": "Quasar", "pos": 8}])
+    [{'rowcount': 1}, {'rowcount': 1}]
+
+Using ``bulk_parameters`` directly
+...................................
+
+``execute()``  accepts a ``bulk_parameters`` keyword argument directly:
+
+.. NOTE::
+    Please prefer ``executemany()`` for bulk inserts, it is the standard DB-API 2.0
+    interface. The ``bulk_parameters`` argument is a lower-level alternative.
+
+    >>> cursor.execute(
+    ...     "INSERT INTO locations (name, kind, position) VALUES (?, ?, ?)",
+    ...     bulk_parameters=[('Cloverleaf', 'Quasar', 7),
+    ...                      ('Old Faithful', 'Quasar', 8)])
+
+Named ``%(name)s`` placeholders are also supported. When the rows are
+:class:`py:dict` objects the SQL template and rows are fully converted,
+identical to the ``executemany()`` path:
+
+    >>> cursor.execute(
+    ...     "INSERT INTO locations (name, kind, position) "
+    ...     "VALUES (%(name)s, %(kind)s, %(pos)s)",
+    ...     bulk_parameters=[{"name": "Cloverleaf", "kind": "Quasar", "pos": 7},
+    ...                      {"name": "Old Faithful", "kind": "Quasar", "pos": 8}])
+
+When the rows are already positional lists (e.g. data coming from a
+DataFrame), only the SQL template is rewritten. In this case the caller must
+ensure the value order in each row matches the placeholder order in the SQL:
+
+    >>> cursor.execute(
+    ...     "INSERT INTO locations (name, kind, position) "
+    ...     "VALUES (%(name)s, %(kind)s, %(pos)s)",
+    ...     bulk_parameters=[['Cloverleaf', 'Quasar', 7],
+    ...                      ['Old Faithful', 'Quasar', 8]])
+
 .. _selects:
 
 Selecting data

{crate-2.2.1b2 → crate-2.3.0}/pyproject.toml

@@ -5,10 +5,10 @@ build-backend = "hatchling.build"
 [tool.hatch.build.targets.sdist]
 include = [
   "/docs",
-  "/src/crate/*.py",
+  "/src/crate",
   "/tests",
-  "*.rst",
-  "*.txt",
+  "/*.rst",
+  "/*.txt",
 ]
 exclude = [
   "/docs/.crate-docs",
@@ -58,10 +58,10 @@ dependencies = [
 dev = [
     "certifi",
     "coverage",
-    "mypy<2.2",
+    "mypy<2.4",
     "pytest<10",
     "pytz",
-    "ruff<0.16",
+    "ruff<0.17",
 ]
 docs = [
     "sphinx",

crate-2.3.0/src/crate/client/__init__.py

@@ -0,0 +1,49 @@
+# -*- coding: utf-8; -*-
+#
+# Licensed to CRATE Technology GmbH ("Crate") under one or more contributor
+# license agreements.  See the NOTICE file distributed with this work for
+# additional information regarding copyright ownership.  Crate licenses
+# this file to you under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.  You may
+# obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+# However, if you have executed another commercial license agreement
+# with Crate these terms will supersede the license and you may use the
+# software solely pursuant to the terms of the relevant commercial agreement.
+
+from .connection import Connection as connect
+from .exceptions import Error
+
+__all__ = [
+    "connect",
+    "Error",
+]
+
+# ruff: noqa: E402
+try:
+    from importlib.metadata import PackageNotFoundError, version
+except (ImportError, ModuleNotFoundError):  # pragma: no cover
+    from importlib_metadata import (  # type: ignore[assignment,no-redef,unused-ignore]
+        PackageNotFoundError,
+        version,
+    )
+
+__appname__ = "crate"
+
+try:
+    __version__ = version(__appname__)
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "unknown"
+
+# codeql[py/unused-global-variable]
+apilevel = "2.0"
+threadsafety = 1
+paramstyle = "pyformat"

crate-2.3.0/src/crate/client/_pep440.py

@@ -0,0 +1 @@
+from verlib2 import Version  # noqa: F401

crate-2.3.0/src/crate/client/blob.py

@@ -0,0 +1,105 @@
+# -*- coding: utf-8; -*-
+#
+# Licensed to CRATE Technology GmbH ("Crate") under one or more contributor
+# license agreements.  See the NOTICE file distributed with this work for
+# additional information regarding copyright ownership.  Crate licenses
+# this file to you under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.  You may
+# obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+# However, if you have executed another commercial license agreement
+# 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 hashlib
+
+
+class BlobContainer:
+    """class that represents a blob collection in crate.
+
+    can be used to download, upload and delete blobs
+    """
+
+    def __init__(self, container_name, connection):
+        self.container_name = container_name
+        self.conn = connection
+
+    def _compute_digest(self, f):
+        f.seek(0)
+        m = hashlib.sha1()  # noqa: S324
+        while True:
+            d = f.read(1024 * 32)
+            if not d:
+                break
+            m.update(d)
+        f.seek(0)
+        return m.hexdigest()
+
+    def put(self, f, digest=None):
+        """
+        Upload a blob
+
+        :param f:
+            File object to be uploaded (required to support seek if digest is
+            not provided).
+        :param digest:
+            Optional SHA-1 hex digest of the file contents. Gets computed
+            before actual upload if not provided, which requires an extra file
+            read.
+        :return:
+            The hex digest of the uploaded blob if not provided in the call.
+            Otherwise, a boolean indicating if the blob has been newly created.
+        """
+
+        if digest:
+            actual_digest = digest
+        else:
+            actual_digest = self._compute_digest(f)
+
+        created = self.conn.client.blob_put(
+            self.container_name, actual_digest, f
+        )
+        if digest:
+            return created
+        return actual_digest
+
+    def get(self, digest, chunk_size=1024 * 128):
+        """
+        Return the contents of a blob
+
+        :param digest: the hex digest of the blob to return
+        :param chunk_size: the size of the chunks returned on each iteration
+        :return: generator returning chunks of data
+        """
+        return self.conn.client.blob_get(
+            self.container_name, digest, chunk_size
+        )
+
+    def delete(self, digest):
+        """
+        Delete a blob
+
+        :param digest: the hex digest of the blob to be deleted
+        :return: True if blob existed
+        """
+        return self.conn.client.blob_del(self.container_name, digest)
+
+    def exists(self, digest):
+        """
+        Check if a blob exists
+
+        :param digest: Hex digest of the blob
+        :return: Boolean indicating existence of the blob
+        """
+        return self.conn.client.blob_exists(self.container_name, digest)
+
+    def __repr__(self):
+        return "<BlobContainer '{0}'>".format(self.container_name)