symdef 0.4.0__py3-none-any.whl

symdef/__init__.py

@@ -0,0 +1,97 @@
+"""Standard-agnostic core for graphical symbols."""
+
+from symdef._version import LIBRARY_VERSION
+from symdef.boxes import body_box, keepout_box, slot_box
+from symdef.build import load_bundle, load_library, stale_build, write_build
+from symdef.errors import GraphicalSymbolsError, LibraryError, UnknownSymbolError
+from symdef.geometry import (
+    Arc,
+    Box,
+    Circle,
+    Direction,
+    Element,
+    Fill,
+    Line,
+    Orientation,
+    Point,
+    Polyline,
+    Style,
+    Text,
+    Weight,
+)
+from symdef.lint import lint
+from symdef.model import (
+    Allow,
+    Anchor,
+    Finding,
+    Library,
+    LibraryConfig,
+    Node,
+    Path,
+    PathKind,
+    Port,
+    Potential,
+    Reference,
+    Severity,
+    Slot,
+    Status,
+    Symbol,
+    SymbolKind,
+)
+from symdef.orient import orient, translate
+from symdef.repeat import repeat
+from symdef.svg import to_fragment, to_svg
+from symdef.units import DEFAULT_MODULE_MM, GRID_DIVISION, on_grid, snap
+
+__all__ = [
+    "DEFAULT_MODULE_MM",
+    "GRID_DIVISION",
+    "LIBRARY_VERSION",
+    "Allow",
+    "Anchor",
+    "Arc",
+    "Box",
+    "Circle",
+    "Direction",
+    "Element",
+    "Fill",
+    "Finding",
+    "GraphicalSymbolsError",
+    "Library",
+    "LibraryConfig",
+    "LibraryError",
+    "Line",
+    "Node",
+    "Orientation",
+    "Path",
+    "PathKind",
+    "Point",
+    "Polyline",
+    "Port",
+    "Potential",
+    "Reference",
+    "Severity",
+    "Slot",
+    "Status",
+    "Style",
+    "Symbol",
+    "SymbolKind",
+    "Text",
+    "UnknownSymbolError",
+    "Weight",
+    "body_box",
+    "keepout_box",
+    "lint",
+    "load_bundle",
+    "load_library",
+    "on_grid",
+    "orient",
+    "repeat",
+    "slot_box",
+    "snap",
+    "stale_build",
+    "to_fragment",
+    "to_svg",
+    "translate",
+    "write_build",
+]

symdef/_version.py

@@ -0,0 +1,3 @@
+"""The package version, written by scripts/build.py. Do not edit."""
+
+LIBRARY_VERSION = "0.4.0"

symdef/boxes.py

@@ -0,0 +1,112 @@
+"""The body, slot and keep-out boxes of a symbol."""
+
+import math
+
+import deal
+
+from symdef.geometry import (
+    Arc,
+    Box,
+    Circle,
+    Direction,
+    Element,
+    Line,
+    Point,
+    Polyline,
+    Text,
+    arc_point,
+    arc_sweep,
+)
+from symdef.model import Slot, Symbol
+
+_AXIS_ANGLES = (0, 90, 180, 270)
+_FULL_TURN = 360
+_TEXT_WIDTH_PER_HEIGHT = 0.6
+_ORIGIN_BOX = Box(Point(0, 0), Point(0, 0))
+
+
+@deal.pure
+def _extent_points(element: Element) -> tuple[Point, ...]:
+    """Return points whose bounding box is the element's extent, ignoring stroke width.
+
+    An arc with a non-finite angle has no swept extent and counts as its centre.
+    """
+    match element:
+        case Line(start=start, end=end):
+            return (start, end)
+        case Polyline(points=points):
+            return points
+        case Circle(center=c, radius=r):
+            return (Point(c.x - r, c.y - r), Point(c.x + r, c.y + r))
+        case Arc() as arc:
+            if not (math.isfinite(arc.start_deg) and math.isfinite(arc.end_deg)):
+                return (arc.center,)
+            start, end = arc.start_deg % _FULL_TURN, arc.end_deg % _FULL_TURN
+            sweep = arc_sweep(arc)
+            extremes = tuple(a for a in _AXIS_ANGLES if (a - start) % _FULL_TURN <= sweep)
+            return tuple(arc_point(arc, a) for a in (start, end, *extremes))
+        case Text(content=content, position=at, height=height):
+            half_w = _TEXT_WIDTH_PER_HEIGHT * height * len(content) / 2
+            return (
+                Point(at.x - half_w, at.y - height / 2),
+                Point(at.x + half_w, at.y + height / 2),
+            )
+
+
+@deal.pure
+def _bounding(points: tuple[Point, ...]) -> Box:
+    """Return the smallest box holding every point; no points give the origin box."""
+    if not points:
+        return _ORIGIN_BOX
+    xs = [p.x for p in points]
+    ys = [p.y for p in points]
+    return Box(Point(min(xs), min(ys)), Point(max(xs), max(ys)))
+
+
+@deal.pure
+def element_box(element: Element) -> Box:
+    """Return the extent of one element.
+
+    A line or polyline extends over its points, a circle over its full diameter, an arc over its
+    true swept extent, and text is a box centred on its position, `height` tall and `0.6 * height`
+    per character wide. Stroke width is ignored. A polyline without points has the origin box.
+    """
+    return _bounding(_extent_points(element))
+
+
+@deal.pure
+def body_box(symbol: Symbol) -> Box:
+    """Return the union of the element extents, in module units, ignoring stroke width.
+
+    Extents are as for text (`0.6 * height` per character), arcs (the true swept extent) and the
+    other elements. A symbol without elements has the box (0, 0) to (0, 0). Ports, anchors and
+    slots do not count.
+    """
+    return _bounding(tuple(p for e in symbol.elements for p in _extent_points(e)))
+
+
+@deal.pure
+def slot_box(slot: Slot) -> Box:
+    """Return the box a slot reserves: it grows from the slot point towards its side.
+
+    E and W grow horizontally and are vertically centred; N grows up and S grows down and both
+    are horizontally centred. The box is never rotated; only the point and side are.
+    """
+    x, y = slot.position.x, slot.position.y
+    w, h = slot.box
+    match slot.side:
+        case Direction.E:
+            return Box(Point(x, y - h / 2), Point(x + w, y + h / 2))
+        case Direction.W:
+            return Box(Point(x - w, y - h / 2), Point(x, y + h / 2))
+        case Direction.N:
+            return Box(Point(x - w / 2, y - h), Point(x + w / 2, y))
+        case Direction.S:
+            return Box(Point(x - w / 2, y), Point(x + w / 2, y + h))
+
+
+@deal.pure
+def keepout_box(symbol: Symbol) -> Box:
+    """Return the body box united with every slot box: the room the symbol needs kept clear."""
+    boxes = (body_box(symbol), *(slot_box(s) for s in symbol.slots))
+    return _bounding(tuple(p for b in boxes for p in (b.min, b.max)))

symdef/build.py

@@ -0,0 +1,207 @@
+"""The impure shell: everything that reads or writes files. Pure work stays in the other modules."""
+
+from dataclasses import replace
+from pathlib import Path
+from typing import Any
+
+from symdef.errors import LibraryError
+from symdef.lint.registry import rule_finding
+from symdef.load import (
+    is_file_stem,
+    library_from_bundle,
+    parse_config,
+    parse_json,
+    parse_toml,
+    validate_bundle,
+)
+from symdef.model import Finding, Library, LibraryConfig
+from symdef.resolve import resolve_library
+from symdef.serialize import GENERATED_DIRS, build_files, package_folder
+
+
+def _named(name: str, findings: tuple[Finding, ...]) -> tuple[Finding, ...]:
+    """Prefix each message with the file it is about, since a finding has no file of its own."""
+    return tuple(replace(f, message=f"{name}: {f.message}") for f in findings)
+
+
+def _read(path: Path) -> tuple[str | None, tuple[Finding, ...]]:
+    """Read a UTF-8 text file; one that cannot be read is a `schema` finding located at its name."""
+    try:
+        return path.read_text(encoding="utf-8"), ()
+    except (OSError, UnicodeDecodeError) as error:
+        return None, _named(path.name, (rule_finding("schema", str(error), path.name),))
+
+
+def _read_config(path: Path) -> tuple[LibraryConfig | None, tuple[Finding, ...]]:
+    """Read `library.toml`."""
+    text, found = _read(path)
+    if text is None:
+        return None, found
+    config, problems = parse_config(text)
+    return config, _named(path.name, problems)
+
+
+def _read_symbol(path: Path) -> tuple[dict[str, Any] | None, tuple[Finding, ...]]:
+    """Read one symbol file's TOML."""
+    text, found = _read(path)
+    if text is None:
+        return None, found
+    data, problems = parse_toml(text)
+    return data, _named(path.name, problems)
+
+
+def load_library(root: Path) -> Library:
+    """Read `library.toml` and `symbols/*.toml` under `root`, validate, resolve and flatten them.
+
+    Args:
+        root: The data repo's directory.
+
+    Returns:
+        The library, its symbols keyed by reference number.
+
+    Raises:
+        LibraryError: If a file cannot be read or fails any check. `findings` holds every
+            finding, `library.toml` first and then the symbol files in name order, each message
+            prefixed with its file name.
+    """
+    config, problems = _read_config(root / "library.toml")
+    directory = root / "symbols"
+    if not directory.is_dir():
+        missing = rule_finding("schema", "the directory does not exist", directory.name)
+        raise LibraryError((*problems, *_named(directory.name, (missing,))))
+    per_file: dict[str, tuple[Finding, ...]] = {}
+    sources: dict[str, dict[str, Any]] = {}
+    for path in sorted(directory.glob("*.toml"), key=lambda p: p.stem):
+        data, found = _read_symbol(path)
+        if data is None:
+            per_file[path.stem] = found
+        else:
+            sources[path.stem] = data
+    if config is None:
+        raise LibraryError((*problems, *(f for stem in sorted(per_file) for f in per_file[stem])))
+    resolution = resolve_library(config, sources)
+    per_file |= {stem: _named(f"{stem}.toml", found) for stem, found in resolution.findings.items()}
+    problems += tuple(f for stem in sorted(per_file) for f in per_file[stem])
+    if problems:
+        raise LibraryError(problems)
+    return Library(config.standard, config.title, config.number_pattern, resolution.symbols)
+
+
+def load_bundle(json_path: Path) -> Library:
+    """Read a resolved bundle (`bundle.json`) into a library.
+
+    The library has the bundle's standard for both `standard` and `title`, and no number pattern
+    (D7). Symbols are checked like a source file, plus the resolved form (`validate_bundle`).
+
+    Args:
+        json_path: The bundle file.
+
+    Returns:
+        The library, its symbols keyed by the bundle's keys.
+
+    Raises:
+        LibraryError: If the file cannot be read, is not JSON or is not a valid bundle. Every
+            finding is a `schema` finding, its message prefixed with the file name.
+    """
+    text, found = _read(json_path)
+    if text is None:
+        raise LibraryError(found)
+    data, problems = parse_json(text)
+    if not problems:
+        problems = validate_bundle(data)
+    if problems:
+        raise LibraryError(_named(json_path.name, problems))
+    return library_from_bundle(data)
+
+
+def _package_key(root: Path) -> str:
+    """Return the `package` key of `root/library.toml`, or `""` when it is absent or unreadable.
+
+    `load_library` is where a bad `library.toml` is reported; a build only reads the one key.
+    """
+    config, _ = _read_config(root / "library.toml")
+    return config.package if config else ""
+
+
+def _check_names(library: Library, package: str) -> None:
+    """Refuse a library that would need an unsafe file or directory name, before any file is made.
+
+    A number must be a file stem, and the standard must give a package folder (D8, D35, D45).
+    """
+    for number in library.symbols:
+        if not is_file_stem(number):
+            msg = f"symbol number {number!r} cannot be used as a file name"
+            raise ValueError(msg)
+    if not package_folder(library.standard, package):
+        msg = f"the standard {library.standard!r} has no letter or digit to make a package name of"
+        raise ValueError(msg)
+
+
+def write_build(library: Library, root: Path) -> tuple[Path, ...]:
+    """Write the build of a library under a data repo: `build/` and `src/<package>/bundle.json`.
+
+    `<package>` is the `package` key of `root/library.toml` when it has one, else made from the
+    standard (D8, D45).
+
+    Files are written as bytes, so line endings are LF on every platform, and missing directories
+    are created. Nothing is deleted: a file that an earlier build wrote and this one does not
+    (a removed symbol) stays, and `stale_build` reports it; removing it is the caller's job.
+
+    Args:
+        library: The library to build.
+        root: The data repo's directory.
+
+    Returns:
+        Every path written, as `root / <relative path>` (so relative if `root` is), in the order
+        of their `/`-separated relative paths.
+
+    Raises:
+        ValueError: If a symbol number is not a file stem (`is_file_stem`) or the standard has no
+            letter or digit to make a package name of; nothing is written.
+        OSError: If a path cannot be written; files already written stay.
+    """
+    package = _package_key(root)
+    _check_names(library, package)
+    written = []
+    for relative, data in build_files(library, package).items():
+        target = root / relative
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(data)
+        written.append(target)
+    return tuple(written)
+
+
+def stale_build(library: Library, root: Path) -> tuple[Path, ...]:
+    """Return the files under `root` that differ from what `write_build` would write.
+
+    A file is stale if it is missing or has other bytes, or if it sits anywhere under
+    `build/resolved`, `build/svg` or `build/annotated` and the library does not produce it.
+    Nothing else under `root` is looked at.
+
+    Args:
+        library: The library the build should match.
+        root: The data repo's directory.
+
+    Returns:
+        The stale paths, as `root / <relative path>` (so relative if `root` is), in the order of
+        their `/`-separated relative paths.
+
+    Raises:
+        ValueError: If a symbol number is not a file stem (`is_file_stem`) or the standard has no
+            letter or digit to make a package name of.
+        OSError: If a file cannot be read; it is not treated as stale.
+    """
+    package = _package_key(root)
+    _check_names(library, package)
+    files = build_files(library, package)
+    stale = {
+        relative
+        for relative, data in files.items()
+        if not (root / relative).is_file() or (root / relative).read_bytes() != data
+    }
+    for directory in GENERATED_DIRS:
+        for path in (root / directory).rglob("*"):
+            relative = path.relative_to(root).as_posix()
+            if path.is_file() and relative not in files:
+                stale.add(relative)
+    return tuple(root / relative for relative in sorted(stale))