ygg 0.1.57__py3-none-any.whl → 0.1.64__py3-none-any.whl

yggdrasil/types/cast/pandas_cast.py

@@ -11,9 +11,10 @@ from .arrow_cast import (
 )
 from .cast_options import CastOptions
 from .registry import register_converter
-from ...libs.pandaslib import pandas, require_pandas
+from ...libs.pandaslib import pandas, PandasDataFrame, PandasSeries
 
 __all__ = [
+    "pandas_converter",
     "cast_pandas_series",
     "cast_pandas_dataframe",
     "arrow_array_to_pandas_series",
@@ -29,11 +30,6 @@ __all__ = [
 # ---------------------------------------------------------------------------
 
 if pandas is not None:
-    require_pandas()
-
-    PandasSeries = pandas.Series
-    PandasDataFrame = pandas.DataFrame
-
     def pandas_converter(*args, **kwargs):
         """Return a register_converter wrapper when pandas is available.
 
@@ -47,14 +43,6 @@ if pandas is not None:
         return register_converter(*args, **kwargs)
 
 else:
-    # Dummy types so annotations/decorators don't explode without pandas
-    class _PandasDummy:  # pragma: no cover - only used when pandas not installed
-        """Placeholder type for pandas symbols when pandas is unavailable."""
-        pass
-
-    PandasSeries = _PandasDummy
-    PandasDataFrame = _PandasDummy
-
     def pandas_converter(*_args, **_kwargs):  # pragma: no cover - no-op decorator
         """Return a no-op decorator when pandas is unavailable.
 
@@ -83,188 +71,188 @@ else:
 # pandas <-> Arrow via ArrowCastOptions
 # ---------------------------------------------------------------------------
 
+if pandas is not None:
+    @pandas_converter(PandasSeries, PandasSeries)
+    def cast_pandas_series(
+        series: PandasSeries,
+        options: Optional[CastOptions] = None,
+    ) -> PandasSeries:
+        """
+        Cast a pandas Series to a target Arrow type using Arrow casting rules.
 
-@pandas_converter(PandasSeries, PandasSeries)
-def cast_pandas_series(
-    series: "pandas.Series",
-    options: Optional[CastOptions] = None,
-) -> "pandas.Series":
-    """
-    Cast a pandas Series to a target Arrow type using Arrow casting rules.
+        The target type/field should be provided via `options` (e.g. options.target_schema
+        or options.target_field, depending on how ArrowCastOptions is defined).
 
-    The target type/field should be provided via `options` (e.g. options.target_schema
-    or options.target_field, depending on how ArrowCastOptions is defined).
+        Arrow does:
+          - type cast
+          - nullability enforcement
+          - default handling (via cast_arrow_array)
+        We then convert back to pandas and restore index/name.
+        """
+        options = CastOptions.check_arg(options)
 
-    Arrow does:
-      - type cast
-      - nullability enforcement
-      - default handling (via cast_arrow_array)
-    We then convert back to pandas and restore index/name.
-    """
-    options = CastOptions.check_arg(options)
+        arrow_array = pa.array(series, from_pandas=True)
+        casted = cast_arrow_array(arrow_array, options)
 
-    arrow_array = pa.array(series, from_pandas=True)
-    casted = cast_arrow_array(arrow_array, options)
+        result = casted.to_pandas()
+        result.index = series.index
+        result.name = series.name
+        return result
 
-    result = casted.to_pandas()
-    result.index = series.index
-    result.name = series.name
-    return result
 
+    @pandas_converter(PandasDataFrame, PandasDataFrame)
+    def cast_pandas_dataframe(
+        dataframe: PandasDataFrame,
+        options: Optional[CastOptions] = None,
+    ) -> PandasDataFrame:
+        """
+        Cast a pandas DataFrame to a target Arrow schema using Arrow casting rules.
 
-@pandas_converter(PandasDataFrame, PandasDataFrame)
-def cast_pandas_dataframe(
-    dataframe: "pandas.DataFrame",
-    options: Optional[CastOptions] = None,
-) -> "pandas.DataFrame":
-    """
-    Cast a pandas DataFrame to a target Arrow schema using Arrow casting rules.
+        Behavior is analogous to the Polars version, but we delegate casting to
+        `cast_arrow_table` and then adjust columns on the pandas side:
 
-    Behavior is analogous to the Polars version, but we delegate casting to
-    `cast_arrow_table` and then adjust columns on the pandas side:
+          - options.target_schema: Arrow schema / field used by cast_arrow_table
+          - options.allow_add_columns:
+              * False: result only has columns from the cast Arrow table
+              * True: extra pandas columns (not in the target schema / cast result)
+                      are appended unchanged
+        """
+        options = CastOptions.check_arg(options)
 
-      - options.target_schema: Arrow schema / field used by cast_arrow_table
-      - options.allow_add_columns:
-          * False: result only has columns from the cast Arrow table
-          * True: extra pandas columns (not in the target schema / cast result)
-                  are appended unchanged
-    """
-    options = CastOptions.check_arg(options)
+        original_index = dataframe.index
 
-    original_index = dataframe.index
+        arrow_table = pa.Table.from_pandas(dataframe, preserve_index=False)
+        casted_table = cast_arrow_tabular(arrow_table, options)
 
-    arrow_table = pa.Table.from_pandas(dataframe, preserve_index=False)
-    casted_table = cast_arrow_tabular(arrow_table, options)
+        result = casted_table.to_pandas()
+        result.index = original_index
 
-    result = casted_table.to_pandas()
-    result.index = original_index
+        if getattr(options, "allow_add_columns", False):
+            casted_cols = set(result.columns)
+            extra_cols = [col for col in dataframe.columns if col not in casted_cols]
 
-    if getattr(options, "allow_add_columns", False):
-        casted_cols = set(result.columns)
-        extra_cols = [col for col in dataframe.columns if col not in casted_cols]
+            if extra_cols:
+                extra_df = dataframe[extra_cols]
+                extra_df.index = result.index
+                result = pandas.concat([result, extra_df], axis=1)
 
-        if extra_cols:
-            extra_df = dataframe[extra_cols]
-            extra_df.index = result.index
-            result = pandas.concat([result, extra_df], axis=1)
+        return result
 
-    return result
 
+    # ---------------------------------------------------------------------------
+    # Arrow -> pandas
+    # ---------------------------------------------------------------------------
 
-# ---------------------------------------------------------------------------
-# Arrow -> pandas
-# ---------------------------------------------------------------------------
 
+    @pandas_converter(pa.Array, PandasSeries)
+    @pandas_converter(pa.ChunkedArray, PandasSeries)
+    def arrow_array_to_pandas_series(
+        array: pa.Array,
+        cast_options: Optional[CastOptions] = None,
+    ) -> PandasSeries:
+        """
+        Convert a pyarrow.Array (or ChunkedArray) to a pandas Series,
+        optionally applying Arrow casting via ArrowCastOptions before conversion.
+        """
+        opts = CastOptions.check_arg(cast_options)
 
-@pandas_converter(pa.Array, PandasSeries)
-@pandas_converter(pa.ChunkedArray, PandasSeries)
-def arrow_array_to_pandas_series(
-    array: pa.Array,
-    cast_options: Optional[CastOptions] = None,
-) -> "pandas.Series":
-    """
-    Convert a pyarrow.Array (or ChunkedArray) to a pandas Series,
-    optionally applying Arrow casting via ArrowCastOptions before conversion.
-    """
-    opts = CastOptions.check_arg(cast_options)
-
-    if isinstance(array, pa.ChunkedArray):
-        array = array.combine_chunks()
-
-    casted = cast_arrow_array(array, opts)
-    return casted.to_pandas()
-
-
-@pandas_converter(pa.Table, PandasDataFrame)
-def arrow_table_to_pandas_dataframe(
-    table: pa.Table,
-    cast_options: Optional[CastOptions] = None,
-) -> "pandas.DataFrame":
-    """
-    Convert a pyarrow.Table to a pandas DataFrame, optionally applying Arrow
-    casting rules first.
-    """
-    opts = CastOptions.check_arg(cast_options)
-
-    if opts.target_arrow_schema is not None:
-        table = cast_arrow_tabular(table, opts)
+        if isinstance(array, pa.ChunkedArray):
+            array = array.combine_chunks()
 
-    return table.to_pandas()
+        casted = cast_arrow_array(array, opts)
+        return casted.to_pandas()
 
 
-@pandas_converter(pa.RecordBatchReader, PandasDataFrame)
-def record_batch_reader_to_pandas_dataframe(
-    reader: pa.RecordBatchReader,
-    cast_options: Optional[CastOptions] = None,
-) -> "pandas.DataFrame":
-    """
-    Convert a pyarrow.RecordBatchReader to a pandas DataFrame.
+    @pandas_converter(pa.Table, PandasDataFrame)
+    def arrow_table_to_pandas_dataframe(
+        table: pa.Table,
+        cast_options: Optional[CastOptions] = None,
+    ) -> PandasDataFrame:
+        """
+        Convert a pyarrow.Table to a pandas DataFrame, optionally applying Arrow
+        casting rules first.
+        """
+        opts = CastOptions.check_arg(cast_options)
 
-    - If cast_options.target_schema is set, we first apply
-      `cast_arrow_record_batch_reader` and then collect to a Table and pandas DF.
-    """
-    opts = CastOptions.check_arg(cast_options)
+        if opts.target_arrow_schema is not None:
+            table = cast_arrow_tabular(table, opts)
 
-    if opts.target_arrow_schema is not None:
-        reader = cast_arrow_record_batch_reader(reader, opts)
+        return table.to_pandas()
 
-    batches = list(reader)
-    if not batches:
-        empty_table = pa.Table.from_arrays([], names=[])
-        return empty_table.to_pandas()
 
-    table = pa.Table.from_batches(batches)
-    return arrow_table_to_pandas_dataframe(table, opts)
+    @pandas_converter(pa.RecordBatchReader, PandasDataFrame)
+    def record_batch_reader_to_pandas_dataframe(
+        reader: pa.RecordBatchReader,
+        cast_options: Optional[CastOptions] = None,
+    ) -> PandasDataFrame:
+        """
+        Convert a pyarrow.RecordBatchReader to a pandas DataFrame.
 
+        - If cast_options.target_schema is set, we first apply
+          `cast_arrow_record_batch_reader` and then collect to a Table and pandas DF.
+        """
+        opts = CastOptions.check_arg(cast_options)
 
-# ---------------------------------------------------------------------------
-# pandas -> Arrow
-# ---------------------------------------------------------------------------
+        if opts.target_arrow_schema is not None:
+            reader = cast_arrow_record_batch_reader(reader, opts)
 
+        batches = list(reader)
+        if not batches:
+            empty_table = pa.Table.from_arrays([], names=[])
+            return empty_table.to_pandas()
+
+        table = pa.Table.from_batches(batches)
+        return arrow_table_to_pandas_dataframe(table, opts)
+
+
+    # ---------------------------------------------------------------------------
+    # pandas -> Arrow
+    # ---------------------------------------------------------------------------
+
+
+    @pandas_converter(PandasSeries, pa.Array)
+    def pandas_series_to_arrow_array(
+        series: PandasSeries,
+        cast_options: Optional[CastOptions] = None,
+    ) -> pa.Array:
+        """
+        Convert a pandas Series to a pyarrow.Array, optionally applying Arrow
+        casting via ArrowCastOptions.
+        """
+        opts = CastOptions.check_arg(cast_options)
+
+        array = pa.array(series, from_pandas=True)
+        return cast_arrow_array(array, opts)
+
+
+    @pandas_converter(PandasDataFrame, pa.Table)
+    def pandas_dataframe_to_arrow_table(
+        dataframe: PandasDataFrame,
+        cast_options: Optional[CastOptions] = None,
+    ) -> pa.Table:
+        """
+        Convert a pandas DataFrame to a pyarrow.Table, optionally applying Arrow
+        casting rules via ArrowCastOptions.
+        """
+        opts = CastOptions.check_arg(cast_options)
+
+        table = pa.Table.from_pandas(dataframe, preserve_index=False)
+        return cast_arrow_tabular(table, opts)
+
+
+    @pandas_converter(PandasDataFrame, pa.RecordBatchReader)
+    def pandas_dataframe_to_record_batch_reader(
+        dataframe: PandasDataFrame,
+        cast_options: Optional[CastOptions] = None,
+    ) -> pa.RecordBatchReader:
+        """
+        Convert a pandas DataFrame to a pyarrow.RecordBatchReader, optionally
+        applying Arrow casting via ArrowCastOptions.
+        """
+        opts = CastOptions.check_arg(cast_options)
+
+        table = pa.Table.from_pandas(dataframe, preserve_index=False)
+        table = cast_arrow_tabular(table, opts)
 
-@pandas_converter(PandasSeries, pa.Array)
-def pandas_series_to_arrow_array(
-    series: "pandas.Series",
-    cast_options: Optional[CastOptions] = None,
-) -> pa.Array:
-    """
-    Convert a pandas Series to a pyarrow.Array, optionally applying Arrow
-    casting via ArrowCastOptions.
-    """
-    opts = CastOptions.check_arg(cast_options)
-
-    array = pa.array(series, from_pandas=True)
-    return cast_arrow_array(array, opts)
-
-
-@pandas_converter(PandasDataFrame, pa.Table)
-def pandas_dataframe_to_arrow_table(
-    dataframe: "pandas.DataFrame",
-    cast_options: Optional[CastOptions] = None,
-) -> pa.Table:
-    """
-    Convert a pandas DataFrame to a pyarrow.Table, optionally applying Arrow
-    casting rules via ArrowCastOptions.
-    """
-    opts = CastOptions.check_arg(cast_options)
-
-    table = pa.Table.from_pandas(dataframe, preserve_index=False)
-    return cast_arrow_tabular(table, opts)
-
-
-@pandas_converter(PandasDataFrame, pa.RecordBatchReader)
-def pandas_dataframe_to_record_batch_reader(
-    dataframe: "pandas.DataFrame",
-    cast_options: Optional[CastOptions] = None,
-) -> pa.RecordBatchReader:
-    """
-    Convert a pandas DataFrame to a pyarrow.RecordBatchReader, optionally
-    applying Arrow casting via ArrowCastOptions.
-    """
-    opts = CastOptions.check_arg(cast_options)
-
-    table = pa.Table.from_pandas(dataframe, preserve_index=False)
-    table = cast_arrow_tabular(table, opts)
-
-    batches = table.to_batches()
-    return pa.RecordBatchReader.from_batches(table.schema, batches)
+        batches = table.to_batches()
+        return pa.RecordBatchReader.from_batches(table.schema, batches)

yggdrasil/types/cast/polars_cast.py

@@ -1,18 +1,21 @@
 """Polars <-> Arrow casting helpers and converters."""
 
-from typing import Optional, Tuple, Union, Dict, Any
+from typing import Optional, Tuple, Union, Dict
 
 import pyarrow as pa
 
 from .arrow_cast import (
     cast_arrow_array,
     cast_arrow_tabular,
-    cast_arrow_record_batch_reader, is_arrow_type_binary_like, is_arrow_type_string_like, is_arrow_type_list_like,
+    cast_arrow_record_batch_reader,
+    is_arrow_type_binary_like,
+    is_arrow_type_string_like,
+    is_arrow_type_list_like,
 )
 from .cast_options import CastOptions
 from .registry import register_converter
 from ..python_defaults import default_arrow_scalar
-from ...libs.polarslib import polars
+from ...libs.polarslib import *
 
 __all__ = [
     "polars_converter",
@@ -41,14 +44,8 @@ __all__ = [
 # Polars type aliases + decorator wrapper (safe when Polars is missing)
 # ---------------------------------------------------------------------------
 
-if polars is not None:
-    PolarsSeries = polars.Series
-    PolarsExpr = polars.Expr
-    PolarsDataFrame = polars.DataFrame
-    PolarsField = polars.Field
-    PolarsSchema = polars.Schema
-    PolarsDataType = polars.DataType
 
+if polars is not None:
     # Primitive Arrow -> Polars dtype mapping (base, non-nested types).
     # These are Polars *dtype classes* (not instances), so they can be used
     # directly in schemas (e.g. pl.Struct({"a": pl.Int64})).
@@ -95,18 +92,6 @@ if polars is not None:
 else:
     ARROW_TO_POLARS = {}
 
-    # Dummy types so annotations/decorators don't explode without Polars
-    class _PolarsDummy:  # pragma: no cover - only used when Polars not installed
-        """Placeholder type for polars symbols when polars is unavailable."""
-        pass
-
-    PolarsSeries = _PolarsDummy
-    PolarsExpr = _PolarsDummy
-    PolarsDataFrame = _PolarsDummy
-    PolarsField = _PolarsDummy
-    PolarsSchema = _PolarsDummy
-    PolarsDataType = _PolarsDummy
-
     def polars_converter(*_args, **_kwargs):  # pragma: no cover - no-op decorator
         """Return a no-op decorator when polars is unavailable.
 
@@ -737,26 +722,6 @@ def arrow_field_to_polars_field(
     return built
 
 
-def _polars_base_type(pl_dtype: Any) -> Any:
-    """
-    Normalize a Polars dtype or dtype class to its base_type class,
-    so we can key into POLARS_BASE_TO_ARROW.
-    """
-    # dtype is an instance
-    base_method = getattr(pl_dtype, "base_type", None)
-    if callable(base_method):
-        return base_method()
-    # dtype is a class (e.g. pl.Int64)
-    try:
-        instance = pl_dtype()
-    except Exception:
-        return pl_dtype
-    base_method = getattr(instance, "base_type", None)
-    if callable(base_method):
-        return base_method()
-    return pl_dtype
-
-
 @polars_converter(PolarsDataType, pa.DataType)
 def polars_type_to_arrow_type(
     pl_type: PolarsDataType,
@@ -767,7 +732,10 @@ def polars_type_to_arrow_type(
 
     Handles primitives via POLARS_BASE_TO_ARROW and common nested/temporal types.
     """
-    base = _polars_base_type(pl_type)
+    try:
+        base =  pl_type()
+    except Exception:
+        base = pl_type
 
     # Primitive base mapping
     existing = POLARS_BASE_TO_ARROW.get(base) or POLARS_BASE_TO_ARROW.get(type(pl_type))

yggdrasil/types/dummy_class.py

@@ -0,0 +1,81 @@
+from abc import ABC, abstractmethod
+
+
+__all__ = ["DummyModuleClass"]
+
+
+class DummyModuleClass(ABC):
+    """
+    Hard-fail dummy proxy: any interaction raises, except a few safe internals.
+    """
+
+    @classmethod
+    @abstractmethod
+    def module_name(cls) -> str:
+        raise NotImplementedError
+
+    def _raise(self, action: str, name: str | None = None):
+        target = type(self).module_name()
+        extra = f" '{name}'" if name else ""
+        raise ModuleNotFoundError(
+            f"{type(self).__name__} is a dummy for missing optional dependency "
+            f"module '{target}'. Tried to {action}{extra}."
+        )
+
+    # --- attribute access / mutation ---
+    def __getattribute__(self, name: str):
+        # allow introspection / internals without blowing up
+        if name in {"module_name", "_raise", "__class__", "__dict__", "__repr__", "__str__", "__dir__"}:
+            return object.__getattribute__(self, name)
+        self._raise("access attribute", name)
+
+    def __getattr__(self, name: str):
+        self._raise("access attribute", name)
+
+    def __setattr__(self, name: str, value):
+        self._raise("set attribute", name)
+
+    def __delattr__(self, name: str):
+        self._raise("delete attribute", name)
+
+    def __dir__(self):
+        # show minimal surface
+        return ["module_name"]
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__} dummy for '{type(self).module_name()}'>"
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+    # --- common "other" interactions ---
+    def __call__(self, *args, **kwargs):
+        self._raise("call module")
+
+    def __getitem__(self, key):
+        self._raise("index", str(key))
+
+    def __setitem__(self, key, value):
+        self._raise("set item", str(key))
+
+    def __delitem__(self, key):
+        self._raise("delete item", str(key))
+
+    def __iter__(self):
+        self._raise("iterate")
+
+    def __len__(self):
+        self._raise("get length")
+
+    def __contains__(self, item):
+        self._raise("check containment")
+
+    def __bool__(self):
+        self._raise("coerce to bool")
+
+
+# Example:
+# class PyArrowDummy(DummyModuleClass):
+#     @classmethod
+#     def module_name(cls) -> str:
+#         return "pyarrow"

yggdrasil/types/file_format.py

@@ -1,8 +1,12 @@
-from pyarrow.dataset import FileFormat
+from pyarrow.dataset import FileFormat, ParquetFileFormat, CsvFileFormat, JsonFileFormat
 
 
 __all__ = [
-    "ExcelFileFormat"
+    "FileFormat",
+    "ExcelFileFormat",
+    "ParquetFileFormat",
+    "CsvFileFormat",
+    "JsonFileFormat"
 ]