symdef 0.4.0__tar.gz

symdef-0.4.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

symdef-0.4.0/.github/workflows/docs.yml

@@ -0,0 +1,33 @@
+name: docs
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - run: uv run --only-group dev python scripts/build_site.py site
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

symdef-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: publish
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - name: The tag matches the package version
+        run: test "v$(uv version --short)" = "$GITHUB_REF_NAME"
+      - run: uv build
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # trusted publishing: no token secret
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          attestations: true

symdef-0.4.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+.ruff_cache/
+.pytest_cache/
+.coverage
+.superpowers/
+claude-tools/
+dist/

symdef-0.4.0/.python-version

@@ -0,0 +1 @@
+3.15

symdef-0.4.0/AGENTS.md

@@ -0,0 +1,12 @@
+# AGENTS.md
+
+`CLAUDE.md` holds this repo's rules for any agent, not only Claude. This file restates none of
+them.
+
+- To work on the toolkit: read `CLAUDE.md`, then the spec,
+  `src/symdef/docs/SYMBOL_INTERFACE.html`. `just --list` names the recipes, and
+  `just ci` is the gate.
+- To use the toolkit from another project: read `README.md` (install and a short tour), then
+  `docs/GUIDE.md` (the concepts and the calls). The docstrings of the names in
+  `symdef.__all__` are the API reference. The spec ships inside the package:
+  `importlib.resources.files("symdef").joinpath("docs/SYMBOL_INTERFACE.html")`.

symdef-0.4.0/CLAUDE.md

@@ -0,0 +1,62 @@
+# symdef: agent guide
+
+Standard-agnostic Python toolkit for graphical-symbol data. It reads TOML symbol files, resolves
+composition, lints the wiring contract, renders SVG, and builds a resolved JSON bundle plus an SVG
+gallery. Data packages hold only data and reuse this toolkit: `electrical-symbols` (a package
+of the Fransys repo, `../fransys-dev`) now, ISO 14617 and ISA 5.1 later. Alpha,
+single owner.
+
+Fransys is
+one user. It pins an exact PyPI version, and its `electrical-symbols` package is an IEC 60617
+data package. A change Fransys needs lands here first, released as `vX.Y.Z` on PyPI, then
+Fransys bumps its pin. No code, test or script here imports or names a Fransys package.
+
+## The spec decides
+
+`src/graphical_symbols/docs/SYMBOL_INTERFACE.html` (the spec; older entries in
+`docs/DECISIONS.md` call it the guide) is the only design document. It ships as package data,
+readable at runtime through `importlib.resources`; `electrical-symbols`' verbatim gate reads it
+from the installed distribution (D38). It is final and binding. Read all of it before doing
+anything. Never edit it. Definitions in it
+(extents, overlap, orientations, the wire lane, placement, `repeat`, the 33 lint rules, the JSON
+output format) are exact: implement them as written. The toolkit has one rule beyond the spec's
+33, `lead-off-port` (D40).
+
+Where the spec is silent, decide yourself and record the decision in `docs/DECISIONS.md`, one entry
+each: what you decided, why, what it costs if wrong. If you believe the spec is wrong or
+self-contradictory, do not edit it: implement it as written, record the concern in
+`docs/DECISIONS.md` and report it to the owner at the end.
+
+## The work
+
+The toolkit the spec describes is built (spec sections 4 to 12). Work now arrives as a work
+order from the Fransys workflow's orchestrator: a change a Fransys package needs, a
+bug, or a new public function, each recorded in `docs/DECISIONS.md`. Keep the public names of
+spec section 11 exactly as written; a new name gets a decision entry.
+
+## Rules
+
+- Python 3.15 (`.python-version`); `requires-python` is `>=3.14`, and `just
+  ci` runs the tests on 3.14 too, `uv` only (never bare `python` or `pip`), ruff, ty, pytest, hypothesis,
+  vulture, deal. Every dependency pinned to the exact latest stable version. Runtime dependency:
+  `deal` only (`jsonschema` may be a dev dependency for the agreement test). TOML is read with the
+  standard library's `tomllib`.
+- Pure core: every module-level function in a pure module is `@deal.pure` and does not raise. Only
+  the modules that read or write files are impure. `scripts/fp_purity_gate.py` enforces it.
+- `docs/` holds `DECISIONS.md` and `GUIDE.md` only; plans stay out of the repo.
+- Frozen slotted dataclasses; transforms are free functions; no positional port aliases.
+- Every gate and lint rule is proven able to fail with a deliberately broken fixture.
+- `just ci` passes before every commit; quote its output. Look at rendered output: convert SVGs to
+  PNG and view them (`uv run --with cairosvg` or playwright, from a scratch directory outside
+  the repo).
+- Git: stage named paths only; Conventional Commits ending with
+  the attribution line your session gives; work on a feature branch from `main`, never commit to
+  `main` directly. The orchestrator reviews, merges, pushes and tags the release (`vX.Y.Z`,
+  matching `version` in `pyproject.toml`); an implementer does not.
+- Never edit another repo. A change Fransys needs because of yours goes in your hand-back.
+
+## Done means
+
+The work order's acceptance is met, every new rule or gate has a failing fixture, `just ci` is
+green (quote it), and the hand-back lists every decision recorded and anything the owner must
+decide.

symdef-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OleJBondahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

symdef-0.4.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: symdef
+Version: 0.4.0
+Summary: Standard-agnostic core for graphical symbols as strict, typed, immutable Python values
+Project-URL: Repository, https://github.com/OleJBondahl/symdef
+Author: Ole Johan Bondahl
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: deal==4.24.6
+Description-Content-Type: text/markdown
+
+# symdef
+
+Standard-agnostic toolkit for graphical-symbol data. Symbols are TOML files; the toolkit loads
+them, resolves composition, lints the wiring contract, renders SVG, and builds a resolved JSON
+bundle plus a gallery. Data packages hold only data and reuse the toolkit and its gates:
+`electrical-symbols` (IEC 60617-style symbols, Fransys' `packages/electrical-symbols`) now, ISO 14617 and
+ISA 5.1 later.
+
+Status: alpha. The toolkit the spec below describes is built: reading, resolving, linting, SVG and
+the build, with every lint rule and gate proven by a failing fixture. Released by exact git tags
+(`v0.1.0` to `v0.3.0` as `graphical-symbols`; `v0.4.0` on as `symdef`); Fransys pins one of them.
+
+## Install
+
+```
+uv add "symdef==0.4.0"
+```
+
+Python 3.14 or later. The one runtime dependency is `deal`. More depth:
+[docs/GUIDE.md](docs/GUIDE.md).
+
+## The design
+
+[src/symdef/docs/SYMBOL_INTERFACE.html](src/symdef/docs/SYMBOL_INTERFACE.html)
+is the binding, final spec. Open it in a browser; it ships as package data, readable at runtime
+through `importlib.resources.files("symdef").joinpath("docs/SYMBOL_INTERFACE.html")`.
+The key ideas:
+
+- A symbol is a definition: no tag, terminal numbers, position or orientation. Those belong to
+  the placement in a drawing library.
+- Port ids are roles (`in`, `out`, `anode`, ...), never terminal markings (`13`, `A1`).
+- Electrical function is data: nodes and typed paths, so a consumer can netlist without
+  per-symbol knowledge.
+- Text lives in slots: the symbol reserves boxes for tags and terminal markings.
+- Module units (M = 2.5 mm), a 0.125 M drawing grid and a 1 M wiring grid. A strict wiring
+  contract is linted in all 8 orientations.
+- Composition mirrors the standard: composites reference parts by anchor, no copied coordinates.
+
+## What is here
+
+The data model and `orient`, the boxes and `repeat`, the TOML reader with its JSON Schema
+(`schema/symbol.schema.json`), the composition resolver, 34 lint rules, plain and annotated SVG,
+and the build (resolved JSON per symbol, the bundle, SVGs, a gallery README). Decisions the spec
+leaves open, and concerns about the spec, are in [docs/DECISIONS.md](docs/DECISIONS.md).
+
+## Use
+
+A data repo has `library.toml` and `symbols/<number>.toml`; `root` below is its directory.
+
+```python
+from symdef import lint, load_library
+from symdef.lint import RULES
+
+library = load_library(root)  # raises LibraryError, listing every problem in the files
+contact = library.get("S00227")  # by number; iterating a library is sorted by number
+assert len(RULES) == 34  # the spec's 33 rules plus lead-off-port (D40)
+findings = lint(contact)  # all 34 rules, geometric ones in all 8 orientations
+assert findings == ()  # the spec's make contact lints clean
+for finding in findings:  # each has .rule, .severity, .message, .location, .orientation
+    print(finding.rule, finding.location, finding.message)
+```
+
+Symbols are immutable; `orient`, `translate` and `repeat` return new ones. A repeated symbol is
+an ordinary symbol with ports such as `1.in` and `3.out`.
+
+```python
+from symdef import Orientation, keepout_box, orient, repeat, to_svg
+
+breaker = orient(repeat(contact, 3), Orientation.R0)
+print(keepout_box(breaker))
+svg = to_svg(breaker, annotate=True, texts={"tag": "-Q1"})
+```
+
+`write_build` writes `build/` and `src/<package>/bundle.json` under the repo; `stale_build` lists
+the files that differ from what it would write, so a test can fail when a committed build is out
+of date. `load_bundle` reads a bundle back without the sources. `<package>` is the standard's
+normalised name (lowercase letters and digits, D8): the example's standard is `IEC 60617`, so its
+package is `iec60617`.
+
+```python
+from symdef import load_bundle, stale_build, write_build
+
+write_build(library, root)
+assert stale_build(library, root) == ()
+assert len(load_bundle(root / "src" / "iec60617" / "bundle.json")) == len(library)
+```
+
+## Development
+
+```
+uv sync
+just ci        # format check, ruff, ty, vulture, purity gate, pytest with coverage
+```
+
+Coverage must stay at 100% (`--cov-fail-under=100`), so a partial run such as
+`uv run pytest tests/test_units.py` fails on coverage alone: add `--no-cov` for one.
+`tests/test_readme.py` runs the examples above and those in [docs/GUIDE.md](docs/GUIDE.md), so
+they stay true. Agents: start at [AGENTS.md](AGENTS.md).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

symdef-0.4.0/README.md

@@ -0,0 +1,102 @@
+# symdef
+
+Standard-agnostic toolkit for graphical-symbol data. Symbols are TOML files; the toolkit loads
+them, resolves composition, lints the wiring contract, renders SVG, and builds a resolved JSON
+bundle plus a gallery. Data packages hold only data and reuse the toolkit and its gates:
+`electrical-symbols` (IEC 60617-style symbols, Fransys' `packages/electrical-symbols`) now, ISO 14617 and
+ISA 5.1 later.
+
+Status: alpha. The toolkit the spec below describes is built: reading, resolving, linting, SVG and
+the build, with every lint rule and gate proven by a failing fixture. Released by exact git tags
+(`v0.1.0` to `v0.3.0` as `graphical-symbols`; `v0.4.0` on as `symdef`); Fransys pins one of them.
+
+## Install
+
+```
+uv add "symdef==0.4.0"
+```
+
+Python 3.14 or later. The one runtime dependency is `deal`. More depth:
+[docs/GUIDE.md](docs/GUIDE.md).
+
+## The design
+
+[src/symdef/docs/SYMBOL_INTERFACE.html](src/symdef/docs/SYMBOL_INTERFACE.html)
+is the binding, final spec. Open it in a browser; it ships as package data, readable at runtime
+through `importlib.resources.files("symdef").joinpath("docs/SYMBOL_INTERFACE.html")`.
+The key ideas:
+
+- A symbol is a definition: no tag, terminal numbers, position or orientation. Those belong to
+  the placement in a drawing library.
+- Port ids are roles (`in`, `out`, `anode`, ...), never terminal markings (`13`, `A1`).
+- Electrical function is data: nodes and typed paths, so a consumer can netlist without
+  per-symbol knowledge.
+- Text lives in slots: the symbol reserves boxes for tags and terminal markings.
+- Module units (M = 2.5 mm), a 0.125 M drawing grid and a 1 M wiring grid. A strict wiring
+  contract is linted in all 8 orientations.
+- Composition mirrors the standard: composites reference parts by anchor, no copied coordinates.
+
+## What is here
+
+The data model and `orient`, the boxes and `repeat`, the TOML reader with its JSON Schema
+(`schema/symbol.schema.json`), the composition resolver, 34 lint rules, plain and annotated SVG,
+and the build (resolved JSON per symbol, the bundle, SVGs, a gallery README). Decisions the spec
+leaves open, and concerns about the spec, are in [docs/DECISIONS.md](docs/DECISIONS.md).
+
+## Use
+
+A data repo has `library.toml` and `symbols/<number>.toml`; `root` below is its directory.
+
+```python
+from symdef import lint, load_library
+from symdef.lint import RULES
+
+library = load_library(root)  # raises LibraryError, listing every problem in the files
+contact = library.get("S00227")  # by number; iterating a library is sorted by number
+assert len(RULES) == 34  # the spec's 33 rules plus lead-off-port (D40)
+findings = lint(contact)  # all 34 rules, geometric ones in all 8 orientations
+assert findings == ()  # the spec's make contact lints clean
+for finding in findings:  # each has .rule, .severity, .message, .location, .orientation
+    print(finding.rule, finding.location, finding.message)
+```
+
+Symbols are immutable; `orient`, `translate` and `repeat` return new ones. A repeated symbol is
+an ordinary symbol with ports such as `1.in` and `3.out`.
+
+```python
+from symdef import Orientation, keepout_box, orient, repeat, to_svg
+
+breaker = orient(repeat(contact, 3), Orientation.R0)
+print(keepout_box(breaker))
+svg = to_svg(breaker, annotate=True, texts={"tag": "-Q1"})
+```
+
+`write_build` writes `build/` and `src/<package>/bundle.json` under the repo; `stale_build` lists
+the files that differ from what it would write, so a test can fail when a committed build is out
+of date. `load_bundle` reads a bundle back without the sources. `<package>` is the standard's
+normalised name (lowercase letters and digits, D8): the example's standard is `IEC 60617`, so its
+package is `iec60617`.
+
+```python
+from symdef import load_bundle, stale_build, write_build
+
+write_build(library, root)
+assert stale_build(library, root) == ()
+assert len(load_bundle(root / "src" / "iec60617" / "bundle.json")) == len(library)
+```
+
+## Development
+
+```
+uv sync
+just ci        # format check, ruff, ty, vulture, purity gate, pytest with coverage
+```
+
+Coverage must stay at 100% (`--cov-fail-under=100`), so a partial run such as
+`uv run pytest tests/test_units.py` fails on coverage alone: add `--no-cov` for one.
+`tests/test_readme.py` runs the examples above and those in [docs/GUIDE.md](docs/GUIDE.md), so
+they stay true. Agents: start at [AGENTS.md](AGENTS.md).
+
+## License
+
+MIT, see [LICENSE](LICENSE).