dycw-utilities 0.109.7__py3-none-any.whl → 0.109.9__py3-none-any.whl

{dycw_utilities-0.109.7.dist-info → dycw_utilities-0.109.9.dist-info}/METADATA

@@ -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.dist-info → dycw_utilities-0.109.9.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=MUwL4q6Wbk3lcuTXRAV3j_zzg6Rwbca04bQFKgMtHec,60
+utilities/__init__.py,sha256=53_kiHhGqVZU7uWgI_AWTOmG7yG5Vbb_k-XsqiAMxyk,60
 utilities/altair.py,sha256=NSyDsm8QlkAGmsGdxVwCkHnPxt_35yJBa9Lg7bz9Ays,9054
 utilities/astor.py,sha256=xuDUkjq0-b6fhtwjhbnebzbqQZAjMSHR1IIS5uOodVg,777
 utilities/asyncio.py,sha256=41oQUurWMvadFK5gFnaG21hMM0Vmfn2WS6OpC0R9mas,14757
@@ -11,7 +11,7 @@ utilities/contextlib.py,sha256=OOIIEa5lXKGzFAnauaul40nlQnQko6Na4ryiMJcHkIg,478
 utilities/contextvars.py,sha256=RsSGGrbQqqZ67rOydnM7WWIsM2lIE31UHJLejnHJPWY,505
 utilities/cryptography.py,sha256=HyOewI20cl3uRXsKivhIaeLVDInQdzgXZGaly7hS5dE,771
 utilities/cvxpy.py,sha256=Rv1-fD-XYerosCavRF8Pohop2DBkU3AlFaGTfD8AEAA,13776
-utilities/dataclasses.py,sha256=Rh5QajjwyXGpQqndeOFRT-VnPJXF0jWI515GjCSprS0,23326
+utilities/dataclasses.py,sha256=rQS-G-JwhQNufV80aThSOD_ENliueqkz4N6NqtTTPN8,23294
 utilities/datetime.py,sha256=GOs-MIEW_A49kzqa1yhIoeNeSqqPVgGO-h2AThtgTDk,37326
 utilities/enum.py,sha256=HoRwVCWzsnH0vpO9ZEcAAIZLMv0Sn2vJxxA4sYMQgDs,5793
 utilities/errors.py,sha256=BtSNP0JC3ik536ddPyTerLomCRJV9f6kdMe6POz0QHM,361
@@ -40,12 +40,12 @@ utilities/operator.py,sha256=0M2yZJ0PODH47ogFEnkGMBe_cfxwZR02T_92LZVZvHo,3715
 utilities/optuna.py,sha256=loyJGWTzljgdJaoLhP09PT8Jz6o_pwBOwehY33lHkhw,1923
 utilities/orjson.py,sha256=Wj5pzG_VdgoAy14a7Luhem-BgYrRtRFvvl_POiszRd0,36930
 utilities/os.py,sha256=D_FyyT-6TtqiN9KSS7c9g1fnUtgxmyMtzAjmYLkk46A,3587
-utilities/parse.py,sha256=hzMDMUA9h3IpgsR48-Dk4CaojXofLm-eAn_bvJ8o6k8,7081
+utilities/parse.py,sha256=D1rqqrULV1FkjnCZS6804Io26_AZbMrsEILf-pZGNzw,7192
 utilities/pathlib.py,sha256=31WPMXdLIyXgYOMMl_HOI2wlo66MGSE-cgeelk-Lias,1410
 utilities/period.py,sha256=ikHXsWtDLr553cfH6p9mMaiCnIAP69B7q84ckWV3HaA,10884
 utilities/pickle.py,sha256=Bhvd7cZl-zQKQDFjUerqGuSKlHvnW1K2QXeU5UZibtg,657
 utilities/platform.py,sha256=NU7ycTvAXAG-fdYmDXaM1m4EOml2cGiaYwaUzfzSqyU,1767
-utilities/polars.py,sha256=USK_Rck8nmFYg2Rs-akqN9jV4w52lpz4rgkWUMQdLMk,49087
+utilities/polars.py,sha256=nB2pfK8N8HRpPE_tdbiTfFGLWC_TekAqgHlYDhnUzAM,52169
 utilities/pqdm.py,sha256=foRytQybmOQ05pjt5LF7ANyzrIa--4ScDE3T2wd31a4,3118
 utilities/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 utilities/pydantic.py,sha256=f6qtR5mO2YMuyvNmbaEj5YeD9eGA4YYfb7Bjzh9jUs0,1845
@@ -53,7 +53,7 @@ utilities/pyinstrument.py,sha256=ROq2txPwbe2ZUuYJ2IDNbfT97lu2ca0v5_C_yn6sSlM,800
 utilities/pyrsistent.py,sha256=TLJfiiKO4cKNU_pCoM3zDqmSM421qpuoaeaBNnyC_Ac,2489
 utilities/pytest.py,sha256=85QUax4g2VBBAqAHtM9wekcSLB7_9O8AKFTaCshztL8,7989
 utilities/pytest_regressions.py,sha256=-SVT9647Dg6-JcdsiaDKXe3NdOmmrvGevLKWwGjxq3c,5088
-utilities/python_dotenv.py,sha256=ZIz45FjpwoMs5fdYr9kRM6f4qEp2GNM5rKLnrRe8_7c,3218
+utilities/python_dotenv.py,sha256=JDIGuaGIiVkOcOBDpA7OZZM_0vxrkZyrrfqOssB6cqE,3170
 utilities/random.py,sha256=lYdjgxB7GCfU_fwFVl5U-BIM_HV3q6_urL9byjrwDM8,4157
 utilities/re.py,sha256=5J4d8VwIPFVrX2Eb8zfoxImDv7IwiN_U7mJ07wR2Wvs,3958
 utilities/redis.py,sha256=CsDQqc9V6ASLzLQwtbQXZQEndyG9pJiCOhPlPeszt7Y,21203
@@ -74,7 +74,7 @@ utilities/text.py,sha256=X_EjRQeV_PsG3oP7OiGYIyXGKWqciTnSwoKhM2tsy6M,3120
 utilities/threading.py,sha256=GvBOp4CyhHfN90wGXZuA2VKe9fGzMaEa7oCl4f3nnPU,1009
 utilities/timer.py,sha256=Rkc49KSpHuC8s7vUxGO9DU55U9I6yDKnchsQqrUCVBs,4075
 utilities/traceback.py,sha256=KwHPLdEbdj0fFhXo8MBfxcvem8A-VXYDwFMNJ6f0cTM,27328
-utilities/types.py,sha256=QK8kgH80TJdh_vktaZHrCEk7f1f8kHiDr8dJlK8aSac,17814
+utilities/types.py,sha256=fkaqL67A_1p0-Q88JTu1dt_GV3mVo5mSslYa9DGWNq4,17903
 utilities/typing.py,sha256=gLg4EbE1FX52fJ1d3ji4i08qolwu9qgWt8w_w_Y5DTk,5512
 utilities/tzdata.py,sha256=2ZsPmhTVM9Ptrxb4QrWKtKOB9RiH8IOO-A1u7ULdVbg,176
 utilities/tzlocal.py,sha256=42BCquGF54oIqIKe5RGziP4K8Nbm3Ey7uqcNn6m5ge8,534
@@ -84,7 +84,7 @@ utilities/warnings.py,sha256=yUgjnmkCRf6QhdyAXzl7u0qQFejhQG3PrjoSwxpbHrs,1819
 utilities/whenever.py,sha256=TjoTAJ1R27-rKXiXzdE4GzPidmYqm0W58XydDXp-QZM,17786
 utilities/zipfile.py,sha256=24lQc9ATcJxHXBPc_tBDiJk48pWyRrlxO2fIsFxU0A8,699
 utilities/zoneinfo.py,sha256=-DQz5a0Ikw9jfSZtL0BEQkXOMC9yGn_xiJYNCLMiqEc,1989
-dycw_utilities-0.109.7.dist-info/METADATA,sha256=pDfjhbqQ0EwowMUVigqpK60JwGhbUysd3RLQVL398aw,13004
-dycw_utilities-0.109.7.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.109.7.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.109.7.dist-info/RECORD,,
+dycw_utilities-0.109.9.dist-info/METADATA,sha256=sh80SudoQ_j2lWexCpuls1seZsGjBvS7FlKhOLC6kIE,13004
+dycw_utilities-0.109.9.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.109.9.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.109.9.dist-info/RECORD,,

utilities/__init__.py

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

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(

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
 
 

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",

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")

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",