entangled-cli 2.2.1__tar.gz → 2.3.0__tar.gz

{entangled_cli-2.2.1 → entangled_cli-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: entangled-cli
-Version: 2.2.1
+Version: 2.3.0
 Summary: Literate Programming toolbox
 Project-URL: Homepage, https://entangled.github.io/
 Project-URL: Repository, https://github.com/entangled/entangled.py

{entangled_cli-2.2.1 → entangled_cli-2.3.0}/entangled/code_reader.py

@@ -1,5 +1,5 @@
 from dataclasses import dataclass, field
-from pathlib import Path, PurePath
+from pathlib import PurePath
 
 import mawk
 import re

{entangled_cli-2.2.1 → entangled_cli-2.3.0}/entangled/commands/__init__.py

@@ -3,12 +3,14 @@ from .status import status
 from .stitch import stitch
 from .sync import sync
 from .tangle import tangle
+from .reset import reset
 from .watch import watch
 from .brei import brei
 
 __all__ = [
     "new",
     "brei",
+    "reset",
     "status",
     "stitch",
     "sync",

{entangled_cli-2.2.1 → entangled_cli-2.3.0}/entangled/commands/brei.py

@@ -1,5 +1,6 @@
 from pathlib import Path
-from typing import Awaitable, Optional
+from collections.abc import Awaitable
+from typing import Any
 import argh  # type: ignore
 import asyncio
 import textwrap
@@ -11,15 +12,15 @@ from ..logging import logger
 log = logger()
 
 
-async def main(target_strs: list[str], force_run: bool, throttle: Optional[int]):
+async def main(target_strs: list[str], force_run: bool, throttle: int | None):
     if not Path(".entangled").exists():
         Path(".entangled").mkdir()
 
-    db = await resolve_tasks(config.brei, Path(".entangled/brei_history"))
+    db = await resolve_tasks(config.get.brei, Path(".entangled/brei_history"))
     if throttle:
         db.throttle = asyncio.Semaphore(throttle)
     db.force_run = force_run
-    jobs: list[Awaitable] = [db.run(Phony(t), db=db) for t in target_strs]
+    jobs: list[Awaitable[Any]] = [db.run(Phony(t), db=db) for t in target_strs]
     with db.persistent_history():
         results = await asyncio.gather(*jobs)
 
@@ -35,8 +36,7 @@ async def main(target_strs: list[str], force_run: bool, throttle: Optional[int])
 @argh.arg("targets", nargs="+", help="name of target to run")
 @argh.arg("-B", "--force-run", help="rebuild all dependencies")
 @argh.arg("-j", "--throttle", help="limit number of concurrent jobs")
-def brei(targets: list[str], *, force_run: bool = False, throttle: Optional[int] = None):
+def brei(targets: list[str], *, force_run: bool = False, throttle: int | None = None):
     """Build one of the configured targets."""
     config.read()
     asyncio.run(main(targets, force_run, throttle))
-

{entangled_cli-2.2.1 → entangled_cli-2.3.0}/entangled/commands/new.py

@@ -1,10 +1,9 @@
-from typing import Optional
-
 import argh  # type: ignore
+from argh.utils import get_subparsers
 import argparse
 
 from pathlib import Path
-from brei.cli import RichHelpFormatter
+from rich_argparse import RichHelpFormatter
 from rich.console import Console
 from rich.table import Table
 
@@ -45,7 +44,7 @@ def print_help() -> None:
     """
     parser = argparse.ArgumentParser(formatter_class=RichHelpFormatter)
     argh.add_commands(parser, [new], func_kwargs={"formatter_class": RichHelpFormatter})
-    argh.utils.get_subparsers(parser).choices["new"].print_help()
+    get_subparsers(parser).choices["new"].print_help()
 
 
 @argh.arg(
@@ -96,9 +95,9 @@ def print_help() -> None:
     help="Initialize a new project at this path",
 )
 def new(
-    template: Optional[str],
-    project_path: Optional[Path], *,
-    answers_file: Optional[str] = None,
+    template: str | None,
+    project_path: Path | None, *,
+    answers_file: str | None = None,
     data: str = "",
     defaults: bool = False,
     pretend: bool = False,
@@ -135,7 +134,7 @@ def new(
             copy_this_template = template_option.url
             break
 
-    data_dict: dict = {}
+    data_dict: dict[str, str] = {}
     if data:
         try:
             for d in data.split(";"):

entangled_cli-2.3.0/entangled/commands/reset.py

@@ -0,0 +1,62 @@
+"""
+The `reset` command resets the file database in `.entangled/filedb.json`.
+This database gets updated every time you tangle or stitch, but sometimes
+its contents may become invalid, for instance when switching branches.
+This command will read the markdown sources, then pretend to be tangling
+without actually writing out to source files.
+"""
+
+from ..io import TransactionMode, transaction
+from ..config import config, get_input_files
+from ..hooks import  get_hooks
+from ..document import ReferenceMap
+from ..errors.user import UserError
+
+import logging
+from pathlib import Path
+
+
+def reset():
+    """
+    Resets the database. This performs a tangle without actually writing
+    output to the files, but updating the database as if we were.
+    """
+    config.read()
+
+    # these imports depend on config being read
+    from ..markdown_reader import read_markdown_file
+    from ..tangle import tangle_ref
+
+    input_file_list = get_input_files()
+
+    refs = ReferenceMap()
+    hooks = get_hooks()
+    logging.debug("tangling with hooks: %s", [h.__module__ for h in hooks])
+    mode = TransactionMode.RESETDB
+    annotation_method = config.get.annotation
+
+    try:
+        with transaction(mode) as t:
+            for path in input_file_list:
+                logging.debug("reading `%s`", path)
+                t.update(path)
+                _, _ = read_markdown_file(path, refs=refs, hooks=hooks)
+
+            for h in hooks:
+                h.pre_tangle(refs)
+
+            for tgt in refs.targets:
+                result, deps = tangle_ref(refs, tgt, annotation_method)
+                mask = next(iter(refs.by_name(tgt))).mode
+                t.write(Path(tgt), result, list(map(Path, deps)), mask)
+
+            for h in hooks:
+                h.on_tangle(t, refs)
+
+            t.clear_orphans()
+
+        for h in hooks:
+            h.post_tangle(refs)
+
+    except UserError as e:
+        logging.error(str(e))

{entangled_cli-2.2.1 → entangled_cli-2.3.0}/entangled/commands/status.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
-from typing import Iterable
-from ..status import find_watch_dirs, list_input_files, list_dependent_files
+from collections.abc import Iterable
+from ..status import list_input_files, list_dependent_files
 from ..config import config
 from pathlib import Path
 
@@ -10,6 +10,7 @@ from rich.table import Table
 from rich.panel import Panel
 from rich.tree import Tree
 
+
 def tree_from_files(files: Iterable[Path]):
     tree = Tree(label=".")
     dirs = {Path("."): tree}
@@ -17,13 +18,15 @@ def tree_from_files(files: Iterable[Path]):
         for p in reversed(f.parents):
             if p not in dirs:
                 dirs[p] = dirs[p.parent].add(p.name, style="repr.path")
-        dirs[f.parent].add(f.name, style="repr.filename")
+        _ = dirs[f.parent].add(f.name, style="repr.filename")
     return tree
 
+
 def files_panel(file_list: Iterable[Path], title: str) -> Panel:
     tree = tree_from_files(file_list)
     return Panel(tree, title=title, border_style="dark_cyan")
 
+
 def rich_status():
     config_table = Table()
     config_table.add_column("name")

{entangled_cli-2.2.1 → entangled_cli-2.3.0}/entangled/commands/stitch.py

@@ -6,9 +6,9 @@ import argh  # type: ignore
 
 from ..config import config
 from ..document import ReferenceMap, Content, PlainText, ReferenceId
-from ..transaction import transaction, TransactionMode
+from ..io import transaction, TransactionMode
 from ..errors.user import UserError
-from .tangle import get_input_files
+from ..config import get_input_files
 
 
 def stitch_markdown(reference_map: ReferenceMap, content: list[Content]) -> str:
@@ -52,7 +52,7 @@ def stitch(*, force: bool = False, show: bool = False):
             content[path] = c
 
         with transaction(mode) as t:
-            for path in t.db.managed:
+            for path in t.db.managed_files:
                 logging.debug("reading `%s`", path)
                 t.update(path)
                 with open(path, "r") as f:

{entangled_cli-2.2.1 → entangled_cli-2.3.0}/entangled/commands/sync.py

@@ -4,7 +4,7 @@ from pathlib import Path
 
 import logging
 
-from ..filedb import file_db
+from ..io import filedb, FileCache
 from ..config import config
 from .stitch import stitch, get_input_files
 from .tangle import tangle
@@ -15,11 +15,12 @@ def _stitch_then_tangle():
     tangle()
 
 
-def sync_action() -> Optional[Callable[[], None]]:
+def sync_action() -> Callable[[], None] | None:
     input_file_list = get_input_files()
+    fs = FileCache()
 
-    with file_db(readonly=True) as db:
-        changed = set(db.changed())
+    with filedb(readonly=True) as db:
+        changed = set(db.changed_files(fs))
 
         if not all(f in db for f in input_file_list):
             return tangle
@@ -27,17 +28,17 @@ def sync_action() -> Optional[Callable[[], None]]:
         if not changed:
             return None
 
-        if changed.isdisjoint(db.managed):
+        if changed.isdisjoint(db.managed_files):
             logging.info("Tangling")
             return tangle
 
-        if changed.issubset(db.managed):
+        if changed.issubset(db.managed_files):
             logging.info("Stitching")
             return _stitch_then_tangle
 
         logging.error("changed: %s", [str(p) for p in changed])
         logging.error(
-            "Both markdown and code seem to have changed. " "Don't know what to do now."
+            "Both markdown and code seem to have changed, don't know what to do now."
         )
         return None
 

{entangled_cli-2.2.1 → entangled_cli-2.3.0}/entangled/commands/tangle.py

@@ -1,25 +1,15 @@
-from itertools import chain
 from pathlib import Path
 
 import argh  # type: ignore
 import logging
 
 from ..document import ReferenceMap
-from ..config import config, AnnotationMethod
-from ..transaction import transaction, TransactionMode
+from ..config import config, AnnotationMethod, get_input_files
+from ..io import transaction, TransactionMode
 from ..hooks import get_hooks
 from ..errors.user import UserError
 
 
-def get_input_files() -> list[Path]:
-    include_file_list = chain.from_iterable(map(Path(".").glob, config.get.watch_list))
-    input_file_list = [
-        path for path in include_file_list
-        if not any(path.match(pat) for pat in config.get.ignore_list)
-    ]
-    return input_file_list
-
-
 @argh.arg(
     "-a",
     "--annotate",
@@ -62,7 +52,7 @@ def tangle(*, annotate: str | None = None, force: bool = False, show: bool = Fal
             for path in input_file_list:
                 logging.debug("reading `%s`", path)
                 t.update(path)
-                read_markdown_file(path, refs=refs, hooks=hooks)
+                _, _ = read_markdown_file(path, refs=refs, hooks=hooks)
 
             for h in hooks:
                 h.pre_tangle(refs)

{entangled_cli-2.2.1 → entangled_cli-2.3.0}/entangled/config/__init__.py

@@ -11,6 +11,7 @@ from copy import copy, deepcopy
 from enum import StrEnum
 from pathlib import Path
 from typing import Any
+from itertools import chain
 
 import msgspec
 from msgspec import Struct, field
@@ -86,7 +87,7 @@ class Config(Struct, dict=True):
     annotation: AnnotationMethod = AnnotationMethod.STANDARD
     use_line_directives: bool = False
     hooks: list[str] = field(default_factory=lambda: ["shebang"])
-    hook: dict[str, Any] = field(default_factory=dict)
+    hook: dict[str, Any] = field(default_factory=dict)  # pyright: ignore[reportExplicitAny]
     brei: Program = field(default_factory=Program)
 
     language_index: dict[str, Language] = field(default_factory=dict)
@@ -126,10 +127,10 @@ def read_config_from_toml(
         return None
     try:
         with open(path, "rb") as f:
-            json: Any = tomllib.load(f)
+            json: Any = tomllib.load(f)  # pyright: ignore[reportExplicitAny]
             if section is not None:
                 for s in section.split("."):
-                    json = json[s]
+                    json = json[s]  # pyright: ignore[reportAny]
             return msgspec.convert(json, type=Config, dec_hook=from_str.dec_hook)
 
     except ValueError as e:
@@ -162,7 +163,7 @@ class ConfigWrapper(threading.local):
     @property
     def get(self) -> Config:
         if self.config is None:
-            raise ValueError(f"No config loaded.")
+            raise ValueError("No config loaded.")
         return self.config
 
     @contextmanager
@@ -179,10 +180,19 @@ class ConfigWrapper(threading.local):
 
     def get_language(self, lang_name: str) -> Language | None:
         if self.config is None:
-            raise ValueError(f"No config loaded.")
+            raise ValueError("No config loaded.")
         return self.config.language_index.get(lang_name, None)
 
 
 config = ConfigWrapper()
 """The `config.config` variable is changed when the `config` module is loaded.
 Config is read from `entangled.toml` file."""
+
+
+def get_input_files() -> list[Path]:
+    include_file_list = chain.from_iterable(map(Path(".").glob, config.get.watch_list))
+    input_file_list = [
+        path for path in include_file_list
+        if not any(path.match(pat) for pat in config.get.ignore_list)
+    ]
+    return sorted(input_file_list)

{entangled_cli-2.2.1 → entangled_cli-2.3.0}/entangled/document.py

@@ -125,8 +125,10 @@ def content_to_text(r: ReferenceMap, c: Content) -> str:
         A string, usually not terminated by a newline.
     """
     match c:
-        case PlainText(s): return s
-        case ReferenceId(): return r.get_codeblock(c).indented_text
+        case PlainText(s):
+            return s
+        case ReferenceId():
+            return r.get_codeblock(c).indented_text
 
 
 def document_to_text(r: ReferenceMap, cs: Iterable[Content]) -> str:

{entangled_cli-2.2.1 → entangled_cli-2.3.0}/entangled/hooks/base.py

@@ -3,7 +3,7 @@ from typing import override
 from msgspec import Struct
 
 from ..document import ReferenceMap, CodeBlock
-from ..transaction import Transaction
+from ..io import Transaction
 
 
 @dataclass
@@ -26,23 +26,23 @@ class HookBase:
         """When prerequisites aren't met, raise PrerequisitesFailed."""
         pass
 
-    def on_read(self, code: CodeBlock):
+    def on_read(self, code: CodeBlock):  # pyright: ignore[reportUnusedParameter]
         """Called when the Markdown is being read, before the assembling of
         the reference map."""
         pass
 
-    def pre_tangle(self, refs: ReferenceMap):
+    def pre_tangle(self, refs: ReferenceMap):  # pyright: ignore[reportUnusedParameter]
         """Executed after reading Markdown, but before actually tangling files.
         This allows the opportunity to add more targets to the reference map.
         """
         pass
 
-    def on_tangle(self, t: Transaction, refs: ReferenceMap):
+    def on_tangle(self, t: Transaction, refs: ReferenceMap):  # pyright: ignore[reportUnusedParameter]
         """Executed after other targets were tangled, but during the same
         transaction. If you want to write a file, consider doing so as part of
         the transaction."""
         pass
 
-    def post_tangle(self, refs: ReferenceMap):
+    def post_tangle(self, refs: ReferenceMap):  # pyright: ignore[reportUnusedParameter]
         """Called after the tangle transaction is finished."""
         pass

{entangled_cli-2.2.1 → entangled_cli-2.3.0}/entangled/hooks/build.py

@@ -97,7 +97,7 @@ class Hook(HookBase):
                 refs.index[script_file_name].append(ref)
                 refs.targets.add(script_file_name)
 
-            deps = (get_attribute(cb.properties, "deps") or "").split()
+            deps = [str(s) for s in (get_attribute(cb.properties, "deps") or "").split()]
             self.recipes.append(Hook.Recipe(target, deps, cb.language, script_file_name))
 
     @override

entangled_cli-2.3.0/entangled/hooks/quarto_attributes.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+import re
+import textwrap
+from typing import Any, final, override
+import yaml
+
+from entangled.config.language import Language
+
+from ..properties import Attribute, Class, Id, Property
+from ..document import CodeBlock
+from .base import HookBase
+from ..logging import logger
+
+
+log = logger()
+
+
+def split_yaml_header(language: Language, source: str) -> tuple[str, str, object]:
+    """Split source into YAML header and body."""
+    trigger = re.escape(language.comment.open) + r"\s*\|(.*)"
+    lines = source.splitlines()
+    header_lines: list[str] = []
+    body_start: int = 0
+
+    for i, line in enumerate(lines):
+        if m := re.match(trigger, line):
+            header_lines.append(m.group(1))
+            continue
+
+        body_start = i
+        break
+
+    return "\n".join(lines[:body_start]), "\n".join(lines[body_start:]), yaml.safe_load("\n".join(header_lines))
+
+
+def amend_code_properties(code_block: CodeBlock):
+    language = code_block.language
+    if not language:
+        return
+
+    source = code_block.source
+    props: list[Property] = []
+
+    header, body, attrs = split_yaml_header(language, source)
+
+    if attrs is None:
+        return
+
+    if not isinstance(attrs, dict):
+        log.warning(f"{code_block.origin}: Quarto attributes do not evaluate to dictionary; skipping")
+        log.warning(f"tried to parse:\n{header}")
+        return
+
+    if "id" in attrs.keys():
+        if not isinstance(attrs["id"], str):
+            log.warning(f"{code_block.origin}: Quarto id does not evaluate to string; skipping")
+            log.warning(f"tried to parse:\n{header}")
+            return
+        props.append(Id(attrs["id"]))
+
+    if "classes" in attrs.keys():
+        classes = attrs["classes"]
+        if not all(isinstance(c, str) for c in classes):
+            log.warning(f"{code_block.origin}: Quarto classes do not evaluate to strings; skipping")
+            log.warning(f"tried to parse:\n{header}")
+            return
+        props.extend(Class(c) for c in classes)
+
+    props.extend(Attribute(str(k), v) for k, v in attrs.items()
+                 if k not in ("id", "classes"))
+
+    code_block.source = body
+    code_block.open_line += "\n" + header
+    code_block.properties.extend(props)
+
+
+@final
+class Hook(HookBase):
+    def __init__(self, config: Hook.Config):
+        super().__init__(config)
+        self.config = config
+
+    @override
+    def on_read(self, code: CodeBlock):
+        log.debug("quarto filter: %s", code)
+        amend_code_properties(code)

{entangled_cli-2.2.1 → entangled_cli-2.3.0}/entangled/hooks/repl.py

@@ -10,7 +10,7 @@ from msgspec import Struct, field
 from pathlib import Path
 
 from ..logging import logger
-from ..transaction import Transaction
+from ..io import Transaction
 from ..document import CodeBlock, ReferenceMap
 from ..properties import Class, get_attribute, get_id
 

{entangled_cli-2.2.1 → entangled_cli-2.3.0}/entangled/hooks/task.py

@@ -6,7 +6,7 @@ from pathlib import Path
 from typing import Any, final, override
 
 from ..config import AnnotationMethod
-from ..transaction import Transaction
+from ..io import Transaction
 
 from ..document import CodeBlock, ReferenceId, ReferenceMap
 from ..properties import Class, Property, get_attribute, get_classes

entangled_cli-2.3.0/entangled/io/__init__.py

@@ -0,0 +1,11 @@
+"""
+In Entangled all file IO should pass through a transaction.
+"""
+
+
+from .transaction import transaction, Transaction, TransactionMode
+from .filedb import filedb
+from .virtual import FileCache
+
+
+__all__ = ["FileCache", "filedb", "Transaction", "TransactionMode", "transaction"]

entangled_cli-2.3.0/entangled/io/filedb.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+from collections.abc import Generator
+from contextlib import contextmanager
+import json
+from pathlib import Path
+from typing import Any
+
+import msgspec
+from msgspec import Struct
+
+import logging
+
+from filelock import FileLock
+
+from entangled.errors.user import HelpfulUserError
+
+from ..version import __version__
+from ..utility import normal_relative, ensure_parent
+from .virtual import FileCache
+from .stat import Stat, hexdigest
+
+
+class FileDB(Struct):
+    """Persistent storage for file stats of both Markdown and generated
+    files. We can use this to detect conflicts.
+
+    This data is stored in `.entangled/files.json`. It is recommended to
+    keep this file under version control. That way entangled shouldn't get
+    too confused when switching branches.
+
+    All files are stored in a single dictionary, the distinction between
+    source and target files is made in two separate indices."""
+
+    version: str
+    files: dict[str, Stat]
+    targets: set[str]
+
+    def clear(self):
+        self.files = {}
+        self.targets = set()
+
+    @property
+    def managed_files(self) -> set[Path]:
+        """List all managed files. These are files that can be reconstructed
+        from the sources, at least when things are in a consistent state.
+
+        For example: markdown sources cannot be reconstructed, so are not
+        listed here. However, generated code is first constructed from
+        the markdown, so is considered to be managed."""
+        return {Path(p) for p in self.targets}
+
+    def changed_files(self, fs: FileCache) -> Generator[Path]:
+        return (Path(p) for p, known_stat in self.files.items()
+                if fs[Path(p)].stat != known_stat)
+
+    def create_target(self, fs: FileCache, path: Path):
+        path = normal_relative(path)
+        self.update(fs, path)
+        self.targets.add(path.as_posix())
+
+    def update(self, fs: FileCache, path: Path):
+        path = normal_relative(path)
+        self.files[path.as_posix()] = fs[path].stat
+
+    def __contains__(self, path: Path) -> bool:
+        return path.as_posix() in self.files
+
+    def __getitem__(self, path: Path) -> Stat:
+        return self.files[path.as_posix()]
+
+    def __delitem__(self, path: Path):
+        path_str = path.as_posix()
+        if path_str in self.targets:
+            self.targets.remove(path_str)
+        del self.files[path_str]
+
+    def __iter__(self):
+        return (Path(p) for p in self.files)
+
+    def check(self, path: Path, content: str) -> bool:
+        return hexdigest(content) == self.files[path.as_posix()].hexdigest
+
+
+FILEDB_PATH =  Path(".") / ".entangled" / "filedb.json"
+FILEDB_LOCK_PATH = Path(".") / ".entangled" / "filedb.lock"
+
+
+def new_db() -> FileDB:
+    return FileDB(__version__, {}, set())
+
+
+def read_filedb() -> FileDB:
+    if not FILEDB_PATH.exists():
+        return new_db()
+
+    logging.debug("Reading FileDB")
+    raw: Any = json.load(open(FILEDB_PATH, "rb"))   # pyright: ignore[reportExplicitAny, reportAny]
+    if raw["version"] != __version__:
+        raise HelpfulUserError(
+            f"File database was created with a different version of Entangled ({raw["version"]}).\n" +
+            f"Run `entangled reset` to regenerate the database to version {__version__}.")
+
+    db = msgspec.convert(raw, type=FileDB)
+
+    undead = list(filter(lambda p: not p.exists(), db))
+    for path in undead:
+        logging.warning(f"undead file `{path}` (found in db but not on drive)")
+
+    return db
+
+
+def write_filedb(db: FileDB):
+    logging.debug("Writing FileDB")
+    _ = FILEDB_PATH.open("wb").write(msgspec.json.encode(db, order="sorted"))
+
+
+@contextmanager
+def filedb(readonly: bool = False, writeonly: bool = False):
+    lock = FileLock(ensure_parent(FILEDB_LOCK_PATH))
+    with lock:
+        db = read_filedb() if not writeonly else new_db()
+        yield db
+        if not readonly:
+            write_filedb(db)