Metadata-Version: 2.4
Name: deped-runtime
Version: 0.2.2
Summary: Shared non-semantic runtime plumbing for DepEd data repositories.
Author-email: Marcelino Veloso III <marsveloso@gmail.com>
Requires-Python: >=3.14
Requires-Dist: click>=8.4
Requires-Dist: rich>=15.0
Provides-Extra: all
Requires-Dist: altair>=6.2.2; extra == 'all'
Requires-Dist: cloudflare-r2>=0.0.6; extra == 'all'
Requires-Dist: folium>=0.20; extra == 'all'
Requires-Dist: marimo[sql]>=0.23.14; extra == 'all'
Requires-Dist: openpyxl>=3.1.5; extra == 'all'
Requires-Dist: polars>=1.42.0; extra == 'all'
Requires-Dist: pydantic>=2.13.0; extra == 'all'
Provides-Extra: charts
Requires-Dist: altair>=6.2.2; extra == 'charts'
Requires-Dist: polars>=1.42.0; extra == 'charts'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1.5; extra == 'excel'
Provides-Extra: maps
Requires-Dist: folium>=0.20; extra == 'maps'
Provides-Extra: marimo
Requires-Dist: marimo>=0.23.14; extra == 'marimo'
Provides-Extra: marimo-sql
Requires-Dist: marimo[sql]>=0.23.14; extra == 'marimo-sql'
Provides-Extra: notebooks
Requires-Dist: altair>=6.2.2; extra == 'notebooks'
Requires-Dist: marimo>=0.23.14; extra == 'notebooks'
Requires-Dist: polars>=1.42.0; extra == 'notebooks'
Provides-Extra: notebooks-maps
Requires-Dist: altair>=6.2.2; extra == 'notebooks-maps'
Requires-Dist: folium>=0.20; extra == 'notebooks-maps'
Requires-Dist: marimo>=0.23.14; extra == 'notebooks-maps'
Requires-Dist: polars>=1.42.0; extra == 'notebooks-maps'
Provides-Extra: notebooks-sql
Requires-Dist: altair>=6.2.2; extra == 'notebooks-sql'
Requires-Dist: marimo[sql]>=0.23.14; extra == 'notebooks-sql'
Requires-Dist: polars>=1.42.0; extra == 'notebooks-sql'
Provides-Extra: polars
Requires-Dist: polars>=1.42.0; extra == 'polars'
Provides-Extra: r2
Requires-Dist: cloudflare-r2>=0.0.6; extra == 'r2'
Requires-Dist: pydantic>=2.13.0; extra == 'r2'
Description-Content-Type: text/markdown

# deped-runtime

`deped-runtime` is the dependency-light operational layer shared by DepEd data
repositories. Version `0.2.0` owns reusable artifact, file, SQLite, SQL, Rich
console, workbook, profiling, R2, and notebook-presentation mechanics. Producer
schemas, ingestion policy, semantic normalization, artifact contracts, and
application state stay with the repository that defines them.

## 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 runtime integration a consumer needs:

```sh
uv add 'deped-runtime[excel]'   # openpyxl workbook helpers
uv add 'deped-runtime[polars]'  # SQLite query/source frames
uv add 'deped-runtime[r2]'      # Cloudflare R2 API and CLI
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/files-and-workbooks.md).
- Inspect SQLite, attach sources read-only, validate raw source tables, or
  return Polars frames: see [SQL and SQLite](docs/sql-and-sqlite.md).
- Render consistent command status and build progress: see
  [console and progress](docs/console-and-progress.md).
- Transfer namespaced artifacts with the API or CLI: see
  [R2 transfers](docs/r2.md).
- Produce a Markdown quality report for a SQLite table: see
  [`profile-table`](docs/profile-table.md).
- Compose consistent Marimo sidebars, stats, tables, callouts, and charts: see
  [notebook design system](docs/notebooks.md).
- Move a consumer from `deped-dcp-template 0.9.0`: see the
  [migration guide](docs/migration-0.1.md).

The complete ownership boundary and module map are in the
[documentation](docs/index.md).

## Quick examples

```python
from deped_runtime.artifacts import file_sha256
from deped_runtime.sqlite import connect_readonly_sqlite, relation_columns

with connect_readonly_sqlite("artifacts/example.db") as conn:
    print(file_sha256("artifacts/example.db"))
    print(relation_columns(conn, "example"))
```

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

## Development

```sh
just docs   # serve documentation on http://localhost:8002
just check  # lint, type-check, test, build docs, and build the wheel
```
