PySHDL 0.3.0__tar.gz → 1.0.0__tar.gz

pyshdl-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+# CI — T0..T4 on every push / PR (golden_tests.md §1.2, CCT-6, FUZ-6 gate).
+#
+# Runs the commit-time tiers (unit, property, differential small-N, conformance,
+# CPU acceptance) across the Linux + macOS platform matrix with both the system
+# compiler and, on Linux, clang — the CCT-6 platform-matrix obligation (today the
+# suite is proven on macOS/clang only). uv provides Python 3.14 and the single
+# dev dependency (pytest). The heavy stress tier (SHDLC_SCALE) and the soak
+# campaign run nightly, not here, so commit-time stays fast.
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+  workflow_dispatch:
+
+# A newer push to the same ref cancels the in-flight run.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: T0-T4 (${{ matrix.os }}, cc=${{ matrix.cc }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Linux: exercise both gcc (system cc) and clang — the two backends
+          # CCT-6 calls out as missing today.
+          - os: ubuntu-latest
+            cc: gcc
+          - os: ubuntu-latest
+            cc: clang
+          # macOS: the platform the suite was originally proven on (clang).
+          - os: macos-latest
+            cc: clang
+    env:
+      # shdlc.cc honours $CC for compiler discovery; pin it per matrix leg so the
+      # generated-C builds (differential, chunked, CPU) use the intended toolchain.
+      CC: ${{ matrix.cc }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Pin Python 3.14
+        run: uv python install 3.14
+
+      - name: Sync the environment (pytest only; no extra deps)
+        run: uv sync --frozen
+
+      - name: Show the compiler under test
+        run: ${{ matrix.cc }} --version
+
+      # T0 unit + T1 property + T2 differential (small N) + T3 conformance + T4
+      # CPU acceptance. The whole tree under tests/ is the commit-time suite; the
+      # minutes-scale stress tests self-skip unless SHDLC_SCALE is set (nightly).
+      - name: Run T0-T4 (uv run pytest -q)
+        run: uv run pytest -q

pyshdl-1.0.0/.github/workflows/nightly.yml

@@ -0,0 +1,86 @@
+# Nightly soak + coverage (golden_tests.md T5, FUZ-6, the P2 coverage gate).
+#
+# The commit-time CI (ci.yml) runs the suite at its fast defaults. This scheduled
+# job re-runs it with the soak knobs cranked to campaign scale — the large-N
+# differential / fuzz tiers and the SHDLC_SCALE stress builds (SCL-3/4) — and
+# emits a report-only coverage summary for flattener/ and shdlc/. A nightly
+# failure freezes a permanent regression artifact (suite policy §4).
+name: Nightly
+
+on:
+  schedule:
+    # 07:00 UTC daily (off-peak; after most pushes have settled).
+    - cron: "0 7 * * *"
+  workflow_dispatch:
+
+concurrency:
+  group: nightly-${{ github.workflow }}
+  cancel-in-progress: false
+
+jobs:
+  soak:
+    name: Soak campaign (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    env:
+      # Differential / netlist-fuzz tiers at campaign scale.
+      SHDLC_FUZZ: "500"
+      SHDLC_DIFF_CYCLES: "5000"
+      # FUZ-3 SHDL-source fuzzer at campaign scale, with the compiled-C lockstep
+      # leg enabled (opt-in / ~100x slower, so it only runs here).
+      SHDLC_SOURCE_FUZZ: "500"
+      SHDLC_SOURCE_FUZZ_CYCLES: "100"
+      SHDLC_SOURCE_FUZZ_CC: "1"
+      # FUZ-4 frontend no-crash campaign.
+      SHDLC_NOCRASH: "2000"
+      # SCL-3/SCL-4 minutes-scale stress builds (10^5-gate compile + 100-cycle
+      # differential, 10^4-instance generator).
+      SHDLC_SCALE: "1"
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Pin Python 3.14
+        run: uv python install 3.14
+
+      - name: Sync the environment
+        run: uv sync --frozen
+
+      # -p no:randomly / no special flags: the suite is seed-stable by name, so a
+      # campaign-scale run is a deterministic, larger replay of the same tests.
+      - name: Run the soak campaign (T0-T5)
+        run: uv run pytest -q
+
+  coverage:
+    name: Coverage (report-only)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Pin Python 3.14
+        run: uv python install 3.14
+
+      - name: Sync the environment
+        run: uv sync --frozen
+
+      # Report-only line+branch coverage for the two packages the P2 gate names.
+      # pytest-cov is pulled in ad-hoc via --with so it never enters the locked
+      # runtime/dev dependency set. No fail-under here: this is a ratchet target
+      # (≥95% on flattener phases), reported, not yet enforced.
+      - name: Coverage report for flattener/ and shdlc/
+        run: >-
+          uv run --with pytest-cov pytest -q
+          --cov=flattener --cov=shdlc --cov-branch
+          --cov-report=term-missing

{pyshdl-0.3.0 → pyshdl-1.0.0}/.github/workflows/publish.yml

@@ -14,23 +14,23 @@ jobs:
   build:
     name: Build distribution
     runs-on: ubuntu-latest
-    
+
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
-      
+
       - name: Install uv
         uses: astral-sh/setup-uv@v4
-      
+
       - name: Set up Python
-        run: uv python install 3.12
-      
+        run: uv python install 3.14
+
       - name: Set up env
         run: uv venv
 
       - name: Build package
         run: uv build
-      
+
       - name: Store the distribution packages
         uses: actions/upload-artifact@v4
         with:
@@ -41,21 +41,21 @@ jobs:
     name: Publish to PyPI
     needs: [build]
     runs-on: ubuntu-latest
-    
+
     environment:
       name: pypi
       url: https://pypi.org/p/PySHDL
-    
+
     permissions:
       id-token: write  # IMPORTANT: mandatory for trusted publishing
-    
+
     steps:
       - name: Download all the dists
         uses: actions/download-artifact@v4
         with:
           name: python-package-distributions
           path: dist/
-      
+
       - name: Publish distribution to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
 
@@ -64,21 +64,21 @@ jobs:
     if: github.event_name == 'workflow_dispatch'
     needs: [build]
     runs-on: ubuntu-latest
-    
+
     environment:
       name: testpypi
       url: https://test.pypi.org/p/PySHDL
-    
+
     permissions:
       id-token: write
-    
+
     steps:
       - name: Download all the dists
         uses: actions/download-artifact@v4
         with:
           name: python-package-distributions
           path: dist/
-      
+
       - name: Publish distribution to TestPyPI
         uses: pypa/gh-action-pypi-publish@release/v1
         with:

pyshdl-1.0.0/.gitignore

@@ -0,0 +1,31 @@
+# Python bytecode / packaging
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Virtual environments
+.venv/
+
+# Tool caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+
+# Compiled simulator artifacts emitted by shdlc (shared libraries)
+*.so
+*.dylib
+*.dll
+
+# macOS
+.DS_Store
+
+# Claude Code: keep shareable workflows under version control; ignore local state
+.claude/*
+!.claude/workflows/

pyshdl-1.0.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: PySHDL
+Version: 1.0.0
+Summary: SHDL hardware-description toolchain: the PySHDL user-facing driver, the SHDL→Base SHDL flattener, the Base SHDL→C compiler (shdlc), and the conformance suite.
+Project-URL: Homepage, https://github.com/rafa-rrayes/SHDL
+Project-URL: Repository, https://github.com/rafa-rrayes/SHDL
+Project-URL: Documentation, https://rafa-rrayes.github.io/SHDL/
+Author-email: rafa-rrayes <rafa@rayes.com.br>
+License-Expression: GPL-3.0-or-later
+License-File: LICENSE
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# SHDL
+
+SHDL (Simple Hardware Description Language) is an educational, gate-level
+hardware description language and simulation toolchain. Its founding principle
+is **fidelity**: circuits simulate gate by gate, one propagation level per
+cycle (the unit-delay model), and no tool in the chain is allowed to collapse
+or shortcut that structure. You describe hardware out of AND/OR/NOT/XOR; you
+watch signals ripple through it.
+
+## The two languages
+
+**SHDL** is the authoring language: reusable hierarchical components,
+multi-bit ports, compile-time parameters, generators and conditionals for
+repetitive structure, bit slices and concatenation, named constants, optional
+initial state, and imports. Specified in [docs/shdl.md](docs/shdl.md).
+
+**Base SHDL** is the intermediate representation every tool consumes: a flat
+netlist of single-bit wires over exactly six primitives — `AND`, `OR`, `NOT`,
+`XOR`, `__VCC__`, `__GND__` — plus a JSON metadata section (multi-bit port
+groups, hierarchy, source maps, timing, constants, init seeds). Specified in
+[docs/base_shdl.md](docs/base_shdl.md).
+
+## Pipeline
+
+```
+ .shdl source
+      │
+      ▼
+  Flattener        six phases: strip, monomorphize, expand generators,
+      │            expand slices, materialize constants, flatten hierarchy
+      ▼
+  Base SHDL        single-bit primitive netlist + JSON metadata
+      │
+      ▼
+  SHDLC            generates C (two-buffer compute/commit cycle),
+      │            builds a shared library with a stable ABI
+      ▼
+  libcircuit       reset() / poke() / peek() / step()
+                   (+ step_settle() / run_batch() throughput paths)
+```
+
+## Quickstart
+
+Requires Python ≥ 3.14 and a C compiler (clang or gcc).
+
+Install the released package from PyPI to get the `SHDL` Python package and the
+`shdlc` / `shdl-flatten` / `shdl-conformance` CLIs:
+
+```sh
+pip install PySHDL          # or: uv add PySHDL
+```
+
+Or work from a clone with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv sync
+
+# Flatten SHDL to Base SHDL (inspect the IR)
+uv run shdl-flatten examples/fullAdder.shdl
+
+# Compile straight from SHDL source to a shared library
+uv run shdlc examples/fullAdder.shdl -o fullAdder.dylib
+```
+
+Drive a circuit from Python with **PySHDL** — one class, `Circuit`, runs the
+whole pipeline (flatten → compile → build → load) in-process and exposes
+poke/peek/step plus dict access and a context manager:
+
+```python
+from SHDL import Circuit
+
+with Circuit("examples/adder8.shdl") as c:
+    c["A"] = 100            # dict-style poke; bit 0 is the LSB
+    c["B"] = 55
+    c.settle()             # advance every gate level (combinational depth)
+    print(c["Sum"])         # 155
+```
+
+See [docs/pyshdl.md](docs/pyshdl.md) for the full guide, and
+[examples/interacting.py](examples/interacting.py) for a runnable walkthrough
+(`uv run python examples/interacting.py`). The underlying ABI is callable from
+any language; see [docs/shdlc_goals.md](docs/shdlc_goals.md) §3 for the full
+contract (masking, lazy evaluation, init-seeded power-on state).
+
+## Repository layout
+
+| Path | What it is |
+|---|---|
+| `flattener/` | SHDL → Base SHDL (lexer, parser, six lowering phases, metadata, `HighEval` reference interpreter) |
+| `shdlc/` | Base SHDL → C → shared library (model, codegen, cc driver, `BaseEval` reference interpreter, ctypes harness) |
+| `SHDL/` | The user-facing Python driver: `Circuit` runs the pipeline in-process and exposes poke/peek/step (`from SHDL import Circuit`) |
+| `conformance/` | Frozen corpus of cases with golden Base SHDL + cycle-by-cycle traces, and its runner |
+| `tests/` | `flattener/`, `compiler/`, and `cpu/` suites (~1640 tests) |
+| `examples/` | Small circuits (adders, latches, mux, ALU) and a complete, verified 16-bit CPU (`examples/CPU/`) |
+| `docs/` | The normative specs and the verification map |
+| `scripts/` | Maintenance tooling (conformance corpus builder) |
+
+The flattener and shdlc are deliberately decoupled: Base SHDL text is the
+*only* contract between them, and each side carries its own independent
+reference interpreter so the two can cross-check each other.
+
+## Testing
+
+```sh
+uv run pytest                    # full suite
+uv run shdl-conformance run      # golden corpus: flatten + compile + trace lockstep
+```
+
+The suite covers per-phase units, per-raise-site diagnostics (every error's
+exact position is pinned), differential fuzzing against two independent
+oracles, byte-determinism, ABI contracts under ASAN/UBSAN, and instruction-
+level lockstep of the example CPU against a golden model.
+
+## Documentation
+
+- [docs/SHDL_Project.md](docs/SHDL_Project.md) — project charter: architecture, ecosystem, build sequence.
+- [docs/shdl.md](docs/shdl.md) — the SHDL language specification.
+- [docs/base_shdl.md](docs/base_shdl.md) — the Base SHDL IR specification.
+- [docs/shdlc_goals.md](docs/shdlc_goals.md) — the compiler's obligations and ABI contract.
+- [docs/golden_tests.md](docs/golden_tests.md) — the verification map tying every spec obligation to tests.
+
+## Status
+
+The flattener, the SHDLC compiler (release ABI), the conformance suite, and
+**PySHDL** — the user-facing Python driver (`from SHDL import Circuit`) — are
+complete and green. Next up are the debug build and the SHDB debugger — see the
+build sequence in the charter.

pyshdl-1.0.0/README.md

@@ -0,0 +1,127 @@
+# SHDL
+
+SHDL (Simple Hardware Description Language) is an educational, gate-level
+hardware description language and simulation toolchain. Its founding principle
+is **fidelity**: circuits simulate gate by gate, one propagation level per
+cycle (the unit-delay model), and no tool in the chain is allowed to collapse
+or shortcut that structure. You describe hardware out of AND/OR/NOT/XOR; you
+watch signals ripple through it.
+
+## The two languages
+
+**SHDL** is the authoring language: reusable hierarchical components,
+multi-bit ports, compile-time parameters, generators and conditionals for
+repetitive structure, bit slices and concatenation, named constants, optional
+initial state, and imports. Specified in [docs/shdl.md](docs/shdl.md).
+
+**Base SHDL** is the intermediate representation every tool consumes: a flat
+netlist of single-bit wires over exactly six primitives — `AND`, `OR`, `NOT`,
+`XOR`, `__VCC__`, `__GND__` — plus a JSON metadata section (multi-bit port
+groups, hierarchy, source maps, timing, constants, init seeds). Specified in
+[docs/base_shdl.md](docs/base_shdl.md).
+
+## Pipeline
+
+```
+ .shdl source
+      │
+      ▼
+  Flattener        six phases: strip, monomorphize, expand generators,
+      │            expand slices, materialize constants, flatten hierarchy
+      ▼
+  Base SHDL        single-bit primitive netlist + JSON metadata
+      │
+      ▼
+  SHDLC            generates C (two-buffer compute/commit cycle),
+      │            builds a shared library with a stable ABI
+      ▼
+  libcircuit       reset() / poke() / peek() / step()
+                   (+ step_settle() / run_batch() throughput paths)
+```
+
+## Quickstart
+
+Requires Python ≥ 3.14 and a C compiler (clang or gcc).
+
+Install the released package from PyPI to get the `SHDL` Python package and the
+`shdlc` / `shdl-flatten` / `shdl-conformance` CLIs:
+
+```sh
+pip install PySHDL          # or: uv add PySHDL
+```
+
+Or work from a clone with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv sync
+
+# Flatten SHDL to Base SHDL (inspect the IR)
+uv run shdl-flatten examples/fullAdder.shdl
+
+# Compile straight from SHDL source to a shared library
+uv run shdlc examples/fullAdder.shdl -o fullAdder.dylib
+```
+
+Drive a circuit from Python with **PySHDL** — one class, `Circuit`, runs the
+whole pipeline (flatten → compile → build → load) in-process and exposes
+poke/peek/step plus dict access and a context manager:
+
+```python
+from SHDL import Circuit
+
+with Circuit("examples/adder8.shdl") as c:
+    c["A"] = 100            # dict-style poke; bit 0 is the LSB
+    c["B"] = 55
+    c.settle()             # advance every gate level (combinational depth)
+    print(c["Sum"])         # 155
+```
+
+See [docs/pyshdl.md](docs/pyshdl.md) for the full guide, and
+[examples/interacting.py](examples/interacting.py) for a runnable walkthrough
+(`uv run python examples/interacting.py`). The underlying ABI is callable from
+any language; see [docs/shdlc_goals.md](docs/shdlc_goals.md) §3 for the full
+contract (masking, lazy evaluation, init-seeded power-on state).
+
+## Repository layout
+
+| Path | What it is |
+|---|---|
+| `flattener/` | SHDL → Base SHDL (lexer, parser, six lowering phases, metadata, `HighEval` reference interpreter) |
+| `shdlc/` | Base SHDL → C → shared library (model, codegen, cc driver, `BaseEval` reference interpreter, ctypes harness) |
+| `SHDL/` | The user-facing Python driver: `Circuit` runs the pipeline in-process and exposes poke/peek/step (`from SHDL import Circuit`) |
+| `conformance/` | Frozen corpus of cases with golden Base SHDL + cycle-by-cycle traces, and its runner |
+| `tests/` | `flattener/`, `compiler/`, and `cpu/` suites (~1640 tests) |
+| `examples/` | Small circuits (adders, latches, mux, ALU) and a complete, verified 16-bit CPU (`examples/CPU/`) |
+| `docs/` | The normative specs and the verification map |
+| `scripts/` | Maintenance tooling (conformance corpus builder) |
+
+The flattener and shdlc are deliberately decoupled: Base SHDL text is the
+*only* contract between them, and each side carries its own independent
+reference interpreter so the two can cross-check each other.
+
+## Testing
+
+```sh
+uv run pytest                    # full suite
+uv run shdl-conformance run      # golden corpus: flatten + compile + trace lockstep
+```
+
+The suite covers per-phase units, per-raise-site diagnostics (every error's
+exact position is pinned), differential fuzzing against two independent
+oracles, byte-determinism, ABI contracts under ASAN/UBSAN, and instruction-
+level lockstep of the example CPU against a golden model.
+
+## Documentation
+
+- [docs/SHDL_Project.md](docs/SHDL_Project.md) — project charter: architecture, ecosystem, build sequence.
+- [docs/shdl.md](docs/shdl.md) — the SHDL language specification.
+- [docs/base_shdl.md](docs/base_shdl.md) — the Base SHDL IR specification.
+- [docs/shdlc_goals.md](docs/shdlc_goals.md) — the compiler's obligations and ABI contract.
+- [docs/golden_tests.md](docs/golden_tests.md) — the verification map tying every spec obligation to tests.
+
+## Status
+
+The flattener, the SHDLC compiler (release ABI), the conformance suite, and
+**PySHDL** — the user-facing Python driver (`from SHDL import Circuit`) — are
+complete and green. Next up are the debug build and the SHDB debugger — see the
+build sequence in the charter.

pyshdl-1.0.0/SHDL/__init__.py

@@ -0,0 +1,57 @@
+"""SHDL — the Python driver for SHDL circuits.
+
+The user-facing layer of the SHDL toolchain: compile a circuit (from a
+``.shdl`` file, SHDL source text, a Base SHDL artifact, or a prebuilt
+shared library) and drive the simulation through an ergonomic interface::
+
+    from SHDL import Circuit
+
+    with Circuit("examples/adder8.shdl") as c:
+        c["A"] = 100
+        c["B"] = 55
+        c.settle()
+        print(c["Sum"])  # 155
+
+Everything runs in-process: the flattener lowers SHDL to Base SHDL, shdlc
+generates C, the host C compiler builds a shared library, and ctypes loads
+a private copy of it. See ``docs/pyshdl.md`` for the user guide.
+"""
+
+from __future__ import annotations
+
+__version__ = "1.0.0"
+
+from .circuit import Circuit
+from .errors import (
+    BuildError,
+    ClosedCircuitError,
+    CompilationError,
+    CompileError,
+    FlattenError,
+    MetadataUnavailableError,
+    PortValueError,
+    PySHDLError,
+    SettleRefusedError,
+    SignalNotFoundError,
+    SimulationError,
+)
+from .info import CircuitInfo, PortInfo, TimingInfo
+
+__all__ = [
+    "BuildError",
+    "Circuit",
+    "CircuitInfo",
+    "ClosedCircuitError",
+    "CompilationError",
+    "CompileError",
+    "FlattenError",
+    "MetadataUnavailableError",
+    "PortInfo",
+    "PortValueError",
+    "PySHDLError",
+    "SettleRefusedError",
+    "SignalNotFoundError",
+    "SimulationError",
+    "TimingInfo",
+    "__version__",
+]