entangled-cli 2.3.2__tar.gz → 2.4.2__tar.gz

{entangled_cli-2.3.2 → entangled_cli-2.4.2}/.gitignore

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

{entangled_cli-2.3.2 → entangled_cli-2.4.2}/PKG-INFO

@@ -1,26 +1,26 @@
 Metadata-Version: 2.4
 Name: entangled-cli
-Version: 2.3.2
+Version: 2.4.2
 Summary: Literate Programming toolbox
 Project-URL: Homepage, https://entangled.github.io/
 Project-URL: Repository, https://github.com/entangled/entangled.py
 Author-email: Johan Hidding <j.hidding@esciencecenter.nl>
 License-Expression: Apache-2.0
 License-File: LICENSE
-Requires-Python: <4,>=3.12
-Requires-Dist: argh<0.31,>=0.30
+Requires-Python: <4,>=3.13
 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: pexpect<5,>=4.9.0
+Requires-Dist: msgspec>=0.20.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<14,>=13.3.5
+Requires-Dist: rich-click>=1.9.4
+Requires-Dist: rich<15,>=13
 Requires-Dist: tomlkit<0.13,>=0.12.1
-Requires-Dist: watchdog>=6.0.0
+Requires-Dist: typeguard>=4.4.4
+Requires-Dist: watchfiles>=1.1.1
 Description-Content-Type: text/markdown
 
 # Entangled

{entangled_cli-2.3.2 → entangled_cli-2.4.2}/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.2 → entangled_cli-2.4.2}/entangled/commands/brei.py

@@ -1,22 +1,26 @@
 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 ..io import FileCache
 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(FileCache())
+    db = await resolve_tasks(cfg.brei, Path(".entangled/brei_history"))
     if throttle:
         db.throttle = asyncio.Semaphore(throttle)
     db.force_run = force_run
@@ -33,10 +37,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.2/entangled/commands/main.py

@@ -0,0 +1,23 @@
+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().info(f"Welcome to Entangled v{__version__}!")

{entangled_cli-2.3.2 → entangled_cli-2.4.2}/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.2/entangled/commands/reset.py

@@ -0,0 +1,20 @@
+"""
+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
+from .main import main
+from .tangle import do_tangle
+
+
+@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.
+    """
+    do_tangle(mode=TransactionMode.RESETDB)

{entangled_cli-2.3.2 → entangled_cli-2.4.2}/entangled/commands/status.py

@@ -1,7 +1,8 @@
 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 ..io import FileCache
 from pathlib import Path
 
 from rich.console import Console, Group
@@ -10,6 +11,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 +31,25 @@ def files_panel(file_list: Iterable[Path], title: str) -> Panel:
 
 
 def rich_status():
+    fs = FileCache()
+    cfg = Config() | read_config(fs)
     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(fs, cfg), "input files"),
                 files_panel(list_dependent_files(), "dependent files"),
             ]
         ),
@@ -53,6 +58,7 @@ def rich_status():
     console.print(group)
 
 
+@main.command()
 def status():
-    config.read()
+    """Print a status overview."""
     rich_status()

entangled_cli-2.4.2/entangled/commands/stitch.py

@@ -0,0 +1,27 @@
+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
+
+    doc = Document()
+
+    with transaction(mode) as t:
+        doc.load(t)
+        doc.load_all_code(t)
+        doc.stitch(t)

entangled_cli-2.4.2/entangled/commands/sync.py

@@ -0,0 +1,81 @@
+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()
+
+    with filedb(readonly=True, fs=doc.context.fs) as db:
+        changed = set(db.changed_files(doc.context.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():
+    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
+
+
+@main.command()
+def sync():
+    """Be smart wether to tangle or stich"""
+    run_sync()

entangled_cli-2.4.2/entangled/commands/tangle.py

@@ -0,0 +1,48 @@
+import rich_click as click
+
+from .main import main
+
+from ..config import AnnotationMethod, Config
+from ..io import AbstractFileCache, FileCache, transaction, TransactionMode
+from ..errors.user import UserError
+from ..interface import Context, 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):
+    if show:
+        mode = TransactionMode.SHOW
+    elif force:
+        mode = TransactionMode.FORCE
+    else:
+        mode = TransactionMode.FAIL
+
+    do_tangle(annotate=annotate, mode=mode, skip_post_tangle=False)
+
+
+def do_tangle(*,
+    annotate: AnnotationMethod | None = None,
+    mode: TransactionMode = TransactionMode.FAIL,
+    fs: AbstractFileCache | None = None,
+    skip_post_tangle: bool = True):
+    """Tangle codes from the documentation."""
+
+    if fs is None:
+        fs = FileCache()
+
+    doc = Document(context=Context(fs=fs))
+
+    with transaction(mode, fs=fs) as t:
+        doc.load(t)
+        doc.tangle(t, annotate)
+        t.clear_orphans()
+
+    if skip_post_tangle:
+        return
+
+    for h in doc.context.all_hooks:
+        h.post_tangle(doc.reference_map)

entangled_cli-2.4.2/entangled/commands/watch.py

@@ -0,0 +1,47 @@
+from threading import Event
+from pathlib import Path
+
+from ..status import find_watch_dirs
+from ..logging import logger
+
+from .sync import run_sync
+from .main import main
+
+import watchfiles
+
+
+log = logger()
+
+
+def watch_filter(change: watchfiles.Change, path: str) -> bool:
+    if Path(path).relative_to(Path.cwd()).as_posix().startswith(".entangled"):
+        return False
+    return True
+
+
+def _watch(_stop_event: Event | None = None, _start_event: Event | None = None):
+    """Keep a loop running, watching for changes. This interface is separated
+    from the CLI one, so that it can be tested using threading instead of
+    subprocess."""
+
+    def stop() -> bool:
+        return _stop_event is not None and _stop_event.is_set()
+
+    log.debug("Running daemon")
+    run_sync()
+
+    if _start_event is not None:
+        log.debug("Setting start event")
+        _start_event.set()
+
+    dirs = "."  # find_watch_dirs()
+
+    for changes in watchfiles.watch(dirs, stop_event=_stop_event, watch_filter=watch_filter):
+        log.debug(changes)
+        run_sync()
+
+
+@main.command()
+def watch():
+    """Keep a loop running, watching for changes."""
+    _watch()

entangled_cli-2.4.2/entangled/config/__init__.py

@@ -0,0 +1,93 @@
+"""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
+from ..io import AbstractFileCache
+
+log = logger()
+
+
+def read_config_from_toml(
+    fs: AbstractFileCache, 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 path not in fs:
+        return None
+    try:
+        content = fs[path].content
+        json: Any = tomllib.loads(content)
+        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(fs: AbstractFileCache) -> ConfigUpdate | None:
+    """
+    Read configuration from any of the possible hard-coded locations:
+
+    - `./entangled.toml`
+    - `./pyproject.toml` section `[tool.entangled]`.
+
+    Returns a `ConfigUpdate` or `None`. To get the full `Config` object,
+    run `Config() | read_config(fs)`.
+    """
+    if Path("./entangled.toml") in fs:
+        return read_config_from_toml(fs, Path("./entangled.toml"))
+    if Path("./pyproject.toml") in fs:
+        return (
+            read_config_from_toml(fs, Path("./pyproject.toml"), "tool.entangled")
+        )
+    return None
+
+
+def get_input_files(fs: AbstractFileCache, cfg: Config) -> list[Path]:
+    """
+    Get a sorted list of all input files for this project.
+    """
+    log.debug("watch list: %s; ignoring: %s", cfg.watch_list, cfg.ignore_list)
+    input_file_list = sorted(filter(
+        lambda p: not any(p.match(pat) for pat in cfg.ignore_list),
+        chain.from_iterable(map(fs.glob, cfg.watch_list))))
+    log.debug("input file list %s", input_file_list)
+    return input_file_list
+
+
+__all__ = ["Config", "ConfigUpdate", "AnnotationMethod", "Markers", "NamespaceDefault"]

entangled_cli-2.4.2/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"