spacescans 0.3.0__py3-none-any.whl

spacescans/__init__.py

@@ -0,0 +1,42 @@
+"""spacescans — environmental exposure linkage pipeline."""
+from __future__ import annotations
+import sys
+
+if sys.version_info < (3, 10):
+    raise ImportError(
+        f"spacescans requires Python 3.10+, got "
+        f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}."
+    )
+
+# Single source of truth is pyproject.toml; read it back via package metadata
+# so the version never drifts between the two files.
+from importlib.metadata import version as _pkg_version, PackageNotFoundError
+
+# The distribution is "spacescans" since 0.3.0 (it was "spacescans-pipeline" before its first
+# PyPI release); an environment installed before the rename still has the old metadata.
+for _dist in ("spacescans", "spacescans-pipeline"):
+    try:
+        __version__ = _pkg_version(_dist)
+        break
+    except PackageNotFoundError:
+        continue
+else:  # running from a source tree that isn't installed
+    __version__ = "0.0.0+local"
+del _dist
+
+# Lazy public re-exports — imported on attribute access to keep base install
+# import-light (avoids touching pipeline/runner.py until needed).
+def __getattr__(name: str):
+    if name == "Pipeline":
+        from spacescans.pipeline.runner import Pipeline
+        return Pipeline
+    if name == "resolve_config":
+        from spacescans.config_resolution import resolve_config
+        return resolve_config
+    if name == "capabilities":
+        from spacescans._capabilities import capabilities
+        return capabilities
+    raise AttributeError(f"module 'spacescans' has no attribute {name!r}")
+
+
+__all__ = ["Pipeline", "resolve_config", "capabilities", "__version__"]

spacescans/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m spacescans` — the same CLI as the `spacescans` console script."""
+import sys
+
+from spacescans.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

spacescans/_capabilities.py

@@ -0,0 +1,233 @@
+"""What this spacescans install is and what it can run.
+
+``capabilities()`` replaces the probes clients used to need (reading module
+source for the word "output_grouping", poking at private registries). It is
+cheap enough to call once per client session.
+
+Module level imports the standard library only: the R package's wheel build
+script imports ``fingerprint_wheel`` from a bare source tree.
+"""
+from __future__ import annotations
+
+import functools
+import hashlib
+import importlib
+import importlib.metadata
+import importlib.util
+import os
+import platform
+import sys
+import zipfile
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+# The extras declared in pyproject.toml and the modules each one must provide.
+EXTRAS: dict[str, tuple[str, ...]] = {
+    "geo": ("geopandas", "rasterio", "shapely", "exactextract"),
+    "rda": ("pyreadr",),
+    "hdf4": ("pyhdf",),
+    "nc": ("xarray", "netCDF4"),
+}
+
+# Behaviour flags clients may test instead of version numbers.
+FLAGS: dict[str, bool] = {
+    "episode_grouping": True,        # time.output_grouping = "episode" (0.2.x)
+    "config_from_dict": True,        # load_config_dict / Pipeline.from_dict
+    "engine_options": True,          # engine.threads / memory_limit / temp_directory
+    "unavailable_pattern_error": True,  # registry raises UnavailablePatternError
+    # output_level ("participant" | "episode") in orchestrate.link, render_config, RunContext,
+    # the merge functions and the bridge's link; participant means in every C4 pattern (0.3)
+    "output_level": True,
+    "fara_missing_skip": True,       # FARA leaves tracts without a value out of the buffer mean (0.3)
+}
+
+_DISTRIBUTIONS = (
+    "spacescans", "pydantic", "pyyaml", "pandas", "numpy", "duckdb", "pyarrow",
+    "mercantile", "geopandas", "rasterio", "shapely", "exactextract", "pyogrio", "pyproj",
+    "pyreadr", "pyhdf", "xarray", "netCDF4",
+)
+
+
+def fingerprint_entries(entries: Iterable[tuple[str, bytes]]) -> str:
+    """Hash (relative path, content) pairs into ``"sha256:<hex>"``.
+
+    Paths are POSIX, relative to the ``spacescans`` package directory. Order
+    does not matter: entries are sorted by path first.
+    """
+    h = hashlib.sha256()
+    for rel, data in sorted(entries, key=lambda e: e[0]):
+        h.update(rel.encode("utf-8"))
+        h.update(b"\0")
+        h.update(hashlib.sha256(data).digest())
+        h.update(b"\n")
+    return "sha256:" + h.hexdigest()
+
+
+def _package_root() -> Path:
+    return Path(__file__).resolve().parent
+
+
+@functools.cache
+def code_fingerprint(root: str | os.PathLike | None = None) -> str:
+    """Fingerprint of every ``.py`` file under the installed ``spacescans`` package.
+
+    Detects editable or stale installs whose metadata version does not match
+    the code that actually runs.
+    """
+    base = Path(root) if root is not None else _package_root()
+    entries = []
+    for path in base.rglob("*.py"):
+        if "__pycache__" in path.parts:
+            continue
+        entries.append((path.relative_to(base).as_posix(), path.read_bytes()))
+    return fingerprint_entries(entries)
+
+
+def fingerprint_wheel(wheel: str | os.PathLike) -> str:
+    """The code fingerprint the given wheel will have once installed."""
+    entries = []
+    with zipfile.ZipFile(wheel) as zf:
+        for name in zf.namelist():
+            if name.startswith("spacescans/") and name.endswith(".py"):
+                entries.append((name[len("spacescans/"):], zf.read(name)))
+    return fingerprint_entries(entries)
+
+
+def extras_status() -> dict[str, dict[str, Any]]:
+    """For each extra: whether all its modules are importable, and which are missing."""
+    out = {}
+    for extra, modules in EXTRAS.items():
+        missing = [m for m in modules if importlib.util.find_spec(m) is None]
+        out[extra] = {"available": not missing, "missing": missing}
+    return out
+
+
+def package_versions() -> dict[str, str | None]:
+    """Installed versions of spacescans and its (optional) dependencies, None if absent."""
+    out: dict[str, str | None] = {}
+    for dist in _DISTRIBUTIONS:
+        try:
+            out[dist] = importlib.metadata.version(dist)
+        except importlib.metadata.PackageNotFoundError:
+            out[dist] = None
+    return out
+
+
+def native_versions() -> dict[str, str | None]:
+    """GDAL / GEOS / PROJ versions as the Python bindings see them (None if unavailable)."""
+    probes = {
+        "gdal": ("rasterio", "__gdal_version__"),
+        "gdal_pyogrio": ("pyogrio", "__gdal_version_string__"),
+        "geos": ("shapely", "geos_version_string"),
+        "proj": ("pyproj", "proj_version_str"),
+    }
+    out: dict[str, str | None] = {}
+    for key, (module, attr) in probes.items():
+        if importlib.util.find_spec(module) is None:
+            out[key] = None
+            continue
+        try:
+            out[key] = str(getattr(importlib.import_module(module), attr))
+        except Exception as e:  # a broken binary wheel must not break capabilities()
+            out[key] = f"error: {type(e).__name__}: {e}"
+    return out
+
+
+def platform_info() -> dict[str, Any]:
+    mac = platform.mac_ver()[0] or None
+    return {
+        "system": platform.system(),
+        "release": platform.release(),
+        "machine": platform.machine(),
+        "macos": mac,
+        "platform": platform.platform(),
+    }
+
+
+def python_info() -> dict[str, Any]:
+    return {
+        "version": platform.python_version(),
+        "implementation": platform.python_implementation(),
+        "executable": sys.executable,
+        "prefix": sys.prefix,
+    }
+
+
+def catalog_fingerprint(hashes: dict[str, str] | None = None) -> str:
+    """``"sha256:<hex>"`` over the packaged catalog templates.
+
+    Built from ``catalog.template_hashes()`` ({relpath: sha256 hex}) the same
+    way as :func:`fingerprint_entries` builds the code fingerprint, so it
+    equals ``fingerprint_entries((rel, template_bytes(rel)) ...)``. Two
+    installs with the same value render the same pipeline YAMLs.
+    """
+    if hashes is None:
+        from spacescans import catalog
+        hashes = catalog.template_hashes()
+    h = hashlib.sha256()
+    for rel in sorted(hashes):
+        h.update(rel.encode("utf-8"))
+        h.update(b"\0")
+        h.update(bytes.fromhex(hashes[rel]))
+        h.update(b"\n")
+    return "sha256:" + h.hexdigest()
+
+
+def catalog_info() -> dict[str, Any]:
+    """The catalog this install ships: template fingerprint and counts, file hashes."""
+    from importlib import resources
+
+    from spacescans import catalog
+
+    def file_sha(name: str) -> str:
+        return hashlib.sha256(resources.files("spacescans.catalog").joinpath(name).read_bytes()).hexdigest()
+
+    hashes = catalog.template_hashes()
+    return {
+        "hash": catalog_fingerprint(hashes),
+        "templates": len(hashes),
+        "variables": len(catalog.variables()),
+        "experiments": catalog.experiments(),
+        "variables_sha256": file_sha("variables.json"),
+        "features_sha256": file_sha("features.json"),
+    }
+
+
+def data_release() -> str | None:
+    """The data release the packaged data manifest describes (``manifest.json``)."""
+    from spacescans.data.manifest import load_manifest
+
+    return load_manifest().data_release
+
+
+def _guarded(fn) -> Any:
+    try:
+        return fn()
+    except Exception as e:  # a broken catalog or manifest must not break capabilities()
+        return {"error": f"{type(e).__name__}: {e}"}
+
+
+def capabilities() -> dict[str, Any]:
+    """Version, code fingerprint, extras, registered patterns, native libraries,
+    the catalog fingerprint and the data release."""
+    import spacescans
+    from spacescans.pipeline import registry
+
+    release = _guarded(data_release)
+    return {
+        "spacescans": {
+            "version": spacescans.__version__,
+            "code_fp": code_fingerprint(),
+            "path": str(_package_root()),
+        },
+        "python": python_info(),
+        "platform": platform_info(),
+        "extras": extras_status(),
+        "registry": registry.available(),
+        "flags": dict(FLAGS),
+        "versions": package_versions(),
+        "native": native_versions(),
+        "catalog": _guarded(catalog_info),
+        "data_release": release if isinstance(release, str) else None,
+    }

spacescans/_extras.py

@@ -0,0 +1,65 @@
+# src/spacescans/_extras.py
+"""Optional extras gating: clean errors when a feature needs `pip install [extra]`."""
+from __future__ import annotations
+import importlib.util
+from typing import Sequence
+
+INSTALL_DOCS_URL = "https://github.com/IU-Ultraman/spacescans#optional-extras"
+
+# Which pip extra provides each optional third-party module. Used to explain an
+# import failure that was not raised through `require()` (a bare
+# ModuleNotFoundError from a module-level import).
+EXTRA_FOR_MODULE = {
+    "geopandas": "geo",
+    "rasterio": "geo",
+    "shapely": "geo",
+    "exactextract": "geo",
+    "pyogrio": "geo",
+    "pyproj": "geo",
+    "pyreadr": "rda",
+    "pyhdf": "hdf4",
+    "xarray": "nc",
+    "netCDF4": "nc",
+}
+
+
+class MissingExtraError(ImportError):
+    """Raised when an optional extra is needed but not installed.
+
+    ``extra`` names the pip extra (for example ``"geo"``) and ``missing`` lists
+    the modules that could not be imported, when known. Both are optional so
+    ``MissingExtraError("message")`` keeps working.
+    """
+
+    def __init__(self, *args, extra: str | None = None, missing: Sequence[str] = (), **kwargs):
+        super().__init__(*args, **kwargs)
+        self.extra = extra
+        self.missing = tuple(missing)
+
+
+def extra_for_module(name: str | None) -> str | None:
+    """Return the pip extra that provides top-level module ``name`` (or None)."""
+    if not name:
+        return None
+    return EXTRA_FOR_MODULE.get(name.split(".")[0])
+
+
+def require(extra: str, *modules: str) -> None:
+    """Raise MissingExtraError if any listed module is not importable.
+
+    Use at the top of a module that depends on optional packages:
+
+        from spacescans._extras import require
+        require("geo", "geopandas", "rasterio")
+
+    The error message tells the user exactly how to install the missing extra.
+    """
+    missing = [m for m in modules if importlib.util.find_spec(m) is None]
+    if missing:
+        raise MissingExtraError(
+            f"This feature needs `pip install 'spacescans[{extra}]'`.\n"
+            f"  Missing module(s): {', '.join(missing)}\n"
+            f"  See: {INSTALL_DOCS_URL}",
+            extra=extra,
+            missing=missing,
+        )

spacescans/bridge/__init__.py

@@ -0,0 +1,19 @@
+"""JSON-file protocol for out-of-process clients: the R package now, later the web.
+
+    python -I -u -X utf8 -m spacescans.bridge <command> --request req.json --result res.json
+
+* The request file holds ``{"protocol": 1, "command", "client", "args", "verbose"}``.
+* The result file always gets one envelope: ``{"protocol", "ok", "command",
+  "spacescans": {"version", "code_fp", ...}, "elapsed_s", "value", "warnings", "error"}``.
+* stdout carries only JSON-lines events (``{"ev": ..., "t": ...}``); everything a
+  human should read goes to stderr.
+* Exit codes: 0 ok, 1 handled error (result written, ``ok`` false), 2 protocol or
+  usage error, 130/143 interrupted by SIGINT/SIGTERM (result written when
+  possible); anything else is a crash.
+
+This package imports with the base install only; commands import what they need.
+The full contract is in docs/bridge-protocol.md in the source repository.
+"""
+from spacescans.bridge.protocol import PROTOCOL, PROTOCOL_RANGE
+
+__all__ = ["PROTOCOL", "PROTOCOL_RANGE"]

spacescans/bridge/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m spacescans.bridge <command> --request req.json --result res.json`."""
+import sys
+
+from spacescans.bridge.main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

spacescans/bridge/args.py

@@ -0,0 +1,135 @@
+"""Checking command arguments that arrive as JSON (from R in particular).
+
+R's jsonlite writes a length-1 vector as a scalar, so every list argument
+also accepts a single value (``variables = "ndi"`` means ``["ndi"]``). Paths
+must be absolute: the bridge runs with its cwd set to the client's run
+directory, so a relative path would silently mean something else.
+"""
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from spacescans.bridge.errors import BridgeError
+
+
+def bool_arg(args: Mapping[str, Any], name: str, default: bool = False) -> bool:
+    value = args.get(name, default)
+    if value is None:
+        return default
+    if not isinstance(value, bool):
+        raise BridgeError("config", f"argument '{name}' must be true or false")
+    return value
+
+
+def int_arg(args: Mapping[str, Any], name: str, *, minimum: int | None = None,
+            default: int | None = None) -> int | None:
+    value = args.get(name)
+    if value is None:
+        return default
+    if isinstance(value, float) and value.is_integer():
+        value = int(value)
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise BridgeError("config", f"argument '{name}' must be a whole number, got {value!r}")
+    if minimum is not None and value < minimum:
+        raise BridgeError("config", f"argument '{name}' must be at least {minimum}, got {value}")
+    return value
+
+
+def number_arg(args: Mapping[str, Any], name: str, *, minimum: float | None = None,
+               maximum: float | None = None, default: float | None = None) -> float | None:
+    value = args.get(name)
+    if value is None:
+        return default
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise BridgeError("config", f"argument '{name}' must be a number, got {value!r}")
+    value = float(value)
+    if math.isnan(value):
+        raise BridgeError("config", f"argument '{name}' must be a number, got NaN")
+    if minimum is not None and value < minimum:
+        raise BridgeError("config", f"argument '{name}' must be at least {minimum:g}, got {value:g}")
+    if maximum is not None and value > maximum:
+        raise BridgeError("config", f"argument '{name}' must be at most {maximum:g}, got {value:g}")
+    return value
+
+
+def str_arg(args: Mapping[str, Any], name: str, *, required: bool = False) -> str | None:
+    value = args.get(name)
+    if value is None:
+        if required:
+            raise BridgeError("config", f"argument '{name}' is required")
+        return None
+    if not isinstance(value, str) or not value:
+        raise BridgeError("config", f"argument '{name}' must be a non-empty string")
+    return value
+
+
+def choice_arg(args: Mapping[str, Any], name: str, choices: Sequence[str], *,
+               default: str) -> str:
+    value = args.get(name)
+    if value is None:
+        return default
+    if value not in choices:
+        raise BridgeError("config", f"argument '{name}' must be one of {', '.join(map(repr, choices))}, "
+                          f"got {value!r}", details={"argument": name, "choices": list(choices)})
+    return value
+
+
+def str_list_arg(args: Mapping[str, Any], name: str, *, required: bool = False,
+                 allow_empty: bool = True) -> list[str] | None:
+    """A list of non-empty strings; a single string counts as a list of one."""
+    value = args.get(name)
+    if value is None:
+        if required:
+            raise BridgeError("config", f"argument '{name}' is required")
+        return None
+    if isinstance(value, str):
+        value = [value]
+    if not isinstance(value, list) or not all(isinstance(v, str) and v for v in value):
+        raise BridgeError("config", f"argument '{name}' must be a list of non-empty strings")
+    if not value and not allow_empty:
+        raise BridgeError("config", f"argument '{name}' must not be empty")
+    return list(value)
+
+
+def abs_path(value: Any, name: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise BridgeError("config", f"argument '{name}' must be a path string")
+    if not Path(value).is_absolute():
+        raise BridgeError("config", f"argument '{name}' must be an absolute path, got {value!r}",
+                          details={"argument": name, "value": value})
+    return value
+
+
+def path_arg(args: Mapping[str, Any], name: str, *, required: bool = False) -> str | None:
+    value = args.get(name)
+    if value is None:
+        if required:
+            raise BridgeError("config", f"argument '{name}' is required")
+        return None
+    return abs_path(value, name)
+
+
+def path_list_arg(args: Mapping[str, Any], name: str, *, required: bool = False) -> list[str] | None:
+    value = args.get(name)
+    if value is None:
+        if required:
+            raise BridgeError("config", f"argument '{name}' is required")
+        return None
+    if isinstance(value, str):
+        value = [value]
+    if not isinstance(value, list):
+        raise BridgeError("config", f"argument '{name}' must be a list of absolute paths")
+    return [abs_path(v, name) for v in value]
+
+
+def mapping_arg(args: Mapping[str, Any], name: str) -> dict[str, Any] | None:
+    """An object; ``[]`` (jsonlite's empty named list) counts as empty."""
+    value = args.get(name)
+    if value is None or value == []:
+        return None if value is None else {}
+    if not isinstance(value, dict):
+        raise BridgeError("config", f"argument '{name}' must be an object")
+    return value