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

utilities/click.py

@@ -4,14 +4,16 @@ import enum
 import ipaddress
 import pathlib
 import uuid
+from enum import StrEnum
 from typing import TYPE_CHECKING, TypedDict, assert_never, override
 
 import whenever
 from click import Choice, Context, Parameter, ParamType
 from click.types import IntParamType, StringParamType
 
+from utilities.core import get_class, get_class_name, one
 from utilities.enum import EnsureEnumError, ensure_enum
-from utilities.functions import EnsureStrError, ensure_str, get_class_name
+from utilities.functions import EnsureStrError, ensure_str
 from utilities.iterables import is_iterable_not_str
 from utilities.parse import ParseObjectError, parse_object
 from utilities.text import split_str
@@ -37,17 +39,23 @@ if TYPE_CHECKING:
     )
 
 
-class _HelpOptionNames(TypedDict):
-    help_option_names: list[str]
+class _ContextSettings(TypedDict):
+    context_settings: _ContextSettingsInner
 
 
-class _ContextSettings(TypedDict):
-    context_settings: _HelpOptionNames
+class _ContextSettingsInner(TypedDict):
+    max_content_width: int
+    help_option_names: list[str]
+    show_default: bool
 
 
-CONTEXT_SETTINGS_HELP_OPTION_NAMES = _ContextSettings(
-    context_settings=_HelpOptionNames(help_option_names=["-h", "--help"])
+_MAX_CONTENT_WIDTH = 120
+_CONTEXT_SETTINGS_INNER = _ContextSettingsInner(
+    max_content_width=_MAX_CONTENT_WIDTH,
+    help_option_names=["-h", "--help"],
+    show_default=True,
 )
+CONTEXT_SETTINGS = _ContextSettings(context_settings=_CONTEXT_SETTINGS_INNER)
 
 
 # parameters
@@ -72,7 +80,7 @@ class Date(ParamType):
                 return value
             case str():
                 try:
-                    return whenever.Date.parse_common_iso(value)
+                    return whenever.Date.parse_iso(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
             case never:
@@ -98,7 +106,7 @@ class DateDelta(ParamType):
                 return value
             case str():
                 try:
-                    return whenever.DateDelta.parse_common_iso(value)
+                    return whenever.DateDelta.parse_iso(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
             case never:
@@ -124,7 +132,7 @@ class DateTimeDelta(ParamType):
                 return value
             case str():
                 try:
-                    return whenever.DateTimeDelta.parse_common_iso(value)
+                    return whenever.DateTimeDelta.parse_iso(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
             case never:
@@ -135,10 +143,13 @@ class Enum[E: enum.Enum](ParamType):
     """An enum-valued parameter."""
 
     @override
-    def __init__(self, enum: type[E], /, *, case_sensitive: bool = False) -> None:
+    def __init__(
+        self, enum: type[E], /, *, value: bool = False, case_sensitive: bool = False
+    ) -> None:
         cls = get_class_name(enum)
         self.name = f"enum[{cls}]"
         self._enum = enum
+        self._value = issubclass(self._enum, StrEnum) or value
         self._case_sensitive = case_sensitive
         super().__init__()
 
@@ -160,7 +171,52 @@ class Enum[E: enum.Enum](ParamType):
     @override
     def get_metavar(self, param: Parameter, ctx: Context) -> str | None:
         _ = ctx
-        desc = ",".join(e.name for e in self._enum)
+        desc = ",".join(str(e.value) if self._value else e.name for e in self._enum)
+        return _make_metavar(param, desc)
+
+
+class EnumPartial[E: enum.Enum](ParamType):
+    """An enum-valued parameter."""
+
+    @override
+    def __init__(
+        self,
+        members: Iterable[E],
+        /,
+        *,
+        value: bool = False,
+        case_sensitive: bool = False,
+    ) -> None:
+        self._members = list(members)
+        self._enum = one({get_class(e) for e in self._members})
+        cls = get_class_name(self._enum)
+        self.name = f"enum-partial[{cls}]"
+        self._value = issubclass(self._enum, StrEnum) or value
+        self._case_sensitive = case_sensitive
+        super().__init__()
+
+    @override
+    def __repr__(self) -> str:
+        cls = get_class_name(self._enum)
+        return f"ENUMPARTIAL[{cls}]"
+
+    @override
+    def convert(
+        self, value: EnumLike[E], param: Parameter | None, ctx: Context | None
+    ) -> E:
+        """Convert a value into the `Enum` type."""
+        try:
+            enum = ensure_enum(value, self._enum, case_sensitive=self._case_sensitive)
+        except EnsureEnumError as error:
+            self.fail(str(error), param, ctx)
+        if enum in self._members:
+            return enum
+        return self.fail(f"{enum.value!r} is not a selected member")
+
+    @override
+    def get_metavar(self, param: Parameter, ctx: Context) -> str | None:
+        _ = ctx
+        desc = ",".join(str(e.value) if self._value else e.name for e in self._members)
         return _make_metavar(param, desc)
 
 
@@ -235,7 +291,7 @@ class MonthDay(ParamType):
                 return value
             case str():
                 try:
-                    return whenever.MonthDay.parse_common_iso(value)
+                    return whenever.MonthDay.parse_iso(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
             case never:
@@ -284,7 +340,7 @@ class PlainDateTime(ParamType):
                 return value
             case str():
                 try:
-                    return whenever.PlainDateTime.parse_common_iso(value)
+                    return whenever.PlainDateTime.parse_iso(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
             case never:
@@ -310,7 +366,7 @@ class Time(ParamType):
                 return value
             case str():
                 try:
-                    return whenever.Time.parse_common_iso(value)
+                    return whenever.Time.parse_iso(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
             case never:
@@ -336,7 +392,7 @@ class TimeDelta(ParamType):
                 return value
             case str():
                 try:
-                    return whenever.TimeDelta.parse_common_iso(value)
+                    return whenever.TimeDelta.parse_iso(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
             case never:
@@ -388,7 +444,7 @@ class YearMonth(ParamType):
                 return value
             case str():
                 try:
-                    return whenever.YearMonth.parse_common_iso(value)
+                    return whenever.YearMonth.parse_iso(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
             case never:
@@ -414,7 +470,7 @@ class ZonedDateTime(ParamType):
                 return value
             case str():
                 try:
-                    return whenever.ZonedDateTime.parse_common_iso(value)
+                    return whenever.ZonedDateTime.parse_iso(value)
                 except ValueError as error:
                     self.fail(str(error), param, ctx)
             case never:
@@ -600,12 +656,13 @@ def _make_metavar(param: Parameter, desc: str, /) -> str:
 
 
 __all__ = [
-    "CONTEXT_SETTINGS_HELP_OPTION_NAMES",
+    "CONTEXT_SETTINGS",
     "UUID",
     "Date",
     "DateDelta",
     "DateTimeDelta",
     "Enum",
+    "EnumPartial",
     "FrozenSetChoices",
     "FrozenSetEnums",
     "FrozenSetParameter",

utilities/concurrent.py

@@ -12,7 +12,7 @@ if TYPE_CHECKING:
     from collections.abc import Callable, Iterable
     from multiprocessing.context import BaseContext
 
-    from utilities.os import IntOrAll
+    from utilities.types import IntOrAll
 
 
 def concurrent_map[T](

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",
+]