ygg 0.1.30__py3-none-any.whl → 0.1.32__py3-none-any.whl

yggdrasil/types/cast/cast_options.py

@@ -1,3 +1,5 @@
+"""Casting options for Arrow- and engine-aware conversions."""
+
 import dataclasses
 from typing import Optional, Union, List, Any
 
@@ -69,6 +71,22 @@ class CastOptions:
         target_field: pa.Field | pa.Schema | pa.DataType | None = None,
         **kwargs
     ):
+        """Build a CastOptions instance with optional source/target fields.
+
+        Args:
+            safe: Enable safe casting if True.
+            add_missing_columns: Add missing columns if True.
+            strict_match_names: Require exact field name matches if True.
+            allow_add_columns: Allow extra columns if True.
+            eager: Enable eager casting behavior if True.
+            datetime_patterns: Optional datetime parsing patterns.
+            source_field: Optional source Arrow field/schema/type.
+            target_field: Optional target Arrow field/schema/type.
+            **kwargs: Additional CastOptions fields.
+
+        Returns:
+            CastOptions instance.
+        """
         built = CastOptions(
             safe=safe,
             add_missing_columns=add_missing_columns,
@@ -169,6 +187,14 @@ class CastOptions:
         return result
 
     def check_source(self, obj: Any):
+        """Set the source field if not already configured.
+
+        Args:
+            obj: Source object to infer from.
+
+        Returns:
+            Self.
+        """
         if self.source_field is not None or obj is None:
             return self
 
@@ -177,6 +203,14 @@ class CastOptions:
         return self
 
     def need_arrow_type_cast(self, source_obj: Any):
+        """Return True when Arrow type casting is required.
+
+        Args:
+            source_obj: Source object to compare types against.
+
+        Returns:
+            True if Arrow type cast needed.
+        """
         if self.target_field is None:
             return False
 
@@ -185,6 +219,14 @@ class CastOptions:
         return self.source_field.type != self.target_field.type
 
     def need_polars_type_cast(self, source_obj: Any):
+        """Return True when Polars dtype casting is required.
+
+        Args:
+            source_obj: Source object to compare types against.
+
+        Returns:
+            True if Polars type cast needed.
+        """
         if self.target_polars_field is None:
             return False
 
@@ -193,6 +235,14 @@ class CastOptions:
         return self.source_polars_field.dtype != self.target_polars_field.dtype
 
     def need_spark_type_cast(self, source_obj: Any):
+        """Return True when Spark datatype casting is required.
+
+        Args:
+            source_obj: Source object to compare types against.
+
+        Returns:
+            True if Spark type cast needed.
+        """
         if self.target_spark_field is None:
             return False
 
@@ -201,6 +251,14 @@ class CastOptions:
         return self.source_spark_field.dataType != self.target_spark_field.dataType
 
     def need_nullability_check(self, source_obj: Any):
+        """Return True when nullability checks are required.
+
+        Args:
+            source_obj: Source object to compare nullability against.
+
+        Returns:
+            True if nullability check needed.
+        """
         if self.target_field is None:
             return False
 
@@ -213,6 +271,15 @@ class CastOptions:
         arrow_field: pa.Field,
         index: int
     ):
+        """Return a child Arrow field by index for nested types.
+
+        Args:
+            arrow_field: Parent Arrow field.
+            index: Child index.
+
+        Returns:
+            Child Arrow field.
+        """
         source_type: Union[
             pa.DataType, pa.ListType, pa.StructType, pa.MapType
         ] = arrow_field.type
@@ -235,6 +302,11 @@ class CastOptions:
 
     @property
     def source_field(self):
+        """Return the configured source Arrow field.
+
+        Returns:
+            Source Arrow field.
+        """
         return self.source_arrow_field
 
     @source_field.setter
@@ -248,10 +320,23 @@ class CastOptions:
         object.__setattr__(self, "source_arrow_field", value)
 
     def source_child_arrow_field(self, index: int):
+        """Return a child source Arrow field by index.
+
+        Args:
+            index: Child index.
+
+        Returns:
+            Child Arrow field.
+        """
         return self._child_arrow_field(self.source_arrow_field, index=index)
 
     @property
     def source_polars_field(self):
+        """Return or compute the cached Polars field for the source.
+
+        Returns:
+            Polars field or None.
+        """
         if self.source_arrow_field is not None and self._source_polars_field is None:
             from ...types.cast.polars_cast import arrow_field_to_polars_field
 
@@ -260,6 +345,11 @@ class CastOptions:
 
     @property
     def source_spark_field(self):
+        """Return or compute the cached Spark field for the source.
+
+        Returns:
+            Spark field or None.
+        """
         if self.source_arrow_field is not None and self._source_spark_field is None:
             from ...types.cast.spark_cast import arrow_field_to_spark_field
 
@@ -275,6 +365,11 @@ class CastOptions:
 
     @property
     def target_field_name(self):
+        """Return the effective target field name.
+
+        Returns:
+            Target field name or None.
+        """
         if self.target_field is None:
             if self.source_field is not None:
                 return self.source_field.name
@@ -295,10 +390,23 @@ class CastOptions:
         object.__setattr__(self, "target_arrow_field", value)
 
     def target_child_arrow_field(self, index: int):
+        """Return a child target Arrow field by index.
+
+        Args:
+            index: Child index.
+
+        Returns:
+            Child Arrow field.
+        """
         return self._child_arrow_field(self.target_arrow_field, index=index)
 
     @property
     def target_polars_field(self):
+        """Return or compute the cached Polars field for the target.
+
+        Returns:
+            Polars field or None.
+        """
         if self.target_arrow_field is not None and self._target_polars_field is None:
             from ...types.cast.polars_cast import arrow_field_to_polars_field
 
@@ -307,6 +415,11 @@ class CastOptions:
 
     @property
     def target_spark_field(self):
+        """Return or compute the cached Spark field for the target.
+
+        Returns:
+            Spark field or None.
+        """
         if self.target_arrow_field is not None and self._target_spark_field is None:
             from ...types.cast.spark_cast import arrow_field_to_spark_field
 
@@ -329,6 +442,11 @@ class CastOptions:
 
     @property
     def target_spark_schema(self) -> Optional["pyspark.sql.types.StructType"]:
+        """Return a Spark schema view of the target Arrow schema.
+
+        Returns:
+            Spark StructType schema or None.
+        """
         arrow_schema = self.target_arrow_schema
 
         if arrow_schema is not None:
@@ -338,4 +456,4 @@ class CastOptions:
         return arrow_schema
 
 
-DEFAULT_INSTANCE = CastOptions()
+DEFAULT_INSTANCE = CastOptions()

yggdrasil/types/cast/pandas_cast.py

@@ -1,3 +1,5 @@
+"""Pandas <-> Arrow casting helpers and converters."""
+
 from typing import Optional
 
 import pyarrow as pa
@@ -33,18 +35,45 @@ if pandas is not None:
     PandasDataFrame = pandas.DataFrame
 
     def pandas_converter(*args, **kwargs):
+        """Return a register_converter wrapper when pandas is available.
+
+        Args:
+            *args: Converter registration args.
+            **kwargs: Converter registration kwargs.
+
+        Returns:
+            Converter decorator.
+        """
         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.
+
+        Args:
+            *_args: Ignored positional args.
+            **_kwargs: Ignored keyword args.
+
+        Returns:
+            No-op decorator.
+        """
         def _decorator(func):
+            """Return the function unchanged.
+
+            Args:
+                func: Callable to return.
+
+            Returns:
+                Unchanged callable.
+            """
             return func
 
         return _decorator

yggdrasil/types/cast/polars_cast.py

@@ -1,3 +1,5 @@
+"""Polars <-> Arrow casting helpers and converters."""
+
 from typing import Optional, Tuple, Union, Dict, Any
 
 import pyarrow as pa
@@ -79,12 +81,22 @@ if polars is not None:
     }
 
     def polars_converter(*args, **kwargs):
+        """Return a register_converter wrapper when polars is available.
+
+        Args:
+            *args: Converter registration args.
+            **kwargs: Converter registration kwargs.
+
+        Returns:
+            Converter decorator.
+        """
         return register_converter(*args, **kwargs)
 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
@@ -95,7 +107,24 @@ else:
     PolarsDataType = _PolarsDummy
 
     def polars_converter(*_args, **_kwargs):  # pragma: no cover - no-op decorator
+        """Return a no-op decorator when polars is unavailable.
+
+        Args:
+            *_args: Ignored positional args.
+            **_kwargs: Ignored keyword args.
+
+        Returns:
+            No-op decorator.
+        """
         def _decorator(func):
+            """Return the function unchanged.
+
+            Args:
+                func: Callable to return.
+
+            Returns:
+                Unchanged callable.
+            """
             return func
         return _decorator
 
@@ -171,6 +200,15 @@ def cast_to_list_array(
     array: PolarsSeries,
     options: Optional["CastOptions"] = None,
 ) -> PolarsSeries:
+    """Cast a Polars list series to a target list Arrow type.
+
+    Args:
+        array: Polars Series with list dtype.
+        options: Optional cast options.
+
+    Returns:
+        Casted Polars Series.
+    """
     options = CastOptions.check_arg(options)
 
     if not options.need_polars_type_cast(source_obj=array):
@@ -796,6 +834,15 @@ def polars_array_to_arrow_field(
     array: Union[PolarsSeries, PolarsExpr],
     options: Optional[CastOptions] = None
 ) -> pa.Field:
+    """Infer an Arrow field from a Polars Series or Expr.
+
+    Args:
+        array: Polars Series or Expr.
+        options: Optional cast options.
+
+    Returns:
+        Arrow field.
+    """
     options = CastOptions.check_arg(options)
 
     if options.source_arrow_field:

yggdrasil/types/cast/polars_pandas_cast.py

@@ -1,3 +1,5 @@
+"""Polars <-> pandas conversion helpers via Arrow."""
+
 from typing import Optional
 
 from .arrow_cast import CastOptions
@@ -35,18 +37,45 @@ if polars is not None and pandas is not None:
     PandasDataFrame = pandas.DataFrame
 
     def polars_pandas_converter(*args, **kwargs):
+        """Return a register_converter wrapper when both libs are available.
+
+        Args:
+            *args: Converter registration args.
+            **kwargs: Converter registration kwargs.
+
+        Returns:
+            Converter decorator.
+        """
         return register_converter(*args, **kwargs)
 
 else:
     # Dummy stand-ins so decorators/annotations don't explode if one lib is absent
     class _Dummy:  # pragma: no cover - only used when Polars or pandas not installed
+        """Placeholder type when Polars or pandas are unavailable."""
         pass
 
     PolarsDataFrame = _Dummy
     PandasDataFrame = _Dummy
 
     def polars_pandas_converter(*_args, **_kwargs):  # pragma: no cover - no-op decorator
+        """Return a no-op decorator when dependencies are missing.
+
+        Args:
+            *_args: Ignored positional args.
+            **_kwargs: Ignored keyword args.
+
+        Returns:
+            No-op decorator.
+        """
         def _decorator(func):
+            """Return the function unchanged.
+
+            Args:
+                func: Callable to return.
+
+            Returns:
+                Unchanged callable.
+            """
             return func
 
         return _decorator

yggdrasil/types/cast/registry.py

@@ -1,3 +1,5 @@
+"""Type conversion registry and default converters."""
+
 from __future__ import annotations
 
 import dataclasses as _dataclasses
@@ -31,6 +33,15 @@ __all__ = [
 
 
 def _identity(x, opt):
+    """Return the input value unchanged.
+
+    Args:
+        x: Value to return.
+        opt: Unused options parameter.
+
+    Returns:
+        The input value.
+    """
     return x
 
 ReturnType = TypeVar("ReturnType")
@@ -49,6 +60,14 @@ def register_converter(
     """
 
     def decorator(func: Callable[..., ReturnType]) -> Converter:
+        """Validate and register a converter function.
+
+        Args:
+            func: Converter function to register.
+
+        Returns:
+            Registered converter.
+        """
         sig = inspect.signature(func)
         params = list(sig.parameters.values())
         if any(
@@ -75,6 +94,14 @@ def register_converter(
 
 
 def _unwrap_optional(hint: Any) -> Tuple[bool, Any]:
+    """Return whether a hint is Optional and the underlying hint.
+
+    Args:
+        hint: Type hint to inspect.
+
+    Returns:
+        Tuple of (is_optional, base_hint).
+    """
     origin = get_origin(hint)
     if origin in {Union, types.UnionType}:
         args = get_args(hint)
@@ -114,6 +141,15 @@ def find_converter(
     from_type: Any,
     to_hint: Any
 ) -> Optional[Converter]:
+    """Find a registered converter for the requested type pair.
+
+    Args:
+        from_type: Source type.
+        to_hint: Target type hint.
+
+    Returns:
+        Converter function or None.
+    """
 
     # 0) Fast path: exact key
     conv = _registry.get((from_type, to_hint))
@@ -177,6 +213,17 @@ def find_converter(
 
             # Build composite converter once we find the first viable chain.
             def composed(value, options=None, _c1=conv1, _c2=conv2):
+                """Compose two converters into one.
+
+                Args:
+                    value: Value to convert.
+                    options: Cast options.
+                    _c1: First converter.
+                    _c2: Second converter.
+
+                Returns:
+                    Converted value.
+                """
                 intermediate = _c1(value, options)
                 return _c2(intermediate, options)
 
@@ -190,6 +237,14 @@ def find_converter(
 
 
 def _normalize_fractional_seconds(value: str) -> str:
+    """Normalize fractional seconds to microsecond precision.
+
+    Args:
+        value: Datetime string to normalize.
+
+    Returns:
+        Normalized datetime string.
+    """
     match = re.search(r"(\.)(\d+)(?=(?:[+-]\d{2}:?\d{2})?$)", value)
     if not match:
         return value
@@ -201,6 +256,14 @@ def _normalize_fractional_seconds(value: str) -> str:
 
 
 def is_runtime_value(x) -> bool:
+    """Return True when x is a runtime value, not a type hint.
+
+    Args:
+        x: Value or type hint to inspect.
+
+    Returns:
+        True if runtime value.
+    """
     # True for "42", [], MyClass(), etc.
     # False for MyClass, list[int], dict[str, int], etc.
     if inspect.isclass(x):
@@ -305,6 +368,16 @@ def convert_to_python_enum(
     target_hint: type,
     options: Optional[CastOptions] = None,
 ):
+    """Convert values into a Python Enum member.
+
+    Args:
+        value: Value to convert.
+        target_hint: Enum type.
+        options: Optional cast options.
+
+    Returns:
+        Enum member.
+    """
     if isinstance(value, target_hint):
         return value
 
@@ -343,6 +416,16 @@ def convert_to_python_dataclass(
     target_hint: type,
     options: Optional[CastOptions] = None,
 ):
+    """Convert a mapping into a dataclass instance.
+
+    Args:
+        value: Mapping of field values.
+        target_hint: Dataclass type.
+        options: Optional cast options.
+
+    Returns:
+        Dataclass instance.
+    """
     from yggdrasil.types.python_defaults import default_scalar
 
     if isinstance(value, target_hint):
@@ -385,6 +468,18 @@ def convert_to_python_iterable(
     target_args,
     options: Optional[CastOptions] = None,
 ):
+    """Convert iterable-like values into typed Python collections.
+
+    Args:
+        value: Iterable-like input value.
+        target_hint: Target type hint.
+        target_origin: Target container origin type.
+        target_args: Target type arguments.
+        options: Optional cast options.
+
+    Returns:
+        Converted iterable container.
+    """
     if isinstance(value, (str, bytes)):
         raise TypeError(f"No converter registered for {type(value)} -> {target_hint}")
 
@@ -411,6 +506,15 @@ def convert_to_python_iterable(
 
 @register_converter(str, int)
 def _str_to_int(value: str, cast_options: Any) -> int:
+    """Convert a string into an integer.
+
+    Args:
+        value: String to convert.
+        cast_options: Cast options.
+
+    Returns:
+        Integer value.
+    """
     if value == "":
         return 0
     return int(value)
@@ -418,6 +522,15 @@ def _str_to_int(value: str, cast_options: Any) -> int:
 
 @register_converter(str, float)
 def _str_to_float(value: str, cast_options: Any) -> float:
+    """Convert a string into a float.
+
+    Args:
+        value: String to convert.
+        cast_options: Cast options.
+
+    Returns:
+        Float value.
+    """
     default_value = getattr(cast_options, "default_value", None)
     if value == "" and default_value is not None:
         return default_value
@@ -426,6 +539,15 @@ def _str_to_float(value: str, cast_options: Any) -> float:
 
 @register_converter(str, bool)
 def _str_to_bool(value: str, cast_options: Any) -> bool:
+    """Convert a string into a boolean.
+
+    Args:
+        value: String to convert.
+        cast_options: Cast options.
+
+    Returns:
+        Boolean value.
+    """
     default_value = getattr(cast_options, "default_value", None)
     if value == "" and default_value is not None:
         return default_value
@@ -441,11 +563,29 @@ def _str_to_bool(value: str, cast_options: Any) -> bool:
 
 @register_converter(str, _datetime.date)
 def _str_to_date(value: str, cast_options: Any) -> _datetime.date:
+    """Convert a string into a date.
+
+    Args:
+        value: String to convert.
+        cast_options: Cast options.
+
+    Returns:
+        Date value.
+    """
     return _str_to_datetime(value, cast_options).date()
 
 
 @register_converter(str, _datetime.datetime)
 def _str_to_datetime(value: str, cast_options: Any) -> _datetime.datetime:
+    """Convert a string into a datetime.
+
+    Args:
+        value: String to convert.
+        cast_options: Cast options.
+
+    Returns:
+        Datetime value.
+    """
     default_value = getattr(cast_options, "default_value", None)
     if value == "" and default_value is not None:
         return default_value
@@ -488,6 +628,15 @@ def _str_to_datetime(value: str, cast_options: Any) -> _datetime.datetime:
 
 @register_converter(str, _datetime.timedelta)
 def _str_to_timedelta(value: str, cast_options: Any) -> _datetime.timedelta:
+    """Convert a string into a timedelta.
+
+    Args:
+        value: String to convert.
+        cast_options: Cast options.
+
+    Returns:
+        Timedelta value.
+    """
     default_value = getattr(cast_options, "default_value", None)
     stripped = value.strip()
 
@@ -545,6 +694,15 @@ def _str_to_timedelta(value: str, cast_options: Any) -> _datetime.timedelta:
 
 @register_converter(str, _datetime.time)
 def _str_to_time(value: str, cast_options: Any) -> _datetime.time:
+    """Convert a string into a time.
+
+    Args:
+        value: String to convert.
+        cast_options: Cast options.
+
+    Returns:
+        Time value.
+    """
     default_value = getattr(cast_options, "default_value", None)
     if value == "" and default_value is not None:
         return default_value
@@ -553,9 +711,27 @@ def _str_to_time(value: str, cast_options: Any) -> _datetime.time:
 
 @register_converter(_datetime.datetime, _datetime.date)
 def _datetime_to_date(value: _datetime.datetime, cast_options: Any) -> _datetime.date:
+    """Convert a datetime into a date.
+
+    Args:
+        value: Datetime value.
+        cast_options: Cast options.
+
+    Returns:
+        Date value.
+    """
     return value.date()
 
 
 @register_converter(int, str)
 def _int_to_str(value: int, cast_options: Any) -> str:
+    """Convert an integer into a string.
+
+    Args:
+        value: Integer to convert.
+        cast_options: Cast options.
+
+    Returns:
+        String value.
+    """
     return str(value)