entangled-cli 2.4.3__tar.gz → 2.6.0__tar.gz

entangled_cli-2.4.3/README.md → entangled_cli-2.6.0/PKG-INFO

@@ -1,3 +1,30 @@
+Metadata-Version: 2.5
+Name: entangled-cli
+Version: 2.6.0
+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.13
+Requires-Dist: brei<0.3,>=0.2.3
+Requires-Dist: click>=8.3.0
+Requires-Dist: copier<10,>=9
+Requires-Dist: filelock<5,>=3.12.0
+Requires-Dist: msgspec>=0.20.0
+Requires-Dist: pyyaml<7,>=6.0.1
+Requires-Dist: repl-session>=0.3.0
+Requires-Dist: rich-argparse<2,>=1.4.0
+Requires-Dist: rich-click>=1.9.4
+Requires-Dist: rich<16,>=13
+Requires-Dist: tomlkit<0.16,>=0.12.1
+Requires-Dist: typeguard>=4.4.4
+Requires-Dist: watchfiles>=1.3
+Provides-Extra: jupyter
+Requires-Dist: repl-session[jupyter]>=0.3.0; extra == 'jupyter'
+Description-Content-Type: text/markdown
+
 # Entangled
 
 [![Upload Python Package](https://github.com/entangled/entangled.py/actions/workflows/deploy.yml/badge.svg)](https://github.com/entangled/entangled.py/actions/workflows/deploy.yml)
@@ -13,26 +40,28 @@ Literate programming was introduced by Donald Knuth in 1984 and has since then f
 We’re trying to increase the visibility of Entangled. If you like Entangled, please consider adding this badge [![Entangled badge](https://img.shields.io/badge/entangled-Use%20the%20source!-%2300aeff)](https://entangled.github.io/) to the appropriate location in your project:
 
 ```markdown
-[![Entangled badge](https://img.shields.io/badge/entangled-Use%20the%20source!-%2300aeff)](https://entangled.github.io/)
+[![Entangled badge](https://img.shields.io/badge/entangled-Use%19the%20source!-%2300aeff)](https://entangled.github.io/)
 ```
 
 ## Get started
 
-To install Entangled, all you need is a Python (version &ge;3.11) installation. If you use [`poetry`](https://python-poetry.org), and you start a new project,
+To install Entangled, all you need is a Python (version &ge;3.11) installation. If you use UV, and you start a new project,
 
 ```
-poetry init 
-poetry add entangled-cli
+uv init --bare
+uv add entangled-cli
 ```
 
-The `poetry init` command will create a `pyproject.toml` file and a virtual environment to install Python dependencies in. To activate the virtual environment, run `poetry shell` inside the project directory.
+The `uv init --bare` command will create a `pyproject.toml` file and a virtual environment to install Python dependencies in. To activate the virtual environment, run `. ./.venv/bin/activate` inside the project directory, or you can prepend commands with `uv run` to run them in the venv.
 
-Or, if you prefer plain old `pip`,
+Or, if you prefer plain old `pip`, or `pipx`,
 
 ```
-pip install entangled-cli
+pipx install entangled-cli
 ```
 
+Here, `pipx` creates a virtual environment for just the `entangled-cli` package.
+
 Or, if you prefer the nix package manager:
 
 ```
@@ -160,6 +189,13 @@ identifiers = ["java"]
 comment = { open = "//" }
 ```
 
+## Serving Rendered Pages
+Entangled v2.5 includes a auto-reloading web server. Suppose your documents are in `docs` and they are rendered to `site` with `make site`, you can run the live server like so:
+
+```shell
+entangled serve --watch docs --build 'entangled sync && make site' site
+```
+
 ## Working in VSCode
 The [EntangleD-VSCode](https://github.com/deephbz/entangled-vscode) extension provides code block navigation, reference&symbol search, NOWEB high-lighting functionalities.
 
@@ -431,6 +467,22 @@ You can use `${variable}` syntax inside Brei tasks just as you would in a stand-
 
 Entangled has been used successfully with the following document generators. Note that some of these examples were built using older versions of Entangled, but they should work just the same.
 
+### Weaving
+
+The `entangled weave` command transforms a Markdown document into Markdown that renders well in a documentation tool, by applying one or more filters to the code blocks:
+
+```shell
+entangled weave --list-filters                          # show available filters
+entangled weave docs/index.md                           # apply the `label` filter, print to stdout
+entangled weave -f title docs/index.md -o out/index.md  # MkDocs/pymdownx style titles
+```
+
+- `label` wraps each named code block in a `<div class="entangled-code-block">` with a label showing its name or target file. This renders in most Markdown previews (GitHub, Pandoc, Python-Markdown with `md_in_html`).
+- `title` adds a `title` attribute to the code block header, as understood by `pymdownx.superfences`.
+- `repl` inserts the results of a REPL session (see the `repl` hook) after each code block with the `repl` class. The results are read from the session file with its extension replaced by `.out.json`, e.g. `repl-session < session.json > session.out.json`. Text output becomes a `{.text .output}` code block; with the Jupyter backend, rich output (Markdown, HTML, SVG, PNG/JPEG) is included as well, with images embedded as data URIs. Set a `mime-type` attribute on the code block to choose a representation.
+
+Filters can be combined by repeating `-f`; they are applied in the given order. The same transformation is available from Python through `entangled.weave.transform_markdown`, so that documentation tools only need a thin adapter.
+
 ### Pandoc
 
 [Pandoc](https://pandoc.org/) is a very versatile tool for converting documents in any format. It specifically has very wide support for different forms of Markdown syntax out in the wild, including a filter system that lets you extend the workings of Pandoc. Those filters can be written in any language through an API, for instance Python filters can be written using `panflute`, but there is also native support for Lua.
@@ -496,7 +548,9 @@ This is a rewrite of Entangled in Python. Older versions were written in Haskell
 
 ## Contributing
 
-If you have an idea for improving Entangled, please file an issue before creating a pull request. Code in this repository is formatted using `black` and type checked using `mypy`.
+If you have an idea for improving Entangled, please file an issue before creating a pull request. Code in this repository is type checked using `mypy`. Within reasonable limits we adhere to PEP-8 code standards.
+
+Some parts of Entangled were developed with AI assistance. When you submit a PR, in interest of careful review, please make sure that you've pruned for needles changes.
 
 ## License
 

entangled_cli-2.4.3/PKG-INFO → entangled_cli-2.6.0/README.md

@@ -1,28 +1,3 @@
-Metadata-Version: 2.4
-Name: entangled-cli
-Version: 2.4.3
-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.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: 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-click>=1.9.4
-Requires-Dist: rich<15,>=13
-Requires-Dist: tomlkit<0.13,>=0.12.1
-Requires-Dist: typeguard>=4.4.4
-Requires-Dist: watchfiles>=1.1.1
-Description-Content-Type: text/markdown
-
 # Entangled
 
 [![Upload Python Package](https://github.com/entangled/entangled.py/actions/workflows/deploy.yml/badge.svg)](https://github.com/entangled/entangled.py/actions/workflows/deploy.yml)
@@ -38,26 +13,28 @@ Literate programming was introduced by Donald Knuth in 1984 and has since then f
 We’re trying to increase the visibility of Entangled. If you like Entangled, please consider adding this badge [![Entangled badge](https://img.shields.io/badge/entangled-Use%20the%20source!-%2300aeff)](https://entangled.github.io/) to the appropriate location in your project:
 
 ```markdown
-[![Entangled badge](https://img.shields.io/badge/entangled-Use%20the%20source!-%2300aeff)](https://entangled.github.io/)
+[![Entangled badge](https://img.shields.io/badge/entangled-Use%19the%20source!-%2300aeff)](https://entangled.github.io/)
 ```
 
 ## Get started
 
-To install Entangled, all you need is a Python (version &ge;3.11) installation. If you use [`poetry`](https://python-poetry.org), and you start a new project,
+To install Entangled, all you need is a Python (version &ge;3.11) installation. If you use UV, and you start a new project,
 
 ```
-poetry init 
-poetry add entangled-cli
+uv init --bare
+uv add entangled-cli
 ```
 
-The `poetry init` command will create a `pyproject.toml` file and a virtual environment to install Python dependencies in. To activate the virtual environment, run `poetry shell` inside the project directory.
+The `uv init --bare` command will create a `pyproject.toml` file and a virtual environment to install Python dependencies in. To activate the virtual environment, run `. ./.venv/bin/activate` inside the project directory, or you can prepend commands with `uv run` to run them in the venv.
 
-Or, if you prefer plain old `pip`,
+Or, if you prefer plain old `pip`, or `pipx`,
 
 ```
-pip install entangled-cli
+pipx install entangled-cli
 ```
 
+Here, `pipx` creates a virtual environment for just the `entangled-cli` package.
+
 Or, if you prefer the nix package manager:
 
 ```
@@ -185,6 +162,13 @@ identifiers = ["java"]
 comment = { open = "//" }
 ```
 
+## Serving Rendered Pages
+Entangled v2.5 includes a auto-reloading web server. Suppose your documents are in `docs` and they are rendered to `site` with `make site`, you can run the live server like so:
+
+```shell
+entangled serve --watch docs --build 'entangled sync && make site' site
+```
+
 ## Working in VSCode
 The [EntangleD-VSCode](https://github.com/deephbz/entangled-vscode) extension provides code block navigation, reference&symbol search, NOWEB high-lighting functionalities.
 
@@ -456,6 +440,22 @@ You can use `${variable}` syntax inside Brei tasks just as you would in a stand-
 
 Entangled has been used successfully with the following document generators. Note that some of these examples were built using older versions of Entangled, but they should work just the same.
 
+### Weaving
+
+The `entangled weave` command transforms a Markdown document into Markdown that renders well in a documentation tool, by applying one or more filters to the code blocks:
+
+```shell
+entangled weave --list-filters                          # show available filters
+entangled weave docs/index.md                           # apply the `label` filter, print to stdout
+entangled weave -f title docs/index.md -o out/index.md  # MkDocs/pymdownx style titles
+```
+
+- `label` wraps each named code block in a `<div class="entangled-code-block">` with a label showing its name or target file. This renders in most Markdown previews (GitHub, Pandoc, Python-Markdown with `md_in_html`).
+- `title` adds a `title` attribute to the code block header, as understood by `pymdownx.superfences`.
+- `repl` inserts the results of a REPL session (see the `repl` hook) after each code block with the `repl` class. The results are read from the session file with its extension replaced by `.out.json`, e.g. `repl-session < session.json > session.out.json`. Text output becomes a `{.text .output}` code block; with the Jupyter backend, rich output (Markdown, HTML, SVG, PNG/JPEG) is included as well, with images embedded as data URIs. Set a `mime-type` attribute on the code block to choose a representation.
+
+Filters can be combined by repeating `-f`; they are applied in the given order. The same transformation is available from Python through `entangled.weave.transform_markdown`, so that documentation tools only need a thin adapter.
+
 ### Pandoc
 
 [Pandoc](https://pandoc.org/) is a very versatile tool for converting documents in any format. It specifically has very wide support for different forms of Markdown syntax out in the wild, including a filter system that lets you extend the workings of Pandoc. Those filters can be written in any language through an API, for instance Python filters can be written using `panflute`, but there is also native support for Lua.
@@ -521,7 +521,9 @@ This is a rewrite of Entangled in Python. Older versions were written in Haskell
 
 ## Contributing
 
-If you have an idea for improving Entangled, please file an issue before creating a pull request. Code in this repository is formatted using `black` and type checked using `mypy`.
+If you have an idea for improving Entangled, please file an issue before creating a pull request. Code in this repository is type checked using `mypy`. Within reasonable limits we adhere to PEP-8 code standards.
+
+Some parts of Entangled were developed with AI assistance. When you submit a PR, in interest of careful review, please make sure that you've pruned for needles changes.
 
 ## License
 

{entangled_cli-2.4.3 → entangled_cli-2.6.0}/entangled/commands/__init__.py

@@ -7,7 +7,9 @@ from .sync import sync
 from .watch import watch
 from .status import status
 from .brei import brei
+from .serve import serve
+from .weave import weave
 
 __all__ = [
-    "main", "stitch", "tangle", "new", "reset", "sync", "watch", "status", "brei"
+    "main", "stitch", "tangle", "new", "reset", "sync", "watch", "status", "brei", "serve", "weave"
 ]

entangled_cli-2.6.0/entangled/commands/serve.py

@@ -0,0 +1,57 @@
+from ..server.server import Reloader, Handler
+from .main import main
+from ..logging import logger
+
+from functools import partial
+from pathlib import Path
+import subprocess
+import threading
+from http.server import ThreadingHTTPServer
+
+from watchfiles import watch
+import click
+
+
+def watch_site(site: Path, reloader: Reloader):
+    for changes in watch(site):
+        logger().info(f"[livereload] {len(changes)} change(s) in {site}, reloading")
+        reloader.trigger()
+
+
+def watch_sources(paths: list[Path], site: Path, build: str):
+    def is_source(_change, path: str) -> bool:
+        return not Path(path).resolve().is_relative_to(site.resolve())
+
+    for _ in watch(*paths, watch_filter=is_source):
+        logger().info(f"[livereload] sources changed, running: {build}")
+        subprocess.run(build, shell=True, check=False)
+
+
+@main.command()
+@click.argument("directory", type=Path, help="directory to serve")
+@click.option("-p", "--port", type=int, default=8000)
+@click.option("-b", "--bind", default="127.0.0.1")
+@click.option("--build", help="shell command to run when sources change")
+@click.option("-w", "--watch", type=Path, multiple=True, help="source paths for --build")
+def serve(directory: Path, port: int, bind: str, build: str | None = None, watch: list[Path] | None = None) -> None:
+    """Stand-alone webserver with browser auto-reloading."""
+    reloader = Reloader()
+    threading.Thread(
+        target=watch_site, args=(directory, reloader), daemon=True
+    ).start()
+    if build:
+        threading.Thread(
+            target=watch_sources,
+            args=(watch or [Path(".")], directory, build),
+            daemon=True,
+        ).start()
+
+    handler = partial(Handler, directory=str(directory))
+    Handler.reloader = reloader
+    with ThreadingHTTPServer((bind, port), handler) as server:
+        server.daemon_threads = True
+        logger().info(f"[livereload] serving {directory} at http://{bind}:{port}/")
+        try:
+            server.serve_forever()
+        except KeyboardInterrupt:
+            pass

entangled_cli-2.6.0/entangled/commands/weave.py

@@ -0,0 +1,50 @@
+from pathlib import Path, PurePath
+import sys
+
+import rich_click as click
+
+from .main import main
+
+from ..config import read_config
+from ..interface import Context
+from ..weave import filters, filter_description, transform_markdown
+
+
+def print_filters():
+    width = max(map(len, filters))
+    for name, f in filters.items():
+        print(f"{name:<{width}}  {filter_description(f)}")
+
+
+@main.command()
+@click.argument("input", type=click.Path(dir_okay=False, allow_dash=True, path_type=Path),
+                default="-")
+@click.option("-o", "--output", type=click.Path(dir_okay=False, allow_dash=True, path_type=Path),
+              default="-", help="output file, defaults to standard output")
+@click.option("-f", "--filter", "filter_names", type=click.Choice(list(filters)), multiple=True,
+              help="filter to apply, can be repeated; defaults to `label`")
+@click.option("--list-filters", is_flag=True, help="list available filters and exit")
+def weave(*, input: Path, output: Path, filter_names: tuple[str, ...] = (),
+          list_filters: bool = False):
+    """Transform Markdown for rendering by documentation tools."""
+    if list_filters:
+        print_filters()
+        return
+
+    context = Context()
+    context |= read_config(context.fs)
+
+    if input == Path("-"):
+        text = sys.stdin.read()
+        filename = PurePath("-")
+    else:
+        text = input.read_text()
+        filename = input
+
+    selected = [filters[n] for n in (filter_names or ("label",))]
+    result = "".join(transform_markdown(context, text, *selected, filename=filename))
+
+    if output == Path("-"):
+        _ = sys.stdout.write(result)
+    else:
+        _ = output.write_text(result)

{entangled_cli-2.4.3 → entangled_cli-2.6.0}/entangled/errors/user.py

@@ -73,3 +73,15 @@ class CodeAttributeError(UserError):
     @override
     def __str__(self) -> str:
         return f"{self.origin}: Attribute error: {self.msg}"
+
+
+@dataclass
+class StitchConflict(UserError):
+    reference: str
+    files: tuple[Path, Path]
+
+    @override
+    def __str__(self) -> str:
+        a, b = self.files
+        return (f"code block `{self.reference}` was changed differently in "
+                f"`{a}` and `{b}`; resolve this by hand")

{entangled_cli-2.4.3 → entangled_cli-2.6.0}/entangled/hooks/repl.py

@@ -6,7 +6,7 @@ import msgspec
 
 from entangled.config.language import Language
 from .base import HookBase
-from repl_session import ReplConfig, ReplSession, ReplCommand
+from repl_session import JupyterConfig, ReplConfig, ReplSession, ReplCommand
 from msgspec import Struct
 from pathlib import Path
 
@@ -18,6 +18,15 @@ from ..model.properties import Class, get_attribute, get_attribute_string, get_i
 
 log = logger()
 
+type BackendConfig = ReplConfig | JupyterConfig
+
+
+def backend_config(cfg: dict[str, object]) -> BackendConfig:
+    """Convert a REPL config, defaulting to the `repl` (pexpect) backend when
+    no `backend` is given."""
+    return msgspec.convert({"backend": "repl"} | cfg, type=BackendConfig)
+
+
 class Session(Struct):
     filename: Path
     language: str
@@ -35,7 +44,7 @@ def strip_comments(code: str, language: Language) -> str:
 @final
 class Hook(HookBase):
     class Config(HookBase.Config):
-        config: dict[str, ReplConfig] = msgspec.field(default_factory=dict)
+        config: dict[str, dict[str, object]] = msgspec.field(default_factory=dict)
 
     @dataclass
     class State(HookBase.State):
@@ -44,7 +53,8 @@ class Hook(HookBase):
     def __init__(self, config: Config, state: State):
         super().__init__(config, state)
         log.debug(f"REPL hook config: {config}")
-        self.config = config.config
+        self.config: dict[str, BackendConfig] = {
+            lang: backend_config(cfg) for lang, cfg in config.config.items()}
         self.sessions: dict[str, Session] = state.sessions
 
     @override

{entangled_cli-2.4.3 → entangled_cli-2.6.0}/entangled/interface/document.py

@@ -2,11 +2,12 @@ from dataclasses import dataclass, field
 from pathlib import PurePath, Path
 
 from ..config import Config, ConfigUpdate, get_input_files, read_config, AnnotationMethod
-from ..model import ReferenceMap, tangle_ref, Content, content_to_text
+from ..model import ReferenceMap, ReferenceId, tangle_ref, Content, content_to_text
 from ..io import AbstractFileCache, FileCache, Transaction
 from ..readers import code
 from ..iterators import numbered_lines, run_generator
 from ..logging import logger
+from ..errors.user import StitchConflict
 
 from .context import Context, markdown
 
@@ -65,18 +66,37 @@ class Document:
         t.update(path)
         return update
 
-    def load_code(self, t: Transaction, path: Path):
+    def load_code(self, t: Transaction, path: Path,
+                  loaded: dict[ReferenceId, Path] | None = None):
+        """Read code blocks back from a tangled file. If `loaded` is given, it
+        records which file each block was read from, so that a block that
+        was read before with different content raises a `StitchConflict`."""
         reader = code(numbered_lines(path, t.read(path)))
         for block in reader:
-            self.reference_map[block.reference_id].source = block.content
+            ref = block.reference_id
+            if loaded is not None:
+                if ref in loaded and self.reference_map[ref].source != block.content:
+                    raise StitchConflict(str(ref), (loaded[ref], path))
+                loaded[ref] = path
+            self.reference_map[ref].source = block.content
         t.update(path)
 
     def load_all_code(self, t: Transaction):
+        """Read code blocks back from all targets that changed since they were
+        tangled. Unchanged targets are skipped: they match the documentation,
+        and when they share a block with a changed target, reading them would
+        undo the change."""
         log.debug(f"Targets: {self.reference_map.targets()}")
+        loaded: dict[ReferenceId, Path] = {}
         for tgt in self.reference_map.targets():
+            path = Path(tgt)
+            if path not in t.fs:
+                continue
+            if path in t.db and t.fs[path].stat == t.db[path]:
+                log.debug(f"Skipping unchanged code: `{tgt}`")
+                continue
             log.debug(f"Reading code: `{tgt}`")
-            if Path(tgt) in t.fs:
-                self.load_code(t, Path(tgt))
+            self.load_code(t, path, loaded)
 
     def load(self, t: Transaction):
         files = get_input_files(t.fs, self.config)

{entangled_cli-2.4.3 → entangled_cli-2.6.0}/entangled/io/stat.py

@@ -12,10 +12,13 @@ import time
 
 
 def hexdigest(s: str) -> str:
-    """Creates a MD5 hash digest from a string. Before hashing, the string has
-    linefeed `\\r` characters and trailing newlines removed, and the string
-    is encoded as UTF-8."""
-    content = s.replace("\r", "").rstrip().encode()
+    """Creates a SHA-256 hash digest from a string. Before hashing, the string
+    has carriage return `\\r` characters, trailing white space on each line
+    and trailing newlines removed, and the string is encoded as UTF-8. This
+    way, changes in white space only, like the ones made by editors that
+    strip trailing white space on save, don't count as changes."""
+    lines = s.replace("\r", "").split("\n")
+    content = "\n".join(line.rstrip() for line in lines).rstrip().encode()
     return hashlib.sha256(content).hexdigest()
 
 

{entangled_cli-2.4.3 → entangled_cli-2.6.0}/entangled/logging.py

@@ -20,7 +20,7 @@ class WhitespaceStrippingConsole(Console):
         return "\n".join(line.rstrip() for line in rendered.splitlines()) + newline_char
 
 # Global rich console object
-console: Console = WhitespaceStrippingConsole()
+console: Console = WhitespaceStrippingConsole(stderr=True)
 
 def logger():
     return logging.getLogger("entangled")

{entangled_cli-2.4.3 → entangled_cli-2.6.0}/entangled/model/tangle.py

@@ -75,7 +75,9 @@ type Tangler = Callable[[Tangler, Deps, ReferenceId, bool, bool], Iterator[str]]
 
 
 def indent(prefix: str, g: Iterator[str]) -> Iterator[str]:
-    return map(lambda line: "" if not line else prefix + line, g)
+    """Indent lines with `prefix`. Blank lines are not indented, so that they
+    don't get trailing white space."""
+    return map(lambda line: prefix + line if line.strip() else line.lstrip(" \t"), g)
 
 
 def naked_tangler(refs: ReferenceMap) -> Tangler:

{entangled_cli-2.4.3 → entangled_cli-2.6.0}/entangled/readers/markdown.py

@@ -48,7 +48,11 @@ def code_block_guard(origin: TextLocation, open_match: re.Match[str], close_matc
 
 
 def dedent_line(location: TextLocation, indent: str, line: str):
-    if line.startswith(indent) or line.strip() == "":
+    # Blank lines lose all their white space, as they do when reading code
+    # back from a tangled file.
+    if line.strip() == "":
+        return line.lstrip(" \t")
+    if line.startswith(indent):
         return line.removeprefix(indent)
     raise IndentationError(location)
 

entangled_cli-2.6.0/entangled/server/server.py

@@ -0,0 +1,86 @@
+"""Minimal live-reloading static file server.
+
+Serves a directory over HTTP, injects a tiny script into every HTML page,
+and tells connected browsers to reload (via Server-Sent Events) whenever
+something in the served directory changes. Optionally runs a build command
+whenever source files change.
+
+Mostly generated by Claude Opus 5.5.
+"""
+
+import threading
+from pathlib import Path
+from http import HTTPStatus
+from http.server import SimpleHTTPRequestHandler
+
+
+EVENT_PATH = "/__livereload"
+SNIPPET = (
+    f'<script>new EventSource("{EVENT_PATH}")'
+    '.addEventListener("reload", () => location.reload());</script>'
+).encode()
+
+
+class Reloader:
+    """Generation counter that SSE handlers block on."""
+
+    def __init__(self):
+        self.generation = 0
+        self.cond = threading.Condition()
+
+    def trigger(self):
+        with self.cond:
+            self.generation += 1
+            self.cond.notify_all()
+
+    def wait(self, generation: int, timeout: float) -> int:
+        with self.cond:
+            self.cond.wait_for(lambda: self.generation != generation, timeout)
+            return self.generation
+
+
+class Handler(SimpleHTTPRequestHandler):
+    reloader: Reloader
+
+    def do_GET(self):
+        if self.path == EVENT_PATH:
+            return self.serve_events()
+        path = Path(self.translate_path(self.path))
+        if path.is_dir():
+            path = path / "index.html"
+        if path.suffix == ".html" and path.is_file():
+            return self.serve_html(path)
+        return super().do_GET()
+
+    def serve_html(self, path: Path):
+        body = path.read_bytes()
+        i = body.rfind(b"</body>")
+        body = body[:i] + SNIPPET + body[i:] if i >= 0 else body + SNIPPET
+        self.send_response(HTTPStatus.OK)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def serve_events(self):
+        self.send_response(HTTPStatus.OK)
+        self.send_header("Content-Type", "text/event-stream")
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        generation = self.reloader.generation
+        try:
+            while True:
+                new = self.reloader.wait(generation, timeout=15)
+                if new != generation:
+                    generation = new
+                    self.wfile.write(b"event: reload\ndata: \n\n")
+                else:
+                    self.wfile.write(b": keepalive\n\n")  # detects closed tabs
+                self.wfile.flush()
+        except (BrokenPipeError, ConnectionResetError):
+            pass
+
+    def log_message(self, format, *args):
+        if self.path != EVENT_PATH:
+            super().log_message(format, *args)

entangled_cli-2.6.0/entangled/weave/__init__.py

@@ -0,0 +1,9 @@
+from .base import (
+    ContentFilter, CodeBlockFilter, codeblock_filter, compose_filters, iter_bind, transform_markdown
+)
+from .filters import filters, filter_description, block_title
+
+__all__ = [
+    "ContentFilter", "CodeBlockFilter", "codeblock_filter", "compose_filters", "iter_bind",
+    "transform_markdown", "filters", "filter_description", "block_title"
+]

entangled_cli-2.6.0/entangled/weave/base.py

@@ -0,0 +1,66 @@
+"""
+Generic machinery for weaving: transforming the Markdown source of a page,
+code block by code block, into Markdown that renders well in some target.
+"""
+
+from collections.abc import Callable, Iterable, Iterator
+from functools import partial, reduce, wraps
+from itertools import chain
+from pathlib import PurePath
+
+from ..interface import Context, markdown
+from ..iterators import numbered_lines
+from ..model import Content, PlainText, ReferenceId, ReferenceMap, content_to_text
+
+
+type ContentFilter = Callable[[ReferenceMap, Content], Iterable[Content]]
+type CodeBlockFilter = Callable[[ReferenceMap, ReferenceId], Iterable[Content]]
+
+
+def codeblock_filter(f: CodeBlockFilter) -> ContentFilter:
+    """Lift a filter on code blocks to a filter on content, passing plain text
+    through unchanged."""
+    @wraps(f)
+    def _filter(rm: ReferenceMap, c: Content) -> Iterable[Content]:
+        match c:
+            case PlainText():
+                return [c]
+            case ReferenceId():
+                return f(rm, c)
+    return _filter
+
+
+def iter_bind[T, U](lst: Iterable[T], f: Callable[[T], Iterable[U]]) -> Iterator[U]:
+    return chain.from_iterable(map(f, lst))
+
+
+def compose_filter(a: ContentFilter, b: ContentFilter) -> ContentFilter:
+    def _joined(rm: ReferenceMap, c: Content) -> Iterable[Content]:
+        return iter_bind(a(rm, c), partial(b, rm))
+    return _joined
+
+
+def compose_filters(*args: ContentFilter) -> ContentFilter:
+    """Compose filters left to right: the first filter is applied first."""
+    identity: ContentFilter = lambda _, c: [c]
+    return reduce(compose_filter, args, identity)
+
+
+def transform_markdown(
+    context: Context,
+    text: str,
+    *filters: ContentFilter,
+    filename: PurePath = PurePath("-"),
+    reference_map: ReferenceMap | None = None,
+) -> Iterator[str]:
+    """
+    Read a Markdown document, pass its content through the given filters,
+    and yield the resulting Markdown text.
+
+    Filters may modify code blocks in the reference map in place. If no
+    `reference_map` is given, a fresh one is used for this document only.
+    """
+    refs = ReferenceMap() if reference_map is None else reference_map
+    content = markdown(context, refs, numbered_lines(filename, text))
+    for c in iter_bind(content, partial(compose_filters(*filters), refs)):
+        yield content_to_text(refs, c)[0]

entangled_cli-2.6.0/entangled/weave/filters.py

@@ -0,0 +1,235 @@
+"""
+Filters for `entangled weave`. Each filter is registered by name in `filters`;
+the first line of its docstring serves as description for `--list-filters`.
+"""
+
+from base64 import b64encode
+from functools import lru_cache
+from html import escape
+from io import StringIO
+from pathlib import Path
+from textwrap import indent
+import re
+
+import msgspec
+
+from repl_session import ReplCommand, ReplOutput, ReplSession, read_session
+
+from ..hooks.repl import strip_comments
+from ..logging import logger
+from ..model import CodeBlock, Content, PlainText, ReferenceId, ReferenceMap
+from ..model.properties import Attribute, Class, Id, get_attribute_string
+from .base import ContentFilter, codeblock_filter
+
+
+log = logger()
+
+
+def block_title(code_block: CodeBlock) -> str | None:
+    """Compute a human readable title for a code block from its id and `file`
+    attribute. Returns `None` for anonymous code blocks."""
+    ids = [p.value for p in code_block.properties if isinstance(p, Id)]
+    filenames = [p.value for p in code_block.properties  # pyright: ignore[reportAny]
+                 if isinstance(p, Attribute) and p.key == "file"]
+
+    if len(ids) > 1 or len(filenames) > 1:
+        return "error: ambiguous code block title"
+    if ids and filenames:
+        return f"#{ids[0]} / file: {filenames[0]}"
+    if ids:
+        return f"#{ids[0]}"
+    if filenames:
+        return f"file: {filenames[0]}"
+    return None
+
+
+def first_line(text: str) -> tuple[str, str]:
+    head, nl, rest = text.partition("\n")
+    return head, nl + rest
+
+
+@codeblock_filter
+def title(reference_map: ReferenceMap, r: ReferenceId) -> list[Content]:
+    """Add a `title` attribute to the code block header (MkDocs/pymdownx style)."""
+    code_block = reference_map[r]
+    text = block_title(code_block)
+    ids = [p.value for p in code_block.properties if isinstance(p, Id)]
+    classes = [p.value for p in code_block.properties if isinstance(p, Class)]
+
+    head, rest = first_line(code_block.open_line)
+    fence_match = re.match(r"\s*(`{3,}|~{3,})", head)
+    fence = fence_match.group(1) if fence_match else "```"
+
+    attrs: list[str] = []
+    if ids:
+        attrs.append(str(Id(ids[0])))
+    attrs.extend(str(Class(c)) for c in classes[1:])
+    if text:
+        attrs.append(str(Attribute("title", text)))
+
+    head = fence + (classes[0] if classes else "")
+    if attrs:
+        head += " {" + " ".join(attrs) + "}"
+
+    code_block.open_line = head + (rest or "\n")
+    return [r]
+
+
+@codeblock_filter
+def label(reference_map: ReferenceMap, r: ReferenceId) -> list[Content]:
+    """Wrap code blocks in a `<div>` with a label; renders in most Markdown previews."""
+    code_block = reference_map[r]
+    text = block_title(code_block)
+    if text is None:
+        return [r]
+
+    ind = code_block.indent
+    header = (f"{ind}<div class=\"entangled-code-block\" markdown=\"1\">\n"
+              f"{ind}<div class=\"entangled-code-title\"><code>{escape(text)}</code></div>\n\n")
+    # The closing fence may lack a newline at the end of a file. The blank
+    # lines around `</div>` end the HTML block in CommonMark.
+    eol = "" if code_block.close_line.endswith("\n") else "\n"
+    footer = f"{eol}\n{ind}</div>\n\n"
+    return [PlainText(header), r, PlainText(footer)]
+
+
+# Representations to pick from a MIME bundle, most preferred first.
+MIME_PRIORITY = [
+    "text/markdown", "text/html", "image/svg+xml", "image/png", "image/jpeg", "image/gif",
+    "text/plain",
+]
+
+
+def fenced(text: str, classes: list[str]) -> str:
+    """Put text in a fenced code block, with a fence longer than any backtick
+    run inside the text."""
+    longest = max((len(m) for m in re.findall(r"`+", text)), default=0)
+    fence = "`" * max(3, longest + 1)
+    attrs = " ".join(str(Class(c)) for c in classes)
+    return f"{fence} {{{attrs}}}\n{text}\n{fence}"
+
+
+def render_mime(mime: str, data: str, kind: str) -> str | None:
+    """Render a single representation as Markdown, or `None` if there is
+    nothing to show."""
+    match mime:
+        case "text/plain":
+            text = data.strip("\n")
+            if not text.strip():
+                return None
+            return fenced(text, ["text", "output"] + ([] if kind == "result" else [kind]))
+        case "text/markdown" | "text/html":
+            return data.strip("\n") or None
+        case "image/svg+xml":
+            return f"![](data:{mime};base64,{b64encode(data.encode()).decode()})"
+        case _ if mime.startswith("image/"):
+            return f"![](data:{mime};base64,{"".join(data.split())})"
+        case _:
+            return None
+
+
+def render_output(output: ReplOutput, output_type: str) -> str | None:
+    """Render the most preferred representation in an output's MIME bundle.
+    A `mime-type` set on the code block, other than the default `text/plain`,
+    takes precedence."""
+    preferred = [] if output_type == "text/plain" else [output_type]
+    for mime in [*preferred, *MIME_PRIORITY]:
+        if mime in output.data:
+            return render_mime(mime, output.data[mime], output.kind)
+    return None
+
+
+def command_outputs(command: ReplCommand) -> list[ReplOutput]:
+    """Outputs of a command; sessions from older versions of `repl-session`
+    only have the `output` field."""
+    if command.outputs is not None:
+        return command.outputs
+    if command.output is None:
+        return []
+    return [ReplOutput("result", {command.output_type: command.output})]
+
+
+@lru_cache(maxsize=16)
+def decode_session(text: str) -> ReplSession:
+    """Decode the output of a REPL session. Every code block in the session
+    needs it, so we cache on the contents of the file; modification times
+    are too coarse to tell when a file was rewritten."""
+    return read_session(StringIO(text))
+
+
+def session_output(path: Path) -> ReplSession | None:
+    try:
+        return decode_session(path.read_text())
+    except FileNotFoundError:
+        log.warning("REPL session output `%s` not found; run `repl-session` first.", path)
+    except msgspec.MsgspecError as e:
+        log.warning("REPL session output `%s` could not be read: %s", path, e)
+    return None
+
+
+def find_command(reference_map: ReferenceMap, r: ReferenceId) -> ReplCommand | None:
+    """Find the command for a code block in the output of its REPL session.
+    The session is opened by the first code block of the same name that has
+    the `repl` class and a `session` attribute; every code block of that name
+    from there on is a command in the session."""
+    refs = reference_map.select_by_name(r.name)
+    try:
+        start = next(i for i, ref in enumerate(refs)
+                     if Class("repl") in reference_map[ref].properties
+                     and get_attribute_string(reference_map[ref].properties, "session"))
+    except StopIteration:
+        return None
+
+    session_file = get_attribute_string(reference_map[refs[start]].properties, "session")
+    assert session_file is not None
+    session = session_output(Path(session_file).with_suffix(".out.json"))
+    if session is None:
+        return None
+
+    index = refs.index(r) - start
+    code_block = reference_map[r]
+    if not 0 <= index < len(session.commands):
+        log.warning("%s: no output for this code block in REPL session `%s`.",
+                    code_block.origin, session_file)
+        return None
+
+    command = session.commands[index]
+    if code_block.language is not None \
+            and command.command.strip() != strip_comments(code_block.source, code_block.language).strip():
+        log.warning("%s: REPL session `%s` is out of date; tangle and run `repl-session` again.",
+                    code_block.origin, session_file)
+        return None
+    return command
+
+
+@codeblock_filter
+def repl(reference_map: ReferenceMap, r: ReferenceId) -> list[Content]:
+    """Insert the output of REPL sessions (from the `repl` hook) after code blocks with the `repl` class."""
+    code_block = reference_map[r]
+    if Class("repl") not in code_block.properties:
+        return [r]
+
+    command = find_command(reference_map, r)
+    if command is None:
+        return [r]
+
+    rendered = [text for out in command_outputs(command)
+                if (text := render_output(out, command.output_type)) is not None]
+    if not rendered:
+        return [r]
+
+    # The closing fence may lack a newline at the end of a file.
+    eol = "" if code_block.close_line.endswith("\n") else "\n"
+    body = "".join(indent(f"\n{text}\n", code_block.indent) for text in rendered)
+    return [r, PlainText(eol + body)]
+
+
+filters: dict[str, ContentFilter] = {
+    "label": label,
+    "repl": repl,
+    "title": title,
+}
+
+
+def filter_description(f: ContentFilter) -> str:
+    return (f.__doc__ or "").strip().partition("\n")[0]

{entangled_cli-2.4.3 → entangled_cli-2.6.0}/pyproject.toml

@@ -1,25 +1,30 @@
 [project]
 name = "entangled-cli"
-version = "2.4.3"
+version = "2.6.0"
 description = "Literate Programming toolbox"
 authors = [{ name = "Johan Hidding", email = "j.hidding@esciencecenter.nl" }]
 requires-python = ">=3.13,<4"
 readme = "README.md"
 license = "Apache-2.0"
 dependencies = [
-        "filelock>=3.12.0,<4",
-        "rich>=13,<15",
-        "tomlkit>=0.12.1,<0.13",
+        "filelock>=3.12.0,<5",
+        "rich>=13,<16",
+        "tomlkit>=0.12.1,<0.16",
         "copier>=9,<10",
         "brei>=0.2.3,<0.3",
         "rich-argparse>=1.4.0,<2",
         "pyyaml>=6.0.1,<7",
-        "repl-session>=0.2.0",
+        "repl-session>=0.3.0",
         "msgspec>=0.20.0",
         "click>=8.3.0",
         "rich-click>=1.9.4",
         "typeguard>=4.4.4",
-        "watchfiles>=1.1.1",
+        "watchfiles>=1.3",
+]
+
+[project.optional-dependencies]
+jupyter = [
+        "repl-session[jupyter]>=0.3.0",
 ]
 
 [project.urls]
@@ -32,8 +37,7 @@ entangled = "entangled.main:cli"
 [dependency-groups]
 dev = [
         "pytest>=9.0,<10",
-        "mypy>=1.18,<2",
-        "black>=23.3.0,<24",
+        "mypy>=2.4.0",
         "pytest-cov>=4.0.0,<5",
         "mkdocs>=1.4.3,<2",
         "mkdocs-material>=9.7,<10",
@@ -48,7 +52,7 @@ dev = [
         "types-pexpect>=4.9.0.20250916",
         "types-PyYAML>=6.0.1,<7",
         "pytest-timeout>=2.4.0",
-        "ty>=0.0.1a24",
+        "ipykernel>=7.0",
 ]
 
 [tool.hatch.build.targets.sdist]
@@ -70,5 +74,10 @@ testpaths = ["test"]
 [tool.mypy]
 packages = ["entangled"]
 
+[tool.uv.workspace]
+members = [
+    ".",
+]
+
 [tool.uv.sources]
-watchdog = { git = "https://github.com/gorakhargosh/watchdog" }
+entangled-cli = { workspace = true, editable = true }