dycw-utilities 0.112.8__py3-none-any.whl → 0.112.10__py3-none-any.whl

{dycw_utilities-0.112.8.dist-info → dycw_utilities-0.112.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.112.8
+Version: 0.112.10
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -24,7 +24,7 @@ Provides-Extra: zzz-test-altair
 Requires-Dist: altair<5.6,>=5.5.0; extra == 'zzz-test-altair'
 Requires-Dist: atomicwrites<1.5,>=1.4.1; extra == 'zzz-test-altair'
 Requires-Dist: img2pdf<0.7,>=0.6.0; extra == 'zzz-test-altair'
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-altair'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-altair'
 Requires-Dist: vl-convert-python<1.8,>=1.7.0; extra == 'zzz-test-altair'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-altair'
 Provides-Extra: zzz-test-astor
@@ -48,7 +48,7 @@ Provides-Extra: zzz-test-cvxpy
 Requires-Dist: cvxpy<1.7,>=1.6.5; extra == 'zzz-test-cvxpy'
 Provides-Extra: zzz-test-dataclasses
 Requires-Dist: orjson<3.11,>=3.10.15; extra == 'zzz-test-dataclasses'
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-dataclasses'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-dataclasses'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-dataclasses'
 Provides-Extra: zzz-test-datetime
 Requires-Dist: tzlocal<5.4,>=5.3.1; extra == 'zzz-test-datetime'
@@ -70,11 +70,11 @@ Provides-Extra: zzz-test-getpass
 Provides-Extra: zzz-test-git
 Provides-Extra: zzz-test-hashlib
 Requires-Dist: orjson<3.11,>=3.10.15; extra == 'zzz-test-hashlib'
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-hashlib'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-hashlib'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-hashlib'
 Provides-Extra: zzz-test-http
 Requires-Dist: atomicwrites<1.5,>=1.4.1; extra == 'zzz-test-http'
-Requires-Dist: orjson<3.11,>=3.10.16; extra == 'zzz-test-http'
+Requires-Dist: orjson<3.11,>=3.10.18; extra == 'zzz-test-http'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-http'
 Provides-Extra: zzz-test-hypothesis
 Requires-Dist: aiosqlite<0.22,>=0.21.0; extra == 'zzz-test-hypothesis'
@@ -92,12 +92,12 @@ Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-hypothesis'
 Provides-Extra: zzz-test-ipython
 Requires-Dist: ipython<9.1,>=9.0.1; extra == 'zzz-test-ipython'
 Provides-Extra: zzz-test-iterables
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-iterables'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-iterables'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-iterables'
 Provides-Extra: zzz-test-jupyter
 Requires-Dist: jupyterlab<4.3,>=4.2.0; extra == 'zzz-test-jupyter'
 Requires-Dist: pandas<2.3,>=2.2.2; extra == 'zzz-test-jupyter'
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-jupyter'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-jupyter'
 Provides-Extra: zzz-test-logging
 Requires-Dist: atomicwrites<1.5,>=1.4.1; extra == 'zzz-test-logging'
 Requires-Dist: coloredlogs<15.1,>=15.0.1; extra == 'zzz-test-logging'
@@ -121,13 +121,13 @@ Requires-Dist: more-itertools<10.8,>=10.7.0; extra == 'zzz-test-more-itertools'
 Provides-Extra: zzz-test-numpy
 Requires-Dist: numpy<2.3,>=2.2.5; extra == 'zzz-test-numpy'
 Provides-Extra: zzz-test-operator
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-operator'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-operator'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-operator'
 Provides-Extra: zzz-test-optuna
 Requires-Dist: optuna<4.4,>=4.3.0; extra == 'zzz-test-optuna'
 Provides-Extra: zzz-test-orjson
 Requires-Dist: orjson<3.11,>=3.10.15; extra == 'zzz-test-orjson'
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-orjson'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-orjson'
 Requires-Dist: rich<14.1,>=14.0.0; extra == 'zzz-test-orjson'
 Requires-Dist: tzlocal<5.4,>=5.3.1; extra == 'zzz-test-orjson'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-orjson'
@@ -138,13 +138,13 @@ Requires-Dist: atomicwrites<1.5,>=1.4.1; extra == 'zzz-test-pickle'
 Provides-Extra: zzz-test-platform
 Provides-Extra: zzz-test-polars
 Requires-Dist: dacite<1.10,>=1.9.2; extra == 'zzz-test-polars'
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-polars'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-polars'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-polars'
 Provides-Extra: zzz-test-pqdm
 Requires-Dist: pqdm<0.3,>=0.2.0; extra == 'zzz-test-pqdm'
 Provides-Extra: zzz-test-pydantic
 Requires-Dist: atomicwrites<1.5,>=1.4.1; extra == 'zzz-test-pydantic'
-Requires-Dist: pydantic<2.12,>=2.11.2; extra == 'zzz-test-pydantic'
+Requires-Dist: pydantic<2.12,>=2.11.4; extra == 'zzz-test-pydantic'
 Provides-Extra: zzz-test-pyinstrument
 Requires-Dist: atomicwrites<1.5,>=1.4.1; extra == 'zzz-test-pyinstrument'
 Requires-Dist: pyinstrument<5.1,>=5.0.0; extra == 'zzz-test-pyinstrument'
@@ -153,7 +153,7 @@ Provides-Extra: zzz-test-pyrsistent
 Requires-Dist: pyrsistent<0.21,>=0.20.0; extra == 'zzz-test-pyrsistent'
 Provides-Extra: zzz-test-pytest
 Requires-Dist: atomicwrites<1.5,>=1.4.1; extra == 'zzz-test-pytest'
-Requires-Dist: orjson<3.11,>=3.10.16; extra == 'zzz-test-pytest'
+Requires-Dist: orjson<3.11,>=3.10.18; extra == 'zzz-test-pytest'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-pytest'
 Provides-Extra: zzz-test-pytest-regressions
 Requires-Dist: pytest-regressions<2.8,>=2.7.0; extra == 'zzz-test-pytest-regressions'
@@ -164,7 +164,7 @@ Provides-Extra: zzz-test-random
 Provides-Extra: zzz-test-re
 Provides-Extra: zzz-test-redis
 Requires-Dist: orjson<3.11,>=3.10.15; extra == 'zzz-test-redis'
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-redis'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-redis'
 Requires-Dist: redis<5.3,>=5.2.1; extra == 'zzz-test-redis'
 Requires-Dist: rich<14.1,>=14.0.0; extra == 'zzz-test-redis'
 Requires-Dist: tenacity<9.0,>=8.5.0; extra == 'zzz-test-redis'
@@ -192,12 +192,12 @@ Requires-Dist: aiosqlite<0.22,>=0.21.0; extra == 'zzz-test-sqlalchemy-polars'
 Requires-Dist: asyncpg<0.31,>=0.30.0; extra == 'zzz-test-sqlalchemy-polars'
 Requires-Dist: greenlet<3.3,>=3.2.0; extra == 'zzz-test-sqlalchemy-polars'
 Requires-Dist: nest-asyncio<1.7,>=1.6.0; extra == 'zzz-test-sqlalchemy-polars'
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-sqlalchemy-polars'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-sqlalchemy-polars'
 Requires-Dist: sqlalchemy<2.1,>=2.0.40; extra == 'zzz-test-sqlalchemy-polars'
 Requires-Dist: tenacity<9.0,>=8.5.0; extra == 'zzz-test-sqlalchemy-polars'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-sqlalchemy-polars'
 Provides-Extra: zzz-test-streamlit
-Requires-Dist: streamlit<1.45,>=1.44.1; extra == 'zzz-test-streamlit'
+Requires-Dist: streamlit<1.46,>=1.45.0; extra == 'zzz-test-streamlit'
 Provides-Extra: zzz-test-sys
 Requires-Dist: atomicwrites<1.5,>=1.4.1; extra == 'zzz-test-sys'
 Requires-Dist: rich<14.1,>=14.0.0; extra == 'zzz-test-sys'
@@ -217,7 +217,7 @@ Requires-Dist: tzlocal<5.4,>=5.3.1; extra == 'zzz-test-traceback'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-traceback'
 Provides-Extra: zzz-test-types
 Provides-Extra: zzz-test-typing
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-typing'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-typing'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-typing'
 Provides-Extra: zzz-test-tzlocal
 Requires-Dist: tzlocal<5.4,>=5.3.1; extra == 'zzz-test-tzlocal'

{dycw_utilities-0.112.8.dist-info → dycw_utilities-0.112.10.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=XeC2tMugkErM_YQbJ1Iwis-CVp-V14bjMaBeziiWF1s,60
+utilities/__init__.py,sha256=mALrkpjRtE0nW8tAmwclFaEZyShTCa75IjKVwftuFOc,61
 utilities/altair.py,sha256=Gpja-flOo-Db0PIPJLJsgzAlXWoKUjPU1qY-DQ829ek,9156
 utilities/astor.py,sha256=xuDUkjq0-b6fhtwjhbnebzbqQZAjMSHR1IIS5uOodVg,777
 utilities/asyncio.py,sha256=41oQUurWMvadFK5gFnaG21hMM0Vmfn2WS6OpC0R9mas,14757
@@ -36,7 +36,7 @@ utilities/math.py,sha256=TexfvLCI12d9Sw5_W4pKVBZ3nRr3zk2iPkcEU7xdEWU,26771
 utilities/memory_profiler.py,sha256=tf2C51P2lCujPGvRt2Rfc7VEw5LDXmVPCG3z_AvBmbU,962
 utilities/modules.py,sha256=iuvLluJya-hvl1Q25-Jk3dLgx2Es3ck4SjJiEkAlVTs,3195
 utilities/more_itertools.py,sha256=CPUxrMAcTwRxbzbhiqPKi3Xx9hxqI0t6gkWjutaibGk,5534
-utilities/numpy.py,sha256=cBgCBet8YfZP_rb4nkCJHZx9_03qPEinVENMk1dGVYQ,25683
+utilities/numpy.py,sha256=Xn23sA2ZbVNqwUYEgNJD3XBYH6IbCri_WkHSNhg3NkY,26122
 utilities/operator.py,sha256=0M2yZJ0PODH47ogFEnkGMBe_cfxwZR02T_92LZVZvHo,3715
 utilities/optuna.py,sha256=loyJGWTzljgdJaoLhP09PT8Jz6o_pwBOwehY33lHkhw,1923
 utilities/orjson.py,sha256=DBm2zPP04kcHpY3l1etL24ksNynu-R3duFyx3U-RjqQ,36948
@@ -46,7 +46,7 @@ utilities/pathlib.py,sha256=31WPMXdLIyXgYOMMl_HOI2wlo66MGSE-cgeelk-Lias,1410
 utilities/period.py,sha256=RWfcNVoNlW07RNdU47g_zuLZMKbtgfK4bE6G-9tVjY8,11024
 utilities/pickle.py,sha256=Bhvd7cZl-zQKQDFjUerqGuSKlHvnW1K2QXeU5UZibtg,657
 utilities/platform.py,sha256=NU7ycTvAXAG-fdYmDXaM1m4EOml2cGiaYwaUzfzSqyU,1767
-utilities/polars.py,sha256=q8a2hTX9tyPxtxUarIm2BxlnckIwF1RCpcJz03OoIoY,58458
+utilities/polars.py,sha256=ZdhGu9qMlgbwfdYYDEV3Pk3kfJr1V5FSolfCWHI3Nxc,63283
 utilities/polars_ols.py,sha256=efhXf0gjrHUpQrvS6a7g8yJQJWf_ATKtJnqqF2inCOU,5680
 utilities/pqdm.py,sha256=foRytQybmOQ05pjt5LF7ANyzrIa--4ScDE3T2wd31a4,3118
 utilities/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -58,7 +58,7 @@ utilities/pytest_regressions.py,sha256=-SVT9647Dg6-JcdsiaDKXe3NdOmmrvGevLKWwGjxq
 utilities/python_dotenv.py,sha256=iWcnpXbH7S6RoXHiLlGgyuH6udCupAcPd_gQ0eAenQ0,3190
 utilities/random.py,sha256=lYdjgxB7GCfU_fwFVl5U-BIM_HV3q6_urL9byjrwDM8,4157
 utilities/re.py,sha256=5J4d8VwIPFVrX2Eb8zfoxImDv7IwiN_U7mJ07wR2Wvs,3958
-utilities/redis.py,sha256=fAUbfOlCmxcxhh47PXQX63w0CU5iOFKfdUJ7jDn9ntM,22096
+utilities/redis.py,sha256=XYHo1Qne4j5_BSIUorF8n5EWCRwByTdbAL3NLC6e2_4,25261
 utilities/reprlib.py,sha256=Re9bk3n-kC__9DxQmRlevqFA86pE6TtVfWjUgpbVOv0,1849
 utilities/rich.py,sha256=t50MwwVBsoOLxzmeVFSVpjno4OW6Ufum32skXbV8-Bs,1911
 utilities/scipy.py,sha256=X6ROnHwiUhAmPhM0jkfEh0-Fd9iRvwiqtCQMOLmOQF8,945
@@ -87,7 +87,7 @@ utilities/warnings.py,sha256=un1LvHv70PU-LLv8RxPVmugTzDJkkGXRMZTE2-fTQHw,1771
 utilities/whenever.py,sha256=iLRP_-8CZtBpHKbGZGu-kjSMg1ZubJ-VSmgSy7Eudxw,17787
 utilities/zipfile.py,sha256=24lQc9ATcJxHXBPc_tBDiJk48pWyRrlxO2fIsFxU0A8,699
 utilities/zoneinfo.py,sha256=-Xm57PMMwDTYpxJdkiJG13wnbwK--I7XItBh5WVhD-o,1874
-dycw_utilities-0.112.8.dist-info/METADATA,sha256=i2cGlKTXS9uPmvL_dC8xIdqS9wlxq5NbsOgmOn6J23o,13004
-dycw_utilities-0.112.8.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.112.8.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.112.8.dist-info/RECORD,,
+dycw_utilities-0.112.10.dist-info/METADATA,sha256=HXZIn_uHvb-xc5-RuCEn_T8pPkJ58gnElO7ootr182o,13005
+dycw_utilities-0.112.10.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.112.10.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.112.10.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.112.8"
+__version__ = "0.112.10"

utilities/numpy.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
+from collections.abc import Sequence
 from dataclasses import dataclass
 from functools import partial, reduce
 from itertools import repeat
-from typing import TYPE_CHECKING, Any, overload, override
+from typing import TYPE_CHECKING, Any, SupportsIndex, overload, override
 
 import numpy as np
 from numpy import (
@@ -46,6 +47,9 @@ if TYPE_CHECKING:
     from utilities.types import MaybeIterable
 
 
+type ShapeLike = SupportsIndex | Sequence[SupportsIndex]
+
+
 ##
 
 
@@ -136,6 +140,19 @@ class AsIntError(Exception): ...
 ##
 
 
+def bernoulli(
+    *, true: float = 0.5, seed: int | None = None, size: ShapeLike = ()
+) -> NDArrayB:
+    """Return a set of Bernoulli random variates."""
+    from numpy.random import default_rng
+
+    rng = default_rng(seed=seed)
+    return rng.binomial(1, true, size=size).astype(bool)
+
+
+##
+
+
 def boxcar(
     array: NDArrayF,
     /,
@@ -980,11 +997,13 @@ __all__ = [
     "NDArrayF",
     "NDArrayI",
     "NDArrayO",
+    "ShapeLike",
     "ShiftError",
     "SigmoidError",
     "adjust_frequencies",
     "array_indexer",
     "as_int",
+    "bernoulli",
     "boxcar",
     "datetime64D",
     "datetime64M",

utilities/polars.py

@@ -39,17 +39,20 @@ from polars import (
     Series,
     String,
     Struct,
+    UInt32,
     all_horizontal,
     col,
     concat,
     int_range,
     lit,
     struct,
+    sum_horizontal,
     when,
 )
 from polars.datatypes import DataType, DataTypeClass
 from polars.exceptions import (
     ColumnNotFoundError,
+    NoRowsReturnedError,
     OutOfBoundsError,
     PolarsInefficientMapWarning,
 )
@@ -337,6 +340,102 @@ def are_frames_equal(
 ##
 
 
+def bernoulli(
+    obj: int | Series | DataFrame,
+    /,
+    *,
+    true: float = 0.5,
+    seed: int | None = None,
+    name: str | None = None,
+) -> Series:
+    """Construct a series of Bernoulli-random variables."""
+    match obj:
+        case int() as height:
+            import utilities.numpy
+
+            values = utilities.numpy.bernoulli(true=true, seed=seed, size=height)
+            return Series(name=name, values=values)
+        case Series() as series:
+            return bernoulli(series.len(), true=true, seed=seed, name=name)
+        case DataFrame() as df:
+            return bernoulli(df.height, true=true, seed=seed, name=name)
+        case _ as never:
+            assert_never(never)
+
+
+##
+
+
+def boolean_value_counts(
+    obj: Series | DataFrame, /, *exprs: IntoExprColumn, **named_exprs: IntoExprColumn
+) -> DataFrame:
+    """Conduct a set of boolean value counts."""
+    match obj:
+        case Series() as series:
+            return boolean_value_counts(series.to_frame(), *exprs, **named_exprs)
+        case DataFrame() as df:
+            all_exprs = ensure_expr_or_series_many(*exprs, **named_exprs)
+            rows = [_boolean_value_counts_one(df, expr) for expr in all_exprs]
+            true, false, null = [col(c) for c in ["true", "false", "null"]]
+            total = sum_horizontal(true, false, null).alias("total")
+            return DataFrame(
+                rows,
+                schema={
+                    "name": String,
+                    "true": UInt32,
+                    "false": UInt32,
+                    "null": UInt32,
+                },
+                orient="row",
+            ).with_columns(
+                total,
+                (true / total).alias("true (%)"),
+                (false / total).alias("false (%)"),
+                (null / total).alias("null (%)"),
+            )
+        case _ as never:
+            assert_never(never)
+
+
+def _boolean_value_counts_one(
+    df: DataFrame, expr: IntoExprColumn, /
+) -> Mapping[str, Any]:
+    name = get_expr_name(df, expr)
+    sr = df.select(expr)[name]
+    if not isinstance(sr.dtype, Boolean):
+        raise BooleanValueCountsError(name=name, dtype=sr.dtype)
+    counts = sr.value_counts()
+    truth = col(name)
+    try:
+        true = counts.row(by_predicate=truth.is_not_null() & truth, named=True)["count"]
+    except NoRowsReturnedError:
+        true = 0
+    try:
+        false = counts.row(by_predicate=(truth.is_not_null() & ~truth), named=True)[
+            "count"
+        ]
+    except NoRowsReturnedError:
+        false = 0
+    try:
+        null = counts.row(by_predicate=truth.is_null(), named=True)["count"]
+    except NoRowsReturnedError:
+        null = 0
+    return {"name": name, "true": true, "false": false, "null": null}
+
+
+@dataclass(kw_only=True, slots=True)
+class BooleanValueCountsError(Exception):
+    name: str
+    dtype: DataType
+
+    @override
+    def __str__(self) -> str:
+        return f"Column {self.name!r} must be Boolean; got {self.dtype!r}"
+
+
+##
+
+
 @overload
 def ceil_datetime(column: ExprLike, every: ExprLike, /) -> Expr: ...
 @overload
@@ -637,6 +736,54 @@ class _CheckPolarsDataFrameWidthError(CheckPolarsDataFrameError):
 ##
 
 
+def choice(
+    obj: int | Series | DataFrame,
+    elements: Iterable[Any],
+    /,
+    *,
+    replace: bool = True,
+    p: Iterable[float] | None = None,
+    seed: int | None = None,
+    name: str | None = None,
+    dtype: PolarsDataType = Float64,
+) -> Series:
+    """Construct a series of random samples."""
+    match obj:
+        case int() as height:
+            from numpy.random import default_rng
+
+            rng = default_rng(seed=seed)
+            elements = list(elements)
+            p = None if p is None else list(p)
+            values = rng.choice(elements, size=height, replace=replace, p=p)
+            return Series(name=name, values=values.tolist(), dtype=dtype)
+        case Series() as series:
+            return choice(
+                series.len(),
+                elements,
+                replace=replace,
+                p=p,
+                seed=seed,
+                name=name,
+                dtype=dtype,
+            )
+        case DataFrame() as df:
+            return choice(
+                df.height,
+                elements,
+                replace=replace,
+                p=p,
+                seed=seed,
+                name=name,
+                dtype=dtype,
+            )
+        case _ as never:
+            assert_never(never)
+
+
+##
+
+
 def collect_series(expr: Expr, /) -> Series:
     """Collect a column expression into a Series."""
     data = DataFrame().with_columns(expr)
@@ -1053,6 +1200,18 @@ def ensure_expr_or_series(column: IntoExprColumn, /) -> Expr | Series:
 ##
 
 
+def ensure_expr_or_series_many(
+    *columns: IntoExprColumn, **named_columns: IntoExprColumn
+) -> Sequence[Expr | Series]:
+    """Ensure a set of column expressions and/or Series are returned."""
+    args = map(ensure_expr_or_series, columns)
+    kwargs = (ensure_expr_or_series(v).alias(k) for k, v in named_columns.items())
+    return list(chain(args, kwargs))
+
+
+##
+
+
 @overload
 def finite_ewm_mean(
     column: ExprLike,
@@ -1227,7 +1386,7 @@ class _GetDataTypeOrSeriesTimeZoneNotZonedError(GetDataTypeOrSeriesTimeZoneError
 ##
 
 
-def get_expr_name(obj: Series | DataFrame, expr: Expr, /) -> str:
+def get_expr_name(obj: Series | DataFrame, expr: IntoExprColumn, /) -> str:
     """Get the name of an expression."""
     match obj:
         case Series() as series:
@@ -1948,6 +2107,7 @@ def zoned_datetime(
 
 
 __all__ = [
+    "BooleanValueCountsError",
     "CheckPolarsDataFrameError",
     "ColumnsToDictError",
     "DataClassToDataFrameError",
@@ -1971,8 +2131,11 @@ __all__ = [
     "adjust_frequencies",
     "append_dataclass",
     "are_frames_equal",
+    "bernoulli",
+    "boolean_value_counts",
     "ceil_datetime",
     "check_polars_dataframe",
+    "choice",
     "collect_series",
     "columns_to_dict",
     "concat_series",
@@ -1983,6 +2146,7 @@ __all__ = [
     "drop_null_struct_series",
     "ensure_data_type",
     "ensure_expr_or_series",
+    "ensure_expr_or_series_many",
     "finite_ewm_mean",
     "floor_datetime",
     "get_data_type_or_series_time_zone",

utilities/redis.py

@@ -31,11 +31,18 @@ from utilities.datetime import (
 )
 from utilities.errors import ImpossibleCaseError
 from utilities.functions import ensure_int
-from utilities.iterables import always_iterable
+from utilities.iterables import always_iterable, one
 
 if TYPE_CHECKING:
     import datetime as dt
-    from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
+    from collections.abc import (
+        AsyncIterator,
+        Awaitable,
+        Callable,
+        Iterable,
+        Mapping,
+        Sequence,
+    )
 
     from redis.asyncio import ConnectionPool
     from redis.asyncio.client import PubSub
@@ -71,6 +78,7 @@ class RedisHashMapKey(Generic[_K, _V]):
     name: str
     key: TypeLike[_K]
     key_serializer: Callable[[_K], bytes] | None = None
+    key_deserializer: Callable[[bytes], _K] | None = None
     value: TypeLike[_V]
     value_serializer: Callable[[_V], bytes] | None = None
     value_deserializer: Callable[[bytes], _V] | None = None
@@ -95,46 +103,102 @@ class RedisHashMapKey(Generic[_K, _V]):
                 "Awaitable[bool]", redis.hexists(self.name, cast("str", key))
             )
 
-    async def get(self, redis: Redis, key: _K, /) -> _V | None:
+    async def get(self, redis: Redis, key: _K, /) -> _V:
+        """Get a value from a hashmap in `redis`."""
+        result = one(await self.get_many(redis, [key]))  # skipif-ci-and-not-linux
+        if result is None:  # skipif-ci-and-not-linux
+            raise KeyError(self.name, key)
+        return result  # skipif-ci-and-not-linux
+
+    async def get_all(self, redis: Redis, /) -> Mapping[_K, _V]:
         """Get a value from a hashmap in `redis`."""
-        ser_key = _serialize(  # skipif-ci-and-not-linux
-            key, serializer=self.key_serializer
-        )
         async with timeout_dur(  # skipif-ci-and-not-linux
             duration=self.timeout, error=self.error
         ):
             result = await cast(  # skipif-ci-and-not-linux
-                "Awaitable[bytes | None]", redis.hget(self.name, cast("Any", ser_key))
+                "Awaitable[Mapping[bytes, bytes]]", redis.hgetall(self.name)
             )
-        match result:  # skipif-ci-and-not-linux
-            case None:
-                return None
-            case bytes() as data:
-                return _deserialize(data, deserializer=self.value_deserializer)
-            case _ as never:
-                assert_never(never)
+        return {  # skipif-ci-and-not-linux
+            _deserialize(key, deserializer=self.key_deserializer): _deserialize(
+                value, deserializer=self.value_deserializer
+            )
+            for key, value in result.items()
+        }
+
+    async def get_many(
+        self, redis: Redis, keys: Iterable[_K], /
+    ) -> Sequence[_V | None]:
+        """Get multiple values from a hashmap in `redis`."""
+        keys = list(keys)  # skipif-ci-and-not-linux
+        if len(keys) == 0:  # skipif-ci-and-not-linux
+            return []
+        ser = [  # skipif-ci-and-not-linux
+            _serialize(key, serializer=self.key_serializer) for key in keys
+        ]
+        async with timeout_dur(  # skipif-ci-and-not-linux
+            duration=self.timeout, error=self.error
+        ):
+            result = await cast(  # skipif-ci-and-not-linux
+                "Awaitable[Sequence[bytes | None]]", redis.hmget(self.name, ser)
+            )
+        return [  # skipif-ci-and-not-linux
+            None
+            if data is None
+            else _deserialize(data, deserializer=self.value_deserializer)
+            for data in result
+        ]
+
+    async def keys(self, redis: Redis, /) -> Sequence[_K]:
+        """Get the keys of a hashmap in `redis`."""
+        async with timeout_dur(  # skipif-ci-and-not-linux
+            duration=self.timeout, error=self.error
+        ):
+            result = await cast("Awaitable[Sequence[bytes]]", redis.hkeys(self.name))
+        return [  # skipif-ci-and-not-linux
+            _deserialize(data, deserializer=self.key_deserializer) for data in result
+        ]
+
+    async def length(self, redis: Redis, /) -> int:
+        """Get the length of a hashmap in `redis`."""
+        async with timeout_dur(  # skipif-ci-and-not-linux
+            duration=self.timeout, error=self.error
+        ):
+            return await cast("Awaitable[int]", redis.hlen(self.name))
 
     async def set(self, redis: Redis, key: _K, value: _V, /) -> int:
         """Set a value in a hashmap in `redis`."""
-        ser_key = _serialize(  # skipif-ci-and-not-linux
-            key, serializer=self.key_serializer
-        )
-        ser_value = _serialize(  # skipif-ci-and-not-linux
-            value, serializer=self.value_serializer
-        )
+        return await self.set_many(redis, {key: value})  # skipif-ci-and-not-linux
+
+    async def set_many(self, redis: Redis, mapping: Mapping[_K, _V], /) -> int:
+        """Set multiple value(s) in a hashmap in `redis`."""
+        if len(mapping) == 0:  # skipif-ci-and-not-linux
+            return 0
+        ser = {  # skipif-ci-and-not-linux
+            _serialize(key, serializer=self.key_serializer): _serialize(
+                value, serializer=self.value_serializer
+            )
+            for key, value in mapping.items()
+        }
         async with timeout_dur(  # skipif-ci-and-not-linux
             duration=self.timeout, error=self.error
         ):
             result = await cast(
-                "Awaitable[int]",
-                redis.hset(
-                    self.name, key=cast("Any", ser_key), value=cast("Any", ser_value)
-                ),
+                "Awaitable[int]", redis.hset(self.name, mapping=cast("Any", ser))
             )
             if self.ttl is not None:
                 await redis.pexpire(self.name, datetime_duration_to_timedelta(self.ttl))
         return result  # skipif-ci-and-not-linux
 
+    async def values(self, redis: Redis, /) -> Sequence[_V]:
+        """Get the values of a hashmap in `redis`."""
+        async with timeout_dur(  # skipif-ci-and-not-linux
+            duration=self.timeout, error=self.error
+        ):
+            result = await cast("Awaitable[Sequence[bytes]]", redis.hvals(self.name))
+        return [  # skipif-ci-and-not-linux
+            _deserialize(data, deserializer=self.value_deserializer) for data in result
+        ]
+
 
 @overload
 def redis_hash_map_key(
@@ -144,6 +208,7 @@ def redis_hash_map_key(
     /,
     *,
     key_serializer: Callable[[_K], bytes] | None = None,
+    key_deserializer: Callable[[bytes], Any] | None = None,
     value_serializer: Callable[[_V], bytes] | None = None,
     value_deserializer: Callable[[bytes], _V] | None = None,
     timeout: Duration | None = None,
@@ -158,6 +223,7 @@ def redis_hash_map_key(
     /,
     *,
     key_serializer: Callable[[_K], bytes] | None = None,
+    key_deserializer: Callable[[bytes], Any] | None = None,
     value_serializer: Callable[[_V1 | _V2], bytes] | None = None,
     value_deserializer: Callable[[bytes], _V1 | _V2] | None = None,
     timeout: Duration | None = None,
@@ -172,6 +238,7 @@ def redis_hash_map_key(
     /,
     *,
     key_serializer: Callable[[_K], bytes] | None = None,
+    key_deserializer: Callable[[bytes], Any] | None = None,
     value_serializer: Callable[[_V1 | _V2 | _V3], bytes] | None = None,
     value_deserializer: Callable[[bytes], _V1 | _V2 | _V3] | None = None,
     timeout: Duration | None = None,
@@ -186,6 +253,7 @@ def redis_hash_map_key(
     /,
     *,
     key_serializer: Callable[[_K1 | _K2], bytes] | None = None,
+    key_deserializer: Callable[[bytes], Any] | None = None,
     value_serializer: Callable[[_V], bytes] | None = None,
     value_deserializer: Callable[[bytes], _V] | None = None,
     timeout: Duration | None = None,
@@ -200,6 +268,7 @@ def redis_hash_map_key(
     /,
     *,
     key_serializer: Callable[[_K1 | _K2], bytes] | None = None,
+    key_deserializer: Callable[[bytes], Any] | None = None,
     value_serializer: Callable[[_V1 | _V2], bytes] | None = None,
     value_deserializer: Callable[[bytes], _V1 | _V2] | None = None,
     timeout: Duration | None = None,
@@ -214,6 +283,7 @@ def redis_hash_map_key(
     /,
     *,
     key_serializer: Callable[[_K1 | _K2], bytes] | None = None,
+    key_deserializer: Callable[[bytes], Any] | None = None,
     value_serializer: Callable[[_V1 | _V2 | _V3], bytes] | None = None,
     value_deserializer: Callable[[bytes], _V1 | _V2 | _V3] | None = None,
     timeout: Duration | None = None,
@@ -228,6 +298,7 @@ def redis_hash_map_key(
     /,
     *,
     key_serializer: Callable[[_K1 | _K2 | _K3], bytes] | None = None,
+    key_deserializer: Callable[[bytes], Any] | None = None,
     value_serializer: Callable[[_V], bytes] | None = None,
     value_deserializer: Callable[[bytes], _V] | None = None,
     timeout: Duration | None = None,
@@ -242,6 +313,7 @@ def redis_hash_map_key(
     /,
     *,
     key_serializer: Callable[[_K1 | _K2 | _K3], bytes] | None = None,
+    key_deserializer: Callable[[bytes], Any] | None = None,
     value_serializer: Callable[[_V1 | _V2], bytes] | None = None,
     value_deserializer: Callable[[bytes], _V1 | _V2] | None = None,
     timeout: Duration | None = None,
@@ -256,6 +328,7 @@ def redis_hash_map_key(
     /,
     *,
     key_serializer: Callable[[_K1 | _K2 | _K3], bytes] | None = None,
+    key_deserializer: Callable[[bytes], Any] | None = None,
     value_serializer: Callable[[_V1 | _V2 | _V3], bytes] | None = None,
     value_deserializer: Callable[[bytes], _V1 | _V2 | _V3] | None = None,
     timeout: Duration | None = None,
@@ -270,6 +343,7 @@ def redis_hash_map_key(
     /,
     *,
     key_serializer: Callable[[_K1 | _K2 | _K3], bytes] | None = None,
+    key_deserializer: Callable[[bytes], Any] | None = None,
     value_serializer: Callable[[_V1 | _V2 | _V3], bytes] | None = None,
     value_deserializer: Callable[[bytes], _V1 | _V2 | _V3] | None = None,
     timeout: Duration | None = None,
@@ -283,6 +357,7 @@ def redis_hash_map_key(
     /,
     *,
     key_serializer: Callable[[Any], bytes] | None = None,
+    key_deserializer: Callable[[bytes], Any] | None = None,
     value_serializer: Callable[[Any], bytes] | None = None,
     value_deserializer: Callable[[bytes], Any] | None = None,
     timeout: Duration | None = None,
@@ -294,6 +369,7 @@ def redis_hash_map_key(
         name=name,
         key=key,
         key_serializer=key_serializer,
+        key_deserializer=key_deserializer,
         value=value,
         value_serializer=value_serializer,
         value_deserializer=value_deserializer,
@@ -343,23 +419,15 @@ class RedisKey(Generic[_T]):
             duration=self.timeout, error=self.error
         ):
             result = cast("bytes | None", await redis.get(self.name))
-        match result:  # skipif-ci-and-not-linux
-            case None:
-                return None
-            case bytes() as data:
-                if self.deserializer is None:
-                    from utilities.orjson import deserialize
-
-                    return deserialize(data)
-                return self.deserializer(data)
-            case _ as never:
-                assert_never(never)
+        if result is None:  # skipif-ci-and-not-linux
+            raise KeyError(self.name)
+        return _deserialize(  # skipif-ci-and-not-linux
+            result, deserializer=self.deserializer
+        )
 
     async def set(self, redis: Redis, value: _T, /) -> int:
         """Set a value in `redis`."""
-        ser_value = _serialize(  # skipif-ci-and-not-linux
-            value, serializer=self.serializer
-        )
+        ser = _serialize(value, serializer=self.serializer)  # skipif-ci-and-not-linux
         ttl = (  # skipif-ci-and-not-linux
             None
             if self.ttl is None
@@ -369,7 +437,7 @@ class RedisKey(Generic[_T]):
             duration=self.timeout, error=self.error
         ):
             result = await redis.set(  # skipif-ci-and-not-linux
-                self.name, ser_value, px=ttl
+                self.name, ser, px=ttl
             )
         return ensure_int(result)  # skipif-ci-and-not-linux