dycw-utilities 0.165.0__tar.gz → 0.165.2__tar.gz

{dycw_utilities-0.165.0 → dycw_utilities-0.165.2}/PKG-INFO

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

{dycw_utilities-0.165.0 → dycw_utilities-0.165.2}/pyproject.toml

@@ -233,7 +233,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.165.0"
+version = "0.165.2"
 
 [project.entry-points.pytest11]
 pytest-randomly = "utilities.pytest_plugins.pytest_randomly"
@@ -266,7 +266,7 @@ test = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.165.0"
+current_version = "0.165.2"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"

{dycw_utilities-0.165.0 → dycw_utilities-0.165.2}/src/tests/test_contextlib.py

@@ -4,6 +4,7 @@ import asyncio
 import time
 from asyncio import run
 from dataclasses import dataclass
+from inspect import signature
 from multiprocessing import Process
 from pathlib import Path
 from typing import TYPE_CHECKING, override
@@ -103,6 +104,15 @@ class TestEnhancedContextManager:
             assert not cleared
         assert cleared
 
+    def test_sync_signature(self) -> None:
+        @enhanced_context_manager
+        def yield_marker(x: int, y: int, /) -> Iterator[int]:
+            yield x + y
+
+        sig = set(signature(yield_marker).parameters)
+        expected = {"x", "y"}
+        assert sig == expected
+
     @given(
         sigabrt=booleans(),
         sigfpe=booleans(),
@@ -142,6 +152,15 @@ class TestEnhancedContextManager:
             assert not cleared
         assert cleared
 
+    def test_async_signature(self) -> None:
+        @enhanced_async_context_manager
+        async def yield_marker(x: int, y: int, /) -> AsyncIterator[int]:
+            yield x + y
+
+        sig = set(signature(yield_marker).parameters)
+        expected = {"x", "y"}
+        assert sig == expected
+
     @mark.parametrize(
         "target",
         [

{dycw_utilities-0.165.0 → dycw_utilities-0.165.2}/src/tests/test_typing.py

@@ -10,9 +10,11 @@ from typing import (
     TYPE_CHECKING,
     Any,
     Final,
+    ForwardRef,
     Literal,
     NamedTuple,
-    TypedDict,
+    NotRequired,
+    _TypedDictMeta,  # pyright: ignore[reportAttributeAccessIssue]
     assert_never,
 )
 from uuid import UUID
@@ -50,6 +52,8 @@ from tests.test_typing_funcs.no_future import (
     DataClassNoFutureNestedInnerFirstOuter,
     DataClassNoFutureNestedOuterFirstInner,
     DataClassNoFutureNestedOuterFirstOuter,
+    TypedDictNoFutureIntFloat,
+    TypedDictNoFutureIntFloatOptional,
 )
 from tests.test_typing_funcs.with_future import (
     DataClassFutureDate,
@@ -80,10 +84,11 @@ from tests.test_typing_funcs.with_future import (
     TrueOrFalseFutureLit,
     TrueOrFalseFutureTypeLit,
     TypedDictFutureIntFloat,
+    TypedDictFutureIntFloatOptional,
 )
 from utilities.hypothesis import text_ascii
 from utilities.sentinel import Sentinel
-from utilities.types import LogLevel, Number, Parallelism, Seed
+from utilities.types import LogLevel, Number, Parallelism, Seed, StrMapping
 from utilities.typing import (
     IsInstanceGenError,
     IsSubclassGenError,
@@ -92,6 +97,7 @@ from utilities.typing import (
     _GetUnionTypeClassesInternalTypeError,
     _GetUnionTypeClassesUnionTypeError,
     get_args,
+    get_forward_ref_args,
     get_literal_elements,
     get_type_classes,
     get_type_hints,
@@ -107,6 +113,8 @@ from utilities.typing import (
     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,
@@ -158,6 +166,13 @@ class TestGetArgs:
         assert result == expected
 
 
+class TestGetForwardRefArgs:
+    def test_main(self) -> None:
+        args = get_forward_ref_args(TypedDictFutureIntFloat)
+        expected = {"int_": "int", "float_": "float"}
+        assert args == expected
+
+
 type _PlusOrMinusOneLit = Literal[1, -1]
 type _TruthLit = Literal["true", "false"]
 type _True = Literal["true"]
@@ -495,13 +510,23 @@ class TestGetTypeHints:
         expected = {"truth": TrueOrFalseFutureTypeLit}
         assert hints == expected
 
-    def test_typed_dict(self) -> None:
-        class Example(TypedDict):
-            int_: int
-            float_: float
-
-        hints = get_type_hints(Example)
-        expected = {"int_": int, "float_": float}
+    @mark.parametrize(
+        ("obj", "expected"),
+        [
+            param(TypedDictNoFutureIntFloat, {"int_": int, "float_": float}),
+            param(TypedDictFutureIntFloat, {"int_": int, "float_": float}),
+            param(
+                TypedDictNoFutureIntFloatOptional,
+                {"int_": int, "float_": NotRequired[float]},
+            ),
+            param(
+                TypedDictFutureIntFloatOptional,
+                {"int_": int, "float_": NotRequired[float]},
+            ),
+        ],
+    )
+    def test_typed_dict(self, *, obj: _TypedDictMeta, expected: StrMapping) -> None:
+        hints = get_type_hints(obj)
         assert hints == expected
 
     @given(data=data())
@@ -637,6 +662,8 @@ class TestIsAnnotationOfType:
             param(is_mapping_type, list[int], False),
             param(is_mapping_type, set[int], False),
             param(is_mapping_type, tuple[int, int], False),
+            param(is_not_required_type, NotRequired, True),
+            param(is_not_required_type, NotRequired[int], True),
             param(is_optional_type, Literal["a", "b", "c"] | None, True),
             param(is_optional_type, Literal["a", "b", "c"], False),
             param(is_optional_type, int | None, True),
@@ -824,8 +851,39 @@ class TestIsInstanceGen:
             param({"int_": 0, "float_": 0.0, "extra": None}, True),
         ],
     )
-    def test_typed_dict(self, *, obj: Any, expected: bool) -> None:
-        result = is_instance_gen(obj, TypedDictFutureIntFloat)
+    @mark.parametrize(
+        "cls", [param(TypedDictNoFutureIntFloat), param(TypedDictFutureIntFloat)]
+    )
+    def test_typed_dict(self, *, obj: Any, cls: _TypedDictMeta, expected: bool) -> None:
+        result = is_instance_gen(obj, cls)
+        assert result is expected
+
+    @mark.parametrize(
+        ("obj", "expected"),
+        [
+            param(None, False),
+            param({}, False),
+            param({None: False}, False),
+            param({"int_": None}, False),
+            param({"int_": 0}, True),
+            param({"int_": None, "float_": None}, False),
+            param({"int_": 0, "float_": None}, True),
+            param({"int_": None, "float_": 0.0}, False),
+            param({"int_": 0, "float_": 0.0}, True),
+            param({"int_": 0, "float_": 0.0, "extra": None}, True),
+        ],
+    )
+    @mark.parametrize(
+        "cls",
+        [
+            param(TypedDictNoFutureIntFloatOptional),
+            param(TypedDictFutureIntFloatOptional),
+        ],
+    )
+    def test_typed_dict_optional(
+        self, *, obj: Any, cls: _TypedDictMeta, expected: bool
+    ) -> None:
+        result = is_instance_gen(obj, cls)
         assert result is expected
 
     def test_error(self) -> None:
@@ -884,6 +942,27 @@ class TestIsNamedTuple:
         assert not is_namedtuple_instance(Example(x=0))
 
 
+class TestIsNotRequiredAnnotation:
+    @mark.parametrize(
+        ("obj", "expected"),
+        [
+            param(NotRequired, True),
+            param(NotRequired[int], True),
+            param(int, False),
+            param("NotRequired", True),
+            param("NotRequired[int]", True),
+            param("int", False),
+            param(ForwardRef("NotRequired"), True),
+            param(ForwardRef("NotRequired[int]"), True),
+            param(ForwardRef("int"), False),
+            param(None, False),
+        ],
+    )
+    def test_main(self, *, obj: Any, expected: bool) -> None:
+        result = is_not_required_annotation(obj)
+        assert result is expected
+
+
 class TestIsSequenceOf:
     @mark.parametrize(
         ("obj", "expected"),

{dycw_utilities-0.165.0 → dycw_utilities-0.165.2}/src/tests/test_typing_funcs/no_future.py

@@ -1,5 +1,5 @@
 from dataclasses import dataclass
-from typing import Literal
+from typing import Literal, NotRequired, TypedDict
 
 TrueOrFalseNoFutureLit = Literal["true", "false"]
 type TrueOrFalseNoFutureTypeLit = Literal["true", "false"]
@@ -33,3 +33,13 @@ class DataClassNoFutureNestedOuterFirstOuter:
 @dataclass(kw_only=True)
 class DataClassNoFutureNestedOuterFirstInner:
     int_: int
+
+
+class TypedDictNoFutureIntFloat(TypedDict):
+    int_: int
+    float_: float
+
+
+class TypedDictNoFutureIntFloatOptional(TypedDict):
+    int_: int
+    float_: NotRequired[float]

{dycw_utilities-0.165.0 → dycw_utilities-0.165.2}/src/tests/test_typing_funcs/with_future.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Literal, TypedDict, override
+from typing import TYPE_CHECKING, Literal, NotRequired, TypedDict, override
 
 if TYPE_CHECKING:
     from pathlib import Path
@@ -239,3 +239,8 @@ class DataClassFutureZonedDateTimePeriod:
 class TypedDictFutureIntFloat(TypedDict):
     int_: int
     float_: float
+
+
+class TypedDictFutureIntFloatOptional(TypedDict):
+    int_: int
+    float_: NotRequired[float]

{dycw_utilities-0.165.0 → dycw_utilities-0.165.2}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.165.0"
+__version__ = "0.165.2"

{dycw_utilities-0.165.0 → dycw_utilities-0.165.2}/src/utilities/contextlib.py

@@ -8,7 +8,7 @@ from contextlib import (
     asynccontextmanager,
     contextmanager,
 )
-from functools import partial
+from functools import partial, wraps
 from signal import SIGABRT, SIGFPE, SIGILL, SIGINT, SIGSEGV, SIGTERM, getsignal, signal
 from typing import TYPE_CHECKING, Any, assert_never, cast, overload
 
@@ -77,6 +77,7 @@ def enhanced_context_manager[**P, T_co](
     make_gcm = contextmanager(func)
 
     @contextmanager
+    @wraps(func)
     def wrapped(*args: P.args, **kwargs: P.kwargs) -> Iterator[T_co]:
         gcm = make_gcm(*args, **kwargs)
         sigabrt0 = _swap_handler(SIGABRT, gcm) if sigabrt else None
@@ -159,6 +160,7 @@ def enhanced_async_context_manager[**P, T_co](
     make_agcm = asynccontextmanager(func)
 
     @asynccontextmanager
+    @wraps(func)
     async def wrapped(*args: P.args, **kwargs: P.kwargs) -> AsyncIterator[T_co]:
         agcm = make_agcm(*args, **kwargs)
         sigabrt0 = _swap_handler(SIGABRT, agcm) if sigabrt else None

{dycw_utilities-0.165.0 → dycw_utilities-0.165.2}/src/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",