mkdocs-entangled-plugin 0.4.0__tar.gz → 0.6.0__tar.gz

mkdocs_entangled_plugin-0.6.0/.gitignore

@@ -0,0 +1,6 @@
+site
+.mypy_cache
+.pytest_cache
+__pycache__
+dist
+poetry.lock

{mkdocs_entangled_plugin-0.4.0 → mkdocs_entangled_plugin-0.6.0}/PKG-INFO

@@ -1,17 +1,14 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: mkdocs-entangled-plugin
-Version: 0.4.0
+Version: 0.6.0
 Summary: Plugin for MkDocs helping with rendering Entangled (entangled.github.io) projects.
-License: Apache 2.0
-Author: Johan Hidding
-Author-email: j.hidding@esciencecenter.nl
-Requires-Python: >=3.11,<4.0
-Classifier: License :: Other/Proprietary License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Requires-Dist: entangled-cli (>=2.0.0a6,<3.0.0)
-Requires-Dist: mawk (>=0.1.4,<0.2.0)
-Requires-Dist: mkdocs (>=1.4.2,<2.0.0)
+Author-email: Johan Hidding <j.hidding@esciencecenter.nl>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: <4,>=3.12
+Requires-Dist: entangled-cli<3,>=2.4
+Requires-Dist: mawk<0.2,>=0.1.7
+Requires-Dist: mkdocs<2,>=1.4.2
 Description-Content-Type: text/markdown
 
 # Welcome to MkDocs Entangled Plugin
@@ -125,4 +122,3 @@ Build artifacts by specifying a Makefile.
 
 ## License
 Licensed under the Apache-2 license agreement: see LICENSE
-

mkdocs_entangled_plugin-0.6.0/mkdocs_entangled/on_page_markdown.py

@@ -0,0 +1,138 @@
+from collections.abc import Iterable, Callable
+from functools import partial, reduce
+from pathlib import Path
+from textwrap import indent
+from itertools import chain
+
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.pages import Page
+from mkdocs.structure.files import Files
+
+from entangled.model import ReferenceMap, Content, PlainText, ReferenceId, CodeBlock, content_to_text
+from entangled.model.properties import get_attribute, Id, Attribute, Class
+from entangled.config import ConfigUpdate, read_config
+from entangled.interface import Context, read_markdown
+from repl_session import read_session
+
+
+type ContentFilter = Callable[[ReferenceMap, Content], Iterable[Content]]
+type CodeBlockFilter = Callable[[ReferenceMap, ReferenceId], Iterable[Content]]
+
+
+def codeblock_filter(f: CodeBlockFilter) -> ContentFilter:
+    def _foo(rm: ReferenceMap, c: Content) -> Iterable[Content]:
+        match c:
+            case PlainText():
+                return [c]
+            case ReferenceId():
+                return f(rm, c)
+    return _foo
+
+
+def document_to_text(refs: ReferenceMap, content: Iterable[Content]) -> str:
+    return "".join(map(lambda c: content_to_text(refs, c)[0], content))
+
+
+def iter_bind[T, U](lst: Iterable[T], f: Callable[[T], Iterable[U]]) -> Iterable[U]:
+    return chain(*map(f, lst))
+
+
+def compose_filter(a: ContentFilter, b: ContentFilter) -> ContentFilter:
+    def _joined(rm: ReferenceMap, c: Content) -> Iterable[Content]:
+        return iter_bind(partial(a, rm)(c), partial(b, rm))
+    return _joined
+
+
+def compose_filters(*args: ContentFilter) -> ContentFilter:
+    return reduce(compose_filter, args, lambda _, c: [c])
+
+
+def read_single_markdown(ctx: Context, text: str) -> tuple[ReferenceMap, list[Content]]:
+    refs = ReferenceMap()
+    content, _ = read_markdown(ctx, refs, text)
+    return refs, content
+
+
+@codeblock_filter
+def add_title(reference_map: ReferenceMap, r: ReferenceId) -> list[Content]:
+    """
+    Changes the `open_line` member of a `CodeBlock` to reflect accepted
+    MkDocs syntax, adding a `title` attribute.
+    """
+    codeblock: CodeBlock = reference_map[r]
+
+    ids = [p.value for p in codeblock.properties if isinstance(p, Id)]
+    classes = [p.value for p in codeblock.properties if isinstance(p, Class)]
+    filenames = [p.value for p in codeblock.properties if isinstance(p, Attribute) and p.key == "file"]
+
+    title = None
+    if len(ids) == 1 and len(filenames) == 1:
+        title = f"#{ids[0]} / file: {filenames[0]}"
+    elif len(ids) == 1:
+        title = f"#{ids[0]}"
+    elif len(filenames) == 1:
+        title = f"file: {filenames[0]}"
+    elif len(ids) > 1 or len(filenames) > 1:
+        title = "error: ambiguous code block title"
+
+    open_line = "```"
+    if classes:
+        language_id = classes[0]
+        open_line += language_id
+
+    if ids or classes or title:
+        open_line += " {"
+
+        if ids:
+            open_line += str(Id(ids[0]))
+
+        for c in classes[1:]:
+            open_line += " " + str(Class(c))
+
+        if title:
+            open_line += " " + str(Attribute("title", title))
+
+        open_line += "}\n"
+
+    codeblock.open_line = open_line
+    return [r]
+
+
+@codeblock_filter
+def include_repl_output(reference_map: ReferenceMap, r: ReferenceId) -> list[Content]:
+    """
+    Takes any codeblock that has the `repl` class and append its pre-computed output.
+    """
+    codeblock: CodeBlock = reference_map[r]
+    if Class("repl") not in codeblock.properties:
+        return [r]
+
+    ref = next(iter(reference_map.select_by_name(r.name)))
+    first: CodeBlock = reference_map[ref]
+    session_filename = get_attribute(first.properties, "session")
+    assert session_filename is not None
+    session_path: Path = Path(session_filename)
+    assert session_path.exists()
+    session_output_path: Path = session_path.with_suffix(".out.json")
+    assert session_output_path.exists()
+
+    session = read_session(session_output_path.open("r"))
+    command = session.commands[r.ref_count]
+
+    if not command.output:
+        return [r]
+
+    output: str
+    if command.output_type == "text/plain":
+        output = indent(f"\n``` {{.text .output}}\n{command.output}\n```", codeblock.indent)
+    else:
+        output = indent(f"\n**unknown MIME type: {command.output_type}**", codeblock.indent)
+
+    return [r, PlainText(output)]
+
+
+def on_page_markdown(markdown: str, *, page: Page, config: MkDocsConfig, files: Files) -> str:
+    context = Context() | read_config()
+    reference_map, content = read_single_markdown(context, markdown)
+    filtered_content = iter_bind(content, partial(compose_filters(add_title, include_repl_output), reference_map))
+    return document_to_text(reference_map, filtered_content)

{mkdocs_entangled_plugin-0.4.0 → mkdocs_entangled_plugin-0.6.0}/mkdocs_entangled/plugin.py

@@ -1,4 +1,5 @@
-import mkdocs
+from typing import override
+from mkdocs.plugins import BasePlugin
 from mkdocs.config.defaults import MkDocsConfig
 from mkdocs.structure.pages import Page
 from mkdocs.structure.files import Files
@@ -6,6 +7,8 @@ from mkdocs.structure.files import Files
 from .on_page_markdown import on_page_markdown
 from .config import EntangledConfig
 
-class EntangledPlugin(mkdocs.plugins.BasePlugin[EntangledConfig]):
+
+class EntangledPlugin(BasePlugin[EntangledConfig]):
+    @override
     def on_page_markdown(self, markdown: str, *, page: Page, config: MkDocsConfig, files: Files):
         return on_page_markdown(markdown, page=page, config=config, files=files)

mkdocs_entangled_plugin-0.6.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "mkdocs-entangled-plugin"
+version = "0.6.0"
+description = "Plugin for MkDocs helping with rendering Entangled (entangled.github.io) projects."
+authors = [{ name = "Johan Hidding", email = "j.hidding@esciencecenter.nl" }]
+requires-python = ">=3.12,<4"
+readme = "README.md"
+license = "Apache-2.0"
+dependencies = [
+    "mkdocs>=1.4.2,<2",
+    "entangled-cli>=2.4,<3",
+    "mawk>=0.1.7,<0.2",
+]
+
+[project.entry-points."mkdocs.plugins"]
+entangled = "mkdocs_entangled:EntangledPlugin"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.2.0,<2",
+    "pytest>=7.3.0,<8",
+    "pytest-mypy>=0.10.3,<0.11",
+    "mkdocs-material>=9.1.6,<10",
+    "pyright>=1.1.406",
+]
+
+[tool.hatch.build.targets.sdist]
+include = ["mkdocs_entangled"]
+
+[tool.hatch.build.targets.wheel]
+include = ["mkdocs_entangled"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+addopts = ["--mypy"]
+testpaths = [
+    "test"
+]
+
+[tool.mypy]
+packages = ["mkdocs_entangled"]
+
+[tool.uv.sources]
+entangled-cli = { git = "https://github.com/entangled/entangled.py" }
+

mkdocs_entangled_plugin-0.4.0/mkdocs_entangled/on_page_markdown.py

@@ -1,64 +0,0 @@
-from typing import Optional
-from dataclasses import dataclass
-import re
-
-from mkdocs.config.defaults import MkDocsConfig
-from mkdocs.structure.pages import Page
-from mkdocs.structure.files import Files
-
-from .properties import read_properties, Id, Attribute
-import mawk
-
-
-@dataclass
-class EntangledFilter(mawk.RuleSet):
-    add_title: bool = True
-    _ignore: bool = False
-
-    @mawk.on_match(r"~~~markdown")
-    def start_ignore(self, m):
-        self._ignore = True
-        return [m[0]]
-    
-    @mawk.on_match(r"~~~")
-    def stop_ignore(self, m):
-        self._ignore = False
-        return [m[0]]
-
-    @mawk.on_match(r"(\s*)``` *\{([^}]*)\}")
-    def open_code_block(self, m: re.Match) -> Optional[list[str]]:
-        if self._ignore:
-            return None
-
-        indent = m[1]
-        props = list(read_properties(m[2]))
-        
-        ids = [p.value for p in props if isinstance(p, Id)]
-        filenames = [p.value for p in props if isinstance(p, Attribute) and p.key == "file"]
-
-        if self.add_title:
-            title = None
-            if len(ids) == 1 and len(filenames) == 1:
-                title = f"#{ids[0]} / file: {filenames[0]}"
-            elif len(ids) == 1:
-                title = f"#{ids[0]}"
-            elif len(filenames) == 1:
-                title = f"file: {filenames[0]}"
-            elif len(ids) > 1 or len(filenames) > 1:
-                title = f"error: ambiguous code block title"
-
-            if title is not None:
-                props.append(Attribute("title", title))
-        
-        prop_str = " ".join(str(p) for p in props)
-        return [f"{indent}``` {{{prop_str}}}"]
-
-    @mawk.on_match(r"\s*```\s*$")
-    def close_code_block(self, m: re.Match) -> Optional[list[str]]:
-        return None
-
-
-def on_page_markdown(markdown: str, *, page: Page, config: MkDocsConfig, files: Files) -> str:
-    result = EntangledFilter().run(markdown)
-    return result
-

mkdocs_entangled_plugin-0.4.0/mkdocs_entangled/properties.py

@@ -1,124 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Optional, Protocol, TypeVar, Generic, Any, Sequence, Union
-import re
-
-
-T = TypeVar("T")
-T_co = TypeVar("T_co", covariant=True)
-
-class Parser(Protocol[T_co]):
-    def read(self, inp: str) -> Optional[tuple[T_co, str]]:
-        ...
-
-@dataclass
-class Id:
-    value: str
-
-    def __str__(self):
-        return f"#{self.value}"
-
-    @staticmethod
-    def read(inp: str) -> Optional[tuple[Id, str]]:
-        if m := re.match("#([^ {}]+)", inp):
-            return Id(m[1]), inp[m.end():]
-        return None
-
-
-@dataclass
-class Class:
-    value: str
-
-    def __str__(self):
-        return f".{self.value}"
-
-    @staticmethod
-    def read(inp: str) -> Optional[tuple[Class, str]]:
-        if m := re.match("\\.([^ {}]+)", inp):
-            return Class(m[1]), inp[m.end():]
-        return None
-
-
-@dataclass
-class Attribute:
-    key: str
-    value: str
-
-    def __str__(self):
-        return f"{self.key}=\"{self.value}\""
-    
-    @staticmethod
-    def read(inp: str) -> Optional[tuple[Attribute, str]]:
-        if m := re.match("([^ {}]+) *= *([^ {}\"]+)", inp):
-            return Attribute(m[1], m[2]), inp[m.end():]
-        if m := re.match("([^ {}]+) *= *\"([^\"]*)\"", inp):
-            return Attribute(m[1], m[2]), inp[m.end():]
-        return None
-
-
-Property = Union[Attribute, Class, Id]
-
-@dataclass
-class Choice(Generic[T]):
-    options: Sequence[Parser[T]]
-
-    def read(self, inp: str) -> Optional[tuple[T, str]]:
-        for o in self.options:
-            rv = o.read(inp)
-            if rv is None:
-                continue
-            else:
-                return rv
-        return None
-
-
-@dataclass
-class Many(Generic[T]):
-    parser: Parser[T]
-
-    def read(self, inp: str) -> tuple[list[T], str]:
-        result: list[T] = []
-        while True:
-            rv = self.parser.read(inp)
-            if rv is None:
-                return result, inp
-            else:
-                value, rest = rv
-                result.append(value)
-                inp = rest
-
-
-@dataclass
-class Skip:
-    what: str
-
-    def read(self, inp: str) -> Optional[tuple[None, str]]:
-        if m := re.match(self.what, inp):
-            return None, inp[m.end():]
-        return None
-
-
-@dataclass
-class Last(Generic[T]):
-    first: Parser[Any]
-    second: Parser[T]
-
-    def read(self, inp: str) -> Optional[tuple[T, str]]:
-        rv = self.first.read(inp)
-        if rv is None:
-            return None
-        else:
-            _, rest = rv
-            return self.second.read(rest)
-
-
-def tokenize(p: Parser[T]) -> Parser[T]:
-    return Last(Skip(" *"), p)
-
-
-def read_properties(inp: str) -> list[Property]:
-    # Explicit typing is needed to convince MyPy of correctness
-    parsers: list[Parser[Property]] = [Id, Class, Attribute]
-    result, _ = Many(tokenize(Choice(parsers))).read(inp) 
-    return result

mkdocs_entangled_plugin-0.4.0/pyproject.toml

@@ -1,39 +0,0 @@
-[tool.poetry]
-name = "mkdocs-entangled-plugin"
-version = "0.4.0"
-description = "Plugin for MkDocs helping with rendering Entangled (entangled.github.io) projects."
-readme = "README.md"
-authors = ["Johan Hidding <j.hidding@esciencecenter.nl>"]
-license = "Apache 2.0"
-packages = [
-    { include = "mkdocs_entangled" }
-]
-
-[tool.poetry.plugins."mkdocs.plugins"]
-entangled = "mkdocs_entangled:EntangledPlugin"
-
-[tool.poetry.dependencies]
-python = "^3.11"
-mkdocs = "^1.4.2"
-entangled-cli = "^2.0.0a6"
-mawk = "^0.1.4"
-
-[tool.poetry.dev-dependencies]
-mypy = "^1.2.0"
-pytest = "^7.3.0"
-pytest-mypy = "^0.10.3"
-mkdocs-material = "^9.1.6"
-twine = "^4.0.2"
-
-[build-system]
-requires = ["poetry-core>=1.0.0"]
-build-backend = "poetry.core.masonry.api"
-
-[tool.pytest.ini_options]
-addopts = ["--mypy"]
-testpaths = [
-    "test"
-]
-
-[tool.mypy]
-packages = ["mkdocs_entangled"]