deped-primitives 0.0.5

Shared DepEd PSGC, hierarchy, territory, SQL, and Marimo primitives.

deped-primitives

deped-primitives is the shared semantic contract layer for the DepEd data ecosystem. Producer repositories publish artifacts and source-specific contracts; consumer repositories build maps, datasets, notebooks, and dashboards. This package owns the reusable value rules and interpretation semantics between those layers.

It is intentionally not an application framework. It does not load source workbooks, dissolve geometry, persist databases, run downstream build CLIs, write artifacts, or host dashboards. It gives every DepEd repo one small, tested place to import the rules that should not be reimplemented locally.

Mental Model

The package has four API families:

• Foundation primitives: PSGC code rules, boundary/legacy code normalization, hierarchy metadata, region groups, and shared reference vocabularies.
• Artifact semantics: normalized PSGC frames, deped-maps boundary artifact interpretation, legislative coverage semantics, and legislative child rollup classification.
• Product construction helpers: territory filters, access scopes, schema-adapter SQL builders, CLI build-progress helpers, and optional Marimo notebook controls.
• Source-reference helpers: governance label normalization, DepEd division and school-district IDs, UACS organization reference keys, school-name normalization, and small reusable Polars frame helpers.

The root package exposes a curated facade for common foundation, construction, and source-reference helpers. Specialized artifact semantics and complete module surfaces stay in their owner modules so their contracts remain explicit.

Quick Start

from deped_primitives import (
    AccessScope,
    FilterSpec,
    GeoType,
    SCHOOL_OBSERVATIONS_ADAPTER,
    add_governance_ids,
    ancestor_codes,
    breakdown,
    clean_school_name,
    normalize_boundary_pcode_to_psgc_id,
    normalize_code,
    scope_locks_from_access,
    summary_sql,
)

assert normalize_code(" 13-3900-0000 ") == "1339000000"
assert ancestor_codes("1380610001", GeoType.BGY) == [
    "1300000000",
    "1380600000",
    "1380610000",
]
assert breakdown("0908301001").barangay.code == "0908301001"
assert normalize_boundary_pcode_to_psgc_id("PH0102801") == "0102801000"
assert scope_locks_from_access(
    AccessScope(level="regional", psgc_region_id="1300000000")
).locked_levels == ("region",)
assert clean_school_name("baliwag nhs") == "Baliwag National High School"
assert "school_observations" in summary_sql(
    SCHOOL_OBSERVATIONS_ADAPTER,
    FilterSpec(),
)

Import specialized semantics from owner modules:

from deped_primitives.boundaries import (
    area_component_rollups,
    usable_area_boundary_components,
)
from deped_primitives.legislative import legislative_child_rollups
from deped_primitives.psgc.frames import normalized_psgc_group_rows

groups = normalized_psgc_group_rows(canonical_psgc_units)
usable_components = usable_area_boundary_components(area_boundary_components)
display_components = area_component_rollups(area_boundary_components, canonical_psgc_units)
children = legislative_child_rollups(coverage, barangay_context)

Owned Surfaces

• deped_primitives.psgc and psgc.frames: PSGC parsing, validation, parentage, Manila sub-municipality normalization, typed breakdowns, lineage, and normalized group-row construction from canonical_psgc_units.csv.
• deped_primitives.codes: PSGC ID, PSA/NAMRIA PCODE, legacy-code, and comparable-name normalization plus caller-provided canonical-name mapping.
• deped_primitives.coordinates: shared school coordinate parsing, Philippine review extent validation, Pag-asa/Kalayaan handling, and presence status classification.
• deped_primitives.boundaries: consumer-safe interpretation of deped-maps boundary mapping and area-boundary component artifacts.
• deped_primitives.hierarchies and region_groups: shared hierarchy metadata, aliases, graph topology, renderability, derived IDs, and regional reporting groups.
• deped_primitives.regions, education, and school_sizes: typed reference vocabularies.
• deped_primitives.urbanicity, school_ids, and school_years: shared urban/rural bands, EBEIS school-ID first-digit rules, and school-year source specs.
• deped_primitives.filters and access: territory cascades, area scopes, membership traversal, office permission scopes, and UI lock derivation.
• deped_primitives.sql, cli, and marimo: schema-adapter SQL builders, shared CLI build-progress helpers, and optional notebook controls.
• deped_primitives.legislative: legislative anchors, coverage policy, coverage completion, area linkage, special cases, and child rollup classification.
• deped_primitives.outliers and planning_metrics: reusable statistical scoring helpers and Polars planning metric formulas for downstream review and geography products.
• deped_primitives.frames, enrollment, school_names, and uacs: small Polars frame utilities, DepEd governance ID construction, school-name normalization, and UACS organization reference matching.

Documentation

• Ecosystem role explains where this package sits between producers and consumers.
• PSGC and codes, coordinates, boundaries, and legislative cover the core semantic contracts.
• Hierarchies, reference vocabularies, governance references, planning metrics, filters, and querying cover reusable construction helpers.
• CLI progress covers shared terminal build status and progress helpers for consumer CLIs.
• Status is the current capability map.
• Reference contains generated API pages.

Development

pre-commit run --all-files
just check

Useful narrower commands:

just test
uv run zensical build
uv run --extra marimo marimo check notebooks/*.py