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

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.33"

ygg-0.1.31.dist-info/RECORD

@@ -1,59 +0,0 @@
-ygg-0.1.31.dist-info/licenses/LICENSE,sha256=HrhfyXIkWY2tGFK11kg7vPCqhgh5DcxleloqdhrpyMY,11558
-yggdrasil/__init__.py,sha256=6OPibApplA5TF4TeixkQO_qewpaAidYX-fSDvvKYcTI,91
-yggdrasil/databricks/__init__.py,sha256=aGVve5mpoQtxSK2nfzrexjRPoutCIyaOnKZijkG4_QE,92
-yggdrasil/databricks/compute/__init__.py,sha256=TVDwPmW2SOmHmnhzZhsvrWbrxZ_lEcgqe3l9BeB-oxM,218
-yggdrasil/databricks/compute/cluster.py,sha256=P4e4eBSSSykO8lzrGLLfHEZukObqcnJgCoHhSGPh9Ko,28999
-yggdrasil/databricks/compute/execution_context.py,sha256=ecpjx1smGYu85Gv57SUM9T1Yo3n71gyRhAVqbe7X4-0,18677
-yggdrasil/databricks/compute/remote.py,sha256=f8IJpPmEjXQh8toaS5Kt8rxkeVph7Uxrcv7utKjnT1I,1347
-yggdrasil/databricks/jobs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-yggdrasil/databricks/jobs/config.py,sha256=FI2fiiXcxps-aRRfcqqQCqnnYj_TUHQNVJMBxQBe_OU,10693
-yggdrasil/databricks/sql/__init__.py,sha256=JZpQ9eCphDf1l4yzIZ7a7OLigxqXkqOgb0Mio7Rj09A,181
-yggdrasil/databricks/sql/engine.py,sha256=edNXVdAwjfGENegoeE8cq1mxelaqsUJFtf57puZFEpY,30894
-yggdrasil/databricks/sql/exceptions.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-yggdrasil/databricks/sql/statement_result.py,sha256=sqg3hLG-0vmMZSqQEf5QEbmb3CPvBwBKov7hPc_cPlo,12909
-yggdrasil/databricks/sql/types.py,sha256=nkoLNCan5tGRFq_rQJUz2mbz5bjr8effHvm4Gkuaf68,5661
-yggdrasil/databricks/workspaces/__init__.py,sha256=9Hk1csqJp2UiaAS5MZ7oz6KHh9JNo7A4Vo1xf61y2DM,68
-yggdrasil/databricks/workspaces/filesytem.py,sha256=e7oWaLdbhnl8evl2AjTUdhnITMem3ry2WmOFO4CQ02g,4761
-yggdrasil/databricks/workspaces/io.py,sha256=tGyjB5MWJK01lgeZC2my8mlyEEfpS9f-2MidTJNtlCI,21363
-yggdrasil/databricks/workspaces/path.py,sha256=MEPck7V0Pc92JGzgkFz5b6p8rH1m_otmewGttsAs_nQ,39091
-yggdrasil/databricks/workspaces/path_kind.py,sha256=S7f9jKLeceQNc6uZu9safASkZqHfKU-06Pq_3ixtfIU,174
-yggdrasil/databricks/workspaces/workspace.py,sha256=vVm4hD3_Bjv3qRGz6Q03LgNCaIithaJJCCAVVYTYWKM,17563
-yggdrasil/dataclasses/__init__.py,sha256=QVAvZnNl7gFYTLOVTfMkdQZf6o_WL8_UuDV1uTZ7Aeg,67
-yggdrasil/dataclasses/dataclass.py,sha256=ln-D1-bbiCLBd2khRMGs4dFoxzJEEGzHTKekWCnF2uk,5436
-yggdrasil/libs/__init__.py,sha256=88VTVKz8pnB8JSit6rlNzFm9O1ORyxqh0TQ7OBkXkQo,104
-yggdrasil/libs/databrickslib.py,sha256=H8AfQ2QU0F_dzZSsY5wfUh6cyMFB08YBKy-MBmqHCnU,667
-yggdrasil/libs/pandaslib.py,sha256=CIpYDhyhif5GLVLkfUWjZrnkM9hOxVM2DTZKw3bsZB4,360
-yggdrasil/libs/polarslib.py,sha256=SZlUSWjjXPC47S4a-6P-UNx3q8gNgcb6FOlkB7XpRxQ,362
-yggdrasil/libs/sparklib.py,sha256=1uXwNQX6jks4-o11yQF5DYex7a1tux5x2K2QVQF_plY,8996
-yggdrasil/libs/extensions/__init__.py,sha256=qkkRF1BQ_NLZlKeeZeeZDAbf9Q3wQXu5s4OmCggf51U,67
-yggdrasil/libs/extensions/polars_extensions.py,sha256=kojeJOW5VPBXMVTJT2gWUJypNuryq9ZeXmH-VZXgXoM,10531
-yggdrasil/libs/extensions/spark_extensions.py,sha256=uCcpLJr0wEE9V_-nc8DrQtAh9n2Q4mV_NicU-DNGG54,13396
-yggdrasil/pyutils/__init__.py,sha256=-aU5Y1huWoTLTPdSDxZM7QU0p0sTYj5j77cP833RsnQ,139
-yggdrasil/pyutils/callable_serde.py,sha256=P3hqCAtQQJTEh7-QTISIX-Viq9Oi51RVMKLK9RKMY7s,18083
-yggdrasil/pyutils/exceptions.py,sha256=Kt4xY4jPv-Ld8vBJaiQy51xbewD6Q-3bZkaa3THsFNM,2891
-yggdrasil/pyutils/modules.py,sha256=N7_YVKlWt_S_1GdHGGw1Lq2xtOI3RiyqaScL-R9BlkU,10208
-yggdrasil/pyutils/parallel.py,sha256=L2r4_iumOzDk7omWVBPYmT5U8n7suOdv1AFpa_ghHSY,5902
-yggdrasil/pyutils/python_env.py,sha256=hq4DynrxuChqAhi8P3blDdOKSRw0X7yO96ysf9_4ZzY,42641
-yggdrasil/pyutils/retry.py,sha256=1zjascEsffvnkVRdHhdeoenk6tBPrzrj4VhBltbhBeU,10390
-yggdrasil/requests/__init__.py,sha256=THJz1IoZYQccwmXcQR3N8D-uWxCkfMtgeXDhONdERR8,41
-yggdrasil/requests/msal.py,sha256=ucnN45iZZpbXkByw212PX4shH4g0EeyrW8JEmfimWtY,5861
-yggdrasil/requests/session.py,sha256=YomLcDf8O_mc8BUnf9fr5wrupDnxEzaGw-guhV91NsE,830
-yggdrasil/types/__init__.py,sha256=p0Qu_69RkePPgQGM9nSue_bcbEIAM2u9eo3zsEplHJ8,82
-yggdrasil/types/libs.py,sha256=7-p0M4C6TnEWpUGf2nY4XshhJxtXOE_-bsYmJWU6jtk,227
-yggdrasil/types/python_arrow.py,sha256=1Ac1ZnEgmH4nLNBfrfbM6E9EfANGWtdANqlwMENQkTw,21408
-yggdrasil/types/python_defaults.py,sha256=7t0GMdgn1yJ-xhObeD3-vP091e6tdPl6qrm-wU7bbqw,8390
-yggdrasil/types/cast/__init__.py,sha256=2qiXTrUk7HRcdN8ZuDDUxSDCkqJfAfuwG0M1XA7rTzk,240
-yggdrasil/types/cast/arrow_cast.py,sha256=1brucYDBLJ9MUjQQ4ura2slIW2lUApzTc_7efq043fg,38664
-yggdrasil/types/cast/cast_options.py,sha256=R758Gfv3latG6hq_xrB4hbNPHPL51D-euwIvKEY8YYw,12149
-yggdrasil/types/cast/pandas_cast.py,sha256=-DlaZxGmisIklsZElUZI3g6nrj4R-xNDTI7q01IMB6g,7889
-yggdrasil/types/cast/polars_cast.py,sha256=Z48vvAVyRYZVYabiad22e3tn44tZ1iaSJgOOoJ1MorU,27523
-yggdrasil/types/cast/polars_pandas_cast.py,sha256=EV8zJ_AOtuxj_2lgeB-t7T0ofT9M5WcAcfoTjHSar3s,4249
-yggdrasil/types/cast/registry.py,sha256=-88mq-U1pDSGbEC9PRY0zJCzloyBodXgeSRBPb6hz78,17582
-yggdrasil/types/cast/spark_cast.py,sha256=IHthM78dugabGXxNNW9sSHn-olDwzXcFdIFcPo9IiXU,23021
-yggdrasil/types/cast/spark_pandas_cast.py,sha256=8PgJItF_XbyBcNuBnXkMQU3PBy3sAPEXZT9SXL2WbU4,4200
-yggdrasil/types/cast/spark_polars_cast.py,sha256=ba1UOvY1ouGCro1Np9slXmJ4TEyWnUtwVEAwxGvPLlk,8336
-ygg-0.1.31.dist-info/METADATA,sha256=6xmpGqSGuLKSCgOJkXoMJz3gHI4494h9fCT8Mx5daEQ,19204
-ygg-0.1.31.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ygg-0.1.31.dist-info/entry_points.txt,sha256=6q-vpWG3kvw2dhctQ0LALdatoeefkN855Ev02I1dKGY,70
-ygg-0.1.31.dist-info/top_level.txt,sha256=iBe9Kk4VIVbLpgv_p8OZUIfxgj4dgJ5wBg6vO3rigso,10
-ygg-0.1.31.dist-info/RECORD,,