parseo 0.4.4__py3-none-any.whl

parseo/schema_registry.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import field
+from functools import lru_cache
+from importlib.resources import as_file
+from importlib.resources import files
+from pathlib import Path
+import re
+from types import MappingProxyType
+from typing import Any
+from typing import Dict
+from typing import Iterator
+from typing import Mapping
+from typing import Optional
+from typing import Union
+
+from ._json import load_json
+
+SCHEMAS_ROOT = "schemas"
+
+_FAMILY_ALIASES: Dict[str, str] = {
+    "IMP": "IMPERVIOUSNESS",
+    "SWF": "SMALL-WOODY-FEATURES",
+    "VI": "VEGETATION-INDEX",
+}
+
+_FAMILY_SYNONYMS: Dict[str, str] = {v: k for k, v in _FAMILY_ALIASES.items()}
+
+
+def _normalize_family_name(family: str) -> str:
+    fam = family.upper()
+    if ":" in fam:
+        fam = fam.split(":")[-1]
+    return _FAMILY_SYNONYMS.get(fam, fam)
+
+
+def to_display_family(family: Optional[str]) -> Optional[str]:
+    if family is None:
+        return None
+    return _FAMILY_ALIASES.get(family, family)
+
+
+@lru_cache(maxsize=256)
+def _load_json_from_path(path: Path) -> Dict:
+    return load_json(path)
+
+
+def _iter_schema_paths(pkg: str) -> Iterator[Path]:
+    """Yield all schema JSON files recursively for *pkg*."""
+    root = files(pkg).joinpath(SCHEMAS_ROOT)
+    with as_file(root) as root_path:
+        base = Path(root_path)
+        if not base.exists():
+            return
+        yield from (p for p in base.rglob("*filename_v*.json") if p.is_file())
+
+
+@lru_cache(maxsize=32)
+def _get_schema_paths(pkg: str) -> list[Path]:
+    return list(_iter_schema_paths(pkg))
+
+
+def _family_tokens_from_name(family: str) -> tuple[str, ...]:
+    fam = family.upper()
+    tokens = {fam}
+    m = re.fullmatch(r"S(\d+)([A-Z]*)", fam)
+    if m:
+        num, suffix = m.groups()
+        tokens.add(f"SENTINEL-{num}{suffix}")
+    return tuple(tokens)
+
+
+@dataclass(frozen=True)
+class _FamilyInfo:
+    """Metadata about a mission family discovered from schema files."""
+
+    schema_id: str
+    tokens: tuple[str, ...]
+    schema_path: Path
+    version: Optional[str] = None
+    status: Optional[str] = None
+    versions: Mapping[str, tuple[Path, Optional[str]]] = field(default_factory=dict)
+
+
+@lru_cache(maxsize=1)
+def _discover_family_info(pkg: str) -> Dict[str, _FamilyInfo]:
+    """Scan schema JSON files to discover mission families and versions."""
+
+    families: Dict[str, dict[str, Any]] = {}
+    for path in _get_schema_paths(pkg):
+        if "filename_v" not in path.name:
+            continue
+        try:
+            data = _load_json_from_path(path)
+        except (OSError, ValueError):
+            continue
+        schema_id = data.get("schema_id")
+        version = data.get("schema_version")
+        status = data.get("status", "current")
+        if not isinstance(schema_id, str) or not isinstance(version, str):
+            continue
+        family = schema_id.split(":")[-1].upper()
+        fam_entry = families.setdefault(
+            family,
+            {
+                "schema_id": schema_id,
+                "versions": {},
+            },
+        )
+        if not isinstance(fam_entry.get("schema_id"), str):
+            fam_entry["schema_id"] = schema_id
+        versions = fam_entry.setdefault("versions", {})
+        if not isinstance(versions, dict):
+            versions = {}
+            fam_entry["versions"] = versions
+        versions[version] = (path, status)
+
+    info: Dict[str, _FamilyInfo] = {}
+
+    for family, payload in families.items():
+        versions = payload.get("versions", {})
+        if not isinstance(versions, dict):
+            continue
+        current_version = None
+        current_path = None
+        current_status = None
+        for ver, (p, st) in sorted(versions.items(), reverse=True):
+            if st == "current":
+                current_version = ver
+                current_path = p
+                current_status = st
+                break
+        if current_path is None:
+            available = ", ".join(sorted(versions))
+            raise RuntimeError(
+                f"No schema version marked as 'current' for family {family}. "
+                f"Available versions: {available}"
+            )
+        schema_id = payload.get("schema_id")
+        if not isinstance(schema_id, str):
+            continue
+        info[family] = _FamilyInfo(
+            schema_id=schema_id,
+            tokens=_family_tokens_from_name(family),
+            schema_path=current_path,
+            version=current_version,
+            status=current_status,
+            versions=MappingProxyType(versions),
+        )
+    return info
+
+
+def discover_families(pkg: str = __package__) -> Dict[str, dict]:
+    """Return mapping of family name to version metadata."""
+
+    info = _discover_family_info(pkg)
+    out: Dict[str, dict] = {}
+    for fam, meta in info.items():
+        out[fam] = {
+            "schema_id": meta.schema_id,
+            "current": meta.version,
+            "path": meta.schema_path,
+            "versions": {
+                ver: {"path": p, "status": st} for ver, (p, st) in meta.versions.items()
+            },
+        }
+    return out
+
+
+def list_schema_families(pkg: str = __package__) -> list[str]:
+    """Return a sorted list of available mission families."""
+
+    families = discover_families(pkg)
+    names = set(families.keys())
+    for canonical in list(names):
+        display = to_display_family(canonical)
+        if display and display != canonical:
+            names.add(display)
+    return sorted(names)
+
+
+def list_schema_versions(family: str, pkg: str = __package__) -> list[dict]:
+    """Return version descriptors for *family*."""
+
+    fam = _normalize_family_name(family)
+    info = discover_families(pkg)
+    meta = info.get(fam)
+    if meta is None:
+        raise KeyError(f"Unknown family: {family}")
+    versions = []
+    for ver, data in sorted(meta["versions"].items()):
+        versions.append(
+            {
+                "version": ver,
+                "status": data.get("status"),
+                "file": str(data.get("path")),
+            }
+        )
+    return versions
+
+
+@lru_cache(maxsize=256)
+def get_schema_path(
+    family: str, version: Union[str, None] = None, pkg: str = __package__
+) -> Path:
+    """Return filesystem path to schema for *family* and *version*.
+
+    If *version* is ``None`` the schema version marked as ``current`` is used.
+    """
+
+    fam = _normalize_family_name(family)
+    info = _discover_family_info(pkg)
+    meta = info.get(fam)
+    if meta is None:
+        raise KeyError(f"Unknown family: {family}")
+
+    if version is None:
+        return meta.schema_path
+
+    path_status = meta.versions.get(version)
+    if path_status is None:
+        avail = ", ".join(sorted(meta.versions))
+        raise KeyError(
+            f"Version {version!r} not found for family {family}. Available: {avail}"
+        )
+    path, _status = path_status
+    return path
+
+
+def clear_cache() -> None:
+    """Clear internal caches used by the schema registry.
+
+    This helper is primarily intended for tests that need to add or modify
+    schema files at runtime.
+    """
+
+    _load_json_from_path.cache_clear()
+    _get_schema_paths.cache_clear()
+    _discover_family_info.cache_clear()
+    # Also clear per-schema pattern caches stored in parser module
+    from . import parser as _parser
+
+    _parser._SCHEMA_PATTERN_CACHE.clear()
+    _parser._SCHEMA_ORDER_CACHE.clear()
+    get_schema_path.cache_clear()

parseo/schemas/copernicus/clms/clc/clc_filename_v1_0_0.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "schema_id": "copernicus:clms:clc",
+  "schema_version": "1.0.0",
+  "status": "deprecated",
+  "description": "Corine Land Cover product filename (extension optional).",
+  "fields": {
+    "project": {
+      "type": "string",
+      "enum": [
+        "CLC",
+        "U"
+      ],
+      "description": "Project code"
+    },
+    "reference_year": {
+      "type": "string",
+      "pattern": "^\\d{4}$",
+      "description": "Reference year (e.g., 2018, 2012)"
+    },
+    "product": {
+      "type": "string",
+      "pattern": "^[A-Z0-9]+$",
+      "description": "Product name, often CLCYYYY or change token"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^V\\d{4}$",
+      "description": "Product version (e.g., V2020)"
+    },
+    "release_number": {
+      "type": "string",
+      "pattern": "^\\d{2}(?:[A-Za-z]\\d+)?$",
+      "description": "Release identifier (e.g., 20, 20b2, 20u1)."
+    },
+    "extension": {
+      "type": "string",
+      "enum": [
+        "tif"
+      ],
+      "description": "File extension without leading dot"
+    }
+  },
+  "template": "{project}{reference_year}_{product}_{version}_{release_number}[.{extension}]",
+  "examples": [
+    "CLC2018_CLC2018_V2020_20u1.tif"
+  ]
+}

parseo/schemas/copernicus/clms/clc/clc_filename_v1_1_0.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "schema_id": "copernicus:clms:clc",
+  "schema_version": "1.1.0",
+  "status": "current",
+
+  "description": "Corine Land Cover filename (status and change layers, extension optional).",
+  "fields": {
+    "update_campaign": {
+      "type": "string",
+      "pattern": "^U\\d{4}$",
+      "description": "Year of the CLC update campaign (YYYY)."
+    },
+    "product": {
+      "type": "string",
+      "enum": [
+        "CLC",
+        "CHA"
+      ],
+      "description": "Layer theme: CLC for status layers, CHA for change layers."
+    },
+    "reference_code": {
+      "type": "string",
+      "pattern": "^\\d{4}$",
+      "description": "Reference year (status) or two-year span code (change)."
+    },
+    "change_component": {
+      "type": "string",
+      "pattern": "^(?:12|18)$",
+      "description": "Change raster component: 12 for consumption, 18 for formation."
+    },
+    "release_year": {
+      "type": "string",
+      "pattern": "^V\\d{4}$",
+      "description": "Year of data release (YYYY)."
+    },
+    "release_number": {
+      "type": "string",
+      "pattern": "^\\d{2}(?:[A-Za-z]\\d+)?$",
+      "description": "Release identifier (e.g., 20, 20b2, 20u1)."
+    },
+    "country_code": {
+      "type": "string",
+      "pattern": "^[A-Z]{2}$",
+      "description": "ISO 3166-1 alpha-2 country code for overseas deliveries."
+    },
+    "dom_code": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}$",
+      "description": "DOM (overseas department) code used with country_code."
+    },
+    "extension": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9]+$",
+      "description": "File extension without leading dot."
+    }
+  },
+  "template": "{update_campaign}_{product}{reference_code}[_{change_component}]_{release_year}_{release_number}[_{country_code}_{dom_code}][.{extension}]",
+  "examples": [
+    "U2006_CLC2000_V2018_20b2.zip",
+    "U2018_CHA1218_V2020_20u1.tif",
+    "U2018_CHA1218_12_V2020_20u1.tif",
+    "U2006_CLC2000_V2018_20b2_FR_GLP.zip"
+  ]
+}

parseo/schemas/copernicus/clms/clcplus/ras/clcplus_filename_v0_0_0.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "schema_id": "copernicus:clms:clcplus",
+  "schema_version": "0.0.0",
+  "status": "deprecated",
+  "stac_version": "1.1.0",
+  "stac_extensions": [
+    "https://stac-extensions.github.io/raster/v1.0.0/schema.json",
+    "https://stac-extensions.github.io/eo/v1.0.0/schema.json"
+  ],
+  "description": "CLMS CLC+ raster product filename (extension optional).",
+  "fields": {
+    "programme": {
+      "type": "string",
+      "enum": [
+        "CLMS"
+      ],
+      "description": "Copernicus Land Monitoring Service programme identifier"
+    },
+    "product": {
+      "type": "string",
+      "enum": [
+        "CLCPLUS"
+      ],
+      "description": "Product family identifier"
+    },
+    "type": {
+      "type": "string",
+      "enum": [
+        "RASTER"
+      ],
+      "description": "Data class code (raster)",
+      "stac_map": {
+        "values": {
+          "RAS": {
+            "type": "raster"
+          }
+        }
+      }
+    },
+    "season": {
+      "type": "string",
+      "pattern": "^(\\d{4}|C\\d{4}-\\d{4})$",
+      "description": "Reference season and year (SYYYY) or change interval (CYYYY-YYYY)"
+    },
+    "resolution": {
+      "type": "string",
+      "pattern": "^\\d{3}m$",
+      "description": "Spatial resolution expressed with leading 'R' and units"
+    },
+    "tile_id": {
+      "description": "Tile identifier in the EEA 10m grid (easting/northing) or two-letter geographic code",
+      "oneOf": [
+        {
+          "title": "INSPIRE ETRS89-LAEA Grid",
+          "type": "string",
+          "pattern": "^[EW]\\d{2,3}[NS]\\d{2,3}$",
+          "description": "Regional LAEA grid tile identifier (2- or 3-digit coordinates)"
+        },
+        {
+          "title": "Geographic code",
+          "type": "string",
+          "pattern": "^[A-Z]{2}$",
+          "description": "Two-letter geographic code used by VLCC vector products"
+        }
+      ]
+    },
+    "epsg_code": {
+      "type": "string",
+      "pattern": "^0?\\d{4}$",
+      "description": "EPSG code of the product grid"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^V\\d{1}_\\d{1}$",
+      "description": "Product version"
+    },
+    "extension": {
+      "type": "string",
+      "enum": [
+        "tif"
+      ],
+      "description": "File extension without leading dot"
+    }
+  },
+  "template": "{programme}_{product}_{type}_{season}_{resolution}_{tile_id}_{epsg_code}_{version}[.{extension}]",
+  "examples": [
+    "CLMS_CLCPLUS_RASTER_2018_010m_E48N37_03035_V1_1.tif"
+  ]
+}

parseo/schemas/copernicus/clms/clcplus/ras/clcplus_filename_v0_0_1.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "schema_id": "copernicus:clms:clcplus",
+  "schema_version": "0.0.1",
+  "status": "current",
+  "stac_version": "1.1.0",
+  "description": "CLMS CLC+ raster product filename (extension optional).",
+  "fields": {
+    "programme": {
+      "type": "string",
+      "enum": [
+        "CLMS"
+      ],
+      "description": "Copernicus Land Monitoring Service programme identifier"
+    },
+    "product": {
+      "type": "string",
+      "enum": [
+        "CLCPLUS"
+      ],
+      "description": "Product family identifier"
+    },
+    "type": {
+      "type": "string",
+      "enum": [
+        "RAS"
+      ],
+      "description": "Data class code (raster)",
+      "stac_map": {
+        "values": {
+          "RAS": {
+            "representation": "raster"
+          }
+        }
+      }
+    },
+    "season": {
+      "type": "string",
+      "pattern": "^(S\\d{4}|C\\d{4}-\\d{4})$",
+      "description": "Reference season and year (SYYYY) or change interval (CYYYY-YYYY)"
+    },
+    "resolution": {
+      "type": "string",
+      "pattern": "^R\\d{2}m$",
+      "description": "Spatial resolution expressed with leading 'R' and units"
+    },
+    "tile_id": {
+      "title": "INSPIRE ETRS89-LAEA Grid",
+      "type": "string",
+      "pattern": "^[EW]\\d{2,3}[NS]\\d{2,3}$",
+      "description": "Regional LAEA grid tile identifier (2- or 3-digit coordinates)"
+    },
+    "epsg_code": {
+      "type": "string",
+      "pattern": "^0?\\d{4}$",
+      "description": "EPSG code of the product grid"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^V\\d{2}$",
+      "description": "Product version"
+    },
+    "revision": {
+      "type": "string",
+      "pattern": "^R\\d{2}$",
+      "description": "Product revision"
+    },
+    "extension": {
+      "type": "string",
+      "enum": [
+        "tif"
+      ],
+      "description": "File extension without leading dot"
+    }
+  },
+  "template": "{programme}_{product}_{type}_{season}_{resolution}_{tile_id}_{epsg_code}_{version}_{revision}[.{extension}]",
+  "examples": [
+    "CLMS_CLCPLUS_RAS_S2023_R10m_E48N37_03035_V01_R00.tif"
+  ]
+}

parseo/schemas/copernicus/clms/egms/egms_gnss_model_filename_v0_0_0.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "schema_id": "copernicus:clms:egms-gnss-model",
+  "schema_version": "0.0.0",
+  "status": "current",
+
+  "description": "Copernicus European Ground Motion Service GNSS model filename.",
+  "fields": {
+    "product": {
+      "type": "string",
+      "enum": [
+        "EGMS"
+      ],
+      "description": "Constant service prefix"
+    },
+    "variable": {
+      "type": "string",
+      "enum": [
+        "AEPND"
+      ],
+      "description": "Product identifier"
+    },
+    "issue_year": {
+      "type": "string",
+      "pattern": "^V\\d{4}$",
+      "description": "Year of issue"
+    },
+    "revision": {
+      "type": "string",
+      "pattern": "^\\d$",
+      "description": "Revision within the year (0 pre-release, 1 first full release)"
+    },
+    "extension": {
+      "type": "string",
+      "enum": [
+        "csv"
+      ],
+      "description": "File extension without leading dot"
+    }
+  },
+  "template": "{product}_{variable}_{issue_year}.{revision}.{extension}",
+  "examples": [
+    "EGMS_AEPND_V2020.0.csv",
+    "EGMS_AEPND_V2023.1.csv"
+  ]
+}

parseo/schemas/copernicus/clms/egms/egms_l2a_product_filename_v0_0_0.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "schema_id": "copernicus:clms:egms-l2a",
+  "schema_version": "0.0.0",
+  "status": "current",
+
+  "description": "Copernicus European Ground Motion Service Level 2 basic and calibrated product filename (extension optional).",
+  "fields": {
+    "product": {
+      "type": "string",
+      "enum": [
+        "EGMS"
+      ],
+      "description": "Constant service prefix"
+    },
+    "level": {
+      "type": "string",
+      "pattern": "^L[0-9]+[a-zA-Z]$",
+      "description": "Product processing level"
+    },
+    "track": {
+      "type": "string",
+      "pattern": "^\\d{3}$",
+      "description": "Sentinel-1 track number"
+    },
+    "burst": {
+      "type": "string",
+      "pattern": "^\\d{4}$",
+      "description": "Progressive index of the burst inside the track"
+    },
+    "swath": {
+      "type": "string",
+      "pattern": "^IW[0-9]$",
+      "description": "Sentinel-1 IW swath identifier"
+    },
+    "polarisation": {
+      "type": "string",
+      "pattern": "^(?:VV|VH|HH|HV)$",
+      "description": "Polarisation of the SAR acquisition"
+    },
+    "start_year": {
+      "type": "string",
+      "pattern": "^\\d{4}$",
+      "description": "First nominal year included in the product"
+    },
+    "end_year": {
+      "type": "string",
+      "pattern": "^\\d{4}$",
+      "description": "Last nominal year included in the product"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+$",
+      "description": "Version of the delivered data"
+    },
+    "extension": {
+      "type": "string",
+      "enum": [
+        "csv",
+        "zip"
+      ],
+      "description": "File extension without leading dot"
+    }
+  },
+  "template": "{product}_{level}_{track}_{burst}_{swath}_{polarisation}_{start_year}_{end_year}_{version}[.{extension}]",
+  "examples": [
+    "EGMS_L2a_088_0282_IW2_VV_2018_2022_1.csv",
+    "EGMS_L2a_088_0282_IW2_VV_2018_2022_1.zip",
+    "EGMS_L2a_124_0135_IW1_VH_2015_2020_2.csv"
+  ]
+}