entangled-cli 2.3.1__tar.gz → 2.4.0__tar.gz

{entangled_cli-2.3.1 → entangled_cli-2.4.0}/.gitignore

@@ -4,3 +4,4 @@ __pycache__
 coverage.*
 dist
 site
+

{entangled_cli-2.3.1 → entangled_cli-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: entangled-cli
-Version: 2.3.1
+Version: 2.4.0
 Summary: Literate Programming toolbox
 Project-URL: Homepage, https://entangled.github.io/
 Project-URL: Repository, https://github.com/entangled/entangled.py
@@ -10,17 +10,20 @@ License-File: LICENSE
 Requires-Python: <4,>=3.12
 Requires-Dist: argh<0.31,>=0.30
 Requires-Dist: brei<0.3,>=0.2.3
+Requires-Dist: click>=8.3.0
 Requires-Dist: copier<10,>=9
 Requires-Dist: filelock<4,>=3.12.0
 Requires-Dist: mawk<0.2,>=0.1.7
-Requires-Dist: msgspec>=0.19.0
+Requires-Dist: msgspec>=0.20.0
 Requires-Dist: pexpect<5,>=4.9.0
 Requires-Dist: pyyaml<7,>=6.0.1
 Requires-Dist: repl-session>=0.2.0
 Requires-Dist: rich-argparse<2,>=1.4.0
+Requires-Dist: rich-click>=1.9.4
 Requires-Dist: rich<14,>=13.3.5
 Requires-Dist: tomlkit<0.13,>=0.12.1
-Requires-Dist: watchdog<4,>=3.0.0
+Requires-Dist: typeguard>=4.4.4
+Requires-Dist: watchdog>=6.0.0
 Description-Content-Type: text/markdown
 
 # Entangled

{entangled_cli-2.3.1 → entangled_cli-2.4.0}/entangled/commands/__init__.py

@@ -1,19 +1,13 @@
-from .new import new
-from .status import status
+from .main import main
 from .stitch import stitch
-from .sync import sync
 from .tangle import tangle
+from .new import new
 from .reset import reset
+from .sync import sync
 from .watch import watch
+from .status import status
 from .brei import brei
 
 __all__ = [
-    "new",
-    "brei",
-    "reset",
-    "status",
-    "stitch",
-    "sync",
-    "tangle",
-    "watch",
+    "main", "stitch", "tangle", "new", "reset", "sync", "watch", "status", "brei"
 ]

{entangled_cli-2.3.1 → entangled_cli-2.4.0}/entangled/commands/brei.py

@@ -1,22 +1,25 @@
 from pathlib import Path
 from collections.abc import Awaitable
 from typing import Any
-import argh  # type: ignore
 import asyncio
 import textwrap
 
-from ..config import config
+from ..config import Config, read_config
 from brei import resolve_tasks, Phony
 from ..logging import logger
+from .main import main
+
+import click
 
 log = logger()
 
 
-async def main(target_strs: list[str], force_run: bool, throttle: int | None):
+async def brei_main(target_strs: list[str], force_run: bool, throttle: int | None):
     if not Path(".entangled").exists():
         Path(".entangled").mkdir()
 
-    db = await resolve_tasks(config.get.brei, Path(".entangled/brei_history"))
+    cfg = Config() | read_config()
+    db = await resolve_tasks(cfg.brei, Path(".entangled/brei_history"))
     if throttle:
         db.throttle = asyncio.Semaphore(throttle)
     db.force_run = force_run
@@ -33,10 +36,13 @@ async def main(target_strs: list[str], force_run: bool, throttle: int | None):
                 log.error(msg)
 
 
-@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")
+@main.command()
+@click.argument("targets", nargs=-1)
+@click.option("-B", "--force-run", is_flag=True, help="rebuild all dependencies")
+@click.option("-j", "--throttle", is_flag=True, help="limit number of concurrent jobs")
 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))
+    """Build one of the configured targets.
+
+    TARGETS     Names of the targets to run.
+    """
+    asyncio.run(brei_main(targets, force_run, throttle))

entangled_cli-2.4.0/entangled/commands/main.py

@@ -0,0 +1,24 @@
+from ..logging import configure, logger
+from ..version import __version__
+
+import sys
+import rich_click as click
+
+
+@click.group(
+    invoke_without_command=True,
+    epilog="See https://entangled.github.io/ for more help and tutorials."
+)
+@click.rich_config({"commands_before_options": True, "theme": "nord-modern"})
+@click.option("-v", "--version", is_flag=True, help="Show version.")
+@click.option("-d", "--debug", is_flag=True, help="Enable debugging.")
+def main(version: bool = False, debug: bool = False):
+    """Your literate programming toolkit.
+    """
+    if version:
+        print(f"Entangled {__version__}")
+        sys.exit(0)
+
+    configure(debug)
+    logger().debug(f"Welcome to Entangled v{__version__}!")
+

{entangled_cli-2.3.1 → entangled_cli-2.4.0}/entangled/commands/new.py

@@ -1,13 +1,11 @@
-import argh  # type: ignore
-from argh.utils import get_subparsers
-import argparse
+import click
 
 from pathlib import Path
-from rich_argparse import RichHelpFormatter
 from rich.console import Console
 from rich.table import Table
 
 from ..errors.user import HelpfulUserError
+from .main import main
 
 description = """Create a new entangled project from a template.
 
@@ -42,61 +40,52 @@ def print_help() -> None:
     For this we first have to create a parser and attach this `new` function
     to it. Then we have a parser object that we can `print_help()` from.
     """
-    parser = argparse.ArgumentParser(formatter_class=RichHelpFormatter)
-    argh.add_commands(parser, [new], func_kwargs={"formatter_class": RichHelpFormatter})
-    get_subparsers(parser).choices["new"].print_help()
+    ctx = click.get_current_context()
+    click.echo(ctx.get_help())
+    ctx.exit()
 
 
-@argh.arg(
-    "-a",
-    "--answers-file",
+@main.command(
+    epilog="This command, and the options provided are a front-end for `copier`. " +
+           "See https://copier.readthedocs.io/en/stable/ for more information."
+)
+@click.option(
+    "-a", "--answers-file",
     help="Update using this path (relative to [project_path]) to find the answers file for `copier`",
 )
-@argh.arg(
-    "-d",
-    "--data",
+@click.option(
+    "-d", "--data",
     help='"VARIABLE1=VALUE1;VARIABLE1=VALUE2" Make VARIABLEs available as VALUEs when rendering the template; make sure to use quotation marks for multiple variables/values',
 )
-@argh.arg(
-    "-D",
-    "--defaults",
+@click.option(
+    "-D", "--defaults", is_flag=True,
     help="Use default answers to questions, which might be null if not specified; overwrites when combined with -d!",
 )
-@argh.arg(
-    "-p",
-    "--pretend",
+@click.option(
+    "-p", "--pretend", is_flag=True,
     help="Run but do not make any changes",
 )
-@argh.arg(
-    "-o",
-    "--overwrite",
+@click.option(
+    "-o", "--overwrite", is_flag=True,
     help="Overwrite files that already exist, without asking.",
 )
-@argh.arg(
-    "-l",
-    "--list-templates",
+@click.option(
+    "-l", "--list-templates", is_flag=True,
     help="List all official templates and exit",
 )
-@argh.arg(
-    "-t",
-    "--trust",
+@click.option(
+    "-t", "--trust", is_flag=True,
     help='Allow templates with unsafe features (Jinja extensions, migrations, tasks); "True" for officially supported templates',
 )
-@argh.arg(
-    "template",
-    # default=None,
-    nargs="?",
-    help="Template handle or URL; initialize a new project from this template",
+@click.argument(
+    "template"
 )
-@argh.arg(
-    "project-path",
-    # default=None,
-    nargs="?",
-    help="Initialize a new project at this path",
+@click.argument(
+    "project-path"
 )
 def new(
-    template: str | None,
-    project_path: Path | None, *,
+    template: str,
+    project_path: Path, *,
     answers_file: str | None = None,
     data: str = "",
     defaults: bool = False,
@@ -105,7 +94,12 @@ def new(
     list_templates: bool = False,
     trust: bool = False,
 ) -> None:
-    """Create a new entangled project from a template."""
+    """Create a new entangled project from a template.
+
+    TEMPLATE      Template handle or URL; initialize a new project from this template.
+
+    PROJECT_PATH  Initialize a new project at this path.
+    """
 
     from ..config.templates import templates as AVAILABLE_TEMPLATES
     from ..config.templates import Template

entangled_cli-2.4.0/entangled/commands/reset.py

@@ -0,0 +1,34 @@
+"""
+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 ..errors.user import UserError
+from ..interface import Document
+from .main import main
+
+import logging
+
+
+@main.command(short_help="Reset the file database.")
+def reset():
+    """
+    Resets the file database. This performs a tangle without actually
+    writing output to the files, but updating the database as if we were.
+    """
+    
+    try:
+        doc = Document()
+        mode = TransactionMode.RESETDB
+
+        with transaction(mode) as t:
+            doc.load(t)
+            doc.tangle(t)
+            t.clear_orphans()
+
+    except UserError as e:
+        logging.error(str(e))

{entangled_cli-2.3.1 → entangled_cli-2.4.0}/entangled/commands/status.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 from collections.abc import Iterable
-from ..status import list_input_files, list_dependent_files
-from ..config import config
+from ..status import list_dependent_files
+from ..config import Config, read_config, get_input_files
 from pathlib import Path
 
 from rich.console import Console, Group
@@ -10,6 +10,8 @@ from rich.table import Table
 from rich.panel import Panel
 from rich.tree import Tree
 
+from .main import main
+
 
 def tree_from_files(files: Iterable[Path]):
     tree = Tree(label=".")
@@ -28,23 +30,24 @@ def files_panel(file_list: Iterable[Path], title: str) -> Panel:
 
 
 def rich_status():
+    cfg = Config() | read_config()
     config_table = Table()
     config_table.add_column("name")
     config_table.add_column("value")
     config_table.add_row(
-        "Watch list", ", ".join(f"'{pat}'" for pat in config.get.watch_list)
+        "Watch list", ", ".join(f"'{pat}'" for pat in cfg.watch_list)
     )
     config_table.add_row(
-        "Ignore list", ", ".join(f"'{pat}'" for pat in config.get.ignore_list)
+        "Ignore list", ", ".join(f"'{pat}'" for pat in cfg.ignore_list)
     )
-    config_table.add_row("Hooks enabled", ", ".join(config.get.hooks))
+    config_table.add_row("Hooks enabled", ", ".join(cfg.hooks))
 
     console = Console(color_system="auto")
     group = Group(
         Panel(config_table, title="config", border_style="dark_cyan"),
         Columns(
             [
-                files_panel(list_input_files(), "input files"),
+                files_panel(get_input_files(cfg), "input files"),
                 files_panel(list_dependent_files(), "dependent files"),
             ]
         ),
@@ -53,6 +56,7 @@ def rich_status():
     console.print(group)
 
 
+@main.command()
 def status():
-    config.read()
+    """Print a status overview."""
     rich_status()

entangled_cli-2.4.0/entangled/commands/stitch.py

@@ -0,0 +1,31 @@
+import rich_click as click
+
+from .main import main
+
+from ..interface import Document
+from ..io import transaction, TransactionMode
+from ..errors.user import UserError
+
+
+@main.command()
+@click.option("-f", "--force", is_flag=True, help="force overwrite on conflict")
+@click.option("-s", "--show", is_flag=True, help="only show, don't act")
+def stitch(*, force: bool = False, show: bool = False):
+    """Stitch code changes back into the documentation."""
+    if show:
+        mode = TransactionMode.SHOW
+    elif force:
+        mode = TransactionMode.FORCE
+    else:
+        mode = TransactionMode.FAIL
+
+    try:
+        doc = Document()
+
+        with transaction(mode) as t:
+            doc.load(t)
+            doc.load_all_code(t)
+            doc.stitch(t)
+
+    except UserError as e:
+        e.handle()

entangled_cli-2.4.0/entangled/commands/sync.py

@@ -0,0 +1,87 @@
+from enum import Enum
+
+from ..io import filedb, FileCache, transaction
+from ..interface import Document
+from ..errors.user import UserError
+
+from .main import main
+
+import logging
+
+
+class Action(Enum):
+    NOTHING = 0
+    TANGLE = 1
+    STITCH = 2
+
+
+def sync_action(doc: Document) -> Action:
+    input_file_list = doc.input_files()
+    fs = FileCache()
+
+    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 Action.TANGLE
+
+        if not changed:
+            return Action.NOTHING
+
+        if changed.isdisjoint(db.managed_files):
+            return Action.TANGLE
+
+        if changed.issubset(db.managed_files):
+            return Action.STITCH
+
+        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."
+        )
+        return Action.NOTHING
+
+
+def tangle(doc: Document):
+    with transaction() as t:
+        doc.load(t)
+        doc.tangle(t)
+        t.clear_orphans()
+        for h in doc.context.all_hooks:
+            h.post_tangle(doc.reference_map)
+
+
+def stitch(doc: Document):
+    with transaction() as t:
+        doc.load(t)
+        doc.load_all_code(t)
+        doc.stitch(t)
+    with transaction() as t:
+        doc.tangle(t)
+        for h in doc.context.all_hooks:
+            h.post_tangle(doc.reference_map)
+        
+
+def run_sync():
+    try:
+        doc = Document()
+        match sync_action(doc):
+            case Action.TANGLE:
+                logging.info("Tangling.")
+                tangle(doc)
+
+            case Action.STITCH:
+                logging.info("Stitching.")
+                stitch(doc)
+
+            case Action.NOTHING:
+                pass
+
+    except UserError as e:
+        e.handle()
+
+
+@main.command()
+def sync():
+    """Be smart wether to tangle or stich"""
+    run_sync()
+

entangled_cli-2.4.0/entangled/commands/tangle.py

@@ -0,0 +1,37 @@
+import rich_click as click
+
+from .main import main
+
+from ..config import AnnotationMethod
+from ..io import transaction, TransactionMode
+from ..errors.user import UserError
+from ..interface import Document
+
+
+@main.command()
+@click.option("-a", "--annotate", type=click.Choice(AnnotationMethod, case_sensitive=False),
+              help="annotation method")
+@click.option("-f", "--force", is_flag=True, help="force overwriting existing files")
+@click.option("-s", "--show", is_flag=True, help="only show what would happen")
+def tangle(*, annotate: AnnotationMethod | None = None, force: bool = False, show: bool = False):
+    """Tangle codes from the documentation."""
+    if show:
+        mode = TransactionMode.SHOW
+    elif force:
+        mode = TransactionMode.FORCE
+    else:
+        mode = TransactionMode.FAIL
+
+    try:
+        doc = Document()
+
+        with transaction(mode) as t:
+            doc.load(t)
+            doc.tangle(t, annotate)
+            t.clear_orphans()
+
+        for h in doc.context.all_hooks:
+            h.post_tangle(doc.reference_map)
+
+    except UserError as e:
+        e.handle()

{entangled_cli-2.3.1 → entangled_cli-2.4.0}/entangled/commands/watch.py

@@ -4,10 +4,11 @@ from threading import Event
 from watchdog.observers import Observer
 from watchdog.events import FileSystemEventHandler, FileSystemEvent
 
-from .sync import sync
-from ..config import config
 from ..status import find_watch_dirs
 
+from .sync import run_sync
+from .main import main
+
 
 class EventHandler(FileSystemEventHandler):
     def __init__(self):
@@ -19,12 +20,16 @@ class EventHandler(FileSystemEventHandler):
     def on_any_event(self, event: FileSystemEvent):
         if event.event_type == "opened":
             return
-        config.read()
-        path = Path(event.src_path)
+
+        if isinstance(event.src_path, bytes):
+            path = Path(event.src_path.decode("utf-8"))
+        else:
+            path = Path(event.src_path)
+
         if path.absolute().is_relative_to(Path("./.entangled").absolute()):
             return
         if any(path.absolute().is_relative_to(p.absolute()) for p in self.watched):
-            sync()
+            run_sync()
             # os.sync()
         self.update_watched()
 
@@ -37,7 +42,7 @@ def _watch(_stop_event: Event | None = None, _start_event: Event | None = None):
     def stop() -> bool:
         return _stop_event is not None and _stop_event.is_set()
 
-    sync()
+    run_sync()
 
     event_handler = EventHandler()
     observer = Observer()
@@ -55,7 +60,7 @@ def _watch(_stop_event: Event | None = None, _start_event: Event | None = None):
         observer.join()
 
 
+@main.command()
 def watch():
     """Keep a loop running, watching for changes."""
-    config.read()
     _watch()

entangled_cli-2.4.0/entangled/config/__init__.py

@@ -0,0 +1,83 @@
+"""Configuration. The variable `config` should be automatically populated with
+defaults and config loaded from `entangled.toml` in the work directory.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+from itertools import chain
+
+import msgspec
+import tomllib
+
+from .annotation_method import AnnotationMethod
+from .markers import Markers
+from .config_data import Config
+from .config_update import ConfigUpdate
+from .namespace_default import NamespaceDefault
+
+from ..logging import logger
+from ..version import __version__
+from ..errors.user import HelpfulUserError
+
+
+log = logger()
+
+
+def read_config_from_toml(
+    path: Path, section: str | None = None
+) -> ConfigUpdate | None:
+    """Read a config from given `path` in given `section`. The path should refer to
+    a TOML file that should decode to a `Config` object. If `section` is given, only
+    that section is decoded to a `Config` object. The `section` string may contain
+    periods to indicate deeper nesting.
+
+    Example:
+
+    ```python
+    read_config_from_toml(Path("./pyproject.toml"), "tool.entangled")
+    ```
+    """
+    if not path.exists():
+        return None
+    try:
+        with open(path, "rb") as f:
+            json: Any = tomllib.load(f)  # pyright: ignore[reportExplicitAny]
+            if section is not None:
+                for s in section.split("."):
+                    json = json[s]  # pyright: ignore[reportAny]
+            update = msgspec.convert(json, type=ConfigUpdate)
+            log.debug("Read config from `%s`", path)
+            return update
+
+    except (msgspec.ValidationError, tomllib.TOMLDecodeError) as e:
+        raise HelpfulUserError(f"Could not read config: {e}")
+    except KeyError as e:
+        log.debug("%s", str(e))
+        log.debug("The config file %s should contain a section %s", path, section)
+        return None
+
+
+def read_config() -> ConfigUpdate | None:
+    if Path("./entangled.toml").exists():
+        return read_config_from_toml(Path("./entangled.toml"))
+    if Path("./pyproject.toml").exists():
+        return (
+            read_config_from_toml(Path("./pyproject.toml"), "tool.entangled")
+        )
+    return None
+
+
+def get_input_files(cfg: Config) -> list[Path]:
+    log.debug("watch list: %s; ignoring: %s", cfg.watch_list, cfg.ignore_list)
+    include_file_list = chain.from_iterable(map(Path(".").glob, cfg.watch_list))
+    input_file_list = [
+        path for path in include_file_list
+        if not any(path.match(pat) for pat in cfg.ignore_list) and path.is_file()
+    ]
+    log.debug("input file list %s", input_file_list)
+    return sorted(input_file_list)
+
+
+__all__ = ["Config", "ConfigUpdate", "AnnotationMethod", "Markers", "NamespaceDefault"]

entangled_cli-2.4.0/entangled/config/annotation_method.py

@@ -0,0 +1,17 @@
+from enum import StrEnum
+
+
+class AnnotationMethod(StrEnum):
+    """Annotation methods.
+
+    - `STANDARD` is the default. Comments tell where a piece of code
+       came from in enough detail to reconstruct the markdown if some
+       of the code is changed.
+    - `NAKED` adds no comments to the tangled files. Stitching is not
+       possible with this setting.
+    - `SUPPLEMENTED` adds extra information to the comment lines.
+    """
+
+    STANDARD = "standard"
+    NAKED = "naked"
+    SUPPLEMENTED = "supplemented"