specreq 0.1.0__tar.gz

specreq-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Hogben
+
+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.

specreq-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: specreq
+Version: 0.1.0
+Summary: Write product specs as Python code.
+Author-email: William Hogben <will@willhogben.com>
+License-Expression: MIT
+Project-URL: Homepage, https://willhogben.com
+Project-URL: Repository, https://github.com/whogben/specreq
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typer>=0.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file

specreq-0.1.0/README.md

@@ -0,0 +1,6 @@
+# specreq
+
+Write product specs as Python code.
+1. Define reusable elements by subclassing `Requirement` — override `validate(self, product: Path)` for each node, or `_validate` to control how children are validated.
+2. Instance reusable elements to create specific product specs.
+3. Run `specreq <spec> <product> [--save] [--strict]` — `--save` writes the requirement tree as JSON; `--strict` turns off exception catching inside `_validate` (fail fast). Default collects exceptions with tracebacks.

specreq-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "specreq"
+version = "0.1.0"
+description = "Write product specs as Python code."
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "William Hogben", email = "will@willhogben.com" },
+]
+urls.Homepage = "https://willhogben.com"
+urls.Repository = "https://github.com/whogben/specreq"
+dependencies = [
+    "pydantic>=2.0",
+    "typer>=0.9",
+]
+
+[project.scripts]
+specreq = "specreq.cli:app"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

specreq-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

specreq-0.1.0/src/specreq/__init__.py

@@ -0,0 +1,93 @@
+"""specreq — write product specs as Python code."""
+
+from __future__ import annotations
+
+import traceback
+from pathlib import Path
+from typing import TypeVar, Generic
+
+from pydantic import BaseModel
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class Requirement(Generic[T]):
+    """Subclass to define a reusable spec element. Create instances to build a spec tree."""
+
+    _instances: list[Requirement] = []
+
+    def __init__(self, config: T | None = None, parent: Requirement | None = None):
+        self.config = config
+        self.parent = parent
+        self.children: list[Requirement] = []
+        if parent is not None:
+            parent.children.append(self)
+        Requirement._instances.append(self)
+
+    @staticmethod
+    def _format_node_exception(node: Requirement, exc: BaseException) -> str:
+        fqn = f"{node.__class__.__module__}.{node.__class__.__qualname__}"
+        tb = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
+        return f"exception at {fqn}: {type(exc).__name__}: {exc}\n{tb}"
+
+    def _validate(self, product: Path, *, survive_exceptions: bool = True) -> list[str]:
+        """Run ``_validate`` on each child, then ``validate`` on this node.
+
+        Override this when you need to choose which children validate or in what order.
+        Forward ``survive_exceptions`` if you call ``super()._validate`` from a subclass.
+
+        When ``survive_exceptions`` is True (default), child failures are recorded with a
+        full traceback string and validation continues. When False, the first exception
+        propagates (``validate`` is never wrapped — only this orchestration).
+        """
+        issues: list[str] = []
+        for child in self.children:
+            if survive_exceptions:
+                try:
+                    issues.extend(
+                        child._validate(
+                            product, survive_exceptions=survive_exceptions
+                        )
+                    )
+                except Exception as e:
+                    issues.append(self._format_node_exception(child, e))
+            else:
+                issues.extend(
+                    child._validate(
+                        product, survive_exceptions=survive_exceptions
+                    )
+                )
+        if survive_exceptions:
+            try:
+                issues.extend(self.validate(product))
+            except Exception as e:
+                issues.append(self._format_node_exception(self, e))
+        else:
+            issues.extend(self.validate(product))
+        return issues
+
+    def validate(self, product: Path) -> list[str]:
+        """Return issues for this node only. Children are handled by ``_validate``."""
+        return []
+
+    def to_dict(self) -> dict:
+        d: dict = {
+            "class": f"{self.__class__.__module__}.{self.__class__.__qualname__}",
+        }
+        if self.config is not None:
+            d["config"] = self.config.model_dump()
+        if self.children:
+            d["children"] = [c.to_dict() for c in self.children]
+        return d
+
+    @classmethod
+    def export_roots(cls) -> list[dict]:
+        """Serialize all root instances (no parent) as a list of dicts."""
+        return [i.to_dict() for i in cls._instances if i.parent is None]
+
+    @classmethod
+    def reset(cls):
+        cls._instances.clear()
+
+
+__all__ = ["Requirement"]

specreq-0.1.0/src/specreq/cli.py

@@ -0,0 +1,117 @@
+"""specreq CLI."""
+
+from __future__ import annotations
+
+import importlib
+import json
+import sys
+import traceback
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from specreq import Requirement
+
+app = typer.Typer()
+
+
+def _resolve_module_name(target: str) -> str:
+    """Top-level module name used by importlib / sys.modules for this target."""
+    path = Path(target)
+    if path.exists():
+        return path.name if path.is_dir() else path.stem
+    return target
+
+
+def _import_target(target: str):
+    """Import a module by dotted name or file path. Returns the module."""
+    path = Path(target)
+    if path.exists():
+        # file or dir — add parent to sys.path, import by name
+        parent = str(path.parent.resolve())
+        if parent not in sys.path:
+            sys.path.insert(0, parent)
+        if path.is_dir():
+            name = path.name
+        else:
+            name = path.stem
+        return importlib.import_module(name)
+    else:
+        # treat as dotted module name
+        return importlib.import_module(target)
+
+
+def _load_spec(target: str):
+    """Load or reload the spec module so import-time instances run after Requirement.reset()."""
+    name = _resolve_module_name(target)
+    if name in sys.modules:
+        return importlib.reload(sys.modules[name])
+    return _import_target(target)
+
+
+@app.command()
+def validate(
+    spec: Annotated[str, typer.Argument(help="Spec module: file path or dotted name")],
+    product: Annotated[str, typer.Argument(help="Path to the product directory")],
+    save: bool = typer.Option(False, "--save", help="Save spec tree as JSON on success"),
+    strict: bool = typer.Option(
+        False,
+        "--strict",
+        help="Propagate validator exceptions (no per-node catch inside _validate)",
+    ),
+):
+    """Validate a product against a spec."""
+    Requirement.reset()
+    try:
+        _load_spec(spec)
+    except ModuleNotFoundError as e:
+        typer.echo(f"Could not import spec: {e}")
+        raise typer.Exit(1)
+
+    instances = Requirement._instances
+    if not instances:
+        typer.echo("No Requirement instances found in spec.")
+        raise typer.Exit(1)
+
+    product_path_obj = Path(product).resolve()
+    if not product_path_obj.exists():
+        typer.echo(f"Product path does not exist: {product_path_obj}")
+        raise typer.Exit(1)
+
+    roots = [i for i in instances if i.parent is None]
+    if not roots:
+        typer.echo("No root Requirement instances found (every instance has a parent).")
+        raise typer.Exit(1)
+
+    survive = not strict
+    issues: list[str] = []
+    for root in roots:
+        tag = f"{root.__class__.__module__}.{root.__class__.__qualname__}"
+        try:
+            lines = root._validate(
+                product_path_obj, survive_exceptions=survive
+            )
+            issues.extend(f"[root {tag}] {line}" for line in lines)
+        except Exception as e:
+            tb = "".join(traceback.format_exception(type(e), e, e.__traceback__))
+            issues.append(
+                f"[root {tag}] exception escaped _validate tree: "
+                f"{type(e).__name__}: {e}\n{tb}"
+            )
+
+    if issues:
+        typer.echo(f"Issues ({len(issues)}):")
+        for i in issues:
+            typer.echo(f"  - {i}")
+        raise typer.Exit(1)
+
+    typer.echo(f"Valid. {len(roots)} root(s) passed.")
+
+    if save:
+        out = Path(f"{Path(spec).stem}.json") if Path(spec).exists() else Path(f"{spec.split('.')[-1]}.json")
+        out.write_text(json.dumps(Requirement.export_roots(), indent=2))
+        typer.echo(f"Saved {out}")
+
+
+if __name__ == "__main__":
+    app()

specreq-0.1.0/src/specreq.egg-info/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: specreq
+Version: 0.1.0
+Summary: Write product specs as Python code.
+Author-email: William Hogben <will@willhogben.com>
+License-Expression: MIT
+Project-URL: Homepage, https://willhogben.com
+Project-URL: Repository, https://github.com/whogben/specreq
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typer>=0.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file

specreq-0.1.0/src/specreq.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/specreq/__init__.py
+src/specreq/cli.py
+src/specreq.egg-info/PKG-INFO
+src/specreq.egg-info/SOURCES.txt
+src/specreq.egg-info/dependency_links.txt
+src/specreq.egg-info/entry_points.txt
+src/specreq.egg-info/requires.txt
+src/specreq.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_requirement.py

specreq-0.1.0/src/specreq.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

specreq-0.1.0/src/specreq.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+specreq = specreq.cli:app

specreq-0.1.0/src/specreq.egg-info/requires.txt

@@ -0,0 +1,5 @@
+pydantic>=2.0
+typer>=0.9
+
+[dev]
+pytest>=7

specreq-0.1.0/src/specreq.egg-info/top_level.txt

@@ -0,0 +1 @@
+specreq

specreq-0.1.0/tests/test_cli.py

@@ -0,0 +1,151 @@
+import json
+from pathlib import Path
+
+from typer.testing import CliRunner
+
+from specreq.cli import app
+
+runner = CliRunner()
+
+SPEC_PY = '''\
+from specreq import Requirement
+
+
+class Root(Requirement):
+    pass
+
+
+Root()
+'''
+
+SPEC_NO_INSTANCES = """\
+from specreq import Requirement
+
+
+class Root(Requirement):
+    pass
+"""
+
+SPEC_ERROR = '''\
+from pathlib import Path
+
+from specreq import Requirement
+
+
+class Root(Requirement):
+    def validate(self, product: Path) -> list[str]:
+        raise ValueError("spec boom")
+
+
+Root()
+'''
+
+SPEC_TWO_ROOTS = '''\
+from specreq import Requirement
+
+
+class A(Requirement):
+    pass
+
+
+class B(Requirement):
+    pass
+
+
+A()
+B()
+'''
+
+
+def _write_spec(tmp: Path, filename: str, content: str) -> Path:
+    p = tmp / filename
+    p.write_text(content)
+    return p
+
+
+def test_validate_file_spec(tmp_path):
+    spec = _write_spec(tmp_path, "file_spec.py", SPEC_PY)
+    result = runner.invoke(app, [str(spec), str(tmp_path)])
+    assert result.exit_code == 0
+    assert "Valid." in result.stdout
+
+
+def test_validate_twice_same_process_reloads_spec(tmp_path):
+    """Second invoke must rebuild instances after reset (sys.modules cache)."""
+    spec = _write_spec(tmp_path, "reload_spec.py", SPEC_PY)
+    for _ in range(2):
+        result = runner.invoke(app, [str(spec), str(tmp_path)])
+        assert result.exit_code == 0, result.stdout
+        assert "Valid." in result.stdout
+
+
+def test_validate_no_instances(tmp_path):
+    spec = _write_spec(tmp_path, "empty_spec.py", SPEC_NO_INSTANCES)
+    result = runner.invoke(app, [str(spec), str(tmp_path)])
+    assert result.exit_code == 1
+    assert "No Requirement instances" in result.stdout
+
+
+def test_validate_missing_product(tmp_path):
+    spec = _write_spec(tmp_path, "prod_spec.py", SPEC_PY)
+    missing = tmp_path / "nope"
+    result = runner.invoke(app, [str(spec), str(missing)])
+    assert result.exit_code == 1
+    assert "Product path does not exist" in result.stdout
+
+
+def test_validate_missing_spec_module(tmp_path):
+    result = runner.invoke(
+        app, ["not_a_real_module_xyz_abc", str(tmp_path)]
+    )
+    assert result.exit_code == 1
+    assert "Could not import spec" in result.stdout
+
+
+def test_validate_survive_includes_traceback(tmp_path):
+    spec = _write_spec(tmp_path, "boom_spec.py", SPEC_ERROR)
+    result = runner.invoke(app, [str(spec), str(tmp_path)])
+    assert result.exit_code == 1
+    assert "Traceback (most recent call last)" in result.stdout
+    assert "exception at" in result.stdout
+
+
+def test_validate_strict_propagates(tmp_path):
+    spec = _write_spec(tmp_path, "strict_spec.py", SPEC_ERROR)
+    result = runner.invoke(app, [str(spec), str(tmp_path), "--strict"])
+    assert result.exit_code == 1
+    assert result.exception is not None
+
+
+def test_validate_two_roots(tmp_path):
+    spec = _write_spec(tmp_path, "two_roots.py", SPEC_TWO_ROOTS)
+    result = runner.invoke(app, [str(spec), str(tmp_path)])
+    assert result.exit_code == 0
+    assert "2 root(s) passed." in result.stdout
+
+
+def test_validate_save_writes_json(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    spec = _write_spec(tmp_path, "save_me.py", SPEC_PY)
+    result = runner.invoke(app, [str(spec), str(tmp_path), "--save"])
+    assert result.exit_code == 0
+    assert "Saved save_me.json" in result.stdout
+
+    out = tmp_path / "save_me.json"
+    assert out.is_file()
+    data = json.loads(out.read_text())
+    assert isinstance(data, list)
+    assert len(data) == 1
+    assert "class" in data[0]
+    assert data[0]["class"].endswith("Root")
+
+
+def test_validate_save_two_roots_json(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    spec = _write_spec(tmp_path, "pair_spec.py", SPEC_TWO_ROOTS)
+    result = runner.invoke(app, [str(spec), str(tmp_path), "--save"])
+    assert result.exit_code == 0
+    data = json.loads((tmp_path / "pair_spec.json").read_text())
+    assert len(data) == 2
+    names = {entry["class"].split(".")[-1] for entry in data}
+    assert names == {"A", "B"}

specreq-0.1.0/tests/test_requirement.py

@@ -0,0 +1,230 @@
+"""Unit tests for Requirement validation order, trees, and serialization."""
+
+from pathlib import Path
+
+import pytest
+from pydantic import BaseModel
+
+from specreq import Requirement
+
+
+def test_validate_runs_children_before_parent():
+    Requirement.reset()
+    order: list[str] = []
+
+    class Child(Requirement):
+        def validate(self, product: Path) -> list[str]:
+            order.append("child")
+            return []
+
+    class Parent(Requirement):
+        def validate(self, product: Path) -> list[str]:
+            order.append("parent")
+            return []
+
+    p = Parent()
+    Child(parent=p)
+
+    product = Path("/tmp")
+    p._validate(product)
+    assert order == ["child", "parent"]
+
+
+def test_custom_validate_issues():
+    Requirement.reset()
+
+    class R(Requirement):
+        def validate(self, product: Path) -> list[str]:
+            return ["bad"]
+
+    r = R()
+    assert r._validate(Path("/tmp")) == ["bad"]
+
+
+def test_override_validate_skips_default_child_walk():
+    Requirement.reset()
+
+    class Leaf(Requirement):
+        def validate(self, product: Path) -> list[str]:
+            return ["leaf"]
+
+    class Parent(Requirement):
+        def _validate(self, product: Path, *, survive_exceptions: bool = True) -> list[str]:
+            return ["custom"]
+
+    parent = Parent()
+    Leaf(parent=parent)
+    assert parent._validate(Path("/tmp"), survive_exceptions=True) == ["custom"]
+
+
+def test_survive_exceptions_records_traceback():
+    Requirement.reset()
+
+    class Boom(Requirement):
+        def validate(self, product: Path) -> list[str]:
+            raise ValueError("nope")
+
+    b = Boom()
+    issues = b._validate(Path("/tmp"), survive_exceptions=True)
+    assert len(issues) == 1
+    assert "exception at" in issues[0]
+    assert "ValueError: nope" in issues[0]
+    assert "Traceback (most recent call last)" in issues[0]
+
+
+def test_survive_exceptions_false_propagates():
+    Requirement.reset()
+
+    class Boom(Requirement):
+        def validate(self, product: Path) -> list[str]:
+            raise RuntimeError("boom")
+
+    b = Boom()
+    with pytest.raises(RuntimeError, match="boom"):
+        b._validate(Path("/tmp"), survive_exceptions=False)
+
+
+def test_to_dict_includes_config_and_nested_children():
+    Requirement.reset()
+
+    class Cfg(BaseModel):
+        name: str
+        port: int = 9
+
+    class Leaf(Requirement):
+        pass
+
+    class Root(Requirement[Cfg]):
+        pass
+
+    root = Root(config=Cfg(name="svc", port=80))
+    Leaf(parent=root)
+
+    d = root.to_dict()
+    assert d["config"] == {"name": "svc", "port": 80}
+    assert d["class"].endswith("Root")
+    assert len(d["children"]) == 1
+    assert d["children"][0]["class"].endswith("Leaf")
+    assert "config" not in d["children"][0]
+
+    roots = Requirement.export_roots()
+    assert len(roots) == 1
+    assert roots[0] == d
+
+
+def test_validate_reads_config():
+    Requirement.reset()
+
+    class Cfg(BaseModel):
+        env: str
+
+    class R(Requirement[Cfg]):
+        def validate(self, product: Path) -> list[str]:
+            if self.config is None or self.config.env != "prod":
+                return ["wrong env"]
+            return []
+
+    r = R(config=Cfg(env="prod"))
+    assert r._validate(Path("/tmp")) == []
+
+
+def test_three_level_validate_order():
+    Requirement.reset()
+    order: list[str] = []
+
+    class L3(Requirement):
+        def validate(self, product: Path) -> list[str]:
+            order.append("l3")
+            return []
+
+    class L2(Requirement):
+        def validate(self, product: Path) -> list[str]:
+            order.append("l2")
+            return []
+
+    class L1(Requirement):
+        def validate(self, product: Path) -> list[str]:
+            order.append("l1")
+            return []
+
+    l1 = L1()
+    l2 = L2(parent=l1)
+    L3(parent=l2)
+
+    l1._validate(Path("/tmp"))
+    assert order == ["l3", "l2", "l1"]
+
+
+def test_mixed_child_issues_parent_still_runs_all_children():
+    Requirement.reset()
+    order: list[str] = []
+
+    class Bad(Requirement):
+        def validate(self, product: Path) -> list[str]:
+            order.append("bad")
+            return ["from-bad"]
+
+    class Ok(Requirement):
+        def validate(self, product: Path) -> list[str]:
+            order.append("ok")
+            return []
+
+    class Parent(Requirement):
+        def validate(self, product: Path) -> list[str]:
+            order.append("parent")
+            return []
+
+    p = Parent()
+    Bad(parent=p)
+    Ok(parent=p)
+
+    issues = p._validate(Path("/tmp"), survive_exceptions=True)
+    assert order == ["bad", "ok", "parent"]
+    assert issues == ["from-bad"]
+
+
+def test_mixed_child_raise_sibling_and_parent_still_run():
+    Requirement.reset()
+    order: list[str] = []
+
+    class Boom(Requirement):
+        def validate(self, product: Path) -> list[str]:
+            order.append("boom")
+            raise RuntimeError("child boom")
+
+    class Ok(Requirement):
+        def validate(self, product: Path) -> list[str]:
+            order.append("ok")
+            return []
+
+    class Parent(Requirement):
+        def validate(self, product: Path) -> list[str]:
+            order.append("parent")
+            return []
+
+    p = Parent()
+    Boom(parent=p)
+    Ok(parent=p)
+
+    issues = p._validate(Path("/tmp"), survive_exceptions=True)
+    assert order == ["boom", "ok", "parent"]
+    assert len(issues) == 1
+    assert "RuntimeError: child boom" in issues[0]
+    assert "Traceback" in issues[0]
+
+
+def test_multi_root_export_roots():
+    Requirement.reset()
+
+    class A(Requirement):
+        pass
+
+    class B(Requirement):
+        pass
+
+    A()
+    B()
+    roots = Requirement.export_roots()
+    assert len(roots) == 2
+    classes = {r["class"].split(".")[-1] for r in roots}
+    assert classes == {"A", "B"}