texmodel 0.3.0__tar.gz → 0.3.1__tar.gz

{texmodel-0.3.0 → texmodel-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: texmodel
-Version: 0.3.0
+Version: 0.3.1
 Summary: Typed document-family models rendered to TeX, with an optional latexmk driver and verifier plugins.
 Author-Email: Ilja Orlovs <ilja@release.art>
 License-Expression: MIT
@@ -205,6 +205,22 @@ texmodel check     # exit 1 if a committed generated file is stale, missing or o
   is not a field, an argument the body never uses, unbalanced braces, a name collision.
 - **Typed**: `Fact("A soft woof.")` type-checks; fields are `Text`, `Raw` or either `| None`; values are `Length`, `CMYK`/`RGB`/`Gray` (components in [0, 1], no conversion between models) or `bool`.
 
+### Shared bases
+
+Components that repeat a body or a grammar share a base declared `abstract=True`. It carries fields, `body` (or `begin` and
+`end`) and `children`; it needs no docstring and may have any Python name (`_Image`); it is never registered
+(`TM-M043`), and its subclasses inherit all of it:
+
+```python
+class _Image(Command, abstract=True):
+    src: Text
+    def body(self): return r"\includegraphics{#src}"
+
+@pkg.command
+class Photo(_Image):
+    '''A photo.'''
+```
+
 ### Generating a body
 
 A body can also be built from pieces that are well-formed by construction, so a generator cannot write an unbalanced brace or
@@ -312,7 +328,9 @@ class Put(Command):                           # \put(1,2){x}
 - **Slots.** `{}` `[]` `()` `<>` or your own `Delimiter`; a `Star` or other token; a slot left out is not written, and an
   optional slot left out before a later optional one writes `fill=` (say `""` for empty brackets) or is refused
   (`Gap.REFUSE`); declaring two optionals without saying which is `TM-M037`. A `SlotGroup` is written together or not at all.
-  Optional and token fields are keyword-only in Python wherever they stand, so give an optional one `default=None`.
+  Optional and token fields are keyword-only in Python wherever they stand. Write an optional field with `arg(default=...)`
+  (`label: Text | None = arg(default=None)`): a type checker then reads it as keyword-only and accepts a required field after
+  it, where a plain `= None` is reported as a field-order error although it runs.
 - **Value types.** `Text` (escaped), `PdfString`, `Raw`, `Length` (`Length("2mm")`, or `Length.expr(r"\linewidth")` for a TeX
   expression), a colour model (`CMYK`, `RGB`, `Gray`) or a `ColourName` (`blue!50`), `int`, `float`, `bool` (`true`/`false`),
   a `Choice`, a tuple, `NamedTuple`, dataclass or model of those, a `list`, and a `KeyVals`. A wrong value is a violation

{texmodel-0.3.0 → texmodel-0.3.1}/README.md

@@ -186,6 +186,22 @@ texmodel check     # exit 1 if a committed generated file is stale, missing or o
   is not a field, an argument the body never uses, unbalanced braces, a name collision.
 - **Typed**: `Fact("A soft woof.")` type-checks; fields are `Text`, `Raw` or either `| None`; values are `Length`, `CMYK`/`RGB`/`Gray` (components in [0, 1], no conversion between models) or `bool`.
 
+### Shared bases
+
+Components that repeat a body or a grammar share a base declared `abstract=True`. It carries fields, `body` (or `begin` and
+`end`) and `children`; it needs no docstring and may have any Python name (`_Image`); it is never registered
+(`TM-M043`), and its subclasses inherit all of it:
+
+```python
+class _Image(Command, abstract=True):
+    src: Text
+    def body(self): return r"\includegraphics{#src}"
+
+@pkg.command
+class Photo(_Image):
+    '''A photo.'''
+```
+
 ### Generating a body
 
 A body can also be built from pieces that are well-formed by construction, so a generator cannot write an unbalanced brace or
@@ -293,7 +309,9 @@ class Put(Command):                           # \put(1,2){x}
 - **Slots.** `{}` `[]` `()` `<>` or your own `Delimiter`; a `Star` or other token; a slot left out is not written, and an
   optional slot left out before a later optional one writes `fill=` (say `""` for empty brackets) or is refused
   (`Gap.REFUSE`); declaring two optionals without saying which is `TM-M037`. A `SlotGroup` is written together or not at all.
-  Optional and token fields are keyword-only in Python wherever they stand, so give an optional one `default=None`.
+  Optional and token fields are keyword-only in Python wherever they stand. Write an optional field with `arg(default=...)`
+  (`label: Text | None = arg(default=None)`): a type checker then reads it as keyword-only and accepts a required field after
+  it, where a plain `= None` is reported as a field-order error although it runs.
 - **Value types.** `Text` (escaped), `PdfString`, `Raw`, `Length` (`Length("2mm")`, or `Length.expr(r"\linewidth")` for a TeX
   expression), a colour model (`CMYK`, `RGB`, `Gray`) or a `ColourName` (`blue!50`), `int`, `float`, `bool` (`true`/`false`),
   a `Choice`, a tuple, `NamedTuple`, dataclass or model of those, a `list`, and a `KeyVals`. A wrong value is a violation

{texmodel-0.3.0 → texmodel-0.3.1}/pyproject.toml

@@ -20,7 +20,7 @@ dependencies = [
     "typer>=0.27.3",
     "pydantic>=2.14.1",
 ]
-version = "0.3.0"
+version = "0.3.1"
 
 [project.optional-dependencies]
 proof-pdf = [

{texmodel-0.3.0 → texmodel-0.3.1}/src/texmodel/components.py

@@ -200,6 +200,7 @@ class _Meta(type):
 
 
 def _document(cls: type) -> str:
+    """The docstring of a component, which must be documented and named as a TeX control word would be."""
     check_name(cls.__name__, "component")
     doc = (cls.__dict__.get("__doc__") or "").strip()
     if not doc:
@@ -208,13 +209,18 @@ def _document(cls: type) -> str:
 
 
 def _source(cls: type, name: str) -> Source | None:
-    """The class's own `body` / `begin` / `end` as (pieces, origin), or None.
+    """The class's `body` / `begin` / `end` as (pieces, origin), or None: its own, else the nearest base class's (a
+    shared base is declared `abstract=True`).
 
-    It is a string, a `TemplateRef` (the file is read now), a `TexRaw`, a `Ref`, a `Comment`, a sequence, iterator or
-    generator of those, or a method returning any of them. A field of that name is not a body.
+    It is a string, a `TemplateRef` (the file is read now, relative to the module that wrote it), a `TexRaw`, a `Ref`,
+    a `Comment`, a sequence, iterator or generator of those, or a method returning any of them. A field of that name
+    is not a body.
     """
-    found: object = cls.__dict__.get(name)
-    if found is None or name in inspect.get_annotations(cls):
+    owner = next((k for k in cls.__mro__ if name in k.__dict__), None)
+    if owner is None:
+        return None
+    found: object = owner.__dict__[name]
+    if found is None or name in inspect.get_annotations(owner):
         return None
     if isinstance(found, types.FunctionType):
         try:
@@ -238,7 +244,7 @@ def _source(cls: type, name: str) -> Source | None:
     out: list[Resolved] = []
     for piece in given:
         if isinstance(piece, TemplateRef):
-            text = template_text(piece, sys.modules[cls.__module__].__file__ or ".", f"{cls.__qualname__}.{name}")
+            text = template_text(piece, sys.modules[owner.__module__].__file__ or ".", f"{cls.__qualname__}.{name}")
             out.append(TexRaw(text, piece.whitespace, piece.syntax))
             origins.append(piece.path.name)
         else:
@@ -248,9 +254,15 @@ def _source(cls: type, name: str) -> Source | None:
 
 
 def control_name(cls: type) -> str:
-    """The control sequence of a registered component, without the backslash: its `cs`, else its package's prefix and
-    its class name."""
+    """The control sequence of a registered component or value, without the backslash: its `cs`, else its package's
+    prefix and its class name. A colour is not a control sequence (`TM-M042`)."""
     name: str | None = getattr(cls, "__tm_cs__", None)
+    if name is None and isinstance(getattr(cls, "__tm_kind__", None), ValueKind) and hasattr(cls, "__tm_prefix__"):
+        raise DeclarationError(
+            f"{cls.__qualname__}: a colour has no control sequence",
+            code="TM-M042",
+            hint="its name is `colour_name`, else prefix-kebab (xcolor's namespace)",
+        )
     if name is None:
         raise DeclarationError(
             f"{cls.__qualname__}: not registered with a package", code="TM-M019", hint="decorate it with @pkg.command"
@@ -261,6 +273,9 @@ def control_name(cls: type) -> str:
 class _Node(metaclass=_Meta):
     """What a `Command` and an `Environment` share: declaration data, `repr`, `validate` and `render`."""
 
+    __tm_abstract__: ClassVar[
+        bool
+    ]  # a shared base (`abstract=True`): fields and a body for subclasses, never registered
     __tm_unused__: ClassVar[tuple[str, ...]]
     __tm_args__: ClassVar[tuple[Arg, ...]]
     __tm_doc__: ClassVar[str]
@@ -295,9 +310,11 @@ def _as_field(given: object) -> "dataclasses.Field[object]":
     return typing.cast("dataclasses.Field[object]", dataclasses.field(default=given))
 
 
-def _build(cls: type[_Node], unused: Sequence[str], *, init: bool) -> None:
-    """Turn a declared class into a frozen dataclass whose fields are its arguments."""
-    cls.__tm_doc__ = doc = _document(cls)
+def _build(cls: type[_Node], unused: Sequence[str], *, init: bool, abstract: bool) -> None:
+    """Turn a declared class into a frozen dataclass whose fields are its arguments. An abstract base needs no name a
+    control word could have and no docstring: it is never registered."""
+    cls.__tm_abstract__ = abstract
+    cls.__tm_doc__ = doc = "" if abstract else _document(cls)
     cls.__tm_unused__ = tuple(unused)
     if "cs" in cls.__dict__:
         Cs(cls.__dict__["cs"], cls.syntax)  # a control word of the class's syntax (TM-M027)
@@ -334,10 +351,10 @@ class Command(_Node):
 
     __tm_inline__: ClassVar[Source | None]
 
-    def __init_subclass__(cls, *, unused: Sequence[str] = (), **kwargs: Any) -> None:
+    def __init_subclass__(cls, *, unused: Sequence[str] = (), abstract: bool = False, **kwargs: Any) -> None:
         super().__init_subclass__(**kwargs)
         cls.__tm_inline__ = _source(cls, "body")
-        _build(cls, unused, init=True)
+        _build(cls, unused, init=True, abstract=abstract)
 
     @classmethod
     def call(cls, *required: ArgValue, **optional: ArgValue) -> Ref:
@@ -356,11 +373,11 @@ class Environment(_Node):
     __tm_inline__: ClassVar[tuple[Source | None, Source | None]]
     __tm_grammar__: ClassVar[tuple[Repeat | Anywhere, ...]]
 
-    def __init_subclass__(cls, *, unused: Sequence[str] = (), **kwargs: Any) -> None:
+    def __init_subclass__(cls, *, unused: Sequence[str] = (), abstract: bool = False, **kwargs: Any) -> None:
         super().__init_subclass__(**kwargs)
         cls.__tm_inline__ = (_source(cls, "begin"), _source(cls, "end"))
         cls.__tm_grammar__ = _grammar(cls)
-        _build(cls, unused, init=False)
+        _build(cls, unused, init=False, abstract=abstract)
 
     @classmethod
     def open(cls, **args: ArgValue) -> Ref:
@@ -466,7 +483,7 @@ def _repr(node: Command | Environment | Passthrough) -> str:
 
 def _grammar(cls: type[Environment]) -> tuple[Repeat | Anywhere, ...]:
     terms: list[Repeat | Anywhere] = []
-    for item in cls.__dict__.get("children", ()):
+    for item in cls.children:  # inherited from a shared base, or its own
         if isinstance(item, type) and issubclass(item, Command | Environment | Passthrough):
             item = Repeat(item, 1, 1)
         if not isinstance(item, Repeat | Anywhere) or not issubclass(item.kind, _Node):
@@ -801,6 +818,13 @@ class Value[T]:
     __tm_doc__: ClassVar[str]
     __tm_kind__: ClassVar[ValueKind]
     __tm_prefix__: ClassVar[str]
+    __tm_cs__: ClassVar[str]  # the control sequence, once registered (not for a colour); see `control_name`
+
+    @classmethod
+    def declared_default(cls) -> T | None:
+        """The class's `default` (None when it has none): reading `default` through a class is ambiguous to a type
+        checker, this is not."""
+        return getattr(cls, "default", None)
 
     def __init__(self, value: T) -> None:
         """A document's setting for this value (D1a): `FactGap(Length("3mm"))`, checked against the declared type."""

{texmodel-0.3.0 → texmodel-0.3.1}/src/texmodel/package.py

@@ -114,6 +114,16 @@ class _Defs(NamedTuple):
         return [*(("control", n) for n in self.controls), *sorted(self.others)]
 
 
+def _concrete(cls: type[Command] | type[Environment]) -> None:
+    if cls.__tm_abstract__:
+        raise DeclarationError(
+            f"{cls.__qualname__}: an abstract base is not registered",
+            code="TM-M043",
+            path=cls.__name__,
+            hint="register the subclasses",
+        )
+
+
 def _shown(kind: str, name: str) -> str:
     return f"\\{name}" if kind == "control" else f"{kind} {name}"
 
@@ -194,6 +204,7 @@ class Package:
 
     def command[C: type[Command]](self, cls: C) -> C:
         """Register a command class."""
+        _concrete(cls)
         spec = spec_of(cls, declared_only=self.adopted, whitespace=self.whitespace)
         self._own_library(cls)
         if not self.adopted and cls.defined_by is None:
@@ -254,6 +265,7 @@ class Package:
 
     def environment[E: type[Environment]](self, cls: E) -> E:
         """Register an environment class: `\\newenvironment` with its begin and end bodies."""
+        _concrete(cls)
         spec = env_spec_of(cls, declared_only=self.adopted, whitespace=self.whitespace)
         self._own_library(cls)
         if not self.adopted and cls.defined_by is None:
@@ -283,6 +295,8 @@ class Package:
             for table, key, shown in spec.kind.claims(*addressed(self.prefix, spec.name, spec.cs), spec.alias)
         ]
         self._add(spec, *claims, rendered=cls.defined_by is None)
+        if not spec.kind.named:  # a colour is not a control sequence
+            cls.__tm_cs__ = "".join(addressed(self.prefix, spec.name, spec.cs))
         cls.__tm_prefix__ = self.prefix
         self._classes.append(cls)
         return cls

{texmodel-0.3.0 → texmodel-0.3.1}/tests/test_texmodel/test_parts.py

@@ -302,3 +302,102 @@ def test_colour_components_are_written_to_five_decimals():
 
     assert str(RGB(78.8 / 100, 0, 1 / 3)) == "0.788,0,0.33333"
     assert str(CMYK(0.1 + 0.2, 1, 0.000004, 0.5)) == "0.3,1,0,0.5"
+
+
+def test_a_shared_base_carries_fields_and_bodies_for_its_subclasses():
+    from texmodel.components import Environment
+
+    p = Package("p", prefix="ac")
+
+    @p.command
+    class Fact(Command, unused=("text",)):
+        """A fact."""
+
+        text: Text
+
+        def body(self):
+            return r"#text"
+
+    class _Image(Command, abstract=True):  # no docstring, and a name a control word could not have
+        src: Text
+
+        def body(self):
+            return r"\includegraphics{#src}"
+
+    class _Panel(Environment, abstract=True):
+        children = [Fact.times(2, 3)]
+
+        def begin(self):
+            return r"\begin{minipage}{\linewidth}"
+
+        def end(self):
+            return r"\end{minipage}"
+
+    @p.command
+    class Photo(_Image):
+        """A photo."""
+
+    @p.command
+    class Icon(_Image):
+        """An icon."""
+
+    @p.environment
+    class Card(_Panel):
+        """A card."""
+
+    out = p.render()
+    assert out.count("\\includegraphics{#1}") == 2 and "\\newcommand{\\acPhoto}[1]{%" in out
+    assert out.count("\\begin{minipage}{\\linewidth}") == 1 and Photo("a.png").render() == "\\acPhoto{a.png}"
+    assert [v.code for v in Card(Fact("a")).validate()] == ["TM-C002"]  # the base's grammar: 2 to 3 facts
+    with pytest.raises(DeclarationError, check=lambda e: e.code == "TM-M043"):
+        p.command(_Image)
+
+
+def test_a_value_has_a_control_sequence_and_a_default_a_type_checker_can_read():
+    from texmodel.components import Value, control_name
+    from texmodel.types import RGB, Colour, Length
+
+    p = Package("p", prefix="ac")
+
+    @p.value
+    class Gap(Value[Length]):
+        """Gap."""
+
+        default = Length("2mm")
+
+    @p.value
+    class Crop(Value[bool]):
+        """Crop."""
+
+        cs = "acshowcrop"
+        default = True
+
+    @p.value
+    class Ink(Value[Colour]):
+        """Ink."""
+
+        default = RGB(0, 0, 0)
+
+    assert control_name(Gap) == "acGap" and control_name(Crop) == "acshowcrop"
+    assert Gap.declared_default() == Length("2mm") and Crop.declared_default() is True
+    with pytest.raises(DeclarationError, check=lambda e: e.code == "TM-M042"):
+        control_name(Ink)
+
+
+def test_a_field_called_body_is_a_field_not_a_body():
+    from texmodel.interface import arg
+
+    p = Package("p", prefix="ac")
+
+    class Note(Command, unused=("body",)):
+        """A note."""
+
+        text: Text
+        body: Text | None = arg(default=None)
+
+        def end(self):  # not a body either: only `body` is read for a command
+            return ""
+
+    assert Note.__tm_inline__ is None and [a.name for a in Note.__tm_args__] == ["text", "body"]
+    with pytest.raises(DeclarationError, check=lambda e: e.code == "TM-M006"):
+        p.command(Note)