dycw-utilities 0.148.5__py3-none-any.whl → 0.174.12__py3-none-any.whl

utilities/redis.py

@@ -25,7 +25,9 @@ from utilities.contextlib import enhanced_async_context_manager
 from utilities.errors import ImpossibleCaseError
 from utilities.functions import ensure_int, identity
 from utilities.iterables import always_iterable, one
-from utilities.whenever import MILLISECOND, SECOND, to_milliseconds, to_seconds
+from utilities.os import is_pytest
+from utilities.typing import is_instance_gen
+from utilities.whenever import MILLISECOND, SECOND, to_milliseconds, to_nanoseconds
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator, Awaitable, Collection, Iterable
@@ -35,7 +37,7 @@ if TYPE_CHECKING:
     from redis.typing import EncodableT
 
     from utilities.iterables import MaybeIterable
-    from utilities.types import Delta, MaybeListStr, MaybeSequence, MaybeType, TypeLike
+    from utilities.types import Delta, MaybeSequence, MaybeType, TypeLike
 
 
 _PUBLISH_TIMEOUT: Delta = SECOND
@@ -187,7 +189,7 @@ def redis_hash_map_key[K, V](
     value_serializer: Callable[[V], bytes] | None = None,
     value_deserializer: Callable[[bytes], V] | None = None,
     timeout: Delta | None = None,
-    error: type[Exception] = TimeoutError,
+    error: MaybeType[BaseException] = TimeoutError,
     ttl: Delta | None = None,
 ) -> RedisHashMapKey[K, V]: ...
 @overload
@@ -202,7 +204,7 @@ def redis_hash_map_key[K, V1, V2](
     value_serializer: Callable[[V1 | V2], bytes] | None = None,
     value_deserializer: Callable[[bytes], V1 | V2] | None = None,
     timeout: Delta | None = None,
-    error: type[Exception] = TimeoutError,
+    error: MaybeType[BaseException] = TimeoutError,
     ttl: Delta | None = None,
 ) -> RedisHashMapKey[K, V1 | V2]: ...
 @overload
@@ -217,7 +219,7 @@ def redis_hash_map_key[K, V1, V2, V3](
     value_serializer: Callable[[V1 | V2 | V3], bytes] | None = None,
     value_deserializer: Callable[[bytes], V1 | V2 | V3] | None = None,
     timeout: Delta | None = None,
-    error: type[Exception] = TimeoutError,
+    error: MaybeType[BaseException] = TimeoutError,
     ttl: Delta | None = None,
 ) -> RedisHashMapKey[K, V1 | V2 | V3]: ...
 @overload
@@ -232,7 +234,7 @@ def redis_hash_map_key[K1, K2, V](
     value_serializer: Callable[[V], bytes] | None = None,
     value_deserializer: Callable[[bytes], V] | None = None,
     timeout: Delta | None = None,
-    error: type[Exception] = TimeoutError,
+    error: MaybeType[BaseException] = TimeoutError,
     ttl: Delta | None = None,
 ) -> RedisHashMapKey[K1 | K2, V]: ...
 @overload
@@ -247,7 +249,7 @@ def redis_hash_map_key[K1, K2, V1, V2](
     value_serializer: Callable[[V1 | V2], bytes] | None = None,
     value_deserializer: Callable[[bytes], V1 | V2] | None = None,
     timeout: Delta | None = None,
-    error: type[Exception] = TimeoutError,
+    error: MaybeType[BaseException] = TimeoutError,
     ttl: Delta | None = None,
 ) -> RedisHashMapKey[K1 | K2, V1 | V2]: ...
 @overload
@@ -262,7 +264,7 @@ def redis_hash_map_key[K1, K2, V1, V2, V3](
     value_serializer: Callable[[V1 | V2 | V3], bytes] | None = None,
     value_deserializer: Callable[[bytes], V1 | V2 | V3] | None = None,
     timeout: Delta | None = None,
-    error: type[Exception] = TimeoutError,
+    error: MaybeType[BaseException] = TimeoutError,
     ttl: Delta | None = None,
 ) -> RedisHashMapKey[K1 | K2, V1 | V2 | V3]: ...
 @overload
@@ -277,7 +279,7 @@ def redis_hash_map_key[K1, K2, K3, V](
     value_serializer: Callable[[V], bytes] | None = None,
     value_deserializer: Callable[[bytes], V] | None = None,
     timeout: Delta | None = None,
-    error: type[Exception] = TimeoutError,
+    error: MaybeType[BaseException] = TimeoutError,
     ttl: Delta | None = None,
 ) -> RedisHashMapKey[K1 | K2 | K3, V]: ...
 @overload
@@ -292,7 +294,7 @@ def redis_hash_map_key[K1, K2, K3, V1, V2](
     value_serializer: Callable[[V1 | V2], bytes] | None = None,
     value_deserializer: Callable[[bytes], V1 | V2] | None = None,
     timeout: Delta | None = None,
-    error: type[Exception] = TimeoutError,
+    error: MaybeType[BaseException] = TimeoutError,
     ttl: Delta | None = None,
 ) -> RedisHashMapKey[K1 | K2 | K3, V1 | V2]: ...
 @overload
@@ -307,7 +309,7 @@ def redis_hash_map_key[K1, K2, K3, V1, V2, V3](
     value_serializer: Callable[[V1 | V2 | V3], bytes] | None = None,
     value_deserializer: Callable[[bytes], V1 | V2 | V3] | None = None,
     timeout: Delta | None = None,
-    error: type[Exception] = TimeoutError,
+    error: MaybeType[BaseException] = TimeoutError,
     ttl: Delta | None = None,
 ) -> RedisHashMapKey[K1 | K2 | K3, V1 | V2 | V3]: ...
 @overload
@@ -322,7 +324,7 @@ def redis_hash_map_key[K, K1, K2, K3, V, V1, V2, V3](
     value_serializer: Callable[[V1 | V2 | V3], bytes] | None = None,
     value_deserializer: Callable[[bytes], V1 | V2 | V3] | None = None,
     timeout: Delta | None = None,
-    error: type[Exception] = TimeoutError,
+    error: MaybeType[BaseException] = TimeoutError,
     ttl: Delta | None = None,
 ) -> RedisHashMapKey[K, V]: ...
 def redis_hash_map_key[K, V](
@@ -337,7 +339,7 @@ def redis_hash_map_key[K, V](
     value_deserializer: Callable[[bytes], Any] | None = None,
     timeout: Delta | None = None,
     ttl: Delta | None = None,
-    error: type[Exception] = TimeoutError,
+    error: MaybeType[BaseException] = TimeoutError,
 ) -> RedisHashMapKey[K, V]:
     """Create a redis key."""
     return RedisHashMapKey(  # skipif-ci-and-not-linux
@@ -386,7 +388,7 @@ class RedisKey[T]:
         match result:  # skipif-ci-and-not-linux
             case 0 | 1 as value:
                 return bool(value)
-            case _ as never:
+            case never:
                 assert_never(never)
 
     async def get(self, redis: Redis, /) -> T:
@@ -425,7 +427,7 @@ def redis_key[T](
     serializer: Callable[[T], bytes] | None = None,
     deserializer: Callable[[bytes], T] | None = None,
     timeout: Delta | None = None,
-    error: type[Exception] = TimeoutError,
+    error: MaybeType[BaseException] = TimeoutError,
     ttl: Delta | None = None,
 ) -> RedisKey[T]: ...
 @overload
@@ -437,7 +439,7 @@ def redis_key[T1, T2](
     serializer: Callable[[T1 | T2], bytes] | None = None,
     deserializer: Callable[[bytes], T1 | T2] | None = None,
     timeout: Delta | None = None,
-    error: type[Exception] = TimeoutError,
+    error: MaybeType[BaseException] = TimeoutError,
     ttl: Delta | None = None,
 ) -> RedisKey[T1 | T2]: ...
 @overload
@@ -449,7 +451,7 @@ def redis_key[T1, T2, T3](
     serializer: Callable[[T1 | T2 | T3], bytes] | None = None,
     deserializer: Callable[[bytes], T1 | T2 | T3] | None = None,
     timeout: Delta | None = None,
-    error: type[Exception] = TimeoutError,
+    error: MaybeType[BaseException] = TimeoutError,
     ttl: Delta | None = None,
 ) -> RedisKey[T1 | T2 | T3]: ...
 @overload
@@ -461,7 +463,7 @@ def redis_key[T1, T2, T3, T4](
     serializer: Callable[[T1 | T2 | T3 | T4], bytes] | None = None,
     deserializer: Callable[[bytes], T1 | T2 | T3 | T4] | None = None,
     timeout: Delta | None = None,
-    error: type[Exception] = TimeoutError,
+    error: MaybeType[BaseException] = TimeoutError,
     ttl: Delta | None = None,
 ) -> RedisKey[T1 | T2 | T3 | T4]: ...
 @overload
@@ -473,7 +475,7 @@ def redis_key[T1, T2, T3, T4, T5](
     serializer: Callable[[T1 | T2 | T3 | T4 | T5], bytes] | None = None,
     deserializer: Callable[[bytes], T1 | T2 | T3 | T4 | T5] | None = None,
     timeout: Delta | None = None,
-    error: type[Exception] = TimeoutError,
+    error: MaybeType[BaseException] = TimeoutError,
     ttl: Delta | None = None,
 ) -> RedisKey[T1 | T2 | T3 | T4 | T5]: ...
 @overload
@@ -485,7 +487,7 @@ def redis_key[T, T1, T2, T3, T4, T5](
     serializer: Callable[[T1 | T2 | T3 | T4 | T5], bytes] | None = None,
     deserializer: Callable[[bytes], T1 | T2 | T3 | T4 | T5] | None = None,
     timeout: Delta | None = None,
-    error: type[Exception] = TimeoutError,
+    error: MaybeType[BaseException] = TimeoutError,
     ttl: Delta | None = None,
 ) -> RedisKey[T]: ...
 def redis_key[T](
@@ -496,7 +498,7 @@ def redis_key[T](
     serializer: Callable[[Any], bytes] | None = None,
     deserializer: Callable[[bytes], Any] | None = None,
     timeout: Delta | None = None,
-    error: type[Exception] = TimeoutError,
+    error: MaybeType[BaseException] = TimeoutError,
     ttl: Delta | None = None,
 ) -> RedisKey[T]:
     """Create a redis key."""
@@ -522,7 +524,7 @@ async def publish[T](
     /,
     *,
     serializer: Callable[[T], EncodableT],
-    timeout: Delta = _PUBLISH_TIMEOUT,
+    timeout: Delta | None = _PUBLISH_TIMEOUT,
 ) -> int: ...
 @overload
 async def publish(
@@ -532,7 +534,7 @@ async def publish(
     /,
     *,
     serializer: None = None,
-    timeout: Delta = _PUBLISH_TIMEOUT,
+    timeout: Delta | None = _PUBLISH_TIMEOUT,
 ) -> int: ...
 @overload
 async def publish[T](
@@ -542,7 +544,7 @@ async def publish[T](
     /,
     *,
     serializer: Callable[[T], EncodableT] | None = None,
-    timeout: Delta = _PUBLISH_TIMEOUT,
+    timeout: Delta | None = _PUBLISH_TIMEOUT,
 ) -> int: ...
 async def publish[T](
     redis: Redis,
@@ -551,7 +553,7 @@ async def publish[T](
     /,
     *,
     serializer: Callable[[T], EncodableT] | None = None,
-    timeout: Delta = _PUBLISH_TIMEOUT,
+    timeout: Delta | None = _PUBLISH_TIMEOUT,
 ) -> int:
     """Publish an object to a channel."""
     match data, serializer:  # skipif-ci-and-not-linux
@@ -561,7 +563,7 @@ async def publish[T](
             raise PublishError(data=data)
         case _, Callable():
             data_use = serializer(data)
-        case _ as never:
+        case never:
             assert_never(never)
     async with timeout_td(timeout):  # skipif-ci-and-not-linux
         response = await redis.publish(channel, data_use)  # skipif-ci-and-not-linux
@@ -583,11 +585,11 @@ class PublishError(Exception):
 async def publish_many[T](
     redis: Redis,
     channel: str,
-    data: MaybeSequence[bytes | T] | MaybeListStr,
+    data: MaybeSequence[bytes | str | T],
     /,
     *,
     serializer: Callable[[T], EncodableT] | None = None,
-    timeout: Delta = _PUBLISH_TIMEOUT,
+    timeout: Delta | None = _PUBLISH_TIMEOUT,
 ) -> Sequence[bool]:
     """Publish an object/multiple objects to a channel."""
     async with TaskGroup() as tg:
@@ -613,7 +615,7 @@ async def _try_publish[T](
     /,
     *,
     serializer: Callable[[T], EncodableT] | None = None,
-    timeout: Delta = _PUBLISH_TIMEOUT,
+    timeout: Delta | None = _PUBLISH_TIMEOUT,
 ) -> bool:
     try:
         _ = await publish(redis, channel, data, serializer=serializer, timeout=timeout)
@@ -638,9 +640,11 @@ def subscribe(
     /,
     *,
     timeout: Delta | None = _SUBSCRIBE_TIMEOUT,
-    sleep: Delta = _SUBSCRIBE_SLEEP,
     output: Literal["raw"],
-    filter_: Callable[[_RedisMessage], bool] | None = None,
+    error_transform: Callable[[_RedisMessage, Exception], None] | None = None,
+    filter_: Callable[[bytes], bool] | None = None,
+    error_filter: Callable[[bytes, Exception], None] | None = None,
+    sleep: Delta = _SUBSCRIBE_SLEEP,
 ) -> AsyncIterator[Task[None]]: ...
 @overload
 @enhanced_async_context_manager
@@ -651,9 +655,11 @@ def subscribe(
     /,
     *,
     timeout: Delta | None = _SUBSCRIBE_TIMEOUT,
-    sleep: Delta = _SUBSCRIBE_SLEEP,
     output: Literal["bytes"],
+    error_transform: Callable[[_RedisMessage, Exception], None] | None = None,
     filter_: Callable[[bytes], bool] | None = None,
+    error_filter: Callable[[bytes, Exception], None] | None = None,
+    sleep: Delta = _SUBSCRIBE_SLEEP,
 ) -> AsyncIterator[Task[None]]: ...
 @overload
 @enhanced_async_context_manager
@@ -664,9 +670,11 @@ def subscribe(
     /,
     *,
     timeout: Delta | None = _SUBSCRIBE_TIMEOUT,
-    sleep: Delta = _SUBSCRIBE_SLEEP,
     output: Literal["text"] = "text",
+    error_transform: Callable[[_RedisMessage, Exception], None] | None = None,
     filter_: Callable[[str], bool] | None = None,
+    error_filter: Callable[[str, Exception], None] | None = None,
+    sleep: Delta = _SUBSCRIBE_SLEEP,
 ) -> AsyncIterator[Task[None]]: ...
 @overload
 @enhanced_async_context_manager
@@ -677,9 +685,11 @@ def subscribe[T](
     /,
     *,
     timeout: Delta | None = _SUBSCRIBE_TIMEOUT,
-    sleep: Delta = _SUBSCRIBE_SLEEP,
     output: Callable[[bytes], T],
+    error_transform: Callable[[_RedisMessage, Exception], None] | None = None,
     filter_: Callable[[T], bool] | None = None,
+    error_filter: Callable[[T, Exception], None] | None = None,
+    sleep: Delta = _SUBSCRIBE_SLEEP,
 ) -> AsyncIterator[Task[None]]: ...
 @enhanced_async_context_manager
 async def subscribe[T](
@@ -689,28 +699,27 @@ async def subscribe[T](
     /,
     *,
     timeout: Delta | None = _SUBSCRIBE_TIMEOUT,
-    sleep: Delta = _SUBSCRIBE_SLEEP,
     output: Literal["raw", "bytes", "text"] | Callable[[bytes], T] = "text",
-    filter_: Callable[[Any], bool] | None = None,
+    error_transform: Callable[[_RedisMessage, Exception], None] | None = None,
+    filter_: Callable[[T], bool] | None = None,
+    error_filter: Callable[[T, Exception], None] | None = None,
+    sleep: Delta = _SUBSCRIBE_SLEEP,
 ) -> AsyncIterator[Task[None]]:
     """Subscribe to the data of a given channel(s)."""
     channels = list(always_iterable(channels))  # skipif-ci-and-not-linux
     match output:  # skipif-ci-and-not-linux
         case "raw":
-            transform = cast("Any", identity)
+            transform = cast("Callable[[_RedisMessage], T]", identity)
         case "bytes":
-            transform = cast("Any", itemgetter("data"))
+            transform = cast("Callable[[_RedisMessage], T]", itemgetter("data"))
         case "text":
-
-            def transform(message: _RedisMessage, /) -> str:  # pyright: ignore[reportRedeclaration]
-                return message["data"].decode()
-
+            transform = cast("Callable[[_RedisMessage], T]", _decoded_data)
         case Callable() as deserialize:
 
             def transform(message: _RedisMessage, /) -> T:
                 return deserialize(message["data"])
 
-        case _ as never:
+        case never:
             assert_never(never)
 
     task = create_task(  # skipif-ci-and-not-linux
@@ -720,8 +729,10 @@ async def subscribe[T](
             transform,
             queue,
             timeout=timeout,
-            sleep=sleep,
+            error_transform=error_transform,
             filter_=filter_,
+            error_filter=error_filter,
+            sleep=sleep,
         )
     )
     try:  # skipif-ci-and-not-linux
@@ -730,27 +741,31 @@ async def subscribe[T](
         try:
             _ = task.cancel()
         except RuntimeError as error:  # pragma: no cover
-            from utilities.pytest import is_pytest
-
             if (not is_pytest()) or (error.args[0] != "Event loop is closed"):
                 raise
         with suppress(CancelledError):
             await task
 
 
-async def _subscribe_core(
+def _decoded_data(message: _RedisMessage, /) -> str:
+    return message["data"].decode()
+
+
+async def _subscribe_core[T](
     redis: Redis,
     channels: MaybeIterable[str],
-    transform: Callable[[_RedisMessage], Any],
+    transform: Callable[[_RedisMessage], T],
     queue: Queue[Any],
     /,
     *,
     timeout: Delta | None = _SUBSCRIBE_TIMEOUT,
+    error_transform: Callable[[_RedisMessage, Exception], None] | None = None,
+    filter_: Callable[[T], bool] | None = None,
+    error_filter: Callable[[T, Exception], None] | None = None,
     sleep: Delta = _SUBSCRIBE_SLEEP,
-    filter_: Callable[[Any], bool] | None = None,
 ) -> None:
     timeout_use = (  # skipif-ci-and-not-linux
-        None if timeout is None else to_seconds(timeout)
+        None if timeout is None else (to_nanoseconds(timeout) / 1e9)
     )
     is_subscribe_message = partial(  # skipif-ci-and-not-linux
         _is_message, channels={c.encode() for c in channels}
@@ -759,9 +774,14 @@ async def _subscribe_core(
         while True:
             message = await pubsub.get_message(timeout=timeout_use)
             if is_subscribe_message(message):
-                transformed = transform(message)
-                if (filter_ is None) or filter_(transformed):
-                    queue.put_nowait(transformed)
+                _handle_message(
+                    message,
+                    transform,
+                    queue,
+                    error_transform=error_transform,
+                    filter_=filter_,
+                    error_filter=error_filter,
+                )
             else:
                 await sleep_td(sleep)
 
@@ -769,17 +789,34 @@ async def _subscribe_core(
 def _is_message(
     message: Any, /, *, channels: Collection[bytes]
 ) -> TypeGuard[_RedisMessage]:
-    return (
-        isinstance(message, Mapping)
-        and ("type" in message)
-        and (message["type"] in {"subscribe", "psubscribe", "message", "pmessage"})
-        and ("pattern" in message)
-        and ((message["pattern"] is None) or isinstance(message["pattern"], str))
-        and ("channel" in message)
-        and (message["channel"] in channels)
-        and ("data" in message)
-        and isinstance(message["data"], bytes)
-    )
+    return is_instance_gen(message, _RedisMessage) and (message["channel"] in channels)
+
+
+def _handle_message[T](
+    message: _RedisMessage,
+    transform: Callable[[_RedisMessage], T],
+    queue: Queue[Any],
+    /,
+    *,
+    error_transform: Callable[[_RedisMessage, Exception], None] | None = None,
+    filter_: Callable[[T], bool] | None = None,
+    error_filter: Callable[[T, Exception], None] | None = None,
+) -> None:
+    try:
+        transformed = transform(message)
+    except Exception as error:  # noqa: BLE001
+        if error_transform is not None:
+            error_transform(message, error)
+        return
+    if filter_ is None:
+        queue.put_nowait(transformed)
+        return
+    try:
+        if filter_(transformed):
+            queue.put_nowait(transformed)
+    except Exception as error:  # noqa: BLE001
+        if error_filter is not None:
+            error_filter(transformed, error)
 
 
 class _RedisMessage(TypedDict):

utilities/sentinel.py

@@ -4,6 +4,8 @@ from dataclasses import dataclass
 from re import IGNORECASE, search
 from typing import Any, override
 
+from typing_extensions import TypeIs
+
 
 class _Meta(type):
     """Metaclass for the sentinel."""
@@ -34,6 +36,13 @@ class Sentinel(metaclass=_Meta):
 
 sentinel = Sentinel()
 
+##
+
+
+def is_sentinel(obj: Any, /) -> TypeIs[Sentinel]:
+    """Check if an object is the sentinel."""
+    return obj is sentinel
+
 
 ##
 
@@ -58,6 +67,7 @@ __all__ = [
     "SENTINEL_REPR",
     "ParseSentinelError",
     "Sentinel",
+    "is_sentinel",
     "parse_sentinel",
     "sentinel",
 ]

utilities/shelve.py

@@ -12,12 +12,15 @@ if TYPE_CHECKING:
     from utilities.types import PathLike
 
 
+type _Flag = Literal["r", "w", "c", "n"]
+
+
 @contextmanager
 def yield_shelf(
     path: PathLike,
     /,
     *,
-    flag: Literal["r", "w", "c", "n"] = "c",
+    flag: _Flag = "c",
     protocol: int | None = None,
     writeback: bool = False,
 ) -> Iterator[Shelf[Any]]:

utilities/shutil.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import override
+
+
+def which(cmd: str, /) -> Path:
+    path = shutil.which(cmd)
+    if path is None:
+        raise WhichError(cmd=cmd)
+    return Path(path)
+
+
+@dataclass(kw_only=True, slots=True)
+class WhichError(Exception):
+    cmd: str
+
+    @override
+    def __str__(self) -> str:
+        return f"{self.cmd!r} not found"
+
+
+__all__ = ["WhichError", "which"]

utilities/slack_sdk.py

@@ -15,7 +15,7 @@ if TYPE_CHECKING:
     from slack_sdk.webhook import WebhookResponse
     from whenever import TimeDelta
 
-    from utilities.types import Delta
+    from utilities.types import Delta, MaybeType
 
 
 _TIMEOUT: Delta = MINUTE
@@ -39,11 +39,16 @@ def _get_client(url: str, /, *, timeout: Delta = _TIMEOUT) -> WebhookClient:
 
 
 async def send_to_slack_async(
-    url: str, text: str, /, *, timeout: TimeDelta = _TIMEOUT
+    url: str,
+    text: str,
+    /,
+    *,
+    timeout: TimeDelta = _TIMEOUT,
+    error: MaybeType[BaseException] = TimeoutError,
 ) -> None:
     """Send a message via Slack."""
     client = _get_async_client(url, timeout=timeout)
-    async with timeout_td(timeout):
+    async with timeout_td(timeout, error=error):
         response = await client.send(text=text)
     if response.status_code != HTTPStatus.OK:  # pragma: no cover
         raise SendToSlackError(text=text, response=response)