dycw-utilities 0.129.10__py3-none-any.whl → 0.175.17__py3-none-any.whl

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,9 +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
 
@@ -23,14 +24,9 @@ if TYPE_CHECKING:
 
 def save_chart(chart: Chart, path: PathLike, /, *, overwrite: bool = False) -> None:
     """Atomically save a chart to disk."""
-    from utilities.atomicwrites import writer  # pragma: no cover
-
     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
 
 
@@ -82,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