deped-runtime

deped-runtime collects reusable file, database, download, console, and notebook helpers used across DepEd data repositories. Install only the optional features a project needs. Each project still defines its own schemas, source rules, data meaning, published formats, and application state.

See the DepEd Orchestrator for the full repository graph, build order, and verification workflow.

Install

The base package includes artifact, CSV, OOXML, text, SQL, SQLite, console, and profile-table support:

uv add deped-runtime

Install only the optional integration your project needs:

uv add 'deped-runtime[excel]'   # openpyxl workbook helpers
uv add 'deped-runtime[polars]'  # SQLite query/source frames
uv add 'deped-runtime[geoparquet]'  # GeoParquet and WKB polygon mechanics
uv add 'deped-runtime[geodesy]' # NumPy point distance and candidate search
uv add 'deped-runtime[r2]'      # Cloudflare R2 API and CLI
uv add 'deped-runtime[marimo]'  # standalone Marimo UI helpers
uv add 'deped-runtime[marimo-sql]' # standalone Marimo SQL integration
uv add 'deped-runtime[charts]'  # standalone Altair and Polars chart helpers
uv add 'deped-runtime[maps]'    # standalone Folium map helpers
uv add 'deped-runtime[notebooks]'      # Marimo and generic Altair components
uv add 'deped-runtime[notebooks-sql]'  # notebook components plus Marimo SQL
uv add 'deped-runtime[notebooks-maps]' # notebook components plus Folium maps
uv add 'deped-runtime[all]'     # all optional integrations

Start by task

• Hash files, count or write CSV rows, and fingerprint sources: see files and workbooks.
• Verify a bundle-relative file or publish a directory with rollback: see artifact integrity and publication.
• Implement explicit, progress-aware network fetch commands while keeping provider policy local: see source fetching.
• Publish and integrity-check hash-backed source artifacts: see source-product manifests.
• Record build inputs, outputs, hashes, and production/review classification: see build receipts.
• Inspect SQLite, attach sources read-only, validate raw source tables, or return Polars frames: see SQL and SQLite.
• Read and write WKB GeoParquet or simplify polygon batches without breaking valid shared-edge coverages: see GeoParquet and geometry.
• Rank bounded point-distance candidates: see point distance and candidate search.
• Render consistent command status and build progress: see console and progress.
• Transfer namespaced artifacts with the API or CLI: see R2 transfers.
• Produce a Markdown quality report for a SQLite table: see profile-table.
• Calculate a page window or slice an in-memory sequence without taking over labels and URLs: see pagination.
• Compose consistent Marimo sidebars, stats, tables, callouts, and charts: see notebook design system.
• Move a consumer from deped-dcp-template 0.9.0: see the migration guide.

The documentation routes to the complete module map, installation matrix, capability guides, and ownership boundary.

Quick examples

from deped_runtime.artifacts import file_identity, file_sha256
from deped_runtime.sqlite import fetch_required_int, open_readonly_sqlite, relation_columns

with open_readonly_sqlite("artifacts/example.db") as conn:
    print(file_sha256("artifacts/example.db"))
    print(file_identity("artifacts/example.db"))
    print(relation_columns(conn, "example"))
    print(fetch_required_int(conn, "SELECT COUNT(*) FROM example", label="example rows"))

uv run --extra r2 deped-runtime r2 download --target data --prefix deped-example
uv run profile-table artifacts/example.db example

Development

Install all optional integrations for development; the dev dependency group contains testing and documentation tools. Pre-commit owns the Ruff and ty versions and runs lock validation, file hygiene, lint fixes, formatting, and project-wide type checks. Repository guidance is in AGENTS.md.

uv sync --locked --all-extras
uv tool install pre-commit --with pre-commit-uv
pre-commit run --all-files  # lock, hygiene, lint, format, and project-wide ty
just check  # validate lock, test, build docs, and build distributions
just docs   # serve documentation on http://localhost:8002

For focused checks:

uv run --locked --all-extras pytest tests/test_typing_contracts.py
pre-commit run ruff-check --all-files
pre-commit run ruff-format --all-files

The 0.9 migration report records hash consolidation, candidate versions, compatibility evidence, and current verification limitations.

The 0.8 migration report records coordinated sibling versions, validation results, temporary candidate parity, and deferred publication gates.

Command environment

just publish uses op run --env-file=env.publish; only the upload process receives UV_PUBLISH_TOKEN. Package builds do not require vault access. Just does not load or generate .env. Export ordinary configuration overrides in your shell. Existing local .env files are not deleted automatically; move any needed overrides before removing old plaintext copies.

Without 1Password

For package publication, build with just package, then supply UV_PUBLISH_TOKEN from your secret manager or CI secret store to uv publish:

just package
uv publish

This requires publishing permission for the package. just publish still invokes op; use the direct command above when 1Password is unavailable.

Keep actual secrets out of reference files, committed files, and shell command history. Ordinary offline builds and checks do not require 1Password.

deped-verify --root PATH (or python -m deped_runtime.verification --root PATH) selects ordered verification lanes from Git changes. Repository policy stays in PATH/scripts/verification.json; --profile accepts an alternate profile path (relative to the root unless absolute). Existing base, CI, dry-run, links and isolated-wheel flags are preserved. Runtime adds no domain or deployment policy. See verification for profile fields and adoption.