dycw-utilities 0.109.7__tar.gz → 0.109.9__tar.gz

{dycw_utilities-0.109.7 → dycw_utilities-0.109.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.109.7
+Version: 0.109.9
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12

{dycw_utilities-0.109.7 → dycw_utilities-0.109.9}/pyproject.toml

@@ -89,7 +89,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.109.7"
+version = "0.109.9"
 
 [project.optional-dependencies]
 test = [
@@ -332,7 +332,7 @@ zzz-test-zoneinfo = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.109.7"
+current_version = "0.109.9"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"

{dycw_utilities-0.109.7 → dycw_utilities-0.109.9}/src/tests/test_parse.py

@@ -14,9 +14,14 @@ from pytest import raises
 from tests.test_operator import TruthEnum
 from tests.test_typing_funcs.with_future import (
     DataClassFutureInt,
+    DataClassFutureIntEven,
+    DataClassFutureIntEvenOrOddTypeUnion,
+    DataClassFutureIntEvenOrOddUnion,
+    DataClassFutureIntOdd,
     TrueOrFalseFutureLit,
     TrueOrFalseFutureTypeLit,
 )
+from utilities.errors import ImpossibleCaseError
 from utilities.functions import ensure_path
 from utilities.hypothesis import (
     datetime_durations,
@@ -78,7 +83,7 @@ class TestParseText:
         assert result is truth
 
     @given(value=integers())
-    def test_extra(self, *, value: int) -> None:
+    def test_extra_type(self, *, value: int) -> None:
         text = str(value)
         result = parse_text(
             DataClassFutureInt,
@@ -200,6 +205,60 @@ class TestParseText:
         result = parse_text(TrueOrFalseFutureTypeLit, truth)
         assert result == truth
 
+    @given(value=integers())
+    def test_type_union_with_extra(self, *, value: int) -> None:
+        def parse_even_or_odd(text: str, /) -> DataClassFutureIntEvenOrOddTypeUnion:
+            value = int(text)
+            match value % 2:
+                case 0:
+                    return DataClassFutureIntEven(even_int=value)
+                case 1:
+                    return DataClassFutureIntOdd(odd_int=value)
+                case _:
+                    raise ImpossibleCaseError(case=[f"{value=}"])
+
+        text = str(value)
+        result = parse_text(
+            DataClassFutureIntEvenOrOddTypeUnion,
+            text,
+            extra={DataClassFutureIntEvenOrOddTypeUnion: parse_even_or_odd},
+        )
+        match value % 2:
+            case 0:
+                expected = DataClassFutureIntEven(even_int=value)
+            case 1:
+                expected = DataClassFutureIntOdd(odd_int=value)
+            case _:
+                raise ImpossibleCaseError(case=[f"{value=}"])
+        assert result == expected
+
+    @given(value=integers())
+    def test_union_with_extra(self, *, value: int) -> None:
+        def parse_even_or_odd(text: str, /) -> DataClassFutureIntEvenOrOddUnion:
+            value = int(text)
+            match value % 2:
+                case 0:
+                    return DataClassFutureIntEven(even_int=value)
+                case 1:
+                    return DataClassFutureIntOdd(odd_int=value)
+                case _:
+                    raise ImpossibleCaseError(case=[f"{value=}"])
+
+        text = str(value)
+        result = parse_text(
+            DataClassFutureIntEvenOrOddUnion,
+            text,
+            extra={DataClassFutureIntEvenOrOddUnion: parse_even_or_odd},
+        )
+        match value % 2:
+            case 0:
+                expected = DataClassFutureIntEven(even_int=value)
+            case 1:
+                expected = DataClassFutureIntOdd(odd_int=value)
+            case _:
+                raise ImpossibleCaseError(case=[f"{value=}"])
+        assert result == expected
+
     @given(version=versions())
     def test_version(self, *, version: Version) -> None:
         text = str(version)
@@ -272,6 +331,13 @@ class TestParseText:
                 },
             )
 
+    def test_error_union_type_extra(self) -> None:
+        with raises(
+            _ParseTextParseError,
+            match=r"Unable to parse tests\.test_typing_funcs\.with_future\.DataClassFutureIntEven \| tests\.test_typing_funcs\.with_future\.DataClassFutureIntOdd; got 'invalid'",
+        ):
+            _ = parse_text(DataClassFutureIntEvenOrOddUnion, "invalid", extra={})
+
     def test_error_float(self) -> None:
         with raises(
             _ParseTextParseError, match="Unable to parse <class 'float'>; got 'invalid'"
@@ -364,9 +430,10 @@ class TestParseText:
 
     def test_error_unknown_union_type(self) -> None:
         with raises(
-            _ParseTextParseError, match=r"Unable to parse <class '.*'>; got 'invalid'"
+            _ParseTextParseError,
+            match=r"Unable to parse tests\.test_typing_funcs\.with_future\.DataClassFutureIntEven \| tests\.test_typing_funcs\.with_future\.DataClassFutureIntOdd; got 'invalid'",
         ):
-            _ = parse_text(DataClassFutureInt | DataClassFutureInt, "invalid")
+            _ = parse_text(DataClassFutureIntEvenOrOddUnion, "invalid")
 
     def test_error_version(self) -> None:
         with raises(

{dycw_utilities-0.109.7 → dycw_utilities-0.109.9}/src/tests/test_polars.py

@@ -11,6 +11,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any, ClassVar, Literal, cast
 from uuid import UUID, uuid4
 
+import hypothesis.strategies
 import polars as pl
 from hypothesis import given
 from hypothesis.strategies import (
@@ -20,7 +21,6 @@ from hypothesis.strategies import (
     data,
     fixed_dictionaries,
     floats,
-    integers,
     lists,
     none,
     sampled_from,
@@ -50,10 +50,12 @@ from polars import (
 from polars.testing import assert_frame_equal, assert_series_equal
 from pytest import raises
 
+import utilities.polars
 from utilities.datetime import get_now, get_today
 from utilities.hypothesis import (
     assume_does_not_raise,
     int64s,
+    pairs,
     text_ascii,
     zoned_datetimes,
 )
@@ -129,11 +131,13 @@ from utilities.polars import (
     map_over_columns,
     nan_sum_agg,
     nan_sum_cols,
+    normal,
     replace_time_zone,
     set_first_row_as_columns,
     struct_dtype,
     struct_from_dataclass,
     touch,
+    uniform,
     unique_element,
     week_num,
     yield_struct_series_dataclasses,
@@ -1210,7 +1214,7 @@ class TestGetDataTypeOrSeriesTimeZone:
 
 
 class TestGetSeriesNumberOfDecimals:
-    @given(data=data(), n=integers(1, 10), nullable=booleans())
+    @given(data=data(), n=hypothesis.strategies.integers(1, 10), nullable=booleans())
     def test_main(self, *, data: DataObject, n: int, nullable: bool) -> None:
         strategy = int64s() | none() if nullable else int64s()
         ints_or_none = data.draw(lists(strategy, min_size=1, max_size=10))
@@ -1312,6 +1316,37 @@ class TestInsertBetween:
             _ = insert_between(self.df, "a", "c", lit(None).alias("new"))
 
 
+class TestIntegers:
+    @given(
+        length=hypothesis.strategies.integers(0, 10),
+        high=hypothesis.strategies.integers(1, 10),
+    )
+    def test_int(self, *, length: int, high: int) -> None:
+        series = utilities.polars.integers(length, high)
+        assert series.len() == length
+        assert series.is_between(0, high, closed="left").all()
+
+    @given(
+        length=hypothesis.strategies.integers(0, 10),
+        high=hypothesis.strategies.integers(1, 10),
+    )
+    def test_series(self, *, length: int, high: int) -> None:
+        orig = int_range(end=length, eager=True)
+        series = utilities.polars.integers(orig, high)
+        assert series.len() == length
+        assert series.is_between(0, high, closed="left").all()
+
+    @given(
+        length=hypothesis.strategies.integers(0, 10),
+        high=hypothesis.strategies.integers(1, 10),
+    )
+    def test_dataframe(self, *, length: int, high: int) -> None:
+        df = int_range(end=length, eager=True).to_frame()
+        series = utilities.polars.integers(df, high)
+        assert series.len() == length
+        assert series.is_between(0, high, closed="left").all()
+
+
 class TestIsNullAndIsNotNullStructSeries:
     @given(
         case=sampled_from([
@@ -1526,6 +1561,28 @@ class TestNanSumCols:
         assert df["z"].item() == expected
 
 
+class TestNormal:
+    @given(length=hypothesis.strategies.integers(0, 10))
+    def test_int(self, *, length: int) -> None:
+        series = normal(length)
+        assert series.len() == length
+        assert series.is_finite().all()
+
+    @given(length=hypothesis.strategies.integers(0, 10))
+    def test_series(self, *, length: int) -> None:
+        orig = int_range(end=length, eager=True)
+        series = normal(orig)
+        assert series.len() == length
+        assert series.is_finite().all()
+
+    @given(length=hypothesis.strategies.integers(0, 10))
+    def test_dataframe(self, *, length: int) -> None:
+        df = int_range(end=length, eager=True).to_frame()
+        series = normal(df)
+        assert series.len() == length
+        assert series.is_finite().all()
+
+
 class TestReplaceTimeZone:
     def test_datetime(self) -> None:
         now_utc = get_now()
@@ -1711,6 +1768,40 @@ class TestStructFromDataClass:
             _ = struct_from_dataclass(Example)
 
 
+class TestUniform:
+    @given(
+        length=hypothesis.strategies.integers(0, 10),
+        bounds=pairs(floats(0.0, 1.0), sorted=True),
+    )
+    def test_int(self, *, length: int, bounds: tuple[float, float]) -> None:
+        low, high = bounds
+        series = uniform(length, low=low, high=high)
+        assert series.len() == length
+        assert series.is_between(low, high).all()
+
+    @given(
+        length=hypothesis.strategies.integers(0, 10),
+        bounds=pairs(floats(0.0, 1.0), sorted=True),
+    )
+    def test_series(self, *, length: int, bounds: tuple[float, float]) -> None:
+        low, high = bounds
+        orig = int_range(end=length, eager=True)
+        series = uniform(orig, low=low, high=high)
+        assert series.len() == length
+        assert series.is_between(low, high).all()
+
+    @given(
+        length=hypothesis.strategies.integers(0, 10),
+        bounds=pairs(floats(0.0, 1.0), sorted=True),
+    )
+    def test_dataframe(self, *, length: int, bounds: tuple[float, float]) -> None:
+        low, high = bounds
+        df = int_range(end=length, eager=True).to_frame()
+        series = uniform(df, low=low, high=high)
+        assert series.len() == length
+        assert series.is_between(low, high).all()
+
+
 class TestUniqueElement:
     def test_main(self) -> None:
         series = Series(

{dycw_utilities-0.109.7 → dycw_utilities-0.109.9}/src/tests/test_typing_funcs/with_future.py

@@ -54,6 +54,22 @@ class DataClassFutureIntDefault:
     int_: int = 0
 
 
+@dataclass(order=True, unsafe_hash=True, kw_only=True)
+class DataClassFutureIntEven:
+    even_int: int
+
+
+@dataclass(order=True, unsafe_hash=True, kw_only=True)
+class DataClassFutureIntOdd:
+    odd_int: int
+
+
+DataClassFutureIntEvenOrOddUnion = DataClassFutureIntEven | DataClassFutureIntOdd
+type DataClassFutureIntEvenOrOddTypeUnion = (
+    DataClassFutureIntEven | DataClassFutureIntOdd
+)
+
+
 @dataclass(order=True, unsafe_hash=True, kw_only=True)
 class DataClassFutureIntNullable:
     int_: int | None = None

{dycw_utilities-0.109.7 → dycw_utilities-0.109.9}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.109.7"
+__version__ = "0.109.9"

{dycw_utilities-0.109.7 → dycw_utilities-0.109.9}/src/utilities/dataclasses.py

@@ -24,7 +24,7 @@ from utilities.iterables import OneStrEmptyError, OneStrNonUniqueError, one_str
 from utilities.operator import is_equal
 from utilities.parse import ParseTextError, parse_text
 from utilities.sentinel import Sentinel, sentinel
-from utilities.types import TDataclass
+from utilities.types import ParseTextExtra, TDataclass
 from utilities.typing import get_type_hints
 
 if TYPE_CHECKING:
@@ -454,7 +454,7 @@ def text_to_dataclass(
     head: bool = False,
     case_sensitive: bool = False,
     allow_extra_keys: bool = False,
-    extra_parsers: Mapping[type[_T], Callable[[str], _T]] | None = None,
+    extra_parsers: ParseTextExtra | None = None,
 ) -> TDataclass:
     """Construct a dataclass from a string or a mapping or strings."""
     match text_or_mapping:
@@ -524,7 +524,7 @@ def _text_to_dataclass_parse(
     *,
     head: bool = False,
     case_sensitive: bool = False,
-    extra: Mapping[type[_T], Callable[[str], _T]] | None = None,
+    extra: ParseTextExtra | None = None,
 ) -> Any:
     try:
         return parse_text(

{dycw_utilities-0.109.7 → dycw_utilities-0.109.9}/src/utilities/parse.py

@@ -7,7 +7,7 @@ from enum import Enum
 from pathlib import Path
 from re import DOTALL
 from types import NoneType
-from typing import TYPE_CHECKING, Any, TypeVar, override
+from typing import Any, override
 
 from utilities.datetime import is_subclass_date_not_datetime
 from utilities.enum import ParseEnumError, parse_enum
@@ -17,7 +17,7 @@ from utilities.math import ParseNumberError, parse_number
 from utilities.re import ExtractGroupError, extract_group
 from utilities.sentinel import ParseSentinelError, Sentinel, parse_sentinel
 from utilities.text import ParseBoolError, ParseNoneError, parse_bool, parse_none
-from utilities.types import Duration, Number
+from utilities.types import Duration, Number, ParseTextExtra
 from utilities.typing import (
     get_args,
     is_literal_type,
@@ -27,12 +27,6 @@ from utilities.typing import (
 )
 from utilities.version import ParseVersionError, Version, parse_version
 
-if TYPE_CHECKING:
-    from collections.abc import Callable, Mapping
-
-
-_T = TypeVar("_T")
-
 
 def parse_text(
     obj: Any,
@@ -41,7 +35,7 @@ def parse_text(
     *,
     head: bool = False,
     case_sensitive: bool = False,
-    extra: Mapping[type[_T], Callable[[str], _T]] | None = None,
+    extra: ParseTextExtra | None = None,
 ) -> Any:
     """Parse text."""
     if obj is None:
@@ -76,7 +70,7 @@ def parse_text(
             for arg, text in zip(args, texts, strict=True)
         )
     if is_union_type(obj):
-        return _parse_text_union_type(obj, text)
+        return _parse_text_union_type(obj, text, extra=extra)
     raise _ParseTextParseError(obj=obj, text=text) from None
 
 
@@ -86,7 +80,7 @@ def _parse_text_type(
     /,
     *,
     case_sensitive: bool = False,
-    extra: Mapping[type[_T], Callable[[str], _T]] | None = None,
+    extra: ParseTextExtra | None = None,
 ) -> Any:
     """Parse text."""
     if issubclass(cls, NoneType):
@@ -170,7 +164,9 @@ def _parse_text_type(
     raise _ParseTextParseError(obj=cls, text=text) from None
 
 
-def _parse_text_union_type(obj: Any, text: str, /) -> Any:
+def _parse_text_union_type(
+    obj: Any, text: str, /, *, extra: ParseTextExtra | None = None
+) -> Any:
     if obj is Number:
         try:
             return parse_number(text)
@@ -183,6 +179,13 @@ def _parse_text_union_type(obj: Any, text: str, /) -> Any:
             return parse_duration(text)
         except ParseDurationError:
             raise _ParseTextParseError(obj=obj, text=text) from None
+    if extra is not None:
+        try:
+            parser = one(p for c, p in extra.items() if c is obj)
+        except OneEmptyError:
+            pass
+        else:
+            return parser(text)
     raise _ParseTextParseError(obj=obj, text=text) from None
 
 

{dycw_utilities-0.109.7 → dycw_utilities-0.109.9}/src/utilities/polars.py

@@ -1165,6 +1165,52 @@ class _InsertBetweenNonConsecutiveError(InsertBetweenError):
 ##
 
 
+def integers(
+    obj: int | Series | DataFrame,
+    low: int,
+    /,
+    *,
+    high: int | None = None,
+    seed: int | None = None,
+    endpoint: bool = False,
+    name: str | None = None,
+    dtype: PolarsDataType = Int64,
+) -> Series:
+    """Construct a series of normally-distributed numbers."""
+    match obj:
+        case int() as height:
+            from numpy.random import default_rng
+
+            rng = default_rng(seed=seed)
+            values = rng.integers(low, high=high, size=height, endpoint=endpoint)
+            return Series(name=name, values=values, dtype=dtype)
+        case Series() as series:
+            return integers(
+                series.len(),
+                low,
+                high=high,
+                seed=seed,
+                endpoint=endpoint,
+                name=name,
+                dtype=dtype,
+            )
+        case DataFrame() as df:
+            return integers(
+                df.height,
+                low,
+                high=high,
+                seed=seed,
+                endpoint=endpoint,
+                name=name,
+                dtype=dtype,
+            )
+        case _ as never:
+            assert_never(never)
+
+
+##
+
+
 def is_not_null_struct_series(series: Series, /) -> Series:
     """Check if a struct-dtype Series is not null as per the <= 1.1 definition."""
     try:
@@ -1324,6 +1370,39 @@ def nan_sum_cols(
 ##
 
 
+def normal(
+    obj: int | Series | DataFrame,
+    /,
+    *,
+    loc: float = 0.0,
+    scale: float = 1.0,
+    seed: int | None = None,
+    name: str | None = None,
+    dtype: PolarsDataType = Float64,
+) -> Series:
+    """Construct a series of normally-distributed numbers."""
+    match obj:
+        case int() as height:
+            from numpy.random import default_rng
+
+            rng = default_rng(seed=seed)
+            values = rng.normal(loc=loc, scale=scale, size=height)
+            return Series(name=name, values=values, dtype=dtype)
+        case Series() as series:
+            return normal(
+                series.len(), loc=loc, scale=scale, seed=seed, name=name, dtype=dtype
+            )
+        case DataFrame() as df:
+            return normal(
+                df.height, loc=loc, scale=scale, seed=seed, name=name, dtype=dtype
+            )
+        case _ as never:
+            assert_never(never)
+
+
+##
+
+
 @overload
 def replace_time_zone(
     obj: Series, /, *, time_zone: TimeZoneLike | None = UTC
@@ -1461,6 +1540,39 @@ class _StructFromDataClassTypeError(StructFromDataClassError):
 ##
 
 
+def uniform(
+    obj: int | Series | DataFrame,
+    /,
+    *,
+    low: float = 0.0,
+    high: float = 1.0,
+    seed: int | None = None,
+    name: str | None = None,
+    dtype: PolarsDataType = Float64,
+) -> Series:
+    """Construct a series of uniformly-distributed numbers."""
+    match obj:
+        case int() as height:
+            from numpy.random import default_rng
+
+            rng = default_rng(seed=seed)
+            values = rng.uniform(low=low, high=high, size=height)
+            return Series(name=name, values=values, dtype=dtype)
+        case Series() as series:
+            return uniform(
+                series.len(), low=low, high=high, seed=seed, name=name, dtype=dtype
+            )
+        case DataFrame() as df:
+            return uniform(
+                df.height, low=low, high=high, seed=seed, name=name, dtype=dtype
+            )
+        case _ as never:
+            assert_never(never)
+
+
+##
+
+
 def unique_element(column: ExprLike, /) -> Expr:
     """Get the unique element in a list."""
     column = ensure_expr_or_series(column)
@@ -1645,17 +1757,20 @@ __all__ = [
     "insert_after",
     "insert_before",
     "insert_between",
+    "integers",
     "is_not_null_struct_series",
     "is_null_struct_series",
     "join",
     "map_over_columns",
     "nan_sum_agg",
     "nan_sum_cols",
+    "normal",
     "replace_time_zone",
     "set_first_row_as_columns",
     "struct_dtype",
     "struct_from_dataclass",
     "touch",
+    "uniform",
     "unique_element",
     "yield_struct_series_dataclasses",
     "yield_struct_series_elements",

{dycw_utilities-0.109.7 → dycw_utilities-0.109.9}/src/utilities/python_dotenv.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from os import environ
-from typing import TYPE_CHECKING, TypeVar, override
+from typing import TYPE_CHECKING, override
 
 from dotenv import dotenv_values
 
@@ -13,14 +13,11 @@ from utilities.pathlib import PWD
 from utilities.reprlib import get_repr
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Mapping
+    from collections.abc import Mapping
     from collections.abc import Set as AbstractSet
     from pathlib import Path
 
-    from utilities.types import PathLike, StrMapping, TDataclass
-
-
-_T = TypeVar("_T")
+    from utilities.types import ParseTextExtra, PathLike, StrMapping, TDataclass
 
 
 def load_settings(
@@ -33,7 +30,7 @@ def load_settings(
     warn_name_errors: bool = False,
     head: bool = False,
     case_sensitive: bool = False,
-    extra_parsers: Mapping[type[_T], Callable[[str], _T]] | None = None,
+    extra_parsers: ParseTextExtra | None = None,
 ) -> TDataclass:
     """Load a set of settings from the `.env` file."""
     path = get_repo_root(cwd=cwd).joinpath(".env")

{dycw_utilities-0.109.7 → dycw_utilities-0.109.9}/src/utilities/types.py

@@ -229,6 +229,10 @@ class SupportsRound(Protocol[_T_co]):
     def __round__(self, ndigits: int, /) -> _T_co: ...
 
 
+# parse
+type ParseTextExtra = Mapping[Any, Callable[[str], Any]]
+
+
 # pathlib
 type PathLike = MaybeStr[Path]
 type PathLikeOrCallable = PathLike | Callable[[], PathLike]
@@ -278,6 +282,7 @@ __all__ = [
     "OpenMode",
     "OptExcInfo",
     "Parallelism",
+    "ParseTextExtra",
     "PathLike",
     "PathLikeOrCallable",
     "RoundMode",