dycw-utilities 0.151.12__py3-none-any.whl → 0.153.0__py3-none-any.whl

utilities/types.py

@@ -1,16 +1,7 @@
 from __future__ import annotations
 
 import datetime as dt
-from asyncio import Event
-from collections.abc import (
-    Callable,
-    Collection,
-    Coroutine,
-    Hashable,
-    Iterable,
-    Mapping,
-    Sequence,
-)
+from collections.abc import Callable, Collection, Coroutine, Iterable, Mapping
 from enum import Enum
 from ipaddress import IPv4Address, IPv6Address
 from logging import Logger
@@ -27,6 +18,7 @@ from typing import (
     overload,
     runtime_checkable,
 )
+from uuid import UUID
 from zoneinfo import ZoneInfo
 
 from whenever import (
@@ -47,6 +39,7 @@ _T_contra = TypeVar("_T_contra", contravariant=True)
 
 
 # basic
+type BoolLike = MaybeStr[bool]
 type OpenMode = Literal[
     "r",
     "w",
@@ -70,8 +63,7 @@ type OpenMode = Literal[
     "a+b",
 ]
 type MaybeCallable[T] = T | Callable[[], T]
-type MaybeCallableBool = MaybeCallable[bool]
-type MaybeCallableStr = MaybeCallable[str]
+type MaybeCallableBoolLike = MaybeCallable[BoolLike]
 type MaybeStr[T] = T | str
 type MaybeType[T] = T | type[T]
 type StrMapping = Mapping[str, Any]
@@ -82,7 +74,6 @@ type TupleOrStrMapping = tuple[Any, ...] | StrMapping
 
 # asyncio
 type Coro[T] = Coroutine[Any, Any, T]
-type MaybeCallableEvent = MaybeCallable[Event]
 type MaybeCoro[T] = T | Coro[T]
 
 
@@ -123,25 +114,22 @@ IPv6AddressLike = MaybeStr[IPv6Address]
 
 
 # iterables
-type IterableHashable[T: Hashable] = tuple[T, ...] | frozenset[T]
+type SequenceLT[T] = list[T] | tuple[T, ...]
+# iterables - maybe
 type MaybeCollection[T] = T | Collection[T]
-type MaybeIterableHashable[T: Hashable] = T | IterableHashable[T]
 type MaybeIterable[T] = T | Iterable[T]
-type MaybeList[T] = T | list[T]
-type MaybeSequence[T] = T | Sequence[T]
+type MaybeSequence[T] = T | SequenceLT[T]
 # iterables - str
-type CollectionStr = (
-    dict[str, Any] | frozenset[str] | list[str] | set[str] | tuple[str, ...]
-)
+type SequenceStr = SequenceLT[str]
+type CollectionStr = dict[str, Any] | frozenset[str] | set[str] | SequenceStr
+# iterables - maybe str
 type MaybeCollectionStr = str | CollectionStr
-type MaybeListStr = MaybeList[str]
 type MaybeSequenceStr = str | SequenceStr
-type SequenceStr = list[str] | tuple[str, ...]
 
 
 # logging
 type LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
-type LoggerOrName = MaybeStr[Logger]
+type LoggerLike = MaybeStr[Logger]
 
 
 # math
@@ -225,8 +213,8 @@ type SerializeObjectExtra = Mapping[Any, Callable[[Any], str]]
 
 
 # pathlib
-type MaybeCallablePathLike = MaybeCallable[PathLike]
 type PathLike = MaybeStr[Path]
+type MaybeCallablePathLike = MaybeCallable[PathLike]
 
 
 # random
@@ -237,11 +225,20 @@ type Seed = int | float | str | bytes | bytearray | Random
 type PatternLike = MaybeStr[Pattern[str]]
 
 
+# text
+type MaybeCallableStr = MaybeCallable[str]
+
+
 # traceback
 type ExcInfo = tuple[type[BaseException], BaseException, TracebackType]
 type OptExcInfo = ExcInfo | tuple[None, None, None]
 
 
+# uuid
+type UUIDLike = MaybeStr[UUID]
+type MaybeCallableUUIDLike = MaybeCallable[UUIDLike | Seed]
+
+
 # whenever
 type DateDeltaLike = MaybeStr[DateDelta]
 type DateLike = MaybeStr[Date]
@@ -251,8 +248,8 @@ type DateTimeRoundMode = Literal[
     "ceil", "floor", "half_ceil", "half_floor", "half_even"
 ]
 type Delta = DateDelta | TimeDelta | DateTimeDelta
-type MaybeCallableDate = MaybeCallable[Date]
-type MaybeCallableZonedDateTime = MaybeCallable[ZonedDateTime]
+type MaybeCallableDateLike = MaybeCallable[DateLike]
+type MaybeCallableZonedDateTimeLike = MaybeCallable[ZonedDateTimeLike]
 type MonthDayLike = MaybeStr[MonthDay]
 type PlainDateTimeLike = MaybeStr[PlainDateTime]
 type TimeDeltaLike = MaybeStr[TimeDelta]
@@ -288,24 +285,20 @@ __all__ = [
     "ExceptionTypeLike",
     "IPv4AddressLike",
     "IPv6AddressLike",
-    "IterableHashable",
     "LogLevel",
-    "LoggerOrName",
+    "LoggerLike",
     "MathRoundMode",
     "MaybeCallable",
-    "MaybeCallableBool",
-    "MaybeCallableDate",
-    "MaybeCallableEvent",
+    "MaybeCallableBoolLike",
+    "MaybeCallableDateLike",
     "MaybeCallablePathLike",
     "MaybeCallableStr",
-    "MaybeCallableZonedDateTime",
+    "MaybeCallableUUIDLike",
+    "MaybeCallableZonedDateTimeLike",
     "MaybeCollection",
     "MaybeCollectionStr",
     "MaybeCoro",
     "MaybeIterable",
-    "MaybeIterableHashable",
-    "MaybeList",
-    "MaybeListStr",
     "MaybeSequence",
     "MaybeSequenceStr",
     "MaybeStr",
@@ -345,6 +338,7 @@ __all__ = [
     "TimeZoneLike",
     "TupleOrStrMapping",
     "TypeLike",
+    "UUIDLike",
     "WeekDay",
     "YearMonthLike",
     "ZonedDateTimeLike",

utilities/uuid.py

@@ -1,24 +1,61 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from collections.abc import Callable
+from random import Random
+from typing import TYPE_CHECKING, assert_never, overload
 from uuid import UUID, uuid4
 
 from utilities.random import get_state
+from utilities.sentinel import Sentinel
 
 if TYPE_CHECKING:
-    from utilities.types import Seed
+    from utilities.types import MaybeCallableUUIDLike, Seed
 
 
 UUID_PATTERN = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
 UUID_EXACT_PATTERN = f"^{UUID_PATTERN}$"
 
 
-def get_uuid(*, seed: Seed | None = None) -> UUID:
+##
+
+
+def get_uuid(seed: Seed | None = None, /) -> UUID:
     """Generate a UUID, possibly with a seed."""
     if seed is None:
         return uuid4()
-    state = get_state(seed=seed)
+    state = get_state(seed)
     return UUID(int=state.getrandbits(128), version=4)
 
 
-__all__ = ["UUID_EXACT_PATTERN", "UUID_PATTERN", "get_uuid"]
+##
+
+
+@overload
+def to_uuid(uuid: Sentinel, /, *, seed: Seed | None = None) -> Sentinel: ...
+@overload
+def to_uuid(
+    uuid: MaybeCallableUUIDLike | None = get_uuid, /, *, seed: Seed | None = None
+) -> UUID: ...
+def to_uuid(
+    uuid: MaybeCallableUUIDLike | None | Sentinel = get_uuid,
+    /,
+    *,
+    seed: Seed | None = None,
+) -> UUID | Sentinel:
+    """Convert to a UUID."""
+    match uuid:
+        case UUID() | Sentinel():
+            return uuid
+        case None:
+            return get_uuid(seed)
+        case str():
+            return UUID(uuid)
+        case int() | float() | bytes() | bytearray() | Random() as seed:
+            return get_uuid(seed)
+        case Callable() as func:
+            return to_uuid(func(), seed=seed)
+        case never:
+            assert_never(never)
+
+
+__all__ = ["UUID_EXACT_PATTERN", "UUID_PATTERN", "get_uuid", "to_uuid"]

utilities/version.py

@@ -6,7 +6,7 @@ from dataclasses import dataclass, field, replace
 from functools import total_ordering
 from typing import Any, Self, assert_never, overload, override
 
-from utilities.sentinel import Sentinel, sentinel
+from utilities.sentinel import Sentinel
 from utilities.types import MaybeCallable, MaybeStr
 
 type VersionLike = MaybeStr[Version]
@@ -131,30 +131,6 @@ class _VersionEmptySuffixError(VersionError):
 ##
 
 
-@overload
-def get_version(*, version: MaybeCallableVersionLike) -> Version: ...
-@overload
-def get_version(*, version: None) -> None: ...
-@overload
-def get_version(*, version: Sentinel) -> Sentinel: ...
-def get_version(
-    *, version: MaybeCallableVersionLike | None | Sentinel = sentinel
-) -> Version | None | Sentinel:
-    """Get the version."""
-    match version:
-        case Version() | None | Sentinel():
-            return version
-        case str():
-            return parse_version(version)
-        case Callable() as func:
-            return get_version(version=func())
-        case never:
-            assert_never(never)
-
-
-##
-
-
 def parse_version(version: str, /) -> Version:
     """Parse a string into a version object."""
     try:
@@ -178,12 +154,37 @@ class ParseVersionError(Exception):
         return f"Invalid version string: {self.version!r}"
 
 
+##
+
+
+@overload
+def to_version(version: MaybeCallableVersionLike, /) -> Version: ...
+@overload
+def to_version(version: None, /) -> None: ...
+@overload
+def to_version(version: Sentinel, /) -> Sentinel: ...
+def to_version(
+    version: MaybeCallableVersionLike | None | Sentinel, /
+) -> Version | None | Sentinel:
+    """Convert to a version."""
+    match version:
+        case Version() | None | Sentinel():
+            return version
+        case str():
+            return parse_version(version)
+        case Callable() as func:
+            return to_version(func())
+        case never:
+            assert_never(never)
+
+
+##
 __all__ = [
     "MaybeCallableVersionLike",
     "ParseVersionError",
     "Version",
     "VersionError",
     "VersionLike",
-    "get_version",
     "parse_version",
+    "to_version",
 ]