Metadata-Version: 2.3
Name: deped-runtime
Version: 0.9.5
Summary: Shared non-semantic runtime plumbing for DepEd data repositories.
Author: Marcelino Veloso III
Author-email: Marcelino Veloso III <marsveloso@gmail.com>
Requires-Dist: click>=8.5
Requires-Dist: rich>=15.0
Requires-Dist: deped-runtime[excel,geoparquet,geodesy,r2,notebooks-sql,maps] ; extra == 'all'
Requires-Dist: altair>=6.3 ; extra == 'charts'
Requires-Dist: polars>=2.0 ; extra == 'charts'
Requires-Dist: openpyxl>=3.1.5 ; extra == 'excel'
Requires-Dist: numpy>=2 ; extra == 'geodesy'
Requires-Dist: polars>=2.0 ; extra == 'geoparquet'
Requires-Dist: pyarrow>=22.0 ; extra == 'geoparquet'
Requires-Dist: shapely>=2.1 ; extra == 'geoparquet'
Requires-Dist: branca>=0.8.2 ; extra == 'maps'
Requires-Dist: folium>=0.20 ; extra == 'maps'
Requires-Dist: marimo>=0.25 ; extra == 'marimo'
Requires-Dist: marimo[sql]>=0.25 ; extra == 'marimo-sql'
Requires-Dist: deped-runtime[marimo,charts] ; extra == 'notebooks'
Requires-Dist: deped-runtime[notebooks,maps] ; extra == 'notebooks-maps'
Requires-Dist: deped-runtime[marimo-sql,charts] ; extra == 'notebooks-sql'
Requires-Dist: polars>=2.0 ; extra == 'polars'
Requires-Dist: botocore>=1.43 ; extra == 'r2'
Requires-Dist: cloudflare-r2>=0.0.6 ; extra == 'r2'
Requires-Dist: pydantic>=2.13 ; extra == 'r2'
Requires-Python: >=3.14
Provides-Extra: all
Provides-Extra: charts
Provides-Extra: excel
Provides-Extra: geodesy
Provides-Extra: geoparquet
Provides-Extra: maps
Provides-Extra: marimo
Provides-Extra: marimo-sql
Provides-Extra: notebooks
Provides-Extra: notebooks-maps
Provides-Extra: notebooks-sql
Provides-Extra: polars
Provides-Extra: r2
Description-Content-Type: text/markdown

# 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](https://mv3.dev/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:

```sh
uv add deped-runtime
```

Install only the optional integration your project needs:

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

The [documentation](docs/index.md) routes to the complete module map,
installation matrix, capability guides, and ownership boundary.

## Quick examples

```python
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"))
```

```sh
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`.

```sh
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:

```sh
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](MIGRATION-0.9.md) records hash consolidation, candidate
versions, compatibility evidence, and current verification limitations.

The [0.8 migration report](MIGRATION-0.8.md) 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`:

```sh
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](docs/start/verification.md) for profile fields and adoption.
