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

entangled_cli-2.5.0/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)
@@ -440,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.

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

@@ -1,28 +1,3 @@
-Metadata-Version: 2.5
-Name: entangled-cli
-Version: 2.5.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.2.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
-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)
@@ -465,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.

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

@@ -8,7 +8,8 @@ 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", "serve"
+    "main", "stitch", "tangle", "new", "reset", "sync", "watch", "status", "brei", "serve", "weave"
 ]

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.5.0 → 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.5.0 → 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.5.0 → 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.5.0 → 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.5.0 → 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.5.0 → 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.5.0 → 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/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.5.0 → entangled_cli-2.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "entangled-cli"
-version = "2.5.0"
+version = "2.6.0"
 description = "Literate Programming toolbox"
 authors = [{ name = "Johan Hidding", email = "j.hidding@esciencecenter.nl" }]
 requires-python = ">=3.13,<4"
@@ -14,7 +14,7 @@ dependencies = [
         "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",
@@ -22,6 +22,11 @@ dependencies = [
         "watchfiles>=1.3",
 ]
 
+[project.optional-dependencies]
+jupyter = [
+        "repl-session[jupyter]>=0.3.0",
+]
+
 [project.urls]
 Homepage = "https://entangled.github.io/"
 Repository = "https://github.com/entangled/entangled.py"
@@ -47,6 +52,7 @@ dev = [
         "types-pexpect>=4.9.0.20250916",
         "types-PyYAML>=6.0.1,<7",
         "pytest-timeout>=2.4.0",
+        "ipykernel>=7.0",
 ]
 
 [tool.hatch.build.targets.sdist]