openverto 0.1.1__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.
- openverto/__init__.py +55 -0
- openverto/base.py +124 -0
- openverto/cache.py +126 -0
- openverto/cli.py +536 -0
- openverto/detect.py +121 -0
- openverto/geo.py +159 -0
- openverto/refdata.py +74 -0
- openverto/systems.py +44 -0
- openverto/transform.py +283 -0
- openverto-0.1.1.dist-info/METADATA +144 -0
- openverto-0.1.1.dist-info/RECORD +13 -0
- openverto-0.1.1.dist-info/WHEEL +4 -0
- openverto-0.1.1.dist-info/entry_points.txt +3 -0
openverto/__init__.py
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
"""openverto — Python CLI and library for the IGM Verto Online coordinate service.
|
|
2
|
+
|
|
3
|
+
Convert coordinates between every Italian reference system (Roma40, ED50,
|
|
4
|
+
IGM95, ETRS89, RDN2008) via the official IGM service, with zero grid-file
|
|
5
|
+
setup. Offline EPSG intelligence (``inspect``, ``targets``, ``detect``) needs
|
|
6
|
+
no network.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
10
|
+
|
|
11
|
+
try:
|
|
12
|
+
__version__ = version("openverto")
|
|
13
|
+
except PackageNotFoundError:
|
|
14
|
+
__version__ = "0.0.0"
|
|
15
|
+
|
|
16
|
+
from .base import (
|
|
17
|
+
MAX_COORD,
|
|
18
|
+
VertoError,
|
|
19
|
+
get_extra_headers,
|
|
20
|
+
set_base_url,
|
|
21
|
+
set_extra_headers,
|
|
22
|
+
set_timeout,
|
|
23
|
+
)
|
|
24
|
+
from .transform import convert, convert_skipping, inspect, roundtrip, targets
|
|
25
|
+
from .detect import detect
|
|
26
|
+
from .geo import reproject_geojson
|
|
27
|
+
from .systems import info, system_by_epsg, systems
|
|
28
|
+
|
|
29
|
+
__all__ = [
|
|
30
|
+
"systems",
|
|
31
|
+
"system_by_epsg",
|
|
32
|
+
"info",
|
|
33
|
+
"convert",
|
|
34
|
+
"convert_skipping",
|
|
35
|
+
"inspect",
|
|
36
|
+
"targets",
|
|
37
|
+
"roundtrip",
|
|
38
|
+
"detect",
|
|
39
|
+
"reproject_geojson",
|
|
40
|
+
"set_timeout",
|
|
41
|
+
"set_base_url",
|
|
42
|
+
"set_extra_headers",
|
|
43
|
+
"get_extra_headers",
|
|
44
|
+
"VertoError",
|
|
45
|
+
"MAX_COORD",
|
|
46
|
+
"__version__",
|
|
47
|
+
"main",
|
|
48
|
+
]
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def main() -> None:
|
|
52
|
+
"""CLI entrypoint (lazy import so the library has no CLI-only deps cost)."""
|
|
53
|
+
from .cli import app
|
|
54
|
+
|
|
55
|
+
app()
|
openverto/base.py
ADDED
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
"""HTTP layer for the IGM Verto Online service.
|
|
2
|
+
|
|
3
|
+
The service is a single POST endpoint discriminated by the body field
|
|
4
|
+
``richiesta``: ``"info"`` lists the supported reference systems, ``"conversione"``
|
|
5
|
+
transforms an array of ``{e, n}`` coordinates between two EPSG codes. The
|
|
6
|
+
``utente``/``chiave`` fields are mandatory but ignored by the service (they are
|
|
7
|
+
NOT authentication); we send fixed placeholders.
|
|
8
|
+
|
|
9
|
+
Service-level errors are returned inside an HTTP 200 body as
|
|
10
|
+
``{"stato": "errore", "dove": ..., "messaggio": ...}`` and surface as
|
|
11
|
+
:class:`VertoError`.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
import time
|
|
17
|
+
|
|
18
|
+
import httpx
|
|
19
|
+
|
|
20
|
+
#: Default endpoint (relative path ``/volapi`` is already included).
|
|
21
|
+
DEFAULT_BASE_URL = "https://igmi.esercito.difesa.it/porta-magna/wps/volapi"
|
|
22
|
+
|
|
23
|
+
#: Maximum number of coordinates accepted per ``conversione`` request.
|
|
24
|
+
MAX_COORD = 32000
|
|
25
|
+
|
|
26
|
+
_USER_AGENT = "openverto"
|
|
27
|
+
|
|
28
|
+
# Module-level configuration (mutable via the setters below).
|
|
29
|
+
_base_url = DEFAULT_BASE_URL
|
|
30
|
+
_timeout = 30.0
|
|
31
|
+
_extra_headers: dict[str, str] = {}
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def set_base_url(url: str) -> None:
|
|
35
|
+
"""Override the service endpoint (useful for tests or a mirror)."""
|
|
36
|
+
global _base_url
|
|
37
|
+
_base_url = url
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def get_base_url() -> str:
|
|
41
|
+
return _base_url
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def set_timeout(seconds: float) -> None:
|
|
45
|
+
"""Set the per-request timeout in seconds."""
|
|
46
|
+
global _timeout
|
|
47
|
+
_timeout = float(seconds)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def get_timeout() -> float:
|
|
51
|
+
return _timeout
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def set_extra_headers(headers: dict[str, str]) -> None:
|
|
55
|
+
"""Replace the static extra HTTP headers sent with every request."""
|
|
56
|
+
global _extra_headers
|
|
57
|
+
_extra_headers = dict(headers)
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def get_extra_headers() -> dict[str, str]:
|
|
61
|
+
return dict(_extra_headers)
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class VertoError(Exception):
|
|
65
|
+
"""A service-level error reported by Verto Online (``stato: errore``).
|
|
66
|
+
|
|
67
|
+
The most common case is an out-of-grid coordinate, signalled by
|
|
68
|
+
``dove == "Proj"`` (the underlying PROJ transform rejecting a coordinate
|
|
69
|
+
outside the IGM grid coverage).
|
|
70
|
+
"""
|
|
71
|
+
|
|
72
|
+
def __init__(self, messaggio: str, dove: str = ""):
|
|
73
|
+
self.messaggio = messaggio
|
|
74
|
+
self.dove = dove
|
|
75
|
+
super().__init__(str(self))
|
|
76
|
+
|
|
77
|
+
def __str__(self) -> str:
|
|
78
|
+
if self.dove:
|
|
79
|
+
return f"verto service error ({self.dove}): {self.messaggio}"
|
|
80
|
+
return f"verto service error: {self.messaggio}"
|
|
81
|
+
|
|
82
|
+
@property
|
|
83
|
+
def outside_grid(self) -> bool:
|
|
84
|
+
"""Whether this is the 'coordinate outside the IGM grid coverage' case."""
|
|
85
|
+
if self.dove.strip().lower() == "proj":
|
|
86
|
+
return True
|
|
87
|
+
m = (self.messaggio or "").lower()
|
|
88
|
+
return "outside grid" in m or "griglia" in m
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def post(body: dict, *, retries: int = 2) -> dict:
|
|
92
|
+
"""POST a request body to the Verto endpoint and return the parsed JSON.
|
|
93
|
+
|
|
94
|
+
Retries transient network/5xx errors with a short backoff. Raises
|
|
95
|
+
:class:`httpx.HTTPError` on a non-recoverable transport error and
|
|
96
|
+
:class:`ValueError` on an unparseable body. Service-level ``stato: errore``
|
|
97
|
+
bodies are returned as-is for the caller to interpret.
|
|
98
|
+
"""
|
|
99
|
+
headers = {"Content-Type": "application/json", "User-Agent": _USER_AGENT}
|
|
100
|
+
headers.update(_extra_headers)
|
|
101
|
+
last_exc: Exception | None = None
|
|
102
|
+
for attempt in range(retries + 1):
|
|
103
|
+
try:
|
|
104
|
+
with httpx.Client(timeout=_timeout) as client:
|
|
105
|
+
resp = client.post(_base_url, json=body, headers=headers)
|
|
106
|
+
if resp.status_code >= 500 and attempt < retries:
|
|
107
|
+
last_exc = httpx.HTTPStatusError(
|
|
108
|
+
f"server error {resp.status_code}", request=resp.request, response=resp
|
|
109
|
+
)
|
|
110
|
+
time.sleep(0.5 * (attempt + 1))
|
|
111
|
+
continue
|
|
112
|
+
resp.raise_for_status()
|
|
113
|
+
try:
|
|
114
|
+
return resp.json()
|
|
115
|
+
except ValueError as exc:
|
|
116
|
+
raise ValueError(f"invalid JSON from Verto service: {exc}") from exc
|
|
117
|
+
except (httpx.TransportError, httpx.HTTPStatusError) as exc:
|
|
118
|
+
last_exc = exc
|
|
119
|
+
if attempt < retries:
|
|
120
|
+
time.sleep(0.5 * (attempt + 1))
|
|
121
|
+
continue
|
|
122
|
+
raise
|
|
123
|
+
# Unreachable, but keeps type-checkers happy.
|
|
124
|
+
raise last_exc if last_exc else RuntimeError("post failed")
|
openverto/cache.py
ADDED
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
"""Offline write-through cache for systems and conversion results.
|
|
2
|
+
|
|
3
|
+
Cached results let pipelines replay the same conversions offline and keep CI
|
|
4
|
+
runs reproducible without hitting the live service. Files live under the user
|
|
5
|
+
cache directory (``platformdirs``); set ``OPENVERTO_CACHE_DIR`` to override.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import json
|
|
11
|
+
import os
|
|
12
|
+
from pathlib import Path
|
|
13
|
+
|
|
14
|
+
from platformdirs import user_cache_dir
|
|
15
|
+
|
|
16
|
+
# Conversion cache keys round e/n to this many decimals so float jitter on the
|
|
17
|
+
# input does not prevent a hit. 6 decimals is ~0.1 mm at the equator — finer
|
|
18
|
+
# than the service's own precision.
|
|
19
|
+
_KEY_DECIMALS = 6
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def cache_dir() -> Path:
|
|
23
|
+
"""Return the cache directory, honouring ``OPENVERTO_CACHE_DIR``."""
|
|
24
|
+
override = os.environ.get("OPENVERTO_CACHE_DIR")
|
|
25
|
+
d = Path(override) if override else Path(user_cache_dir("openverto"))
|
|
26
|
+
d.mkdir(parents=True, exist_ok=True)
|
|
27
|
+
return d
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def _systems_file() -> Path:
|
|
31
|
+
return cache_dir() / "systems.json"
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def _conv_file() -> Path:
|
|
35
|
+
return cache_dir() / "conversions.json"
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def load_systems() -> list[dict]:
|
|
39
|
+
"""Return the cached systems list, or ``[]`` on miss/corruption."""
|
|
40
|
+
f = _systems_file()
|
|
41
|
+
try:
|
|
42
|
+
return json.loads(f.read_text(encoding="utf-8"))
|
|
43
|
+
except (OSError, ValueError):
|
|
44
|
+
return []
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def save_systems(systems: list[dict]) -> None:
|
|
48
|
+
try:
|
|
49
|
+
_systems_file().write_text(
|
|
50
|
+
json.dumps(systems, ensure_ascii=False), encoding="utf-8"
|
|
51
|
+
)
|
|
52
|
+
except OSError:
|
|
53
|
+
pass
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _conv_key(in_epsg: int, out_epsg: int, e: float, n: float) -> str:
|
|
57
|
+
return f"{in_epsg}:{out_epsg}:{round(e, _KEY_DECIMALS)}:{round(n, _KEY_DECIMALS)}"
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
class ConvCache:
|
|
61
|
+
"""A write-through cache of conversion results, persisted as JSON."""
|
|
62
|
+
|
|
63
|
+
def __init__(self, data: dict[str, list[float]] | None = None):
|
|
64
|
+
self._data: dict[str, list[float]] = data or {}
|
|
65
|
+
self._dirty = False
|
|
66
|
+
|
|
67
|
+
@classmethod
|
|
68
|
+
def load(cls) -> "ConvCache":
|
|
69
|
+
try:
|
|
70
|
+
raw = json.loads(_conv_file().read_text(encoding="utf-8"))
|
|
71
|
+
if isinstance(raw, dict):
|
|
72
|
+
return cls(raw)
|
|
73
|
+
except (OSError, ValueError):
|
|
74
|
+
pass
|
|
75
|
+
return cls()
|
|
76
|
+
|
|
77
|
+
def get(self, in_epsg: int, out_epsg: int, e: float, n: float) -> tuple[float, float] | None:
|
|
78
|
+
v = self._data.get(_conv_key(in_epsg, out_epsg, e, n))
|
|
79
|
+
if v and len(v) == 2:
|
|
80
|
+
return (v[0], v[1])
|
|
81
|
+
return None
|
|
82
|
+
|
|
83
|
+
def put(self, in_epsg: int, out_epsg: int, e: float, n: float, result: tuple[float, float]) -> None:
|
|
84
|
+
self._data[_conv_key(in_epsg, out_epsg, e, n)] = [result[0], result[1]]
|
|
85
|
+
self._dirty = True
|
|
86
|
+
|
|
87
|
+
def save(self) -> None:
|
|
88
|
+
if not self._dirty:
|
|
89
|
+
return
|
|
90
|
+
try:
|
|
91
|
+
_conv_file().write_text(
|
|
92
|
+
json.dumps(self._data, ensure_ascii=False), encoding="utf-8"
|
|
93
|
+
)
|
|
94
|
+
self._dirty = False
|
|
95
|
+
except OSError:
|
|
96
|
+
pass
|
|
97
|
+
|
|
98
|
+
def __len__(self) -> int:
|
|
99
|
+
return len(self._data)
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def stats() -> dict:
|
|
103
|
+
"""Return cache statistics for the ``cache --stats`` command."""
|
|
104
|
+
conv = _conv_file()
|
|
105
|
+
syst = _systems_file()
|
|
106
|
+
return {
|
|
107
|
+
"cache_dir": str(cache_dir()),
|
|
108
|
+
"systems_cached": len(load_systems()),
|
|
109
|
+
"conversions_cached": len(ConvCache.load()),
|
|
110
|
+
"conversions_file": str(conv) if conv.exists() else None,
|
|
111
|
+
"size_bytes": (conv.stat().st_size if conv.exists() else 0)
|
|
112
|
+
+ (syst.stat().st_size if syst.exists() else 0),
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def clear() -> list[str]:
|
|
117
|
+
"""Delete cache files. Returns the paths removed."""
|
|
118
|
+
removed = []
|
|
119
|
+
for f in (_conv_file(), _systems_file()):
|
|
120
|
+
if f.exists():
|
|
121
|
+
try:
|
|
122
|
+
f.unlink()
|
|
123
|
+
removed.append(str(f))
|
|
124
|
+
except OSError:
|
|
125
|
+
pass
|
|
126
|
+
return removed
|