honua-gp 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
honua_gp/__init__.py ADDED
@@ -0,0 +1,175 @@
1
+ """Honua compatibility shim for the desktop geoprocessing scripting API.
2
+
3
+ Customers replace the desktop scripting module import with ``import honua_gp`` and
4
+ point the shim at a Honua deployment via :func:`configure` or the
5
+ ``HONUA_BASE_URL`` / ``HONUA_API_KEY`` environment variables. Every shim call
6
+ dispatches through ``honua_sdk`` / ``honua_admin`` / OGC API Processes and
7
+ writes an audit JSONL record.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from typing import Any
13
+
14
+ from . import analysis as analysis # re-export sub-package
15
+ from . import da as da
16
+ from . import management as management
17
+ from . import sa as sa
18
+ from ._audit import AuditWriter, default_writer, set_audit_writer
19
+ from ._compat import COMPAT, FunctionEntry, anchor_for, entry_for
20
+ from ._raster_tools import RasterResult
21
+ from ._errors import (
22
+ ExecuteError,
23
+ ExecuteWarning,
24
+ HonuaGpConfigurationError,
25
+ HonuaGpResolveError,
26
+ HonuaGpUnsupportedError,
27
+ )
28
+ from ._resolve import ResolvedSource, resolve
29
+ from ._session import HonuaSession, LayerAlias, get_session
30
+ from .env import env
31
+
32
+ # Re-export Describe / ListFields at the package level to mirror the real scripting API,
33
+ # where both are top-level convenience functions rather than
34
+ # ``management.*``-only.
35
+ from .management import (
36
+ Describe,
37
+ DescribeResult,
38
+ FieldDescribe,
39
+ ListFields,
40
+ Selection,
41
+ SpatialReferenceInfo,
42
+ )
43
+
44
+ # Re-export the raster input model from honua_sdk so callers can build raster
45
+ # references (layer id / raster id / GeoTIFF bytes) without importing the SDK
46
+ # module directly: ``honua_gp.RasterReference.from_layer_id(...)``.
47
+ from honua_sdk.geoprocessing import LayerReference, RasterReference
48
+
49
+ try:
50
+ from importlib.metadata import version as _meta_version
51
+
52
+ __version__: str = _meta_version("honua-gp")
53
+ except Exception: # pragma: no cover -- editable / not-installed fallback
54
+ __version__ = "0.0.0.dev0"
55
+
56
+
57
+ def configure(
58
+ *,
59
+ base_url: str | None = None,
60
+ api_key: str | None = None,
61
+ bearer_token: str | None = None,
62
+ client: Any | None = None,
63
+ admin_client: Any | None = None,
64
+ processes_client: Any | None = None,
65
+ **client_kwargs: Any,
66
+ ) -> None:
67
+ """Configure the global Honua session.
68
+
69
+ ``base_url`` + (``api_key`` or ``bearer_token``) is the standard path.
70
+ The remaining keywords (``client``, ``admin_client``, ``processes_client``)
71
+ accept pre-built instances for testing or wire-once integration cases.
72
+
73
+ Credentials are refused over a plain ``http://`` base URL unless its host
74
+ is ``localhost`` or a loopback address. Pass ``allow_insecure_http=True``
75
+ (forwarded to the SDK clients) or set ``HONUA_ALLOW_INSECURE_HTTP=1`` to
76
+ opt in.
77
+ """
78
+
79
+ get_session().configure(
80
+ base_url=base_url,
81
+ api_key=api_key,
82
+ bearer_token=bearer_token,
83
+ client=client,
84
+ admin_client=admin_client,
85
+ processes_client=processes_client,
86
+ **client_kwargs,
87
+ )
88
+
89
+
90
+ def configure_from_env() -> None:
91
+ """Configure the global session from ``HONUA_BASE_URL`` / ``HONUA_API_KEY``."""
92
+
93
+ get_session().configure_from_env()
94
+
95
+
96
+ def reset() -> None:
97
+ """Reset the global session (test-only helper)."""
98
+
99
+ get_session().reset()
100
+
101
+
102
+ # Module-level shorthand mirroring the real scripting API:
103
+ # GetCount_management(...) -> management.GetCount(...)
104
+ GetCount = management.GetCount
105
+
106
+
107
+ # Legacy suffix-style aliases. The real scripting API exposes both ``analysis.Buffer``
108
+ # and ``Buffer_analysis``; many production scripts use the suffix form,
109
+ # so the shim re-exports the top-of-corpus entries that way too. Adding a
110
+ # new alias requires only listing it here and in ``__all__`` below.
111
+ _SUFFIX_ALIASES: dict[str, Any] = {
112
+ # analysis.*
113
+ "Buffer_analysis": analysis.Buffer,
114
+ "Clip_analysis": analysis.Clip,
115
+ "Erase_analysis": analysis.Erase,
116
+ "Intersect_analysis": analysis.Intersect,
117
+ "SpatialJoin_analysis": analysis.SpatialJoin,
118
+ "Union_analysis": analysis.Union,
119
+ # management.*
120
+ "CalculateField_management": management.CalculateField,
121
+ "Copy_management": management.Copy,
122
+ "CopyFeatures_management": management.CopyFeatures,
123
+ "Delete_management": management.Delete,
124
+ "Dissolve_management": management.Dissolve,
125
+ "GetCount_management": management.GetCount,
126
+ "MakeFeatureLayer_management": management.MakeFeatureLayer,
127
+ "MakeTableView_management": management.MakeTableView,
128
+ "Project_management": management.Project,
129
+ "SelectLayerByAttribute_management": management.SelectLayerByAttribute,
130
+ }
131
+
132
+ globals().update(_SUFFIX_ALIASES)
133
+
134
+
135
+ __all__ = [
136
+ "__version__",
137
+ "analysis",
138
+ "da",
139
+ "management",
140
+ "sa",
141
+ "env",
142
+ "configure",
143
+ "configure_from_env",
144
+ "reset",
145
+ "AuditWriter",
146
+ "COMPAT",
147
+ "ExecuteError",
148
+ "ExecuteWarning",
149
+ "FunctionEntry",
150
+ "HonuaGpConfigurationError",
151
+ "HonuaGpResolveError",
152
+ "HonuaGpUnsupportedError",
153
+ "HonuaSession",
154
+ "LayerAlias",
155
+ "ResolvedSource",
156
+ "anchor_for",
157
+ "default_writer",
158
+ "entry_for",
159
+ "get_session",
160
+ "resolve",
161
+ "set_audit_writer",
162
+ # scripting-API-compatible re-exports
163
+ "Describe",
164
+ "DescribeResult",
165
+ "FieldDescribe",
166
+ "GetCount",
167
+ "LayerReference",
168
+ "ListFields",
169
+ "RasterReference",
170
+ "RasterResult",
171
+ "Selection",
172
+ "SpatialReferenceInfo",
173
+ # Legacy suffix-form aliases (the real scripting API exposes both)
174
+ *_SUFFIX_ALIASES.keys(),
175
+ ]
honua_gp/_audit.py ADDED
@@ -0,0 +1,211 @@
1
+ """JSONL audit logger for shim invocations.
2
+
3
+ Every call to a supported shim function produces one JSON line. The shape is::
4
+
5
+ {
6
+ "timestamp": "2026-05-22T17:42:11Z",
7
+ "function": "analysis.Buffer",
8
+ "args": ["...", "...", ...], # redacted positional args
9
+ "kwargs": {"distance": "..."}, # redacted kwargs
10
+ "result_shape": {...}, # shape-only summary, no values
11
+ "latency_ms": 12.4,
12
+ "status": "ok" | "error",
13
+ "error_kind": "..." # only when status == "error"
14
+ }
15
+
16
+ The file path is ``${HONUA_GP_AUDIT_DIR:-./.honua-gp/audit}/audit-YYYYMMDD.jsonl``
17
+ in UTC, written append-only with one writer at a time per process. Redaction
18
+ delegates to :mod:`honua_admin._redaction` so we don't reinvent path /
19
+ secret heuristics.
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ import json
25
+ import os
26
+ import threading
27
+ import time
28
+ from collections.abc import Mapping, Sequence
29
+ from contextlib import contextmanager
30
+ from datetime import datetime, timezone
31
+ from pathlib import Path
32
+ from typing import Any, Iterator
33
+
34
+ # Import failure must stop the process before any audit line is written.
35
+ # A local substitute returns URLs unchanged and would record credentials.
36
+ from honua_admin._redaction import (
37
+ _is_sensitive_context,
38
+ _looks_like_bare_secret,
39
+ _looks_like_path,
40
+ _looks_like_url,
41
+ _redact_path,
42
+ _redact_url,
43
+ )
44
+
45
+
46
+ _AUDIT_LOCK = threading.Lock()
47
+ _AUDIT_DIR_ENV = "HONUA_GP_AUDIT_DIR"
48
+ _AUDIT_DEFAULT_DIR = Path(".honua-gp") / "audit"
49
+
50
+
51
+ def _audit_dir() -> Path:
52
+ override = os.environ.get(_AUDIT_DIR_ENV)
53
+ if override:
54
+ return Path(override)
55
+ return _AUDIT_DEFAULT_DIR
56
+
57
+
58
+ def _audit_path(now: datetime | None = None) -> Path:
59
+ moment = now or datetime.now(timezone.utc)
60
+ return _audit_dir() / f"audit-{moment.strftime('%Y%m%d')}.jsonl"
61
+
62
+
63
+ def _utc_timestamp(now: datetime | None = None) -> str:
64
+ moment = now or datetime.now(timezone.utc)
65
+ return moment.strftime("%Y-%m-%dT%H:%M:%SZ")
66
+
67
+
68
+ def _redact_value(value: Any, *, context: str | None = None) -> Any:
69
+ if isinstance(value, str):
70
+ if _is_sensitive_context(context):
71
+ return "<redacted>"
72
+ if _looks_like_url(value):
73
+ return _redact_url(value)
74
+ if _looks_like_bare_secret(value):
75
+ return "<redacted>"
76
+ if _looks_like_path(value):
77
+ return _redact_path(value)
78
+ return value
79
+ if isinstance(value, Mapping):
80
+ return {str(key): _redact_value(item, context=str(key)) for key, item in value.items()}
81
+ if isinstance(value, (list, tuple)):
82
+ return [_redact_value(item, context=context) for item in value]
83
+ if isinstance(value, (int, float, bool)) or value is None:
84
+ return value
85
+ # Fall back to a shape-only representation: type tag rather than __repr__.
86
+ return {"type": type(value).__name__}
87
+
88
+
89
+ def _shape_of(value: Any) -> Any:
90
+ """Return a shape-only summary suitable for the result_shape field."""
91
+
92
+ if value is None:
93
+ return None
94
+ if isinstance(value, Mapping):
95
+ return {"type": "object", "keys": sorted(str(key) for key in value)}
96
+ if isinstance(value, (list, tuple)):
97
+ return {"type": "array", "length": len(value)}
98
+ if isinstance(value, str):
99
+ return {"type": "string", "length": len(value)}
100
+ if isinstance(value, (int, float, bool)):
101
+ return {"type": type(value).__name__}
102
+ return {"type": type(value).__name__}
103
+
104
+
105
+ class AuditWriter:
106
+ """Append-only JSONL writer with one open handle per UTC day."""
107
+
108
+ def __init__(self, base_dir: Path | None = None) -> None:
109
+ self._base_dir_override = base_dir
110
+ self._current_path: Path | None = None
111
+ self._current_handle: Any = None
112
+ self._lock = threading.Lock()
113
+
114
+ def _resolve_path(self, now: datetime | None = None) -> Path:
115
+ if self._base_dir_override is not None:
116
+ moment = now or datetime.now(timezone.utc)
117
+ return self._base_dir_override / f"audit-{moment.strftime('%Y%m%d')}.jsonl"
118
+ return _audit_path(now)
119
+
120
+ def write(self, record: Mapping[str, Any], *, now: datetime | None = None) -> None:
121
+ path = self._resolve_path(now)
122
+ line = json.dumps(record, ensure_ascii=False, sort_keys=True)
123
+ with self._lock:
124
+ if self._current_path != path or self._current_handle is None:
125
+ self.close()
126
+ path.parent.mkdir(parents=True, exist_ok=True)
127
+ self._current_handle = path.open("a", encoding="utf-8")
128
+ self._current_path = path
129
+ self._current_handle.write(line + "\n")
130
+ self._current_handle.flush()
131
+
132
+ def close(self) -> None:
133
+ if self._current_handle is not None:
134
+ try:
135
+ self._current_handle.close()
136
+ finally:
137
+ self._current_handle = None
138
+ self._current_path = None
139
+
140
+
141
+ _DEFAULT_WRITER = AuditWriter()
142
+
143
+
144
+ def set_audit_writer(writer: AuditWriter) -> AuditWriter:
145
+ """Replace the module-default writer. Returns the previous instance."""
146
+
147
+ global _DEFAULT_WRITER
148
+ previous = _DEFAULT_WRITER
149
+ _DEFAULT_WRITER = writer
150
+ return previous
151
+
152
+
153
+ def default_writer() -> AuditWriter:
154
+ return _DEFAULT_WRITER
155
+
156
+
157
+ @contextmanager
158
+ def record_call(
159
+ function: str,
160
+ *,
161
+ args: Sequence[Any] = (),
162
+ kwargs: Mapping[str, Any] | None = None,
163
+ writer: AuditWriter | None = None,
164
+ ) -> Iterator[dict[str, Any]]:
165
+ """Audit a shim invocation.
166
+
167
+ Yields a mutable dictionary so the dispatcher can attach ``result_shape``
168
+ once the underlying call returns. The line is always written on exit --
169
+ failures land with ``status="error"`` plus ``error_kind``.
170
+ """
171
+
172
+ target = writer or _DEFAULT_WRITER
173
+ redacted_args = [_redact_value(value, context=f"arg{index}") for index, value in enumerate(args)]
174
+ redacted_kwargs = {
175
+ str(key): _redact_value(value, context=str(key))
176
+ for key, value in (kwargs or {}).items()
177
+ }
178
+ record: dict[str, Any] = {
179
+ "function": function,
180
+ "args": redacted_args,
181
+ "kwargs": redacted_kwargs,
182
+ "status": "ok",
183
+ }
184
+ start = time.perf_counter()
185
+ try:
186
+ yield record
187
+ except BaseException as exc:
188
+ record["status"] = "error"
189
+ kind = getattr(exc, "error_kind", None) or exc.__class__.__name__
190
+ record["error_kind"] = str(kind)
191
+ raise
192
+ finally:
193
+ record["latency_ms"] = round((time.perf_counter() - start) * 1000.0, 3)
194
+ record["timestamp"] = _utc_timestamp()
195
+ record.setdefault("result_shape", None)
196
+ try:
197
+ target.write(record)
198
+ except Exception:
199
+ # Audit is observability; never let a logging failure mask the
200
+ # real call's outcome or success.
201
+ pass
202
+
203
+
204
+ __all__ = [
205
+ "AuditWriter",
206
+ "default_writer",
207
+ "record_call",
208
+ "set_audit_writer",
209
+ "_redact_value",
210
+ "_shape_of",
211
+ ]
honua_gp/_cli.py ADDED
@@ -0,0 +1,150 @@
1
+ """``honua-gp`` console entry point.
2
+
3
+ ``matrix`` regenerates the compatibility matrix markdown from the in-code
4
+ manifest, offline; CI uses ``--check`` as a doc gate.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import argparse
10
+ import sys
11
+ from collections.abc import Sequence
12
+ from pathlib import Path
13
+
14
+ from ._compat import COMPAT, FunctionEntry
15
+
16
+ def render_compat_matrix() -> str:
17
+ """Render the compatibility manifest as a Markdown document."""
18
+
19
+ families = ("analysis", "management", "da", "sa")
20
+ lines: list[str] = []
21
+ # OKF v0.2 frontmatter. This matrix is real consumer documentation - it is
22
+ # what someone checks before committing to a migration - so it belongs in
23
+ # the documentation bundle. It is also generated and compared against this
24
+ # output by a test, so the frontmatter has to come from here rather than be
25
+ # added by hand. See docs/okf-bundle.v1.json.
26
+ lines.append("---")
27
+ lines.append("type: reference")
28
+ lines.append('title: "honua-gp compatibility matrix"')
29
+ lines.append(
30
+ 'description: "Which scripting API surfaces the shim supports, which run with '
31
+ 'documented deviations, and which raise rather than fail silently. Check '
32
+ 'this before committing to a migration."'
33
+ )
34
+ # `resource` points at the shim's source rather than PyPI: honua-gp is not
35
+ # published there, and a resource that 404s is worse than none.
36
+ lines.append(
37
+ 'resource: "https://github.com/honua-io/honua-sdk-python/tree/trunk/packages/honua-gp"'
38
+ )
39
+ lines.append("tags: [honua-gp, geoprocessing, compatibility, generated]")
40
+ lines.append("---")
41
+ lines.append("# honua-gp compatibility matrix")
42
+ lines.append("")
43
+ lines.append(
44
+ "Generated from the in-code ``COMPAT`` manifest by "
45
+ "``scripts/render_compat_matrix.py`` (re-run after manifest edits)."
46
+ )
47
+ lines.append("")
48
+ lines.append(_status_legend())
49
+ lines.append("")
50
+
51
+ for family in families:
52
+ lines.append(f"## {family}.*")
53
+ lines.append("")
54
+ lines.append("| Function | Status | Backend | Replacement / notes |")
55
+ lines.append("| --- | --- | --- | --- |")
56
+ for name, entry in sorted(_filter_family(family).items()):
57
+ anchor_id = name.replace(".", "").lower()
58
+ status = entry.status.capitalize()
59
+ backend = entry.backend.replace("_", "-")
60
+ cell = entry.notes
61
+ if entry.replacement_hint:
62
+ cell = f"{cell}<br>**hint:** {entry.replacement_hint}"
63
+ if entry.tracking:
64
+ cell = f"{cell}<br>**tracking:** `{entry.tracking}`"
65
+ lines.append(
66
+ f"| <a id=\"{anchor_id}\"></a>`{name}` | {status} | `{backend}` | {cell} |"
67
+ )
68
+ lines.append("")
69
+
70
+ lines.append("## Coverage")
71
+ lines.append("")
72
+ supported = sum(1 for entry in COMPAT.values() if entry.is_supported)
73
+ stubs = sum(1 for entry in COMPAT.values() if entry.status == "stub")
74
+ lines.append(f"* Total functions: {len(COMPAT)}")
75
+ lines.append(f"* Supported / partial: {supported}")
76
+ lines.append(f"* Stubbed (raise ``HonuaGpUnsupportedError``): {stubs}")
77
+ lines.append("")
78
+ lines.append(
79
+ "Stubs intentionally raise rather than silently fail so customer scripts surface gaps "
80
+ "before the migration tool ingests the audit JSONL."
81
+ )
82
+ return "\n".join(lines).rstrip() + "\n"
83
+
84
+
85
+ def _status_legend() -> str:
86
+ return (
87
+ "Statuses: **Supported** runs against Honua, **Partial** runs with documented deviations, "
88
+ "**Stub** raises ``HonuaGpUnsupportedError`` with a replacement hint and tracking ticket."
89
+ )
90
+
91
+
92
+ def _filter_family(family: str) -> dict[str, FunctionEntry]:
93
+ return {name: entry for name, entry in COMPAT.items() if name.startswith(f"{family}.")}
94
+
95
+
96
+ def _matrix(args: argparse.Namespace) -> int:
97
+ text = render_compat_matrix()
98
+ # ``--check`` runs against the committed file before any ``--output``
99
+ # write so a caller that points both flags at the same path cannot
100
+ # rewrite the committed file with fresh-rendered text and then compare
101
+ # it to itself, masking real drift.
102
+ if args.check is not None:
103
+ existing = args.check.read_text(encoding="utf-8") if args.check.exists() else ""
104
+ if existing != text:
105
+ sys.stderr.write(
106
+ f"Compatibility matrix drift detected at {args.check}. "
107
+ "Re-run `honua-gp matrix --output <path>` and commit the result.\n"
108
+ )
109
+ return 1
110
+ if args.output is not None:
111
+ args.output.parent.mkdir(parents=True, exist_ok=True)
112
+ args.output.write_text(text, encoding="utf-8")
113
+ else:
114
+ sys.stdout.write(text)
115
+ return 0
116
+
117
+
118
+ def build_parser() -> argparse.ArgumentParser:
119
+ parser = argparse.ArgumentParser(prog="honua-gp", description=__doc__)
120
+ sub = parser.add_subparsers(dest="command", required=True)
121
+
122
+ matrix = sub.add_parser(
123
+ "matrix",
124
+ help="Render docs/compatibility-matrix.md from the in-code manifest.",
125
+ )
126
+ matrix.add_argument(
127
+ "--output",
128
+ type=Path,
129
+ default=None,
130
+ help="Path to write the rendered markdown (default: stdout).",
131
+ )
132
+ matrix.add_argument(
133
+ "--check",
134
+ type=Path,
135
+ default=None,
136
+ help="Compare against an existing file and exit non-zero on drift (CI doc gate).",
137
+ )
138
+ matrix.set_defaults(func=_matrix)
139
+
140
+ return parser
141
+
142
+
143
+ def main(argv: Sequence[str] | None = None) -> int:
144
+ parser = build_parser()
145
+ args = parser.parse_args(argv)
146
+ return args.func(args)
147
+
148
+
149
+ if __name__ == "__main__": # pragma: no cover
150
+ raise SystemExit(main())