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

utilities/os.py

@@ -1,42 +1,12 @@
 from __future__ import annotations
 
-from contextlib import suppress
 from dataclasses import dataclass
-from os import cpu_count, environ, getenv
-from typing import TYPE_CHECKING, Literal, assert_never, overload, override
+from typing import TYPE_CHECKING, assert_never, override
 
-from utilities.contextlib import enhanced_context_manager
-from utilities.iterables import OneStrEmptyError, one_str
+from utilities.constants import CPU_COUNT
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator, Mapping
-
-
-type IntOrAll = int | Literal["all"]
-
-
-##
-
-
-def get_cpu_count() -> int:
-    """Get the CPU count."""
-    count = cpu_count()
-    if count is None:  # pragma: no cover
-        raise GetCPUCountError
-    return count
-
-
-@dataclass(kw_only=True, slots=True)
-class GetCPUCountError(Exception):
-    @override
-    def __str__(self) -> str:
-        return "CPU count must not be None"  # pragma: no cover
-
-
-CPU_COUNT = get_cpu_count()
-
-
-##
+    from utilities.types import IntOrAll
 
 
 def get_cpu_use(*, n: IntOrAll = "all") -> int:
@@ -61,117 +31,4 @@ class GetCPUUseError(Exception):
         return f"Invalid number of CPUs to use: {self.n}"
 
 
-##
-
-
-@overload
-def get_env_var(
-    key: str, /, *, case_sensitive: bool = False, default: str, nullable: bool = False
-) -> str: ...
-@overload
-def get_env_var(
-    key: str,
-    /,
-    *,
-    case_sensitive: bool = False,
-    default: None = None,
-    nullable: Literal[False] = False,
-) -> str: ...
-@overload
-def get_env_var(
-    key: str,
-    /,
-    *,
-    case_sensitive: bool = False,
-    default: str | None = None,
-    nullable: bool = False,
-) -> str | None: ...
-def get_env_var(
-    key: str,
-    /,
-    *,
-    case_sensitive: bool = False,
-    default: str | None = None,
-    nullable: bool = False,
-) -> str | None:
-    """Get an environment variable."""
-    try:
-        key_use = one_str(environ, key, case_sensitive=case_sensitive)
-    except OneStrEmptyError:
-        match default, nullable:
-            case None, False:
-                raise GetEnvVarError(key=key, case_sensitive=case_sensitive) from None
-            case None, True:
-                return None
-            case str(), _:
-                return default
-            case never:
-                assert_never(never)
-    return environ[key_use]
-
-
-@dataclass(kw_only=True, slots=True)
-class GetEnvVarError(Exception):
-    key: str
-    case_sensitive: bool = False
-
-    @override
-    def __str__(self) -> str:
-        desc = f"No environment variable {self.key!r}"
-        return desc if self.case_sensitive else f"{desc} (modulo case)"
-
-
-##
-
-
-def is_debug() -> bool:
-    """Check if we are in `DEBUG` mode."""
-    return get_env_var("DEBUG", nullable=True) is not None
-
-
-##
-
-
-def is_pytest() -> bool:
-    """Check if `pytest` is running."""
-    return get_env_var("PYTEST_VERSION", nullable=True) is not None
-
-
-##
-
-
-@enhanced_context_manager
-def temp_environ(
-    env: Mapping[str, str | None] | None = None, **env_kwargs: str | None
-) -> Iterator[None]:
-    """Context manager with temporary environment variable set."""
-    mapping: dict[str, str | None] = ({} if env is None else dict(env)) | env_kwargs
-    prev = {key: getenv(key) for key in mapping}
-
-    def apply(mapping: Mapping[str, str | None], /) -> None:
-        for key, value in mapping.items():
-            if value is None:
-                with suppress(KeyError):
-                    del environ[key]
-            else:
-                environ[key] = value
-
-    apply(mapping)
-    try:
-        yield
-    finally:
-        apply(prev)
-
-
-__all__ = [
-    "CPU_COUNT",
-    "GetCPUCountError",
-    "GetCPUUseError",
-    "IntOrAll",
-    "get_cpu_count",
-    "get_cpu_use",
-    "get_env_var",
-    "is_debug",
-    "is_pytest",
-    "temp_environ",
-]
+__all__ = ["GetCPUUseError", "get_cpu_use"]

utilities/packaging.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Self, overload, override
+
+import packaging._parser
+import packaging.requirements
+from packaging.requirements import _parse_requirement
+from packaging.specifiers import Specifier, SpecifierSet
+
+from utilities.core import OneEmptyError, one
+
+if TYPE_CHECKING:
+    from packaging._parser import MarkerList
+
+
+@dataclass(order=True, unsafe_hash=True, slots=True)
+class Requirement:
+    requirement: str
+    _parsed_req: packaging._parser.ParsedRequirement = field(init=False, repr=False)
+    _custom_req: _CustomRequirement = field(init=False, repr=False)
+
+    def __getitem__(self, operator: str, /) -> str:
+        return self.specifier_set[operator]
+
+    def __post_init__(self) -> None:
+        self._parsed_req = _parse_requirement(self.requirement)
+        self._custom_req = _CustomRequirement(self.requirement)
+
+    @override
+    def __str__(self) -> str:
+        return str(self._custom_req)
+
+    def drop(self, operator: str, /) -> Self:
+        return type(self)(str(self._custom_req.drop(operator)))
+
+    @property
+    def extras(self) -> list[str]:
+        return self._parsed_req.extras
+
+    @overload
+    def get(self, operator: str, default: str, /) -> str: ...
+    @overload
+    def get(self, operator: str, default: None = None, /) -> str | None: ...
+    def get(self, operator: str, default: str | None = None, /) -> str | None:
+        return self.specifier_set.get(operator, default)
+
+    @property
+    def marker(self) -> MarkerList | None:
+        return self._parsed_req.marker
+
+    @property
+    def name(self) -> str:
+        return self._parsed_req.name
+
+    def replace(self, operator: str, version: str | None, /) -> Self:
+        return type(self)(str(self._custom_req.replace(operator, version)))
+
+    @property
+    def specifier(self) -> str:
+        return self._parsed_req.specifier
+
+    @property
+    def specifier_set(self) -> _CustomSpecifierSet:
+        return _CustomSpecifierSet(_parse_requirement(self.requirement).specifier)
+
+    @property
+    def url(self) -> str:
+        return self._parsed_req.url
+
+
+class _CustomRequirement(packaging.requirements.Requirement):
+    specifier: _CustomSpecifierSet
+
+    @override
+    def __init__(self, requirement_string: str) -> None:
+        super().__init__(requirement_string)
+        parsed = _parse_requirement(requirement_string)
+        self.specifier = _CustomSpecifierSet(parsed.specifier)  # pyright: ignore[reportIncompatibleVariableOverride]
+
+    def drop(self, operator: str, /) -> Self:
+        new = type(self)(super().__str__())
+        new.specifier = self.specifier.drop(operator)
+        return new
+
+    def replace(self, operator: str, version: str | None, /) -> Self:
+        new = type(self)(super().__str__())
+        new.specifier = self.specifier.replace(operator, version)
+        return new
+
+
+class _CustomSpecifierSet(SpecifierSet):
+    def __getitem__(self, operator: str, /) -> str:
+        try:
+            return one(s.version for s in self if s.operator == operator)
+        except OneEmptyError:
+            raise KeyError(operator) from None
+
+    @override
+    def __str__(self) -> str:
+        specs = sorted(self._specs, key=self._sort_key)
+        return ", ".join(map(str, specs))
+
+    def drop(self, operator: str, /) -> Self:
+        if any(s.operator == operator for s in self):
+            return type(self)(s for s in self if s.operator != operator)
+        raise KeyError(operator)
+
+    @overload
+    def get(self, operator: str, default: str, /) -> str: ...
+    @overload
+    def get(self, operator: str, default: None = None, /) -> str | None: ...
+    def get(self, operator: str, default: str | None = None, /) -> str | None:
+        try:
+            return self[operator]
+        except KeyError:
+            return default
+
+    def replace(self, operator: str, version: str | None, /) -> Self:
+        specifiers = [s for s in self if s.operator != operator]
+        if version is not None:
+            specifiers.append(Specifier(spec=f"{operator}{version}"))
+        return type(self)(specifiers)
+
+    def _sort_key(self, spec: Specifier, /) -> int:
+        return ["==", "!=", "~=", ">", ">=", "<", "<="].index(spec.operator)
+
+
+__all__ = ["Requirement"]

utilities/parse.py

@@ -21,15 +21,24 @@ from whenever import (
     ZonedDateTime,
 )
 
-from utilities.enum import ParseEnumError, parse_enum
-from utilities.iterables import OneEmptyError, OneNonUniqueError, one, one_str
-from utilities.math import ParseNumberError, parse_number
-from utilities.re import ExtractGroupError, extract_group
-from utilities.sentinel import ParseSentinelError, Sentinel, parse_sentinel
-from utilities.text import (
+from utilities.constants import (
     BRACKETS,
     LIST_SEPARATOR,
     PAIR_SEPARATOR,
+    Sentinel,
+    SentinelParseError,
+)
+from utilities.core import (
+    ExtractGroupError,
+    OneEmptyError,
+    OneNonUniqueError,
+    extract_group,
+    one,
+    one_str,
+)
+from utilities.enum import ParseEnumError, parse_enum
+from utilities.math import ParseNumberError, parse_number
+from utilities.text import (
     ParseBoolError,
     ParseNoneError,
     join_strs,
@@ -52,7 +61,12 @@ from utilities.typing import (
     is_tuple_type,
     is_union_type,
 )
-from utilities.version import ParseVersionError, Version, parse_version
+from utilities.version import (
+    Version2,
+    Version3,
+    _Version2ParseError,
+    _Version3ParseError,
+)
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Mapping, Sequence
@@ -204,20 +218,25 @@ def _parse_object_type(
         ),
     ):
         try:
-            return cls.parse_common_iso(text)
+            return cls.parse_iso(text)
         except ValueError:
             raise _ParseObjectParseError(type_=cls, text=text) from None
     if issubclass(cls, Path):
         return Path(text).expanduser()
     if issubclass(cls, Sentinel):
         try:
-            return parse_sentinel(text)
-        except ParseSentinelError:
+            return Sentinel.parse(text)
+        except SentinelParseError:
+            raise _ParseObjectParseError(type_=cls, text=text) from None
+    if issubclass(cls, Version2):
+        try:
+            return Version2.parse(text)
+        except _Version2ParseError:
             raise _ParseObjectParseError(type_=cls, text=text) from None
-    if issubclass(cls, Version):
+    if issubclass(cls, Version3):
         try:
-            return parse_version(text)
-        except ParseVersionError:
+            return Version3.parse(text)
+        except _Version3ParseError:
             raise _ParseObjectParseError(type_=cls, text=text) from None
     raise _ParseObjectParseError(type_=cls, text=text)
 
@@ -460,7 +479,8 @@ def serialize_object(
         | IPv6Address
         | Path
         | Sentinel
-        | Version,
+        | Version2
+        | Version3,
     ):
         return str(obj)
     if isinstance(
@@ -477,7 +497,7 @@ def serialize_object(
             ZonedDateTime,
         ),
     ):
-        return obj.format_common_iso()
+        return obj.format_iso()
     if isinstance(obj, Enum):
         return obj.name
     if isinstance(obj, dict):

utilities/pathlib.py

@@ -3,26 +3,19 @@ from __future__ import annotations
 from collections.abc import Callable
 from dataclasses import dataclass
 from itertools import chain
-from os import chdir
-from os.path import expandvars
 from pathlib import Path
 from re import IGNORECASE, search
 from subprocess import PIPE, CalledProcessError, check_output
 from typing import TYPE_CHECKING, Literal, assert_never, overload, override
 
-from utilities.contextlib import enhanced_context_manager
-from utilities.errors import ImpossibleCaseError
-from utilities.sentinel import Sentinel
+from utilities.constants import Sentinel
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator, Sequence
+    from collections.abc import Sequence
 
     from utilities.types import MaybeCallablePathLike, PathLike
 
 
-PWD = Path.cwd()
-
-
 def ensure_suffix(path: PathLike, suffix: str, /) -> Path:
     """Ensure a path has a given suffix."""
     path = Path(path)
@@ -42,43 +35,6 @@ def ensure_suffix(path: PathLike, suffix: str, /) -> Path:
 ##
 
 
-def expand_path(path: PathLike, /) -> Path:
-    """Expand a path."""
-    path = str(path)
-    path = expandvars(path)
-    return Path(path).expanduser()
-
-
-##
-
-
-def get_package_root(path: MaybeCallablePathLike = Path.cwd, /) -> Path:
-    """Get the package root."""
-    path = to_path(path)
-    path_dir = path.parent if path.is_file() else path
-    all_paths = list(chain([path_dir], path_dir.parents))
-    try:
-        return next(
-            p.resolve()
-            for p in all_paths
-            if any(p_i.name == "pyproject.toml" for p_i in p.iterdir())
-        )
-    except StopIteration:
-        raise GetPackageRootError(path=path) from None
-
-
-@dataclass(kw_only=True, slots=True)
-class GetPackageRootError(Exception):
-    path: PathLike
-
-    @override
-    def __str__(self) -> str:
-        return f"Path is not part of a package: {self.path}"
-
-
-##
-
-
 def get_repo_root(path: MaybeCallablePathLike = Path.cwd, /) -> Path:
     """Get the repo root."""
     path = to_path(path)
@@ -112,7 +68,7 @@ class GetRepoRootError(Exception): ...
 class _GetRepoRootGitNotFoundError(GetRepoRootError):
     @override
     def __str__(self) -> str:
-        return "'git' not found"
+        return "'git' not found"  # pragma: no cover
 
 
 @dataclass(kw_only=True, slots=True)
@@ -127,50 +83,6 @@ class _GetRepoRootNotARepoError(GetRepoRootError):
 ##
 
 
-def get_root(path: MaybeCallablePathLike = Path.cwd, /) -> Path:
-    """Get the root of a path."""
-    path = to_path(path)
-    try:
-        repo = get_repo_root(path)
-    except GetRepoRootError:
-        repo = None
-    try:
-        package = get_package_root(path)
-    except GetPackageRootError:
-        package = None
-    match repo, package:
-        case None, None:
-            raise GetRootError(path=path)
-        case Path(), None:
-            return repo
-        case None, Path():
-            return package
-        case Path(), Path():
-            if repo == package:
-                return repo
-            if is_sub_path(repo, package, strict=True):
-                return repo
-            if is_sub_path(package, repo, strict=True):
-                return package
-            raise ImpossibleCaseError(  # pragma: no cover
-                case=[f"{repo=}", f"{package=}"]
-            )
-        case never:
-            assert_never(never)
-
-
-@dataclass(kw_only=True, slots=True)
-class GetRootError(Exception):
-    path: PathLike
-
-    @override
-    def __str__(self) -> str:
-        return f"Unable to determine root from {str(self.path)!r}"
-
-
-##
-
-
 type _GetTailDisambiguate = Literal["raise", "earlier", "later"]
 
 
@@ -268,15 +180,6 @@ def module_path(
 ##
 
 
-def is_sub_path(x: PathLike, y: PathLike, /, *, strict: bool = False) -> bool:
-    """Check if a path is a sub path of another."""
-    x, y = [Path(i).resolve() for i in [x, y]]
-    return x.is_relative_to(y) and not (strict and y.is_relative_to(x))
-
-
-##
-
-
 def list_dir(path: PathLike, /) -> Sequence[Path]:
     """List the contents of a directory."""
     return sorted(Path(path).iterdir())
@@ -285,20 +188,6 @@ def list_dir(path: PathLike, /) -> Sequence[Path]:
 ##
 
 
-@enhanced_context_manager
-def temp_cwd(path: PathLike, /) -> Iterator[None]:
-    """Context manager with temporary current working directory set."""
-    prev = Path.cwd()
-    chdir(path)
-    try:
-        yield
-    finally:
-        chdir(prev)
-
-
-##
-
-
 @overload
 def to_path(path: Sentinel, /) -> Sentinel: ...
 @overload
@@ -321,18 +210,12 @@ def to_path(
 
 
 __all__ = [
-    "PWD",
-    "GetPackageRootError",
     "GetRepoRootError",
     "GetTailError",
     "ensure_suffix",
-    "expand_path",
-    "get_package_root",
     "get_repo_root",
     "get_tail",
-    "is_sub_path",
     "list_dir",
     "module_path",
-    "temp_cwd",
     "to_path",
 ]

utilities/platform.py

@@ -1,74 +1,9 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
-from pathlib import Path
-from platform import system
 from re import sub
-from typing import TYPE_CHECKING, Literal, assert_never, override
+from typing import assert_never
 
-if TYPE_CHECKING:
-    from collections.abc import Iterable, Iterator
-
-
-System = Literal["windows", "mac", "linux"]
-
-
-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 GetSystemError(sys=sys)  # pragma: no cover
-
-
-@dataclass(kw_only=True, slots=True)
-class GetSystemError(Exception):
-    sys: str
-
-    @override
-    def __str__(self) -> str:
-        return (  # pragma: no cover
-            f"System must be one of Windows, Darwin, Linux; got {self.sys!r} instead"
-        )
-
-
-SYSTEM = get_system()
-IS_WINDOWS = SYSTEM == "windows"
-IS_MAC = SYSTEM == "mac"
-IS_LINUX = SYSTEM == "linux"
-IS_NOT_WINDOWS = not IS_WINDOWS
-IS_NOT_MAC = not IS_MAC
-IS_NOT_LINUX = not IS_LINUX
-
-
-##
-
-
-def get_max_pid() -> int | None:
-    """Get the maximum process ID."""
-    match SYSTEM:
-        case "windows":  # pragma: no cover
-            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 = get_max_pid()
-
-
-##
+from utilities.constants import SYSTEM
 
 
 def get_strftime(text: str, /) -> str:
@@ -87,32 +22,15 @@ def get_strftime(text: str, /) -> str:
 ##
 
 
-def maybe_yield_lower_case(text: Iterable[str], /) -> Iterator[str]:
-    """Yield lower-cased text if the platform is case-insentive."""
+def maybe_lower_case(text: str, /) -> str:
+    """Lower-case text if the platform is case-insensitive w.r.t. filenames."""
     match SYSTEM:
-        case "windows":  # skipif-not-windows
-            yield from (t.lower() for t in text)
-        case "mac":  # skipif-not-macos
-            yield from (t.lower() for t in text)
+        case "windows" | "mac":  # skipif-linux
+            return text.lower()
         case "linux":  # skipif-not-linux
-            yield from text
+            return text
         case never:
             assert_never(never)
 
 
-__all__ = [
-    "IS_LINUX",
-    "IS_MAC",
-    "IS_NOT_LINUX",
-    "IS_NOT_MAC",
-    "IS_NOT_WINDOWS",
-    "IS_WINDOWS",
-    "MAX_PID",
-    "SYSTEM",
-    "GetSystemError",
-    "System",
-    "get_max_pid",
-    "get_strftime",
-    "get_system",
-    "maybe_yield_lower_case",
-]
+__all__ = ["get_strftime", "maybe_lower_case"]