dycw-utilities 0.153.1__py3-none-any.whl → 0.153.3__py3-none-any.whl

{dycw_utilities-0.153.1.dist-info → dycw_utilities-0.153.3.dist-info}/METADATA

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

{dycw_utilities-0.153.1.dist-info → dycw_utilities-0.153.3.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=tLMJ7LzsnMye2vQj1HzCBHT0fuYeBMXUcof9VDP_uyk,60
+utilities/__init__.py,sha256=1GHQrcKaEUZf3pfIY7NBsyrMxgkxqFe8199dJVber6A,60
 utilities/altair.py,sha256=92E2lCdyHY4Zb-vCw6rEJIsWdKipuu-Tu2ab1ufUfAk,9079
 utilities/asyncio.py,sha256=QXkTtugXkqtYt7Do23zgYErqzdp6jwzPpV_SP9fJ1gI,16780
 utilities/atomicwrites.py,sha256=tPo6r-Rypd9u99u66B9z86YBPpnLrlHtwox_8Z7T34Y,5790
@@ -45,7 +45,7 @@ utilities/parse.py,sha256=JcJn5yXKhIWXBCwgBdPsyu7Hvcuw6kyEdqvaebCaI9k,17951
 utilities/pathlib.py,sha256=qGuU8XPmdgGpy8tOMUgelfXx3kxI8h9IaV3TI_06QGE,8428
 utilities/pickle.py,sha256=MBT2xZCsv0pH868IXLGKnlcqNx2IRVKYNpRcqiQQqxw,653
 utilities/platform.py,sha256=pTn7gw6N4T6LdKrf0virwarof_mze9WtoQlrGMzhGVI,2798
-utilities/polars.py,sha256=uxV4liIQoCO92aERDO-AMfa8Es_-xCKgwZoyTO3PazQ,74410
+utilities/polars.py,sha256=Ba1XxJZ3Q8i_mHkcNxjo4aGuMKwRsCdh0mIDI-V_HXw,76581
 utilities/polars_ols.py,sha256=Uc9V5kvlWZ5cU93lKZ-cfAKdVFFw81tqwLW9PxtUvMs,5618
 utilities/postgres.py,sha256=70BPcb_Na0LqDXJfqu0JwkHkGrwyuKpIVooSm6NlRn8,12467
 utilities/pottery.py,sha256=HJ96oLRarTP37Vhg0WTyB3yAu2hETeg6HgRmpDIqyUs,6581
@@ -74,7 +74,7 @@ utilities/threading.py,sha256=GvBOp4CyhHfN90wGXZuA2VKe9fGzMaEa7oCl4f3nnPU,1009
 utilities/timer.py,sha256=oXfTii6ymu57niP0BDGZjFD55LEHi2a19kqZKiTgaFQ,2588
 utilities/traceback.py,sha256=e0BpxNMybVmELHGsYM5N6LVbfmn0jLhefLoa81NjZBg,9100
 utilities/typed_settings.py,sha256=SFWqS3lAzV7IfNRwqFcTk0YynTcQ7BmrcW2mr_KUnos,4466
-utilities/types.py,sha256=DMHTom46_vSwM4taulNgw6SEzseVggCVxX7e2JZnij8,18404
+utilities/types.py,sha256=SE5UTkI7EVdg_gVehgn9fRQ7TAOi2C1LpEm8qLIhZcs,18455
 utilities/typing.py,sha256=Z-_XDaWyT_6wIo3qfNK-hvRlzxP2Jxa9PgXzm5rDYRA,13790
 utilities/tzdata.py,sha256=fgNVj66yUbCSI_-vrRVzSD3gtf-L_8IEJEPjP_Jel5Y,266
 utilities/tzlocal.py,sha256=KyCXEgCTjqGFx-389JdTuhMRUaT06U1RCMdWoED-qro,728
@@ -87,8 +87,8 @@ utilities/zoneinfo.py,sha256=FBMcUQ4662Aq8SsuCL1OAhDQiyANmVjtb-C30DRrWoE,1966
 utilities/pytest_plugins/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
 utilities/pytest_plugins/pytest_randomly.py,sha256=B1qYVlExGOxTywq2r1SMi5o7btHLk2PNdY_b1p98dkE,409
 utilities/pytest_plugins/pytest_regressions.py,sha256=9v8kAXDM2ycIXJBimoiF4EgrwbUvxTycFWJiGR_GHhM,1466
-dycw_utilities-0.153.1.dist-info/METADATA,sha256=5qPYBod9hSVQarpW6SVN-iqMQgPfp9YYT6u5wPGAAVk,1696
-dycw_utilities-0.153.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.153.1.dist-info/entry_points.txt,sha256=BOD_SoDxwsfJYOLxhrSXhHP_T7iw-HXI9f2WVkzYxvQ,135
-dycw_utilities-0.153.1.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.153.1.dist-info/RECORD,,
+dycw_utilities-0.153.3.dist-info/METADATA,sha256=xSL1sIennAtafYoihcSuowIbjg7Wywuh9l5u3kLM7qg,1696
+dycw_utilities-0.153.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.153.3.dist-info/entry_points.txt,sha256=BOD_SoDxwsfJYOLxhrSXhHP_T7iw-HXI9f2WVkzYxvQ,135
+dycw_utilities-0.153.3.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.153.3.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.153.1"
+__version__ = "0.153.3"

utilities/polars.py

@@ -33,6 +33,7 @@ from polars import (
     any_horizontal,
     col,
     concat,
+    datetime_range,
     int_range,
     lit,
     struct,
@@ -49,6 +50,7 @@ from polars.exceptions import (
 )
 from polars.schema import Schema
 from polars.testing import assert_frame_equal, assert_series_equal
+from whenever import ZonedDateTime
 
 from utilities.dataclasses import _YieldFieldsInstance, yield_fields
 from utilities.errors import ImpossibleCaseError
@@ -129,6 +131,7 @@ DatetimeUSEastern = Datetime(time_zone="US/Eastern")
 DatetimeUTC = Datetime(time_zone="UTC")
 _FINITE_EWM_MIN_WEIGHT = 0.9999
 
+
 ##
 
 
@@ -2021,6 +2024,19 @@ def normal(
 ##
 
 
+def offset_datetime(
+    datetime: ZonedDateTime, offset: str, /, *, n: int = 1
+) -> ZonedDateTime:
+    """Offset a datetime as `polars` would."""
+    sr = Series(values=[datetime.py_datetime()])
+    for _ in range(n):
+        sr = sr.dt.offset_by(offset)
+    return ZonedDateTime.from_py_datetime(sr.item())
+
+
+##
+
+
 @overload
 def order_of_magnitude(column: ExprLike, /, *, round_: bool = False) -> Expr: ...
 @overload
@@ -2041,6 +2057,75 @@ def order_of_magnitude(
 ##
 
 
+@overload
+def period_range(
+    start: ZonedDateTime,
+    end_or_length: ZonedDateTime | int,
+    /,
+    *,
+    interval: str = "1d",
+    time_unit: TimeUnit | None = None,
+    time_zone: TimeZoneLike | None = None,
+    eager: Literal[True],
+) -> Series: ...
+@overload
+def period_range(
+    start: ZonedDateTime,
+    end_or_length: ZonedDateTime | int,
+    /,
+    *,
+    interval: str = "1d",
+    time_unit: TimeUnit | None = None,
+    time_zone: TimeZoneLike | None = None,
+    eager: Literal[False] = False,
+) -> Expr: ...
+@overload
+def period_range(
+    start: ZonedDateTime,
+    end_or_length: ZonedDateTime | int,
+    /,
+    *,
+    interval: str = "1d",
+    time_unit: TimeUnit | None = None,
+    time_zone: TimeZoneLike | None = None,
+    eager: bool = False,
+) -> Series | Expr: ...
+def period_range(
+    start: ZonedDateTime,
+    end_or_length: ZonedDateTime | int,
+    /,
+    *,
+    interval: str = "1d",
+    time_unit: TimeUnit | None = None,
+    time_zone: TimeZoneLike | None = None,
+    eager: bool = False,
+) -> Series | Expr:
+    """Construct a period range."""
+    time_zone_use = None if time_zone is None else ensure_time_zone(time_zone).key
+    match end_or_length:
+        case ZonedDateTime() as end:
+            ...
+        case int() as length:
+            end = offset_datetime(start, interval, n=length)
+        case never:
+            assert_never(never)
+    starts = datetime_range(
+        start.py_datetime(),
+        end.py_datetime(),
+        interval,
+        closed="left",
+        time_unit=time_unit,
+        time_zone=time_zone_use,
+        eager=eager,
+    ).alias("start")
+    ends = (starts.dt.offset_by(interval)).alias("end")
+    period = struct(starts, ends)
+    return try_reify_expr(period, starts, ends)
+
+
+##
+
+
 def reify_exprs(
     *exprs: IntoExprColumn, **named_exprs: IntoExprColumn
 ) -> Expr | Series | DataFrame:
@@ -2529,7 +2614,9 @@ __all__ = [
     "nan_sum_agg",
     "nan_sum_cols",
     "normal",
+    "offset_datetime",
     "order_of_magnitude",
+    "period_range",
     "read_dataframe",
     "read_series",
     "replace_time_zone",

utilities/types.py

@@ -39,7 +39,6 @@ _T_contra = TypeVar("_T_contra", contravariant=True)
 
 
 # basic
-type BoolLike = MaybeStr[bool]
 type OpenMode = Literal[
     "r",
     "w",
@@ -63,13 +62,15 @@ type OpenMode = Literal[
     "a+b",
 ]
 type MaybeCallable[T] = T | Callable[[], T]
-type MaybeCallableBoolLike = MaybeCallable[BoolLike]
 type MaybeStr[T] = T | str
 type MaybeType[T] = T | type[T]
 type StrMapping = Mapping[str, Any]
 type StrStrMapping = Mapping[str, str]
-type TypeLike[T] = type[T] | tuple[type[T], ...]
 type TupleOrStrMapping = tuple[Any, ...] | StrMapping
+type TypeLike[T] = type[T] | tuple[type[T], ...]
+# basic - derived
+type MaybeCallableBoolLike = MaybeCallable[BoolLike]
+type BoolLike = MaybeStr[bool]
 
 
 # asyncio
@@ -114,12 +115,12 @@ IPv6AddressLike = MaybeStr[IPv6Address]
 
 
 # iterables
-type SequenceLT[T] = list[T] | tuple[T, ...]
-# iterables - maybe
 type MaybeCollection[T] = T | Collection[T]
 type MaybeIterable[T] = T | Iterable[T]
+type MaybeList[T] = T | list[T]
+type SequenceLT[T] = list[T] | tuple[T, ...]
+# iterables - dervied
 type MaybeSequence[T] = T | SequenceLT[T]
-# iterables - str
 type SequenceStr = SequenceLT[str]
 type CollectionStr = dict[str, Any] | frozenset[str] | set[str] | SequenceStr
 # iterables - maybe str
@@ -299,6 +300,7 @@ __all__ = [
     "MaybeCollectionStr",
     "MaybeCoro",
     "MaybeIterable",
+    "MaybeList",
     "MaybeSequence",
     "MaybeSequenceStr",
     "MaybeStr",