Metadata-Version: 2.3
Name: deped-runtime
Version: 0.6.2
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.4
Requires-Dist: rich>=15.0
Requires-Dist: altair>=6.2.2 ; extra == 'all'
Requires-Dist: botocore>=1.43.46 ; extra == 'all'
Requires-Dist: branca>=0.8.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.16 ; extra == 'all'
Requires-Dist: numpy>=2 ; extra == 'all'
Requires-Dist: openpyxl>=3.1.5 ; extra == 'all'
Requires-Dist: polars>=1.42 ; extra == 'all'
Requires-Dist: pyarrow>=22.0 ; extra == 'all'
Requires-Dist: pydantic>=2.13.0 ; extra == 'all'
Requires-Dist: shapely>=2.1 ; extra == 'all'
Requires-Dist: altair>=6.2.2 ; extra == 'charts'
Requires-Dist: polars>=1.42 ; extra == 'charts'
Requires-Dist: openpyxl>=3.1.5 ; extra == 'excel'
Requires-Dist: numpy>=2 ; extra == 'geodesy'
Requires-Dist: polars>=1.42 ; 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.23.16 ; extra == 'marimo'
Requires-Dist: marimo[sql]>=0.23.16 ; extra == 'marimo-sql'
Requires-Dist: altair>=6.2.2 ; extra == 'notebooks'
Requires-Dist: marimo>=0.23.16 ; extra == 'notebooks'
Requires-Dist: polars>=1.42 ; extra == 'notebooks'
Requires-Dist: altair>=6.2.2 ; extra == 'notebooks-maps'
Requires-Dist: branca>=0.8.2 ; extra == 'notebooks-maps'
Requires-Dist: folium>=0.20 ; extra == 'notebooks-maps'
Requires-Dist: marimo>=0.23.16 ; extra == 'notebooks-maps'
Requires-Dist: polars>=1.42 ; extra == 'notebooks-maps'
Requires-Dist: altair>=6.2.2 ; extra == 'notebooks-sql'
Requires-Dist: marimo[sql]>=0.23.16 ; extra == 'notebooks-sql'
Requires-Dist: polars>=1.42 ; extra == 'notebooks-sql'
Requires-Dist: polars>=1.42 ; extra == 'polars'
Requires-Dist: botocore>=1.43.46 ; extra == 'r2'
Requires-Dist: cloudflare-r2>=0.0.6 ; extra == 'r2'
Requires-Dist: pydantic>=2.13.0 ; 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` is the dependency-light operational layer shared by DepEd data
repositories. It provides reusable artifact, file, SQLite, SQL, Rich console,
workbook, source-staging, source-product, GeoParquet, WKB geometry, profiling,
R2, pagination, 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[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).
- 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_sha256
from deped_runtime.sqlite import open_readonly_sqlite, relation_columns

with open_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
```
