crate 2.1.0.dev0__tar.gz → 2.1.0.dev2__tar.gz

crate-2.1.0.dev2/.gitignore

@@ -0,0 +1,23 @@
+.venv*
+.coverage
+coverage.xml
+.idea/
+.installed.cfg
+.tox/
+*.DS_Store
+*.lock
+*.pyc
+bin/*
+!bin/test
+!bin/sphinx
+build/
+crate-python.iml
+crate.egg-info
+develop-eggs/
+dist/
+eggs/
+htmlcov/
+out/
+parts/
+tmp/
+env/

{crate-2.1.0.dev0 → crate-2.1.0.dev2}/CHANGES.rst

@@ -5,8 +5,16 @@ Changes for crate
 Unreleased
 ==========
 
-- Changed connection behaviour to fail early if the database cluster
-  does not respond
+- Exceptions from the BLOB API now include their full names.
+
+- Dropped support for Python versions earlier than 3.10 as they've reached
+  their end of life.
+
+- Parse path prefixes from server URLs and propagate them to all requests.
+
+- Fixed compatibility with ``urllib3-future``.
+
+- Added JWT token authentication.
 
 2025/01/30 2.0.0
 ================

crate-2.1.0.dev2/DEVELOP.rst

@@ -0,0 +1,130 @@
+==============================
+CrateDB Python developer guide
+==============================
+
+Setup
+=====
+
+Clone the repository::
+
+    git clone https://github.com/crate/crate-python
+    cd crate-python
+
+Setup a virtualenv and install the package::
+
+    python -m venv .venv
+    source .venv/bin/activate
+    python -m pip install --group dev --group docs -e .
+
+Or if using `uv`_::
+
+    uv venv .venv
+    source .venv/bin/activate
+    uv pip install --group dev --group docs -e .
+
+
+Running tests
+=============
+
+Ensure the virtualenv is active and run tests using `pytest`_::
+
+    python -m pytest
+
+
+See also:
+
+- `How to invoke pytest <https://docs.pytest.org/en/stable/how-to/usage.html>` for more information.
+
+
+Formatting and linting code
+===========================
+
+Use `ruff`_ for code formatting and linting::
+
+    ruff format --check .
+    ruff check .
+
+
+Use ``mypy`` for type checking::
+
+    mypy
+
+Renew certificates
+==================
+
+For conducting TLS connectivity tests, there are a few X.509 certificates at
+`tests/assets/pki/*.pem`_. In order to renew them, follow the instructions
+within the README file in this folder.
+
+
+Preparing a release
+===================
+
+To create a new release, you must:
+
+- Backport your bug fixes to the latest stable branch x.y (e.g. 0.19)
+
+- For new features, create a new stable branch x.(y+1) (e.g. 0.20)
+
+In the release branch:
+
+- Add a section for the new version in the ``CHANGES.rst`` file
+
+- Commit your changes with a message like "Release x.y.z"
+
+- Push to origin/<release_branch>
+
+- Create a tag by running ``git tag -s <version>`` and push it ``git push --tags``.
+  This will trigger a Github action which releases the new version to PyPI.
+
+- Announce the new release on the `GitHub Releases`_ page.
+
+On branch ``main``:
+
+- Update the release notes to reflect the release
+
+Next:
+
+- Archive docs for old releases (see section below)
+
+Archiving docs versions
+-----------------------
+
+Check the `versions hosted on ReadTheDocs`_.
+
+We should only be hosting the docs for `latest`, `stable`, and the most recent
+patch versions for the last two minor releases.
+
+To make changes to the RTD configuration (e.g., to activate or deactivate a
+release version), please contact the `@crate/docs`_ team.
+
+Writing documentation
+=====================
+
+The docs live under the ``docs`` directory.
+
+The docs are written with ReStructuredText_ and processed with Sphinx_.
+
+Build the docs by running::
+
+    ./bin/sphinx
+
+The output can then be found in the ``out/html`` directory.
+
+The docs are automatically built from Git by `Read the Docs`_ and there is
+nothing special you need to do to get the live docs to update.
+
+.. _@crate/docs: https://github.com/orgs/crate/teams/docs
+.. _GitHub Releases: https://github.com/crate/crate-python/releases
+.. _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/
+.. _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/
+.. _pytest: https://docs.pytest.org/en/stable/

{crate-2.1.0.dev0 → crate-2.1.0.dev2}/PKG-INFO

@@ -1,66 +1,33 @@
 Metadata-Version: 2.4
 Name: crate
-Version: 2.1.0.dev0
+Version: 2.1.0.dev2
 Summary: CrateDB Python Client
-Home-page: https://github.com/crate/crate-python
-Author: Crate.io
-Author-email: office@crate.io
-License: Apache License 2.0
-Keywords: cratedb db api dbapi database sql http rdbms olap
-Platform: any
+Author-email: "Crate.io" <office@crate.io>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Programming Language :: SQL
 Classifier: Topic :: Database
-Requires-Python: >=3.6
-Description-Content-Type: text/x-rst
-License-File: LICENSE
-License-File: NOTICE
-Requires-Dist: orjson<4
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Requires-Dist: orjson
 Requires-Dist: urllib3
 Requires-Dist: verlib2
-Provides-Extra: doc
-Requires-Dist: crate-docs-theme>=0.26.5; extra == "doc"
-Requires-Dist: sphinx<9,>=3.5; extra == "doc"
-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.16; extra == "test"
-Requires-Dist: poethepoet<1; extra == "test"
-Requires-Dist: ruff<0.12; extra == "test"
-Requires-Dist: stopit<2,>=1.1.2; 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<8,>=5; extra == "test"
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: keywords
-Dynamic: license
-Dynamic: license-file
-Dynamic: platform
-Dynamic: provides-extra
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
+Description-Content-Type: text/x-rst
 
 =====================
 CrateDB Python Client

crate-2.1.0.dev2/docs/.gitignore

@@ -0,0 +1 @@
+.crate-docs

crate-2.1.0.dev2/docs/Makefile

@@ -0,0 +1,159 @@
+# Licensed to Crate (https://crate.io) 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.
+
+
+# =============================================================================
+# Crate Docs
+# =============================================================================
+
+# The Crate Docs project provides a common set of tools for producing the
+# Crate.io documentation. See <https://github.com/crate/crate-docs/> for more
+# information.
+
+# This file is taken from the demo Sphinx project available at
+# <https://github.com/crate/crate-docs/blob/main/docs>. This demo docs project
+# provides a reference implementation that should be copied for all Sphinx
+# projects at Crate.io.
+
+# The Crate Docs build system works by centralizing its core components in the
+# `crate-docs` repository. At build time, this Makefile creates a copy of the
+# this project under the `.crate-docs` directory. This Makefile is an interface
+# for those core components.
+
+
+# Upgraded instructions
+# -----------------------------------------------------------------------------
+
+# You must pin your Sphinx project to a specific version of the Crate Docs
+# project. You can do this by editing the `build.json` file. Change the JSON
+# `message` value to the desired release number. A list of releases is
+# available at <https://github.com/crate/crate-docs/releases>.
+
+# Although care has been taken to restrict changes to the core components, you
+# may occasionally need to update your project to match the reference
+# implementation. Check the release notes for any special instructions.
+
+
+# Project-specific customization
+# =============================================================================
+
+# If you want to customize the build system for your Sphinx project, add lines
+# to this section.
+
+
+# Build system integration
+# =============================================================================
+
+# This is a boilerplate section is required for integration with the Crate Docs
+# build system. All Sphinx projects using a the same Crate Docs version
+# should have exactly the same boilerplate.
+
+# IF YOU ARE EDITING THIS FILE IN A REAL SPHINX PROJECT, YOU SHOULD NOT MAKE
+# ANY CHANGES TO THIS SECTION.
+
+# If you want to make changes to the boilerplate, please make a pull request on
+# the demo Sphinx project in the Crate Docs repository available at
+# <https://github.com/crate/crate-docs/blob/main/docs>.
+
+.EXPORT_ALL_VARIABLES:
+
+DOCS_DIR      := docs
+TOP_DIR       := ..
+BUILD_JSON    := build.json
+BUILD_REPO    := https://github.com/crate/crate-docs.git
+LATEST_BUILD  := https://github.com/crate/crate-docs/releases/latest
+CLONE_DIR     := .crate-docs
+SRC_DIR       := $(CLONE_DIR)/common-build
+SELF_SRC      := $(TOP_DIR)/common-build
+SELF_MAKEFILE := $(SELF_SRC)/rules.mk
+SRC_MAKE      := $(MAKE) -f $(SRC_DIR)/rules.mk
+
+# Parse the JSON file
+BUILD_VERSION := $(shell cat $(BUILD_JSON) | \
+    python3 -c 'import json, sys; print(json.load(sys.stdin)["message"])')
+
+ifeq ($(BUILD_VERSION),)
+$(error No build version specified in `$(BUILD_JSON)`.)
+endif
+
+# This is a non-essential check so we timeout after only two seconds so as not
+# to frustrate the user when there are network issues
+LATEST_VERSION := $(shell curl -sI --connect-timeout 2 '$(LATEST_BUILD)' | \
+    grep -i 'Location:' | grep -Eoh '[^/]+$$')
+
+# Skip if no version could be determined (i.e., because of a network error)
+ifneq ($(LATEST_VERSION),)
+# Only issue a warning if there is a version mismatch
+ifneq ($(BUILD_VERSION),$(LATEST_VERSION))
+define version_warning
+You are using Crate Docs version $(BUILD_VERSION), however version \
+$(LATEST_VERSION) is available. You should consider upgrading. Follow the \
+instructions in `Makefile` and then run `make reset`.
+endef
+endif
+endif
+
+# Default rule
+.PHONY: help
+help: $(CLONE_DIR)
+	@ $(MAKE) version-warn
+	@ $(SRC_MAKE) $@
+
+.PHONY: version-warn
+version-warn:
+	@ # Because version numbers may vary in length, we must wrap the warning
+	@ # message at run time to be sure of correct output
+	@ if test -n '$(version_warning)'; then \
+	      printf '\033[33m'; \
+	      echo '$(version_warning)' | fold -w 79 -s; \
+	      printf '\033[00m\n'; \
+	  fi
+
+ifneq ($(wildcard $(SELF_MAKEFILE)),)
+# The project detects itself and fakes an install of its own core build rules
+# so that it can test itself
+$(CLONE_DIR):
+	@ printf '\033[1mInstalling the build system...\033[00m\n'
+	@ mkdir -p $@
+	@ cp -R $(SELF_SRC) $(SRC_DIR)
+	@ printf 'Created: $(CLONE_DIR)\n'
+else
+# All other projects install a versioned copy of the core build rules
+$(CLONE_DIR):
+	@ printf '\033[1mInstalling the build system...\033[00m\n'
+	@ git clone --depth=1 -c advice.detachedHead=false \
+	    --branch=$(BUILD_VERSION) $(BUILD_REPO) $(CLONE_DIR)
+	@ printf 'Created: $(CLONE_DIR)\n'
+endif
+
+# Don't pass through this target
+.PHONY: Makefile
+Makefile:
+
+# By default, pass targets through to the core build rules
+.PHONY:
+%: $(CLONE_DIR)
+	@ $(MAKE) version-warn
+	@ $(SRC_MAKE) $@
+
+.PHONY: reset
+reset:
+	@ printf '\033[1mResetting the build system...\033[00m\n'
+	@ rm -rf $(CLONE_DIR)
+	@ printf 'Removed: $(CLONE_DIR)\n'

{crate-2.1.0.dev0 → crate-2.1.0.dev2}/docs/blobs.rst

@@ -8,11 +8,6 @@ The CrateDB Python client library provides full access to the powerful
 :ref:`blob storage capabilities <crate-reference:blob_support>` of your
 CrateDB cluster.
 
-.. rubric:: Table of contents
-
-.. contents::
-   :local:
-
 Get a blob container
 ====================
 

crate-2.1.0.dev2/docs/build.json

@@ -0,0 +1,5 @@
+{
+  "schemaVersion": 1,
+  "label": "docs build",
+  "message": "2.1.5"
+}

{crate-2.1.0.dev0 → crate-2.1.0.dev2}/docs/by-example/client.rst

@@ -7,12 +7,6 @@ Python. This section of the documentation outlines different methods to connect
 to the database cluster, as well as how to run basic inquiries to the database,
 and closing the connection again.
 
-.. rubric:: Table of Contents
-
-.. contents::
-   :local:
-
-
 Connect to a database
 =====================
 
@@ -31,12 +25,16 @@ replication. In order for clients to make use of this property it is
 recommended to specify all hosts of the cluster. This way if a server does not
 respond, the request is automatically routed to the next server:
 
-    >>> invalid_host = 'http://not_responding_host:4200'
+    >>> invalid_host = 'http://127.0.0.1:4201'
     >>> connection = client.connect([invalid_host, crate_host])
     >>> connection.close()
 
-If no ``servers`` are supplied to the ``connect`` method, the default address
-``http://127.0.0.1:4200`` is used.
+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 the option ``error_trace`` is set to ``True``, the client will print a whole
 traceback if a server error occurs:
@@ -51,7 +49,7 @@ It's possible to define a default timeout value in seconds for all servers
 using the optional parameter ``timeout``. In this case, it will serve as a
 total timeout (connect and read):
 
-    >>> connection = client.connect([crate_host, invalid_host], timeout=5)
+    >>> connection = client.connect([crate_host, invalid_host], timeout=1)
     >>> connection.close()
 
 If you want to adjust the connect- vs. read-timeout values individually,
@@ -60,7 +58,7 @@ please use the ``urllib3.Timeout`` object like:
     >>> import urllib3
     >>> connection = client.connect(
     ...     [crate_host, invalid_host],
-    ...     timeout=urllib3.Timeout(connect=5, read=None))
+    ...     timeout=urllib3.Timeout(connect=1, read=None))
     >>> connection.close()
 
 Authentication

{crate-2.1.0.dev0 → crate-2.1.0.dev2}/docs/by-example/connection.rst

@@ -9,12 +9,6 @@ The examples use an instance of ``ClientMocked`` instead of a real ``Client``
 instance. This allows us to verify the examples without needing a real database
 connection.
 
-.. rubric:: Table of Contents
-
-.. contents::
-   :local:
-
-
 connect()
 =========
 

{crate-2.1.0.dev0 → crate-2.1.0.dev2}/docs/by-example/cursor.rst

@@ -8,12 +8,6 @@ behaviors of the ``crate.client.cursor.Cursor`` object.
 The example code uses ``ClientMocked`` and ``set_next_response`` for
 demonstration purposes, so they don't need a real database connection.
 
-.. rubric:: Table of Contents
-
-.. contents::
-   :local:
-
-
 Introduction
 ============
 

{crate-2.1.0.dev0 → crate-2.1.0.dev2}/docs/by-example/http.rst

@@ -2,12 +2,6 @@
 HTTP client
 ===========
 
-.. rubric:: Table of Contents
-
-.. contents::
-   :local:
-
-
 Introduction
 ============
 
@@ -40,23 +34,23 @@ If no ``server`` argument (or no argument at all) is passed, the default one
 
 When using a list of servers, the servers are selected by round-robin:
 
-    >>> invalid_host = "invalid_host:9999"
-    >>> even_more_invalid_host = "even_more_invalid_host:9999"
-    >>> http_client = HttpClient([crate_host, invalid_host, even_more_invalid_host], timeout=0.3)
+    >>> invalid_host1 = "192.0.2.1:9999"
+    >>> invalid_host2 = "192.0.2.2:9999"
+    >>> http_client = HttpClient([crate_host, invalid_host1, invalid_host2], timeout=0.3)
     >>> http_client._get_server()
     'http://127.0.0.1:44209'
 
     >>> http_client._get_server()
-    'http://invalid_host:9999'
+    'http://192.0.2.1:9999'
 
     >>> http_client._get_server()
-    'http://even_more_invalid_host:9999'
+    'http://192.0.2.2:9999'
 
     >>> http_client.close()
 
 Servers with connection errors will be removed from the active server list:
 
-    >>> http_client = HttpClient([invalid_host, even_more_invalid_host, crate_host], timeout=0.3)
+    >>> http_client = HttpClient([invalid_host1, invalid_host2, crate_host], timeout=0.3)
     >>> result = http_client.sql('select name from locations')
     >>> http_client._active_servers
     ['http://127.0.0.1:44209']
@@ -70,19 +64,17 @@ sleep after the first request::
     >>> import time; time.sleep(1)
     >>> server = http_client._get_server()
     >>> http_client._active_servers
-    ['http://invalid_host:9999',
-     'http://even_more_invalid_host:9999',
-     'http://127.0.0.1:44209']
+    ['http://127.0.0.1:44209', 'http://192.0.2.2:9999', 'http://192.0.2.1:9999']
     >>> http_client.close()
 
 If no active servers are available and the retry interval is not reached, just use the oldest
 inactive one:
 
-    >>> http_client = HttpClient([invalid_host, even_more_invalid_host, crate_host], timeout=0.3)
+    >>> http_client = HttpClient([invalid_host1, invalid_host2, crate_host], timeout=0.3)
     >>> result = http_client.sql('select name from locations')
     >>> http_client._active_servers = []
     >>> http_client._get_server()
-    'http://invalid_host:9999'
+    'http://192.0.2.1:9999'
     >>> http_client.close()
 
 SQL Statements
@@ -124,7 +116,7 @@ Trying to get a non-existing blob throws an exception:
     >>> http_client.blob_get('myfiles', '041f06fd774092478d450774f5ba30c5da78acc8')
     Traceback (most recent call last):
     ...
-    crate.client.exceptions.DigestNotFoundException: myfiles/041f06fd774092478d450774f5ba30c5da78acc8
+    crate.client.exceptions.DigestNotFoundException: DigestNotFoundException('myfiles/041f06fd774092478d450774f5ba30c5da78acc8')
 
 Creating a new blob - this method returns ``True`` if the blob was newly created:
 
@@ -179,7 +171,7 @@ Uploading a blob to a table with disabled blob support throws an exception:
     ...     'locations', '040f06fd774092478d450774f5ba30c5da78acc8', f)
     Traceback (most recent call last):
     ...
-    crate.client.exceptions.BlobLocationNotFoundException: locations/040f06fd774092478d450774f5ba30c5da78acc8
+    crate.client.exceptions.BlobLocationNotFoundException: BlobLocationNotFoundException('locations/040f06fd774092478d450774f5ba30c5da78acc8')
 
     >>> http_client.close()
     >>> f.close()