deped-primitives 0.0.1

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

deped-primitives

Shared DepEd primitives for PSGC codes and boundary-code normalization.

The package is in its parity phase. It ports existing behavior from the DepEd toolchain into a small, tested library before downstream repositories migrate.

Purpose

The package gives downstream projects one tested owner for shared DepEd value rules that were duplicated across repositories:

• PSGC code shape validation and slicing.
• PSGC geographic level normalization and labels.
• Parent and ancestor rules for regions, provinces, HUCs, NCR localities, Manila sub-municipalities, and barangays.
• Pure predecessor/successor lineage resolution helpers.
• PSA/NAMRIA boundary PCODE and legacy-code normalization.
• Stable comparable-name keys for exact source matching.
• Area hierarchy constants and public hierarchy option aliases.
• Regional reporting groups and their component-region rows.
• Region display aliases, school grade key stages, and school-size bands.
• Territory cascade state, area-scope filters, descendant/ancestor membership traversal, and dataset foundation selection normalization.
• Schema-adapter SQL builders for the school_observations explorer surface.
• Optional Marimo helpers for cascading dropdown notebooks.
• Legislative anchor normalization, descendant barangay predicates, and legislative district code generation.

It deliberately does not include dataframe pipelines, workbook loading, full legislative coverage builders, YAML policy contracts, migration wrappers, or repo-specific dashboards. Those remain in their source repos unless a later plan explicitly moves them.

Scope

• deped_primitives.psgc: zero-dependency PSGC parsing, hierarchy inference, parent/ancestor rules, relation validation, typed code breakdowns, normalized geo types, constants, and pure lineage helpers.
• deped_primitives.codes: stdlib normalization helpers for PSGC IDs, PSA/NAMRIA boundary PCODEs, legacy codes, and comparable name keys.
• deped_primitives.hierarchies: shared hierarchy constants, derived group IDs, level labels, hierarchy aliases, and sort helpers.
• deped_primitives.region_groups: regional reporting group definitions, options, membership lookups, and Polars component-row generation.
• deped_primitives.regions: region display aliases keyed by PSGC region ID.
• deped_primitives.education: grade labels and key-stage lookup helpers.
• deped_primitives.school_sizes: school-size bands and inclusive range lookups.
• deped_primitives.filters: Polars territory cascades, area-scope helpers, hierarchy membership traversal, and dataset-style selection normalization.
• deped_primitives.access: office access scopes, derived UI scope locks, island-group scoping, and access-limited area-stats filtering.
• deped_primitives.sql: schema-adapter SQL builders for the dataset school_observations explorer queries.
• deped_primitives.marimo: optional notebook control helpers; Marimo is loaded only by the consumer environment.
• deped_primitives.legislative: legislative value primitives only.

The documentation is organized by domain:

• docs/index.md is the landing page and current-scope summary.
• docs/guide/psgc-and-codes.md covers PSGC, lineage, and boundary-code helpers.
• docs/guide/hierarchies-and-region-groups.md covers hierarchy and regional reporting helpers.
• docs/guide/reference-vocabularies.md covers region aliases, grade key stages, and school-size bands.
• docs/guide/filters.md covers territory cascade, area-scope, membership, and selection helpers.
• docs/guide/querying.md covers SQL builders and optional Marimo controls.
• docs/guide/legislative.md covers legislative value helpers.
• docs/reference/ contains generated API reference pages.
• docs/status.md records landed and deferred scope.

The root package intentionally exposes only __version__. Import concrete helpers from their owner modules:

from deped_primitives.psgc import GeoType, ancestor_codes, breakdown, normalize_code
from deped_primitives.codes import normalize_boundary_pcode_to_psgc_id

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"

Pure lineage helpers live below deped_primitives.psgc.lineage:

from deped_primitives.psgc.lineage import psgc_like_from_code

assert psgc_like_from_code("098301000") == "0908301000"

Hierarchy and regional group helpers live in their owner modules:

from deped_primitives.hierarchies import configured_levels, hierarchy_internal_value
from deped_primitives.region_groups import region_group_region_ids
from deped_primitives.regions import region_common_label
from deped_primitives.school_sizes import school_size_label
from deped_primitives.filters import cascade_control_levels, derive_result_level
from deped_primitives.access import AccessScope, scope_locks_from_access
from deped_primitives.sql import SCHOOL_OBSERVATIONS_ADAPTER, FilterSpec, summary_sql
from deped_primitives.legislative import legis_id

assert hierarchy_internal_value("geo") == "psgc_normalized"
assert configured_levels("geo")[0] == "region_group"
assert "1900000000" not in region_group_region_ids("excluding_barmm")
assert region_common_label("1300000000") == "NCR"
assert school_size_label(101) == "vs"
assert cascade_control_levels("geo") == ("region", "province", "locality", "barangay")
assert derive_result_level("geo", (("region", "1300000000"),)) == "province"
assert scope_locks_from_access(
    AccessScope(level="regional", psgc_region_id="1300000000")
).locked_levels == ("region",)
assert "school_observations" in summary_sql(SCHOOL_OBSERVATIONS_ADAPTER, FilterSpec())
assert legis_id(20, "1381701000", 0) == "201381701x"

Development

just test
just check
uv run zensical build

Core depends on Polars only. Marimo remains optional:

uv run --extra marimo marimo check notebooks/*.py