dycw-utilities 0.165.1__py3-none-any.whl → 0.165.3__py3-none-any.whl

{dycw_utilities-0.165.1.dist-info → dycw_utilities-0.165.3.dist-info}/METADATA

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

{dycw_utilities-0.165.1.dist-info → dycw_utilities-0.165.3.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=jXIaJyG5YtjB8gWKCypYzBJ3Xi_oFaGo1ydJol5wBR0,60
+utilities/__init__.py,sha256=dGyOX1Z3m0mhIPCR1cqAXlybAWUxvEasnTNSAfT9Fh8,60
 utilities/aeventkit.py,sha256=ddoleSwW9zdc2tjX5Ge0pMKtYwV_JMxhHYOxnWX2AGM,12609
 utilities/altair.py,sha256=92E2lCdyHY4Zb-vCw6rEJIsWdKipuu-Tu2ab1ufUfAk,9079
 utilities/asyncio.py,sha256=PUedzQ5deqlSECQ33sam9cRzI9TnygHz3FdOqWJWPTM,15288
@@ -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=X-TaklmHmyJazckJIRNMwwvgSp3q6EGGb0mVnwHEDrI,80811
+utilities/polars.py,sha256=6_k8cU7LePQ942Qfqe5l_tR8ND0M0bLlpnaMvDbRCM8,81754
 utilities/polars_ols.py,sha256=LNTFNLPuYW7fcAHymlbnams_DhitToblYvib3mhKbwI,5615
 utilities/postgres.py,sha256=ynCTTaF-bVEOSW-KEAR-dlLh_hYjeVVjm__-4pEU8Zk,12269
 utilities/pottery.py,sha256=ggMN72Y7wx7Js8VN6eyNyodpm8TIYqZHGghkDPXIVWk,3949
@@ -76,7 +76,7 @@ utilities/timer.py,sha256=oXfTii6ymu57niP0BDGZjFD55LEHi2a19kqZKiTgaFQ,2588
 utilities/traceback.py,sha256=b1nSvlyrGmI1MyZLkkoLVET3DQBSGt9qqIlAAQbyjEw,9629
 utilities/typed_settings.py,sha256=SFWqS3lAzV7IfNRwqFcTk0YynTcQ7BmrcW2mr_KUnos,4466
 utilities/types.py,sha256=oeH-hEC3-67Eja4nLz-Nj9WvK6Z9-3T1zobO_XJpuVg,18735
-utilities/typing.py,sha256=vPqxHE2G5_dbDEgWAyAaTSDbUQE0pmihIj0vdXogbRU,24185
+utilities/typing.py,sha256=QYoCIc71e_u5W-kBeiNzrD-GXxpLtMOGc9PqgZjMXeE,25274
 utilities/tzdata.py,sha256=fgNVj66yUbCSI_-vrRVzSD3gtf-L_8IEJEPjP_Jel5Y,266
 utilities/tzlocal.py,sha256=KyCXEgCTjqGFx-389JdTuhMRUaT06U1RCMdWoED-qro,728
 utilities/uuid.py,sha256=nQZs6tFX4mqtc2Ku3KqjloYCqwpTKeTj8eKwQwh3FQI,1572
@@ -88,8 +88,8 @@ utilities/zoneinfo.py,sha256=tdIScrTB2-B-LH0ukb1HUXKooLknOfJNwHk10MuMYvA,3619
 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.165.1.dist-info/METADATA,sha256=Lo1wurJzugPUwkNpIOKHWWc7zSUL4xWGCSQ7FCWI0ZA,1696
-dycw_utilities-0.165.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.165.1.dist-info/entry_points.txt,sha256=BOD_SoDxwsfJYOLxhrSXhHP_T7iw-HXI9f2WVkzYxvQ,135
-dycw_utilities-0.165.1.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.165.1.dist-info/RECORD,,
+dycw_utilities-0.165.3.dist-info/METADATA,sha256=pkTtRCmg_YK5SUclEGBHKWThH6nFfAdR3vn_EJZjGO8,1696
+dycw_utilities-0.165.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.165.3.dist-info/entry_points.txt,sha256=BOD_SoDxwsfJYOLxhrSXhHP_T7iw-HXI9f2WVkzYxvQ,135
+dycw_utilities-0.165.3.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.165.3.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.165.1"
+__version__ = "0.165.3"

utilities/polars.py

@@ -105,6 +105,7 @@ from utilities.whenever import (
 from utilities.zoneinfo import UTC, to_time_zone_name
 
 if TYPE_CHECKING:
+    import datetime as dt
     from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
     from collections.abc import Set as AbstractSet
 
@@ -2460,6 +2461,34 @@ class RoundToFloatError(Exception):
 ##
 
 
+def search_period(
+    series: Series,
+    date_time: ZonedDateTime,
+    /,
+    *,
+    start_or_end: Literal["start", "end"] = "end",
+) -> int | None:
+    """Search a series of periods for the one containing a given date-time."""
+    start, end = [series.struct[k] for k in ["start", "end"]]
+    py_date_time = date_time.py_datetime()
+    match start_or_end:
+        case "start":
+            index = end.search_sorted(py_date_time, side="right")
+            if index >= len(series):
+                return None
+            item: dt.datetime = series[index]["start"]
+            return index if py_date_time >= item else None
+        case "end":
+            index = end.search_sorted(py_date_time, side="left")
+            if index >= len(series):
+                return None
+            item: dt.datetime = series[index]["start"]
+            return index if py_date_time > item else None
+
+
+##
+
+
 def select_exact(
     df: DataFrame, /, *columns: IntoExprColumn, drop: MaybeIterable[str] | None = None
 ) -> DataFrame:
@@ -2750,6 +2779,7 @@ __all__ = [
     "read_series",
     "replace_time_zone",
     "round_to_float",
+    "search_period",
     "select_exact",
     "serialize_dataframe",
     "set_first_row_as_columns",

utilities/typing.py

@@ -6,12 +6,14 @@ from dataclasses import dataclass, is_dataclass
 from functools import partial
 from itertools import chain
 from pathlib import Path
+from re import search
 from types import NoneType, UnionType
 from typing import (
     Any,
     ForwardRef,
     Literal,
     NamedTuple,
+    NotRequired,
     Optional,  # pyright: ignore[reportDeprecated]
     TypeAliasType,
     TypeGuard,
@@ -56,6 +58,18 @@ def get_args(obj: Any, /, *, optional_drop_none: bool = False) -> tuple[Any, ...
 ##
 
 
+def get_forward_ref_args(obj: Any, /) -> Mapping[str, str]:
+    """Get the forward args."""
+    return {
+        k: v.__forward_arg__
+        for k, v in obj.__annotations__.items()
+        if isinstance(v, ForwardRef)
+    }
+
+
+##
+
+
 def get_literal_elements(obj: Any, /) -> list[Any]:
     """Get the elements of a literal annotation."""
     return _get_literal_elements_inner(obj)
@@ -151,21 +165,20 @@ def get_type_hints(
     globalns_use = globals() | ({} if globalns is None else dict(globalns))
     localns_use = {} if localns is None else dict(localns)
     result: dict[str, Any] = obj.__annotations__
-    result = {
-        k: v.__forward_arg__ if isinstance(v, ForwardRef) else v
-        for k, v in result.items()
-    }
+    result = result | dict(get_forward_ref_args(obj))
     try:
-        hints = _get_type_hints(obj, globalns=globalns_use, localns=localns_use)
+        hints = _get_type_hints(
+            obj, globalns=globalns_use, localns=localns_use, include_extras=True
+        )
     except NameError as error:
         if warn_name_errors:
             warn(f"Error getting type hints for {obj!r}; {error}", stacklevel=2)
     else:
-        result.update({
+        result = result | {
             key: value
             for key, value in hints.items()
             if (key not in result) or isinstance(result[key], str)
-        })
+        }
     return result
 
 
@@ -393,17 +406,21 @@ def _is_instance_typed_dict[T: _TypedDictMeta](
     hints = get_type_hints(
         type_, globalns=globalns, localns=localns, warn_name_errors=warn_name_errors
     )
-    if not set(obj).issuperset(hints):
+    optional = {
+        k for k, v in type_.__annotations__.items() if is_not_required_annotation(v)
+    }
+    required = {k: v for k, v in hints.items() if k not in optional}
+    if not set(obj).issuperset(required):
         return False
     return all(
         is_instance_gen(
             obj[k],
-            hints[k],
+            required[k],
             globalns=globalns,
             localns=localns,
             warn_name_errors=warn_name_errors,
         )
-        for k in hints
+        for k in required
     )
 
 
@@ -577,6 +594,30 @@ def _is_namedtuple_core(obj: Any, /) -> bool:
 ##
 
 
+def is_not_required_annotation(obj: Any) -> bool:
+    """Check if an annotation is not required."""
+    if is_not_required_type(obj):
+        return True
+    match obj:
+        case str() as text:
+            return bool(search("NotRequired", text))
+        case ForwardRef() as fr:
+            return is_not_required_annotation(fr.__forward_arg__)
+        case _:
+            return False
+
+
+##
+
+
+def is_not_required_type(obj: Any, /) -> bool:
+    """Check if an object is a not-required type annotation."""
+    return (obj is NotRequired) or _is_annotation_of_type(obj, NotRequired)
+
+
+##
+
+
 def is_optional_type(obj: Any, /) -> bool:
     """Check if an object is an optional type annotation."""
     is_optional = _is_annotation_of_type(obj, Optional)  # pyright: ignore[reportDeprecated]
@@ -889,6 +930,8 @@ __all__ = [
     "is_mapping_type",
     "is_namedtuple_class",
     "is_namedtuple_instance",
+    "is_not_required_annotation",
+    "is_not_required_type",
     "is_optional_type",
     "is_sequence_of",
     "is_sequence_of_tuple_or_str_mapping",