deped-primitives 0.0.1__tar.gz

deped_primitives-0.0.1/.editorconfig

@@ -0,0 +1,18 @@
+# http://editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.py]
+indent_size = 4
+
+[*.{css,html,js,json,sass,scss,vue,yaml,yml}]
+indent_style = space
+indent_size = 2

deped_primitives-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: Example UV CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  uv-example:
+    name: Python (UV)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@main
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install the project with UV
+        run: uv sync --locked --all-extras --dev
+
+      - name: Install Dependencies
+        run: |
+          uv tool install pre-commit --with pre-commit-uv
+          pre-commit install-hooks
+
+      - name: Lint with pre-commit
+        run: pre-commit run --all-files
+
+      - name: Run tests
+        run: uv run pytest

deped_primitives-0.0.1/.gitignore

@@ -0,0 +1,148 @@
+.DS_Store
+.ruff_cache
+*.sqlite
+*.db
+*.db-shm
+*.db-wal
+*.rdb
+.env.*
+__marimo__
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/

deped_primitives-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+default_language_version:
+  python: python3.14
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: name-tests-test
+        args: ["--django"]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.15.17
+    hooks:
+      # Run the linter.
+      - id: ruff-check
+        args: [--fix]
+      # Run the formatter.
+      - id: ruff-format
+        types_or: [python, pyi, jupyter]

deped_primitives-0.0.1/AGENTS.md

@@ -0,0 +1,27 @@
+# Standards
+
+## Start With The Docs
+
+1. For new features, read the relevant docs before broad code search.
+2. Start with `README.md`, `docs/index.md`.
+4. Use the docs to identify likely app boundaries and entrypoints, then run targeted `rg` searches.
+5. If behavior is not documented, inspect tests and implementation. Update docs when a change affects public concepts, routes, workflows, or commands.
+
+## Valid Code
+
+1. `except TypeError, ValueError` is valid in Python 3.14 and will compile, no need to fix.
+2. If unnecessary, do not use lazy imports
+3. After adding new feature, run `pre-commit run --all-files`, resolve any linting issues, then run `just check`
+
+## Design Choices
+
+1. Avoid pass-through adapters: do not add wrappers that merely rename, re-shape, or forward to another function unless they enforce a durable boundary, shared signature normalization, policy, validation, caching, logging, transactions, or meaningful repeated construction.
+2. Prefer existing app boundaries, shell helpers, and documented integration patterns over new one-off service/helper layers.
+3. When replacing an abstraction, update its callers and remove the obsolete layer in the same change.
+4. Keep changes scoped. Avoid unrelated refactors, route churn, migration resets, generated-file churn, and developer-data changes unless explicitly requested.
+
+## Commands And Verification
+
+1. Use `uv run` and `just` recipes.
+2. Routine check with `just check`.
+4. Prefer targeted pytest slices for behavior changes.

deped_primitives-0.0.1/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+## Unreleased
+
+Post-parity hardening. Unlike the parity release, these are net-new APIs; each
+lands with a named downstream consumer and its own fixtures, and the root package
+still exposes only `__version__`. Planned hardening (legislative coverage
+building and its YAML policy) is tracked in
+[`docs/status.md`](docs/status.md).
+
+### Added
+
+- `deped_primitives.psgc.relations` with `is_valid_parent_child` (parent/child
+  validation across the NCR, HUC, Manila sub-municipality, and
+  municipality-collapse rules) and `breakdown` / `PsgcBreakdown` typed code
+  breakdowns for breadcrumb and drilldown context.
+- `classify_lineage_delta` with `LineageDelta` / `LineageDeltaKind` in
+  `deped_primitives.psgc.lineage`, classifying resolved predecessor/successor
+  relationships as renamed, merged, split, transferred, or unchanged.
+- `deped_primitives.hierarchies.graph` with the `HierarchyGraph` value object
+  (`cascade_path`, parent/child/ancestor/descendant traversal, `id_column`,
+  `boundary_level`), the prebuilt `PSGC_GRAPH` / `PSGC_NORMALIZED_GRAPH` /
+  `GOVERNANCE_GRAPH` / `LEGISLATIVE_GRAPH`, the `hierarchy_graph` resolver, and
+  opt-in `HierarchyGraph.extend(...)` for consumer drilldown levels (e.g. the
+  `psgc-maps` `legis_child` extension) that never mutate the core graphs.
+- `resolve_level_alias` in `deped_primitives.hierarchies.aliases`, the single
+  owner of the `locality ↔ city ↔ municipality` equivalence, plus the
+  `has_boundary_geometry` / `boundary_artifact_name` renderability predicates.
+- `deped_primitives.access` with `AccessScope` (office permission scope),
+  `ScopeLocks` (derived UI lock state), `scope_locks_from_access`, and Polars
+  island-group and access-scoped area-stats filtering rewritten from the pandas
+  originals.
+- Generalized, adapter-declared SQL search (`search_clause(adapter, query,
+  fields=None)` backed by `SchemaAdapter.searchable_fields`) and the centralized
+  `deped_primitives.sql.labels` module owning the
+  region/locality/barangay/legislative label-coalesce precedence previously
+  duplicated across the builders — a behavior-preserving refactor (default field
+  set and label output unchanged).
+- Hardening fixtures captured from source-repo behavior for each capability
+  above (parent/child truth tables, the Bacoor merger lineage delta, graph
+  traversal incl. the `legis_child` extension, and access-scope round-trips).
+
+## 0.0.1
+
+- Add parity-phase scaffold for `deped-primitives`.
+- Add `deped_primitives.psgc` with PSGC type, constant, core, exception, and
+  pure lineage helpers.
+- Add `deped_primitives.codes` with PSGC, boundary PCODE, legacy code, and name
+  normalization helpers.
+- Add `deped_primitives.hierarchies` with shared area contract constants,
+  hierarchy aliases, level labels, derived group-id helpers, and sort helpers.
+- Add `deped_primitives.region_groups` with the eight shared regional reporting
+  groups and a Polars component builder.
+- Use the `psgc-maps` region-group display order as the canonical option order;
+  `deped-geos` exposed the same eight groups with a different option ordering.
+- Add `deped_primitives.regions`, `deped_primitives.education`, and
+  `deped_primitives.school_sizes` with parity fixtures captured from
+  `deped-dataset/data/generic.yml`.
+- Capture Phase 2b generic-reference fixtures for `region_names`,
+  `school_grades`, `school_sizes`, region display-label coalescing, and
+  inclusive school-size range matching.
+- Add `deped_primitives.filters` with Polars territory cascade state, area-scope
+  helpers, membership traversal, and dataset foundation selection normalization.
+- Capture Phase 3 parity fixtures for NCR province skipping, region-group plus
+  manual area-scope composition, SGA default exclusion, and stale selection
+  clearing.
+- Add `deped_primitives.sql` with a `SchemaAdapter`, plain `FilterSpec`, dataset
+  `school_observations` SQL builders, choice SQL, rollup columns, where-clause
+  builders, and quote escaping.
+- Add `deped_primitives.marimo` with optional cascading dropdown, `selection_with`,
+  and `option_key` helpers, plus a notebook smoke example for `check-notebooks`.
+- Add `deped_primitives.legislative` with value primitives for legdist
+  normalization, anchor descendant predicates, anchor IDs by congress, and
+  legislative district code generation.
+- Capture Phase 4 and Phase 6 parity fixtures for dataset explorer SQL fragments
+  and legislative value primitives.
+- Document the purpose of landed Phase 1 through Phase 6 and the exact module
+  surface currently available.
+- Share filter and SQL selection constants through `deped_primitives.filters`
+  and refresh stale docs that still described shipped parity phases as future
+  work.
+- Enable the Zensical `mkdocstrings` plugin with the Python handler so generated
+  API reference pages render from source docstrings.

deped_primitives-0.0.1/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: deped-primitives
+Version: 0.0.1
+Summary: Shared DepEd PSGC, hierarchy, territory, SQL, and Marimo primitives.
+Author-email: Marcelino Veloso III <marsveloso@gmail.com>
+Requires-Python: >=3.14
+Requires-Dist: polars>=1.41
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: marimo
+Requires-Dist: marimo>=0.16; extra == 'marimo'
+Description-Content-Type: text/markdown
+
+# deped-primitives
+
+![Github CI](https://github.com/justmars/deped-primitives/actions/workflows/ci.yml/badge.svg)
+
+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:
+
+```python
+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`:
+
+```python
+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:
+
+```python
+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
+
+```sh
+just test
+just check
+uv run zensical build
+```
+
+Core depends on Polars only. Marimo remains optional:
+
+```sh
+uv run --extra marimo marimo check notebooks/*.py
+```

deped_primitives-0.0.1/README.md

@@ -0,0 +1,139 @@
+# deped-primitives
+
+![Github CI](https://github.com/justmars/deped-primitives/actions/workflows/ci.yml/badge.svg)
+
+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:
+
+```python
+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`:
+
+```python
+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:
+
+```python
+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
+
+```sh
+just test
+just check
+uv run zensical build
+```
+
+Core depends on Polars only. Marimo remains optional:
+
+```sh
+uv run --extra marimo marimo check notebooks/*.py
+```