deped-primitives 0.1.1

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

Read the package top-down:

• places get one canonical identity across PSGC IDs, legacy codes, boundary PCODEs, and source names;
• regions can be read through geography, congressional, and school-admin lenses;
• areas carry boundary geometry, PSGC classifications, shapefile metrics, and school-observation properties;
• users drill down a lens tree to an area, access scopes gate the visible subtree, and metrics/outliers measure the selected population.

The root package exposes only __version__ and the seven domain packages. Helper symbols live in their owner modules so their contracts remain explicit. See the documentation overview for the domain flow and ecosystem guide for the sibling-repo ownership map.

Ecosystem

deped-primitives interprets across the ecosystem data flow:

• deped-psgc, deped-legdist, deped-enroll, and deped-entity produce source contracts.
• deped-dataset builds canonical identity and school-observation tables.
• deped-maps combines identity with shapefiles so areas have shared IDs, shapes, population, and area_sqkm.
• deped-geos aggregates area and school properties into read-only geography artifacts.
• deped-analytics serves the office-scoped user-facing app.

Provider repositories such as deped-web, deped-hr, deped-equipment, and deped-exams keep their own domain artifacts and public tables. The ecosystem guide explains why those sibling repos remain separate and which shared rules belong here.

Quick Start

from deped_primitives.identity import GeoType, ancestor_codes, breakdown, normalize_code
from deped_primitives.identity.codes import normalize_boundary_pcode_to_psgc_id
from deped_primitives.schools.names import clean_school_name
from deped_primitives.selection.access import AccessScope, scope_locks_from_access
from deped_primitives.selection.sql import (
    SCHOOL_OBSERVATIONS_ADAPTER,
    FilterSpec,
    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.areas.boundaries import (
    area_component_rollups,
    usable_area_boundary_components,
)
from deped_primitives.authority.legislative import legislative_child_rollups
from deped_primitives.areas.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

The status page is the capability map. The generated package reference shows the seven root packages, and the module reference pages show complete owner-module surfaces.

Documentation

• Overview explains where this package sits between producers and consumers and how identity, regions, boundaries, filters, access, and metrics connect.
• Ecosystem explains the sibling-repo ownership boundaries and the rule for moving shared semantics into this package.
• Core references, codes, coordinates, boundaries, and legislative cover the central semantic contracts.
• Hierarchy, region group, filter, access, SQL, DataFrames, Providers, and Marimo references cover reusable construction helpers.
• Planning metrics, outliers, and CLI cover shared scoring and terminal build helpers.
• 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