Metadata-Version: 2.3
Name: deped-dcp-template
Version: 0.12.2
Summary: Shared templates and cleaning semantics for DepEd DCP data packages.
Requires-Dist: deped-primitives>=0.17.0,<0.18
Requires-Dist: deped-runtime[excel]>=0.9.0,<0.10
Requires-Dist: click>=8.4
Requires-Dist: email-validator>=2.3
Requires-Dist: deped-runtime[r2]>=0.9.0,<0.10 ; extra == 'r2'
Requires-Python: >=3.14
Provides-Extra: r2
Description-Content-Type: text/markdown

# deped-dcp-template

`deped-dcp-template` packages the approved version 1.16 DepEd Computerization
Program (DCP) workbooks and the rules needed to read their controlled values.
It can extract lookup tables into SQLite and normalize submitted DCP values.

Version `0.10.0` replaced the former catch-all cleaner with focused, typed
modules. Applications remain responsible for loading their own source data and
writing their own databases. See the
[DepEd Orchestrator](https://mv3.dev/deped-orchestrator/) for this package's
place in the wider build process.

## Install

```bash
uv add deped-dcp-template
```

## Commands

```bash
uv run deped-dcp-template extract --templates-dir templates --output artifacts/base.db
uv run deped-dcp-template show --db artifacts/base.db
uv run --extra r2 deped-runtime r2 ls --prefix deped-dcp-template/templates
```

R2 support is optional and provided by `deped-runtime`.

## Public modules

- `normalization`, `values`, and `timestamps` handle submitted scalar values.
- `contacts`, `people`, and `entities` handle DCP collection records.
- `positions` and `equipment` expose immutable catalog builders and
  normalization policy.
- `audit` records shared DCP validation evidence.
- `extractor` and `template_assets` own canonical workbook artifacts.

Generic file, Excel, console, SQL, SQLite, and storage mechanics belong to
`deped-runtime`. Ecosystem-wide DepEd identity and governance semantics belong
to `deped-primitives`. In particular,
`deped_dcp_template.values.normalize_school_id` intentionally retains the
integer-coercion contract used by DCP collection schemas; it is not a
replacement for the Primitives school-identity APIs.

## Documentation and checks

- [Docs index](docs/index.md)
- [Architecture](docs/architecture.md)
- [Lookup extraction](docs/lookup-extraction.md)
- [Normalization](docs/normalization.md)
- [Downstream adoption](docs/downstream-adoption.md)

```bash
just preflight
just status --json
just audit
just check
just package
```

This is a shared library, so `just build` intentionally explains that there is
no repository-level data product. Consumers use the explicit
`deped-dcp-template extract` command for lookup databases. `just download`
restores canonical templates; `just fetch` performs no network refresh.

## Shared-library development

The `[tool.uv.sources]` entries select sibling checkouts for this coordinated
release; published packages retain versioned requirements. Keep the declared
sibling repositories next to this checkout. Run `uv sync --locked --all-extras`,
then `pre-commit run --all-files` and `just check`. Candidate distributions are
also validated without editable sources before external publication.

## Command environment

R2 transfer recipes use `op run --env-file=env.r2` to resolve the checked-in
1Password references only for the transfer process. Install the 1Password CLI
and authorize access to the referenced vault before running them.
`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

Have your secret manager or CI secret store supply `CF_ACCT_ID`,
`R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, and `R2_BUCKET` to the command's
environment, with `R2_REGION=auto`. Supply resolved values, not `op://`
references. Run the underlying CLI directly; the Just transfer recipes still
invoke `op`, even when credentials are already exported:

```sh
uv run --extra r2 deped-runtime r2 download --target "src/deped_dcp_template/templates" --prefix "deped-dcp-template/templates"
uv run --extra r2 deped-runtime r2 upload --source "src/deped_dcp_template/templates" --prefix "deped-dcp-template/templates" --include 'ict-equipment-inventory-school-template_v1.16.xlsx' --include 'ict-equipment-inventory-division-template_v1.16.xlsx' --include 'ict-equipment-inventory-region-template_v1.16.xlsx'
```

These examples use the repository's default paths and prefixes. Adjust the
explicit flags for another location, retaining any include/overwrite options.
The upload command writes to the remote bucket. If you lack bucket access,
obtain the required inputs from maintainers and place them at the documented
local paths; installing 1Password does not itself grant data access.

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.
