parseo 0.4.4__py3-none-any.whl

parseo/__init__.py

@@ -0,0 +1,53 @@
+"""Top level package for parseo."""
+
+from importlib import metadata
+from .assembler import assemble
+from .assembler import assemble_auto
+from .assembler import clear_schema_cache
+from .parser import parse
+from .parser import parse_auto
+from .parser import validate_schema
+from .schema_registry import get_schema_path
+from .schema_registry import list_schema_families
+from .schema_registry import list_schema_versions
+
+try:  # pragma: no cover - import failure handled for graceful degradation
+    from . import parser  # noqa: F401  # import for side effect and re-export
+except Exception:  # ImportError and others
+    parser = None
+
+
+try:  # pragma: no cover - gracefully handle missing distribution
+    __version__ = metadata.version("parseo")
+except metadata.PackageNotFoundError:  # pragma: no cover - defensive
+    __version__ = "unknown"
+
+
+def info() -> dict[str, str]:
+    """Return information about the installed :mod:`parseo` package.
+
+    Returns
+    -------
+    dict[str, str]
+        A dictionary containing the installed version under the ``"version"`` key.
+    """
+
+    return {"version": __version__}
+
+
+__all__ = [
+    "parse",
+    "parse_auto",
+    "assemble",
+    "assemble_auto",
+    "clear_schema_cache",
+    "validate_schema",
+    "list_schema_families",
+    "list_schema_versions",
+    "get_schema_path",
+    "info",
+    "__version__",
+]
+
+if parser is not None:
+    __all__.append("parser")

parseo/_epsg_lookup.py

@@ -0,0 +1,145 @@
+"""Lookup helpers for deriving EPSG codes from tile identifiers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+from typing import Optional
+
+
+_MGRS_LATITUDE_BANDS = {
+    "C": "south",
+    "D": "south",
+    "E": "south",
+    "F": "south",
+    "G": "south",
+    "H": "south",
+    "J": "south",
+    "K": "south",
+    "L": "south",
+    "M": "south",
+    "N": "north",
+    "P": "north",
+    "Q": "north",
+    "R": "north",
+    "S": "north",
+    "T": "north",
+    "U": "north",
+    "V": "north",
+    "W": "north",
+    "X": "north",
+}
+
+
+def mgrs_tile_to_epsg(tile: str) -> Optional[str]:
+    """Return the EPSG code associated with a Sentinel-2 MGRS tile.
+
+    Parameters
+    ----------
+    tile:
+        The tile identifier (e.g. ``"T32TNS"``).
+    """
+
+    if not isinstance(tile, str) or len(tile) < 4:
+        return None
+
+    tile = tile.strip().upper()
+    if not tile.startswith("T"):
+        return None
+
+    zone_part = tile[1:3]
+    try:
+        zone = int(zone_part)
+    except ValueError:
+        return None
+    if not 1 <= zone <= 60:
+        return None
+
+    band = tile[3]
+    hemisphere = _MGRS_LATITUDE_BANDS.get(band)
+    if hemisphere is None:
+        return None
+
+    if hemisphere == "north":
+        epsg = 32600 + zone
+    else:
+        epsg = 32700 + zone
+
+    return f"{epsg:05d}"
+
+
+@dataclass(frozen=True)
+class _WRSOrbitConstants:
+    """Constants derived from the WRS-2 orbital configuration."""
+
+    orbital_period_days: float = 16.0
+    paths: int = 233
+    rows: int = 248
+    inclination_deg: float = 98.2
+
+
+_WRS_CONSTANTS = _WRSOrbitConstants()
+
+
+def _path_to_longitude(path: int) -> float:
+    """Approximate the longitude of the descending node for *path* (degrees)."""
+
+    fraction = (path - 1) / _WRS_CONSTANTS.paths
+    longitude = (fraction * 360.0) % 360.0
+    if longitude > 180.0:
+        longitude -= 360.0
+    return longitude
+
+
+def _row_to_latitude(row: int) -> float:
+    """Approximate the latitude of the scene centre for *row* (degrees)."""
+
+    # Rows increase from north to south. We approximate the relationship using
+    # a linear fit anchored at the documented WRS limits (81°N and 81°S).
+    total_rows = _WRS_CONSTANTS.rows
+    span = 162.0  # 81°N to 81°S
+    step = span / (total_rows - 1)
+    return 81.0 - (row - 1) * step
+
+
+def landsat_path_row_to_epsg(path: str, row: str) -> Optional[str]:
+    """Return the EPSG code inferred from a Landsat WRS path/row pair."""
+
+    try:
+        path_num = int(path)
+        row_num = int(row)
+    except (TypeError, ValueError):
+        return None
+
+    if not 1 <= path_num <= _WRS_CONSTANTS.paths:
+        return None
+    if not 1 <= row_num <= _WRS_CONSTANTS.rows:
+        return None
+
+    longitude = _path_to_longitude(path_num)
+    latitude = _row_to_latitude(row_num)
+
+    zone = int(math.floor((longitude + 180.0) / 6.0)) + 1
+    zone = max(1, min(zone, 60))
+
+    # Special handling for Norway and Svalbard following the UTM specification.
+    if 56.0 <= latitude < 64.0 and 3.0 <= longitude < 12.0:
+        zone = 32
+    if 72.0 <= latitude <= 84.0:
+        if 0.0 <= longitude < 9.0:
+            zone = 31
+        elif 9.0 <= longitude < 21.0:
+            zone = 33
+        elif 21.0 <= longitude < 33.0:
+            zone = 35
+        elif 33.0 <= longitude < 42.0:
+            zone = 37
+
+    hemisphere = "north" if latitude >= 0.0 else "south"
+    if hemisphere == "north":
+        epsg = 32600 + zone
+    else:
+        epsg = 32700 + zone
+
+    return f"{epsg:05d}"
+

parseo/_field_mappings.py

@@ -0,0 +1,219 @@
+"""Utilities for translating between schema tokens and STAC values."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+from typing import Dict
+from typing import Mapping
+from typing import Optional
+
+from ._epsg_lookup import landsat_path_row_to_epsg
+from ._epsg_lookup import mgrs_tile_to_epsg
+from ._tile_systems import TileSystem
+from ._tile_systems import detect_tile_system
+from ._tile_systems import normalize_tile
+
+
+@dataclass(frozen=True)
+class FieldMapping:
+    """Represents a mapping between a filename token and STAC fields."""
+
+    preserve_as: Optional[str]
+    token_map: Dict[str, Dict[str, Any]]
+
+
+def _normalize_mapping_values(values: Mapping[str, Any]) -> Dict[str, Dict[str, Any]]:
+    normalized: Dict[str, Dict[str, Any]] = {}
+    for token, targets in values.items():
+        if not isinstance(targets, Mapping):
+            continue
+        normalized[str(token)] = {str(k): v for k, v in targets.items()}
+    return normalized
+
+
+def get_schema_field_mappings(schema: Mapping[str, Any]) -> Dict[str, FieldMapping]:
+    """Extract field mappings declared in *schema*."""
+
+    fields = schema.get("fields", {})
+    if not isinstance(fields, Mapping):
+        return {}
+
+    mappings: Dict[str, FieldMapping] = {}
+    for field_name, spec in fields.items():
+        if not isinstance(spec, Mapping):
+            continue
+        raw_map = spec.get("stac_map")
+        if not isinstance(raw_map, Mapping):
+            continue
+
+        has_explicit_values = "values" in raw_map
+        preserve_raw = raw_map.get("preserve_original_as")
+        preserve_as: Optional[str]
+
+        if isinstance(preserve_raw, str):
+            preserve_as = preserve_raw.strip() or None
+        elif isinstance(preserve_raw, bool):
+            preserve_as = f"{field_name}_code" if preserve_raw else None
+        elif preserve_raw is not None:
+            preserve_as = str(preserve_raw).strip() or None
+        else:
+            preserve_as = None if has_explicit_values else f"{field_name}_code"
+
+        values: Any
+        if "values" in raw_map:
+            values = raw_map.get("values")
+        else:
+            values = raw_map
+        if not isinstance(values, Mapping):
+            continue
+
+        normalized = _normalize_mapping_values(values)
+        if not normalized:
+            continue
+
+        mappings[str(field_name)] = FieldMapping(preserve_as=preserve_as, token_map=normalized)
+
+    return mappings
+
+
+def _augment_with_tile_variants(fields: Dict[str, Any]) -> Dict[str, Any]:
+    enriched = dict(fields)
+
+    mgrs_value = enriched.get("mgrs_tile")
+    if isinstance(mgrs_value, str) and mgrs_value and "tile_id" not in enriched:
+        enriched["tile_id"] = mgrs_value
+
+    for candidate in ("tile", "tile_id"):
+        value = enriched.get(candidate)
+        if not isinstance(value, str):
+            continue
+
+        system = detect_tile_system(value)
+        if system is None:
+            continue
+
+        normalized = normalize_tile(value)
+        enriched[candidate] = normalized
+
+        if system is TileSystem.MGRS and "tile_id" not in enriched:
+            enriched["tile_id"] = normalized
+        if system is TileSystem.EEA:
+            if "tile_id" not in enriched:
+                enriched["tile_id"] = normalized
+            if "epsg_code" not in enriched:
+                enriched["epsg_code"] = "03035"
+
+    enriched.pop("mgrs_tile", None)
+    return enriched
+
+
+def _backfill_tile_tokens(
+    fields: Dict[str, Any], schema: Mapping[str, Any]
+) -> Dict[str, Any]:
+    translated = dict(fields)
+    specs = schema.get("fields", {})
+
+    if "tile" in specs and "tile" not in translated:
+        for key in ("tile_id", "mgrs_tile"):
+            value = translated.get(key)
+            if isinstance(value, str) and value:
+                translated["tile"] = normalize_tile(value)
+                break
+
+    if "tile_id" in specs and "tile_id" not in translated:
+        for key in ("tile", "mgrs_tile"):
+            value = translated.get(key)
+            if isinstance(value, str) and value:
+                translated["tile_id"] = normalize_tile(value)
+                break
+
+    translated.pop("mgrs_tile", None)
+    return translated
+
+
+def apply_schema_mappings(
+    extracted: Dict[str, Any], schema: Mapping[str, Any]
+) -> Dict[str, Any]:
+    """Augment *extracted* fields with STAC values defined in *schema*."""
+
+    mappings = get_schema_field_mappings(schema)
+
+    enriched = _augment_with_tile_variants(extracted)
+    for field_name, mapping in mappings.items():
+        token = extracted.get(field_name)
+        if token is None:
+            continue
+
+        if mapping.preserve_as:
+            enriched[mapping.preserve_as] = token
+
+        targets = mapping.token_map.get(str(token))
+        if not isinstance(targets, Mapping):
+            continue
+
+        for target_field, target_value in targets.items():
+            enriched[target_field] = target_value
+
+    schema_id = str(schema.get("schema_id", "")).lower()
+
+    if "epsg_code" not in enriched:
+        tile = enriched.get("tile_id")
+        if (
+            tile
+            and "sentinel:s2" in schema_id
+            and detect_tile_system(str(tile)) is TileSystem.MGRS
+        ):
+            epsg = mgrs_tile_to_epsg(str(tile))
+            if epsg:
+                enriched["epsg_code"] = epsg
+
+    if "epsg_code" not in enriched:
+        path = enriched.get("wrs_path")
+        row = enriched.get("wrs_row")
+        if path and row and schema_id.startswith("usgs:landsat"):
+            epsg = landsat_path_row_to_epsg(str(path), str(row))
+            if epsg:
+                enriched["epsg_code"] = epsg
+
+    return enriched
+
+
+def translate_fields_to_tokens(
+    fields: Dict[str, Any], schema: Mapping[str, Any]
+) -> Dict[str, Any]:
+    """Translate STAC field values in *fields* back to schema tokens."""
+
+    mappings = get_schema_field_mappings(schema)
+    if not mappings:
+        return fields
+
+    translated = _augment_with_tile_variants(fields)
+    for field_name, mapping in mappings.items():
+        token: Any = None
+
+        preserved = None
+        if mapping.preserve_as:
+            preserved = fields.get(mapping.preserve_as)
+            if preserved not in (None, ""):
+                token = str(preserved)
+
+        if token is None:
+            current_value = fields.get(field_name)
+            if isinstance(current_value, str) and current_value in mapping.token_map:
+                token = current_value
+
+        if token is None:
+            for candidate, targets in mapping.token_map.items():
+                if all(fields.get(k) == v for k, v in targets.items()):
+                    token = candidate
+                    break
+
+        if token is None:
+            continue
+
+        translated[field_name] = token
+
+    translated = _backfill_tile_tokens(translated, schema)
+    return translated
+

parseo/_json.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+from typing import Dict
+from typing import Union
+
+
+def load_json(path: Union[str, Path]) -> Dict[str, Any]:
+    """Load a JSON file, handling optional UTF-8 BOM."""
+    p = Path(path)
+    text = p.read_text(encoding="utf-8-sig")
+    return json.loads(text)

parseo/_tile_systems.py

@@ -0,0 +1,51 @@
+"""Helpers for recognizing spatial tile identifier systems."""
+
+from __future__ import annotations
+
+import re
+from enum import Enum
+from typing import Optional
+
+
+class TileSystem(str, Enum):
+    """Known spatial tiling systems."""
+
+    MGRS = "mgrs"
+    EEA = "eea"
+
+
+_MGRS_PATTERN = re.compile(r"^T\d{2}[C-HJ-NP-X][A-Z]{2}$")
+_EEA_PATTERN = re.compile(r"^[EW]\d{2,3}[NS]\d{2,3}$")
+
+
+def detect_tile_system(tile: str) -> Optional[TileSystem]:
+    """Return the :class:`TileSystem` matching *tile*, if any."""
+
+    if not isinstance(tile, str):
+        return None
+
+    candidate = tile.strip().upper()
+    if not candidate:
+        return None
+
+    if _MGRS_PATTERN.fullmatch(candidate):
+        return TileSystem.MGRS
+
+    if _EEA_PATTERN.fullmatch(candidate):
+        return TileSystem.EEA
+
+    return None
+
+
+def normalize_tile(tile: str) -> str:
+    """Return a normalised representation of *tile*.
+
+    MGRS and EEA tiles are uppercased.  Tiles from unrecognised systems
+    (e.g., MODIS sinusoidal ``h18v04``) are returned as-is.
+    """
+
+    t = tile.strip()
+    if detect_tile_system(t):
+        return t.upper()
+    return t
+

parseo/assembler.py

@@ -0,0 +1,225 @@
+# src/parseo/assembler.py
+from __future__ import annotations
+
+from functools import lru_cache
+from importlib.resources import as_file
+from importlib.resources import files
+from pathlib import Path
+import re
+from typing import Any
+from typing import Dict
+from typing import Union
+
+from ._field_mappings import translate_fields_to_tokens
+from .parser import _get_fields_order
+from .parser import _pattern_from_schema
+from .schema_registry import _load_json_from_path
+from .schema_registry import get_schema_path
+from .schema_registry import SCHEMAS_ROOT
+from .template import _field_regex
+from .template import compile_template
+
+
+def clear_schema_cache() -> None:
+    """Clear all cached schema data."""
+    _load_json_from_path.cache_clear()
+    from .parser import _SCHEMA_PATTERN_CACHE, _SCHEMA_ORDER_CACHE
+
+    _SCHEMA_PATTERN_CACHE.clear()
+    _SCHEMA_ORDER_CACHE.clear()
+
+
+def _assemble_from_template(template: str, fields: Dict[str, Any]) -> str:
+    """Render *template* using *fields*.
+
+    Optional segments denoted by ``[ ... ]`` are dropped if any enclosed field
+    is missing. ``{field}`` placeholders are replaced by values from *fields*.
+    """
+
+    def render(segment: str) -> str:
+        result = ""
+        i = 0
+        while i < len(segment):
+            ch = segment[i]
+            if ch == "{":
+                j = segment.index("}", i)
+                name = segment[i + 1 : j]
+                if name not in fields:
+                    raise KeyError(name)
+                result += str(fields[name])
+                i = j + 1
+            elif ch == "[":
+                depth = 1
+                j = i + 1
+                while j < len(segment) and depth:
+                    if segment[j] == "[":
+                        depth += 1
+                    elif segment[j] == "]":
+                        depth -= 1
+                    j += 1
+                inner = segment[i + 1 : j - 1]
+                try:
+                    result += render(inner)
+                except KeyError:
+                    pass
+                i = j
+            else:
+                result += ch
+                i += 1
+        return result
+
+    return render(template)
+
+
+def _assemble_schema(schema_path: Union[str, Path], fields: Dict[str, Any]) -> str:
+    """Assemble a filename using a JSON schema.
+
+    Schemas must define a ``template`` string following parseo's mini-template
+    syntax. The template is rendered using the provided *fields* and optional
+    segments are dropped if any enclosed field is missing.
+    """
+
+    sch = _load_json_from_path(schema_path)
+    prepared_fields = translate_fields_to_tokens(fields, sch)
+
+    template = sch.get("template")
+    if not isinstance(template, str):
+        raise ValueError(f"Schema {schema_path} missing 'template' string.")
+
+    epsg_value = prepared_fields.get("epsg_code")
+    if (
+        isinstance(epsg_value, str)
+        and "EPSG{epsg_code}" in template
+        and epsg_value
+    ):
+        prepared_fields["epsg_code"] = epsg_value.lstrip("0") or "0"
+
+    # Validate provided fields against schema definitions
+    specs = sch.get("fields", {})
+    for name, value in prepared_fields.items():
+        spec = specs.get(name)
+        if not spec:
+            continue
+        if "enum" in spec and str(value) not in spec["enum"]:
+            raise ValueError(
+                f"Field '{name}' must be one of {spec['enum']}, got {value!r}."
+            )
+        if "pattern" in spec:
+            pattern = _field_regex({"pattern": spec["pattern"]})
+            regex = re.compile(f"^{pattern}$")
+            if not regex.match(str(value)):
+                raise ValueError(
+                    f"Field '{name}' with value {value!r} does not match pattern {spec['pattern']}."
+                )
+
+    try:
+        return _assemble_from_template(template, prepared_fields)
+    except KeyError as exc:
+        name = exc.args[0]
+        raise ValueError(
+            f"Missing field '{name}' for schema {schema_path}"
+        ) from exc
+
+
+def assemble(
+    fields: Dict[str, Any],
+    family: Union[str, None] = None,
+    version: Union[str, None] = None,
+    schema_path: Union[str, Path, None] = None,
+) -> str:
+    """Assemble a filename from *fields*.
+
+    Provide either a *schema_path* or a schema *family* (with optional
+    *version*) to select the schema. If neither is given the schema is
+    auto-selected based on the supplied *fields*.
+    """
+
+    if schema_path is not None:
+        return _assemble_schema(schema_path, fields)
+    if family is not None:
+        resolved = get_schema_path(family, version=version)
+        return _assemble_schema(resolved, fields)
+    return assemble_auto(fields)
+
+
+def _iter_schema_paths() -> list[Path]:
+    """Return all packaged schema JSON paths."""
+    base = files(__package__).joinpath(SCHEMAS_ROOT)
+    with as_file(base) as bp:
+        root = Path(bp)
+        return list(root.rglob("*.json"))
+
+
+def _select_schema_by_first_compulsory(fields: Dict[str, Any]) -> Path:
+    """Select the most appropriate schema based on provided fields.
+
+    Eligibility requires the user to provide the first compulsory field as
+    derived from the schema's template. Among eligible schemas the one with the
+    largest overlap of provided keys is chosen. A longer field order acts as a
+    tie breaker.
+    """
+    best: Union[tuple[int, int, str], None] = None
+    best_path: Union[Path, None] = None
+    seen_first_keys: set[str] = set()
+
+    for p in _iter_schema_paths():
+        try:
+            sch = _load_json_from_path(p)
+        except (OSError, ValueError):
+            continue
+
+        template = sch.get("template")
+        if not isinstance(template, str):
+            continue
+        _pattern_from_schema(sch)
+        order = _get_fields_order(sch)
+        if not order:
+            continue
+
+        specs = sch.get("fields", {})
+        first_key = None
+        for name in order:
+            spec = specs.get(name, {})
+            enums = spec.get("enum")
+            field_val = fields.get(name)
+            if enums is not None:
+                enums = [str(e) for e in enums]
+                if len(enums) == 1 and field_val == enums[0]:
+                    continue
+                if field_val is not None and field_val not in enums:
+                    first_key = None
+                    break
+                first_key = name
+                break
+            else:
+                first_key = name
+                break
+        if not first_key:
+            continue
+
+        seen_first_keys.add(first_key)
+
+        if first_key not in fields:
+            continue
+
+        overlap = sum(1 for k in fields.keys() if k in order)
+        key = (overlap, len(order), str(p))
+        if best is None or key > best:
+            best = key
+            best_path = p
+
+    if not best_path:
+        sample = ", ".join(sorted(seen_first_keys)) or "<no schemas found>"
+        raise ValueError(
+            "Could not select a schema. "
+            "Include the schema's FIRST compulsory field among your inputs.\n"
+            f"Examples of first fields from packaged schemas: {sample}"
+        )
+
+    return best_path
+
+
+def assemble_auto(fields: Dict[str, Any]) -> str:
+    """Assemble a filename by auto-selecting the appropriate schema."""
+    schema_path = _select_schema_by_first_compulsory(fields)
+    return _assemble_schema(str(schema_path), fields)