refdef 0.1.0__py3-none-any.whl

refdef/__init__.py

@@ -0,0 +1,33 @@
+"""Reference designations as strict, typed, immutable values."""
+
+from refdef._check import check
+from refdef._parse import parse
+from refdef._render import render
+from refdef.designation import Designation
+from refdef.issues import Issue, IssueCode, Parsed
+from refdef.level import Aspect, Level
+from refdef.numbering import allocate, number_group
+from refdef.order import natural_key, sort_key
+from refdef.scheme import STANDARD, ClassEntry, Scheme
+from refdef.terminal import Signal, Terminal
+
+__all__ = [
+    "STANDARD",
+    "Aspect",
+    "ClassEntry",
+    "Designation",
+    "Issue",
+    "IssueCode",
+    "Level",
+    "Parsed",
+    "Scheme",
+    "Signal",
+    "Terminal",
+    "allocate",
+    "check",
+    "natural_key",
+    "number_group",
+    "parse",
+    "render",
+    "sort_key",
+]

refdef/__main__.py

@@ -0,0 +1,18 @@
+"""Command line: `python -m refdef api` prints the public surface."""
+
+import sys
+
+from refdef._api import DOORS, render
+
+
+def main(argv: list[str]) -> int:
+    """Run the one command, `api`; any other argument is a usage error (exit 2)."""
+    if argv != ["api"]:
+        sys.stderr.write("usage: python -m refdef api\n")
+        return 2
+    sys.stdout.write(render(DOORS))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

refdef/_api.py

@@ -0,0 +1,42 @@
+"""The surface printer: `render` lists every door's `__all__` with signatures and docstrings."""
+
+import annotationlib
+import dataclasses
+import enum
+import importlib
+import inspect
+
+DOORS: tuple[str, ...] = ("refdef", "refdef.plc")
+
+
+def _signature(obj: object) -> str:
+    """The signature as source text, so 3.14 and 3.15 print the same bytes."""
+    return str(inspect.signature(obj, annotation_format=annotationlib.Format.STRING))  # ty: ignore[invalid-argument-type] - obj is callable here
+
+
+def _head(name: str, obj: object) -> str:
+    """The first line of a name's entry."""
+    if isinstance(obj, type) and issubclass(obj, enum.Enum):
+        return f"class {name}"
+    if isinstance(obj, type) and dataclasses.is_dataclass(obj):
+        return f"class {name}{_signature(obj)}"
+    if callable(obj):
+        return f"{name}{_signature(obj)}"
+    return f"{name}: {type(obj).__name__}"
+
+
+def _entry(name: str, obj: object) -> list[str]:
+    """A name's head, its docstring indented four spaces, and a blank line."""
+    doc = inspect.getdoc(obj if callable(obj) else type(obj)) or ""
+    return [_head(name, obj), *(f"    {line}".rstrip() for line in doc.splitlines()), ""]
+
+
+def render(doors: tuple[str, ...]) -> str:
+    """Return the public surface of `doors` as text: deterministic, one final newline."""
+    lines: list[str] = []
+    for door in doors:
+        module = importlib.import_module(door)
+        lines.append(f"## {door}")
+        for name in sorted(module.__all__):
+            lines += _entry(name, getattr(module, name))
+    return "\n".join(lines).rstrip("\n") + "\n"

refdef/_check.py

@@ -0,0 +1,55 @@
+"""The scheme rules: the one place that reads a scheme (R5)."""
+
+from collections.abc import Iterable
+
+from refdef.designation import Designation
+from refdef.issues import Issue, IssueCode
+from refdef.level import Level
+from refdef.scheme import Scheme
+
+
+def _level_issues(level: Level, scheme: Scheme) -> list[Issue]:
+    """Aspect rule for every level; letter and class rules for coded levels only."""
+    subject = level.aspect.value + level.text
+    found = []
+    if level.aspect not in scheme.aspects:
+        found.append(
+            Issue(
+                IssueCode.ASPECT_OFF, subject, f"aspect {level.aspect.value} is off in the scheme"
+            )
+        )
+    if not level.code:
+        return found
+    rule = scheme.letters
+    if not rule.min_count <= len(level.code) <= rule.max_count:
+        found.append(
+            Issue(IssueCode.LETTER_COUNT, subject, f"{level.code} has an odd letter count")
+        )
+    if rule.never & set(level.code):
+        found.append(Issue(IssueCode.NEVER_LETTER, subject, f"{level.code} uses a barred letter"))
+    if scheme.classes.get(level.code) is None:
+        found.append(Issue(IssueCode.UNKNOWN_CLASS, subject, f"{level.code} is not a known class"))
+    return found
+
+
+def check(designations: Iterable[Designation], scheme: Scheme) -> tuple[Issue, ...]:
+    """Issues of the designations against `scheme`, in order; duplicates first for each one.
+
+    Terminals and signals are not checked: pass their `of`.
+    """
+    if not isinstance(scheme, Scheme):
+        msg = "scheme must be a Scheme"
+        raise TypeError(msg)
+    found: list[Issue] = []
+    seen: set[str] = set()
+    for design in designations:
+        if not isinstance(design, Designation):
+            msg = "designations must hold Designation"
+            raise TypeError(msg)
+        text = str(design)
+        if text in seen:
+            found.append(Issue(IssueCode.DUPLICATE, text, "designation used twice"))
+        seen.add(text)
+        for level in design.levels:
+            found += _level_issues(level, scheme)
+    return tuple(found)

refdef/_heads.py

@@ -0,0 +1,70 @@
+"""Helpers on tuples of levels; no Designation import, so no import cycle."""
+
+from refdef.level import Aspect, Level
+
+
+def only(levels: tuple[Level, ...], aspects: tuple[Aspect, ...]) -> tuple[Level, ...]:
+    """The levels whose aspect is listed, in order."""
+    return tuple(level for level in levels if level.aspect in aspects)
+
+
+def without_last(levels: tuple[Level, ...], aspect: Aspect | None) -> tuple[Level, ...]:
+    """The levels without the last one of `aspect` (of any aspect if None); unchanged if none."""
+    for index in range(len(levels) - 1, -1, -1):
+        if aspect is None or levels[index].aspect is aspect:
+            return levels[:index] + levels[index + 1 :]
+    return levels
+
+
+def head(levels: tuple[Level, ...], aspect: Aspect) -> tuple[Level, ...]:
+    """The levels of `aspect`, in order."""
+    return tuple(level for level in levels if level.aspect is aspect)
+
+
+def _aspects(levels: tuple[Level, ...]) -> tuple[Aspect, ...]:
+    """The aspects present in `levels`, in order of first appearance."""
+    return tuple(dict.fromkeys(level.aspect for level in levels))
+
+
+def _shared(mine: tuple[Level, ...], other: tuple[Level, ...]) -> int:
+    """The length of the common prefix of two level tuples."""
+    count = 0
+    for left, right in zip(mine, other, strict=False):
+        if left != right:
+            break
+        count += 1
+    return count
+
+
+def within(levels: tuple[Level, ...], root: tuple[Level, ...]) -> bool:
+    """True when the root head is a prefix of ours per shared aspect; a root sharing none fails."""
+    shared = [a for a in _aspects(root) if a in _aspects(levels)]
+    if root and not shared:
+        return False
+    return all(_shared(head(levels, a), head(root, a)) == len(head(root, a)) for a in shared)
+
+
+def drop_heads(levels: tuple[Level, ...], root: tuple[Level, ...]) -> tuple[Level, ...]:
+    """The levels without, per aspect, as many leading ones as the root's head holds."""
+    left = {a: len(head(root, a)) for a in _aspects(root)}
+    kept = []
+    for level in levels:
+        if left.get(level.aspect, 0) > 0:
+            left[level.aspect] -= 1
+        else:
+            kept.append(level)
+    return tuple(kept)
+
+
+def common(first: tuple[Level, ...], *others: tuple[Level, ...]) -> tuple[Level, ...]:
+    """Per aspect of `first`, the shortest head all share with it, in the order of `first`."""
+    keep = {
+        a: min([len(head(first, a)), *(_shared(head(first, a), head(o, a)) for o in others)])
+        for a in _aspects(first)
+    }
+    kept = []
+    for level in first:
+        if keep[level.aspect] > 0:
+            keep[level.aspect] -= 1
+            kept.append(level)
+    return tuple(kept)

refdef/_parse.py

@@ -0,0 +1,177 @@
+"""The lenient reader: text in, a value and the issues of every repair out."""
+
+import re
+
+from refdef.designation import Designation
+from refdef.issues import Issue, IssueCode, Parsed
+from refdef.level import Aspect, Level, coded_split
+from refdef.terminal import Signal, Terminal
+
+_SIGNS = re.compile(r"(==|\+\+|=|-|\+|%|#|\.)")
+_DIGITS = re.compile(r"[A-Za-z]*([0-9]+)")
+_BY_SIGN = {aspect.value: aspect for aspect in Aspect}
+
+
+def _issue(issues: list[Issue], code: IssueCode, subject: str, message: str) -> None:
+    issues.append(Issue(code, subject, message))
+
+
+def _clean(text: str) -> str:
+    """Outer whitespace off a piece of text; pins and names reach this as plain `str`."""
+    return text.strip()
+
+
+def _split_suffix(text: str) -> tuple[str, str, str]:
+    """The text before the first of `: ; &`, that sign, and the rest (sign empty if none)."""
+    cuts = [text.index(sign) for sign in ":;&" if sign in text]
+    if not cuts:
+        return text, "", ""
+    cut = min(cuts)
+    return text[:cut], text[cut], text[cut + 1 :]
+
+
+def _take_top(head: str, issues: list[Issue]) -> tuple[str, str]:
+    """The top node and the text after it; a head with no `<...>` at its start has no top."""
+    if not (head.startswith("<") and ">" in head):
+        return "", head
+    end = head.index(">")
+    raw, rest = head[1:end], head[end + 1 :]
+    top = _clean(raw)
+    if not top:
+        _issue(issues, IssueCode.EMPTY_TOP, raw, "the top node is empty; dropped")
+    elif top != raw:
+        _issue(issues, IssueCode.WHITESPACE, raw, "outer whitespace of the top node removed")
+    return top, rest
+
+
+def _label(
+    aspect: Aspect, body: str, why: tuple[IssueCode, str], issues: list[Issue]
+) -> Level | None:
+    """A label level for text that is not a code, with the issue `why`; None if Level refuses it."""
+    try:
+        level = Level(aspect, label=body)
+    except TypeError:
+        _issue(issues, IssueCode.BAD_LABEL, body, "the label holds a reserved character; dropped")
+        return None
+    _issue(issues, why[0], body, why[1])
+    return level
+
+
+def _not_code(aspect: Aspect, body: str, issues: list[Issue]) -> Level | None:
+    """A level for a body that `coded_split` refused: a zero or oversize number, or free text."""
+    shape = _DIGITS.fullmatch(body)
+    why = (IssueCode.FREE_LABEL, "not letters and a number; kept as a label")
+    if shape is not None and shape.group(1).strip("0"):
+        why = (IssueCode.NUMBER_TOO_LARGE, "the number is over nine digits; kept as a label")
+    elif shape is not None:
+        why = (IssueCode.ZERO_NUMBER, "zero is not a number here; kept as a label")
+    return _label(aspect, body, why, issues)
+
+
+def _level(aspect: Aspect, raw: str, issues: list[Issue]) -> Level | None:
+    """One body read as a level, with an issue per repair; None if nothing is left of it."""
+    body = _clean(raw)
+    if body != raw:
+        _issue(issues, IssueCode.WHITESPACE, raw, "outer whitespace of the level removed")
+    if not body:
+        _issue(issues, IssueCode.EMPTY_LEVEL, raw, "a sign with nothing after it; dropped")
+        return None
+    split = coded_split(body)
+    if split is None:
+        return _not_code(aspect, body, issues)
+    letters, digits = split
+    if len(digits) > 1 and digits.startswith("0"):
+        _issue(issues, IssueCode.LEADING_ZERO, body, "leading zero dropped")
+    if letters != letters.upper():
+        _issue(issues, IssueCode.LOWER_CASE, body, "letters raised to upper case")
+    return Level(aspect, letters.upper(), int(digits))
+
+
+def _signed(
+    sign: str, body: str, levels: list[Level], aspect: Aspect, issues: list[Issue]
+) -> Aspect:
+    """Read one signed body onto `levels`; a dot takes the aspect of the previous level (M6)."""
+    if sign == ".":
+        _issue(issues, IssueCode.DOT_LEVEL, body, "a dot read as a level of the same aspect")
+        aspect = levels[-1].aspect if levels else aspect
+    else:
+        aspect = _BY_SIGN[sign]
+    level = _level(aspect, body, issues)
+    if level is not None:
+        levels.append(level)
+    return aspect
+
+
+def _levels(head: str, bare: Aspect, issues: list[Issue]) -> tuple[Level, ...]:
+    """Split the head on signs and read each body; a dot repeats the aspect before it."""
+    parts = _SIGNS.split(head)
+    levels: list[Level] = []
+    aspect = bare
+    if _clean(parts[0]):
+        _issue(issues, IssueCode.NO_SIGN, parts[0], f"no sign; read as {bare.name.lower()}")
+        first = _level(aspect, parts[0], issues)
+        if first is not None:
+            levels.append(first)
+    elif parts[0]:
+        _issue(issues, IssueCode.WHITESPACE, parts[0], "whitespace before the first sign removed")
+    for sign, body in zip(parts[1::2], parts[2::2], strict=True):
+        aspect = _signed(sign, body, levels, aspect, issues)
+    return tuple(levels)
+
+
+def _pins(rest: str, issues: list[Issue]) -> tuple[str, ...]:
+    """The pins of a terminal: split on `:`, strip each, drop the empty ones."""
+    pins = []
+    for raw in rest.split(":"):
+        pin = _clean(raw)
+        if pin != raw:
+            _issue(issues, IssueCode.WHITESPACE, raw, "outer whitespace of the pin removed")
+        if pin:
+            pins.append(pin)
+        else:
+            _issue(issues, IssueCode.EMPTY_PIN, raw, "an empty pin; dropped")
+    return tuple(pins)
+
+
+def _signal(design: Designation, rest: str, issues: list[Issue]) -> Designation | Signal:
+    """A signal named by the rest; a bare designation if the name is empty."""
+    name = _clean(rest)
+    if name != rest:
+        _issue(issues, IssueCode.WHITESPACE, rest, "outer whitespace of the name removed")
+    if not name:
+        _issue(issues, IssueCode.EMPTY_NAME, rest, "an empty signal name; dropped")
+        return design
+    return Signal(design if design.levels or design.top else None, name)
+
+
+def _finish(
+    design: Designation, sign: str, rest: str, issues: list[Issue]
+) -> Designation | Terminal | Signal:
+    """Attach the suffix: pins make a terminal, a name a signal, `&` is dropped with an issue."""
+    if sign == ":":
+        pins = _pins(rest, issues)
+        return Terminal(design, pins) if pins else design
+    if sign == ";":
+        return _signal(design, rest, issues)
+    if sign == "&":
+        _issue(issues, IssueCode.UNSUPPORTED_SUFFIX, sign + rest, "the document suffix is dropped")
+    return design
+
+
+def parse(text: str, *, bare: Aspect) -> Parsed[Designation | Terminal | Signal]:
+    """Read text as a designation, terminal or signal, with an issue for each repair.
+
+    `bare` is the aspect of text before the first sign. Never raises for content.
+    """
+    if not isinstance(text, str) or not isinstance(bare, Aspect):
+        msg = "parse takes a str and a bare Aspect"
+        raise TypeError(msg)
+    text = _clean(text)
+    issues: list[Issue] = []
+    if not text:
+        _issue(issues, IssueCode.EMPTY, text, "nothing to read")
+        return Parsed(Designation(), tuple(issues))
+    head, sign, rest = _split_suffix(text)
+    top, head = _take_top(head, issues)
+    design = Designation(_levels(head, bare, issues), top)
+    return Parsed(_finish(design, sign, rest, issues), tuple(issues))

refdef/_render.py

@@ -0,0 +1,64 @@
+"""The strict printer and its three explicit options."""
+
+from collections.abc import Collection, Mapping
+
+from refdef.designation import Designation
+from refdef.level import Aspect, Level
+
+
+def _check(d: object, pad: object, dotted: object, bare: object) -> None:
+    if not isinstance(d, Designation):
+        msg = "render takes a Designation"
+        raise TypeError(msg)
+    if pad is not None and not (
+        isinstance(pad, Mapping)
+        and all(isinstance(k, str) and type(v) is int and v >= 0 for k, v in pad.items())
+    ):
+        msg = "pad must be a mapping of str to non-negative int, or None"
+        raise TypeError(msg)
+    if not isinstance(dotted, Collection) or not all(isinstance(a, Aspect) for a in dotted):
+        msg = "dotted must be a collection of Aspect"
+        raise TypeError(msg)
+    if not isinstance(bare, bool):
+        msg = "bare must be a bool"
+        raise TypeError(msg)
+
+
+def _is_sub(level: Level, previous: Level | None) -> bool:
+    """A number-only level right after a level of the same aspect."""
+    return (
+        previous is not None
+        and previous.aspect is level.aspect
+        and level.code == ""
+        and level.number is not None
+    )
+
+
+def _text(level: Level, pad: Mapping[str, int]) -> str:
+    if level.code and level.code in pad:
+        return level.code + str(level.number).zfill(pad[level.code])
+    return level.text
+
+
+def render(
+    d: Designation,
+    *,
+    pad: Mapping[str, int] | None = None,
+    dotted: Collection[Aspect] = (),
+    bare: bool = False,
+) -> str:
+    """Print a designation; `pad`, `dotted` and `bare` are the explicit dialects, none is `str(d)`.
+
+    `pad={"W": 4}` gives `-W0001`; `dotted=(P,)` gives `-W25.1`; `bare=True` omits the first sign.
+    """
+    _check(d, pad, dotted, bare)
+    widths = pad or {}
+    out = [f"<{d.top}>"] if d.top else []
+    previous = None
+    for index, level in enumerate(d.levels):
+        sign = level.aspect.value
+        if _is_sub(level, previous) and level.aspect in dotted:
+            sign = "."
+        out.append(("" if bare and index == 0 else sign) + _text(level, widths))
+        previous = level
+    return "".join(out)

refdef/designation.py

@@ -0,0 +1,93 @@
+"""The designation: a tuple of levels and an optional top node."""
+
+from dataclasses import dataclass
+
+from refdef import _heads
+from refdef.level import Aspect, Level
+
+_NOT_IN_TOP = frozenset(">:;&")
+
+
+@dataclass(frozen=True)
+class Designation:
+    """A tuple of levels and an optional top node, built by the constructor and `child` only.
+
+    Join two through their levels; the empty designation is the root.
+    """
+
+    levels: tuple[Level, ...] = ()
+    top: str = ""
+
+    def __post_init__(self) -> None:
+        """Validate the levels and the top; every violation raises TypeError."""
+        if not isinstance(self.levels, tuple) or not all(isinstance(v, Level) for v in self.levels):
+            msg = "levels must be a tuple of Level"
+            raise TypeError(msg)
+        if not isinstance(self.top, str):
+            msg = "top must be str"
+            raise TypeError(msg)
+        if self.top != self.top.strip() or _NOT_IN_TOP & set(self.top):
+            msg = "top must be stripped and hold none of > : ; &"
+            raise TypeError(msg)
+
+    def __str__(self) -> str:
+        """The strict printed form, the same as `render(self)`."""
+        from refdef._render import render  # render imports this module, so import late
+
+        return render(self)
+
+    def child(
+        self, aspect: Aspect, code: str = "", number: int | None = None, label: str = ""
+    ) -> Designation:
+        """This designation with one more level at the end."""
+        return Designation((*self.levels, Level(aspect, code, number, label)), self.top)
+
+    def only(self, *aspects: Aspect) -> Designation:
+        """The levels of the listed aspects, in order; the top is kept."""
+        if not all(isinstance(a, Aspect) for a in aspects):
+            msg = "aspects must be Aspect"
+            raise TypeError(msg)
+        return Designation(_heads.only(self.levels, aspects), self.top)
+
+    def parent(self, aspect: Aspect | None = None) -> Designation:
+        """Without the last level of `aspect` (of any aspect if None); self if there is none."""
+        if aspect is not None and not isinstance(aspect, Aspect):
+            msg = "aspect must be an Aspect or None"
+            raise TypeError(msg)
+        return Designation(_heads.without_last(self.levels, aspect), self.top)
+
+    @property
+    def last(self) -> Level | None:
+        """The last level, or None for a designation without levels."""
+        return self.levels[-1] if self.levels else None
+
+    def within(self, root: Designation) -> bool:
+        """True when `root` is a head of this designation, aspect by aspect (the top too)."""
+        _need_designation(root)
+        return root.top in ("", self.top) and _heads.within(self.levels, root.levels)
+
+    def relative_to(self, root: Designation) -> Designation:
+        """This designation without the heads `root` holds; unchanged when it is not within."""
+        if not self.within(root):
+            return self
+        return Designation(
+            _heads.drop_heads(self.levels, root.levels), "" if root.top == self.top else self.top
+        )
+
+    @staticmethod
+    def common(*designations: Designation) -> Designation:
+        """The longest head per aspect all share, ordered as the first; the root for none."""
+        for each in designations:
+            _need_designation(each)
+        if not designations:
+            return Designation()
+        first, *others = designations
+        top = first.top if all(d.top == first.top for d in others) else ""
+        return Designation(_heads.common(first.levels, *(d.levels for d in others)), top)
+
+
+def _need_designation(value: object) -> None:
+    """Raise TypeError unless `value` is a Designation."""
+    if not isinstance(value, Designation):
+        msg = "root and the arguments of common must be Designation"
+        raise TypeError(msg)

refdef/issues.py

@@ -0,0 +1,47 @@
+"""Issues found while reading or checking reference designations."""
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class IssueCode(Enum):
+    """The 21 issue codes: the first 16 come from the readers, the last 5 from check."""
+
+    EMPTY = "empty"
+    NO_SIGN = "no_sign"
+    EMPTY_LEVEL = "empty_level"
+    EMPTY_TOP = "empty_top"
+    WHITESPACE = "whitespace"
+    LOWER_CASE = "lower_case"
+    LEADING_ZERO = "leading_zero"
+    ZERO_NUMBER = "zero_number"
+    NUMBER_TOO_LARGE = "number_too_large"
+    FREE_LABEL = "free_label"
+    BAD_LABEL = "bad_label"
+    DOT_LEVEL = "dot_level"
+    EMPTY_PIN = "empty_pin"
+    EMPTY_NAME = "empty_name"
+    UNSUPPORTED_SUFFIX = "unsupported_suffix"
+    NOT_ADDRESS = "not_address"
+    ASPECT_OFF = "aspect_off"
+    LETTER_COUNT = "letter_count"
+    NEVER_LETTER = "never_letter"
+    UNKNOWN_CLASS = "unknown_class"
+    DUPLICATE = "duplicate"
+
+
+@dataclass(frozen=True)
+class Issue:
+    """One finding about a string or a designation: a code, the offending text, a short sentence."""
+
+    code: IssueCode
+    subject: str
+    message: str
+
+
+@dataclass(frozen=True)
+class Parsed[T]:
+    """A value read from text together with the issues the reader found."""
+
+    value: T
+    issues: tuple[Issue, ...]