crate 2.0.0.dev0__py3-none-any.whl

crate/client/__init__.py

@@ -0,0 +1,37 @@
+# -*- 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",
+]
+
+# version string read from setup.py using a regex. Take care not to break the
+# regex!
+__version__ = "2.0.0.dev0"
+
+# codeql[py/unused-global-variable]
+apilevel = "2.0"
+threadsafety = 1
+paramstyle = "qmark"

crate/client/_pep440.py

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

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)

crate/client/connection.py

@@ -0,0 +1,221 @@
+# -*- 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 verlib2 import Version
+
+from .blob import BlobContainer
+from .cursor import Cursor
+from .exceptions import ConnectionError, ProgrammingError
+from .http import Client
+
+
+class Connection:
+    def __init__(
+        self,
+        servers=None,
+        timeout=None,
+        backoff_factor=0,
+        client=None,
+        verify_ssl_cert=True,
+        ca_cert=None,
+        error_trace=False,
+        cert_file=None,
+        key_file=None,
+        ssl_relax_minimum_version=False,
+        username=None,
+        password=None,
+        schema=None,
+        pool_size=None,
+        socket_keepalive=True,
+        socket_tcp_keepidle=None,
+        socket_tcp_keepintvl=None,
+        socket_tcp_keepcnt=None,
+        converter=None,
+        time_zone=None,
+    ):
+        """
+        :param servers:
+            either a string in the form of '<hostname>:<port>'
+            or a list of servers in the form of ['<hostname>:<port>', '...']
+        :param timeout:
+            (optional)
+            define the retry timeout for unreachable servers in seconds
+        :param backoff_factor:
+            (optional)
+            define the retry interval for unreachable servers in seconds
+        :param client:
+            (optional - for testing)
+            client used to communicate with crate.
+        :param verify_ssl_cert:
+            if set to ``False``, disable SSL server certificate verification.
+            defaults to ``True``
+        :param ca_cert:
+            a path to a CA certificate to use when verifying the SSL server
+            certificate.
+        :param error_trace:
+            if set to ``True`` return a whole stacktrace of any server error if
+            one occurs
+        :param cert_file:
+            a path to the client certificate to present to the server.
+        :param key_file:
+            a path to the client key to use when communicating with the server.
+        :param username:
+            the username in the database.
+        :param password:
+            the password of the user in the database.
+        :param pool_size:
+            (optional)
+            Number of connections to save that can be reused.
+            More than 1 is useful in multithreaded situations.
+        :param socket_keepalive:
+            (optional, defaults to ``True``)
+            Enable TCP keepalive on socket level.
+        :param socket_tcp_keepidle:
+            (optional)
+            Set the ``TCP_KEEPIDLE`` socket option, which overrides
+            ``net.ipv4.tcp_keepalive_time`` kernel setting if ``socket_keepalive``
+            is ``True``.
+        :param socket_tcp_keepintvl:
+            (optional)
+            Set the ``TCP_KEEPINTVL`` socket option, which overrides
+            ``net.ipv4.tcp_keepalive_intvl`` kernel setting if ``socket_keepalive``
+            is ``True``.
+        :param socket_tcp_keepcnt:
+            (optional)
+            Set the ``TCP_KEEPCNT`` socket option, which overrides
+            ``net.ipv4.tcp_keepalive_probes`` kernel setting if ``socket_keepalive``
+            is ``True``.
+        :param converter:
+            (optional, defaults to ``None``)
+            A `Converter` object to propagate to newly created `Cursor` objects.
+        :param time_zone:
+            (optional, defaults to ``None``)
+            A time zone specifier used for returning `TIMESTAMP` types as
+            timezone-aware native Python `datetime` objects.
+
+            Different data types are supported. Available options are:
+
+            - ``datetime.timezone.utc``
+            - ``datetime.timezone(datetime.timedelta(hours=7), name="MST")``
+            - ``pytz.timezone("Australia/Sydney")``
+            - ``zoneinfo.ZoneInfo("Australia/Sydney")``
+            - ``+0530`` (UTC offset in string format)
+
+            The driver always returns timezone-"aware" `datetime` objects,
+            with their `tzinfo` attribute set.
+
+            When `time_zone` is `None`, the returned `datetime` objects are
+            using Coordinated Universal Time (UTC), because CrateDB is storing
+            timestamp values in this format.
+
+            When `time_zone` is given, the timestamp values will be transparently
+            converted from UTC to use the given time zone.
+        """  # noqa: E501
+
+        self._converter = converter
+        self.time_zone = time_zone
+
+        if client:
+            self.client = client
+        else:
+            self.client = Client(
+                servers,
+                timeout=timeout,
+                backoff_factor=backoff_factor,
+                verify_ssl_cert=verify_ssl_cert,
+                ca_cert=ca_cert,
+                error_trace=error_trace,
+                cert_file=cert_file,
+                key_file=key_file,
+                ssl_relax_minimum_version=ssl_relax_minimum_version,
+                username=username,
+                password=password,
+                schema=schema,
+                pool_size=pool_size,
+                socket_keepalive=socket_keepalive,
+                socket_tcp_keepidle=socket_tcp_keepidle,
+                socket_tcp_keepintvl=socket_tcp_keepintvl,
+                socket_tcp_keepcnt=socket_tcp_keepcnt,
+            )
+        self.lowest_server_version = self._lowest_server_version()
+        self._closed = False
+
+    def cursor(self, **kwargs) -> Cursor:
+        """
+        Return a new Cursor Object using the connection.
+        """
+        converter = kwargs.pop("converter", self._converter)
+        time_zone = kwargs.pop("time_zone", self.time_zone)
+        if not self._closed:
+            return Cursor(
+                connection=self,
+                converter=converter,
+                time_zone=time_zone,
+            )
+        else:
+            raise ProgrammingError("Connection closed")
+
+    def close(self):
+        """
+        Close the connection now
+        """
+        self._closed = True
+        self.client.close()
+
+    def commit(self):
+        """
+        Transactions are not supported, so ``commit`` is not implemented.
+        """
+        if self._closed:
+            raise ProgrammingError("Connection closed")
+
+    def get_blob_container(self, container_name):
+        """Retrieve a BlobContainer for `container_name`
+
+        :param container_name: the name of the BLOB container.
+        :returns: a :class:ContainerObject
+        """
+        return BlobContainer(container_name, self)
+
+    def _lowest_server_version(self):
+        lowest = None
+        for server in self.client.active_servers:
+            try:
+                _, _, version = self.client.server_infos(server)
+                version = Version(version)
+            except (ValueError, ConnectionError):
+                continue
+            if not lowest or version < lowest:
+                lowest = version
+        return lowest or Version("0.0.0")
+
+    def __repr__(self):
+        return "<Connection {0}>".format(repr(self.client))
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *excs):
+        self.close()
+
+
+# For backwards compatibility and not to break existing imports
+connect = Connection

crate/client/converter.py

@@ -0,0 +1,143 @@
+# -*- 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.
+"""
+Machinery for converting CrateDB database types to native Python data types.
+
+https://crate.io/docs/crate/reference/en/latest/interfaces/http.html#column-types
+"""
+
+import datetime as dt
+import ipaddress
+from copy import deepcopy
+from enum import Enum
+from typing import Any, Callable, Dict, List, Optional, Union
+
+ConverterFunction = Callable[[Optional[Any]], Optional[Any]]
+ColTypesDefinition = Union[int, List[Union[int, "ColTypesDefinition"]]]
+
+
+def _to_ipaddress(
+    value: Optional[str],
+) -> Optional[Union[ipaddress.IPv4Address, ipaddress.IPv6Address]]:
+    """
+    https://docs.python.org/3/library/ipaddress.html
+    """
+    if value is None:
+        return None
+    return ipaddress.ip_address(value)
+
+
+def _to_datetime(value: Optional[float]) -> Optional[dt.datetime]:
+    """
+    https://docs.python.org/3/library/datetime.html
+    """
+    if value is None:
+        return None
+    return dt.datetime.fromtimestamp(value / 1e3, tz=dt.timezone.utc)
+
+
+def _to_default(value: Optional[Any]) -> Optional[Any]:
+    return value
+
+
+# Data type identifiers defined by the CrateDB HTTP interface.
+# https://crate.io/docs/crate/reference/en/latest/interfaces/http.html#column-types
+class DataType(Enum):
+    NULL = 0
+    NOT_SUPPORTED = 1
+    CHAR = 2
+    BOOLEAN = 3
+    TEXT = 4
+    IP = 5
+    DOUBLE = 6
+    REAL = 7
+    SMALLINT = 8
+    INTEGER = 9
+    BIGINT = 10
+    TIMESTAMP_WITH_TZ = 11
+    OBJECT = 12
+    GEOPOINT = 13
+    GEOSHAPE = 14
+    TIMESTAMP_WITHOUT_TZ = 15
+    UNCHECKED_OBJECT = 16
+    REGPROC = 19
+    TIME = 20
+    OIDVECTOR = 21
+    NUMERIC = 22
+    REGCLASS = 23
+    DATE = 24
+    BIT = 25
+    JSON = 26
+    CHARACTER = 27
+    ARRAY = 100
+
+
+ConverterMapping = Dict[DataType, ConverterFunction]
+
+
+# Map data type identifier to converter function.
+_DEFAULT_CONVERTERS: ConverterMapping = {
+    DataType.IP: _to_ipaddress,
+    DataType.TIMESTAMP_WITH_TZ: _to_datetime,
+    DataType.TIMESTAMP_WITHOUT_TZ: _to_datetime,
+}
+
+
+class Converter:
+    def __init__(
+        self,
+        mappings: Optional[ConverterMapping] = None,
+        default: ConverterFunction = _to_default,
+    ) -> None:
+        self._mappings = mappings or {}
+        self._default = default
+
+    def get(self, type_: ColTypesDefinition) -> ConverterFunction:
+        if isinstance(type_, int):
+            return self._mappings.get(DataType(type_), self._default)
+        type_, inner_type = type_
+        if DataType(type_) is not DataType.ARRAY:
+            raise ValueError(
+                f"Data type {type_} is not implemented as collection type"
+            )
+
+        inner_convert = self.get(inner_type)
+
+        def convert(value: Any) -> Optional[List[Any]]:
+            if value is None:
+                return None
+            return [inner_convert(x) for x in value]
+
+        return convert
+
+    def set(self, type_: DataType, converter: ConverterFunction):
+        self._mappings[type_] = converter
+
+
+class DefaultTypeConverter(Converter):
+    def __init__(
+        self, more_mappings: Optional[ConverterMapping] = None
+    ) -> None:
+        mappings: ConverterMapping = {}
+        mappings.update(deepcopy(_DEFAULT_CONVERTERS))
+        if more_mappings:
+            mappings.update(deepcopy(more_mappings))
+        super().__init__(mappings=mappings, default=_to_default)