dycw-utilities 0.148.5__py3-none-any.whl → 0.175.31__py3-none-any.whl

utilities/importlib.py

@@ -1,7 +1,23 @@
 from __future__ import annotations
 
+import importlib.resources
 from importlib import import_module
 from importlib.util import find_spec
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from utilities.errors import ImpossibleCaseError
+
+if TYPE_CHECKING:
+    from importlib.resources import Anchor
+
+
+def files(*, anchor: Anchor | None = None) -> Path:
+    """Get the path for an anchor."""
+    path = importlib.resources.files(anchor)
+    if isinstance(path, Path):
+        return path
+    raise ImpossibleCaseError(case=[f"{path=}"])  # pragma: no cover
 
 
 def is_valid_import(module: str, /, *, name: str | None = None) -> bool:
@@ -15,4 +31,4 @@ def is_valid_import(module: str, /, *, name: str | None = None) -> bool:
     return hasattr(mod, name)
 
 
-__all__ = ["is_valid_import"]
+__all__ = ["files", "is_valid_import"]

utilities/inflect.py

@@ -15,7 +15,7 @@ def counted_noun(obj: int | Sized, noun: str, /) -> str:
             ...
         case Sized() as sized:
             count = len(sized)
-        case _ as never:
+        case never:
             assert_never(never)
     word = cast("Word", noun)
     sin_or_plu = _ENGINE.plural_noun(word, count=count)

utilities/iterables.py

@@ -18,7 +18,7 @@ from enum import Enum
 from functools import cmp_to_key, partial, reduce
 from itertools import accumulate, chain, groupby, islice, pairwise, product
 from math import isnan
-from operator import add, itemgetter, or_
+from operator import add, or_
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -31,7 +31,6 @@ from typing import (
 )
 
 from utilities.errors import ImpossibleCaseError
-from utilities.functions import ensure_hashable, ensure_str
 from utilities.math import (
     _CheckIntegerEqualError,
     _CheckIntegerEqualOrApproxError,
@@ -40,13 +39,13 @@ from utilities.math import (
     check_integer,
 )
 from utilities.reprlib import get_repr
-from utilities.sentinel import Sentinel, sentinel
+from utilities.sentinel import Sentinel, is_sentinel, sentinel
 from utilities.types import SupportsAdd, SupportsLT
 
 if TYPE_CHECKING:
     from types import NoneType
 
-    from utilities.types import MaybeIterable, MaybeIterableHashable, Sign, StrMapping
+    from utilities.types import MaybeIterable, Sign, StrMapping
 
 
 ##
@@ -66,16 +65,6 @@ def always_iterable[T](obj: MaybeIterable[T], /) -> Iterable[T]:
 ##
 
 
-def always_iterable_hashable[T](
-    obj: MaybeIterable[T] | None, /
-) -> MaybeIterableHashable[T] | None:
-    """Ensure an object is always hashable."""
-    return None if obj is None else tuple(always_iterable(obj))
-
-
-##
-
-
 def apply_bijection[T, U](
     func: Callable[[T], U], iterable: Iterable[T], /
 ) -> Mapping[T, U]:
@@ -246,8 +235,7 @@ def check_iterables_equal(left: Iterable[Any], right: Iterable[Any], /) -> None:
             if lv != rv:
                 errors.append((i, lv, rv))
     except ValueError as error:
-        msg = ensure_str(one(error.args))
-        match msg:
+        match one(error.args):
             case "zip() argument 2 is longer than argument 1":
                 state = "right_longer"
             case "zip() argument 2 is shorter than argument 1":
@@ -295,7 +283,7 @@ class CheckIterablesEqualError[T](Exception):
                 yield "right was longer"
             case None:
                 pass
-            case _ as never:
+            case never:
                 assert_never(never)
 
 
@@ -690,7 +678,7 @@ def cmp_nullable[T: SupportsLT](x: T | None, y: T | None, /) -> Sign:
             return 1
         case _, _:
             return cast("Sign", (x > y) - (x < y))
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -705,18 +693,6 @@ def chunked[T](iterable: Iterable[T], n: int, /) -> Iterator[Sequence[T]]:
 ##
 
 
-def ensure_hashables(
-    *args: Any, **kwargs: Any
-) -> tuple[list[Hashable], dict[str, Hashable]]:
-    """Ensure a set of positional & keyword arguments are all hashable."""
-    hash_args = list(map(ensure_hashable, args))
-    hash_kwargs = {k: ensure_hashable(v) for k, v in kwargs.items()}
-    return hash_args, hash_kwargs
-
-
-##
-
-
 def ensure_iterable(obj: Any, /) -> Iterable[Any]:
     """Ensure an object is iterable."""
     if is_iterable(obj):
@@ -831,24 +807,6 @@ def filter_include_and_exclude[T, U](
 ##
 
 
-def group_consecutive_integers(iterable: Iterable[int], /) -> Iterable[tuple[int, int]]:
-    """Group consecutive integers."""
-    integers = sorted(iterable)
-    for _, group in groupby(enumerate(integers), key=lambda x: x[1] - x[0]):
-        as_list = list(map(itemgetter(1), group))
-        yield as_list[0], as_list[-1]
-
-
-def ungroup_consecutive_integers(
-    iterable: Iterable[tuple[int, int]], /
-) -> Iterable[int]:
-    """Ungroup consecutive integers."""
-    return chain.from_iterable(range(start, end + 1) for start, end in iterable)
-
-
-##
-
-
 @overload
 def groupby_lists[T](
     iterable: Iterable[T], /, *, key: None = None
@@ -975,7 +933,7 @@ class MergeStrMappingsError(Exception):
 
 def one[T](*iterables: Iterable[T]) -> T:
     """Return the unique value in a set of iterables."""
-    it = iter(chain(*iterables))
+    it = chain(*iterables)
     try:
         first = next(it)
     except StopIteration:
@@ -1068,7 +1026,7 @@ def one_str(
             it = (t for t in as_list if t.startswith(text))
         case True, False:
             it = (t for t in as_list if t.lower().startswith(text.lower()))
-        case _ as never:
+        case never:
             assert_never(never)
     try:
         return one(it)
@@ -1109,7 +1067,7 @@ class OneStrEmptyError(OneStrError):
                 tail = f"any string starting with {self.text!r}"
             case True, False:
                 tail = f"any string starting with {self.text!r} (modulo case)"
-            case _ as never:
+            case never:
                 assert_never(never)
         return f"{head} {tail}"
 
@@ -1131,7 +1089,7 @@ class OneStrNonUniqueError(OneStrError):
                 mid = f"exactly one string starting with {self.text!r}"
             case True, False:
                 mid = f"exactly one string starting with {self.text!r} (modulo case)"
-            case _ as never:
+            case never:
                 assert_never(never)
         return f"{head} {mid}; got {self.first!r}, {self.second!r} and perhaps more"
 
@@ -1265,7 +1223,7 @@ def reduce_mappings[K, V, W](
 ) -> Mapping[K, V | W]:
     """Reduce a function over the values of a set of mappings."""
     chained = chain_mappings(*sequence)
-    if isinstance(initial, Sentinel):
+    if is_sentinel(initial):
         func2 = cast("Callable[[V, V], V]", func)
         return {k: reduce(func2, v) for k, v in chained.items()}
     func2 = cast("Callable[[W, V], W]", func)
@@ -1382,7 +1340,7 @@ def _sort_iterable_cmp_floats(x: float, y: float, /) -> Sign:
             return -1
         case False, False:
             return cast("Sign", (x > y) - (x < y))
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -1489,7 +1447,6 @@ __all__ = [
     "ResolveIncludeAndExcludeError",
     "SortIterableError",
     "always_iterable",
-    "always_iterable_hashable",
     "apply_bijection",
     "apply_to_tuple",
     "apply_to_varargs",
@@ -1509,13 +1466,11 @@ __all__ = [
     "check_unique_modulo_case",
     "chunked",
     "cmp_nullable",
-    "ensure_hashables",
     "ensure_iterable",
     "ensure_iterable_not_str",
     "enumerate_with_edge",
     "expanding_window",
     "filter_include_and_exclude",
-    "group_consecutive_integers",
     "groupby_lists",
     "hashable_to_iterable",
     "is_iterable",
@@ -1538,6 +1493,5 @@ __all__ = [
     "sum_mappings",
     "take",
     "transpose",
-    "ungroup_consecutive_integers",
     "unique_everseen",
 ]

utilities/jinja2.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal, assert_never, override
+
+from jinja2 import BaseLoader, BytecodeCache, Environment, FileSystemLoader, Undefined
+from jinja2.defaults import (
+    BLOCK_END_STRING,
+    BLOCK_START_STRING,
+    COMMENT_END_STRING,
+    COMMENT_START_STRING,
+    KEEP_TRAILING_NEWLINE,
+    LINE_COMMENT_PREFIX,
+    LINE_STATEMENT_PREFIX,
+    LSTRIP_BLOCKS,
+    NEWLINE_SEQUENCE,
+    TRIM_BLOCKS,
+    VARIABLE_END_STRING,
+    VARIABLE_START_STRING,
+)
+
+from utilities.atomicwrites import writer
+from utilities.text import kebab_case, pascal_case, snake_case
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+    from pathlib import Path
+
+    from jinja2.ext import Extension
+
+    from utilities.types import StrMapping
+
+
+class EnhancedEnvironment(Environment):
+    """Environment with enhanced features."""
+
+    @override
+    def __init__(
+        self,
+        block_start_string: str = BLOCK_START_STRING,
+        block_end_string: str = BLOCK_END_STRING,
+        variable_start_string: str = VARIABLE_START_STRING,
+        variable_end_string: str = VARIABLE_END_STRING,
+        comment_start_string: str = COMMENT_START_STRING,
+        comment_end_string: str = COMMENT_END_STRING,
+        line_statement_prefix: str | None = LINE_STATEMENT_PREFIX,
+        line_comment_prefix: str | None = LINE_COMMENT_PREFIX,
+        trim_blocks: bool = TRIM_BLOCKS,
+        lstrip_blocks: bool = LSTRIP_BLOCKS,
+        newline_sequence: Literal["\n", "\r\n", "\r"] = NEWLINE_SEQUENCE,
+        keep_trailing_newline: bool = KEEP_TRAILING_NEWLINE,
+        extensions: Sequence[str | type[Extension]] = (),
+        optimized: bool = True,
+        undefined: type[Undefined] = Undefined,
+        finalize: Callable[..., Any] | None = None,
+        autoescape: bool | Callable[[str | None], bool] = False,
+        loader: BaseLoader | None = None,
+        cache_size: int = 400,
+        auto_reload: bool = True,
+        bytecode_cache: BytecodeCache | None = None,
+        enable_async: bool = False,
+    ) -> None:
+        super().__init__(
+            block_start_string,
+            block_end_string,
+            variable_start_string,
+            variable_end_string,
+            comment_start_string,
+            comment_end_string,
+            line_statement_prefix,
+            line_comment_prefix,
+            trim_blocks,
+            lstrip_blocks,
+            newline_sequence,
+            keep_trailing_newline,
+            extensions,
+            optimized,
+            undefined,
+            finalize,
+            autoescape,
+            loader,
+            cache_size,
+            auto_reload,
+            bytecode_cache,
+            enable_async,
+        )
+        self.filters["kebab"] = kebab_case
+        self.filters["pascal"] = pascal_case
+        self.filters["snake"] = snake_case
+
+
+@dataclass(order=True, unsafe_hash=True, kw_only=True, slots=True)
+class TemplateJob:
+    """A template with an associated rendering job."""
+
+    template: Path
+    kwargs: StrMapping
+    target: Path
+    mode: Literal["write", "append"] = "write"
+
+    def __post_init__(self) -> None:
+        if not self.template.exists():
+            raise _TemplateJobTemplateDoesNotExistError(path=self.template)
+        if (self.mode == "append") and not self.target.exists():
+            raise _TemplateJobTargetDoesNotExistError(path=self.template)
+
+    def run(self) -> None:
+        """Run the job."""
+        match self.mode:
+            case "write":
+                with writer(self.target, overwrite=True) as temp:
+                    _ = temp.write_text(self.rendered)
+            case "append":
+                with self.target.open(mode="a") as fh:
+                    _ = fh.write(self.rendered)
+            case never:
+                assert_never(never)
+
+    @property
+    def rendered(self) -> str:
+        """The template, rendered."""
+        env = EnhancedEnvironment(loader=FileSystemLoader(self.template.parent))
+        return env.get_template(self.template.name).render(self.kwargs)
+
+
+@dataclass(kw_only=True, slots=True)
+class TemplateJobError(Exception): ...
+
+
+@dataclass(kw_only=True, slots=True)
+class _TemplateJobTemplateDoesNotExistError(TemplateJobError):
+    path: Path
+
+    @override
+    def __str__(self) -> str:
+        return f"Template {str(self.path)!r} does not exist"
+
+
+@dataclass(kw_only=True, slots=True)
+class _TemplateJobTargetDoesNotExistError(TemplateJobError):
+    path: Path
+
+    @override
+    def __str__(self) -> str:
+        return f"Target {str(self.path)!r} does not exist"
+
+
+__all__ = ["EnhancedEnvironment", "TemplateJob", "TemplateJobError"]

utilities/json.py

@@ -36,7 +36,7 @@ def run_prettier(source: bytes | str | Path, /) -> bytes | str | None:
             with writer(path, overwrite=True) as temp:
                 _ = temp.write_bytes(result)
             return None
-        case _ as never:
+        case never:
             assert_never(never)
 
 

utilities/libcst.py

@@ -54,7 +54,7 @@ def generate_import_from(
         case _, str():
             alias = ImportAlias(name=Name(name), asname=AsName(Name(asname)))
             names = [alias]
-        case _ as never:
+        case never:
             assert_never(never)
     return ImportFrom(module=split_dotted_str(module), names=names)
 
@@ -92,9 +92,9 @@ def parse_import(import_: Import | ImportFrom, /) -> Sequence[_ParseImportOutput
                     return [_parse_import_from_one(module, n) for n in names]
                 case ImportStar():
                     return [_ParseImportOutput(module=module, name="*")]
-                case _ as never:
+                case never:
                     assert_never(never)
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -108,7 +108,7 @@ def _parse_import_from_one(module: str, alias: ImportAlias, /) -> _ParseImportOu
             return _ParseImportOutput(module=module, name=name)
         case Attribute() as attr:
             raise _ParseImportAliasError(module=module, attr=attr)
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -150,7 +150,7 @@ def split_dotted_str(dotted: str, /) -> Name | Attribute:
 
 def join_dotted_str(name_or_attr: Name | Attribute, /) -> str:
     """Join a dotted from from a name/attribute."""
-    parts: Sequence[str] = []
+    parts: list[str] = []
     curr: BaseExpression | Name | Attribute = name_or_attr
     while True:
         match curr:
@@ -162,7 +162,7 @@ def join_dotted_str(name_or_attr: Name | Attribute, /) -> str:
                 curr = value
             case BaseExpression():  # pragma: no cover
                 raise ImpossibleCaseError(case=[f"{curr=}"])
-            case _ as never:
+            case never:
                 assert_never(never)
     return ".".join(reversed(parts))
 
@@ -180,7 +180,7 @@ def render_module(source: str | Module, /) -> str:
                 return text
         case Module() as module:
             return render_module(module.code)
-        case _ as never:
+        case never:
             assert_never(never)