makeprov 0.1.1__tar.gz

makeprov-0.1.1/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: makeprov
+Version: 0.1.1
+Summary: An RDF provenance tracking library for simple Python workflows
+Author-email: Benno Kruit <b.b.kruit@amsterdamumc.nl>
+License: MIT
+Project-URL: Homepage, https://github.com/bennokr/makeprov
+Project-URL: Documentation, https://makeprov.readthedocs.io
+Project-URL: Issue Tracker, https://github.com/bennokr/makeprov/issues
+Keywords: provenance,rdf,workflow,python
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+
+# makeprov: Pythonic Provenance Tracking
+
+This library provides a way to track file provenance in Python workflows using RDF and PROV (W3C Provenance) semantics. It supports defining input/output files via decorators and automatically generates provenance datasets.
+
+## Features
+
+- Use decorators to define rules for workflows.
+- Automatically generate RDF-based provenance metadata.
+- Handles input and output streams.
+- Integrates with Python's type hints for easy configuration.
+- Outputs provenance data in TRIG format.
+
+## Installation
+
+You can install the module directly from PyPI:
+
+```bash
+pip install makeprov
+```
+
+## Usage
+
+Here’s an example of how to use this package in your Python scripts:
+
+```python
+from makeprov import rule, InFile, OutFile, build
+
+@rule()
+def process_data(
+    input_file: InFile = InFile('input.txt'), 
+    output_file: OutFile = OutFile('output.txt')
+):
+    with input_file.open('r') as infile, output_file.open('w') as outfile:
+        data = infile.read()
+        outfile.write(data.upper())
+
+if __name__ == '__main__':
+    process_data()
+
+    # or as a command line interface
+    import defopt
+    defopt.run(process_data)
+
+    # or as a workflow graph that automatically (re)generates all dependencies
+    from makeprov import build
+    build('output.txt')
+```
+
+You can execute `example.py` via the CLI like so:
+
+```bash
+python example.py build-all
+
+# Or set configuration through the CLI
+python example.py build-all --conf='{"base_iri": "http://mybaseiri.org/", "prov_dir": "my_prov_directory"}' --force --input_file input.txt --output_file final_output.txt
+
+# Or set configuration through a TOML file
+python example.py build-all --conf=@my_config.toml
+```
+
+### Complex CSV-to-RDF Workflow
+
+For a more involved scenario, see [`complex_example.py`](complex_example.py). It creates multiple CSV files, aggregates their contents, and emits an RDF graph that is both serialized to disk and embedded into the provenance dataset because the function returns an `rdflib.Graph`.
+
+```python
+@rule()
+def export_totals_graph(
+    totals_csv: InFile = InFile("data/region_totals.csv"),
+    graph_ttl: OutFile = OutFile("data/region_totals.ttl"),
+) -> Graph:
+    graph = Graph()
+    graph.bind("sales", SALES)
+
+    with totals_csv.open("r", newline="") as handle:
+        for row in csv.DictReader(handle):
+            region_key = row["region"].lower().replace(" ", "-")
+            subject = SALES[f"region/{region_key}"]
+
+            graph.add((subject, RDF.type, SALES.RegionTotal))
+            graph.add((subject, SALES.regionName, Literal(row["region"])))
+            graph.add((subject, SALES.totalUnits, Literal(row["total_units"], datatype=XSD.integer)))
+            graph.add((subject, SALES.totalRevenue, Literal(row["total_revenue"], datatype=XSD.decimal)))
+
+    with graph_ttl.open("w") as handle:
+        handle.write(graph.serialize(format="turtle"))
+
+    return graph
+```
+
+Run the entire workflow, including CSV generation and RDF export, with:
+
+```bash
+python complex_example.py build-sales-report
+```
+
+### Configuration
+
+You can customize the provenance tracking with the following options:
+
+ - `base_iri` (str): Base IRI for new resources
+ - `prov_dir` (str): Directory for writing PROV `.trig` files
+ - `force` (bool): Force running of dependencies
+ - `dry_run` (bool): Only check workflow, don't run anything
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

makeprov-0.1.1/README.md

@@ -0,0 +1,111 @@
+# makeprov: Pythonic Provenance Tracking
+
+This library provides a way to track file provenance in Python workflows using RDF and PROV (W3C Provenance) semantics. It supports defining input/output files via decorators and automatically generates provenance datasets.
+
+## Features
+
+- Use decorators to define rules for workflows.
+- Automatically generate RDF-based provenance metadata.
+- Handles input and output streams.
+- Integrates with Python's type hints for easy configuration.
+- Outputs provenance data in TRIG format.
+
+## Installation
+
+You can install the module directly from PyPI:
+
+```bash
+pip install makeprov
+```
+
+## Usage
+
+Here’s an example of how to use this package in your Python scripts:
+
+```python
+from makeprov import rule, InFile, OutFile, build
+
+@rule()
+def process_data(
+    input_file: InFile = InFile('input.txt'), 
+    output_file: OutFile = OutFile('output.txt')
+):
+    with input_file.open('r') as infile, output_file.open('w') as outfile:
+        data = infile.read()
+        outfile.write(data.upper())
+
+if __name__ == '__main__':
+    process_data()
+
+    # or as a command line interface
+    import defopt
+    defopt.run(process_data)
+
+    # or as a workflow graph that automatically (re)generates all dependencies
+    from makeprov import build
+    build('output.txt')
+```
+
+You can execute `example.py` via the CLI like so:
+
+```bash
+python example.py build-all
+
+# Or set configuration through the CLI
+python example.py build-all --conf='{"base_iri": "http://mybaseiri.org/", "prov_dir": "my_prov_directory"}' --force --input_file input.txt --output_file final_output.txt
+
+# Or set configuration through a TOML file
+python example.py build-all --conf=@my_config.toml
+```
+
+### Complex CSV-to-RDF Workflow
+
+For a more involved scenario, see [`complex_example.py`](complex_example.py). It creates multiple CSV files, aggregates their contents, and emits an RDF graph that is both serialized to disk and embedded into the provenance dataset because the function returns an `rdflib.Graph`.
+
+```python
+@rule()
+def export_totals_graph(
+    totals_csv: InFile = InFile("data/region_totals.csv"),
+    graph_ttl: OutFile = OutFile("data/region_totals.ttl"),
+) -> Graph:
+    graph = Graph()
+    graph.bind("sales", SALES)
+
+    with totals_csv.open("r", newline="") as handle:
+        for row in csv.DictReader(handle):
+            region_key = row["region"].lower().replace(" ", "-")
+            subject = SALES[f"region/{region_key}"]
+
+            graph.add((subject, RDF.type, SALES.RegionTotal))
+            graph.add((subject, SALES.regionName, Literal(row["region"])))
+            graph.add((subject, SALES.totalUnits, Literal(row["total_units"], datatype=XSD.integer)))
+            graph.add((subject, SALES.totalRevenue, Literal(row["total_revenue"], datatype=XSD.decimal)))
+
+    with graph_ttl.open("w") as handle:
+        handle.write(graph.serialize(format="turtle"))
+
+    return graph
+```
+
+Run the entire workflow, including CSV generation and RDF export, with:
+
+```bash
+python complex_example.py build-sales-report
+```
+
+### Configuration
+
+You can customize the provenance tracking with the following options:
+
+ - `base_iri` (str): Base IRI for new resources
+ - `prov_dir` (str): Directory for writing PROV `.trig` files
+ - `force` (bool): Force running of dependencies
+ - `dry_run` (bool): Only check workflow, don't run anything
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

makeprov-0.1.1/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "makeprov"
+version = "0.1.1"
+description = "An RDF provenance tracking library for simple Python workflows"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Benno Kruit", email = "b.b.kruit@amsterdamumc.nl" }]
+keywords = ["provenance", "rdf", "workflow", "python"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/bennokr/makeprov"
+"Documentation" = "https://makeprov.readthedocs.io"
+"Issue Tracker" = "https://github.com/bennokr/makeprov/issues"
+
+[tool.pytape]
+test = "tests/test_makeprov.py"

makeprov-0.1.1/setup.cfg

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

makeprov-0.1.1/src/config.py

@@ -0,0 +1,45 @@
+from dataclasses import fields, is_dataclass
+import sys, logging, tomllib as toml, defopt
+import argparse
+
+
+def main(subcommands, conf_obj, parsers=None):
+    def conf(dc, params):
+        for f in fields(dc):
+            if f.name in params:
+                cur, new = getattr(dc, f.name), params[f.name]
+                if is_dataclass(cur) and isinstance(new, dict):
+                    conf(cur, new)
+                else:
+                    setattr(dc, f.name, new)
+
+    parent = argparse.ArgumentParser(add_help=False)
+    parent.add_argument(
+        "-c",
+        "--conf",
+        action="append",
+        default=[],
+        help="Set config param from TOML snippet or @file",
+    )
+    parent.add_argument(
+        "-v", "--verbose", action="count", default=0, help="Show more logging output"
+    )
+
+    def apply_globals(argv):
+        ns, _ = parent.parse_known_args(argv)
+        lvl = ("WARNING", "INFO", "DEBUG")[min(max(ns.verbose, 0), 2)]
+        logging.basicConfig(level=getattr(logging, lvl))
+        for t in ns.conf:
+            logging.debug(f"Parsing config {t}")
+            p = toml.load(open(t[1:], "rb")) if t.startswith("@") else toml.loads(t)
+            logging.debug(f"Setting config {p}")
+            conf(conf_obj, p)
+
+    apply_globals(sys.argv[1:])  # apply effects early
+    logging.debug(f"Config: {conf_obj}")
+    defopt.run(
+        subcommands,
+        parsers=parsers or {},
+        argv=sys.argv[1:],
+        argparse_kwargs={"parents": [parent]},
+    )

makeprov-0.1.1/src/makeprov.egg-info/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: makeprov
+Version: 0.1.1
+Summary: An RDF provenance tracking library for simple Python workflows
+Author-email: Benno Kruit <b.b.kruit@amsterdamumc.nl>
+License: MIT
+Project-URL: Homepage, https://github.com/bennokr/makeprov
+Project-URL: Documentation, https://makeprov.readthedocs.io
+Project-URL: Issue Tracker, https://github.com/bennokr/makeprov/issues
+Keywords: provenance,rdf,workflow,python
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+
+# makeprov: Pythonic Provenance Tracking
+
+This library provides a way to track file provenance in Python workflows using RDF and PROV (W3C Provenance) semantics. It supports defining input/output files via decorators and automatically generates provenance datasets.
+
+## Features
+
+- Use decorators to define rules for workflows.
+- Automatically generate RDF-based provenance metadata.
+- Handles input and output streams.
+- Integrates with Python's type hints for easy configuration.
+- Outputs provenance data in TRIG format.
+
+## Installation
+
+You can install the module directly from PyPI:
+
+```bash
+pip install makeprov
+```
+
+## Usage
+
+Here’s an example of how to use this package in your Python scripts:
+
+```python
+from makeprov import rule, InFile, OutFile, build
+
+@rule()
+def process_data(
+    input_file: InFile = InFile('input.txt'), 
+    output_file: OutFile = OutFile('output.txt')
+):
+    with input_file.open('r') as infile, output_file.open('w') as outfile:
+        data = infile.read()
+        outfile.write(data.upper())
+
+if __name__ == '__main__':
+    process_data()
+
+    # or as a command line interface
+    import defopt
+    defopt.run(process_data)
+
+    # or as a workflow graph that automatically (re)generates all dependencies
+    from makeprov import build
+    build('output.txt')
+```
+
+You can execute `example.py` via the CLI like so:
+
+```bash
+python example.py build-all
+
+# Or set configuration through the CLI
+python example.py build-all --conf='{"base_iri": "http://mybaseiri.org/", "prov_dir": "my_prov_directory"}' --force --input_file input.txt --output_file final_output.txt
+
+# Or set configuration through a TOML file
+python example.py build-all --conf=@my_config.toml
+```
+
+### Complex CSV-to-RDF Workflow
+
+For a more involved scenario, see [`complex_example.py`](complex_example.py). It creates multiple CSV files, aggregates their contents, and emits an RDF graph that is both serialized to disk and embedded into the provenance dataset because the function returns an `rdflib.Graph`.
+
+```python
+@rule()
+def export_totals_graph(
+    totals_csv: InFile = InFile("data/region_totals.csv"),
+    graph_ttl: OutFile = OutFile("data/region_totals.ttl"),
+) -> Graph:
+    graph = Graph()
+    graph.bind("sales", SALES)
+
+    with totals_csv.open("r", newline="") as handle:
+        for row in csv.DictReader(handle):
+            region_key = row["region"].lower().replace(" ", "-")
+            subject = SALES[f"region/{region_key}"]
+
+            graph.add((subject, RDF.type, SALES.RegionTotal))
+            graph.add((subject, SALES.regionName, Literal(row["region"])))
+            graph.add((subject, SALES.totalUnits, Literal(row["total_units"], datatype=XSD.integer)))
+            graph.add((subject, SALES.totalRevenue, Literal(row["total_revenue"], datatype=XSD.decimal)))
+
+    with graph_ttl.open("w") as handle:
+        handle.write(graph.serialize(format="turtle"))
+
+    return graph
+```
+
+Run the entire workflow, including CSV generation and RDF export, with:
+
+```bash
+python complex_example.py build-sales-report
+```
+
+### Configuration
+
+You can customize the provenance tracking with the following options:
+
+ - `base_iri` (str): Base IRI for new resources
+ - `prov_dir` (str): Directory for writing PROV `.trig` files
+ - `force` (bool): Force running of dependencies
+ - `dry_run` (bool): Only check workflow, don't run anything
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

makeprov-0.1.1/src/makeprov.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+src/config.py
+src/makeprov.py
+src/makeprov.egg-info/PKG-INFO
+src/makeprov.egg-info/SOURCES.txt
+src/makeprov.egg-info/dependency_links.txt
+src/makeprov.egg-info/top_level.txt
+tests/test_makeprov.py

makeprov-0.1.1/src/makeprov.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

makeprov-0.1.1/src/makeprov.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+config
+makeprov

makeprov-0.1.1/src/makeprov.py

@@ -0,0 +1,593 @@
+from __future__ import annotations
+
+import functools
+import logging
+import mimetypes
+import subprocess
+import sys
+import inspect
+import hashlib
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from datetime import datetime, timezone
+from typing import get_origin, get_args, get_type_hints, Any
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+import importlib.metadata as im
+
+import rdflib
+from rdflib import RDF, RDFS, XSD
+from rdflib.namespace import DCTERMS as DCT
+
+PROV = rdflib.Namespace("http://www.w3.org/ns/prov#")
+
+# ----------------------------------------------------------------------
+# Config
+# ----------------------------------------------------------------------
+
+
+@dataclass
+class ProvenanceConfig:
+    base_iri: str = "http://example.org/"
+    prov_dir: str = "prov"
+    force: bool = False  # if True, run even when up to date
+    dry_run: bool = False  # if True, do not run, just log
+
+
+GLOBAL_CONFIG = ProvenanceConfig()
+
+
+# ----------------------------------------------------------------------
+# File marker hierarchy (with "-" as stdin/stdout)
+# ----------------------------------------------------------------------
+
+
+class File(ABC):
+    """Abstract base for InFile / OutFile.
+
+    Common fields:
+      - raw: original string
+      - path: filesystem path or None (for streams)
+      - is_stream: True if "-" (stdin/stdout)
+      - stream_name: "stdin" / "stdout" / None
+    """
+
+    def __init__(self, path: str | Path, stream_name: str | None):
+        raw = str(path)
+        self.raw = raw
+
+        if raw == "-":
+            self.is_stream = True
+            self.stream_name = stream_name
+            self.path: Path | None = None
+        else:
+            self.is_stream = False
+            self.stream_name = None
+            self.path = Path(path)
+
+    def __fspath__(self):
+        if self.is_stream or self.path is None:
+            raise TypeError(
+                f"{self.__class__.__name__}('-') does not have a filesystem path"
+            )
+        return str(self.path)
+
+    def __str__(self) -> str:
+        return self.raw
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.raw!r})"
+
+    @abstractmethod
+    def open(self, mode: str = "", *args, **kwargs):
+        """Open underlying file or stream."""
+        ...
+
+
+class InFile(File):
+    """Marker type for input files (for provenance + DAG).
+
+    The string "-" stands for stdin.
+    """
+
+    def __init__(self, path: str):
+        super().__init__(path, stream_name="stdin")
+
+    def open(self, mode: str = "r", *args, **kwargs):
+        if self.is_stream:
+            return sys.stdin.buffer if "b" in mode else sys.stdin
+        if self.path is None:
+            raise ValueError("InFile has no path")
+        
+        return self.path.open(mode, *args, **kwargs)
+
+
+class OutFile(File):
+    """Marker type for output files (for provenance + DAG).
+
+    The string "-" stands for stdout.
+    """
+
+    def __init__(self, path: str):
+        super().__init__(path, stream_name="stdout")
+
+    def as_infile(self) -> InFile:
+        """Convert an OutFile path into a new InFile for downstream steps."""
+        if self.is_stream or self.path is None:
+            raise ValueError("Cannot convert a stream-based OutFile into an InFile")
+        return InFile(str(self.path))
+
+    def open(self, mode: str = "w", *args, **kwargs):
+        if self.is_stream:
+            return sys.stdout.buffer if "b" in mode else sys.stdout
+        if self.path is None:
+            raise ValueError("OutFile has no path")
+        
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        return self.path.open(mode, *args, **kwargs)
+
+
+# ----------------------------------------------------------------------
+# Registry + basic Make-like build
+# ----------------------------------------------------------------------
+
+RULES: dict[str, dict[str, Any]] = {}
+COMMANDS: set[Callable] = set()
+
+def _caller_script() -> Path:
+    mod = sys.modules.get("__main__")
+    if getattr(mod, "__file__", None):
+        return Path(mod.__file__).resolve()
+
+    if sys.argv and sys.argv[0]:
+        p = Path(sys.argv[0])
+        if p.exists():
+            return p.resolve()
+
+    for f in reversed(inspect.stack()):
+        p = Path(f.filename)
+        if p.suffix in {".py", ""}:
+            return p.resolve()
+
+    return Path("unknown")
+
+
+def _safe_cmd(argv: list[str]) -> str | None:
+    try:
+        return subprocess.run(
+            argv, check=True, capture_output=True, text=True
+        ).stdout.strip()
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def needs_update(outputs, deps) -> bool:
+    """Return True if outputs missing or older than any dependency."""
+    out_paths = [Path(o) for o in outputs]
+    dep_paths = [Path(d) for d in deps]
+
+    if not out_paths:
+        return True
+
+    if any(not o.exists() for o in out_paths):
+        return True
+
+    oldest_out = min(o.stat().st_mtime for o in out_paths)
+    dep_times = [d.stat().st_mtime for d in dep_paths if d.exists()]
+    if not dep_times:
+        return False
+
+    newest_dep = max(dep_times)
+    return newest_dep > oldest_out
+
+
+def build(target, _seen=None):
+    """
+    Recursively build target after its dependencies, if needed.
+
+    `target` is a path (string/Path). Only rules with default
+    OutFile paths are part of this DAG.
+    """
+    if _seen is None:
+        _seen = set()
+    target = str(target)
+
+    if target in _seen:
+        raise RuntimeError(f"Cycle in build graph at {target!r}")
+    _seen.add(target)
+
+    rule = RULES[target]
+
+    for dep in rule["deps"]:
+        if dep in RULES:
+            build(dep, _seen)
+
+    rule["func"]()
+
+
+# ----------------------------------------------------------------------
+# PROV helpers
+# ----------------------------------------------------------------------
+
+
+def _describe_file(g: rdflib.Graph, base: rdflib.Namespace, path: Path, kind: str):
+    iri = base[f"{kind}/{path.as_posix()}"]
+
+    mtype = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
+    size = path.stat().st_size if path.exists() else 0
+    mtime = (
+        datetime.fromtimestamp(path.stat().st_mtime, tz=timezone.utc).isoformat()
+        if path.exists()
+        else None
+    )
+
+    g.add((iri, RDF.type, PROV.Entity))
+    g.add((iri, DCT.format, rdflib.Literal(mtype)))
+    g.add((iri, DCT.extent, rdflib.Literal(size, datatype=XSD.integer)))
+    if mtime:
+        g.add((iri, DCT.modified, rdflib.Literal(mtime, datatype=XSD.dateTime)))
+
+    if kind == "src" and path.exists():
+        try:
+            sha = hashlib.sha256(path.read_bytes()).hexdigest()
+            g.add((iri, DCT.identifier, rdflib.Literal(f"sha256:{sha}")))
+        except Exception:  # noqa: BLE001
+            pass
+
+    return iri
+
+
+def project_metadata(dist_name: str | None = None):
+    """
+    Return (name, version, requires) using importlib.metadata.
+
+    If dist_name is None, tries to infer from the caller module.
+    """
+    if dist_name is None:
+        # crude default: module name of the caller
+        frame = inspect.stack()[1]
+        module = inspect.getmodule(frame[0])
+        if module and module.__package__:
+            dist_name = module.__package__.split(".", 1)[0]
+        else:
+            return None, None, []
+
+    try:
+        dist = im.distribution(dist_name)
+    except im.PackageNotFoundError:
+        return None, None, []
+
+    name = dist.metadata.get("Name")
+    version = dist.version
+    requires = dist.requires or []
+    return name, version, requires
+
+def pep503_normalize(name: str) -> str:
+    """PEP 503 normalization: lowercase, runs of [-_.] -> '-'."""
+    name = name.strip()
+    name = name.lower()
+    return re.sub(r"[-_.]+", "-", name)
+
+
+def add_deps_to_env(
+    D: rdflib.Graph,
+    env_iri: rdflib.term.Identifier,
+    deps_specs: list[str],
+):
+    """
+    Attach dependencies from deps_specs to env_iri using PyPI-based IRIs.
+
+    deps_specs: e.g. ["rdflib>=6.0.0", "pydantic==2.0.3"]
+    """
+    for spec in deps_specs:
+        spec_str = spec.strip()
+        if not spec_str:
+            continue
+
+        pkg = spec_str.split()[0]
+        # keep only the name part before version operator
+        pkg_name = re.split(r"[<>=!~ ]", pkg, 1)[0]
+        norm = pep503_normalize(pkg_name)
+
+        dep_iri = rdflib.URIRef(f"https://pypi.org/project/{norm}/")
+
+        D.add((dep_iri, RDF.type, RDF.Resource))
+        D.add((dep_iri, RDFS.label, rdflib.Literal(spec_str)))
+        # link environment -> dependency
+        D.add((env_iri, DCT.requires, dep_iri))
+
+def _augment_with_metadata(
+    D: rdflib.Graph,
+    base: rdflib.Namespace,
+    activity: rdflib.term.Identifier,
+    run_id: str,
+):
+    """Add metadata + dependency info to provenance, if possible."""
+    name, version, deps_specs = project_metadata()
+
+    if name or version or deps_specs:
+        env = base[f"env/{run_id}"]
+        D.add((env, RDF.type, PROV.Entity))
+        D.add((env, RDF.type, PROV.Collection))
+        D.add((env, RDFS.label, rdflib.Literal("Python environment")))
+        D.add((activity, PROV.used, env))
+
+        if name:
+            D.add((env, DCT.title, rdflib.Literal(name)))
+        if version:
+            D.add((env, DCT.hasVersion, rdflib.Literal(version)))
+
+        add_deps_to_env(D, env, deps_specs)
+
+
+def _write_provenance_dataset(
+    base_iri: str,
+    name: str,
+    prov_path: str | Path,
+    deps: list[str],
+    outputs: list[str],
+    t0: datetime,
+    t1: datetime,
+    data_graph: rdflib.Graph | None = None,
+    success: bool = True,
+):
+    """
+    Build a Dataset with:
+      - default graph: PROV metadata
+      - named graph:   data_graph (if provided)
+    and serialize as Trig to prov_path.
+    """
+    base = rdflib.Namespace(base_iri)
+    ds = rdflib.Dataset()
+    D = ds.default_context
+
+    ds.bind("", base)
+    ds.bind("prov", PROV)
+    ds.bind("dcterms", DCT)
+
+    run_id = t0.strftime("%Y%m%dT%H%M%S")
+    script = _caller_script()
+
+    activity = base[f"run/{name}/{run_id}"]
+    agent = base[f"agent/{script.name}"]
+    graph_iri = base[f"graph/{name}"]
+
+    commit = _safe_cmd(["git", "rev-parse", "HEAD"])
+    origin = _safe_cmd(["git", "config", "--get", "remote.origin.url"])
+
+    D.add((activity, RDF.type, PROV.Activity))
+    t0_term = rdflib.Literal(t0.isoformat(), datatype=XSD.dateTime)
+    D.add((activity, PROV.startedAtTime, t0_term))
+    t1_term = rdflib.Literal(t1.isoformat(), datatype=XSD.dateTime)
+    D.add((activity, PROV.endedAtTime, t1_term))
+
+    D.add((agent, RDF.type, PROV.SoftwareAgent))
+    D.add((agent, RDFS.label, rdflib.Literal(script.name)))
+    if commit:
+        D.add((agent, DCT.hasVersion, rdflib.Literal(commit)))
+    if origin:
+        D.add((agent, DCT.source, rdflib.URIRef(origin)))
+    D.add((activity, PROV.wasAssociatedWith, agent))
+
+    if data_graph is not None:
+        gx = ds.get_context(graph_iri)
+        for triple in data_graph:
+            gx.add(triple)
+
+        D.add((graph_iri, RDF.type, PROV.Entity))
+        D.add((graph_iri, PROV.wasGeneratedBy, activity))
+        D.add((graph_iri, PROV.wasAttributedTo, agent))
+        D.add((graph_iri, PROV.generatedAtTime, t1_term))
+
+    for d in deps:
+        p = Path(d)
+        if not p.exists():
+            continue
+        src = _describe_file(D, base, p, "src")
+        D.add((activity, PROV.used, src))
+
+    for o in outputs:
+        p = Path(o)
+        if not p.exists():
+            continue
+        ent = _describe_file(D, base, p, "out")
+        D.add((ent, PROV.wasGeneratedBy, activity))
+
+    if not success:
+        D.add((activity, RDFS.comment, rdflib.Literal("task failed")))
+
+    # Add pyproject + dependency information, if available
+    _augment_with_metadata(D, base, activity, run_id)
+
+    prov_path = Path(prov_path)
+    prov_path.parent.mkdir(parents=True, exist_ok=True)
+    logging.info("Writing provenance dataset %s", prov_path)
+    ds.serialize(prov_path, format="trig")
+
+
+# ----------------------------------------------------------------------
+# Annotation helpers (supports Optional[InFile], OutFile | None, etc.)
+# ----------------------------------------------------------------------
+
+
+def _is_kind_annotation(ann: Any, cls: type) -> bool:
+    if ann is cls:
+        return True
+
+    origin = get_origin(ann)
+    if origin is None:
+        return False
+
+    return any(a is cls for a in get_args(ann))
+
+
+# ----------------------------------------------------------------------
+# Decorator: infer inputs/outputs from signature
+# ----------------------------------------------------------------------
+
+
+def rule(
+    *,
+    name: str | None = None,
+    base_iri: str | None = None,
+    prov_dir: str | None = None,
+    prov_path: str | None = None,
+    force: bool | None = None,
+    dry_run: bool | None = None,
+    config: ProvenanceConfig | None = None,
+):
+    base_config = config or GLOBAL_CONFIG
+
+    rule_config = ProvenanceConfig(
+        base_iri=base_iri if base_iri is not None else base_config.base_iri,
+        prov_dir=prov_dir if prov_dir is not None else base_config.prov_dir,
+        force=force if force is not None else base_config.force,
+        dry_run=dry_run if dry_run is not None else base_config.dry_run,
+    )
+
+    def decorator(func):
+        sig = inspect.signature(func)
+        hints = get_type_hints(func)
+
+        in_params: list[str] = []
+        out_params: list[str] = []
+
+        for p in sig.parameters.values():
+            ann = hints.get(p.name, p.annotation)
+            if _is_kind_annotation(ann, InFile):
+                in_params.append(p.name)
+            if _is_kind_annotation(ann, OutFile):
+                out_params.append(p.name)
+
+        if not out_params:
+            raise ValueError(
+                f"Function {func.__name__} must have at least one "
+                f"OutFile (possibly Optional[OutFile]) parameter"
+            )
+
+        deps: list[str] = []
+        outputs: list[str] = []
+
+        for p in sig.parameters.values():
+            if p.name in in_params and p.default is not inspect._empty:
+                val = p.default
+                if isinstance(val, InFile):
+                    if getattr(val, "is_stream", False):
+                        pass
+                    elif val.path is not None:
+                        deps.append(str(val.path))
+                elif isinstance(val, (str, Path)):
+                    if str(val) != "-":
+                        deps.append(str(val))
+
+            if p.name in out_params and p.default is not inspect._empty:
+                val = p.default
+                if isinstance(val, OutFile):
+                    if getattr(val, "is_stream", False):
+                        pass
+                    elif val.path is not None:
+                        outputs.append(str(val.path))
+                elif isinstance(val, (str, Path)):
+                    if str(val) != "-":
+                        outputs.append(str(val))
+
+        register_for_build = bool(outputs)
+        logical_name = name or func.__name__
+
+        if prov_path is not None:
+            rule_prov_path = prov_path
+        else:
+            rule_prov_path = str(Path(rule_config.prov_dir) / f"{logical_name}.trig")
+
+        @functools.wraps(func)
+        def wrapped(*args, **kwargs):
+            bound = sig.bind_partial(*args, **kwargs)
+            bound.apply_defaults()
+
+            in_files: list[Path] = []
+            out_files: list[Path] = []
+
+            for pname in in_params:
+                val = bound.arguments.get(pname)
+                if isinstance(val, InFile):
+                    if val.is_stream or val.path is None:
+                        continue
+                    in_files.append(val.path)
+                elif val is None:
+                    continue
+                else:
+                    if str(val) != "-":
+                        in_files.append(Path(val))
+
+            for pname in out_params:
+                val = bound.arguments.get(pname)
+                if isinstance(val, OutFile):
+                    if val.is_stream or val.path is None:
+                        continue
+                    out_files.append(val.path)
+                elif val is None:
+                    continue
+                else:
+                    if str(val) != "-":
+                        out_files.append(Path(val))
+
+            if not rule_config.force and not needs_update(out_files, in_files):
+                logging.info("Skipping %s (up to date)", logical_name)
+                return None
+
+            if rule_config.dry_run:
+                logging.info(
+                    "Dry-run %s: would run with %s -> %s",
+                    logical_name,
+                    in_files,
+                    out_files,
+                )
+                return None
+
+            t0 = datetime.now(timezone.utc)
+            exc: Exception | None = None
+            data_graph: rdflib.Graph | None = None
+            result = None
+
+            try:
+                result = func(*bound.args, **bound.kwargs)
+                if isinstance(result, (rdflib.Graph, rdflib.Dataset)):
+                    data_graph = result
+                return result
+            except Exception as e:
+                exc = e
+                raise
+            finally:
+                t1 = datetime.now(timezone.utc)
+                try:
+                    _write_provenance_dataset(
+                        base_iri=rule_config.base_iri,
+                        name=logical_name,
+                        prov_path=rule_prov_path,
+                        deps=[str(p) for p in in_files],
+                        outputs=[str(p) for p in out_files],
+                        t0=t0,
+                        t1=t1,
+                        data_graph=data_graph,
+                        success=exc is None,
+                    )
+                except Exception as prov_exc:  # noqa: BLE001
+                    logging.warning(
+                        "Failed to write provenance for %s: %s",
+                        logical_name,
+                        prov_exc,
+                    )
+
+        COMMANDS.add(wrapped)
+        if register_for_build:
+            target = outputs[0]
+            RULES[target] = {
+                "deps": deps,
+                "outputs": outputs,
+                "func": wrapped,
+            }
+
+        return wrapped
+
+    return decorator

makeprov-0.1.1/tests/test_makeprov.py

@@ -0,0 +1,71 @@
+import tempfile
+from pathlib import Path
+
+from rdflib import Graph, Literal, Namespace
+from rdflib.namespace import RDF, XSD
+
+from makeprov import InFile, OutFile, ProvenanceConfig, rule
+
+@rule(name="test_process_data")
+def process_data(input_file: InFile, output_file: OutFile):
+    with input_file.open('r') as infile, output_file.open('w') as outfile:
+        data = infile.read()
+        outfile.write(data)
+
+
+SALES_NS = Namespace("http://example.org/test/")
+TEST_PROV_DIR = Path(tempfile.mkdtemp(prefix="makeprov-tests-"))
+TEST_PROV_CONFIG = ProvenanceConfig(prov_dir=str(TEST_PROV_DIR))
+
+
+@rule(name="test_totals_graph", config=TEST_PROV_CONFIG)
+def totals_graph(input_csv: InFile, graph_out: OutFile) -> Graph:
+    graph = Graph()
+    graph.bind("sales", SALES_NS)
+
+    if graph_out.path is None:
+        raise ValueError("graph_out must have a filesystem path")
+    graph_out.path.parent.mkdir(parents=True, exist_ok=True)
+
+    with input_csv.open('r') as handle:
+        for line in handle.read().strip().splitlines()[1:]:
+            region, units, revenue = line.split(',')
+            subject = SALES_NS[f"region/{region.lower()}"]
+            graph.add((subject, RDF.type, SALES_NS.RegionTotal))
+            graph.add((subject, SALES_NS.regionName, Literal(region)))
+            graph.add((subject, SALES_NS.totalUnits, Literal(units, datatype=XSD.integer)))
+            graph.add((subject, SALES_NS.totalRevenue, Literal(revenue, datatype=XSD.decimal)))
+
+    with graph_out.open('w') as handle:
+        handle.write(graph.serialize(format='turtle'))
+
+    return graph
+
+
+def test_process_data(tmp_path):
+    input_file = tmp_path / "input.txt"
+    output_file = tmp_path / "output.txt"
+
+    input_file.write_text("Hello, world!")
+
+    # Run the process_data function
+    result = process_data(InFile(str(input_file)), OutFile(str(output_file)))
+
+    # Check that the output file was created and contains the correct data
+    assert output_file.exists()
+    assert output_file.read_text() == "Hello, world!"
+
+
+def test_rule_returns_graph(tmp_path):
+    input_csv = tmp_path / "region_totals.csv"
+    graph_ttl = tmp_path / "region_totals.ttl"
+    input_csv.write_text("region,total_units,total_revenue\nNorth,6,119.94\n")
+
+    result = totals_graph(InFile(str(input_csv)), OutFile(str(graph_ttl)))
+
+    assert isinstance(result, Graph)
+    assert graph_ttl.exists()
+    assert "North" in graph_ttl.read_text()
+    prov_path = TEST_PROV_DIR / "test_totals_graph.trig"
+    assert prov_path.exists()
+    prov_path.unlink()