entangled-cli 2.1.12__tar.gz → 2.2.0__tar.gz

{entangled_cli-2.1.12 → entangled_cli-2.2.0}/PKG-INFO

@@ -1,20 +1,22 @@
 Metadata-Version: 2.4
 Name: entangled-cli
-Version: 2.1.12
+Version: 2.2.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: ~=3.11
+Requires-Python: <4,>=3.12
 Requires-Dist: argh<0.31,>=0.30
 Requires-Dist: brei<0.3,>=0.2.3
 Requires-Dist: copier<10,>=9
 Requires-Dist: filelock<4,>=3.12.0
-Requires-Dist: mawk<0.2,>=0.1.4
+Requires-Dist: mawk<0.2,>=0.1.7
+Requires-Dist: msgspec>=0.19.0
 Requires-Dist: pexpect<5,>=4.9.0
 Requires-Dist: pyyaml<7,>=6.0.1
+Requires-Dist: repl-session>=0.2.0
 Requires-Dist: rich-argparse<2,>=1.4.0
 Requires-Dist: rich<14,>=13.3.5
 Requires-Dist: tomlkit<0.13,>=0.12.1
@@ -218,6 +220,8 @@ Entangled has a system of *hooks*: these add actions to the tangling process:
 - `brei` trigger actions (or tasks) using [Brei](https://entangled.github.io/brei), which is automatically installed along with Entangled. This is now prefered over the `build` hook.
 - `quarto_attributes` add attributes to the code block in Quatro style with `#|` comments at the top of the code block.
 - `shebang` takes the first line if it starts with `#!` and puts it at the top of the file.
+- `spdx_license` takes the first line if it contains `SPDX-License-Identifier`
+and puts it at the top of the file.
 
 ### `build` hook
 

{entangled_cli-2.1.12 → entangled_cli-2.2.0}/README.md

@@ -195,6 +195,8 @@ Entangled has a system of *hooks*: these add actions to the tangling process:
 - `brei` trigger actions (or tasks) using [Brei](https://entangled.github.io/brei), which is automatically installed along with Entangled. This is now prefered over the `build` hook.
 - `quarto_attributes` add attributes to the code block in Quatro style with `#|` comments at the top of the code block.
 - `shebang` takes the first line if it starts with `#!` and puts it at the top of the file.
+- `spdx_license` takes the first line if it contains `SPDX-License-Identifier`
+and puts it at the top of the file.
 
 ### `build` hook
 

{entangled_cli-2.1.12 → entangled_cli-2.2.0}/entangled/code_reader.py

@@ -4,7 +4,8 @@ from pathlib import Path, PurePath
 import mawk
 import re
 
-from .document import ReferenceId, TextLocation, ReferenceMap
+from .text_location import TextLocation
+from .document import ReferenceId, ReferenceMap
 from .errors.user import IndentationError
 
 
@@ -19,7 +20,7 @@ class CodeReader(mawk.RuleSet):
     """Reads an annotated code file."""
 
     def __init__(self, path: PurePath, refs: ReferenceMap):
-        self.location = TextLocation(path, 0)
+        self.location: TextLocation = TextLocation(path, 0)
         self.stack: list[Frame] = [Frame(ReferenceId("#root#", PurePath("-"), -1), "")]
         self.refs: ReferenceMap = refs
 
@@ -34,7 +35,7 @@ class CodeReader(mawk.RuleSet):
     @mawk.on_match(
         r"^(?P<indent>\s*).* ~/~ begin <<(?P<source>[^#<>]+)#(?P<ref_name>[^#<>]+)>>\[(?P<ref_count>init|\d+)\]"
     )
-    def on_block_begin(self, m: re.Match):
+    def on_block_begin(self, m: re.Match[str]) -> list[str]:
         ref_name = m["ref_name"]
 
         # When there are lines above the first ref, say a shebang, swap
@@ -62,15 +63,15 @@ class CodeReader(mawk.RuleSet):
         return []
 
     @mawk.on_match(r"^(?P<indent>\s*).* ~/~ end")
-    def on_block_end(self, m: re.Match):
+    def on_block_end(self, m: re.Match[str]) -> list[str]:
         if m["indent"] != self.current.indent:
             raise IndentationError(self.location)
         self.refs[self.current.ref].source = "\n".join(self.current.content)
-        self.stack.pop()
+        _ = self.stack.pop()
         return []
 
     @mawk.always
-    def otherwise(self, line: str):
+    def otherwise(self, line: str) -> list[str]:
         if line.strip() == "":
             self.current.content.append("")
             return []

{entangled_cli-2.1.12 → entangled_cli-2.2.0}/entangled/commands/status.py

@@ -29,12 +29,12 @@ def rich_status():
     config_table.add_column("name")
     config_table.add_column("value")
     config_table.add_row(
-        "Watch list", ", ".join(f"'{pat}'" for pat in config.watch_list)
+        "Watch list", ", ".join(f"'{pat}'" for pat in config.get.watch_list)
     )
     config_table.add_row(
-        "Ignore list", ", ".join(f"'{pat}'" for pat in config.ignore_list)
+        "Ignore list", ", ".join(f"'{pat}'" for pat in config.get.ignore_list)
     )
-    config_table.add_row("Hooks enabled", ", ".join(config.hooks))
+    config_table.add_row("Hooks enabled", ", ".join(config.get.hooks))
 
     console = Console(color_system="auto")
     group = Group(
@@ -53,4 +53,3 @@ def rich_status():
 def status():
     config.read()
     rich_status()
-

{entangled_cli-2.1.12 → entangled_cli-2.2.0}/entangled/commands/stitch.py

@@ -1,6 +1,5 @@
 from itertools import chain
 from pathlib import Path
-from textwrap import indent
 
 import logging
 import argh  # type: ignore
@@ -18,7 +17,7 @@ def stitch_markdown(reference_map: ReferenceMap, content: list[Content]) -> str:
             case PlainText(s):
                 return s
             case ReferenceId():
-                return indent(reference_map[item].source, reference_map[item].indent)
+                return reference_map.get_codeblock(item).indented_text
 
     return "\n".join(get(i) for i in content) + "\n"
 
@@ -33,7 +32,7 @@ def stitch(*, force: bool = False, show: bool = False):
     from ..markdown_reader import read_markdown_file
     from ..code_reader import CodeReader
     from ..hooks import get_hooks
-    
+
     input_file_list = get_input_files()
     hooks = get_hooks()
 

{entangled_cli-2.1.12 → entangled_cli-2.2.0}/entangled/commands/tangle.py

@@ -1,4 +1,3 @@
-from typing import Optional
 from itertools import chain
 from pathlib import Path
 
@@ -13,10 +12,10 @@ from ..errors.user import UserError
 
 
 def get_input_files() -> list[Path]:
-    include_file_list = chain.from_iterable(map(Path(".").glob, config.watch_list))
+    include_file_list = chain.from_iterable(map(Path(".").glob, config.get.watch_list))
     input_file_list = [
         path for path in include_file_list
-        if not any(path.match(pat) for pat in config.ignore_list)
+        if not any(path.match(pat) for pat in config.get.ignore_list)
     ]
     return input_file_list
 
@@ -30,7 +29,7 @@ def get_input_files() -> list[Path]:
 @argh.arg("--force", help="force overwrite on conflict")
 @argh.arg("-s", "--show", help="only show, don't act")
 @argh.arg("-r", "--reset-db", help="resets database")
-def tangle(*, annotate: Optional[str] = None, force: bool = False, show: bool = False, reset_db = False):
+def tangle(*, annotate: str | None = None, force: bool = False, show: bool = False, reset_db: bool = False):
     """Tangle codes from Markdown"""
     config.read()
 
@@ -39,7 +38,7 @@ def tangle(*, annotate: Optional[str] = None, force: bool = False, show: bool =
     from ..tangle import tangle_ref
 
     if annotate is None:
-        annotation_method = config.annotation
+        annotation_method = config.get.annotation
     else:
         annotation_method = AnnotationMethod[annotate.upper()]
 

{entangled_cli-2.1.12 → entangled_cli-2.2.0}/entangled/commands/watch.py

@@ -1,8 +1,5 @@
-from typing import Optional
 from pathlib import Path
-from itertools import chain
 from threading import Event
-import os
 
 from watchdog.observers import Observer
 from watchdog.events import FileSystemEventHandler, FileSystemEvent
@@ -32,7 +29,7 @@ class EventHandler(FileSystemEventHandler):
         self.update_watched()
 
 
-def _watch(_stop_event: Optional[Event] = None, _start_event: Optional[Event] = None):
+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."""

{entangled_cli-2.1.12 → entangled_cli-2.2.0}/entangled/config/__init__.py

@@ -4,21 +4,21 @@ defaults and config loaded from `entangled.toml` in the work directory.
 
 from __future__ import annotations
 
+from functools import cached_property
 import threading
 from contextlib import contextmanager
-from copy import copy
-from dataclasses import dataclass, field
-from enum import Enum
+from copy import copy, deepcopy
+from enum import StrEnum
 from pathlib import Path
-from typing import Any, ClassVar, Optional, TypeVar
+from typing import Any
 
+import msgspec
+from msgspec import Struct, field
 import tomllib
-from entangled.errors.internal import InternalError
-
-from entangled.errors.user import UserError
 
 from brei import Program
-from ..construct import construct
+
+from entangled import from_str
 from .language import Language, languages
 from .version import Version
 from ..logging import logger
@@ -27,7 +27,7 @@ from ..logging import logger
 log = logger()
 
 
-class AnnotationMethod(Enum):
+class AnnotationMethod(StrEnum):
     """Annotation methods.
 
     - `STANDARD` is the default. Comments tell where a piece of code
@@ -38,13 +38,12 @@ class AnnotationMethod(Enum):
     - `SUPPLEMENTED` adds extra information to the comment lines.
     """
 
-    STANDARD = 1
-    NAKED = 2
-    SUPPLEMENTED = 3
+    STANDARD = "standard"
+    NAKED = "naked"
+    SUPPLEMENTED = "supplemented"
 
 
-@dataclass
-class Markers:
+class Markers(Struct):
     """Markers can be used to configure the Markdown dialect. Currently not used."""
 
     open: str
@@ -58,8 +57,7 @@ markers = Markers(
 )
 
 
-@dataclass
-class Config(threading.local):
+class Config(Struct, dict=True):
     """Main config class.
 
     Attributes:
@@ -79,35 +77,40 @@ class Config(threading.local):
 
     This class is made thread-local to make it possible to test in parallel."""
 
-    version: Version
+    _version: str = field(name = "version")
     languages: list[Language] = field(default_factory=list)
     markers: Markers = field(default_factory=lambda: copy(markers))
     watch_list: list[str] = field(default_factory=lambda: ["**/*.md"])
-    ignore_list: list[str] = field(default_factory=lambda: ["README.md"])
-    annotation_format: Optional[str] = None
+    ignore_list: list[str] = field(default_factory=list)
+    annotation_format: str | None = None
     annotation: AnnotationMethod = AnnotationMethod.STANDARD
     use_line_directives: bool = False
     hooks: list[str] = field(default_factory=lambda: ["shebang"])
-    hook: dict = field(default_factory=dict)
+    hook: dict[str, Any] = field(default_factory=dict)
     brei: Program = field(default_factory=Program)
 
+    language_index: dict[str, Language] = field(default_factory=dict)
+
+    @cached_property
+    def version(self) -> Version:
+        return Version.from_str(self._version)
+
     def __post_init__(self):
         self.languages = languages + self.languages
         self.make_language_index()
 
     def make_language_index(self):
-        self.language_index = dict()
         for l in self.languages:
             for i in l.identifiers:
                 self.language_index[i] = l
 
 
-default = Config(Version.from_str("2.0"))
+default = Config("2.0")  # Version.from_str("2.0"))
 
 
 def read_config_from_toml(
-    path: Path, section: Optional[str] = None
-) -> Optional[Config]:
+    path: Path, section: str | None = None
+) -> Config | 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
@@ -127,7 +130,8 @@ def read_config_from_toml(
             if section is not None:
                 for s in section.split("."):
                     json = json[s]
-            return construct(Config, json)
+            return msgspec.convert(json, type=Config, dec_hook=from_str.dec_hook)
+
     except ValueError as e:
         log.error("Could not read config: %s", e)
         return None
@@ -147,30 +151,35 @@ def read_config():
     return default
 
 
-class ConfigWrapper:
-    def __init__(self, config = None):
-        self.config = config
+class ConfigWrapper(threading.local):
+    def __init__(self, config: Config | None = None):
+        self.config: Config | None = config
 
-    def read(self, force=False):
+    def read(self, force: bool = False):
         if self.config is None or force:
             self.config = read_config()
 
-    def __getattr__(self, attr):
+    @property
+    def get(self) -> Config:
         if self.config is None:
-            raise InternalError("Config not loaded.")
-        return getattr(self.config, attr)
+            raise ValueError(f"No config loaded.")
+        return self.config
 
     @contextmanager
     def __call__(self, **kwargs):
-        backup = {k: getattr(self.config, k) for k in kwargs}
+        backup = self.config
+        new_config = deepcopy(self.config)
         for k, v in kwargs.items():
-            setattr(self.config, k, v)
+            setattr(new_config, k, v)
+        self.config = new_config
+
         yield
-        for k in kwargs.keys():
-            setattr(self.config, k, backup[k])
 
-    def get_language(self, lang_name: str) -> Optional[Language]:
-        assert self.config
+        self.config = backup
+
+    def get_language(self, lang_name: str) -> Language | None:
+        if self.config is None:
+            raise ValueError(f"No config loaded.")
         return self.config.language_index.get(lang_name, None)
 
 

{entangled_cli-2.1.12 → entangled_cli-2.2.0}/entangled/config/language.py

@@ -1,19 +1,16 @@
-from typing import Optional
-from dataclasses import dataclass
+from msgspec import Struct
 
 
-@dataclass
-class Comment:
+class Comment(Struct):
     """Comment method for a language. For example: `Comment("/*", "*/")` works
     for C/C++ etc, `Comment("#")` works for Python, and so on.
     """
 
     open: str
-    close: Optional[str] = None
+    close: str | None = None
 
 
-@dataclass
-class Language:
+class Language(Struct):
     """Language information. Given a language we may have any number of short-hands
     to indicate a code block is written in that language. If a language supports
     line directives this can be used to redirect compiler messages directly to the
@@ -22,7 +19,7 @@ class Language:
     name: str
     identifiers: list[str]
     comment: Comment
-    line_directive: Optional[str] = None
+    line_directive: str | None = None
 
 
 languages = [
@@ -43,6 +40,7 @@ languages = [
     Language("Make", ["make", "makefile"], Comment("#")),
     Language("Gnuplot", ["gnuplot"], Comment("#")),
     Language("TOML", ["toml"], Comment("#")),
+    Language("YAML", ["yaml"], Comment("#")),
     Language("F#", ["fsharp"], Comment("//")),
     Language("Javascript", ["javascript", "js", "ecma"], Comment("//")),
     Language("Go", ["go", "golang"], Comment("//")),

{entangled_cli-2.1.12 → entangled_cli-2.2.0}/entangled/config/templates.py

@@ -1,8 +1,7 @@
-from dataclasses import dataclass
+from msgspec import Struct
 
 
-@dataclass
-class Template:
+class Template(Struct):
     """Officially supported templates. Templates are pulled from external GitHub
     repositories: `entangled new <template name>`. These templates are the ones
     we officially support. Other templates can be used with valid copier URL
@@ -32,5 +31,12 @@ templates: list[Template] = [
         "gh:entangled/template-pandoc",
         "pandoc",
         "Supports HTML and PDF output, numbered equations and citations."
+    ),
+    Template(
+        "one-pager",
+        "One-page README",
+        "gh:entangled/template-one-pager",
+        "none",
+        "Everything in a single README, to be rendered on Github/Gitlab/etc."
     )
 ]

{entangled_cli-2.1.12 → entangled_cli-2.2.0}/entangled/config/version.py

@@ -1,16 +1,18 @@
 from __future__ import annotations
 from dataclasses import dataclass
+from ..from_str import FromStr
+from typing import override
 
-from ..construct import FromStr
 
 @dataclass
 class Version(FromStr):
     numbers: tuple[int, ...]
 
-    def __str__(self):
+    @override
+    def to_str(self) -> str:
         return ".".join(str(i) for i in self.numbers)
 
+    @override
     @classmethod
     def from_str(cls, s: str) -> Version:
         return Version(tuple(int(sv) for sv in s.split(".")))
-

{entangled_cli-2.1.12 → entangled_cli-2.2.0}/entangled/document.py

@@ -1,4 +1,5 @@
-from typing import Optional, Union, Iterable, Any
+from textwrap import indent
+from typing import Optional, Union, Iterable, Any, override
 from dataclasses import dataclass, field
 from collections import defaultdict
 from functools import singledispatchmethod
@@ -11,7 +12,7 @@ from .errors.internal import InternalError
 from .text_location import TextLocation
 
 
-def length(iter: Iterable[Any]) -> int:
+def length[T](iter: Iterable[T]) -> int:
     return sum(1 for _ in iter)
 
 
@@ -21,7 +22,8 @@ class ReferenceId:
     file: PurePath
     ref_count: int
 
-    def __hash__(self):
+    @override
+    def __hash__(self) -> int:
         return hash((self.name, self.file, self.ref_count))
 
 
@@ -34,15 +36,25 @@ class PlainText:
 class CodeBlock:
     properties: list[Property]
     indent: str
+    open_line: str
+    close_line: str
     source: str
     origin: TextLocation
-    language: Optional[Language] = None
-    header: Optional[str] = None
-    mode: Optional[int] = None
+    language: Language | None = None
+    header: str | None = None
+    mode: int | None = None
 
+    @property
+    def text(self) -> str:
+        return self.open_line + "\n" + self.source + "\n" + self.close_line
 
-Content = Union[PlainText, ReferenceId]
-RawContent = Union[PlainText, CodeBlock]
+    @property
+    def indented_text(self) -> str:
+        return indent(self.text, self.indent)
+
+
+Content = PlainText | ReferenceId
+RawContent = PlainText | CodeBlock
 
 
 @dataclass
@@ -85,6 +97,9 @@ class ReferenceMap:
     def __contains__(self, key: str) -> bool:
         return key in self.index
 
+    def get_codeblock(self, key: ReferenceId) -> CodeBlock:
+        return self.map[key]
+
     @singledispatchmethod
     def __getitem__(self, key):
         raise NotImplementedError(f"Invalid key: {type(key)}")
@@ -96,3 +111,50 @@ class ReferenceMap:
     @__getitem__.register
     def _(self, key: str) -> Iterable[CodeBlock]:
         return self.by_name(key)
+
+
+def content_to_text(r: ReferenceMap, c: Content) -> str:
+    """
+    Reconstruct original plain text from a piece of content.
+
+    Args:
+        r: the reference map.
+        c: the content.
+
+    Returns:
+        A string, usually not terminated by a newline.
+    """
+    match c:
+        case PlainText(s): return s
+        case ReferenceId(): return r.get_codeblock(c).indented_text
+
+
+def document_to_text(r: ReferenceMap, cs: list[Content]) -> str:
+    """
+    Reconstruct original plain text content from a reference map and
+    list of content.
+
+    Args:
+        r: the reference map.
+        cs: a list of content.
+
+    Returns:
+        A string, including a final newline.
+
+    Usually this is the reconstructed content of a Markdown file. Most
+    editors have a convention to end a file with a newline, but this
+    newline is usually stripped when we read a file.
+
+    Context:
+        In Python `"foo".splitlines()` gives the same as `"foo\n".splitlines()`,
+        with the exception of `"\n".splitlines()` giving `['']`, while
+        `"".splitlines()` returns `[]`.
+
+        As an alternative, we could keep line endings by splitting with `keepends=True`,
+        and joining with `"".join(...)`.
+    """
+    text = "\n".join(content_to_text(r, c) for c in cs)
+    if text[-1] != "\n":
+        return text + "\n"
+    else:
+        return text

{entangled_cli-2.1.12 → entangled_cli-2.2.0}/entangled/errors/user.py

@@ -1,11 +1,12 @@
 from dataclasses import dataclass
 from typing import Any, Callable
+from pathlib import Path
 
 from ..text_location import TextLocation
 
 
 class UserError(Exception):
-    def __str__(self):
+    def __str__(self) -> str:
         return "Unknown user error."
 
 
@@ -25,12 +26,20 @@ class HelpfulUserError(UserError):
     Make sure to also execute e.func() in your error handling."""
 
     msg: str
-    func: Callable = lambda: None
+    func: Callable[[], Any] = lambda: None
 
     def __str__(self):
         return f"error: {self.msg}"
 
 
+@dataclass
+class FileError(UserError):
+    filename: Path
+
+    def __str__(self):
+        return f"file not found `{self.filename}`"
+
+
 @dataclass
 class IndentationError(UserError):
     location: TextLocation