dycw-utilities 0.175.17__py3-none-any.whl → 0.185.8__py3-none-any.whl

utilities/constants.py

@@ -0,0 +1,492 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from getpass import getuser
+from logging import getLogger
+from os import cpu_count, environ
+from pathlib import Path
+from platform import system
+from random import SystemRandom
+from re import IGNORECASE
+from socket import gethostname
+from tempfile import gettempdir
+from typing import TYPE_CHECKING, Any, assert_never, cast, override
+from zoneinfo import ZoneInfo
+
+from tzlocal import get_localzone
+from whenever import (
+    Date,
+    DateDelta,
+    DateTimeDelta,
+    PlainDateTime,
+    Time,
+    TimeDelta,
+    ZonedDateTime,
+)
+
+if TYPE_CHECKING:
+    from utilities.types import System, TimeZone
+
+
+# getpass
+
+
+USER: str = getuser()
+
+
+# math
+
+
+MIN_FLOAT32, MAX_FLOAT32 = -3.4028234663852886e38, 3.4028234663852886e38
+MIN_FLOAT64, MAX_FLOAT64 = -1.7976931348623157e308, 1.7976931348623157e308
+MIN_INT8, MAX_INT8 = -(2 ** (8 - 1)), 2 ** (8 - 1) - 1
+MIN_INT16, MAX_INT16 = -(2 ** (16 - 1)), 2 ** (16 - 1) - 1
+MIN_INT32, MAX_INT32 = -(2 ** (32 - 1)), 2 ** (32 - 1) - 1
+MIN_INT64, MAX_INT64 = -(2 ** (64 - 1)), 2 ** (64 - 1) - 1
+MIN_UINT8, MAX_UINT8 = 0, 2**8 - 1
+MIN_UINT16, MAX_UINT16 = 0, 2**16 - 1
+MIN_UINT32, MAX_UINT32 = 0, 2**32 - 1
+MIN_UINT64, MAX_UINT64 = 0, 2**64 - 1
+
+
+# os
+
+
+IS_CI: bool = "CI" in environ
+
+
+def _get_cpu_count() -> int:
+    """Get the CPU count."""
+    count = cpu_count()
+    if count is None:  # pragma: no cover
+        raise ValueError(count)
+    return count
+
+
+CPU_COUNT: int = _get_cpu_count()
+
+
+# platform
+
+
+def _get_system() -> System:
+    """Get the system/OS name."""
+    sys = system()
+    if sys == "Windows":  # skipif-not-windows
+        return "windows"
+    if sys == "Darwin":  # skipif-not-macos
+        return "mac"
+    if sys == "Linux":  # skipif-not-linux
+        return "linux"
+    raise ValueError(sys)  # pragma: no cover
+
+
+SYSTEM: System = _get_system()
+IS_WINDOWS: bool = SYSTEM == "windows"
+IS_MAC: bool = SYSTEM == "mac"
+IS_LINUX: bool = SYSTEM == "linux"
+IS_NOT_WINDOWS: bool = not IS_WINDOWS
+IS_NOT_MAC: bool = not IS_MAC
+IS_NOT_LINUX: bool = not IS_LINUX
+IS_CI_AND_WINDOWS: bool = IS_CI and IS_WINDOWS
+IS_CI_AND_MAC: bool = IS_CI and IS_MAC
+IS_CI_AND_LINUX: bool = IS_CI and IS_LINUX
+IS_CI_AND_NOT_WINDOWS: bool = IS_CI and IS_NOT_WINDOWS
+IS_CI_AND_NOT_MAC: bool = IS_CI and IS_NOT_MAC
+IS_CI_AND_NOT_LINUX: bool = IS_CI and IS_NOT_LINUX
+
+
+def _get_max_pid() -> int | None:
+    """Get the system max process ID."""
+    match SYSTEM:
+        case "windows":  # skipif-not-windows
+            return None
+        case "mac":  # skipif-not-macos
+            return 99999
+        case "linux":  # skipif-not-linux
+            path = Path("/proc/sys/kernel/pid_max")
+            try:
+                return int(path.read_text())
+            except FileNotFoundError:  # pragma: no cover
+                return None
+        case never:
+            assert_never(never)
+
+
+MAX_PID: int | None = _get_max_pid()
+
+
+# pathlib
+
+
+HOME: Path = Path.home()
+PWD: Path = Path.cwd()
+
+
+# platform -> os
+
+
+def _get_effective_group_id() -> int | None:
+    """Get the effective group ID."""
+    match SYSTEM:
+        case "windows":  # skipif-not-windows
+            return None
+        case "mac" | "linux":  # skipif-windows
+            from os import getegid
+
+            return getegid()
+        case never:
+            assert_never(never)
+
+
+EFFECTIVE_GROUP_ID: int | None = _get_effective_group_id()
+
+
+def _get_effective_user_id() -> int | None:
+    """Get the effective user ID."""
+    match SYSTEM:
+        case "windows":  # skipif-not-windows
+            return None
+        case "mac" | "linux":  # skipif-windows
+            from os import geteuid
+
+            return geteuid()
+        case never:
+            assert_never(never)
+
+
+EFFECTIVE_USER_ID: int | None = _get_effective_user_id()
+
+
+# platform -> os -> grp
+
+
+def _get_gid_name(gid: int, /) -> str | None:
+    """Get the name of a group ID."""
+    match SYSTEM:
+        case "windows":  # skipif-not-windows
+            return None
+        case "mac" | "linux":
+            from grp import getgrgid
+
+            return getgrgid(gid).gr_name
+        case never:
+            assert_never(never)
+
+
+ROOT_GROUP_NAME: str | None = _get_gid_name(0)
+EFFECTIVE_GROUP_NAME: str | None = (
+    None if EFFECTIVE_GROUP_ID is None else _get_gid_name(EFFECTIVE_GROUP_ID)
+)
+
+
+# platform -> os -> pwd
+
+
+def _get_uid_name(uid: int, /) -> str | None:
+    """Get the name of a user ID."""
+    match SYSTEM:
+        case "windows":  # skipif-not-windows
+            return None
+        case "mac" | "linux":  # skipif-windows
+            from pwd import getpwuid
+
+            return getpwuid(uid).pw_name
+        case never:
+            assert_never(never)
+
+
+ROOT_USER_NAME: str | None = _get_uid_name(0)
+EFFECTIVE_USER_NAME: str | None = (
+    None if EFFECTIVE_USER_ID is None else _get_uid_name(EFFECTIVE_USER_ID)
+)
+
+
+# random
+
+
+SYSTEM_RANDOM: SystemRandom = SystemRandom()
+
+
+# reprlib
+
+
+RICH_MAX_WIDTH: int = 80
+RICH_INDENT_SIZE: int = 4
+RICH_MAX_LENGTH: int | None = 20
+RICH_MAX_STRING: int | None = None
+RICH_MAX_DEPTH: int | None = None
+RICH_EXPAND_ALL: bool = False
+
+
+# sentinel
+
+
+class _Meta(type):
+    """Metaclass for the sentinel."""
+
+    instance: Any = None
+
+    @override
+    def __call__(cls, *args: Any, **kwargs: Any) -> Any:
+        if cls.instance is None:
+            cls.instance = super().__call__(*args, **kwargs)
+        return cls.instance
+
+
+class Sentinel(metaclass=_Meta):
+    """Base class for the sentinel object."""
+
+    @override
+    def __repr__(self) -> str:
+        return _SENTINEL_REPR
+
+    @override
+    def __str__(self) -> str:
+        return repr(self)
+
+    @classmethod
+    def parse(cls, text: str, /) -> Sentinel:
+        """Parse a string into the Sentinel value."""
+        if _SENTINEL_PATTERN.search(text):
+            return sentinel
+        raise SentinelParseError(text=text)
+
+
+_SENTINEL_PATTERN = re.compile("^(|sentinel|<sentinel>)$", flags=IGNORECASE)
+_SENTINEL_REPR = "<sentinel>"
+
+
+@dataclass(kw_only=True, slots=True)
+class SentinelParseError(Exception):
+    text: str
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to parse sentinel; got {self.text!r}"
+
+
+sentinel = Sentinel()
+
+
+# socket
+
+
+HOSTNAME = gethostname()
+
+
+# tempfile
+
+
+TEMP_DIR: Path = Path(gettempdir())
+
+
+# text
+
+
+LIST_SEPARATOR: str = ","
+PAIR_SEPARATOR: str = "="
+BRACKETS: set[tuple[str, str]] = {("(", ")"), ("[", "]"), ("{", "}")}
+
+
+# tzlocal
+
+
+def _get_local_time_zone() -> ZoneInfo:
+    """Get the local time zone, with the logging disabled."""
+    logger = getLogger("tzlocal")  # avoid import cycle
+    init_disabled = logger.disabled
+    logger.disabled = True
+    time_zone = get_localzone()
+    logger.disabled = init_disabled
+    return time_zone
+
+
+LOCAL_TIME_ZONE: ZoneInfo = _get_local_time_zone()
+LOCAL_TIME_ZONE_NAME: TimeZone = cast("TimeZone", LOCAL_TIME_ZONE.key)
+
+
+# tzlocal -> whenever
+
+
+def _get_now_local() -> ZonedDateTime:
+    """Get the current zoned date-time in the local time-zone."""
+    return ZonedDateTime.now(LOCAL_TIME_ZONE_NAME)
+
+
+NOW_LOCAL: ZonedDateTime = _get_now_local()
+TODAY_LOCAL: Date = NOW_LOCAL.date()
+TIME_LOCAL: Time = NOW_LOCAL.time()
+NOW_LOCAL_PLAIN: PlainDateTime = NOW_LOCAL.to_plain()
+
+
+# whenever
+
+
+ZERO_DAYS: DateDelta = DateDelta()
+ZERO_TIME: TimeDelta = TimeDelta()
+NANOSECOND: TimeDelta = TimeDelta(nanoseconds=1)
+MICROSECOND: TimeDelta = TimeDelta(microseconds=1)
+MILLISECOND: TimeDelta = TimeDelta(milliseconds=1)
+SECOND: TimeDelta = TimeDelta(seconds=1)
+MINUTE: TimeDelta = TimeDelta(minutes=1)
+HOUR: TimeDelta = TimeDelta(hours=1)
+DAY: DateDelta = DateDelta(days=1)
+WEEK: DateDelta = DateDelta(weeks=1)
+MONTH: DateDelta = DateDelta(months=1)
+YEAR: DateDelta = DateDelta(years=1)
+
+
+DATE_DELTA_MIN: DateDelta = DateDelta(weeks=-521722, days=-5)
+DATE_DELTA_MAX: DateDelta = DateDelta(weeks=521722, days=5)
+TIME_DELTA_MIN: TimeDelta = TimeDelta(hours=-87831216)
+TIME_DELTA_MAX: TimeDelta = TimeDelta(hours=87831216)
+DATE_TIME_DELTA_MIN: DateTimeDelta = DateTimeDelta(
+    weeks=-521722,
+    days=-5,
+    hours=-23,
+    minutes=-59,
+    seconds=-59,
+    milliseconds=-999,
+    microseconds=-999,
+    nanoseconds=-999,
+)
+DATE_TIME_DELTA_MAX: DateTimeDelta = DateTimeDelta(
+    weeks=521722,
+    days=5,
+    hours=23,
+    minutes=59,
+    seconds=59,
+    milliseconds=999,
+    microseconds=999,
+    nanoseconds=999,
+)
+
+
+SECONDS_PER_DAY: int = 24 * 60 * 60
+NANOSECONDS_PER_SECOND: int = 1_000_000_000
+NANOSECONDS_PER_DAY: int = SECONDS_PER_DAY * NANOSECONDS_PER_SECOND
+
+
+# zoneinfo
+
+
+UTC: ZoneInfo = ZoneInfo("UTC")
+HongKong: ZoneInfo = ZoneInfo("Asia/Hong_Kong")
+Tokyo: ZoneInfo = ZoneInfo("Asia/Tokyo")
+USCentral: ZoneInfo = ZoneInfo("US/Central")
+USEastern: ZoneInfo = ZoneInfo("US/Eastern")
+
+
+# zoneinfo -> whenever
+
+
+ZONED_DATE_TIME_MIN: ZonedDateTime = PlainDateTime.MIN.assume_tz(UTC.key)
+ZONED_DATE_TIME_MAX: ZonedDateTime = PlainDateTime.MAX.assume_tz(UTC.key)
+
+
+def _get_now(time_zone: str = UTC.key, /) -> ZonedDateTime:
+    """Get the current zoned date-time."""
+    return ZonedDateTime.now(time_zone)
+
+
+NOW_UTC: ZonedDateTime = _get_now()
+TODAY_UTC: Date = NOW_UTC.date()
+TIME_UTC: Time = NOW_UTC.time()
+NOW_UTC_PLAIN: PlainDateTime = NOW_UTC.to_plain()
+
+
+__all__ = [
+    "BRACKETS",
+    "CPU_COUNT",
+    "DATE_DELTA_MAX",
+    "DATE_DELTA_MIN",
+    "DATE_TIME_DELTA_MAX",
+    "DATE_TIME_DELTA_MIN",
+    "DAY",
+    "EFFECTIVE_GROUP_ID",
+    "EFFECTIVE_GROUP_NAME",
+    "EFFECTIVE_USER_ID",
+    "EFFECTIVE_USER_NAME",
+    "HOME",
+    "HOSTNAME",
+    "HOUR",
+    "IS_CI",
+    "IS_CI_AND_LINUX",
+    "IS_CI_AND_MAC",
+    "IS_CI_AND_NOT_LINUX",
+    "IS_CI_AND_NOT_MAC",
+    "IS_CI_AND_NOT_WINDOWS",
+    "IS_CI_AND_WINDOWS",
+    "IS_LINUX",
+    "IS_MAC",
+    "IS_NOT_LINUX",
+    "IS_NOT_MAC",
+    "IS_NOT_WINDOWS",
+    "IS_WINDOWS",
+    "LIST_SEPARATOR",
+    "LOCAL_TIME_ZONE",
+    "LOCAL_TIME_ZONE_NAME",
+    "MAX_FLOAT32",
+    "MAX_FLOAT64",
+    "MAX_INT8",
+    "MAX_INT16",
+    "MAX_INT32",
+    "MAX_INT64",
+    "MAX_PID",
+    "MAX_UINT8",
+    "MAX_UINT16",
+    "MAX_UINT32",
+    "MAX_UINT64",
+    "MICROSECOND",
+    "MILLISECOND",
+    "MINUTE",
+    "MIN_FLOAT32",
+    "MIN_FLOAT64",
+    "MIN_INT8",
+    "MIN_INT16",
+    "MIN_INT32",
+    "MIN_INT64",
+    "MIN_UINT8",
+    "MIN_UINT16",
+    "MIN_UINT32",
+    "MIN_UINT64",
+    "MONTH",
+    "NANOSECOND",
+    "NANOSECONDS_PER_DAY",
+    "NANOSECONDS_PER_SECOND",
+    "NOW_LOCAL",
+    "NOW_LOCAL_PLAIN",
+    "NOW_UTC",
+    "NOW_UTC_PLAIN",
+    "PAIR_SEPARATOR",
+    "PWD",
+    "ROOT_GROUP_NAME",
+    "ROOT_USER_NAME",
+    "SECOND",
+    "SECONDS_PER_DAY",
+    "SYSTEM",
+    "SYSTEM_RANDOM",
+    "TEMP_DIR",
+    "TIME_DELTA_MAX",
+    "TIME_DELTA_MIN",
+    "TIME_LOCAL",
+    "TIME_UTC",
+    "TODAY_LOCAL",
+    "TODAY_UTC",
+    "USER",
+    "UTC",
+    "WEEK",
+    "YEAR",
+    "ZERO_DAYS",
+    "ZERO_TIME",
+    "ZONED_DATE_TIME_MAX",
+    "ZONED_DATE_TIME_MIN",
+    "HongKong",
+    "Sentinel",
+    "Tokyo",
+    "USCentral",
+    "USEastern",
+    "sentinel",
+]

utilities/contextlib.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import re
 from asyncio import create_task, get_event_loop
 from contextlib import (
     _AsyncGeneratorContextManager,
@@ -90,12 +89,13 @@ def enhanced_context_manager[**P, T_co](
             with gcm as value:
                 yield value
         finally:
-            _ = signal(SIGABRT, sigabrt0) if sigabrt else None
-            _ = signal(SIGFPE, sigfpe0) if sigfpe else None
-            _ = signal(SIGILL, sigill0) if sigill else None
-            _ = signal(SIGINT, sigint0) if sigint else None
-            _ = signal(SIGSEGV, sigsegv0) if sigsegv else None
-            _ = signal(SIGTERM, sigterm0) if sigterm else None
+            with _suppress_signal_error():
+                _ = signal(SIGABRT, sigabrt0) if sigabrt else None
+                _ = signal(SIGFPE, sigfpe0) if sigfpe else None
+                _ = signal(SIGILL, sigill0) if sigill else None
+                _ = signal(SIGINT, sigint0) if sigint else None
+                _ = signal(SIGSEGV, sigsegv0) if sigsegv else None
+                _ = signal(SIGTERM, sigterm0) if sigterm else None
 
     return wrapped
 
@@ -173,12 +173,13 @@ def enhanced_async_context_manager[**P, T_co](
             async with agcm as value:
                 yield value
         finally:
-            _ = signal(SIGABRT, sigabrt0) if sigabrt else None
-            _ = signal(SIGFPE, sigfpe0) if sigfpe else None
-            _ = signal(SIGILL, sigill0) if sigill else None
-            _ = signal(SIGINT, sigint0) if sigint else None
-            _ = signal(SIGSEGV, sigsegv0) if sigsegv else None
-            _ = signal(SIGTERM, sigterm0) if sigterm else None
+            with _suppress_signal_error():
+                _ = signal(SIGABRT, sigabrt0) if sigabrt else None
+                _ = signal(SIGFPE, sigfpe0) if sigfpe else None
+                _ = signal(SIGILL, sigill0) if sigill else None
+                _ = signal(SIGINT, sigint0) if sigint else None
+                _ = signal(SIGSEGV, sigsegv0) if sigsegv else None
+                _ = signal(SIGTERM, sigterm0) if sigterm else None
 
     return wrapped
 
@@ -191,7 +192,8 @@ def _swap_handler(
 ) -> _HANDLER:
     orig_handler = getsignal(signum)
     new_handler = _make_handler(signum, obj)
-    _ = signal(signum, new_handler)
+    with _suppress_signal_error():
+        _ = signal(signum, new_handler)
     return orig_handler
 
 
@@ -220,24 +222,15 @@ def _make_handler(
     return new_handler
 
 
-##
-
-
-_SUPER_OBJECT_HAS_NO_ATTRIBUTE = re.compile(r"'super' object has no attribute '\w+'")
-
-
 @contextmanager
-def suppress_super_object_attribute_error() -> Iterator[None]:
-    """Suppress the super() attribute error, for mix-ins."""
+def _suppress_signal_error() -> Iterator[None]:
     try:
         yield
-    except AttributeError as error:
-        if not _SUPER_OBJECT_HAS_NO_ATTRIBUTE.search(error.args[0]):
-            raise
+    except ValueError as error:
+        (msg,) = error.args
+        if msg == "signal only works in main thread of the main interpreter":
+            return
+        raise  # pragma: no cover
 
 
-__all__ = [
-    "enhanced_async_context_manager",
-    "enhanced_context_manager",
-    "suppress_super_object_attribute_error",
-]
+__all__ = ["enhanced_async_context_manager", "enhanced_context_manager"]

utilities/contextvars.py

@@ -1,15 +1,6 @@
 from __future__ import annotations
 
-from contextlib import contextmanager
 from contextvars import ContextVar
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from collections.abc import Iterator
-
-
-##
-
 
 _GLOBAL_BREAKPOINT = ContextVar("GLOBAL_BREAKPOINT", default=False)
 
@@ -25,17 +16,4 @@ def set_global_breakpoint() -> None:
     _ = _GLOBAL_BREAKPOINT.set(True)
 
 
-##
-
-
-@contextmanager
-def yield_set_context(var: ContextVar[bool], /) -> Iterator[None]:
-    """Yield a context var as being set."""
-    token = var.set(True)
-    try:
-        yield
-    finally:
-        _ = var.reset(token)
-
-
-__all__ = ["global_breakpoint", "set_global_breakpoint", "yield_set_context"]
+__all__ = ["global_breakpoint", "set_global_breakpoint"]