texmodel 0.2.0__py3-none-any.whl

texmodel/plan.py

@@ -0,0 +1,92 @@
+"""A document's plan (B2, D2): every output line with the path of what wrote it, so an edit to the file or a line of a
+compile log names the component, not a line number.
+
+`Package.plan(...)` returns it; `Plan.to_json()` is stored beside a committed document as its baseline, and
+`Plan.edits(text)` compares a file with it by line, so a hand edit is found by path even when the model has moved on.
+"""
+
+import dataclasses
+import difflib
+import enum
+import json
+from collections.abc import Iterator
+
+from .components import Environment, Node
+
+
+@dataclasses.dataclass(frozen=True)
+class Line:
+    path: str  # "Card[1]/CardBack[1]/Name[0]", "preamble.after_package[2]", "header", "document"
+    tex: str
+
+
+@enum.unique
+class EditKind(enum.Enum):
+    ADDED = "added"  # in the file, not in the plan
+    REMOVED = "removed"  # in the plan, not in the file
+    CHANGED = "changed"
+
+
+@dataclasses.dataclass(frozen=True)
+class Edit:
+    """One difference. `kind` says which side lacks the line: a blank line has no text to tell by."""
+
+    path: str
+    expected: str
+    found: str
+    kind: EditKind
+
+
+def node_lines(node: Node, path: str) -> Iterator[Line]:
+    """The lines a node renders; children are indexed within their parent, as `validate()` paths are."""
+    rendered = node.render().splitlines()
+    if not isinstance(node, Environment):
+        yield from (Line(path, tex) for tex in rendered)
+        return
+    yield Line(path, rendered[0])
+    for i, child in enumerate(node.content):
+        yield from node_lines(child, f"{path}/{type(child).__name__}[{i}]")
+    yield Line(path, rendered[-1])
+
+
+def _compared(line: str, ignore_comments: bool) -> str:
+    """A comment line compares equal to any other comment line when comments are ignored."""
+    return "%" if ignore_comments and line.lstrip().startswith("%") else line
+
+
+@dataclasses.dataclass(frozen=True)
+class Plan:
+    lines: tuple[Line, ...]
+
+    @property
+    def text(self) -> str:
+        return "\n".join(line.tex for line in self.lines) + "\n"
+
+    def path_of(self, number: int) -> str:
+        """The path that wrote line `number` (1-based, as TeX counts), e.g. from a log's `input line 39`."""
+        return self.lines[number - 1].path
+
+    def edits(self, text: str, *, ignore_comments: bool = False) -> list[Edit]:
+        """What `text` changed against this plan; each difference carries the path of the line it replaced. With
+        `ignore_comments`, a line that is a comment (starts with `%`) in both is not compared, so a changed audit block
+        is no edit; a comment turned into text, or text into a comment, still is."""
+        found = text.splitlines()
+        out: list[Edit] = []
+        a = [_compared(x.tex, ignore_comments) for x in self.lines]
+        b = [_compared(x, ignore_comments) for x in found]
+        for tag, i1, i2, j1, j2 in difflib.SequenceMatcher(None, a, b).get_opcodes():
+            if tag == "equal":
+                continue
+            for k in range(max(i2 - i1, j2 - j1)):
+                was = self.lines[i1 + k] if i1 + k < i2 else None
+                path = was.path if was else self.lines[i2 - 1].path  # an added line belongs to the line before it
+                kind = EditKind.CHANGED if was and j1 + k < j2 else EditKind.REMOVED if was else EditKind.ADDED
+                out.append(Edit(path, was.tex if was else "", found[j1 + k] if j1 + k < j2 else "", kind))
+        return out
+
+    def to_json(self) -> str:
+        return json.dumps([[x.path, x.tex] for x in self.lines], ensure_ascii=False, indent=0) + "\n"
+
+    @classmethod
+    def from_json(cls, text: str) -> "Plan":
+        return cls(tuple(Line(path, tex) for path, tex in json.loads(text)))

texmodel/pointer.py

@@ -0,0 +1,70 @@
+"""Find what a project names with a pointer (`module:object`, `module:getter()`): its `Package`, a document or a `Plan`.
+Public, so the build harness reads the same pointers."""
+
+import importlib
+import pathlib
+import re
+import sys
+from typing import Any
+
+from .errors import DeclarationError
+from .package import Package
+from .plan import Plan
+
+_POINTER = re.compile(
+    r"(?P<module>[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*):(?P<attr>[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*)(?P<call>\(\))?"
+)
+
+
+def _load(spec: str, root: pathlib.Path, what: str) -> Any:  # noqa: ANN401  # whatever the project put there
+    """Resolve a pointer: `pkg.module:object`, `pkg.module:namespace.object` or `pkg.module:get_object()`, looking in
+    `root` and `root/src` first. A trailing `()` calls the object with no arguments and uses what it returns."""
+    if not (m := _POINTER.fullmatch(spec)):
+        raise DeclarationError(
+            f"{spec!r} must be 'module:object', 'module:namespace.object' or 'module:getter()'",
+            code="TM-D020",
+            hint="the module part is dotted, the object part is a name or a dotted path to one",
+        )
+    for path in (root, root / "src"):
+        if str(path) not in sys.path:
+            sys.path.insert(0, str(path))
+    try:
+        obj: Any = importlib.import_module(m["module"])
+        for name in m["attr"].split("."):
+            obj = getattr(obj, name)
+        return obj() if m["call"] else obj
+    except (ImportError, AttributeError, TypeError) as exc:
+        raise DeclarationError(f"cannot load {spec!r}: {exc}", code="TM-D021", hint=f"check {what}") from exc
+
+
+def load_package(spec: str, root: pathlib.Path) -> Package:
+    """Require the loaded object to be a `Package`."""
+    package = _load(spec, root, "[tool.texmodel] package")
+    if not isinstance(package, Package):
+        raise DeclarationError(f"{spec!r} is a {type(package).__name__}, not a Package", code="TM-D022")
+    return package
+
+
+def load_document(spec: str, root: pathlib.Path) -> str | Plan:
+    """The document: a `str` (`Package.document()`) or a `Plan` (`Package.plan()`), or a function returning one."""
+    obj = _load(spec, root, "the module:attribute you passed")
+    text = obj() if callable(obj) else obj
+    if not isinstance(text, str | Plan):
+        raise DeclarationError(
+            f"{spec!r} is a {type(text).__name__}, not a document",
+            code="TM-D024",
+            hint="point at a str or Plan from Package.document() / plan(), or a function returning one",
+        )
+    return text
+
+
+def load_plan(spec: str, root: pathlib.Path) -> Plan:
+    """The `Plan` a pointer names (`Package.plan()`), for the line-to-component map of a diagnostic (B2, D2)."""
+    found = load_document(spec, root)
+    if not isinstance(found, Plan):
+        raise DeclarationError(
+            f"{spec!r} is a str, not a Plan",
+            code="TM-D025",
+            hint="point at Package.plan(...) (or a function returning one): a str has no line-to-component map",
+        )
+    return found

texmodel/preamble.py

@@ -0,0 +1,110 @@
+"""Typed preamble entries (§21a 10, G3): each renders to one `Raw` and knows which `PreambleSlots` slots it may sit in.
+
+```python
+PreambleSlots(
+    before_class=(RequireMetadata(lang="en-GB", pdfstandard="A-2b"),),
+    before_package=(InputPath("res/"), PassOption("xcolor", "table")),
+    after_package=(GraphicsPath("images/"), PdfInfo(Title="Rex")),
+)
+```
+"""
+
+import dataclasses
+import re
+from typing import ClassVar
+
+from .errors import DeclarationError
+from .types import Raw, pdf_escape
+
+BEFORE_CLASS, BEFORE_PACKAGE, AFTER_PACKAGE = "before_class", "before_package", "after_package"
+
+
+@dataclasses.dataclass(frozen=True)
+class PassOption:
+    """`\\PassOptionsToPackage{option}{package}`: before the package loads."""
+
+    package: str
+    option: str
+    slots: ClassVar[tuple[str, ...]] = (BEFORE_CLASS, BEFORE_PACKAGE)
+
+    def raw(self) -> Raw:
+        return Raw(f"\\PassOptionsToPackage{{{self.option}}}{{{self.package}}}")
+
+
+@dataclasses.dataclass(frozen=True, init=False)
+class InputPath:
+    """Where `\\input` and `\\usepackage` look: the package's own files must be found when it loads."""
+
+    dirs: tuple[str, ...]
+    slots: ClassVar[tuple[str, ...]] = (BEFORE_PACKAGE,)
+
+    def __init__(self, *dirs: str) -> None:
+        object.__setattr__(self, "dirs", dirs)
+
+    def raw(self) -> Raw:
+        return Raw(f"\\makeatletter\\def\\input@path{{{''.join(f'{{{d}}}' for d in self.dirs)}}}\\makeatother")
+
+
+@dataclasses.dataclass(frozen=True, init=False)
+class GraphicsPath:
+    """`\\graphicspath`: it needs graphicx, which the package loads. The current directory is the empty first group."""
+
+    dirs: tuple[str, ...]
+    include_cwd: bool
+    slots: ClassVar[tuple[str, ...]] = (AFTER_PACKAGE,)
+
+    def __init__(self, *dirs: str, include_cwd: bool = True) -> None:
+        object.__setattr__(self, "dirs", dirs)
+        object.__setattr__(self, "include_cwd", include_cwd)
+
+    def raw(self) -> Raw:
+        groups = ("{}" if self.include_cwd else "") + "".join(f"{{{d}}}" for d in self.dirs)
+        return Raw(f"\\graphicspath{{{groups}}}")
+
+
+@dataclasses.dataclass(frozen=True, init=False)
+class RequireMetadata:
+    """`\\DocumentMetadata{key=value, ...}`: before `\\documentclass`. A value with `,` `=` or a space is braced."""
+
+    entries: tuple[tuple[str, str], ...]
+    slots: ClassVar[tuple[str, ...]] = (BEFORE_CLASS,)
+
+    def __init__(self, **entries: str) -> None:
+        object.__setattr__(self, "entries", tuple(entries.items()))
+
+    def raw(self) -> Raw:
+        def value(v: str) -> str:
+            return f"{{{v}}}" if any(c in v for c in ",= ") else v
+
+        return Raw(f"\\DocumentMetadata{{{', '.join(f'{k}={value(v)}' for k, v in self.entries)}}}")
+
+
+@dataclasses.dataclass(frozen=True, init=False)
+class PdfInfo:
+    """`PdfInfo(Title="Rex")`: entries of the PDF Info dictionary. Each value is PDF-escaped and written through
+    `pdfmanagement_add:nnn`, so any text reaches the PDF as it is (§21a 9); the route needs `\\DocumentMetadata`, so a
+    document with one has a `RequireMetadata` in `before_class` (`TM-C009`). A key is letters only (`TM-M035`)."""
+
+    entries: tuple[tuple[str, str], ...]
+    slots: ClassVar[tuple[str, ...]] = (BEFORE_PACKAGE, AFTER_PACKAGE)
+
+    def __init__(self, **entries: str) -> None:
+        if bad := [k for k in entries if not re.fullmatch(r"[A-Za-z]+", k)]:
+            raise DeclarationError(f"PdfInfo key {bad[0]!r}: letters only", code="TM-M035", path="PdfInfo")
+        object.__setattr__(self, "entries", tuple(entries.items()))
+
+    def raw(self) -> Raw:
+        return Raw(
+            "\n".join(
+                f"\\csname pdfmanagement_add:nnn\\endcsname{{Info}}{{{k}}}{{(\\detokenize{{{pdf_escape(v)}}})}}"
+                for k, v in self.entries
+            )
+        )
+
+
+type Entry = PassOption | InputPath | GraphicsPath | RequireMetadata | PdfInfo
+
+
+def tex_of(item: Raw | Entry) -> Raw:
+    """The `Raw` a slot item stands for."""
+    return item if isinstance(item, Raw) else item.raw()

texmodel/spec.py

@@ -0,0 +1,235 @@
+"""A Doc from plain data and back (D2, S): `from_dict`, `to_dict` and `json_schema`, built on pydantic.
+
+Data is what TOML or JSON gives: a component is a dict with its fields, an environment also has `content`, a list of
+children, and a child names its component with `"type"`:
+
+```python
+from_dict(Card, {"content": [
+    {"type": "CardFront", "content": [{"type": "CardImage", "path": "a.jpg"}]},
+    {"type": "CardBack", "content": [{"type": "Name", "text": "Fox"}, {"type": "LeadFact", "text": "..."}]},
+]})
+```
+
+Fields are coerced as pydantic does by default (a `Raw` field takes a string). Everything wrong is reported at once,
+as an `ExceptionGroup` of `ValidationError`, each with the path `validate()` would give it; the grammar (counts and
+order, M4) is checked by `validate()` on the result, so a document that loads is not yet a valid one.
+"""
+
+import typing
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from typing import Annotated, Any
+
+import pydantic
+from pydantic.json_schema import GenerateJsonSchema, JsonSchemaMode
+
+from .body import Comment
+from .components import Command, Environment, Node, Passthrough, Value
+from .errors import ValidationError, Violation
+from .package import Package
+from .types import Choice, Raw
+
+_MODELS: dict[tuple[type[Environment], tuple[type[Comment], ...]], type[pydantic.BaseModel]] = {}
+_COMMENT_MODELS: dict[type[Comment], type[pydantic.BaseModel]] = {}
+
+
+def _tag(value: object) -> object:
+    return value.get("type") if isinstance(value, Mapping) else type(value).__name__  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
+
+
+def _renamer(cls: type[Command] | type[Environment] | type[Passthrough]) -> Callable[[object], object]:
+    """A before-validator that moves a field's old key (`field(renamed_from=)`) to its name; both given is an error."""
+    old = {a.renamed_from: a.name for a in cls.__tm_args__ if a.renamed_from}
+
+    def rename(data: object) -> object:
+        if not old or not isinstance(data, Mapping):
+            return data
+        out = dict(typing.cast("Mapping[str, object]", data))
+        for was, name in old.items():
+            if was in out:
+                if name in out:
+                    raise ValueError(f"{name!r} and its old name {was!r} are both given")
+                out[name] = out.pop(was)
+        return out
+
+    return rename
+
+
+def _same(data: object) -> object:
+    return data
+
+
+def _comment_model(kind: type[Comment]) -> type[pydantic.BaseModel]:
+    if kind not in _COMMENT_MODELS:
+        fields: dict[str, Any] = dict.fromkeys(kind.__tm_fields__, (str, ...))
+        _COMMENT_MODELS[kind] = pydantic.create_model(kind.__name__, __doc__=kind.__doc__, **fields)
+        _COMMENT_MODELS[kind].__tm_cls__ = kind  # pyright: ignore[reportAttributeAccessIssue]
+    return _COMMENT_MODELS[kind]
+
+
+def _model(cls: type[Environment], comments: tuple[type[Comment], ...]) -> type[pydantic.BaseModel]:
+    """The pydantic model of an environment: `content` limited to its grammar's components and to `Comment` and
+    `comments` (a comment is not in a grammar), and its arguments."""
+    if (cls, comments) not in _MODELS:
+        members: list[tuple[Any, Callable[[object], object]]] = []
+        for t in cls.__tm_grammar__:
+            kind = typing.cast("type[Command] | type[Environment] | type[Passthrough]", t.kind)
+            members.append((_model(kind, comments) if issubclass(kind, Environment) else kind, _renamer(kind)))
+        members += [(_comment_model(c), _same) for c in (Comment, *comments)]
+        tagged = tuple(Annotated[m, pydantic.BeforeValidator(r), pydantic.Tag(m.__name__)] for m, r in members)
+        fields: dict[str, Any] = {"content": (list[Annotated[typing.Union[tagged], pydantic.Discriminator(_tag)]], ...)}  # noqa: UP007
+        for a in cls.__tm_args__:
+            kind = a.choice or (Raw if a.raw else str)
+            fields[a.name] = (kind | None, None) if a.optional else (kind, ...)
+        _MODELS[cls, comments] = pydantic.create_model(cls.__name__, **fields)
+        _MODELS[cls, comments].__tm_cls__ = cls  # pyright: ignore[reportAttributeAccessIssue]
+    return _MODELS[cls, comments]
+
+
+def _node(value: Any) -> Node:  # noqa: ANN401  # an instance of a model built at run time, or a Command
+    if isinstance(value, Command | Passthrough):
+        return value
+    cls: type[Environment] | type[Comment] = value.__tm_cls__
+    if issubclass(cls, Comment):
+        return cls(**{f: getattr(value, f) for f in cls.__tm_fields__})
+    args = {a.name: getattr(value, a.name) for a in cls.__tm_args__}
+    return cls(*(_node(c) for c in value.content), **args)
+
+
+def _path(root: str, loc: Sequence[str | int]) -> str:
+    """`('content', 1, 'LeadFact', 'text')` under `Card` is `Card/LeadFact[1].text`, as `validate()` writes it."""
+    path, index = root, None
+    for part in loc:
+        if part == "content":
+            continue
+        if isinstance(part, int):
+            index = part
+        elif index is not None:
+            path, index = f"{path}/{part}[{index}]", None
+        else:
+            path = f"{path}.{part}"
+    return path if index is None else f"{path}/content[{index}]"  # a child no component of the grammar fits
+
+
+def from_dict(
+    cls: type[Command] | type[Environment], data: Mapping[str, object], *, comments: Sequence[type[Comment]] = ()
+) -> Node:
+    """The node `data` describes, as an instance of `cls`; raises an `ExceptionGroup` of `ValidationError` (E2).
+    A child may also be a `Comment` (`"type": "Comment"`, `"text"`) or an instance of one of `comments`."""
+    try:
+        data = typing.cast("Mapping[str, object]", _renamer(cls)(data))
+    except ValueError as exc:  # a renamed key given with its new name too
+        raise ExceptionGroup(f"invalid {cls.__name__}", [Violation("TM-C020", cls.__name__, str(exc)).error()]) from exc
+    try:
+        if issubclass(cls, Command):
+            return pydantic.TypeAdapter(cls).validate_python(data)  # pyright: ignore[reportUnknownVariableType]
+        return _node(_model(cls, tuple(comments)).model_validate(data))
+    except pydantic.ValidationError as exc:
+        raise ExceptionGroup(
+            f"invalid {cls.__name__}",
+            [
+                Violation("TM-C020", _path(cls.__name__, e["loc"]), e["msg"]).error()
+                for e in exc.errors(include_url=False)
+            ],
+        ) from exc
+
+
+def to_dict(node: Node) -> dict[str, object]:
+    """The data of `node`, in the shape `from_dict` reads; an optional field that is `None` is left out."""
+    out: dict[str, object] = {"type": type(node).__name__}
+    if isinstance(node, Comment):
+        return out | {f: getattr(node, f) for f in node.__tm_fields__}
+    for a in type(node).__tm_args__:
+        value = getattr(node, a.name)
+        if value is not None:
+            out[a.name] = value.tex if isinstance(value, Raw) else value.name if isinstance(value, Choice) else value
+    if isinstance(node, Environment):
+        out["content"] = [to_dict(child) for child in node.content]
+    return out
+
+
+def _reachable(classes: Iterable[type]) -> dict[str, type]:
+    """The given classes and every component their grammars name, by class name."""
+    found: dict[str, type] = {}
+    todo = list(classes)
+    while todo:
+        cls = todo.pop()
+        if cls.__name__ not in found:
+            found[cls.__name__] = cls
+            todo += [t.kind for t in getattr(cls, "__tm_grammar__", ())]
+    return found
+
+
+def _requires_type(node: object) -> None:
+    """A child is one of several components, told apart by `"type"`: each branch of such a union requires it, so a
+    child's data matches exactly one branch."""
+    if isinstance(node, dict):
+        branches = typing.cast("dict[str, Any]", node).get("oneOf")
+        if isinstance(branches, list) and all("$ref" in b for b in typing.cast("list[dict[str, Any]]", branches)):
+            for branch in typing.cast("list[dict[str, Any]]", branches):
+                branch["required"] = ["type"]
+        for value in typing.cast("dict[str, Any]", node).values():
+            _requires_type(value)
+    elif isinstance(node, list):
+        for value in typing.cast("list[object]", node):
+            _requires_type(value)
+
+
+def _annotate(schema: dict[str, Any], classes: Iterable[type], comments: Iterable[type] = ()) -> None:
+    """Name every component by its `"type"` constant, and record `x-renamed-from` on each renamed field (§21a 15)."""
+    named = _reachable(classes)
+    kinds = {*named, *(c.__name__ for c in (Comment, *comments))}
+    for node in (schema, *schema.get("$defs", {}).values()):
+        title = str(node.get("title"))
+        if title in kinds:
+            node.setdefault("properties", {})["type"] = {"const": title}
+        for a in getattr(named.get(title), "__tm_args__", ()):
+            if a.renamed_from and a.name in node.get("properties", {}):
+                node["properties"][a.name]["x-renamed-from"] = a.renamed_from
+    _requires_type(schema)
+
+
+_VALUE_TYPES = {"Length": "string", "Colour": "string", "Bool": "boolean", "Text": "string", "Raw": "string"}
+
+
+def _package_schema(package: Package, comments: tuple[type[Comment], ...]) -> dict[str, Any]:
+    """One schema for a package: a `$defs` entry per command and environment, and `Value.<Name>` per value."""
+    nodes = [c for c in package.registered if issubclass(c, Command | Environment)]
+    inputs: list[tuple[str, JsonSchemaMode, Any]] = [
+        (
+            c.__name__,
+            "validation",
+            pydantic.TypeAdapter(c if issubclass(c, Command) else _model(c, comments)).core_schema,
+        )
+        for c in nodes
+    ]
+    _, defs = GenerateJsonSchema(ref_template="#/$defs/{model}").generate_definitions(inputs)
+    schema: dict[str, Any] = {"$defs": defs}
+    schema |= {"$schema": "https://json-schema.org/draft/2020-12/schema", "title": package.name}
+    for cls in package.registered:
+        if issubclass(cls, Value):
+            schema["$defs"][f"Value.{cls.__name__}"] = {
+                "title": cls.__name__,
+                "description": cls.__tm_doc__,
+                "type": _VALUE_TYPES[cls.__tm_kind__],
+            }
+    _annotate(schema, nodes, comments)
+    return schema
+
+
+def json_schema(
+    target: type[Command] | type[Environment] | Package, *, comments: Sequence[type[Comment]] = ()
+) -> dict[str, Any]:
+    """JSON Schema of the data `from_dict(cls, ..., comments=)` accepts; docstrings are descriptions. Given a `Package`,
+    one schema with a `$defs` entry for every registered component and value; a renamed field has `x-renamed-from`."""
+    if isinstance(target, Package):
+        return _package_schema(target, tuple(comments))
+    schema = (
+        pydantic.TypeAdapter(target).json_schema()
+        if issubclass(target, Command)
+        else _model(target, tuple(comments)).model_json_schema()
+    )
+    _annotate(schema, [target], comments)
+    return schema
+
+
+__all__ = ["ValidationError", "from_dict", "json_schema", "to_dict"]

texmodel/std/__init__.py

@@ -0,0 +1,37 @@
+r"""Headers for the standard TeX libraries a deck loads (one module per package, adopted: the interface only).
+
+Written for TeX Live `TEXLIVE`; `tests/test_std` compiles a call of every command against the reference image.
+A header covers what fits the model (required `{}` arguments and one leading `[]`); a library's own syntax
+(TikZ paths, key-value declarations) is written as `Passthrough` or `Raw`.
+
+```python
+from texmodel.std.graphicx import IncludeGraphics
+
+class Photo(Command):
+    '''A picture.'''
+    path: Text
+
+    def body(self):
+        yield IncludeGraphics.call(Hole("path"), options=Raw("width=\\linewidth"))   # \RequirePackage{graphicx}
+```
+"""
+
+TEXLIVE = "2025"
+MODULES = (
+    "latex",
+    "graphicx",
+    "xcolor",
+    "geometry",
+    "etoolbox",
+    "eso_pic",
+    "microtype",
+    "hyphenat",
+    "anyfontsize",
+    "calc",
+    "pdfrender",
+    "enumitem",
+    "adjustbox",
+    "tikz",
+    "tcolorbox",
+    "fontspec",
+)

texmodel/std/adjustbox.py

@@ -0,0 +1,19 @@
+r"""adjustbox: Boxes scaled, clipped and aligned by keys.
+
+A header (the package is adopted): it declares the interface, `texmodel` writes calls and never the package."""
+
+from texmodel.components import Command
+from texmodel.package import Package
+from texmodel.types import Raw
+
+package = Package("adjustbox", prefix="", adopted=True)
+
+
+@package.command
+class AdjustBox(Command):
+    r"""Adjust some content: `\adjustbox{max width=\linewidth}{content}`. (The environment form,
+    `\begin{adjustbox}{...}`, is the same macro; declare only one of the two.)"""
+
+    cs = "adjustbox"
+    options: Raw
+    content: Raw

texmodel/std/anyfontsize.py

@@ -0,0 +1,7 @@
+r"""anyfontsize: Any font size. Loaded with `Package.require`; it declares no commands.
+
+A header (the package is adopted): it declares the interface, `texmodel` writes calls and never the package."""
+
+from texmodel.package import Package
+
+package = Package("anyfontsize", prefix="", adopted=True)

texmodel/std/calc.py

@@ -0,0 +1,7 @@
+r"""calc: Arithmetic in lengths and counters. Loaded with `Package.require`; it declares no commands.
+
+A header (the package is adopted): it declares the interface, `texmodel` writes calls and never the package."""
+
+from texmodel.package import Package
+
+package = Package("calc", prefix="", adopted=True)

texmodel/std/enumitem.py

@@ -0,0 +1,18 @@
+r"""enumitem: List layout.
+
+A header (the package is adopted): it declares the interface, `texmodel` writes calls and never the package."""
+
+from texmodel.components import Command
+from texmodel.package import Package
+from texmodel.types import Raw
+
+package = Package("enumitem", prefix="", adopted=True)
+
+
+@package.command
+class SetList(Command):
+    r"""Change list settings: `\setlist[itemize]{noitemsep}`."""
+
+    cs = "setlist"
+    options: Raw
+    lists: Raw | None = None

texmodel/std/eso_pic.py

@@ -0,0 +1,49 @@
+r"""eso-pic: Material placed on every page, in absolute positions.
+
+A header (the package is adopted): it declares the interface, `texmodel` writes calls and never the package."""
+
+from texmodel.components import Command
+from texmodel.package import Package
+from texmodel.types import Raw
+
+package = Package("eso-pic", prefix="", adopted=True)
+
+
+@package.command
+class AddToShipoutPictureBG(Command):
+    r"""Add a picture behind the page content."""
+
+    cs = "AddToShipoutPictureBG"
+    code: Raw
+
+
+@package.command
+class AddToShipoutPictureFG(Command):
+    r"""Add a picture over the page content."""
+
+    cs = "AddToShipoutPictureFG"
+    code: Raw
+
+
+@package.command
+class AtPageLowerLeft(Command):
+    r"""Put material at the page's lower left corner."""
+
+    cs = "AtPageLowerLeft"
+    code: Raw
+
+
+@package.command
+class AtPageUpperLeft(Command):
+    r"""Put material at the page's upper left corner."""
+
+    cs = "AtPageUpperLeft"
+    code: Raw
+
+
+@package.command
+class AtPageCenter(Command):
+    r"""Put material at the page's centre."""
+
+    cs = "AtPageCenter"
+    code: Raw