dycw-utilities 0.135.0__py3-none-any.whl → 0.178.1__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

@@ -1,17 +1,25 @@
 from __future__ import annotations
 
-from typing import cast
+from collections.abc import Sized
+from typing import assert_never, cast
 
 from inflect import Word, engine
 
 _ENGINE = engine()
 
 
-def counted_noun(num: int, noun: str, /) -> str:
+def counted_noun(obj: int | Sized, noun: str, /) -> str:
     """Construct a counted noun."""
+    match obj:
+        case int() as count:
+            ...
+        case Sized() as sized:
+            count = len(sized)
+        case never:
+            assert_never(never)
     word = cast("Word", noun)
-    sin_or_plu = _ENGINE.plural_noun(word, count=num)
-    return f"{num} {sin_or_plu}"
+    sin_or_plu = _ENGINE.plural_noun(word, count=count)
+    return f"{count} {sin_or_plu}"
 
 
 __all__ = ["counted_noun"]

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):
@@ -755,6 +731,26 @@ class EnsureIterableNotStrError(Exception):
 ##
 
 
+_EDGE: int = 5
+
+
+def enumerate_with_edge[T](
+    iterable: Iterable[T], /, *, start: int = 0, edge: int = _EDGE
+) -> Iterator[tuple[int, int, bool, T]]:
+    """Enumerate an iterable, with the edge items marked."""
+    as_list = list(iterable)
+    total = len(as_list)
+    indices = set(range(edge)) | set(range(total)[-edge:])
+    is_edge = (i in indices for i in range(total))
+    for (i, value), is_edge_i in zip(
+        enumerate(as_list, start=start), is_edge, strict=True
+    ):
+        yield i, total, is_edge_i, value
+
+
+##
+
+
 def expanding_window[T](iterable: Iterable[T], /) -> islice[list[T]]:
     """Yield an expanding window over an iterable."""
 
@@ -811,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
@@ -955,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:
@@ -1048,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)
@@ -1089,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}"
 
@@ -1111,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"
 
@@ -1245,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)
@@ -1362,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)
 
 
@@ -1469,7 +1447,6 @@ __all__ = [
     "ResolveIncludeAndExcludeError",
     "SortIterableError",
     "always_iterable",
-    "always_iterable_hashable",
     "apply_bijection",
     "apply_to_tuple",
     "apply_to_varargs",
@@ -1489,12 +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",
@@ -1517,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

@@ -0,0 +1,70 @@
+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/libcst.py

@@ -23,16 +23,6 @@ from libcst import (
 from utilities.errors import ImpossibleCaseError
 
 
-def generate_from_import(
-    module: str, name: str, /, *, asname: str | None = None
-) -> ImportFrom:
-    """Generate an `ImportFrom` object."""
-    alias = ImportAlias(
-        name=Name(name), asname=AsName(Name(asname)) if asname else None
-    )
-    return ImportFrom(module=split_dotted_str(module), names=[alias])
-
-
 def generate_f_string(var: str, suffix: str, /) -> FormattedString:
     """Generate an f-string."""
     return FormattedString([
@@ -49,6 +39,36 @@ def generate_import(module: str, /, *, asname: str | None = None) -> Import:
     return Import(names=[alias])
 
 
+def generate_import_from(
+    module: str, name: str, /, *, asname: str | None = None
+) -> ImportFrom:
+    """Generate an `ImportFrom` object."""
+    match name, asname:
+        case "*", None:
+            names = ImportStar()
+        case "*", str():
+            raise GenerateImportFromError(module=module, asname=asname)
+        case _, None:
+            alias = ImportAlias(name=Name(name))
+            names = [alias]
+        case _, str():
+            alias = ImportAlias(name=Name(name), asname=AsName(Name(asname)))
+            names = [alias]
+        case never:
+            assert_never(never)
+    return ImportFrom(module=split_dotted_str(module), names=names)
+
+
+@dataclass(kw_only=True, slots=True)
+class GenerateImportFromError(Exception):
+    module: str
+    asname: str | None = None
+
+    @override
+    def __str__(self) -> str:
+        return f"Invalid import: 'from {self.module} import * as {self.asname}'"
+
+
 ##
 
 
@@ -72,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)
 
 
@@ -88,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)
 
 
@@ -130,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:
@@ -142,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))
 
@@ -160,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)
 
 
@@ -168,10 +188,11 @@ def render_module(source: str | Module, /) -> str:
 
 
 __all__ = [
+    "GenerateImportFromError",
     "ParseImportError",
     "generate_f_string",
-    "generate_from_import",
     "generate_import",
+    "generate_import_from",
     "join_dotted_str",
     "parse_import",
     "render_module",

utilities/lightweight_charts.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
-from contextlib import asynccontextmanager
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, override
 
 from utilities.atomicwrites import writer  # pragma: no cover
+from utilities.contextlib import enhanced_async_context_manager
 from utilities.iterables import OneEmptyError, OneNonUniqueError, one
 from utilities.reprlib import get_repr
 
@@ -25,11 +25,8 @@ if TYPE_CHECKING:
 def save_chart(chart: Chart, path: PathLike, /, *, overwrite: bool = False) -> None:
     """Atomically save a chart to disk."""
     chart.show(block=False)  # pragma: no cover
-    with (  # pragma: no cover
-        writer(path, overwrite=overwrite) as temp,
-        temp.open(mode="wb") as fh,
-    ):
-        _ = fh.write(chart.screenshot())
+    with writer(path, overwrite=overwrite) as temp:  # pragma: no cover
+        _ = temp.write_bytes(chart.screenshot())
     chart.exit()  # pragma: no cover
 
 
@@ -81,7 +78,7 @@ class _SetDataFrameNonUniqueError(SetDataFrameError):
 ##
 
 
-@asynccontextmanager
+@enhanced_async_context_manager
 async def yield_chart(chart: Chart, /) -> AsyncIterator[None]:
     """Yield a chart for visualization in a notebook."""
     try:  # pragma: no cover