Metadata-Version: 2.4
Name: deped-runtime
Version: 0.1.0
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: cloudflare-r2>=0.0.6; 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: excel
Requires-Dist: openpyxl>=3.1.5; extra == 'excel'
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.1.0` owns reusable artifact, file, SQLite, SQL, Rich
console, workbook, profiling, and R2 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[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).
- 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
```
