crate 1.0.0.dev2__tar.gz → 2.0.0__tar.gz

crate-1.0.0.dev2/CHANGES.txt → crate-2.0.0/CHANGES.rst

@@ -5,13 +5,45 @@ Changes for crate
 Unreleased
 ==========
 
-- The SQLAlchemy dialect has been split off into the `sqlalchemy-cratedb`_
-  package. See `Migrate from crate.client to sqlalchemy-cratedb`_ to learn
-  about necessary migration steps.
-- Returned Python ``datetime`` objects are now always timezone-aware,
-  using UTC by default. This is a possible BREAKING CHANGE: Removed the use
-  of "naive" Python ``datetime`` objects, i.e. instances without ``tzinfo``
-  attribute set.
+2025/01/30 2.0.0
+================
+
+- Switched JSON encoder to use the `orjson`_ library, to improve JSON
+  marshalling performance. Thanks, @widmogrod.
+
+  orjson is fast and in some spots even more correct when compared against
+  Python's stdlib ``json`` module. Contrary to the stdlib variant, orjson
+  will serialize to ``bytes`` instead of ``str``. When sending data to CrateDB,
+  ``crate-python`` uses a custom encoder to add support for additional data
+  types.
+
+  - Python's ``Decimal`` type will be serialized to ``str``.
+  - Python's ``dt.datetime`` and ``dt.date`` types will be serialized to
+    ``int`` (``LONG``) after converting to milliseconds since epoch, to
+    optimally accommodate CrateDB's `TIMESTAMP`_ representation.
+  - NumPy's data types will be handled by ``orjson`` without any ado.
+
+.. _orjson: https://github.com/ijl/orjson
+.. _TIMESTAMP: https://cratedb.com/docs/crate/reference/en/latest/general/ddl/data-types.html#type-timestamp
+
+2024/11/23 1.0.1
+================
+
+- Python: Fixed "implicit namespace packages" migration by omitting
+  ``__init__.py`` from ``crate`` namespace package, see `PEP 420`_
+  and `Package Discovery and Namespace Package » Finding namespace packages`_.
+
+
+2024/11/05 1.0.0
+================
+
+- BREAKING CHANGE: The SQLAlchemy dialect has been split off into
+  the `sqlalchemy-cratedb`_ package, see notice below.
+- Feature: Returned Python ``datetime`` objects are now always timezone-aware,
+  using UTC by default.
+  It may be a breaking change for some users of the library that don't expect
+  to receive "aware" instead of "naive" Python ``datetime`` objects from now
+  on, i.e. instances with or without the ``tzinfo`` attribute set.
   When no ``time_zone`` information is specified when creating a database
   connection or cursor, ``datetime`` objects will now use Coordinated
   Universal Time (UTC), like CrateDB is storing timestamp values in this
@@ -19,13 +51,11 @@ Unreleased
   This update is coming from a deprecation of Python's
   ``datetime.utcfromtimestamp()``, which is effectively also phasing out
   the use of "naive" timestamp objects in Python, in favor of using
-  timezone-aware objects, also to represent datetimes in UTC. It may be a
-  breaking change for some users of the library that don't expect to
-  receive "aware" ``datetime`` objects from now on.
-- Configured DB API interface attribute ``threadsafety = 1``, which signals
-  "Threads may share the module, but not connections."
-- Added ``error_trace`` to string representation of an Error to relay
-  server stacktraces into exception messages.
+  timezone-aware objects, also to represent datetimes in UTC.
+- Feature: Configured DB API interface attribute ``threadsafety = 1``,
+  which signals "Threads may share the module, but not connections."
+- Feature: Added ``error_trace`` to string representation of an Error,
+  to relay server stacktraces into exception messages.
 - Refactoring: The module namespace ``crate.client.test_util`` has been
   renamed to ``crate.testing.util``.
 - Error handling: At two spots in cursor / value converter handling, where
@@ -35,7 +65,15 @@ Unreleased
   namespaces" for the ``crate`` namespace package, see `PEP 420`_.
 
 
+.. note::
+
+    For learning about the transition to `sqlalchemy-cratedb`_,
+    we recommend to read the enumeration of necessary migration steps
+    at `Migrate from crate.client to sqlalchemy-cratedb`_.
+
+
 .. _Migrate from crate.client to sqlalchemy-cratedb: https://cratedb.com/docs/sqlalchemy-cratedb/migrate-from-crate-client.html
+.. _Package Discovery and Namespace Package » Finding namespace packages: https://setuptools.pypa.io/en/latest/userguide/package_discovery.html#namespace-packages
 .. _PEP 420: https://peps.python.org/pep-0420/
 .. _sqlalchemy-cratedb: https://pypi.org/project/sqlalchemy-cratedb/
 

{crate-1.0.0.dev2 → crate-2.0.0}/DEVELOP.rst

@@ -5,7 +5,7 @@ CrateDB Python developer guide
 Setup
 =====
 
-Optionally install Python package and project manager ``uv``,
+Optionally install Python package and project manager `uv`_,
 in order to significantly speed up the package installation::
 
     {apt,brew,pip,zypper} install uv
@@ -67,16 +67,11 @@ To inspect the whole list of test cases, run::
 
     bin/test --list-tests
 
-You can run the tests against multiple Python interpreters with `tox`_::
-
-    tox
-
-To do this, you will need the respective Python interpreter versions available
-on your ``$PATH``.
-
-To run against a single interpreter, you can also invoke::
-
-    tox -e py37
+The CI setup on GitHub Actions (GHA) provides a full test matrix covering
+relevant Python versions. You can invoke the software tests against a specific
+Python interpreter or multiple `Python versions`_ on your workstation using
+`uv`_, by supplying the ``--python`` command-line option, or by defining the
+`UV_PYTHON`_ environment variable prior to invoking ``source bootstrap.sh``.
 
 *Note*: Before running the tests, make sure to stop all CrateDB instances which
 are listening on the default CrateDB transport port to avoid side effects with
@@ -104,7 +99,7 @@ Renew certificates
 ==================
 
 For conducting TLS connectivity tests, there are a few X.509 certificates at
-`src/crate/client/pki/*.pem`_. In order to renew them, follow the instructions
+`tests/assets/pki/*.pem`_. In order to renew them, follow the instructions
 within the README file in this folder.
 
 
@@ -121,7 +116,7 @@ In the release branch:
 
 - Update ``__version__`` in ``src/crate/client/__init__.py``
 
-- Add a section for the new version in the ``CHANGES.txt`` file
+- Add a section for the new version in the ``CHANGES.rst`` file
 
 - Commit your changes with a message like "prepare release x.y.z"
 
@@ -130,7 +125,7 @@ In the release branch:
 - Create a tag by running ``./devtools/create_tag.sh``. This will trigger a
   Github action which releases the new version to PyPi.
 
-On master:
+On branch ``main``:
 
 - Update the release notes to reflect the release
 
@@ -168,12 +163,14 @@ nothing special you need to do to get the live docs to update.
 .. _@crate/docs: https://github.com/orgs/crate/teams/docs
 .. _buildout: https://pypi.python.org/pypi/zc.buildout
 .. _PyPI: https://pypi.python.org/pypi
+.. _Python versions: https://docs.astral.sh/uv/concepts/python-versions/
 .. _Read the Docs: http://readthedocs.org
 .. _ReStructuredText: http://docutils.sourceforge.net/rst.html
 .. _Sphinx: http://sphinx-doc.org/
-.. _src/crate/client/pki/*.pem: https://github.com/crate/crate-python/tree/master/src/crate/client/pki
-.. _tox: http://testrun.org/tox/latest/
+.. _tests/assets/pki/*.pem: https://github.com/crate/crate-python/tree/main/tests/assets/pki
 .. _twine: https://pypi.python.org/pypi/twine
 .. _useful command-line options for zope-testrunner: https://pypi.org/project/zope.testrunner/#some-useful-command-line-options-to-get-you-started
+.. _uv: https://docs.astral.sh/uv/
+.. _UV_PYTHON: https://docs.astral.sh/uv/configuration/environment/#uv_python
 .. _versions hosted on ReadTheDocs: https://readthedocs.org/projects/crate-python/versions/
 .. _zope.testrunner: https://pypi.org/project/zope.testrunner/

{crate-1.0.0.dev2 → crate-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: crate
-Version: 1.0.0.dev2
+Version: 2.0.0
 Summary: CrateDB Python Client
 Home-page: https://github.com/crate/crate-python
 Author: Crate.io
@@ -29,6 +29,7 @@ Requires-Python: >=3.6
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 License-File: NOTICE
+Requires-Dist: orjson<4
 Requires-Dist: urllib3
 Requires-Dist: verlib2
 Provides-Extra: doc
@@ -38,15 +39,27 @@ Provides-Extra: test
 Requires-Dist: backports.zoneinfo<1; python_version < "3.9" and extra == "test"
 Requires-Dist: certifi; extra == "test"
 Requires-Dist: createcoverage<2,>=1; extra == "test"
-Requires-Dist: mypy<1.14; extra == "test"
-Requires-Dist: poethepoet<0.30; extra == "test"
-Requires-Dist: ruff<0.8; extra == "test"
+Requires-Dist: mypy<1.15; extra == "test"
+Requires-Dist: poethepoet<0.33; extra == "test"
+Requires-Dist: ruff<0.10; extra == "test"
 Requires-Dist: stopit<2,>=1.1.2; extra == "test"
-Requires-Dist: tox<5,>=3; extra == "test"
 Requires-Dist: pytz; extra == "test"
 Requires-Dist: zc.customdoctests<2,>=1.0.1; extra == "test"
 Requires-Dist: zope.testing<6,>=4; extra == "test"
 Requires-Dist: zope.testrunner<7,>=5; extra == "test"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: platform
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 =====================
 CrateDB Python Client
@@ -56,7 +69,7 @@ CrateDB Python Client
     :target: https://github.com/crate/crate-python/actions?workflow=Tests
     :alt: Build status
 
-.. image:: https://codecov.io/gh/crate/crate-python/branch/master/graph/badge.svg
+.. image:: https://codecov.io/gh/crate/crate-python/branch/main/graph/badge.svg
     :target: https://app.codecov.io/gh/crate/crate-python
     :alt: Coverage
 

{crate-1.0.0.dev2 → crate-2.0.0}/README.rst

@@ -6,7 +6,7 @@ CrateDB Python Client
     :target: https://github.com/crate/crate-python/actions?workflow=Tests
     :alt: Build status
 
-.. image:: https://codecov.io/gh/crate/crate-python/branch/master/graph/badge.svg
+.. image:: https://codecov.io/gh/crate/crate-python/branch/main/graph/badge.svg
     :target: https://app.codecov.io/gh/crate/crate-python
     :alt: Coverage
 

{crate-1.0.0.dev2 → crate-2.0.0}/docs/by-example/http.rst

@@ -228,7 +228,7 @@ When connecting to non-CrateDB servers, the HttpClient will raise a ConnectionEr
     >>> http_client.server_infos(http_client._get_server())
     Traceback (most recent call last):
     ...
-    crate.client.exceptions.ProgrammingError: Invalid server response of content-type 'text/html; charset=UTF-8':
+    crate.client.exceptions.ProgrammingError: Invalid server response of content-type 'text/html':
     ...
     >>> http_client.close()
 

{crate-1.0.0.dev2 → crate-2.0.0}/docs/index.rst

@@ -174,12 +174,12 @@ The project is licensed under the terms of the Apache 2.0 license, like
 .. _CrateDB source: https://github.com/crate/crate
 .. _Create an issue: https://github.com/crate/crate-python/issues
 .. _Dask: https://en.wikipedia.org/wiki/Dask_(software)
-.. _development sandbox: https://github.com/crate/crate-python/blob/master/DEVELOP.rst
+.. _development sandbox: https://github.com/crate/crate-python/blob/main/DEVELOP.rst
 .. _cratedb-examples repository: https://github.com/crate/cratedb-examples
 .. _FIWARE QuantumLeap data historian: https://github.com/orchestracities/ngsi-timeseries-api
 .. _GeoJSON: https://geojson.org/
 .. _GeoJSON geometry objects: https://tools.ietf.org/html/rfc7946#section-3.1
-.. _LICENSE: https://github.com/crate/crate-python/blob/master/LICENSE
+.. _LICENSE: https://github.com/crate/crate-python/blob/main/LICENSE
 .. _managed on GitHub: https://github.com/crate/crate-python
 .. _migrate to sqlalchemy-cratedb: https://cratedb.com/docs/sqlalchemy-cratedb/migrate-from-crate-client.html
 .. _pandas: https://en.wikipedia.org/wiki/Pandas_(software)

{crate-1.0.0.dev2 → crate-2.0.0}/pyproject.toml

@@ -71,6 +71,13 @@ lint.per-file-ignores."tests/*" = [
   "S106",  # Possible hardcoded password assigned to argument: "password"
   "S311",  # Standard pseudo-random generators are not suitable for cryptographic purposes
 ]
+lint.per-file-ignores."src/crate/client/{connection.py,http.py}" = [
+  "A004",  # Import `ConnectionError` is shadowing a Python builtin
+  "A005",  # Import `ConnectionError` is shadowing a Python builtin
+]
+lint.per-file-ignores."tests/client/test_http.py" = [
+  "A004",  # Import `ConnectionError` is shadowing a Python builtin
+]
 
 
 # ===================

{crate-1.0.0.dev2 → crate-2.0.0}/setup.py

@@ -54,6 +54,7 @@ setup(
     packages=find_namespace_packages("src"),
     package_dir={"": "src"},
     install_requires=[
+        "orjson<4",
         "urllib3",
         "verlib2",
     ],
@@ -66,11 +67,10 @@ setup(
             'backports.zoneinfo<1; python_version<"3.9"',
             "certifi",
             "createcoverage>=1,<2",
-            "mypy<1.14",
-            "poethepoet<0.30",
-            "ruff<0.8",
+            "mypy<1.15",
+            "poethepoet<0.33",
+            "ruff<0.10",
             "stopit>=1.1.2,<2",
-            "tox>=3,<5",
             "pytz",
             "zc.customdoctests>=1.0.1,<2",
             "zope.testing>=4,<6",

{crate-1.0.0.dev2 → crate-2.0.0}/src/crate/client/__init__.py

@@ -29,8 +29,9 @@ __all__ = [
 
 # version string read from setup.py using a regex. Take care not to break the
 # regex!
-__version__ = "1.0.0.dev2"
+__version__ = "2.0.0"
 
+# codeql[py/unused-global-variable]
 apilevel = "2.0"
 threadsafety = 1
 paramstyle = "qmark"

{crate-1.0.0.dev2 → crate-2.0.0}/src/crate/client/http.py

@@ -21,22 +21,22 @@
 
 
 import calendar
+import datetime as dt
 import heapq
 import io
-import json
 import logging
 import os
 import re
 import socket
 import ssl
 import threading
+import typing as t
 from base64 import b64encode
-from datetime import date, datetime, timezone
 from decimal import Decimal
 from time import time
 from urllib.parse import urlparse
-from uuid import UUID
 
+import orjson
 import urllib3
 from urllib3 import connection_from_url
 from urllib3.connection import HTTPConnection
@@ -86,25 +86,53 @@ def super_len(o):
     return None
 
 
-class CrateJsonEncoder(json.JSONEncoder):
-    epoch_aware = datetime(1970, 1, 1, tzinfo=timezone.utc)
-    epoch_naive = datetime(1970, 1, 1)
-
-    def default(self, o):
-        if isinstance(o, (Decimal, UUID)):
-            return str(o)
-        if isinstance(o, datetime):
-            if o.tzinfo is not None:
-                delta = o - self.epoch_aware
-            else:
-                delta = o - self.epoch_naive
-            return int(
-                delta.microseconds / 1000.0
-                + (delta.seconds + delta.days * 24 * 3600) * 1000.0
-            )
-        if isinstance(o, date):
-            return calendar.timegm(o.timetuple()) * 1000
-        return json.JSONEncoder.default(self, o)
+epoch_aware = dt.datetime(1970, 1, 1, tzinfo=dt.timezone.utc)
+epoch_naive = dt.datetime(1970, 1, 1)
+
+
+def json_encoder(obj: t.Any) -> t.Union[int, str]:
+    """
+    Encoder function for orjson, with additional type support.
+
+    - Python's `Decimal` type will be serialized to `str`.
+    - Python's `dt.datetime` and `dt.date` types will be
+      serialized to `int` after converting to milliseconds
+      since epoch.
+
+    https://github.com/ijl/orjson#default
+    https://cratedb.com/docs/crate/reference/en/latest/general/ddl/data-types.html#type-timestamp
+    """
+    if isinstance(obj, Decimal):
+        return str(obj)
+    if isinstance(obj, dt.datetime):
+        if obj.tzinfo is not None:
+            delta = obj - epoch_aware
+        else:
+            delta = obj - epoch_naive
+        return int(
+            delta.microseconds / 1000.0
+            + (delta.seconds + delta.days * 24 * 3600) * 1000.0
+        )
+    if isinstance(obj, dt.date):
+        return calendar.timegm(obj.timetuple()) * 1000
+    raise TypeError
+
+
+def json_dumps(obj: t.Any) -> bytes:
+    """
+    Serialize to JSON format, using `orjson`, with additional type support.
+
+    https://github.com/ijl/orjson
+    """
+    return orjson.dumps(
+        obj,
+        default=json_encoder,
+        option=(
+            orjson.OPT_PASSTHROUGH_DATETIME
+            | orjson.OPT_NON_STR_KEYS
+            | orjson.OPT_SERIALIZE_NUMPY
+        ),
+    )
 
 
 class Server:
@@ -180,7 +208,7 @@ class Server:
 
 def _json_from_response(response):
     try:
-        return json.loads(response.data.decode("utf-8"))
+        return orjson.loads(response.data)
     except ValueError as ex:
         raise ProgrammingError(
             "Invalid server response of content-type '{}':\n{}".format(
@@ -223,7 +251,7 @@ def _raise_for_status_real(response):
     if response.status == 503:
         raise ConnectionError(message)
     if response.headers.get("content-type", "").startswith("application/json"):
-        data = json.loads(response.data.decode("utf-8"))
+        data = orjson.loads(response.data)
         error = data.get("error", {})
         error_trace = data.get("error_trace", None)
         if "results" in data:
@@ -323,7 +351,7 @@ def _update_pool_kwargs_for_ssl_minimum_version(server, kwargs):
             kwargs["ssl_minimum_version"] = ssl.TLSVersion.MINIMUM_SUPPORTED
 
 
-def _create_sql_payload(stmt, args, bulk_args):
+def _create_sql_payload(stmt, args, bulk_args) -> bytes:
     if not isinstance(stmt, str):
         raise ValueError("stmt is not a string")
     if args and bulk_args:
@@ -334,7 +362,7 @@ def _create_sql_payload(stmt, args, bulk_args):
         data["args"] = args
     if bulk_args:
         data["bulk_args"] = bulk_args
-    return json.dumps(data, cls=CrateJsonEncoder)
+    return json_dumps(data)
 
 
 def _get_socket_opts(
@@ -670,7 +698,7 @@ class Client:
         # if this is the last server raise exception, otherwise try next
         if not self._active_servers:
             raise ConnectionError(
-                ("No more Servers available, " "exception from last server: %s")
+                ("No more Servers available, exception from last server: %s")
                 % message
             )
 

{crate-1.0.0.dev2 → crate-2.0.0}/src/crate.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: crate
-Version: 1.0.0.dev2
+Version: 2.0.0
 Summary: CrateDB Python Client
 Home-page: https://github.com/crate/crate-python
 Author: Crate.io
@@ -29,6 +29,7 @@ Requires-Python: >=3.6
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 License-File: NOTICE
+Requires-Dist: orjson<4
 Requires-Dist: urllib3
 Requires-Dist: verlib2
 Provides-Extra: doc
@@ -38,15 +39,27 @@ Provides-Extra: test
 Requires-Dist: backports.zoneinfo<1; python_version < "3.9" and extra == "test"
 Requires-Dist: certifi; extra == "test"
 Requires-Dist: createcoverage<2,>=1; extra == "test"
-Requires-Dist: mypy<1.14; extra == "test"
-Requires-Dist: poethepoet<0.30; extra == "test"
-Requires-Dist: ruff<0.8; extra == "test"
+Requires-Dist: mypy<1.15; extra == "test"
+Requires-Dist: poethepoet<0.33; extra == "test"
+Requires-Dist: ruff<0.10; extra == "test"
 Requires-Dist: stopit<2,>=1.1.2; extra == "test"
-Requires-Dist: tox<5,>=3; extra == "test"
 Requires-Dist: pytz; extra == "test"
 Requires-Dist: zc.customdoctests<2,>=1.0.1; extra == "test"
 Requires-Dist: zope.testing<6,>=4; extra == "test"
 Requires-Dist: zope.testrunner<7,>=5; extra == "test"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: platform
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 =====================
 CrateDB Python Client
@@ -56,7 +69,7 @@ CrateDB Python Client
     :target: https://github.com/crate/crate-python/actions?workflow=Tests
     :alt: Build status
 
-.. image:: https://codecov.io/gh/crate/crate-python/branch/master/graph/badge.svg
+.. image:: https://codecov.io/gh/crate/crate-python/branch/main/graph/badge.svg
     :target: https://app.codecov.io/gh/crate/crate-python
     :alt: Coverage
 

{crate-1.0.0.dev2 → crate-2.0.0}/src/crate.egg-info/SOURCES.txt

@@ -1,4 +1,4 @@
-CHANGES.txt
+CHANGES.rst
 CONTRIBUTING.rst
 DEVELOP.rst
 LICENSE
@@ -8,7 +8,6 @@ README.rst
 pyproject.toml
 requirements.txt
 setup.py
-docs/backlog.rst
 docs/blobs.rst
 docs/conf.py
 docs/connect.rst
@@ -29,7 +28,6 @@ docs/by-example/cursor.rst
 docs/by-example/http.rst
 docs/by-example/https.rst
 docs/by-example/index.rst
-src/crate/__init__.py
 src/crate.egg-info/PKG-INFO
 src/crate.egg-info/SOURCES.txt
 src/crate.egg-info/dependency_links.txt

{crate-1.0.0.dev2 → crate-2.0.0}/src/crate.egg-info/requires.txt

@@ -1,3 +1,4 @@
+orjson<4
 urllib3
 verlib2
 
@@ -8,11 +9,10 @@ sphinx<9,>=3.5
 [test]
 certifi
 createcoverage<2,>=1
-mypy<1.14
-poethepoet<0.30
-ruff<0.8
+mypy<1.15
+poethepoet<0.33
+ruff<0.10
 stopit<2,>=1.1.2
-tox<5,>=3
 pytz
 zc.customdoctests<2,>=1.0.1
 zope.testing<6,>=4

crate-1.0.0.dev2/docs/backlog.rst

@@ -1,6 +0,0 @@
-:orphan:
-
-- Docs: Jupyter Notebook Example?
-- crate+pyodbc?
-- Add PyPy to CI
-- Check IronPython and JPython?