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

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)

yggdrasil/types/cast/spark_cast.py

@@ -1,3 +1,5 @@
+"""Spark <-> Arrow casting helpers and converters."""
+
 from typing import Optional, Tuple, List
 
 import pyarrow as pa
@@ -57,10 +59,20 @@ if pyspark is not None:
     SparkStructField = T.StructField
 
     def spark_converter(*args, **kwargs):
+        """Return a register_converter wrapper when pyspark is available.
+
+        Args:
+            *args: Converter registration args.
+            **kwargs: Converter registration kwargs.
+
+        Returns:
+            Converter decorator.
+        """
         return register_converter(*args, **kwargs)
 
 else:  # pyspark missing -> dummies + no-op decorator
     class _SparkDummy:  # pragma: no cover
+        """Placeholder type for Spark symbols when pyspark is unavailable."""
         pass
 
     SparkDataFrame = _SparkDummy
@@ -70,7 +82,24 @@ else:  # pyspark missing -> dummies + no-op decorator
     SparkStructField = _SparkDummy
 
     def spark_converter(*_args, **_kwargs):  # pragma: no cover
+        """Return a no-op decorator when pyspark 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
@@ -227,6 +256,17 @@ def check_column_nullability(
     target_field: "T.StructField",
     mask: "pyspark.sql.Column"
 ) -> "pyspark.sql.Column":
+    """Fill nulls when the target field is non-nullable.
+
+    Args:
+        column: Spark column to adjust.
+        source_field: Source Spark field.
+        target_field: Target Spark field.
+        mask: Null mask column.
+
+    Returns:
+        Updated Spark column.
+    """
     source_nullable = True if source_field is None else source_field.nullable
     target_nullable = True if target_field is None else target_field.nullable
 
@@ -532,6 +572,15 @@ def spark_dataframe_to_spark_type(
     df: SparkDataFrame,
     options: Optional[CastOptions] = None,
 ) -> pa.DataType:
+    """Return the Spark DataFrame schema as a Spark data type.
+
+    Args:
+        df: Spark DataFrame.
+        options: Optional cast options.
+
+    Returns:
+        Spark DataType.
+    """
     return df.schema
 
 
@@ -540,6 +589,15 @@ def spark_dataframe_to_spark_field(
     df: SparkDataFrame,
     options: Optional[CastOptions] = None,
 ) -> pa.DataType:
+    """Return a Spark StructField for the DataFrame schema.
+
+    Args:
+        df: Spark DataFrame.
+        options: Optional cast options.
+
+    Returns:
+        Spark StructField.
+    """
     return SparkStructField(
         df.getAlias() or "root",
         df.schema,
@@ -552,6 +610,15 @@ def spark_dataframe_to_arrow_field(
     df: SparkDataFrame,
     options: Optional[CastOptions] = None,
 ) -> pa.DataType:
+    """Return an Arrow field representation of the DataFrame schema.
+
+    Args:
+        df: Spark DataFrame.
+        options: Optional cast options.
+
+    Returns:
+        Arrow field.
+    """
     return spark_field_to_arrow_field(
         spark_dataframe_to_spark_field(df, options),
         options
@@ -563,6 +630,15 @@ def spark_dataframe_to_arrow_schema(
     df: SparkDataFrame,
     options: Optional[CastOptions] = None,
 ) -> pa.DataType:
+    """Return an Arrow schema representation of the DataFrame.
+
+    Args:
+        df: Spark DataFrame.
+        options: Optional cast options.
+
+    Returns:
+        Arrow schema.
+    """
     return arrow_field_to_schema(
         spark_field_to_arrow_field(
             spark_dataframe_to_spark_field(df, options),

yggdrasil/types/cast/spark_pandas_cast.py

@@ -1,3 +1,5 @@
+"""Spark <-> pandas conversion helpers via Arrow."""
+
 from typing import Optional
 
 from .arrow_cast import CastOptions
@@ -34,18 +36,45 @@ if pyspark is not None and pandas is not None:
     PandasDataFrame = pandas.DataFrame
 
     def spark_pandas_converter(*args, **kwargs):
+        """Return a register_converter wrapper when dependencies 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 Spark or pandas not installed
+        """Placeholder type when Spark or pandas are unavailable."""
         pass
 
     SparkDataFrame = _Dummy
     PandasDataFrame = _Dummy
 
     def spark_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/spark_polars_cast.py

@@ -1,3 +1,5 @@
+"""Spark <-> Polars conversion helpers via Arrow."""
+
 from typing import Optional
 
 import pyarrow as pa
@@ -23,10 +25,36 @@ __all__ = [
 # ---------------------------------------------------------------------------
 if pyspark is not None and polars is not None:
     def spark_polars_converter(*args, **kwargs):
+        """Return a register_converter wrapper when deps are available.
+
+        Args:
+            *args: Converter registration args.
+            **kwargs: Converter registration kwargs.
+
+        Returns:
+            Converter decorator.
+        """
         return register_converter(*args, **kwargs)
 else:
     def spark_polars_converter(*_args, **_kwargs):  # pragma: no cover - no-op decorator
+        """Return a no-op decorator when deps 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