deped-primitives 0.0.1__py3-none-any.whl

deped_primitives/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+__version__ = "0.0.1"

deped_primitives/access/__init__.py

@@ -0,0 +1,34 @@
+from deped_primitives.access.locks import ScopeLocks, scope_locks_from_access
+from deped_primitives.access.scope import (
+    NATIONAL_ACCESS_SCOPE,
+    AccessScope,
+    access_scope_from_value,
+    access_scope_group_ids,
+    access_scope_options,
+    access_scope_stats_scope,
+    access_scope_territory_selections,
+    default_hierarchy_for_access_scope,
+    island_group_area_scope_selections,
+    island_group_for_region,
+    island_group_options,
+    island_group_region_ids,
+    island_group_stats_scope,
+)
+
+__all__ = [
+    "NATIONAL_ACCESS_SCOPE",
+    "AccessScope",
+    "ScopeLocks",
+    "access_scope_from_value",
+    "access_scope_group_ids",
+    "access_scope_options",
+    "access_scope_stats_scope",
+    "access_scope_territory_selections",
+    "default_hierarchy_for_access_scope",
+    "island_group_area_scope_selections",
+    "island_group_for_region",
+    "island_group_options",
+    "island_group_region_ids",
+    "island_group_stats_scope",
+    "scope_locks_from_access",
+]

deped_primitives/access/locks.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from deped_primitives.access.scope import AccessScope, island_group_for_region
+
+
+@dataclass(frozen=True)
+class ScopeLocks:
+    """UI lock state derived from an access permission."""
+
+    island_group: str = ""
+    territory_selections: tuple[tuple[str, str], ...] = ()
+    territory_labels: tuple[tuple[str, str], ...] = ()
+
+    @property
+    def locked_levels(self) -> tuple[str, ...]:
+        return tuple(level for level, _group_id in self.territory_selections)
+
+    @property
+    def has_island_group(self) -> bool:
+        return bool(self.island_group)
+
+    def is_territory_locked(self, level: str) -> bool:
+        return str(level or "") in set(self.locked_levels)
+
+    def group_id_for_level(self, level: str) -> str:
+        return dict(self.territory_selections).get(str(level or ""), "")
+
+    def label_for_level(self, level: str) -> str:
+        return dict(self.territory_labels).get(str(level or ""), "")
+
+
+def scope_locks_from_access(
+    access_scope: AccessScope,
+    island_group: str = "",
+) -> ScopeLocks:
+    """Derive territory UI locks from an office access scope."""
+
+    if access_scope.is_national:
+        return ScopeLocks()
+    selections: list[tuple[str, str]] = []
+    labels: list[tuple[str, str]] = []
+    if access_scope.is_regional:
+        selections.append(("region", access_scope.psgc_region_id))
+        labels.append(("region", access_scope.psgc_region_id))
+    elif access_scope.is_division:
+        selections.append(("region", access_scope.psgc_region_id))
+        labels.append(("region", access_scope.psgc_region_id))
+        selections.append(("division", access_scope.division_group_id))
+        labels.append(
+            ("division", access_scope.division_name or access_scope.division_group_id)
+        )
+
+    derived_island_group = island_group_for_region(access_scope.psgc_region_id)
+    return ScopeLocks(
+        island_group=derived_island_group or str(island_group or "").strip(),
+        territory_selections=tuple(selections),
+        territory_labels=tuple(labels),
+    )

deped_primitives/access/scope.py

@@ -0,0 +1,445 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import polars as pl
+
+from deped_primitives.filters.membership import base_rows, descendant_group_ids
+from deped_primitives.hierarchies import (
+    hierarchy_graph,
+    hierarchy_internal_value,
+    split_group_id,
+)
+from deped_primitives.region_groups import (
+    region_group_area_scope_selections,
+    region_group_options,
+    region_group_region_ids,
+)
+
+ISLAND_GROUPS = ("luzon", "visayas", "mindanao")
+
+
+@dataclass(frozen=True)
+class AccessScope:
+    """Office-level permission scope for territory-limited workbench users."""
+
+    level: str = "national"
+    psgc_region_id: str = ""
+    division_group_id: str = ""
+    division_name: str = ""
+
+    @property
+    def is_national(self) -> bool:
+        return self.level == "national"
+
+    @property
+    def is_regional(self) -> bool:
+        return self.level == "regional" and bool(self.psgc_region_id)
+
+    @property
+    def is_division(self) -> bool:
+        return (
+            self.level == "division"
+            and bool(self.psgc_region_id)
+            and bool(self.division_group_id)
+            and bool(self.division_name)
+        )
+
+
+NATIONAL_ACCESS_SCOPE = AccessScope()
+_ACCESS_SCOPE_REGION_PREFIX = "regional:"
+_ACCESS_SCOPE_DIVISION_PREFIX = "division:"
+
+
+def island_group_options() -> dict[str, str]:
+    """Return canonical island/region-group options."""
+
+    return region_group_options()
+
+
+def island_group_region_ids(island_group: str) -> tuple[str, ...]:
+    """Return PSGC region IDs for an island group."""
+
+    return region_group_region_ids(island_group)
+
+
+def island_group_area_scope_selections(
+    island_group: str,
+) -> tuple[tuple[str, str], ...]:
+    """Return region-level area-scope selections for an island group."""
+
+    return region_group_area_scope_selections(island_group)
+
+
+def island_group_for_region(region_id: str) -> str:
+    """Return the broad island group containing a PSGC region ID."""
+
+    region = str(region_id or "").strip()
+    if not region:
+        return ""
+    for island_group in ISLAND_GROUPS:
+        if region in island_group_region_ids(island_group):
+            return island_group
+    return ""
+
+
+def island_group_stats_scope(
+    stats: pl.DataFrame,
+    *,
+    school_year_id: int,
+    island_group: str,
+) -> pl.DataFrame:
+    """Filter area stats to rows that descend from an island group's regions."""
+
+    region_ids = island_group_region_ids(island_group)
+    if not region_ids or stats.is_empty():
+        return stats.clone()
+    required = {"school_year_id", "hierarchy", "level", "group_id"}
+    if not required.issubset(stats.columns):
+        return stats.clear()
+
+    rows = stats.filter(pl.col("school_year_id").cast(pl.Int64) == int(school_year_id))
+    if rows.is_empty():
+        return rows
+
+    scoped_parts: list[pl.DataFrame] = []
+    for row in (
+        rows.select(["hierarchy", "level"])
+        .fill_null("")
+        .cast(pl.String)
+        .unique(maintain_order=True)
+        .iter_rows(named=True)
+    ):
+        hierarchy = str(row["hierarchy"])
+        level = str(row["level"])
+        descendant_ids: set[str] = set()
+        for region_id in region_ids:
+            descendant_ids.update(
+                descendant_group_ids(
+                    stats,
+                    school_year_id=school_year_id,
+                    hierarchy=hierarchy,
+                    ancestor_level="region",
+                    ancestor_group_id=region_id,
+                    target_level=level,
+                )
+            )
+        if descendant_ids:
+            scoped_parts.append(
+                rows.filter(
+                    (pl.col("hierarchy").cast(pl.String) == hierarchy)
+                    & (pl.col("level").cast(pl.String) == level)
+                    & (pl.col("group_id").cast(pl.String).is_in(descendant_ids))
+                )
+            )
+    if not scoped_parts:
+        return rows.clear()
+    return pl.concat(scoped_parts, how="vertical").unique(maintain_order=True)
+
+
+def access_scope_options(stats: pl.DataFrame) -> dict[str, str]:
+    """Return option labels and encoded values for national, regional, and division scopes."""
+
+    options = {"All access": "national"}
+    if stats.is_empty():
+        return options
+    for row in _scope_rows(stats, "governance", "region").iter_rows(named=True):
+        group_id = str(row["group_id"])
+        label = _option_label(group_id, str(row["group_label"]))
+        options[f"Region: {label}"] = f"{_ACCESS_SCOPE_REGION_PREFIX}{group_id}"
+    for row in _scope_rows(stats, "governance", "division").iter_rows(named=True):
+        group_id = str(row["group_id"])
+        label = _option_label(group_id, str(row["group_label"]))
+        options[f"Division: {label}"] = f"{_ACCESS_SCOPE_DIVISION_PREFIX}{group_id}"
+    return options
+
+
+def access_scope_from_value(stats: pl.DataFrame, value: object) -> AccessScope:
+    """Parse and validate an encoded access-scope value against governance stats."""
+
+    if isinstance(value, AccessScope):
+        return _validate_access_scope(stats, value)
+    raw = str(value or "")
+    if raw in {"", "national"}:
+        return NATIONAL_ACCESS_SCOPE
+    if raw.startswith(_ACCESS_SCOPE_REGION_PREFIX):
+        region_id = raw.removeprefix(_ACCESS_SCOPE_REGION_PREFIX)
+        region_ids = set(
+            _scope_rows(stats, "governance", "region")
+            .get_column("group_id")
+            .cast(pl.String)
+            .to_list()
+        )
+        if region_id in region_ids:
+            return AccessScope(level="regional", psgc_region_id=region_id)
+    if raw.startswith(_ACCESS_SCOPE_DIVISION_PREFIX):
+        return _division_access_scope(
+            stats, raw.removeprefix(_ACCESS_SCOPE_DIVISION_PREFIX)
+        )
+    return NATIONAL_ACCESS_SCOPE
+
+
+def default_hierarchy_for_access_scope(
+    access_scope: AccessScope,
+    available_hierarchies: list[str] | tuple[str, ...],
+    fallback: str,
+) -> str:
+    """Prefer governance for office-scoped users when that hierarchy is available."""
+
+    if not access_scope.is_national and "governance" in available_hierarchies:
+        return "governance"
+    return fallback
+
+
+def access_scope_territory_selections(
+    access_scope: AccessScope,
+    hierarchy: str,
+) -> tuple[tuple[str, str], ...]:
+    """Return territory selections implied by an access scope for a hierarchy."""
+
+    if access_scope.is_national:
+        return ()
+    normalized_hierarchy = _normalize_hierarchy(hierarchy)
+    try:
+        levels = set(hierarchy_graph(normalized_hierarchy).cascade_path)
+    except ValueError:
+        levels = set()
+    if access_scope.is_regional:
+        return (("region", access_scope.psgc_region_id),) if "region" in levels else ()
+    if not access_scope.is_division:
+        return ()
+    if normalized_hierarchy == "governance":
+        selections = []
+        if "region" in levels:
+            selections.append(("region", access_scope.psgc_region_id))
+        if "division" in levels:
+            selections.append(("division", access_scope.division_group_id))
+        return tuple(selections)
+    return (("region", access_scope.psgc_region_id),) if "region" in levels else ()
+
+
+def access_scope_group_ids(
+    stats: pl.DataFrame,
+    *,
+    school_year_id: int,
+    hierarchy: str,
+    target_level: str,
+    access_scope: AccessScope = NATIONAL_ACCESS_SCOPE,
+    division_coverage: pl.DataFrame | None = None,
+) -> set[str]:
+    """Return target-level group IDs visible under an access scope."""
+
+    normalized_hierarchy = _normalize_hierarchy(hierarchy)
+    if access_scope.is_national:
+        rows = base_rows(
+            stats,
+            school_year_id=school_year_id,
+            hierarchy=normalized_hierarchy,
+            level=target_level,
+        )
+        if rows.is_empty() or "group_id" not in rows.columns:
+            return set()
+        return set(rows.get_column("group_id").cast(pl.String).to_list()) - {""}
+    if access_scope.is_regional:
+        return descendant_group_ids(
+            stats,
+            school_year_id=school_year_id,
+            hierarchy=normalized_hierarchy,
+            ancestor_level="region",
+            ancestor_group_id=access_scope.psgc_region_id,
+            target_level=target_level,
+        )
+    if not access_scope.is_division:
+        return set()
+    if normalized_hierarchy == "governance":
+        return _governance_division_scope_group_ids(
+            stats, school_year_id, target_level, access_scope
+        )
+    if target_level == "region":
+        return {access_scope.psgc_region_id}
+    return _division_coverage_target_group_ids(
+        division_coverage,
+        school_year_id=school_year_id,
+        access_scope=access_scope,
+        hierarchy=normalized_hierarchy,
+        target_level=target_level,
+    )
+
+
+def access_scope_stats_scope(
+    stats: pl.DataFrame,
+    *,
+    school_year_id: int,
+    access_scope: AccessScope = NATIONAL_ACCESS_SCOPE,
+    hierarchy: str = "",
+    division_coverage: pl.DataFrame | None = None,
+) -> pl.DataFrame:
+    """Filter area stats to rows visible under an access scope."""
+
+    if access_scope.is_national or stats.is_empty():
+        return stats.clone()
+    rows = stats.filter(pl.col("school_year_id").cast(pl.Int64) == int(school_year_id))
+    if rows.is_empty():
+        return rows
+
+    scoped_hierarchies = (
+        (_normalize_hierarchy(hierarchy),)
+        if hierarchy
+        else tuple(
+            rows.get_column("hierarchy")
+            .cast(pl.String)
+            .drop_nulls()
+            .unique(maintain_order=True)
+            .to_list()
+        )
+    )
+    scoped_parts: list[pl.DataFrame] = []
+    for scoped_hierarchy in scoped_hierarchies:
+        hierarchy_rows = rows.filter(
+            pl.col("hierarchy").cast(pl.String) == scoped_hierarchy
+        )
+        for target_level in (
+            hierarchy_rows.get_column("level")
+            .cast(pl.String)
+            .drop_nulls()
+            .unique(maintain_order=True)
+            .to_list()
+        ):
+            group_ids = access_scope_group_ids(
+                stats,
+                school_year_id=school_year_id,
+                hierarchy=scoped_hierarchy,
+                target_level=target_level,
+                access_scope=access_scope,
+                division_coverage=division_coverage,
+            )
+            if group_ids:
+                scoped_parts.append(
+                    hierarchy_rows.filter(
+                        (pl.col("level").cast(pl.String) == target_level)
+                        & (pl.col("group_id").cast(pl.String).is_in(group_ids))
+                    )
+                )
+    if not scoped_parts:
+        return rows.clear()
+    return pl.concat(scoped_parts, how="vertical").unique(maintain_order=True)
+
+
+def _validate_access_scope(stats: pl.DataFrame, scope: AccessScope) -> AccessScope:
+    if scope.is_regional:
+        return access_scope_from_value(
+            stats, f"{_ACCESS_SCOPE_REGION_PREFIX}{scope.psgc_region_id}"
+        )
+    if scope.is_division:
+        return access_scope_from_value(
+            stats, f"{_ACCESS_SCOPE_DIVISION_PREFIX}{scope.division_group_id}"
+        )
+    return NATIONAL_ACCESS_SCOPE
+
+
+def _division_access_scope(stats: pl.DataFrame, division_group_id: str) -> AccessScope:
+    matched = _scope_rows(stats, "governance", "division").filter(
+        pl.col("group_id").cast(pl.String) == str(division_group_id)
+    )
+    if matched.is_empty():
+        return NATIONAL_ACCESS_SCOPE
+    try:
+        parsed = split_group_id("governance", "division", str(division_group_id))
+    except ValueError:
+        return NATIONAL_ACCESS_SCOPE
+    return AccessScope(
+        level="division",
+        psgc_region_id=parsed["psgc_region_id"],
+        division_group_id=str(division_group_id),
+        division_name=parsed["division"],
+    )
+
+
+def _governance_division_scope_group_ids(
+    stats: pl.DataFrame,
+    school_year_id: int,
+    target_level: str,
+    access_scope: AccessScope,
+) -> set[str]:
+    if target_level == "region":
+        return {access_scope.psgc_region_id}
+    if target_level == "division":
+        return {access_scope.division_group_id}
+    if target_level == "school_district":
+        return descendant_group_ids(
+            stats,
+            school_year_id=school_year_id,
+            hierarchy="governance",
+            ancestor_level="division",
+            ancestor_group_id=access_scope.division_group_id,
+            target_level=target_level,
+        )
+    return set()
+
+
+def _division_coverage_target_group_ids(
+    division_coverage: pl.DataFrame | None,
+    *,
+    school_year_id: int,
+    access_scope: AccessScope,
+    hierarchy: str,
+    target_level: str,
+) -> set[str]:
+    if division_coverage is None or division_coverage.is_empty():
+        return set()
+    required = {
+        "school_year_id",
+        "division_group_id",
+        "target_hierarchy",
+        "target_level",
+        "target_group_id",
+    }
+    if not required.issubset(division_coverage.columns):
+        return set()
+    rows = division_coverage.filter(
+        (pl.col("school_year_id").cast(pl.Int64) == int(school_year_id))
+        & (
+            pl.col("division_group_id").cast(pl.String)
+            == access_scope.division_group_id
+        )
+        & (pl.col("target_hierarchy").cast(pl.String) == hierarchy)
+        & (pl.col("target_level").cast(pl.String) == target_level)
+    )
+    if rows.is_empty():
+        return set()
+    return set(rows.get_column("target_group_id").cast(pl.String).to_list()) - {""}
+
+
+def _scope_rows(stats: pl.DataFrame, hierarchy: str, level: str) -> pl.DataFrame:
+    if stats.is_empty() or not {"hierarchy", "level", "group_id"}.issubset(
+        stats.columns
+    ):
+        return pl.DataFrame({"group_id": [], "group_label": []})
+    label_expr = (
+        pl.col("group_label").cast(pl.String)
+        if "group_label" in stats.columns
+        else pl.lit("", dtype=pl.String)
+    )
+    return (
+        stats.filter(
+            (pl.col("hierarchy").cast(pl.String) == hierarchy)
+            & (pl.col("level").cast(pl.String) == level)
+        )
+        .with_columns(
+            pl.col("group_id").cast(pl.String).alias("group_id"),
+            label_expr.alias("group_label"),
+        )
+        .select(["group_id", "group_label"])
+        .unique(subset=["group_id"], keep="first", maintain_order=True)
+        .sort(["group_label", "group_id"], maintain_order=True)
+    )
+
+
+def _option_label(group_id: str, group_label: str) -> str:
+    label = str(group_label or "").strip()
+    return group_id if not label or label == group_id else f"{label} ({group_id})"
+
+
+def _normalize_hierarchy(hierarchy: str) -> str:
+    value = str(hierarchy or "").strip()
+    return hierarchy_internal_value(value) or value

deped_primitives/codes/__init__.py

@@ -0,0 +1,87 @@
+"""Code and name normalization helpers for PSGC and PSA/NAMRIA ADM PCODEs."""
+
+import re
+import unicodedata
+
+_PH_PCODE_RE = re.compile(r"^PH[0-9]*$")
+
+
+def clean_text(value: object) -> str:
+    """Return a stripped string, preserving empty values as an empty string."""
+    if value is None:
+        return ""
+    return str(value).strip()
+
+
+def normalize_psgc_id(value: object) -> str:
+    """Normalize a PSGC ID to the canonical 10-character string shape."""
+    text = clean_text(value)
+    if not text:
+        return ""
+    if not text.isdigit() or len(text) > 10:
+        return text
+    return text.zfill(10)
+
+
+def is_valid_boundary_pcode(pcode: object) -> bool:
+    """Return true when a boundary PCODE has the expected PH-prefixed shape."""
+    text = clean_text(pcode)
+    return bool(text) and bool(_PH_PCODE_RE.fullmatch(text))
+
+
+def normalize_boundary_pcode_to_psgc_id(pcode: object) -> str:
+    """Convert a PH-prefixed ADM PCODE into the direct 10-digit PSGC candidate."""
+    text = clean_text(pcode)
+    if not is_valid_boundary_pcode(text):
+        return ""
+    return text.removeprefix("PH").ljust(10, "0")
+
+
+def normalize_legacy_code(value: object) -> str:
+    """Normalize the PSGC legacy/common code column to a 9-digit candidate."""
+    text = clean_text(value)
+    if not text:
+        return ""
+    if text.endswith(".0"):
+        text = text[:-2]
+    if not text.isdigit():
+        return text
+    return text.zfill(9)
+
+
+def normalize_boundary_pcode_to_legacy_code(pcode: object) -> str:
+    """Convert a 2023 ADM PCODE into the 9-digit PSGC legacy code candidate.
+
+    The 2023 ADM PCODEs retain older compact province/HUC code shapes. Current
+    PSGC IDs can move after reorganizations, but the `cc` column keeps the
+    older code needed for audited fallback matches.
+    """
+    text = clean_text(pcode)
+    if not is_valid_boundary_pcode(text):
+        return ""
+    digits = text.removeprefix("PH")
+    if len(digits) >= 5 and digits[2] == "0":
+        digits = digits[:2] + digits[3:]
+    return digits.ljust(9, "0")
+
+
+def comparable_name(value: object) -> str:
+    """Normalize names only enough to catch casing and whitespace noise."""
+    return " ".join(clean_text(value).split()).casefold()
+
+
+def strip_parenthetical(value: object) -> str:
+    """Remove parenthetical chunks used for alias markers in source names."""
+    return re.sub(r"\s*\([^)]*\)", "", clean_text(value)).strip()
+
+
+def name_key(value: object) -> str:
+    """Normalize a name for exact alias-key comparisons."""
+    normalized = unicodedata.normalize("NFKD", clean_text(value))
+    ascii_text = normalized.encode("ascii", "ignore").decode("ascii")
+    return re.sub(r"[^a-z0-9]+", " ", ascii_text.casefold()).strip()
+
+
+def alias_key(value: object) -> str:
+    """Return the canonical key for exact alias matching."""
+    return name_key(strip_parenthetical(value))

deped_primitives/education/__init__.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Iterable
+
+import polars as pl
+
+
+@dataclass(frozen=True)
+class GradeSpec:
+    """School grade label and key-stage mapping."""
+
+    label: str
+    key_stage: int
+
+
+SCHOOL_GRADES: tuple[GradeSpec, ...] = (
+    GradeSpec("kinder", 1),
+    GradeSpec("esng", 1),
+    GradeSpec("g1", 1),
+    GradeSpec("g2", 1),
+    GradeSpec("g3", 1),
+    GradeSpec("g4", 2),
+    GradeSpec("g5", 2),
+    GradeSpec("g6", 2),
+    GradeSpec("g7", 3),
+    GradeSpec("g8", 3),
+    GradeSpec("g9", 3),
+    GradeSpec("g10", 3),
+    GradeSpec("jhsng", 3),
+    GradeSpec("g11", 4),
+    GradeSpec("g12", 4),
+)
+SCHOOL_GRADES_BY_LABEL = {grade.label: grade for grade in SCHOOL_GRADES}
+
+
+def grade_spec(label: str) -> GradeSpec | None:
+    """Return the grade spec for a case-insensitive grade label."""
+
+    return SCHOOL_GRADES_BY_LABEL.get(str(label or "").lower())
+
+
+def grade_key_stage(label: str) -> int | None:
+    """Return the key-stage number for a grade label."""
+
+    grade = grade_spec(label)
+    return grade.key_stage if grade is not None else None
+
+
+def school_grades_frame(
+    grades: Iterable[GradeSpec] = SCHOOL_GRADES,
+    *,
+    include_id: bool = True,
+) -> pl.DataFrame:
+    """Return school grade mappings as a Polars dataframe."""
+
+    frame = pl.DataFrame([asdict(grade) for grade in grades])
+    if include_id:
+        return frame.with_row_index(name="id", offset=1)
+    return frame
+
+
+__all__ = [
+    "SCHOOL_GRADES",
+    "SCHOOL_GRADES_BY_LABEL",
+    "GradeSpec",
+    "grade_key_stage",
+    "grade_spec",
+    "school_grades_frame",
+]