cadis 0.1.0__tar.gz

cadis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 isempty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cadis-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: cadis
+Version: 0.1.0
+Summary: Public facade entrypoint for Cadis global lookup
+Author: Cadis
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cadis-global>=0.1.0
+Requires-Dist: platformdirs>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# cadis
+
+`cadis` is the public facade entrypoint of the Cadis system.
+
+It provides a zero-configuration global lookup interface while hiding
+runtime, dataset, and bootstrap orchestration details.
+
+`cadis` is **not** a runtime, dataset engine, or CDN client.
+It is a thin facade layer built on top of `cadis-global`.
+
+---
+
+## Install
+
+```bash
+pip install cadis
+```
+
+---
+
+## Quick Start
+
+```python
+from cadis import lookup, info
+
+result = lookup(25.0330, 121.5654)
+print(result["lookup_status"])
+
+print(info())
+```
+
+---
+
+## CLI
+
+`cadis` also provides a minimal CLI entrypoint:
+
+```bash
+cadis lookup <lat> <lon>
+cadis lookup <lat> <lon> --json
+cadis info
+```
+
+Examples:
+
+```bash
+cadis lookup 25.0330 121.5654
+```
+
+```bash
+cadis lookup 25.0330 121.5654 --json
+```
+
+```bash
+cadis info
+```
+
+CLI mode semantics (v0.1):
+
+* `lookup` calls the same `cadis.lookup()` API as Python mode.
+* Default `lookup` output is human-friendly status text.
+* `lookup --json` prints the full API envelope as JSON.
+* `info` prints the full `cadis.info()` payload as JSON.
+* CLI does not add bootstrap/download orchestration logic.
+
+---
+
+## Public API
+
+### `lookup(lat: float, lon: float) -> dict`
+
+Zero-configuration lookup entrypoint.
+
+Behavior:
+
+* Lazy initialization on first call
+* No network or bootstrap work at import time
+* Deterministic response envelope
+* Stable public error semantics
+
+---
+
+### `info() -> dict`
+
+Returns capability metadata for the current environment.
+
+The output includes:
+
+* `version`: public API version
+* `system_iso2`: ISO2 codes available to this installation
+* `offline_iso2`: ISO2 datasets currently available in local cache
+
+Example:
+
+```json
+{
+  "schema_version": "1",
+  "version": "0.1.0",
+  "system_iso2": ["JP", "TW"],
+  "offline_iso2": ["TW"]
+}
+```
+
+`info()` has no side effects and performs no network operations.
+
+---
+
+## Architecture
+
+```text
+cadis (facade)
+  -> cadis-global
+    -> cadis-runtime
+      -> cadis-core + cadis-cdn
+```
+
+---
+
+## Cache Policy
+
+Cache directory resolution order:
+
+1. `CADIS_CACHE_DIR` environment variable
+2. OS standard cache directory (via `platformdirs`)
+3. Fallback path
+
+Examples:
+
+* macOS: `~/Library/Caches/cadis`
+* Linux: `~/.cache/cadis`
+* Windows: `%LOCALAPPDATA%\\cadis\\Cache`
+
+---
+
+## Design Principles
+
+* Facade-only orchestration
+* Lazy initialization
+* Deterministic behavior
+* Minimal public surface
+* Stable error contract
+
+---
+
+## Versioning
+
+`cadis` version represents the public API contract.
+
+It does **not** represent dataset version or internal runtime version.
+
+---
+
+## License
+
+MIT

cadis-0.1.0/README.md

@@ -0,0 +1,155 @@
+# cadis
+
+`cadis` is the public facade entrypoint of the Cadis system.
+
+It provides a zero-configuration global lookup interface while hiding
+runtime, dataset, and bootstrap orchestration details.
+
+`cadis` is **not** a runtime, dataset engine, or CDN client.
+It is a thin facade layer built on top of `cadis-global`.
+
+---
+
+## Install
+
+```bash
+pip install cadis
+```
+
+---
+
+## Quick Start
+
+```python
+from cadis import lookup, info
+
+result = lookup(25.0330, 121.5654)
+print(result["lookup_status"])
+
+print(info())
+```
+
+---
+
+## CLI
+
+`cadis` also provides a minimal CLI entrypoint:
+
+```bash
+cadis lookup <lat> <lon>
+cadis lookup <lat> <lon> --json
+cadis info
+```
+
+Examples:
+
+```bash
+cadis lookup 25.0330 121.5654
+```
+
+```bash
+cadis lookup 25.0330 121.5654 --json
+```
+
+```bash
+cadis info
+```
+
+CLI mode semantics (v0.1):
+
+* `lookup` calls the same `cadis.lookup()` API as Python mode.
+* Default `lookup` output is human-friendly status text.
+* `lookup --json` prints the full API envelope as JSON.
+* `info` prints the full `cadis.info()` payload as JSON.
+* CLI does not add bootstrap/download orchestration logic.
+
+---
+
+## Public API
+
+### `lookup(lat: float, lon: float) -> dict`
+
+Zero-configuration lookup entrypoint.
+
+Behavior:
+
+* Lazy initialization on first call
+* No network or bootstrap work at import time
+* Deterministic response envelope
+* Stable public error semantics
+
+---
+
+### `info() -> dict`
+
+Returns capability metadata for the current environment.
+
+The output includes:
+
+* `version`: public API version
+* `system_iso2`: ISO2 codes available to this installation
+* `offline_iso2`: ISO2 datasets currently available in local cache
+
+Example:
+
+```json
+{
+  "schema_version": "1",
+  "version": "0.1.0",
+  "system_iso2": ["JP", "TW"],
+  "offline_iso2": ["TW"]
+}
+```
+
+`info()` has no side effects and performs no network operations.
+
+---
+
+## Architecture
+
+```text
+cadis (facade)
+  -> cadis-global
+    -> cadis-runtime
+      -> cadis-core + cadis-cdn
+```
+
+---
+
+## Cache Policy
+
+Cache directory resolution order:
+
+1. `CADIS_CACHE_DIR` environment variable
+2. OS standard cache directory (via `platformdirs`)
+3. Fallback path
+
+Examples:
+
+* macOS: `~/Library/Caches/cadis`
+* Linux: `~/.cache/cadis`
+* Windows: `%LOCALAPPDATA%\\cadis\\Cache`
+
+---
+
+## Design Principles
+
+* Facade-only orchestration
+* Lazy initialization
+* Deterministic behavior
+* Minimal public surface
+* Stable error contract
+
+---
+
+## Versioning
+
+`cadis` version represents the public API contract.
+
+It does **not** represent dataset version or internal runtime version.
+
+---
+
+## License
+
+MIT

cadis-0.1.0/cadis/__init__.py

@@ -0,0 +1,6 @@
+"""Public facade for Cadis global lookup."""
+
+from ._api import info, lookup
+
+__all__ = ["lookup", "info"]
+__version__ = "0.1.0"

cadis-0.1.0/cadis/_api.py

@@ -0,0 +1,99 @@
+"""Public API facade for cadis."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ._cache import resolve_cache_dir
+from ._errors import normalize_reason
+from ._manager import get_manager
+
+SCHEMA_VERSION = "1"
+VERSION = "0.1.0"
+
+
+def _to_iso2_list(value: Any) -> list[str]:
+    if isinstance(value, (list, tuple, set)):
+        return sorted({str(v).upper() for v in value if str(v).strip()})
+    return []
+
+
+def _global_info_probe() -> tuple[list[str], list[str]]:
+    """Best-effort static info probe with no lookup/bootstrap side effects."""
+    system_iso2: list[str] = []
+    offline_iso2: list[str] = _offline_iso2_from_cache()
+
+    try:
+        import cadis_global as module
+    except Exception:
+        return system_iso2, offline_iso2
+
+    for attr_name in ("SYSTEM_ISO2", "DEFAULT_ISO2", "SUPPORTED_ISO2"):
+        if not system_iso2 and hasattr(module, attr_name):
+            system_iso2 = _to_iso2_list(getattr(module, attr_name))
+
+    return system_iso2, offline_iso2
+
+
+def _offline_iso2_from_cache() -> list[str]:
+    """Derive cached ISO2s from local cache directory names."""
+    path = resolve_cache_dir()
+    if not path.exists() or not path.is_dir():
+        return []
+
+    iso2: list[str] = []
+    for child in path.iterdir():
+        if child.is_dir() and re.fullmatch(r"[A-Za-z]{2}", child.name):
+            iso2.append(child.name.upper())
+
+    return sorted(set(iso2))
+
+
+def _failure_envelope(reason: Any) -> dict[str, Any]:
+    return {
+        "lookup_status": "failed",
+        "engine": "cadis",
+        "version": VERSION,
+        "reason": normalize_reason(reason),
+        "world_context": None,
+        "admin_result": None,
+    }
+
+
+def lookup(lat: float, lon: float) -> dict[str, Any]:
+    if not isinstance(lat, (float, int)) or not isinstance(lon, (float, int)):
+        return _failure_envelope(ValueError("invalid coordinate type"))
+    if lat < -90 or lat > 90 or lon < -180 or lon > 180:
+        return _failure_envelope(ValueError("invalid coordinate range"))
+
+    manager = get_manager()
+
+    try:
+        global_lookup = manager.get_or_init()
+        result = global_lookup.lookup(float(lat), float(lon))
+    except Exception as exc:
+        return _failure_envelope(exc)
+
+    if not isinstance(result, dict):
+        return _failure_envelope("runtime_invalid_response")
+
+    payload = dict(result)
+    payload["engine"] = "cadis"
+    payload["version"] = VERSION
+
+    reason = payload.get("reason")
+    if reason is not None:
+        payload["reason"] = normalize_reason(reason)
+
+    return payload
+
+
+def info() -> dict[str, Any]:
+    system_iso2, offline_iso2 = _global_info_probe()
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "version": VERSION,
+        "system_iso2": system_iso2,
+        "offline_iso2": offline_iso2,
+    }

cadis-0.1.0/cadis/_cache.py

@@ -0,0 +1,27 @@
+"""Cache directory resolution for the cadis facade."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from platformdirs import user_cache_dir
+
+_ENV_CACHE_DIR = "CADIS_CACHE_DIR"
+_FALLBACK_CACHE_DIR = Path.home() / ".cache" / "cadis"
+
+
+def resolve_cache_dir() -> Path:
+    """Resolve cache path from env, OS defaults, then fallback."""
+    env_value = os.getenv(_ENV_CACHE_DIR)
+    if env_value and env_value.strip():
+        return Path(env_value).expanduser()
+
+    try:
+        cache_dir = user_cache_dir(appname="cadis", appauthor="cadis")
+        if cache_dir:
+            return Path(cache_dir).expanduser()
+    except Exception:
+        pass
+
+    return _FALLBACK_CACHE_DIR

cadis-0.1.0/cadis/_cli.py

@@ -0,0 +1,66 @@
+"""Command-line interface for cadis."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Any, Sequence
+
+from . import info as api_info
+from . import lookup as api_lookup
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="cadis")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    lookup_parser = subparsers.add_parser("lookup")
+    lookup_parser.add_argument("lat", type=float)
+    lookup_parser.add_argument("lon", type=float)
+    lookup_parser.add_argument("--json", action="store_true", dest="as_json")
+
+    subparsers.add_parser("info")
+    return parser
+
+
+def _print_json(payload: Any) -> None:
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def _print_lookup_human(payload: dict[str, Any]) -> int:
+    status = payload.get("lookup_status")
+    reason = payload.get("reason")
+
+    if status == "failed":
+        message = reason if isinstance(reason, str) and reason else "unknown_error"
+        print(f"Lookup failed: {message}")
+        return 1
+
+    if status == "partial":
+        message = reason if isinstance(reason, str) and reason else "partial_result"
+        print(f"Lookup partial: {message}")
+        return 0
+
+    print("Lookup succeeded")
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "info":
+        _print_json(api_info())
+        return 0
+
+    payload = api_lookup(args.lat, args.lon)
+
+    if args.as_json:
+        _print_json(payload)
+        return 0
+
+    if isinstance(payload, dict):
+        return _print_lookup_human(payload)
+
+    print("Lookup failed: internal_error")
+    return 1

cadis-0.1.0/cadis/_errors.py

@@ -0,0 +1,38 @@
+"""Stable reason normalization for cadis public envelopes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+KNOWN_REASONS = {
+    "unsupported_country_dataset",
+    "missing_dataset",
+    "runtime_bootstrap_error",
+    "runtime_dispatch_error",
+    "runtime_invalid_response",
+    "admin_interpretation_unavailable",
+    "world_resolution_error",
+    "invalid_input",
+    "global_lookup_unavailable",
+    "global_init_failed",
+    "lookup_failed",
+    "internal_error",
+}
+
+
+def normalize_reason(reason: Any) -> str:
+    """Return a stable public reason code."""
+    if isinstance(reason, str) and reason in KNOWN_REASONS:
+        return reason
+
+    if isinstance(reason, ValueError):
+        return "invalid_input"
+    if isinstance(reason, ImportError):
+        return "global_lookup_unavailable"
+    if isinstance(reason, RuntimeError):
+        return "global_init_failed"
+
+    if isinstance(reason, str):
+        return "lookup_failed"
+
+    return "internal_error"

cadis-0.1.0/cadis/_manager.py

@@ -0,0 +1,52 @@
+"""Internal singleton manager around cadis-global."""
+
+from __future__ import annotations
+
+import threading
+from pathlib import Path
+
+from ._cache import resolve_cache_dir
+from ._errors import normalize_reason
+
+
+class CadisManager:
+    """Process-level manager for a single GlobalLookup instance."""
+
+    def __init__(self) -> None:
+        self._lookup = None
+        self._lock = threading.Lock()
+
+    def is_initialized(self) -> bool:
+        return self._lookup is not None
+
+    def get_or_init(self):
+        if self._lookup is not None:
+            return self._lookup
+
+        with self._lock:
+            if self._lookup is not None:
+                return self._lookup
+
+            try:
+                from cadis_global import GlobalLookup
+            except Exception as exc:  # pragma: no cover - exercised via tests with import stubs
+                raise ImportError(normalize_reason(exc)) from None
+
+            cache_dir: Path = resolve_cache_dir()
+
+            try:
+                self._lookup = GlobalLookup.from_defaults(
+                    cache_dir=cache_dir,
+                    update_to_latest=False,
+                )
+            except Exception as exc:
+                raise RuntimeError(normalize_reason(exc)) from None
+
+            return self._lookup
+
+
+_MANAGER = CadisManager()
+
+
+def get_manager() -> CadisManager:
+    return _MANAGER

cadis-0.1.0/cadis.egg-info/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: cadis
+Version: 0.1.0
+Summary: Public facade entrypoint for Cadis global lookup
+Author: Cadis
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cadis-global>=0.1.0
+Requires-Dist: platformdirs>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# cadis
+
+`cadis` is the public facade entrypoint of the Cadis system.
+
+It provides a zero-configuration global lookup interface while hiding
+runtime, dataset, and bootstrap orchestration details.
+
+`cadis` is **not** a runtime, dataset engine, or CDN client.
+It is a thin facade layer built on top of `cadis-global`.
+
+---
+
+## Install
+
+```bash
+pip install cadis
+```
+
+---
+
+## Quick Start
+
+```python
+from cadis import lookup, info
+
+result = lookup(25.0330, 121.5654)
+print(result["lookup_status"])
+
+print(info())
+```
+
+---
+
+## CLI
+
+`cadis` also provides a minimal CLI entrypoint:
+
+```bash
+cadis lookup <lat> <lon>
+cadis lookup <lat> <lon> --json
+cadis info
+```
+
+Examples:
+
+```bash
+cadis lookup 25.0330 121.5654
+```
+
+```bash
+cadis lookup 25.0330 121.5654 --json
+```
+
+```bash
+cadis info
+```
+
+CLI mode semantics (v0.1):
+
+* `lookup` calls the same `cadis.lookup()` API as Python mode.
+* Default `lookup` output is human-friendly status text.
+* `lookup --json` prints the full API envelope as JSON.
+* `info` prints the full `cadis.info()` payload as JSON.
+* CLI does not add bootstrap/download orchestration logic.
+
+---
+
+## Public API
+
+### `lookup(lat: float, lon: float) -> dict`
+
+Zero-configuration lookup entrypoint.
+
+Behavior:
+
+* Lazy initialization on first call
+* No network or bootstrap work at import time
+* Deterministic response envelope
+* Stable public error semantics
+
+---
+
+### `info() -> dict`
+
+Returns capability metadata for the current environment.
+
+The output includes:
+
+* `version`: public API version
+* `system_iso2`: ISO2 codes available to this installation
+* `offline_iso2`: ISO2 datasets currently available in local cache
+
+Example:
+
+```json
+{
+  "schema_version": "1",
+  "version": "0.1.0",
+  "system_iso2": ["JP", "TW"],
+  "offline_iso2": ["TW"]
+}
+```
+
+`info()` has no side effects and performs no network operations.
+
+---
+
+## Architecture
+
+```text
+cadis (facade)
+  -> cadis-global
+    -> cadis-runtime
+      -> cadis-core + cadis-cdn
+```
+
+---
+
+## Cache Policy
+
+Cache directory resolution order:
+
+1. `CADIS_CACHE_DIR` environment variable
+2. OS standard cache directory (via `platformdirs`)
+3. Fallback path
+
+Examples:
+
+* macOS: `~/Library/Caches/cadis`
+* Linux: `~/.cache/cadis`
+* Windows: `%LOCALAPPDATA%\\cadis\\Cache`
+
+---
+
+## Design Principles
+
+* Facade-only orchestration
+* Lazy initialization
+* Deterministic behavior
+* Minimal public surface
+* Stable error contract
+
+---
+
+## Versioning
+
+`cadis` version represents the public API contract.
+
+It does **not** represent dataset version or internal runtime version.
+
+---
+
+## License
+
+MIT

cadis-0.1.0/cadis.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+cadis/__init__.py
+cadis/_api.py
+cadis/_cache.py
+cadis/_cli.py
+cadis/_errors.py
+cadis/_manager.py
+cadis.egg-info/PKG-INFO
+cadis.egg-info/SOURCES.txt
+cadis.egg-info/dependency_links.txt
+cadis.egg-info/entry_points.txt
+cadis.egg-info/requires.txt
+cadis.egg-info/top_level.txt
+tests/test_cadis.py
+tests/test_cli.py
+tests/test_errors.py

cadis-0.1.0/cadis.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cadis-0.1.0/cadis.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cadis = cadis._cli:main

cadis-0.1.0/cadis.egg-info/requires.txt

@@ -0,0 +1,5 @@
+cadis-global>=0.1.0
+platformdirs>=4.0
+
+[dev]
+pytest>=8.0

cadis-0.1.0/cadis.egg-info/top_level.txt

@@ -0,0 +1 @@
+cadis

cadis-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cadis"
+version = "0.1.0"
+description = "Public facade entrypoint for Cadis global lookup"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Cadis" }]
+dependencies = [
+  "cadis-global>=0.1.0",
+  "platformdirs>=4.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+]
+
+[project.scripts]
+cadis = "cadis._cli:main"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+include = ["cadis*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

cadis-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cadis-0.1.0/tests/test_cadis.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import importlib
+import sys
+from types import ModuleType
+
+
+class _FakeLookup:
+    def __init__(self) -> None:
+        self.calls = []
+
+    def lookup(self, lat: float, lon: float):
+        self.calls.append((lat, lon))
+        return {
+            "lookup_status": "ok",
+            "reason": None,
+            "world_context": {"iso2": "TW"},
+            "admin_result": {"ok": True},
+        }
+
+
+class _FakeGlobalLookup:
+    init_calls = 0
+
+    @classmethod
+    def from_defaults(cls, **kwargs):
+        cls.init_calls += 1
+        return _FakeLookup()
+
+
+def _install_fake_cadis_global(module: ModuleType) -> None:
+    sys.modules["cadis_global"] = module
+
+
+def _reload_cadis_modules() -> None:
+    for name in ["cadis", "cadis._api", "cadis._manager"]:
+        sys.modules.pop(name, None)
+
+
+def test_lookup_is_lazy_singleton(monkeypatch):
+    fake_mod = ModuleType("cadis_global")
+    fake_mod.GlobalLookup = _FakeGlobalLookup
+
+    _install_fake_cadis_global(fake_mod)
+    _reload_cadis_modules()
+
+    cadis = importlib.import_module("cadis")
+    assert _FakeGlobalLookup.init_calls == 0
+
+    first = cadis.lookup(25.03, 121.56)
+    second = cadis.lookup(35.68, 139.76)
+
+    assert _FakeGlobalLookup.init_calls == 1
+    assert first["lookup_status"] == "ok"
+    assert second["lookup_status"] == "ok"
+
+
+def test_info_has_no_lookup_side_effect(monkeypatch, tmp_path):
+    class _NoInitGlobalLookup:
+        @classmethod
+        def from_defaults(cls, **kwargs):
+            raise AssertionError("from_defaults must not be called by info()")
+
+    fake_mod = ModuleType("cadis_global")
+    fake_mod.GlobalLookup = _NoInitGlobalLookup
+    fake_mod.SUPPORTED_ISO2 = ["tw", "jp"]
+
+    cache_dir = tmp_path / "cadis-cache"
+    cache_dir.mkdir()
+    (cache_dir / "tw").mkdir()
+    (cache_dir / "not-iso").mkdir()
+    monkeypatch.setenv("CADIS_CACHE_DIR", str(cache_dir))
+
+    _install_fake_cadis_global(fake_mod)
+    _reload_cadis_modules()
+
+    cadis = importlib.import_module("cadis")
+    payload = cadis.info()
+
+    assert payload["schema_version"] == "1"
+    assert payload["system_iso2"] == ["JP", "TW"]
+    assert payload["offline_iso2"] == ["TW"]
+
+
+def test_reason_normalization_runtime_error(monkeypatch):
+    class _BrokenGlobalLookup:
+        @classmethod
+        def from_defaults(cls, **kwargs):
+            raise Exception("boom")
+
+    fake_mod = ModuleType("cadis_global")
+    fake_mod.GlobalLookup = _BrokenGlobalLookup
+
+    _install_fake_cadis_global(fake_mod)
+    _reload_cadis_modules()
+
+    cadis = importlib.import_module("cadis")
+    payload = cadis.lookup(25.03, 121.56)
+
+    assert payload["lookup_status"] == "failed"
+    assert payload["reason"] in {"global_init_failed", "internal_error"}
+    assert "traceback" not in str(payload).lower()

cadis-0.1.0/tests/test_cli.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import json
+
+from cadis import _cli
+
+
+def test_lookup_json_passthrough(monkeypatch, capsys):
+    payload = {
+        "lookup_status": "ok",
+        "engine": "cadis",
+        "version": "0.1.0",
+        "reason": None,
+        "world_context": {"iso2": "TW"},
+        "admin_result": {"name": "Xinyi District"},
+    }
+    monkeypatch.setattr(_cli, "api_lookup", lambda lat, lon: payload)
+
+    code = _cli.main(["lookup", "25.0330", "121.5654", "--json"])
+    out = capsys.readouterr().out
+
+    assert code == 0
+    assert json.loads(out) == payload
+
+
+def test_lookup_failed_human(monkeypatch, capsys):
+    monkeypatch.setattr(
+        _cli,
+        "api_lookup",
+        lambda lat, lon: {"lookup_status": "failed", "reason": "missing_dataset"},
+    )
+
+    code = _cli.main(["lookup", "25.0330", "121.5654"])
+    out = capsys.readouterr().out
+
+    assert code == 1
+    assert out.strip() == "Lookup failed: missing_dataset"
+
+
+def test_lookup_partial_human(monkeypatch, capsys):
+    monkeypatch.setattr(
+        _cli,
+        "api_lookup",
+        lambda lat, lon: {"lookup_status": "partial", "reason": "missing_dataset"},
+    )
+
+    code = _cli.main(["lookup", "25.0330", "121.5654"])
+    out = capsys.readouterr().out
+
+    assert code == 0
+    assert out.strip() == "Lookup partial: missing_dataset"
+
+
+def test_info_json_passthrough(monkeypatch, capsys):
+    payload = {
+        "schema_version": "1",
+        "version": "0.1.0",
+        "system_iso2": ["JP", "TW"],
+        "offline_iso2": ["TW"],
+    }
+    monkeypatch.setattr(_cli, "api_info", lambda: payload)
+
+    code = _cli.main(["info"])
+    out = capsys.readouterr().out
+
+    assert code == 0
+    assert json.loads(out) == payload

cadis-0.1.0/tests/test_errors.py

@@ -0,0 +1,8 @@
+from cadis._errors import normalize_reason
+
+
+def test_normalize_reason_map():
+    assert normalize_reason("missing_dataset") == "missing_dataset"
+    assert normalize_reason(ValueError("bad")) == "invalid_input"
+    assert normalize_reason(RuntimeError("broken")) == "global_init_failed"
+    assert normalize_reason(Exception("x")) == "internal_error"