pydiverse-common 0.3.0__py3-none-any.whl → 0.3.4__py3-none-any.whl

pydiverse/common/__init__.py

@@ -25,8 +25,10 @@ from .dtypes import (
     UInt32,
     UInt64,
 )
+from .version import __version__
 
 __all__ = [
+    "__version__",
     "Dtype",
     "Bool",
     "Date",

pydiverse/common/dtypes.py

@@ -12,24 +12,33 @@ class Dtype:
     """Base class for all data types."""
 
     def __eq__(self, rhs):
+        """Return ``True`` if this dtype is equal to `rhs`."""
         return isinstance(rhs, Dtype) and type(self) is type(rhs)
 
     def __hash__(self):
+        """Return a hash for this dtype."""
         return hash(type(self))
 
     def __repr__(self):
+        """Return a string representation of this dtype."""
         return self.__class__.__name__
 
     @classmethod
     def is_int(cls):
+        """Return ``True`` if this dtype is an integer type."""
         return False
 
     @classmethod
     def is_float(cls):
+        """Return ``True`` if this dtype is a float type."""
         return False
 
     @classmethod
     def is_subtype(cls, rhs):
+        """Return ``True`` if this dtype is a subtype of `rhs`.
+
+        For example, ``Int8.is_subtype(Int())`` is ``True``.
+        """
         rhs_cls = type(rhs)
         return (
             (cls is rhs_cls)
@@ -39,6 +48,7 @@ class Dtype:
 
     @staticmethod
     def from_sql(sql_type) -> "Dtype":
+        """Convert a SQL type to a Dtype."""
         import sqlalchemy as sqa
 
         if isinstance(sql_type, sqa.SmallInteger):
@@ -70,15 +80,18 @@ class Dtype:
             return Time()
         if isinstance(sql_type, sqa.DateTime):
             return Datetime()
+        if isinstance(sql_type, sqa.Interval):
+            return Duration()
         if isinstance(sql_type, sqa.ARRAY):
-            return List(Dtype.from_sql(sql_type.item_type.from_sql))
-        if isinstance(sql_type, sqa.Null):
+            return List(Dtype.from_sql(sql_type.item_type))
+        if isinstance(sql_type, sqa.types.NullType):
             return NullType()
 
         raise TypeError
 
     @staticmethod
     def from_pandas(pandas_type) -> "Dtype":
+        """Convert a pandas type to a Dtype."""
         import numpy as np
         import pandas as pd
 
@@ -123,12 +136,16 @@ class Dtype:
             return Bool()
         if pd.api.types.is_datetime64_any_dtype(pandas_type):
             return Datetime()
-        # we don't know any decimal dtype in pandas if column is not arrow backed
+        if pd.api.types.is_timedelta64_dtype(pandas_type):
+            return Duration()
+        # we don't know any decimal/time/null dtypes in pandas if column is not
+        # arrow backed
 
         raise TypeError
 
     @staticmethod
     def from_arrow(arrow_type) -> "Dtype":
+        """Convert a PyArrow type to a Dtype."""
         import pyarrow as pa
 
         if pa.types.is_signed_integer(arrow_type):
@@ -172,10 +189,17 @@ class Dtype:
             return Date()
         if pa.types.is_time(arrow_type):
             return Time()
+        if pa.types.is_duration(arrow_type):
+            return Duration()
+        if pa.types.is_null(arrow_type):
+            return NullType()
+        if pa.types.is_list(arrow_type):
+            return List(Dtype.from_arrow(arrow_type.value_type))
         raise TypeError
 
     @staticmethod
     def from_polars(polars_type) -> "Dtype":
+        """Convert a Polars type to a Dtype."""
         import polars as pl
 
         if isinstance(polars_type, pl.List):
@@ -204,6 +228,7 @@ class Dtype:
         }[polars_type.base_type()]
 
     def to_sql(self):
+        """Convert this Dtype to a SQL type."""
         import sqlalchemy as sqa
 
         return {
@@ -225,10 +250,12 @@ class Dtype:
             Date(): sqa.Date(),
             Time(): sqa.Time(),
             Datetime(): sqa.DateTime(),
+            Duration(): sqa.Interval(),
             NullType(): sqa.types.NullType(),
         }[self]
 
     def to_pandas(self, backend: PandasBackend = PandasBackend.ARROW):
+        """Convert this Dtype to a pandas type."""
         import pandas as pd
 
         if backend == PandasBackend.NUMPY:
@@ -239,12 +266,32 @@ class Dtype:
             return pd.ArrowDtype(self.to_arrow())
 
     def to_pandas_nullable(self, backend: PandasBackend = PandasBackend.ARROW):
+        """Convert this Dtype to a pandas nullable type.
+
+        Nullable can be either pandas extension types like StringDtype or ArrowDtype.
+
+        Parameters
+        ----------
+        backend : PandasBackend, optional
+            The pandas backend to use. Defaults to ``PandasBackend.ARROW``.
+            If ``PandasBackend.NUMPY`` is selected, this method will attempt
+            to return a NumPy-backed nullable pandas dtype. Note that
+            Time, NullType, and List will raise a TypeError for the
+            NUMPY backend as pandas doesn't have corresponding native
+            nullable dtypes for these.
+        """
         import pandas as pd
 
-        if self == Time():
-            if backend == PandasBackend.ARROW:
-                return pd.ArrowDtype(self.to_arrow())
+        if backend == PandasBackend.ARROW:
+            return pd.ArrowDtype(self.to_arrow())
+
+        # we don't want to produce object columns
+        if isinstance(self, Time):
             raise TypeError("pandas doesn't have a native time dtype")
+        if isinstance(self, NullType):
+            raise TypeError("pandas doesn't have a native null dtype")
+        if isinstance(self, List):
+            raise TypeError("pandas doesn't have a native list dtype")
 
         return {
             Int(): pd.Int64Dtype(),  # we default to 64 bit
@@ -263,11 +310,13 @@ class Dtype:
             String(): pd.StringDtype(),
             Bool(): pd.BooleanDtype(),
             Date(): "datetime64[s]",
-            # Time() not supported
             Datetime(): "datetime64[us]",
+            Time(): "timedelta64[us]",
+            Duration(): "timedelta64[us]",
         }[self]
 
     def to_arrow(self):
+        """Convert this Dtype to a PyArrow type."""
         import pyarrow as pa
 
         return {
@@ -289,9 +338,12 @@ class Dtype:
             Date(): pa.date32(),
             Time(): pa.time64("us"),
             Datetime(): pa.timestamp("us"),
+            Duration(): pa.duration("us"),
+            NullType(): pa.null(),
         }[self]
 
     def to_polars(self: "Dtype"):
+        """Convert this Dtype to a Polars type."""
         import polars as pl
 
         return {
@@ -311,8 +363,8 @@ class Dtype:
             String(): pl.Utf8,
             Bool(): pl.Boolean,
             Datetime(): pl.Datetime("us"),
-            Duration(): pl.Duration,
-            Time(): pl.Time,
+            Duration(): pl.Duration("us"),
+            Time(): pl.Time,  # Polars uses nanoseconds since midnight
             Date(): pl.Date,
             NullType(): pl.Null,
         }[self]
@@ -406,3 +458,8 @@ class List(Dtype):
         import polars as pl
 
         return pl.List(self.inner.to_polars())
+
+    def to_arrow(self):
+        import pyarrow as pa
+
+        return pa.list_(self.inner.to_arrow())

pydiverse/common/testing.py

@@ -0,0 +1,14 @@
+# Copyright (c) QuantCo and pydiverse contributors 2025-2025
+# SPDX-License-Identifier: BSD-3-Clause
+
+import inspect
+
+import pydiverse.common.dtypes as dtypes
+
+ALL_TYPES = [
+    getattr(dtypes, c)
+    for c in dir(dtypes)
+    if inspect.isclass(getattr(dtypes, c))
+    and issubclass(getattr(dtypes, c), dtypes.Dtype)
+    and c != "Dtype"
+]

pydiverse/common/version.py

@@ -0,0 +1,10 @@
+# Copyright (c) QuantCo and pydiverse contributors 2025-2025
+# SPDX-License-Identifier: BSD-3-Clause
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version(__package__ or __name__)
+except PackageNotFoundError:
+    # Running from a Git checkout or an editable install
+    __version__ = "0.0.0+dev"

{pydiverse_common-0.3.0.dist-info → pydiverse_common-0.3.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydiverse-common
-Version: 0.3.0
+Version: 0.3.4
 Summary: Common functionality shared between pydiverse libraries
 Author: QuantCo, Inc.
 Author-email: Martin Trautmann <windiana@users.sf.net>, Finn Rudolph <finn.rudolph@t-online.de>
@@ -47,7 +47,8 @@ Classifier: Programming Language :: SQL
 Classifier: Topic :: Database
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development
-Requires-Python: >=3.10
+Requires-Python: <3.14,>=3.10
+Requires-Dist: python-box<8.0.0,>=7.3.2
 Description-Content-Type: text/markdown
 
 # pydiverse.common

{pydiverse_common-0.3.0.dist-info → pydiverse_common-0.3.4.dist-info}/RECORD

@@ -1,5 +1,7 @@
-pydiverse/common/__init__.py,sha256=2t3wnZGY_KITo5lysb-GAgXizeyd_iZvPjEHKnMsYpA,732
-pydiverse/common/dtypes.py,sha256=7qPxKH1yqVSacANi5Kl36DdBTHKSMZI2WkZCiEEejyU,12074
+pydiverse/common/__init__.py,sha256=eK3Wji6868cvXeq6e9YPRxi20vU6i9Lql4IzG6iB4B4,784
+pydiverse/common/dtypes.py,sha256=1ADpaWJbdNIFEE2DFjdIy2RRsp5Wg3UVnSM1ZN8XVdw,14555
+pydiverse/common/testing.py,sha256=FcivI5wn0X3gzJhwnysKvCOgjSTTXaN6FtSFJ72jfSg,341
+pydiverse/common/version.py,sha256=1IU_m4r76_Qq0u-Tyo2_bERZFOkh0ZFueVzDqcCfLO0,336
 pydiverse/common/errors/__init__.py,sha256=FNeEfVbUa23b9sHkFsmxHYhY6sRgjaZysPQmlovpJrI,262
 pydiverse/common/util/__init__.py,sha256=fGdKZtLaTVBW7NfCpX7rZhKHwUzmBnsuY2akDOnAnjc,315
 pydiverse/common/util/computation_tracing.py,sha256=HeXRHRUI8vxpzQ27Xcpa0StndSTP63EMT9vj4trPJUY,9697
@@ -9,7 +11,7 @@ pydiverse/common/util/disposable.py,sha256=4XoGz70YRWA9TAqnUBvRCTAdsOGBviFN0gzxU
 pydiverse/common/util/hashing.py,sha256=6x77BKg-w61u59fuTe9di0BtU-kEKH6UTRcKsRoYJ84,1196
 pydiverse/common/util/import_.py,sha256=K7dSgz4YyrqEvqhoOzbwgD7D8HScMoO5XoSWtjbaoUs,4056
 pydiverse/common/util/structlog.py,sha256=g0d8yaXBzAxmGNGZYMnMP9dsSQ__jN44GAY8Mb0ABeI,3487
-pydiverse_common-0.3.0.dist-info/METADATA,sha256=5pwbOinMHcsH1Nbhe69cbh0eouevUvFNGt-QlLdl-HU,3357
-pydiverse_common-0.3.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-pydiverse_common-0.3.0.dist-info/licenses/LICENSE,sha256=AcE6SDVuAq6v9ZLE_8eOCe_NvSE0rAPR3NR7lSowYh4,1517
-pydiverse_common-0.3.0.dist-info/RECORD,,
+pydiverse_common-0.3.4.dist-info/METADATA,sha256=iV-aHd6IDEbgTaIsbB5lgAstdXaAAdotwZCh05laHA4,3403
+pydiverse_common-0.3.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pydiverse_common-0.3.4.dist-info/licenses/LICENSE,sha256=AcE6SDVuAq6v9ZLE_8eOCe_NvSE0rAPR3NR7lSowYh4,1517
+pydiverse_common-0.3.4.dist-info/RECORD,,