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 +175 -0
- honua_gp/_audit.py +211 -0
- honua_gp/_cli.py +150 -0
- honua_gp/_compat.py +1066 -0
- honua_gp/_dispatch.py +383 -0
- honua_gp/_errors.py +105 -0
- honua_gp/_output_artifact.py +248 -0
- honua_gp/_process_jobs.py +233 -0
- honua_gp/_process_tools.py +802 -0
- honua_gp/_raster_tools.py +475 -0
- honua_gp/_resolve.py +361 -0
- honua_gp/_session.py +342 -0
- honua_gp/_wkb.py +142 -0
- honua_gp/analysis/__init__.py +108 -0
- honua_gp/da/__init__.py +691 -0
- honua_gp/env.py +59 -0
- honua_gp/management/__init__.py +774 -0
- honua_gp/py.typed +0 -0
- honua_gp/sa/__init__.py +376 -0
- honua_gp-0.1.0.dist-info/METADATA +66 -0
- honua_gp-0.1.0.dist-info/RECORD +24 -0
- honua_gp-0.1.0.dist-info/WHEEL +4 -0
- honua_gp-0.1.0.dist-info/entry_points.txt +2 -0
- honua_gp-0.1.0.dist-info/licenses/LICENSE +201 -0
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())
|