tisserande 0.0.0__tar.gz

tisserande-0.0.0/.github/workflows/docs.yml

@@ -0,0 +1,44 @@
+name: Docs Build
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "src/**"
+      - ".readthedocs.yaml"
+      - "pyproject.toml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "src/**"
+      - ".readthedocs.yaml"
+      - "pyproject.toml"
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[docs,dev]"
+
+      - name: Build docs
+        run: |
+          cd docs
+          make html
+
+      - name: Upload docs artifact
+        if: success()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: docs/_build/html/
+          retention-days: 7

tisserande-0.0.0/.github/workflows/linting.yml

@@ -0,0 +1,33 @@
+# This workflow will install Python dependencies,
+# then perform static linting analysis.
+
+name: Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.13'
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          python -m pip install --upgrade pip
+          pip install .
+          pip install .[dev]
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+      - name: Type checking
+        run: |
+          mypy src
+      - name: Linting
+        run: |
+          ruff check src tests

tisserande-0.0.0/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,39 @@
+# This workflow will upload a Python Package using
+# Twine when a release is created
+# For more information see:
+# https://github.com/pypa/gh-action-pypi-publish#trusted-publishing
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.13'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+      - name: Build package
+        run: python -m build
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

tisserande-0.0.0/.github/workflows/smoke-test.yml

@@ -0,0 +1,36 @@
+# This workflow will run daily at 06:45.
+# It will install Python dependencies and run tests with a variety of
+# Python versions.
+
+name: Unit test smoke test
+
+on:
+  schedule:
+    - cron: 45 6 * * *
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.13']
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          python -m pip install --upgrade pip
+          pip install .
+          pip install .[dev]
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+      - name: Run unit tests with pytest
+        run: |
+          python -m pytest tests

tisserande-0.0.0/.github/workflows/testing-and-coverage.yml

@@ -0,0 +1,39 @@
+# This workflow will install Python dependencies, run tests and report
+# code coverage with a variety of Python versions
+
+name: Unit test and code coverage
+
+on:
+  schedule:
+    - cron: 45 7 * * 1
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.13']
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-tags: true
+          fetch-depth: 0
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          python -m pip install --upgrade pip
+          pip install .
+          pip install .[dev]
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+      - name: Run unit tests with pytest
+        run: |
+          python -m pytest tests

tisserande-0.0.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+htmlcov/
+.coverage
+.coverage.*
+*.db
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+src/tisserande/_version.py

tisserande-0.0.0/.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.13"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+        - server

tisserande-0.0.0/CLAUDE.md

@@ -0,0 +1,180 @@
+# CLAUDE.md — tisserande
+
+## Overview
+
+`tisserande` is a Python package for tracking execution provenance of Python functions and shell scripts. It records what functions were called, what data they consumed and produced, and how long they took — all as a directed acyclic graph (DAG) stored in a database.
+
+The package builds on top of `macon` (at `/Users/echarles/software/KIPAC/macon`) which provides a layered CRUD framework. Tisserande adds tracking decorators for automatic provenance capture.
+
+## Architecture — Layered Design
+
+```
+Tracking Decorators (@track, @track_async, track_shell)
+  └── TrackingContext + ArgumentInspector
+        └── TrackingBackend (LocalSyncBackend / NullBackend)
+              └── local_sync (SyncOperations)  ← asyncio.run() wrappers
+                    └── local_async (LocalOperations)  ← @with_session decorators
+                          └── db_oper (TableOperations)  ← FK resolution
+                                └── macon.db_funcs (raw async SQLAlchemy queries)
+                                      └── macon.db (Base, session)
+```
+
+| Layer | Purpose | Key Base Class (from macon) |
+|-------|---------|----------------------------|
+| `models/` | Pydantic models (Base/Create/Response triplets) | `pydantic.BaseModel` |
+| `db/` | SQLAlchemy ORM tables | `macon.db.base.Base` |
+| `db_oper/` | `TableOperations` with FK resolution | `macon.db_oper.base.TableOperations` |
+| `local_async/` | Session-managed async operations | `macon.local_async.base.LocalOperations` |
+| `local_sync/` | Synchronous wrappers | `macon.local_sync.base.SyncOperations` |
+| `tracking/` | Decorators, inspection, backends, context | *(tisserande-specific)* |
+| `router/` | FastAPI app with auto-generated CRUD endpoints | `macon.router.base.create_table_router` |
+| `cli/` | Click CLI entry points | `macon.cli.local.base.make_table_group` |
+| `config.py` | Pydantic Settings configuration | `pydantic_settings.BaseSettings` |
+
+## Domain Model
+
+The provenance graph has three entity types:
+
+- **Nodes** — vertices in the DAG. A single `node` table with a `type_` discriminator column and nullable type-specific fields.
+  - Data nodes: `data_file`, `config_file`, `config_dict`, `parameter`, `array`, `object`
+  - Logic nodes: `python_function`, `member_function`, `shell_function`
+- **Edges** — directed links between nodes (`from_id` → `to_id`)
+  - Data → Logic = "input to function"
+  - Logic → Data = "output from function"
+- **Executions** — groups all nodes/edges from a single function call, with timing and status
+
+Each node type can optionally reference a **type table** (e.g., `data_file_type`, `python_function`) for reusable definitions.
+
+## Key Patterns
+
+- **Single Node table**: All node types share one table with nullable columns. Simplifies graph queries since edges reference only one table.
+- **UUID7 primary keys** for nodes/executions (time-ordered, via `uuid_utils`), int PKs for type tables and edges. Note: `uuid_utils.UUID` is not a subclass of `uuid.UUID` — we use a `uuid7()` wrapper in `db/utils.py` that returns standard `uuid.UUID`.
+- **Macon integration**: Inherits `macon.db.base.Base`, uses `TableOperations`, `LocalOperations`, `SyncOperations`, `create_table_router`, `make_table_group`.
+- **Three-model pattern** (from macon): `FooBase` → `FooCreate` (creation fields) → `Foo` (response with `id_`, `ConfigDict(from_attributes=True)`, `col_names_for_table`).
+- **Tracking annotations**: `Annotated[]` type aliases (`DataFile[T]`, `Param[T]`, etc.) control how arguments are classified.
+- **Pluggable backends**: `TrackingBackend` protocol allows `LocalSyncBackend` (real DB), `NullBackend` (testing), or custom implementations.
+- **Decorator no-op**: If `configure()` hasn't been called, `@track` is transparent (function runs without tracking overhead).
+- **Enum-based status/types**: Tracking code passes `ExecutionStatus` and `NodeType` enums; conversion to string values happens at the db_oper/backend layer.
+- **`reset()`**: Clears the configured backend, making `configure()` safe to call multiple times (useful in tests).
+
+## Critical Files
+
+### Tracking system
+- `src/tisserande/tracking/decorator.py` — `@track`, `@track_async`, `track_shell()`, `configure()`, `reset()`, `get_backend()`
+- `src/tisserande/tracking/context.py` — `TrackingContext` orchestrates one execution lifecycle
+- `src/tisserande/tracking/inspector.py` — `ArgumentInspector` classifies args → NodeType
+- `src/tisserande/tracking/annotations.py` — `DataFile`, `Param`, `Untracked`, etc.
+- `src/tisserande/tracking/backends.py` — `TrackingBackend` protocol, `LocalSyncBackend`, `NullBackend`
+
+### Models & DB
+- `src/tisserande/models/types.py` — `NodeType` and `ExecutionStatus` enums
+- `src/tisserande/models/nodes.py` — All node Pydantic models (generic + typed variants)
+- `src/tisserande/db/nodes.py` — Single `NodeTable` ORM model
+- `src/tisserande/db/execution.py` — `ExecutionTable` ORM model
+- `src/tisserande/db/utils.py` — Shared `uuid7()` helper for time-ordered primary keys
+- `src/tisserande/db_oper/nodes.py` — `NodeOperations` with type-dependent FK resolution
+- `src/tisserande/db_oper/execution.py` — `ExecutionOperations` with status enum conversion
+
+### Configuration
+- `src/tisserande/config.py` — `Configuration` class (env prefix: `TISSERANDE__`)
+
+## Development
+
+### Setup
+```bash
+pip install -e ".[dev]"
+```
+
+### Testing
+```bash
+pytest tests/                    # 86 tests, in-memory SQLite, 100% coverage
+pytest tests/ -x --tb=short     # stop at first failure
+pytest tests/ --cov=tisserande --cov-report=term-missing  # with coverage
+```
+
+Tests use `sqlite+aiosqlite://` (in-memory). The `conftest.py` fixture calls `init_db()` and creates all tables before each test.
+
+Test files:
+- `tests/test_tracking.py` — decorator and inspector unit tests with NullBackend
+- `tests/test_full_stack.py` — end-to-end integration tests with real DB
+- `tests/test_models.py` — Pydantic model validation
+- `tests/test_inspector_coverage.py` — comprehensive inspector branch coverage
+- `tests/test_decorator_coverage.py` — decorator flags and edge cases
+- `tests/test_cli.py` — CLI entry points (Click test runner + mocked uvicorn)
+- `tests/test_router.py` — FastAPI app creation and route registration
+- `tests/test_db_oper_coverage.py` — FK resolution paths
+
+Coverage exclusion patterns (in `pyproject.toml`):
+- `"pragma: no cover"` — explicit exclusion
+- `"unexpected"` — unexpected-condition guards
+- `"raise AssertionError"` / `"raise NotImplementedError"` — abstract/impossible paths
+
+### Linting & Type Checking
+```bash
+ruff check src/ tests/          # all checks pass
+ruff format src/ tests/         # auto-format
+mypy src/                       # no issues in 49 source files
+pylint src/                     # 10.00/10
+```
+
+Ruff ignores: `COM812`, `N802-N816`, `UP047` (TypeVar over PEP 695 syntax).
+Pylint disables: `C0415` (lazy imports), `W0603` (globals), `R0911` (many returns).
+
+### Documentation
+```bash
+pip install -e ".[docs]"
+cd docs && make html     # builds to docs/_build/html/
+```
+- Sphinx with `sphinx-autoapi` (API docs from source), `sphinx_rtd_theme`
+- ReadTheDocs config: `.readthedocs.yaml`
+- Docs source: `docs/` (index, getting_started, user_guide/, api/)
+
+### Configuration
+- `TISSERANDE__DB__URL` — database URL (default: `sqlite+aiosqlite:///tisserande.db`)
+- `TISSERANDE__DB__ECHO` — SQLAlchemy echo (default: `false`)
+- `TISSERANDE__TRACKING__ENABLED` — global enable/disable (default: `true`)
+- `TISSERANDE__TRACKING__BACKEND` — default backend: `local_sync`, `null` (default: `local_sync`)
+- `TISSERANDE__TRACKING__AUTO_CLASSIFY` — heuristic classification (default: `true`)
+- Line length: 110 (ruff), 120 (pylint)
+- Python: 3.13+ required
+- Build: setuptools + setuptools_scm
+- Package manager: pip (or uv)
+
+### CLI Entry Points
+- `tisserande-local` — local DB admin (CRUD for all tables via click)
+- `tisserande-server` — FastAPI/uvicorn server
+
+### CI/CD
+GitHub Actions workflows in `.github/workflows/`:
+- `linting.yml` — ruff + mypy on push/PR to main
+- `testing-and-coverage.yml` — pytest on push/PR + weekly schedule
+- `smoke-test.yml` — daily scheduled pytest run
+- `docs.yml` — Sphinx build on docs/source changes
+- `publish-to-pypi.yml` — trusted publishing on GitHub release
+
+### Dependencies
+- Core: `macon[db]` (provides SQLAlchemy, pydantic, structlog, uuid_utils, anyio, aiosqlite, etc.)
+- Optional: `numpy` (array support), `macon[server]` (FastAPI server), `macon[client]` (HTTP client)
+- Docs: `sphinx`, `sphinx-autoapi`, `sphinx_rtd_theme`, `sphinx-autodoc-typehints`
+
+### Known Limitations
+- **`@track_async` with `LocalSyncBackend`**: Cannot be used inside an already-running event loop because `LocalSyncBackend` internally calls `asyncio.run()` via macon's `local_sync`. A future `LocalAsyncBackend` would resolve this. For now, `@track_async` works when the decorated coroutine is called from synchronous code (e.g., `asyncio.run(my_func(...))`).
+
+### Adding a New Node Type
+
+1. Add value to `NodeType` enum in `models/types.py`
+2. Add nullable columns to `db/nodes.py` `NodeTable` if needed
+3. Add FK mapping to `_TYPE_FK_MAP` in `db_oper/nodes.py`
+4. Add typed Pydantic models (Base/Create/Response) in `models/nodes.py`
+5. Add heuristic classification in `tracking/inspector.py` `_classify_by_value()`
+6. Add annotation alias in `tracking/annotations.py`
+
+### Adding a New Type Table
+
+1. Create Pydantic models (Base/Create/Response) in `models/data_types.py` or `models/function_types.py`
+2. Create ORM table in `db/data_types.py` or `db/function_types.py`
+3. Create `TableOperations` in `db_oper/`
+4. Create `LocalOperations` in `local_async/`
+5. Create `SyncOperations` in `local_sync/`
+6. Add to `__init__.py` exports in each layer
+7. Add router and CLI commands

tisserande-0.0.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: tisserande
+Version: 0.0.0
+Summary: Execution provenance tracking for Python functions and shell scripts
+Author-email: Eric Charles <echarles@slac.stanford.edu>
+Project-URL: Source, https://github.com/eacharles/tisserande
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: tables-io
+Requires-Dist: macon[db]
+Provides-Extra: numpy
+Requires-Dist: numpy; extra == "numpy"
+Provides-Extra: server
+Requires-Dist: macon[server]; extra == "server"
+Provides-Extra: client
+Requires-Dist: macon[client]; extra == "client"
+Provides-Extra: dev
+Requires-Dist: tisserande[numpy]; extra == "dev"
+Requires-Dist: tisserande[server]; extra == "dev"
+Requires-Dist: tisserande[client]; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3.1; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff>=0.8.0; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: types-pyyaml>=6.0.12.20240917; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: nbsphinx; extra == "docs"
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
+Requires-Dist: sphinx_rtd_theme; extra == "docs"
+Requires-Dist: sphinx-autoapi; extra == "docs"
+Provides-Extra: all
+Requires-Dist: tisserande[server]; extra == "all"
+Requires-Dist: tisserande[client]; extra == "all"
+Requires-Dist: tisserande[dev]; extra == "all"
+Requires-Dist: tisserande[docs]; extra == "all"
+
+# tisserande
+
+Execution provenance tracking for Python functions and shell scripts.
+
+Tisserande records **what** functions ran, **what** data they consumed and produced, **how long** they took, and **whether** they succeeded — all as a directed acyclic graph (DAG) stored in a database.
+
+## Installation
+
+```bash
+pip install tisserande
+```
+
+For development:
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### 1. Configure tracking
+
+```python
+from tisserande.tracking import configure
+
+# Uses in-memory SQLite by default for quick experiments
+configure(db_url="sqlite+aiosqlite:///my_provenance.db")
+```
+
+### 2. Decorate your functions
+
+```python
+from tisserande.tracking import track
+from tisserande.tracking.annotations import DataFile, Param
+
+@track
+def fit_model(
+    input_catalog: DataFile[str],
+    config_file: DataFile[str],
+    learning_rate: Param[float],
+) -> DataFile[str]:
+    """Train a model and write output."""
+    # ... your code ...
+    return "/data/results/model_output.fits"
+
+# Call normally — provenance is recorded automatically
+fit_model("/data/catalogs/train.fits", "/configs/model.yaml", 0.01)
+```
+
+### 3. Query the provenance
+
+```python
+from tisserande.local_sync import execution, node, edge
+
+# Get all executions
+for ex in execution.get_rows():
+    print(f"{ex.id_}: status={ex.status}, duration={ex.duration_seconds:.2f}s")
+
+# Get all nodes for a specific execution
+nodes = node.filter_rows(filters=[...])
+```
+
+## Type Annotations
+
+Control how arguments are classified with type annotations:
+
+```python
+from tisserande.tracking.annotations import (
+    DataFile,      # File containing data (e.g., FITS, HDF5, Parquet)
+    ConfigFile,    # Configuration file (e.g., YAML, JSON, TOML)
+    ConfigDict,    # Dictionary containing configuration
+    Param,         # Numeric parameter
+    ArrayArg,      # Array of values
+    ObjectArg,     # Python object
+    Untracked,     # Skip tracking for this argument
+)
+```
+
+Without annotations, tisserande uses heuristics (file extensions, Python types) to classify arguments automatically.
+
+## Tracking Shell Commands
+
+```python
+from tisserande.tracking import track_shell
+
+result = track_shell(
+    "sextractor input.fits -c config.sex",
+    inputs={
+        "image": "/data/input.fits",
+        "config": "/configs/config.sex",
+    },
+    outputs={
+        "catalog": "/data/output.cat",
+    },
+)
+```
+
+## Async Support
+
+```python
+from tisserande.tracking import track_async
+
+@track_async
+async def async_pipeline(data: DataFile[str]) -> DataFile[str]:
+    # ... async processing ...
+    return "/data/output.fits"
+```
+
+## Architecture
+
+Tisserande models provenance as a DAG:
+
+```
+[input.fits] ──→ [fit_model()] ──→ [output.fits]
+[config.yaml] ─┘                    
+[lr=0.01] ─────┘
+```
+
+- **Nodes** represent data (files, configs, parameters, arrays, objects) and logic (functions, scripts)
+- **Edges** connect inputs to functions and functions to outputs
+- **Executions** group all nodes/edges from a single function call
+
+The database stores:
+- **Type tables**: reusable definitions (e.g., "PythonFunction: fit_model in mymodule")
+- **Node table**: specific instances with runtime values
+- **Edge table**: directed connections between nodes
+- **Execution table**: timing, status, error info per function call
+
+## Database Backends
+
+By default, tisserande uses SQLite via SQLAlchemy. Configure any SQLAlchemy-compatible database:
+
+```python
+configure(db_url="postgresql+asyncpg://user:pass@localhost/provenance")
+```
+
+## REST API
+
+Start the server:
+
+```bash
+tisserande-server --port 8080
+```
+
+Provides CRUD endpoints for all tables at `http://localhost:8080/docs`.
+
+## CLI
+
+```bash
+# List executions
+tisserande-local execution get-rows
+
+# Get a specific node
+tisserande-local node get-row <node-uuid>
+```
+
+## Configuration
+
+Environment variables (prefix `TISSERANDE__`, nested with `__`):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TISSERANDE__DB__URL` | `sqlite+aiosqlite:///tisserande.db` | Database URL |
+| `TISSERANDE__TRACKING__ENABLED` | `true` | Global tracking toggle |
+| `TISSERANDE__TRACKING__BACKEND` | `local_sync` | Backend: `local_sync` or `null` |
+
+## Testing
+
+For tests, use the `NullBackend` to avoid database overhead:
+
+```python
+from tisserande.tracking import configure
+from tisserande.tracking.backends import NullBackend
+
+configure(backend=NullBackend())
+```
+
+## License
+
+MIT