pydiverse-common 0.3.2__py2.py3-none-any.whl → 0.3.3__py2.py3-none-any.whl

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):
@@ -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,14 @@ 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
 
         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,10 +191,15 @@ 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):
@@ -211,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 {
@@ -237,6 +255,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 +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
@@ -277,6 +316,7 @@ class Dtype:
         }[self]
 
     def to_arrow(self):
+        """Convert this Dtype to a PyArrow type."""
         import pyarrow as pa
 
         return {
@@ -299,9 +339,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 +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-0.3.2.dist-info → pydiverse_common-0.3.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydiverse-common
-Version: 0.3.2
+Version: 0.3.3
 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>

{pydiverse_common-0.3.2.dist-info → pydiverse_common-0.3.3.dist-info}/RECORD

@@ -1,5 +1,6 @@
 pydiverse/common/__init__.py,sha256=eK3Wji6868cvXeq6e9YPRxi20vU6i9Lql4IzG6iB4B4,784
-pydiverse/common/dtypes.py,sha256=OtxOLnA5HIX9OandrrSgKS8bzERnntLRvQF-hSzvlbU,12509
+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
@@ -10,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.2.dist-info/METADATA,sha256=fwld0ZxdHloPOoeRj-X9WLZPwrNpQ4QuYeD1BZJ7qPo,3333
-pydiverse_common-0.3.2.dist-info/WHEEL,sha256=tkmg4JIqwd9H8mL30xA7crRmoStyCtGp0VWshokd1Jc,105
-pydiverse_common-0.3.2.dist-info/licenses/LICENSE,sha256=AcE6SDVuAq6v9ZLE_8eOCe_NvSE0rAPR3NR7lSowYh4,1517
-pydiverse_common-0.3.2.dist-info/RECORD,,
+pydiverse_common-0.3.3.dist-info/METADATA,sha256=YWmuuq0eJwf20_-rHFz9XsRS8gu3T7NEeOEvyV6QWHE,3333
+pydiverse_common-0.3.3.dist-info/WHEEL,sha256=tkmg4JIqwd9H8mL30xA7crRmoStyCtGp0VWshokd1Jc,105
+pydiverse_common-0.3.3.dist-info/licenses/LICENSE,sha256=AcE6SDVuAq6v9ZLE_8eOCe_NvSE0rAPR3NR7lSowYh4,1517
+pydiverse_common-0.3.3.dist-info/RECORD,,