texpkg 0.2.0__tar.gz → 0.2.2__tar.gz

{texpkg-0.2.0 → texpkg-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: texpkg
-Version: 0.2.0
+Version: 0.2.2
 Summary: LaTeX package management.
 Author-Email: Ilja Orlovs <ilja@release.art>
 License-Expression: MIT

{texpkg-0.2.0 → texpkg-0.2.2}/pyproject.toml

@@ -20,7 +20,7 @@ dependencies = [
     "texmodel>=0.7.0",
     "pydantic>=2.14.1",
 ]
-version = "0.2.0"
+version = "0.2.2"
 
 [project.optional-dependencies]
 build = [

{texpkg-0.2.0 → texpkg-0.2.2}/src/texpkg/_internal/adopt.py

@@ -7,6 +7,7 @@ left aborts with the report.
 """
 
 import copy
+import dataclasses
 import re
 from collections.abc import Iterator, Mapping, Sequence
 from typing import Any, cast
@@ -110,6 +111,39 @@ def _extras_problems(kind: Kind, package: Package, data: dict[str, Any]) -> tupl
     return extras, state.not_allowed(kind, extras)
 
 
+def kind_default_changes(
+    package: Package,
+    extras: Extras,
+    saved: Mapping[str, Any],
+    current: Mapping[str, Any],
+    policy: DefaultChange | Mapping[str, DefaultChange],
+) -> tuple[Extras, list[dict[str, Any]]]:
+    """Apply the consumer's policy to every kind default this release changed (V22), for a value the document does
+    not set itself: following needs nothing (the kind writes the new default); a frozen one becomes a setting of the
+    document with the old value; one that asks is returned as unresolved. The key is the value's class name, the path
+    `/defaults/<class>`."""
+    own = {type(v).__name__ for v in extras.settings}
+    frozen: list[Any] = []
+    asked: list[dict[str, Any]] = []
+    for name in sorted(saved.keys() & current.keys()):
+        if saved[name] == current[name] or name in own:
+            continue
+        action = _policy(policy, f"/defaults/{name}", name)
+        if action is DefaultChange.FREEZE:
+            frozen.append(saved[name])
+        elif action is DefaultChange.ASK:
+            reason = f"the default of {name} changed from {saved[name]!r} to {current[name]!r}"
+            asked.append({"path": f"/defaults/{name}", "reason": reason, "value": saved[name], "boundary": "defaults"})
+    if not frozen:
+        return extras, asked
+    try:
+        kept = state.extras_from(package, {"settings": frozen}).settings
+    except ExceptionGroup as group:
+        reason = "; ".join(str(e) for e in group.exceptions)
+        return extras, [*asked, {"path": "/defaults", "reason": reason, "value": frozen, "boundary": "defaults"}]
+    return dataclasses.replace(extras, settings=(*extras.settings, *kept)), asked
+
+
 def adopt(
     *,
     kind: Kind,
@@ -120,6 +154,8 @@ def adopt(
     consumer: Sequence[Migration],
     policy: DefaultChange | Mapping[str, DefaultChange],
     saved_defaults: Mapping[str, Any] | None,
+    saved_kind_defaults: Mapping[str, Any] | None = None,
+    kind_defaults: Mapping[str, Any] | None = None,
     base_data: Mapping[int, int] | None = None,
 ) -> tuple[Node, Extras]:
     """The tree and extras of `kind` that `envelope` describes at `data` version `current`, or a `MigrationError` naming
@@ -141,6 +177,9 @@ def adopt(
     schema = state.tree_schema(kind.model, "validation")
     extras, found = _extras_problems(kind, package, extras_data)
     left += [{**p, "boundary": "validation"} for p in found]
+    if saved_kind_defaults is not None and not found:
+        extras, asked = kind_default_changes(package, extras, saved_kind_defaults, kind_defaults or {}, policy)
+        left += asked
     left += [{**p, "boundary": "validation"} for p in unplaced(tree, schema)]
     left += [{**p, "boundary": "validation"} for p in problems(kind.model, state.given(tree), schema)]
     if left:

{texpkg-0.2.0 → texpkg-0.2.2}/src/texpkg/_internal/handedits.py

@@ -19,13 +19,14 @@ _SETTING = re.compile(r"settings\[(\d+)\]")
 _ENTRY = re.compile(r"preamble\.(before_class|before_package|after_package)\[(\d+)\]")
 
 
-def extra_path(plan_path: str, *, locked: int, layout: PreambleSlots) -> str:
+def extra_path(plan_path: str, *, locked: int, leading: PreambleSlots) -> str:
     """The data path of a line that a setting or a preamble entry of the document wrote (D10), or `""`: the kind's own
-    `locked` settings come first in the plan, then the document's, and the layout's lines lead each preamble slot."""
+    `locked` settings come first in the plan, then the document's, and the `leading` entries (the layout's and the
+    kind's locked ones) lead each preamble slot."""
     if found := _SETTING.fullmatch(plan_path):
         return f"/settings/{int(found[1]) - locked}" if int(found[1]) >= locked else ""
     if found := _ENTRY.fullmatch(plan_path):
-        own = int(found[2]) - len(getattr(layout, found[1]))
+        own = int(found[2]) - len(getattr(leading, found[1]))
         return f"/preamble/{found[1]}/{own}" if own >= 0 else ""
     return ""
 

{texpkg-0.2.0 → texpkg-0.2.2}/src/texpkg/_internal/release.py

@@ -69,7 +69,19 @@ class Release:
         """What a document of `kind` is written with (L8): for a profile kind, the base kind's presets first, then
         its own locks, then the variant's."""
         base = self.dist.base_kind(kind)
-        return (*(base.presets if base else ()), *kind.settings(variant))
+        return (*(base.presets if base else ()), *kind.settings(variant), *self.kind_defaults(kind))
+
+    def kind_defaults(self, kind: Kind) -> tuple[AnyValue, ...]:
+        """Where a document of `kind` starts for the values it may set: a profile's base kind's, then its own (V21)."""
+        base = self.dist.base_kind(kind)
+        return (*(base.defaults if base else ()), *kind.defaults)
+
+    def kind_defaults_state(self, kind: Kind) -> dict[str, Any]:
+        """The settable ones among them, by class name, in the data shape of a setting: what the template state keeps
+        to tell, at `load`, a default the kind has changed."""
+        found = tuple(v for v in self.kind_defaults(kind) if type(v) in kind.settable)
+        data = state.extras_state(Extras(settings=found)).get("settings", [])
+        return json.loads(dumps({type(v).__name__: d for v, d in zip(found, data, strict=True)}))
 
     def _has_graphics(self, kind: Kind) -> bool:
         kinds = (kind.name, *([kind.over] if kind.over else []))
@@ -79,21 +91,32 @@ class Release:
         """The lines that find the payload, which come before a document's own entries (A5)."""
         return self.dist.layout.preamble(graphics=self._has_graphics(kind))
 
+    def fixed_preamble(self, kind: Kind) -> PreambleSlots:
+        """What leads each preamble slot of every document of `kind`: the layout's lines, then the entries the base kind
+        locks (a profile's), then the kind's own (K020)."""
+        base = self.dist.base_kind(kind)
+        slots = [self.layout_preamble(kind), *([base.locked_preamble] if base else []), kind.locked_preamble]
+        return PreambleSlots(
+            before_class=tuple(e for s in slots for e in s.before_class),
+            before_package=tuple(e for s in slots for e in s.before_package),
+            after_package=tuple(e for s in slots for e in s.after_package),
+        )
+
     def plan(self, kind: Kind, tree: Node, variant: str | None, extras: Extras = Extras()) -> Plan:  # noqa: B008
         """The `.tex` of `tree` as lines with provenance: the kind's presets, then the variant's settings (L8), then the
-        document's own settings (D10).
+        document's own settings (D10); in each preamble slot the fixed entries, then the document's own.
 
         An exposed base kind is written by the base's package; the directory's layout is this distribution's."""
         body = tree if kind.expand is None else kind.expand(tree)
         package = self.dist.owner(kind.name).package
-        found, own = self.layout_preamble(kind), extras.preamble
+        found, own = self.fixed_preamble(kind), extras.preamble
         return package.plan(
             TexDocument(
                 body,
-                options=extras.options,
+                options=kind.class_options(extras.options, variant),
                 settings=(*self.settings(kind, variant), *extras.settings),
                 preamble=PreambleSlots(
-                    before_class=own.before_class,
+                    before_class=(*found.before_class, *own.before_class),
                     before_package=(*found.before_package, *own.before_package),
                     after_package=(*found.after_package, *own.after_package),
                 ),
@@ -152,6 +175,7 @@ class Release:
                 for variant, name in kind.documents()
             },
             "defaults": state.defaults_table(kind.model),
+            "kind_defaults": self.kind_defaults_state(kind),
             "sty": state.sty_hashes(self.sty),
             "stack": self.stack(),
         }
@@ -289,6 +313,8 @@ class KindApi[T: Command | Environment]:
             consumer=migrations,
             policy=default_changes,
             saved_defaults=template.get("defaults"),
+            saved_kind_defaults=template.get("kind_defaults"),
+            kind_defaults=self.release.kind_defaults_state(self.kind),
             base_data=dict(self.release.contracts.base_data) if self.kind.name in self.release.dist.expose else None,
         )
         return Document(cast("T", tree), path, self.release, self.kind, extras)

{texpkg-0.2.0 → texpkg-0.2.2}/src/texpkg/_internal/state.py

@@ -84,6 +84,7 @@ def not_allowed(kind: Kind, extras: Extras) -> list[dict[str, Any]]:
     data = extras_state(extras)
     settable = {c.__name__ for c in kind.settable}
     entries = {c.__name__ for c in kind.preamble}
+    locked = set(kind.locked_classes())
     found = [
         (f"/settings/{i}", f"{type(v).__name__} is not settable in kind {kind.name}", data["settings"][i])
         for i, v in enumerate(extras.settings)
@@ -97,7 +98,9 @@ def not_allowed(kind: Kind, extras: Extras) -> list[dict[str, Any]]:
     found += [
         (
             f"/preamble/{slot}/{i}",
-            f"{type(item).__name__} is not an allowed preamble entry in kind {kind.name}",
+            f"{type(item).__name__} is locked by kind {kind.name}"
+            if type(item).__name__ in locked
+            else f"{type(item).__name__} is not an allowed preamble entry in kind {kind.name}",
             data["preamble"][slot][i],
         )
         for slot, i, item in extras.preamble.items()

{texpkg-0.2.0 → texpkg-0.2.2}/src/texpkg/declaration.py

@@ -19,7 +19,7 @@ from texmodel.components import AnyValue, Command, Environment, Node, Passthroug
 from texmodel.document import OPTION
 from texmodel.interface import Body, BodyKind
 from texmodel.package import Package
-from texmodel.preamble import Entry
+from texmodel.preamble import Entry, PreambleSlots
 
 from .assets import Asset, Resolved
 from .errors import DeclarationError
@@ -36,10 +36,13 @@ type Model = type[Command] | type[Environment]
 
 @dataclasses.dataclass(frozen=True)
 class Variant:
-    """A named set of settings applied to the same document (K6): `doc.render(variant="compact")`."""
+    """A named set of settings and class options applied to the same document (K6): `doc.render(variant="compact")`.
+    The options are written after the document's own, and need not be among the kind's `options`: the variant is the
+    author's choice, not the document's."""
 
     name: str
     settings: tuple[AnyValue, ...] = ()
+    options: tuple[str, ...] = ()
 
     def __post_init__(self) -> None:
         if not _VARIANT.fullmatch(self.name):
@@ -50,6 +53,18 @@ class Variant:
                 hint="it is part of a file name: deck-<variant>.tex",
             )
         object.__setattr__(self, "settings", tuple(self.settings))
+        object.__setattr__(self, "options", tuple(self.options))
+        if bad := next((o for o in self.options if not OPTION.fullmatch(o)), None):
+            raise DeclarationError(
+                f"variant {self.name}: option {bad!r} is not a class option",
+                code="TP-K016",
+                path=self.name,
+                hint="letters, digits, '=', '.' and '-', starting with a letter or digit",
+            )
+        if twice := next((o for o in self.options if self.options.count(o) > 1), None):
+            raise DeclarationError(
+                f"variant {self.name}: option {twice!r} is declared twice", code="TP-K002", path=self.name
+            )
 
 
 @dataclasses.dataclass(frozen=True)
@@ -105,7 +120,10 @@ class Kind:
 
     A document may carry what the kind allows and nothing else: `settable` (values a document sets, after `presets`,
     which every document is written with), `options` (class options) and `preamble` (entry classes). A value is a preset
-    or settable, not both."""
+    or settable, not both. `defaults` are the kind's own start values for settable ones: written after the presets and
+    the variant's settings and before the document's own, so a document that sets the value overrides them (V21).
+    `locked_preamble` holds entries every document is written with, in the slots given, after
+    the layout's lines and before the document's own: a document may not carry an entry class that is locked."""
 
     name: str
     model: Model
@@ -120,9 +138,11 @@ class Kind:
     settable: tuple[type[Value[Any]], ...] = ()
     options: tuple[str, ...] = ()
     preamble: tuple[type[Entry], ...] = ()
+    locked_preamble: PreambleSlots = dataclasses.field(default_factory=PreambleSlots)
+    defaults: tuple[AnyValue, ...] = ()
 
     def __post_init__(self) -> None:
-        for field in ("presets", "migrations", "allow_raw", "variants", "settable", "options", "preamble"):
+        for field in ("presets", "migrations", "allow_raw", "variants", "settable", "options", "preamble", "defaults"):
             object.__setattr__(self, field, tuple(getattr(self, field)))
         if not _KIND.fullmatch(self.name) or keyword.iskeyword(self.name):
             raise DeclarationError(
@@ -173,6 +193,7 @@ class Kind:
         """What a document may carry (D10): no name twice, real class options, nothing both written and settable."""
         self._unique("settable value", [c.__name__ for c in self.settable])
         self._unique("preamble entry", [c.__name__ for c in self.preamble])
+        self._check_locked()
         self._unique("option", list(self.options))
         if bad := next((o for o in self.options if not OPTION.fullmatch(o)), None):
             raise DeclarationError(
@@ -189,6 +210,14 @@ class Kind:
                 path=self.name,
                 hint="a value is written for every document or set by a document, not both",
             )
+        self._unique("default", [type(v).__name__ for v in self.defaults])
+        if loose := next((v for v in self.defaults if type(v) not in self.settable), None):
+            raise DeclarationError(
+                f"kind {self.name}: a default for {type(loose).__name__}, which is not settable",
+                code="TP-K021",
+                path=self.name,
+                hint="a default is where a document starts for a value it may set: add the class to settable",
+            )
         object.__setattr__(self, "stem", self.stem or self.model.__name__.lower())
         if not _STEM.fullmatch(self.stem):
             raise DeclarationError(
@@ -198,6 +227,34 @@ class Kind:
                 hint="letters, digits, '_' and '-', e.g. stem='brand-deck' for brand-deck.tex",
             )
 
+    def locked_classes(self) -> tuple[str, ...]:
+        """The names of the entry classes the kind writes into every document."""
+        return tuple(type(item).__name__ for _, _, item in self.locked_preamble.items())
+
+    def _check_locked(self) -> None:
+        """Locked entries are typed, in a slot they fit, each class once, and not also allowed to a document (K020)."""
+        for slot, _, item in self.locked_preamble.items():
+            slots = getattr(item, "slots", ())
+            if slot not in slots:
+                raise self.locked_error(
+                    f"{type(item).__name__} cannot sit in {slot}" if slots else "is not a typed entry",
+                    f"a typed entry (RequireMetadata, PdfInfo, ...) in a slot it fits: {list(slots) or 'none'}",
+                    item,
+                )
+        names = self.locked_classes()
+        if twice := next((n for n in names if names.count(n) > 1), None):
+            raise self.locked_error("is locked twice", "lock each entry class once", twice)
+        if both := next((c for c in self.preamble if c.__name__ in names), None):
+            raise self.locked_error(
+                "is locked and also allowed to a document", "a class is locked or allowed, not both", both.__name__
+            )
+
+    def locked_error(self, what: str, hint: str, entry: object) -> DeclarationError:
+        name = entry if isinstance(entry, str) else type(entry).__name__
+        return DeclarationError(
+            f"kind {self.name}: locked preamble entry {name} {what}", code="TP-K020", path=self.name, hint=hint
+        )
+
     def _unique(self, what: str, names: list[str]) -> None:
         if twice := next((n for n in names if names.count(n) > 1), None):
             raise DeclarationError(
@@ -208,6 +265,11 @@ class Kind:
         """The `.tex` a save writes, as `(variant, file name)`: the kind's own, then one per variant (K7)."""
         return ((None, f"{self.stem}.tex"), *((v.name, f"{self.stem}-{v.name}.tex") for v in self.variants))
 
+    def class_options(self, own: tuple[str, ...], variant: str | None = None) -> tuple[str, ...]:
+        """The class options of a `.tex` (K6): the document's `own`, then the variant's that are not among them."""
+        found = next((v for v in self.variants if v.name == variant), None)
+        return (*own, *(o for o in (found.options if found else ()) if o not in own))
+
     def settings(self, variant: str | None = None) -> tuple[AnyValue, ...]:
         """What a document of the kind is written with (L8): the presets, then the settings of `variant`, if named."""
         if variant is None:
@@ -347,6 +409,15 @@ class Distribution:
             )
         if problem := self.expansion_problem(kind, kind.example()):
             raise self._bad_expansion(kind, problem)
+        base = offered[kind.over]
+        if clash := next((n for n in kind.locked_classes() if n in base.locked_classes()), None):
+            raise kind.locked_error(
+                "is locked by the base kind too", "the base kind's locked entries are written first", clash
+            )
+        if clash := next((c for c in kind.preamble if c.__name__ in base.locked_classes()), None):
+            raise kind.locked_error(
+                "is locked by the base kind", "a profile cannot allow what its base locks", clash.__name__
+            )
 
     def expansion_problem(self, kind: Kind, tree: Node) -> str | None:
         """Why `tree` of a profile kind does not expand to a valid tree of the base kind (L3); `None` if it does."""

{texpkg-0.2.0 → texpkg-0.2.2}/src/texpkg/document.py

@@ -169,7 +169,7 @@ class Document[T: Command | Environment]:
         own = handedits.extra_path(
             plan_path,
             locked=len(self._release.settings(self._kind, variant)),
-            layout=self._release.layout_preamble(self._kind),
+            leading=self._release.fixed_preamble(self._kind),
         )
         if own:
             return own

{texpkg-0.2.0 → texpkg-0.2.2}/src/texpkg_build/_internal/generate.py

@@ -155,9 +155,11 @@ def _tuple(items: list[str]) -> str:
     return "(" + "".join(f"{item!r}, " for item in items).strip() + ")"
 
 
-def sources(dist: Distribution, pointer_attr: str, version: str, contracts: Contracts) -> dict[str, str]:
-    """The generated files by path inside the module, for `dist` released at `version`. `pointer_attr` is the name
-    `[tool.texpkg] distribution` gives the declaration inside its package."""
+def sources(dist: Distribution, pointer: str, version: str, contracts: Contracts) -> dict[str, str]:
+    """The generated files by path inside the module, for `dist` released at `version`. `pointer` is the
+    `module:attribute` of `[tool.texpkg] distribution`: where the declaring package holds the declaration."""
+    module, _, pointer_attr = pointer.partition(":")
+    where = module.removeprefix(dist.declared_in)  # "" when the declaration is the package's `__init__`
     offered = dist.kinds_offered()
     names = [k.name for k in offered]
     sty = render_sty(dist, version)
@@ -233,7 +235,7 @@ def sources(dist: Distribution, pointer_attr: str, version: str, contracts: Cont
 
                 from texpkg._internal.release import Release
 
-                from ._declaration import {pointer_attr}
+                from ._declaration{where} import {pointer_attr}
                 from ._version import CONTRACTS, VERSION
                 {base_import}
 

{texpkg-0.2.0 → texpkg-0.2.2}/src/texpkg_build/_internal/generated.py

@@ -3,7 +3,9 @@
 `[tool.texpkg] generate = "module:function"` names a pure `function(root) -> {path: source}`, where `root` is the
 declaring package's directory and each path is relative to it. `texpkg-build generate` writes the files; the build runs
 the function again and refuses a file that is missing, differs (stale or hand-edited), or is left over from an earlier
-run. The function must not import the declaring package, whose `__init__` imports the files it produces.
+run. The function must not import a module that imports the files it produces, as the declaration does: keep the
+declaration in a module of its own (`pkg.declaration:dist`) and `pkg/__init__.py` free of imports, and the function can
+share the package's pure modules.
 """
 
 import importlib
@@ -20,8 +22,10 @@ HEADER = "# Generated by texpkg-build generate. Do not edit.\n# fmt: off\n"
 
 
 def package_directory(source: pathlib.Path, module: str) -> pathlib.Path:
-    """The directory of the declaring package `module`, found without importing it."""
-    return source.joinpath(*module.split("."))
+    """The directory of the declaring package, found without importing it: `module` itself when it is a package
+    (`pkg:dist`), else the package that holds it (`pkg.declaration:dist`), as `Distribution(declared_in)` is."""
+    path = source.joinpath(*module.split("."))
+    return path if path.is_dir() else path.parent
 
 
 def _function(pointer: str, isolation: Isolation) -> Callable[[pathlib.Path], Mapping[str, str]]:

{texpkg-0.2.0 → texpkg-0.2.2}/src/texpkg_build/hook.py

@@ -36,22 +36,17 @@ def _pointer(context: Context) -> tuple[str, str]:
 
 
 def pdm_build_initialize(context: Context) -> None:
-    """A wheel needs pydantic and nothing else: texmodel, texpkg and the bases are embedded in it (B7)."""
+    """A wheel needs pydantic and nothing else: texmodel, texpkg and the bases are embedded in it (B7). An editable
+    install embeds nothing, so it needs texpkg itself, which brings texmodel and pydantic."""
     metadata = context.config.metadata
-    metadata["dependencies"] = [PYDANTIC]
+    metadata["dependencies"] = ["texpkg"] if context.target == "editable" else [PYDANTIC]
     if "dynamic" in metadata and "dependencies" in metadata["dynamic"]:
         metadata["dynamic"].remove("dependencies")
 
 
 def pdm_build_update_files(context: Context, files: dict[str, pathlib.Path]) -> None:
-    if context.target == "sdist":
-        return
     if context.target != "wheel":
-        raise DeclarationError(
-            f"a {context.target} build of a texpkg package",
-            code="TP-B008",
-            hint="the module is generated from the declaration: test it with texpkg_build.testing.load_declaration",
-        )
+        return  # the sdist holds the sources, an editable install links them: the module is made for a wheel (B6)
     module, attr = _pointer(context)
     source = context.root / (context.config.build_config.package_dir or ".")
     with author_source(source) as isolation:
@@ -73,7 +68,7 @@ def pdm_build_update_files(context: Context, files: dict[str, pathlib.Path]) ->
         loaded = load_declaration(f"{module}:{attr}", version=version)
         checks.module_satisfies_the_protocols(loaded)
         contracts, held = checks.contract_gate(context.root, dist, loaded._bound.RELEASE, version)  # pyright: ignore[reportAttributeAccessIssue]
-        module_files = generate.sources(dist, attr, version, contracts)
+        module_files = generate.sources(dist, f"{module}:{attr}", version, contracts)
         files.clear()  # a wheel holds the generated module, not the author's sources
         embed.embed(
             context.build_dir / dist.module, dist, declaration, module_files, held

{texpkg-0.2.0 → texpkg-0.2.2}/src/texpkg_build/testing.py

@@ -54,7 +54,7 @@ def load_declaration(pointer: str, *, version: str = "0.0.0", contracts: Contrac
     root = pathlib.Path(scratch.name) / dist.module
     for loaded in [n for n in sys.modules if _is_under(n, dist.module)]:
         del sys.modules[loaded]
-    _write(dist, attr, version, contracts or Contracts(), root)
+    _write(dist, pointer, version, contracts or Contracts(), root)
     spec = importlib.util.spec_from_file_location(
         dist.module, root / "__init__.py", submodule_search_locations=[str(root)]
     )
@@ -102,16 +102,24 @@ class _Flatten(importlib.abc.MetaPathFinder, importlib.abc.Loader):
         """The module is the nested one, already running."""
 
 
-def _attribute_of(dist: Distribution) -> str:
-    """The name the declaration package gives `dist`, which a base's generated module imports it by."""
-    namespace = vars(importlib.import_module(dist.declared_in))
-    return next(name for name, value in namespace.items() if value is dist)
+def _pointer_of(dist: Distribution) -> str:
+    """The `module:attribute` a base's declaration is imported by: the module of its package that holds it."""
+    for name, module in sorted(sys.modules.items()):
+        if _is_under(name, dist.declared_in):
+            if attr := next((n for n, value in vars(module).items() if value is dist), None):
+                return f"{name}:{attr}"
+    raise DeclarationError(
+        f"{dist.name} is not held by a module of {dist.declared_in}",
+        code="TP-B003",
+        path=dist.name,
+        hint="declare the distribution at the top level of a module of its package",
+    )
 
 
-def _write(dist: Distribution, attr: str, version: str, contracts: Contracts, root: pathlib.Path) -> None:
+def _write(dist: Distribution, pointer: str, version: str, contracts: Contracts, root: pathlib.Path) -> None:
     """The generated module of `dist` in `root`, and in `root/_embedded/<base>` that of each base: embedding without
     copying, since the declarations are the modules already imported."""
-    for path, text in generate.sources(dist, attr, version, contracts).items():
+    for path, text in generate.sources(dist, pointer, version, contracts).items():
         (root / path).parent.mkdir(parents=True, exist_ok=True)
         (root / path).write_text(text, encoding="utf-8")
     if dist.base:
@@ -119,7 +127,7 @@ def _write(dist: Distribution, attr: str, version: str, contracts: Contracts, ro
         (root / "_embedded" / "__init__.py").write_text("", encoding="utf-8")
         _write(
             dist.base,
-            _attribute_of(dist.base),
+            _pointer_of(dist.base),
             dist.base.package.version,
             contracts,
             root / "_embedded" / dist.base.module,

{texpkg-0.2.0 → texpkg-0.2.2}/tests/fixtures/acme_deck/__init__.py

@@ -6,9 +6,10 @@ import pathlib
 # exported by its kinds).
 import acme_brand_tex  # pyright: ignore[reportMissingImports]
 from acme_brand_tex._declaration.model import FactGap, Ink  # pyright: ignore[reportMissingImports]
-from texmodel.types import Length
+from texmodel.preamble import PassOption, PreambleSlots, RequireMetadata
+from texmodel.types import CMYK, Length
 
-from texpkg import Asset, Distribution, Kind, Role
+from texpkg import Asset, Distribution, Kind, Role, Variant
 
 from .model import Brief, Heading, Headline, Point, Slide, Tint, expand, pkg
 
@@ -27,7 +28,17 @@ dist = Distribution(
     package=pkg,
     assets=(Asset("assets/DECK.txt", Role.NOTE, "what the deck package is"),),
     kinds=(
-        Kind("slide", Slide, presets=(), example=slide_example),
+        Kind(
+            "slide",
+            Slide,
+            presets=(),
+            example=slide_example,
+            preamble=(PassOption,),
+            settable=(Ink,),
+            defaults=(Ink(CMYK(0, 0, 0, 0.3)),),  # where a slide starts; a slide may set its own
+            variants=(Variant("review", options=("draft",)),),
+            locked_preamble=PreambleSlots(before_class=(RequireMetadata(pdfversion="2.0"),)),  # every slide has it
+        ),
         Kind(
             "brief",
             Brief,

{texpkg-0.2.0 → texpkg-0.2.2}/tests/test_build.py

@@ -179,11 +179,14 @@ def test_the_declaration_must_be_a_package(tmp_path):
     assert raised.value.code == "TP-B004"
 
 
-def test_an_editable_install_is_refused(project, tmp_path, monkeypatch):
+def test_an_editable_install_links_the_sources_and_needs_texpkg(project, tmp_path, monkeypatch):
     monkeypatch.chdir(project)
-    with pytest.raises(DeclarationError) as raised:
-        pdm.backend.build_editable(str(tmp_path / "dist"))
-    assert raised.value.code == "TP-B008"
+    built = tmp_path / "dist" / pdm.backend.build_editable(str(tmp_path / "dist"))
+    names = projects.names(built)
+    assert not any("acme_brand_tex" in n and n.endswith(".py") for n in names)  # no generated module
+    with zipfile.ZipFile(built) as z:
+        metadata = z.read(next(n for n in names if n.endswith("METADATA"))).decode()
+    assert "Requires-Dist: texpkg" in metadata and "pydantic" not in metadata
 
 
 def test_a_generated_module_that_breaks_the_protocol_is_refused(tmp_path, monkeypatch):

{texpkg-0.2.0 → texpkg-0.2.2}/tests/test_declaration.py

@@ -10,7 +10,7 @@ import pytest
 from acme_brand import Card, Compact, Deck, Fact, FactGap, Glossary, Ink, Mark, Term, Title, dist, expert_example
 from texmodel.components import Command, Environment, Passthrough, Value
 from texmodel.package import Package
-from texmodel.preamble import PdfInfo
+from texmodel.preamble import PassOption, PdfInfo, PreambleSlots, RequireMetadata
 from texmodel.types import Length, Raw, Text
 
 from texpkg import Asset, DefaultChange, Distribution, Kind, Migrated, Role, Variant, migration
@@ -262,12 +262,32 @@ def test_a_distribution_declared_in_a_zipped_package_checks_its_root_through_the
         ({"options": ("!",)}, "TP-K016"),
         ({"settable": (FactGap,)}, "TP-K017"),  # a preset of the kind
         ({"settable": (Compact,)}, "TP-K017"),  # a variant's setting
+        ({"locked_preamble": PreambleSlots(before_class=(Raw(r"\\x"),))}, "TP-K020"),  # not a typed entry
+        ({"locked_preamble": PreambleSlots(before_package=(RequireMetadata(lang="en"),))}, "TP-K020"),  # wrong slot
+        ({"locked_preamble": PreambleSlots(before_class=(PassOption("a", "b"), PassOption("c", "d")))}, "TP-K020"),
+        ({"locked_preamble": PreambleSlots(before_class=(RequireMetadata(lang="en"),))}, "TP-K020"),  # also allowed
     ],
 )
 def test_what_a_kind_lets_a_document_carry_is_checked(changes, code):
     assert code_of(dataclasses.replace, dist.kind("expert"), **changes) == code
 
 
+def test_a_variants_options_follow_the_documents_without_repeating_them():
+    expert = dist.kind("expert")
+    review = dataclasses.replace(expert, variants=(Variant("review", options=("draft", "a4paper")),))
+    assert review.class_options(("a4paper",), "review") == ("a4paper", "draft")
+    assert review.class_options(("a4paper",)) == ("a4paper",) and review.class_options((), "missing") == ()
+    assert code_of(Variant, "x", options=("two words",)) == "TP-K016"
+    assert code_of(Variant, "x", options=("draft", "draft")) == "TP-K002"
+
+
+def test_a_kind_locks_entries_of_classes_it_does_not_also_allow():
+    locked = PreambleSlots(before_class=(PassOption("xcolor", "table"),), before_package=(PassOption("a", "b"),))
+    assert code_of(dataclasses.replace, dist.kind("expert"), locked_preamble=locked) == "TP-K020"  # twice, in two slots
+    kind = dataclasses.replace(dist.kind("expert"), locked_preamble=PreambleSlots(before_class=locked.before_class))
+    assert kind.locked_classes() == ("PassOption",) and dist.kind("expert").locked_classes() == ()
+
+
 def test_a_settable_value_is_registered_by_the_package_that_reads_it_back():
     other = Package("other", prefix="ot", version="1.0.0", date="2026/10/22", description="Another")
 

{texpkg-0.2.0 → texpkg-0.2.2}/tests/test_embed.py

@@ -200,6 +200,7 @@ def test_a_wheel_installs_into_a_fresh_environment_that_has_only_pydantic(brand_
     report = json.loads(venvs.run(python, SCRIPT, tmp_path / "out", cwd=tmp_path))
     assert report["names"] == ["slide", "brief", "vocab"] and report["version"] == "0.1.0"
     assert report["slide"] == [
+        "_texpkg/plan-review.json",
         "_texpkg/plan.json",
         "_texpkg/state.json",
         "_texpkg/template.json",
@@ -210,6 +211,7 @@ def test_a_wheel_installs_into_a_fresh_environment_that_has_only_pydantic(brand_
         "res/texpkg/acme-brand.sty",
         "res/texpkg/acme-deck-provenance.sty",
         "res/texpkg/acme-deck.sty",
+        "slide-review.tex",
         "slide.tex",
     ]
     assert "res/texpkg/acme-brand.sty" in report["vocab"] and "glossary.tex" in report["vocab"]

{texpkg-0.2.0 → texpkg-0.2.2}/tests/test_end_to_end.py

@@ -122,8 +122,8 @@ def test_two_wheels_are_installed_used_saved_compiled_and_a_new_release_is_adopt
     ]
     sources = sorted((tmp_path / "docs").rglob("*.tex"))
     assert (
-        len(sources) == 3 + 1 + 1 + 1 + 1
-    )  # expert and its two variants, vocab, then the deck's brief, slide and vocab
+        len(sources) == 3 + 1 + 1 + 2 + 1
+    )  # expert and its two variants, vocab, then the deck's brief, slide and its variant, and vocab
     for source in sources:
         compiler.compile(
             source, tmp_path / "out" / source.parent.parent.name / source.parent.name / source.stem