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 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