pydiverse-common 0.3.1__py3-none-any.whl → 0.3.5__py3-none-any.whl

pydiverse/common/__init__.py

@@ -7,6 +7,7 @@ from .dtypes import (
     Decimal,
     Dtype,
     Duration,
+    Enum,
     Float,
     Float32,
     Float64,
@@ -25,8 +26,10 @@ from .dtypes import (
     UInt32,
     UInt64,
 )
+from .version import __version__
 
 __all__ = [
+    "__version__",
     "Dtype",
     "Bool",
     "Date",
@@ -49,5 +52,6 @@ __all__ = [
     "UInt32",
     "UInt64",
     "List",
+    "Enum",
     "PandasBackend",
 ]

pydiverse/common/dtypes.py

@@ -1,9 +1,9 @@
 # Copyright (c) QuantCo and pydiverse contributors 2025-2025
 # SPDX-License-Identifier: BSD-3-Clause
-from enum import Enum
+import enum
 
 
-class PandasBackend(str, Enum):
+class PandasBackend(str, enum.Enum):
     NUMPY = "numpy"
     ARROW = "arrow"
 
@@ -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):
@@ -73,14 +83,15 @@ class Dtype:
         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
 
@@ -127,13 +138,17 @@ class Dtype:
             return Datetime()
         if pd.api.types.is_timedelta64_dtype(pandas_type):
             return Duration()
-        # we don't know any decimal/time dtypes in pandas if column is not
+        # we don't know any decimal/time/null dtypes in pandas if column is not
         # arrow backed
 
+        if pandas_type.name == "category":
+            return Enum(*pandas_type.categories.to_list())
+
         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):
@@ -179,14 +194,21 @@ class Dtype:
             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):
             return List(Dtype.from_polars(polars_type.inner))
+        if isinstance(polars_type, pl.Enum):
+            return Enum(*polars_type.categories)
 
         return {
             pl.Int64: Int64(),
@@ -207,10 +229,10 @@ class Dtype:
             pl.Date: Date(),
             pl.Null: NullType(),
             pl.Duration: Duration(),
-            pl.Enum: String(),
         }[polars_type.base_type()]
 
     def to_sql(self):
+        """Convert this Dtype to a SQL type."""
         import sqlalchemy as sqa
 
         return {
@@ -237,6 +259,7 @@ class Dtype:
         }[self]
 
     def to_pandas(self, backend: PandasBackend = PandasBackend.ARROW):
+        """Convert this Dtype to a pandas type."""
         import pandas as pd
 
         if backend == PandasBackend.NUMPY:
@@ -247,12 +270,35 @@ 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")
+
+        if isinstance(self, Enum):
+            return pd.CategoricalDtype(self.categories)
 
         return {
             Int(): pd.Int64Dtype(),  # we default to 64 bit
@@ -277,8 +323,12 @@ class Dtype:
         }[self]
 
     def to_arrow(self):
+        """Convert this Dtype to a PyArrow type."""
         import pyarrow as pa
 
+        if isinstance(self, Enum):
+            return pa.string()
+
         return {
             Int(): pa.int64(),  # we default to 64 bit
             Int8(): pa.int8(),
@@ -299,9 +349,11 @@ class Dtype:
             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 {
@@ -416,3 +468,41 @@ 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())
+
+
+class Enum(String):
+    def __init__(self, *categories: str):
+        if not all(isinstance(c, str) for c in categories):
+            raise TypeError("arguments for `Enum` must have type `str`")
+        self.categories = list(categories)
+
+    def __eq__(self, rhs):
+        return isinstance(rhs, Enum) and self.categories == rhs.categories
+
+    def __repr__(self) -> str:
+        return f"Enum[{', '.join(repr(c) for c in self.categories)}]"
+
+    def __hash__(self):
+        return hash(tuple(self.categories))
+
+    def to_polars(self):
+        import polars as pl
+
+        return pl.Enum(self.categories)
+
+    def to_sql(self):
+        import sqlalchemy as sqa
+
+        return sqa.String()
+
+    def to_arrow(self):
+        import pyarrow as pa
+
+        # There is also pa.dictionary(), which seems to be kind of similar to an enum.
+        # Maybe it is better to convert to this.
+        return pa.string()

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.1.dist-info → pydiverse_common-0.3.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydiverse-common
-Version: 0.3.1
+Version: 0.3.5
 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,>=7.3.2
 Description-Content-Type: text/markdown
 
 # pydiverse.common

{pydiverse_common-0.3.1.dist-info → pydiverse_common-0.3.5.dist-info}/RECORD

@@ -1,5 +1,7 @@
-pydiverse/common/__init__.py,sha256=2t3wnZGY_KITo5lysb-GAgXizeyd_iZvPjEHKnMsYpA,732
-pydiverse/common/dtypes.py,sha256=OtxOLnA5HIX9OandrrSgKS8bzERnntLRvQF-hSzvlbU,12509
+pydiverse/common/__init__.py,sha256=J7b4iStFyaEMYre_jdlZ4l_8dLyrMWCIpQdsMQcB8aI,806
+pydiverse/common/dtypes.py,sha256=Twna-Esfy0-4wzIxX37C1CzPTJz8MnesV_LNegndKzE,15787
+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.1.dist-info/METADATA,sha256=Ul8A6lt1G9b05z5khak8nhekPdjTcQsaZxmoReueJXU,3357
-pydiverse_common-0.3.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-pydiverse_common-0.3.1.dist-info/licenses/LICENSE,sha256=AcE6SDVuAq6v9ZLE_8eOCe_NvSE0rAPR3NR7lSowYh4,1517
-pydiverse_common-0.3.1.dist-info/RECORD,,
+pydiverse_common-0.3.5.dist-info/METADATA,sha256=E4Z7zT2kwRtIlGetzPlxFf5Oj5-b037lAkLikUbNgKk,3399
+pydiverse_common-0.3.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pydiverse_common-0.3.5.dist-info/licenses/LICENSE,sha256=AcE6SDVuAq6v9ZLE_8eOCe_NvSE0rAPR3NR7lSowYh4,1517
+pydiverse_common-0.3.5.dist-info/RECORD,,