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

utilities/json.py

@@ -1,70 +0,0 @@
-from __future__ import annotations
-
-from contextlib import suppress
-from dataclasses import dataclass
-from pathlib import Path
-from subprocess import check_output
-from typing import TYPE_CHECKING, assert_never, overload, override
-
-from utilities.atomicwrites import writer
-from utilities.gzip import write_binary
-
-if TYPE_CHECKING:
-    from utilities.types import PathLike
-
-
-##
-
-
-@overload
-def run_prettier(source: bytes, /) -> bytes: ...
-@overload
-def run_prettier(source: str, /) -> str: ...
-@overload
-def run_prettier(source: Path, /) -> None: ...
-def run_prettier(source: bytes | str | Path, /) -> bytes | str | None:
-    """Run `prettier` on a string/path."""
-    match source:  # skipif-ci
-        case bytes() as data:
-            return _run_prettier_core(data, text=False)
-        case str() as text:
-            if (path := Path(text)).is_file():
-                return run_prettier(path)
-            return _run_prettier_core(text, text=True)
-        case Path() as path:
-            result = run_prettier(path.read_bytes())
-            with writer(path, overwrite=True) as temp:
-                _ = temp.write_bytes(result)
-            return None
-        case never:
-            assert_never(never)
-
-
-def _run_prettier_core(data: bytes | str, /, *, text: bool) -> bytes | str:
-    """Run `prettier` on a string/path."""
-    try:  # skipif-ci
-        return check_output(["prettier", "--parser=json"], input=data, text=text)
-    except FileNotFoundError:  # pragma: no cover
-        raise RunPrettierError from None
-
-
-@dataclass(kw_only=True, slots=True)
-class RunPrettierError(Exception):
-    @override
-    def __str__(self) -> str:
-        return "Unable to find 'prettier'"  # pragma: no cover
-
-
-##
-
-
-def write_formatted_json(
-    data: bytes, path: PathLike, /, *, compress: bool = False, overwrite: bool = False
-) -> None:
-    """Write a formatted byte string to disk."""
-    with suppress(RunPrettierError):
-        data = run_prettier(data)
-    write_binary(data, path, compress=compress, overwrite=overwrite)
-
-
-__all__ = ["RunPrettierError", "run_prettier", "write_formatted_json"]

utilities/pickle.py

@@ -1,25 +0,0 @@
-from __future__ import annotations
-
-import gzip
-from pickle import dump, load
-from typing import TYPE_CHECKING, Any
-
-from utilities.atomicwrites import writer
-
-if TYPE_CHECKING:
-    from utilities.types import PathLike
-
-
-def read_pickle(path: PathLike, /) -> Any:
-    """Read an object from disk."""
-    with gzip.open(path, mode="rb") as gz:
-        return load(gz)  # noqa: S301
-
-
-def write_pickle(obj: Any, path: PathLike, /, *, overwrite: bool = False) -> None:
-    """Write an object to disk."""
-    with writer(path, overwrite=overwrite) as temp, gzip.open(temp, mode="wb") as gz:
-        dump(obj, gz)
-
-
-__all__ = ["read_pickle", "write_pickle"]

utilities/re.py

@@ -1,156 +0,0 @@
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-from re import Pattern
-from typing import TYPE_CHECKING, assert_never, override
-
-if TYPE_CHECKING:
-    from utilities.types import PatternLike
-
-
-def ensure_pattern(pattern: PatternLike, /, *, flags: int = 0) -> Pattern[str]:
-    """Ensure a pattern is returned."""
-    match pattern:
-        case Pattern():
-            return pattern
-        case str():
-            return re.compile(pattern, flags=flags)
-        case never:
-            assert_never(never)
-
-
-##
-
-
-def extract_group(pattern: PatternLike, text: str, /, *, flags: int = 0) -> str:
-    """Extract a group.
-
-    The regex must have 1 capture group, and this must match exactly once.
-    """
-    pattern_use = ensure_pattern(pattern, flags=flags)
-    match pattern_use.groups:
-        case 0:
-            raise _ExtractGroupNoCaptureGroupsError(pattern=pattern_use, text=text)
-        case 1:
-            matches: list[str] = pattern_use.findall(text)
-            match len(matches):
-                case 0:
-                    raise _ExtractGroupNoMatchesError(
-                        pattern=pattern_use, text=text
-                    ) from None
-                case 1:
-                    return matches[0]
-                case _:
-                    raise _ExtractGroupMultipleMatchesError(
-                        pattern=pattern_use, text=text, matches=matches
-                    ) from None
-        case _:
-            raise _ExtractGroupMultipleCaptureGroupsError(
-                pattern=pattern_use, text=text
-            )
-
-
-@dataclass(kw_only=True, slots=True)
-class ExtractGroupError(Exception):
-    pattern: Pattern[str]
-    text: str
-
-
-@dataclass(kw_only=True, slots=True)
-class _ExtractGroupMultipleCaptureGroupsError(ExtractGroupError):
-    @override
-    def __str__(self) -> str:
-        return f"Pattern {self.pattern} must contain exactly one capture group; it had multiple"
-
-
-@dataclass(kw_only=True, slots=True)
-class _ExtractGroupMultipleMatchesError(ExtractGroupError):
-    matches: list[str]
-
-    @override
-    def __str__(self) -> str:
-        return f"Pattern {self.pattern} must match against {self.text} exactly once; matches were {self.matches}"
-
-
-@dataclass(kw_only=True, slots=True)
-class _ExtractGroupNoCaptureGroupsError(ExtractGroupError):
-    @override
-    def __str__(self) -> str:
-        return f"Pattern {self.pattern} must contain exactly one capture group; it had none".format(
-            self.pattern
-        )
-
-
-@dataclass(kw_only=True, slots=True)
-class _ExtractGroupNoMatchesError(ExtractGroupError):
-    @override
-    def __str__(self) -> str:
-        return f"Pattern {self.pattern} must match against {self.text}"
-
-
-##
-
-
-def extract_groups(pattern: PatternLike, text: str, /, *, flags: int = 0) -> list[str]:
-    """Extract multiple groups.
-
-    The regex may have any number of capture groups, and they must collectively
-    match exactly once.
-    """
-    pattern_use = ensure_pattern(pattern, flags=flags)
-    if (n_groups := pattern_use.groups) == 0:
-        raise _ExtractGroupsNoCaptureGroupsError(pattern=pattern_use, text=text)
-    matches: list[str] = pattern_use.findall(text)
-    match len(matches), n_groups:
-        case 0, _:
-            raise _ExtractGroupsNoMatchesError(pattern=pattern_use, text=text)
-        case 1, 1:
-            return matches
-        case 1, _:
-            return list(matches[0])
-        case _:
-            raise _ExtractGroupsMultipleMatchesError(
-                pattern=pattern_use, text=text, matches=matches
-            )
-
-
-@dataclass(kw_only=True, slots=True)
-class ExtractGroupsError(Exception):
-    pattern: Pattern[str]
-    text: str
-
-
-@dataclass(kw_only=True, slots=True)
-class _ExtractGroupsMultipleMatchesError(ExtractGroupsError):
-    matches: list[str]
-
-    @override
-    def __str__(self) -> str:
-        return f"Pattern {self.pattern} must match against {self.text} exactly once; matches were {self.matches}"
-
-
-@dataclass(kw_only=True, slots=True)
-class _ExtractGroupsNoCaptureGroupsError(ExtractGroupsError):
-    pattern: Pattern[str]
-    text: str
-
-    @override
-    def __str__(self) -> str:
-        return f"Pattern {self.pattern} must contain at least one capture group"
-
-
-@dataclass(kw_only=True, slots=True)
-class _ExtractGroupsNoMatchesError(ExtractGroupsError):
-    @override
-    def __str__(self) -> str:
-        return f"Pattern {self.pattern} must match against {self.text}"
-
-
-__all__ = [
-    "ExtractGroupError",
-    "ExtractGroupsError",
-    "ensure_pattern",
-    "extract_group",
-    "extract_groups",
-]

utilities/sentinel.py

@@ -1,73 +0,0 @@
-from __future__ import annotations
-
-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."""
-
-    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
-
-
-SENTINEL_REPR = "<sentinel>"
-
-
-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)
-
-
-sentinel = Sentinel()
-
-##
-
-
-def is_sentinel(obj: Any, /) -> TypeIs[Sentinel]:
-    """Check if an object is the sentinel."""
-    return obj is sentinel
-
-
-##
-
-
-def parse_sentinel(text: str, /) -> Sentinel:
-    """Parse text into the Sentinel value."""
-    if search("^(|sentinel|<sentinel>)$", text, flags=IGNORECASE):
-        return sentinel
-    raise ParseSentinelError(text=text)
-
-
-@dataclass(kw_only=True, slots=True)
-class ParseSentinelError(Exception):
-    text: str
-
-    @override
-    def __str__(self) -> str:
-        return f"Unable to parse sentinel value; got {self.text!r}"
-
-
-__all__ = [
-    "SENTINEL_REPR",
-    "ParseSentinelError",
-    "Sentinel",
-    "is_sentinel",
-    "parse_sentinel",
-    "sentinel",
-]

utilities/socket.py

@@ -1,8 +0,0 @@
-from __future__ import annotations
-
-from socket import gethostname
-
-HOSTNAME = gethostname()
-
-
-__all__ = ["HOSTNAME"]

utilities/string.py

@@ -1,20 +0,0 @@
-from __future__ import annotations
-
-from os import environ
-from pathlib import Path
-from string import Template
-from typing import Any, assert_never
-
-
-def substitute_environ(path_or_text: Path | str, /, **kwargs: Any) -> str:
-    """Substitute the environment variables in a file."""
-    match path_or_text:
-        case Path() as path:
-            return substitute_environ(path.read_text(), **kwargs)
-        case str() as text:
-            return Template(text).substitute(environ, **kwargs)
-        case never:
-            assert_never(never)
-
-
-__all__ = ["substitute_environ"]

utilities/tempfile.py

@@ -1,77 +0,0 @@
-from __future__ import annotations
-
-import tempfile
-from pathlib import Path
-from tempfile import gettempdir as _gettempdir
-from typing import TYPE_CHECKING, override
-
-from utilities.warnings import suppress_warnings
-
-if TYPE_CHECKING:
-    from types import TracebackType
-
-    from utilities.types import PathLike
-
-
-class TemporaryDirectory:
-    """Wrapper around `TemporaryDirectory` with a `Path` attribute."""
-
-    def __init__(
-        self,
-        *,
-        suffix: str | None = None,
-        prefix: str | None = None,
-        dir: PathLike | None = None,  # noqa: A002
-        ignore_cleanup_errors: bool = False,
-        delete: bool = True,
-    ) -> None:
-        super().__init__()
-        self._temp_dir = _TemporaryDirectoryNoResourceWarning(
-            suffix=suffix,
-            prefix=prefix,
-            dir=dir,
-            ignore_cleanup_errors=ignore_cleanup_errors,
-            delete=delete,
-        )
-        self.path = Path(self._temp_dir.name)
-
-    def __enter__(self) -> Path:
-        return Path(self._temp_dir.__enter__())
-
-    def __exit__(
-        self,
-        exc: type[BaseException] | None,
-        val: BaseException | None,
-        tb: TracebackType | None,
-    ) -> None:
-        self._temp_dir.__exit__(exc, val, tb)
-
-
-class _TemporaryDirectoryNoResourceWarning(tempfile.TemporaryDirectory):
-    @classmethod
-    @override
-    def _cleanup(  # pyright: ignore[reportGeneralTypeIssues]
-        cls,
-        name: str,
-        warn_message: str,
-        ignore_errors: bool = False,
-        delete: bool = True,
-    ) -> None:
-        with suppress_warnings(category=ResourceWarning):
-            return super()._cleanup(  # pyright: ignore[reportAttributeAccessIssue]
-                name, warn_message, ignore_errors=ignore_errors, delete=delete
-            )
-
-
-##
-
-
-def gettempdir() -> Path:
-    """Get the name of the directory used for temporary files."""
-    return Path(_gettempdir())
-
-
-TEMP_DIR = gettempdir()
-
-
-__all__ = ["TEMP_DIR", "TemporaryDirectory", "gettempdir"]

utilities/typed_settings.py

@@ -1,152 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from functools import partial
-from ipaddress import IPv4Address, IPv6Address
-from os import environ
-from pathlib import Path
-from re import search
-from typing import TYPE_CHECKING, Any, assert_never, override
-from uuid import UUID
-
-import typed_settings
-from typed_settings import EnvLoader, FileLoader, find
-from typed_settings.converters import TSConverter
-from typed_settings.loaders import TomlFormat
-from whenever import (
-    Date,
-    DateDelta,
-    DateTimeDelta,
-    MonthDay,
-    PlainDateTime,
-    Time,
-    TimeDelta,
-    YearMonth,
-    ZonedDateTime,
-)
-
-from utilities.iterables import always_iterable
-from utilities.pathlib import to_path
-from utilities.string import substitute_environ
-
-if TYPE_CHECKING:
-    from collections.abc import Callable, Iterable
-
-    from typed_settings.loaders import Loader
-    from typed_settings.processors import Processor
-
-    from utilities.types import MaybeCallablePathLike, MaybeIterable, PathLike
-
-
-type _ConverterItem = tuple[type[Any], Callable[..., Any]]
-
-
-##
-
-
-class ExtendedTSConverter(TSConverter):
-    """An extension of the TSConverter for custom types."""
-
-    @override
-    def __init__(
-        self,
-        *,
-        resolve_paths: bool = True,
-        strlist_sep: str | Callable[[str], list] | None = ":",
-        extra: Iterable[_ConverterItem] = (),
-    ) -> None:
-        super().__init__(resolve_paths=resolve_paths, strlist_sep=strlist_sep)
-        cases: list[_ConverterItem] = [
-            (Date, Date.parse_common_iso),
-            (DateDelta, DateDelta.parse_common_iso),
-            (DateTimeDelta, DateTimeDelta.parse_common_iso),
-            (IPv4Address, IPv4Address),
-            (IPv6Address, IPv6Address),
-            (MonthDay, MonthDay.parse_common_iso),
-            (Path, partial(_parse_path, resolve=resolve_paths, pwd=Path.cwd())),
-            (PlainDateTime, PlainDateTime.parse_common_iso),
-            (Time, Time.parse_common_iso),
-            (TimeDelta, TimeDelta.parse_common_iso),
-            (UUID, UUID),
-            (YearMonth, YearMonth.parse_common_iso),
-            (ZonedDateTime, ZonedDateTime.parse_common_iso),
-            *extra,
-        ]
-        extras = {cls: _make_converter(cls, func) for cls, func in cases}
-        self.scalar_converters |= extras
-
-
-def _make_converter[T](
-    cls: type[T], parser: Callable[[str], T], /
-) -> Callable[[Any, type[Any]], Any]:
-    def hook(value: T | str, _: type[T] = cls, /) -> Any:
-        if not isinstance(value, (cls, str)):  # pragma: no cover
-            msg = f"Invalid type {type(value).__name__!r}; expected '{cls.__name__}' or 'str'"
-            raise TypeError(msg)
-        if isinstance(value, str):
-            return parser(value)
-        return value
-
-    return hook
-
-
-def _parse_path(
-    path: str, /, *, resolve: bool = False, pwd: MaybeCallablePathLike = Path.cwd
-) -> Path:
-    path = substitute_environ(path, **environ)
-    match resolve:
-        case True:
-            return to_path(pwd).joinpath(path).resolve()
-        case False:
-            return Path(path)
-        case never:
-            assert_never(never)
-
-
-##
-
-
-_BASE_DIR: Path = Path()
-
-
-def load_settings[T](
-    cls: type[T],
-    app_name: str,
-    /,
-    *,
-    filenames: MaybeIterable[str] = "settings.toml",
-    start_dir: PathLike | None = None,
-    loaders: MaybeIterable[Loader] | None = None,
-    processors: MaybeIterable[Processor] = (),
-    converters: Iterable[_ConverterItem] = (),
-    base_dir: Path = _BASE_DIR,
-) -> T:
-    if not search(r"^[A-Za-z]+(?:_[A-Za-z]+)*$", app_name):
-        raise LoadSettingsError(appname=app_name)
-    filenames_use = list(always_iterable(filenames))
-    start_dir_use = None if start_dir is None else Path(start_dir)
-    files = [find(filename, start_dir=start_dir_use) for filename in filenames_use]
-    file_loader = FileLoader(formats={"*.toml": TomlFormat(app_name)}, files=files)
-    env_loader = EnvLoader(f"{app_name.upper()}__", nested_delimiter="__")
-    loaders_use: list[Loader] = [file_loader, env_loader]
-    if loaders is not None:
-        loaders_use.extend(always_iterable(loaders))
-    return typed_settings.load_settings(
-        cls,
-        loaders_use,
-        processors=list(always_iterable(processors)),
-        converter=ExtendedTSConverter(extra=converters),
-        base_dir=base_dir,
-    )
-
-
-@dataclass(kw_only=True, slots=True)
-class LoadSettingsError(Exception):
-    appname: str
-
-    @override
-    def __str__(self) -> str:
-        return f"Invalid app name; got {self.appname!r}"
-
-
-__all__ = ["ExtendedTSConverter", "LoadSettingsError", "load_settings"]

utilities/tzdata.py

@@ -1,11 +0,0 @@
-from __future__ import annotations
-
-from zoneinfo import ZoneInfo
-
-HongKong = ZoneInfo("Asia/Hong_Kong")
-Tokyo = ZoneInfo("Asia/Tokyo")
-USCentral = ZoneInfo("US/Central")
-USEastern = ZoneInfo("US/Eastern")
-
-
-__all__ = ["HongKong", "Tokyo", "USCentral", "USEastern"]

utilities/tzlocal.py

@@ -1,28 +0,0 @@
-from __future__ import annotations
-
-from logging import getLogger
-from typing import TYPE_CHECKING, cast
-
-from tzlocal import get_localzone
-
-if TYPE_CHECKING:
-    from zoneinfo import ZoneInfo
-
-    from utilities.types import TimeZone
-
-
-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 = get_local_time_zone()
-LOCAL_TIME_ZONE_NAME = cast("TimeZone", LOCAL_TIME_ZONE.key)
-
-
-__all__ = ["LOCAL_TIME_ZONE", "LOCAL_TIME_ZONE_NAME", "get_local_time_zone"]

utilities/warnings.py

@@ -1,65 +0,0 @@
-from __future__ import annotations
-
-from contextlib import ExitStack, contextmanager
-from typing import TYPE_CHECKING, Literal, TypedDict
-from warnings import catch_warnings, filterwarnings
-
-if TYPE_CHECKING:
-    from collections.abc import Iterator
-
-    from utilities.types import TypeLike
-
-
-@contextmanager
-def catch_warnings_as_errors(
-    *, message: str = "", category: TypeLike[Warning] | None = None
-) -> Iterator[None]:
-    """Catch warnings as errors."""
-    with _handle_warnings("error", message=message, category=category):
-        yield
-
-
-@contextmanager
-def suppress_warnings(
-    *, message: str = "", category: TypeLike[Warning] | None = None
-) -> Iterator[None]:
-    """Suppress warnings."""
-    with _handle_warnings("ignore", message=message, category=category):
-        yield
-
-
-_ActionKind = Literal["error", "ignore"]
-
-
-def _handle_warnings(
-    action: _ActionKind,
-    /,
-    *,
-    message: str = "",
-    category: TypeLike[Warning] | None = None,
-) -> ExitStack:
-    """Handle a set of warnings."""
-    stack = ExitStack()
-    categories = category if isinstance(category, tuple) else [category]
-    for cat in categories:
-        cm = _handle_warnings_1(action, message=message, category=cat)
-        stack.enter_context(cm)
-    return stack
-
-
-@contextmanager
-def _handle_warnings_1(
-    action: _ActionKind, /, *, message: str = "", category: type[Warning] | None = None
-) -> Iterator[None]:
-    """Handle one set of warnings."""
-
-    class Kwargs(TypedDict, total=False):
-        category: type[Warning]
-
-    with catch_warnings():
-        kwargs: Kwargs = {} if category is None else {"category": category}
-        filterwarnings(action, message=message, **kwargs)
-        yield
-
-
-__all__ = ["catch_warnings_as_errors", "suppress_warnings"]