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

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

yggdrasil/types/libs.py

@@ -1,3 +1,5 @@
+"""Re-export optional dependency helpers for types modules."""
+
 from ..libs import pandas, polars, pyspark, require_pandas, require_polars, require_pyspark
 
 __all__ = [

yggdrasil/types/python_arrow.py

@@ -1,3 +1,5 @@
+"""Arrow type inference utilities from Python type hints."""
+
 import dataclasses
 import datetime
 import decimal
@@ -57,6 +59,14 @@ _INT_UNITS_ORDER = {"s": 0, "ms": 1, "us": 2, "ns": 3}
 
 
 def _is_optional(hint) -> bool:
+    """Return True when the hint includes None.
+
+    Args:
+        hint: Type hint to inspect.
+
+    Returns:
+        True if Optional.
+    """
     origin = get_origin(hint)
 
     if origin is Annotated:
@@ -69,6 +79,14 @@ def _is_optional(hint) -> bool:
 
 
 def _strip_optional(hint):
+    """Return the underlying hint without Optional[...].
+
+    Args:
+        hint: Type hint to inspect.
+
+    Returns:
+        Hint without Optional wrapper.
+    """
     origin = get_origin(hint)
 
     if origin is Annotated:
@@ -89,6 +107,15 @@ def _strip_optional(hint):
 
 
 def _field_name(hint, index: int | None) -> str:
+    """Derive a field name from a hint and optional index.
+
+    Args:
+        hint: Type hint to inspect.
+        index: Optional positional index.
+
+    Returns:
+        Field name string.
+    """
     name = getattr(hint, "__name__", None)
 
     if name:
@@ -101,6 +128,14 @@ def _field_name(hint, index: int | None) -> str:
 
 
 def _struct_from_dataclass(hint) -> pa.StructType:
+    """Build an Arrow struct type from a dataclass.
+
+    Args:
+        hint: Dataclass type.
+
+    Returns:
+        Arrow StructType.
+    """
     fields = []
 
     for field in dataclasses.fields(hint):
@@ -113,6 +148,15 @@ def _struct_from_dataclass(hint) -> pa.StructType:
 
 
 def _struct_from_tuple(args, names: list[str] | None = None) -> pa.StructType:
+    """Build an Arrow struct type from tuple hints.
+
+    Args:
+        args: Tuple element type hints.
+        names: Optional field names.
+
+    Returns:
+        Arrow StructType.
+    """
     if names is not None and len(names) != len(args):
         raise TypeError("Tuple metadata names length must match tuple elements")
 
@@ -125,6 +169,15 @@ def _struct_from_tuple(args, names: list[str] | None = None) -> pa.StructType:
 
 
 def _arrow_type_from_metadata(base_hint, metadata):
+    """Resolve an Arrow type from Annotated metadata when present.
+
+    Args:
+        base_hint: Base Python type hint.
+        metadata: Annotated metadata sequence.
+
+    Returns:
+        Arrow DataType or None.
+    """
     merged_metadata: dict[str, Any] = {}
 
     for item in metadata:
@@ -187,6 +240,14 @@ def _arrow_type_from_metadata(base_hint, metadata):
 
 
 def _arrow_type_from_hint(hint):
+    """Infer an Arrow data type from a Python type hint.
+
+    Args:
+        hint: Python type hint.
+
+    Returns:
+        Arrow DataType.
+    """
     if get_origin(hint) is Annotated:
         base_hint, *metadata = get_args(hint)
         metadata_type = _arrow_type_from_metadata(base_hint, metadata)
@@ -229,6 +290,16 @@ def _arrow_type_from_hint(hint):
 
 
 def arrow_field_from_hint(hint, name: str | None = None, index: int | None = None) -> pa.Field:
+    """Build an Arrow field from a Python type hint.
+
+    Args:
+        hint: Python type hint.
+        name: Optional field name override.
+        index: Optional positional index.
+
+    Returns:
+        Arrow field.
+    """
     nullable = _is_optional(hint)
     base_hint = _strip_optional(hint) if nullable else hint
 
@@ -269,6 +340,15 @@ def is_arrow_type_binary_like(arrow_type: pa.DataType) -> bool:
 
 
 def _merge_metadata(left: Optional[Dict[bytes, bytes]], right: Optional[Dict[bytes, bytes]]) -> Optional[Dict[bytes, bytes]]:
+    """Merge Arrow field metadata with right-hand precedence.
+
+    Args:
+        left: Left metadata mapping.
+        right: Right metadata mapping.
+
+    Returns:
+        Merged metadata mapping or None.
+    """
     if not left and not right:
         return None
     out: Dict[bytes, bytes] = {}
@@ -281,31 +361,87 @@ def _merge_metadata(left: Optional[Dict[bytes, bytes]], right: Optional[Dict[byt
 
 
 def _is_null(dt: pa.DataType) -> bool:
+    """Return True when the Arrow type is null.
+
+    Args:
+        dt: Arrow data type.
+
+    Returns:
+        True if null type.
+    """
     return pa.types.is_null(dt)
 
 
 def _is_integer(dt: pa.DataType) -> bool:
+    """Return True when the Arrow type is integer-like.
+
+    Args:
+        dt: Arrow data type.
+
+    Returns:
+        True if integer type.
+    """
     return pa.types.is_integer(dt)
 
 
 def _is_signed_integer(dt: pa.DataType) -> bool:
+    """Return True when the Arrow type is signed integer.
+
+    Args:
+        dt: Arrow data type.
+
+    Returns:
+        True if signed integer.
+    """
     return pa.types.is_signed_integer(dt)
 
 
 def _is_unsigned_integer(dt: pa.DataType) -> bool:
+    """Return True when the Arrow type is unsigned integer.
+
+    Args:
+        dt: Arrow data type.
+
+    Returns:
+        True if unsigned integer.
+    """
     return pa.types.is_unsigned_integer(dt)
 
 
 def _is_floating(dt: pa.DataType) -> bool:
+    """Return True when the Arrow type is floating-point.
+
+    Args:
+        dt: Arrow data type.
+
+    Returns:
+        True if floating type.
+    """
     return pa.types.is_floating(dt)
 
 
 def _int_bit_width(dt: pa.DataType) -> int:
+    """Return the bit width of an integer Arrow type.
+
+    Args:
+        dt: Arrow data type.
+
+    Returns:
+        Bit width.
+    """
     # int8/int16/int32/int64/uint8/...
     return dt.bit_width
 
 
 def _digits_for_uint_bits(bits: int) -> int:
+    """Return a safe decimal digit count for unsigned integer bits.
+
+    Args:
+        bits: Unsigned bit width.
+
+    Returns:
+        Decimal digit count.
+    """
     # max uint bits -> decimal digits upper bound:
     # uint64 max = 18446744073709551615 => 20 digits
     # 2**bits - 1 has ceil(bits*log10(2)) digits, use safe upper bound
@@ -364,10 +500,27 @@ def _promote_int_types(left: pa.DataType, right: pa.DataType) -> pa.DataType:
 
 def _promote_decimal_types(left: pa.Decimal128Type | pa.Decimal256Type,
                            right: pa.Decimal128Type | pa.Decimal256Type) -> pa.DataType:
+    """Return a decimal type that can represent both inputs.
+
+    Args:
+        left: Left decimal type.
+        right: Right decimal type.
+
+    Returns:
+        Promoted decimal Arrow type.
+    """
     # Match scale, then set precision to fit both after scale alignment.
     scale = max(left.scale, right.scale)
 
     def adj_precision(d: pa.DataType) -> int:
+        """Adjust precision to account for scale differences.
+
+        Args:
+            d: Decimal Arrow type.
+
+        Returns:
+            Adjusted precision.
+        """
         # Increasing scale can require increasing precision to keep same integer digits.
         # integer_digits = precision - scale
         integer_digits = d.precision - d.scale
@@ -382,6 +535,15 @@ def _promote_decimal_types(left: pa.Decimal128Type | pa.Decimal256Type,
 
 
 def _promote_numeric(left: pa.DataType, right: pa.DataType) -> pa.DataType:
+    """Promote numeric Arrow types to a common compatible type.
+
+    Args:
+        left: Left Arrow data type.
+        right: Right Arrow data type.
+
+    Returns:
+        Promoted Arrow data type.
+    """
     # decimal dominates ints/floats if present? Depends on your semantics.
     # Here: decimals keep exactness when mixing with ints; floats win when mixing float+anything non-decimal.
     if pa.types.is_decimal(left) and pa.types.is_decimal(right):
@@ -409,6 +571,15 @@ def _promote_numeric(left: pa.DataType, right: pa.DataType) -> pa.DataType:
 
 
 def _merge_time_units(left_unit: str, right_unit: str) -> str:
+    """Return the finer-grained Arrow time unit of two units.
+
+    Args:
+        left_unit: Left time unit.
+        right_unit: Right time unit.
+
+    Returns:
+        Selected time unit.
+    """
     # choose finer resolution (higher order index)
     return left_unit if _INT_UNITS_ORDER[left_unit] >= _INT_UNITS_ORDER[right_unit] else right_unit
 
@@ -418,6 +589,16 @@ def merge_arrow_types(
     right: Union[pa.DataType, pa.TimestampType, pa.ListType, pa.MapType, pa.StructType],
     add_missing_columns: bool = True
 ) -> pa.DataType:
+    """Merge two Arrow types into a compatible supertype.
+
+    Args:
+        left: Left Arrow data type.
+        right: Right Arrow data type.
+        add_missing_columns: Whether to include missing struct fields.
+
+    Returns:
+        Merged Arrow data type.
+    """
     # null is identity
     if _is_null(left):
         return right
@@ -563,6 +744,16 @@ def merge_arrow_fields(
     right: pa.Field,
     add_missing_columns: bool = True
 ) -> pa.Field:
+    """Merge two Arrow fields into a compatible field.
+
+    Args:
+        left: Left Arrow field.
+        right: Right Arrow field.
+        add_missing_columns: Whether to include missing struct fields.
+
+    Returns:
+        Merged Arrow field.
+    """
     if left.name != right.name:
         raise TypeError(f"Cannot merge fields with different names: {left.name!r} vs {right.name!r}")
 

yggdrasil/types/python_defaults.py

@@ -1,3 +1,5 @@
+"""Default value helpers for Python and Arrow types."""
+
 import dataclasses
 import datetime
 import decimal
@@ -96,6 +98,14 @@ except ImportError:
     _POLARS_DEFAULTS = {}
 
 def _is_optional(hint) -> bool:
+    """Return True when the type hint is Optional.
+
+    Args:
+        hint: Type hint to inspect.
+
+    Returns:
+        True if Optional.
+    """
     origin = get_origin(hint)
 
     if origin in (Union, types.UnionType):
@@ -105,6 +115,14 @@ def _is_optional(hint) -> bool:
 
 
 def _default_for_collection(origin):
+    """Return default values for collection-like origins.
+
+    Args:
+        origin: Collection origin type.
+
+    Returns:
+        Default collection instance or None.
+    """
     if origin in (list, MutableSequence):
         return []
 
@@ -124,6 +142,14 @@ def _default_for_collection(origin):
 
 
 def _default_for_tuple_args(args):
+    """Return a default tuple based on element hints.
+
+    Args:
+        args: Tuple element type hints.
+
+    Returns:
+        Default tuple instance.
+    """
     if not args:
         return tuple()
 
@@ -134,6 +160,14 @@ def _default_for_tuple_args(args):
 
 
 def _default_for_dataclass(hint):
+    """Return a default instance for a dataclass type.
+
+    Args:
+        hint: Dataclass type.
+
+    Returns:
+        Dataclass instance with default values.
+    """
     kwargs = {}
 
     for field in dataclasses.fields(hint):
@@ -156,6 +190,15 @@ def default_arrow_scalar(
     dtype: Union[pa.DataType, pa.ListType, pa.MapType, pa.StructType, pa.FixedSizeListType],
     nullable: bool
 ):
+    """Return a default scalar for a given Arrow type.
+
+    Args:
+        dtype: Arrow data type.
+        nullable: Whether the scalar should be nullable.
+
+    Returns:
+        Arrow scalar default.
+    """
     if nullable:
         return pa.scalar(None, type=dtype)
 
@@ -208,6 +251,19 @@ def default_arrow_array(
     chunks: Optional[List[int]] = None,
     scalar_default: Optional[pa.Scalar] = None,
 ) -> Union[pa.Array, pa.ChunkedArray]:
+    """Return a default Arrow array or chunked array for a given type.
+
+    Args:
+        dtype: Arrow data type.
+        nullable: Whether values are nullable.
+        size: Number of elements.
+        memory_pool: Optional Arrow memory pool.
+        chunks: Optional chunk sizes.
+        scalar_default: Optional scalar default override.
+
+    Returns:
+        Arrow array or chunked array.
+    """
     if scalar_default is None:
         scalar_default = default_arrow_scalar(dtype=dtype, nullable=nullable)
 
@@ -240,6 +296,14 @@ def default_arrow_array(
 
 
 def default_python_scalar(hint: Any):
+    """Return a default Python value for the given type hint.
+
+    Args:
+        hint: Type hint to generate defaults for.
+
+    Returns:
+        Default Python value.
+    """
     if _is_optional(hint):
         return None
 
@@ -286,6 +350,15 @@ def default_scalar(
     ],
     nullable: Optional[bool] = None
 ):
+    """Return a default scalar value for Python or Arrow type hints.
+
+    Args:
+        hint: Python type or Arrow type/field.
+        nullable: Override nullability for Arrow types.
+
+    Returns:
+        Default scalar value.
+    """
     if isinstance(hint, pa.Field):
         nullable = hint.nullable if nullable is None else nullable
         return default_arrow_scalar(dtype=hint.type, nullable=nullable)

yggdrasil/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.32"