crate 1.0.0.dev1__py3-none-any.whl → 1.0.1__py3-none-any.whl

crate/client/__init__.py

@@ -23,14 +23,15 @@ from .connection import Connection as connect
 from .exceptions import Error
 
 __all__ = [
-    connect,
-    Error,
+    "connect",
+    "Error",
 ]
 
 # version string read from setup.py using a regex. Take care not to break the
 # regex!
-__version__ = "1.0.0dev1"
+__version__ = "1.0.1"
 
+# codeql[py/unused-global-variable]
 apilevel = "2.0"
 threadsafety = 1
 paramstyle = "qmark"

crate/client/blob.py

@@ -22,8 +22,8 @@
 import hashlib
 
 
-class BlobContainer(object):
-    """ class that represents a blob collection in crate.
+class BlobContainer:
+    """class that represents a blob collection in crate.
 
     can be used to download, upload and delete blobs
     """
@@ -34,7 +34,7 @@ class BlobContainer(object):
 
     def _compute_digest(self, f):
         f.seek(0)
-        m = hashlib.sha1()
+        m = hashlib.sha1()  # noqa: S324
         while True:
             d = f.read(1024 * 32)
             if not d:
@@ -64,8 +64,9 @@ class BlobContainer(object):
         else:
             actual_digest = self._compute_digest(f)
 
-        created = self.conn.client.blob_put(self.container_name,
-                                            actual_digest, f)
+        created = self.conn.client.blob_put(
+            self.container_name, actual_digest, f
+        )
         if digest:
             return created
         return actual_digest
@@ -78,8 +79,9 @@ class BlobContainer(object):
         :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)
+        return self.conn.client.blob_get(
+            self.container_name, digest, chunk_size
+        )
 
     def delete(self, digest):
         """

crate/client/connection.py

@@ -19,37 +19,38 @@
 # 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 ProgrammingError, ConnectionError
+from .exceptions import ConnectionError, ProgrammingError
 from .http import Client
-from .blob import BlobContainer
-from verlib2 import Version
 
 
-class Connection(object):
-
-    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,
-                 ):
+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>'
@@ -118,12 +119,16 @@ class Connection(object):
             - ``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
-            "naive", without any `tzinfo`, converted using ``datetime.utcfromtimestamp(...)``.
+            using Coordinated Universal Time (UTC), because CrateDB is storing
+            timestamp values in this format.
 
-            When `time_zone` is given, the returned `datetime` objects are "aware",
-            with `tzinfo` set, converted using ``datetime.fromtimestamp(..., tz=...)``.
-        """
+            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
@@ -131,24 +136,25 @@ class Connection(object):
         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.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
 
@@ -182,7 +188,7 @@ class Connection(object):
             raise ProgrammingError("Connection closed")
 
     def get_blob_container(self, container_name):
-        """ Retrieve a BlobContainer for `container_name`
+        """Retrieve a BlobContainer for `container_name`
 
         :param container_name: the name of the BLOB container.
         :returns: a :class:ContainerObject
@@ -199,10 +205,10 @@ class Connection(object):
                 continue
             if not lowest or version < lowest:
                 lowest = version
-        return lowest or Version('0.0.0')
+        return lowest or Version("0.0.0")
 
     def __repr__(self):
-        return '<Connection {0}>'.format(repr(self.client))
+        return "<Connection {0}>".format(repr(self.client))
 
     def __enter__(self):
         return self

crate/client/converter.py

@@ -23,9 +23,10 @@ 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 datetime import datetime
 from enum import Enum
 from typing import Any, Callable, Dict, List, Optional, Union
 
@@ -33,7 +34,9 @@ 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]]:
+def _to_ipaddress(
+    value: Optional[str],
+) -> Optional[Union[ipaddress.IPv4Address, ipaddress.IPv6Address]]:
     """
     https://docs.python.org/3/library/ipaddress.html
     """
@@ -42,20 +45,20 @@ def _to_ipaddress(value: Optional[str]) -> Optional[Union[ipaddress.IPv4Address,
     return ipaddress.ip_address(value)
 
 
-def _to_datetime(value: Optional[float]) -> Optional[datetime]:
+def _to_datetime(value: Optional[float]) -> Optional[dt.datetime]:
     """
     https://docs.python.org/3/library/datetime.html
     """
     if value is None:
         return None
-    return datetime.utcfromtimestamp(value / 1e3)
+    return dt.datetime.fromtimestamp(value / 1e3, tz=dt.timezone.utc)
 
 
 def _to_default(value: Optional[Any]) -> Optional[Any]:
     return value
 
 
-# Symbolic aliases for the numeric data type identifiers defined by the CrateDB HTTP interface.
+# 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
@@ -112,7 +115,9 @@ class Converter:
             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")
+            raise ValueError(
+                f"Data type {type_} is not implemented as collection type"
+            )
 
         inner_convert = self.get(inner_type)
 
@@ -128,11 +133,11 @@ class Converter:
 
 
 class DefaultTypeConverter(Converter):
-    def __init__(self, more_mappings: Optional[ConverterMapping] = None) -> None:
+    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
-        )
+        super().__init__(mappings=mappings, default=_to_default)

crate/client/cursor.py

@@ -18,21 +18,20 @@
 # 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 datetime import datetime, timedelta, timezone
-
-from .converter import DataType
-import warnings
 import typing as t
+import warnings
+from datetime import datetime, timedelta, timezone
 
-from .converter import Converter
+from .converter import Converter, DataType
 from .exceptions import ProgrammingError
 
 
-class Cursor(object):
+class Cursor:
     """
     not thread-safe by intention
     should not be shared between different threads
     """
+
     lastrowid = None  # currently not supported
 
     def __init__(self, connection, converter: Converter, **kwargs):
@@ -40,7 +39,7 @@ class Cursor(object):
         self.connection = connection
         self._converter = converter
         self._closed = False
-        self._result = None
+        self._result: t.Dict[str, t.Any] = {}
         self.rows = None
         self._time_zone = None
         self.time_zone = kwargs.get("time_zone")
@@ -55,8 +54,9 @@ class Cursor(object):
         if self._closed:
             raise ProgrammingError("Cursor closed")
 
-        self._result = self.connection.client.sql(sql, parameters,
-                                                  bulk_parameters)
+        self._result = self.connection.client.sql(
+            sql, parameters, bulk_parameters
+        )
         if "rows" in self._result:
             if self._converter is None:
                 self.rows = iter(self._result["rows"])
@@ -73,9 +73,9 @@ class Cursor(object):
         durations = []
         self.execute(sql, bulk_parameters=seq_of_parameters)
 
-        for result in self._result.get('results', []):
-            if result.get('rowcount') > -1:
-                row_counts.append(result.get('rowcount'))
+        for result in self._result.get("results", []):
+            if result.get("rowcount") > -1:
+                row_counts.append(result.get("rowcount"))
         if self.duration > -1:
             durations.append(self.duration)
 
@@ -85,7 +85,7 @@ class Cursor(object):
             "rows": [],
             "cols": self._result.get("cols", []),
             "col_types": self._result.get("col_types", []),
-            "results": self._result.get("results")
+            "results": self._result.get("results"),
         }
         if self._converter is None:
             self.rows = iter(self._result["rows"])
@@ -112,7 +112,7 @@ class Cursor(object):
         This iterator is shared. Advancing this iterator will advance other
         iterators created from this cursor.
         """
-        warnings.warn("DB-API extension cursor.__iter__() used")
+        warnings.warn("DB-API extension cursor.__iter__() used", stacklevel=2)
         return self
 
     def fetchmany(self, count=None):
@@ -126,7 +126,7 @@ class Cursor(object):
         if count == 0:
             return self.fetchall()
         result = []
-        for i in range(count):
+        for _ in range(count):
             try:
                 result.append(self.next())
             except StopIteration:
@@ -153,7 +153,7 @@ class Cursor(object):
         Close the cursor now
         """
         self._closed = True
-        self._result = None
+        self._result = {}
 
     def setinputsizes(self, sizes):
         """
@@ -174,7 +174,7 @@ class Cursor(object):
         .execute*() produced (for DQL statements like ``SELECT``) or affected
         (for DML statements like ``UPDATE`` or ``INSERT``).
         """
-        if (self._closed or not self._result or "rows" not in self._result):
+        if self._closed or not self._result or "rows" not in self._result:
             return -1
         return self._result.get("rowcount", -1)
 
@@ -185,10 +185,10 @@ class Cursor(object):
         """
         if self.rows is None:
             raise ProgrammingError(
-                "No result available. " +
-                "execute() or executemany() must be called first."
+                "No result available. "
+                + "execute() or executemany() must be called first."
             )
-        elif not self._closed:
+        if not self._closed:
             return next(self.rows)
         else:
             raise ProgrammingError("Cursor closed")
@@ -201,17 +201,11 @@ class Cursor(object):
         This read-only attribute is a sequence of 7-item sequences.
         """
         if self._closed:
-            return
+            return None
 
         description = []
         for col in self._result["cols"]:
-            description.append((col,
-                                None,
-                                None,
-                                None,
-                                None,
-                                None,
-                                None))
+            description.append((col, None, None, None, None, None, None))
         return tuple(description)
 
     @property
@@ -220,9 +214,7 @@ class Cursor(object):
         This read-only attribute specifies the server-side duration of a query
         in milliseconds.
         """
-        if self._closed or \
-                not self._result or \
-                "duration" not in self._result:
+        if self._closed or not self._result or "duration" not in self._result:
             return -1
         return self._result.get("duration", 0)
 
@@ -230,22 +222,21 @@ class Cursor(object):
         """
         Iterate rows, apply type converters, and generate converted rows.
         """
-        assert "col_types" in self._result and self._result["col_types"], \
-               "Unable to apply type conversion without `col_types` information"
+        if not ("col_types" in self._result and self._result["col_types"]):
+            raise ValueError(
+                "Unable to apply type conversion "
+                "without `col_types` information"
+            )
 
-        # Resolve `col_types` definition to converter functions. Running the lookup
-        # redundantly on each row loop iteration would be a huge performance hog.
+        # Resolve `col_types` definition to converter functions. Running
+        # the lookup redundantly on each row loop iteration would be a
+        # huge performance hog.
         types = self._result["col_types"]
-        converters = [
-            self._converter.get(type) for type in types
-        ]
+        converters = [self._converter.get(type_) for type_ in types]
 
         # Process result rows with conversion.
         for row in self._result["rows"]:
-            yield [
-                convert(value)
-                for convert, value in zip(converters, row)
-            ]
+            yield [convert(value) for convert, value in zip(converters, row)]
 
     @property
     def time_zone(self):
@@ -267,11 +258,15 @@ class Cursor(object):
         - ``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
-        "naive", without any `tzinfo`, converted using ``datetime.utcfromtimestamp(...)``.
+        using Coordinated Universal Time (UTC), because CrateDB is storing
+        timestamp values in this format.
 
-        When `time_zone` is given, the returned `datetime` objects are "aware",
-        with `tzinfo` set, converted using ``datetime.fromtimestamp(..., tz=...)``.
+        When `time_zone` is given, the timestamp values will be transparently
+        converted from UTC to use the given time zone.
         """
 
         # Do nothing when time zone is reset.
@@ -279,18 +274,22 @@ class Cursor(object):
             self._time_zone = None
             return
 
-        # Requesting datetime-aware `datetime` objects needs the data type converter.
+        # Requesting datetime-aware `datetime` objects
+        # needs the data type converter.
         # Implicitly create one, when needed.
         if self._converter is None:
             self._converter = Converter()
 
-        # When the time zone is given as a string, assume UTC offset format, e.g. `+0530`.
+        # When the time zone is given as a string,
+        # assume UTC offset format, e.g. `+0530`.
         if isinstance(tz, str):
             tz = self._timezone_from_utc_offset(tz)
 
         self._time_zone = tz
 
-        def _to_datetime_with_tz(value: t.Optional[float]) -> t.Optional[datetime]:
+        def _to_datetime_with_tz(
+            value: t.Optional[float],
+        ) -> t.Optional[datetime]:
             """
             Convert CrateDB's `TIMESTAMP` value to a native Python `datetime`
             object, with timezone-awareness.
@@ -306,12 +305,17 @@ class Cursor(object):
     @staticmethod
     def _timezone_from_utc_offset(tz) -> timezone:
         """
-        Convert UTC offset in string format (e.g. `+0530`) into `datetime.timezone` object.
+        UTC offset in string format (e.g. `+0530`) to `datetime.timezone`.
         """
-        assert len(tz) == 5, f"Time zone '{tz}' is given in invalid UTC offset format"
+        if len(tz) != 5:
+            raise ValueError(
+                f"Time zone '{tz}' is given in invalid UTC offset format"
+            )
         try:
             hours = int(tz[:3])
             minutes = int(tz[0] + tz[3:])
             return timezone(timedelta(hours=hours, minutes=minutes), name=tz)
         except Exception as ex:
-            raise ValueError(f"Time zone '{tz}' is given in invalid UTC offset format: {ex}")
+            raise ValueError(
+                f"Time zone '{tz}' is given in invalid UTC offset format: {ex}"
+            ) from ex

crate/client/exceptions.py

@@ -21,7 +21,6 @@
 
 
 class Error(Exception):
-
     def __init__(self, msg=None, error_trace=None):
         # for compatibility reasons we want to keep the exception message
         # attribute because clients may depend on it
@@ -36,7 +35,8 @@ class Error(Exception):
         return "\n".join([super().__str__(), str(self.error_trace)])
 
 
-class Warning(Exception):
+# A001 Variable `Warning` is shadowing a Python builtin
+class Warning(Exception):  # noqa: A001
     pass
 
 
@@ -74,7 +74,9 @@ class NotSupportedError(DatabaseError):
 
 # exceptions not in db api
 
-class ConnectionError(OperationalError):
+
+# A001 Variable `ConnectionError` is shadowing a Python builtin
+class ConnectionError(OperationalError):  # noqa: A001
     pass