py-cloudip 0.1.0__py3-none-any.whl

cloudip/__init__.py

@@ -0,0 +1,166 @@
+"""py-cloudip — fast cloud-provider IP detection.
+
+Detect whether an IP address belongs to AWS, GCP, Azure, Cloudflare,
+DigitalOcean, or Oracle Cloud. Data comes from the rezmoss/cloudip-db database
+(network fetch with SHA-256 verification, on-disk cache, and an embedded
+offline fallback).
+
+Quick start::
+
+    import cloudip
+    cloudip.is_aws("52.94.76.1")        # True
+    cloudip.get_provider("34.64.0.1")   # "gcp"
+    cloudip.lookup("52.94.76.1")        # LookupResult(found=True, provider="aws", ...)
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import List, Optional, Union
+
+from .constants import (
+    PROVIDER_AWS,
+    PROVIDER_AZURE,
+    PROVIDER_CLOUDFLARE,
+    PROVIDER_DIGITALOCEAN,
+    PROVIDER_GCP,
+    PROVIDER_ORACLE,
+)
+from .detector import Detector, load_version, new_detector
+from .types import (
+    CheckUpdateResult,
+    Database,
+    IPEntry,
+    LookupResult,
+    Provider,
+    Range,
+    VersionInfo,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Detector",
+    "new_detector",
+    "lookup",
+    "get_provider",
+    "is_cloud_provider",
+    "is_aws",
+    "is_gcp",
+    "is_azure",
+    "is_cloudflare",
+    "is_digitalocean",
+    "is_oracle",
+    "get_ips",
+    "version",
+    "range_count",
+    "providers",
+    "update",
+    "check_update",
+    "clear_cache",
+    "remote_version",
+    "CheckUpdateResult",
+    "Database",
+    "IPEntry",
+    "LookupResult",
+    "Provider",
+    "Range",
+    "VersionInfo",
+    "PROVIDER_AWS",
+    "PROVIDER_GCP",
+    "PROVIDER_AZURE",
+    "PROVIDER_CLOUDFLARE",
+    "PROVIDER_DIGITALOCEAN",
+    "PROVIDER_ORACLE",
+]
+
+_default: Optional[Detector] = None
+_default_lock = threading.Lock()
+
+
+def _get_default() -> Detector:
+    global _default
+    if _default is not None:
+        return _default
+    with _default_lock:
+        if _default is None:
+            _default = new_detector()
+    return _default
+
+
+def lookup(ip: str) -> LookupResult:
+    return _get_default().lookup(ip)
+
+
+def get_provider(ip: str) -> Provider:
+    return _get_default().get_provider(ip)
+
+
+def is_cloud_provider(ip: str) -> bool:
+    return _get_default().is_cloud_provider(ip)
+
+
+def is_aws(ip: str) -> bool:
+    return _get_default().is_aws(ip)
+
+
+def is_gcp(ip: str) -> bool:
+    return _get_default().is_gcp(ip)
+
+
+def is_azure(ip: str) -> bool:
+    return _get_default().is_azure(ip)
+
+
+def is_cloudflare(ip: str) -> bool:
+    return _get_default().is_cloudflare(ip)
+
+
+def is_digitalocean(ip: str) -> bool:
+    return _get_default().is_digitalocean(ip)
+
+
+def is_oracle(ip: str) -> bool:
+    return _get_default().is_oracle(ip)
+
+
+def get_ips(
+    providers: Optional[Union[Provider, List[Provider]]] = None
+) -> List[IPEntry]:
+    return _get_default().get_ips(providers)
+
+
+def version() -> str:
+    return _get_default().version()
+
+
+def range_count() -> int:
+    return _get_default().range_count()
+
+
+def providers() -> List[Provider]:
+    return _get_default().providers()
+
+
+def update() -> None:
+    _get_default().update()
+
+
+def check_update() -> CheckUpdateResult:
+    return _get_default().check_update()
+
+
+def remote_version(version_url: Optional[str] = None) -> VersionInfo:
+    if version_url is None:
+        from .constants import DEFAULT_VERSION_URL
+
+        version_url = DEFAULT_VERSION_URL
+    return load_version(version_url)
+
+
+def clear_cache() -> None:
+    global _default
+    if _default is not None:
+        _default.clear_cache()
+        _default.close()
+    _default = None

cloudip/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cloudip/cache.py

@@ -0,0 +1,75 @@
+"""On-disk caching of the downloaded database under a user cache directory."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import time
+from pathlib import Path
+from typing import NamedTuple, Optional
+
+_DATA_FILE = "cloudip.msgpack.gz"
+_META_FILE = "version.json"
+
+
+class CachedData(NamedTuple):
+    version: str
+    bytes: bytes
+
+
+def _default_cache_dir() -> str:
+    base = (
+        os.environ.get("XDG_CACHE_HOME")
+        or os.path.join(os.path.expanduser("~"), ".cache")
+    )
+    return os.path.join(base, "py-cloudip")
+
+
+def resolve_cache_dir(dir: Optional[str]) -> Optional[str]:
+    """``None`` disables caching; an unset (sentinel) value uses the default dir."""
+    if dir is None:
+        return None
+    if dir == "":
+        return _default_cache_dir()
+    return dir
+
+
+def read_cache(dir: str) -> Optional[CachedData]:
+    try:
+        p = Path(dir)
+        data = (p / _DATA_FILE).read_bytes()
+        meta = json.loads((p / _META_FILE).read_text("utf-8"))
+        return CachedData(version=meta.get("version", ""), bytes=data)
+    except (OSError, ValueError):
+        return None
+
+
+def write_cache(dir: str, version: str, data: bytes) -> None:
+    try:
+        p = Path(dir)
+        p.mkdir(parents=True, exist_ok=True)
+        (p / _DATA_FILE).write_bytes(data)
+        (p / _META_FILE).write_text(
+            json.dumps({"version": version, "stored_at": time.time()})
+        )
+    except OSError:
+        pass  # best-effort
+
+
+def cache_age_seconds(dir: str) -> Optional[float]:
+    try:
+        meta = json.loads((Path(dir) / _META_FILE).read_text("utf-8"))
+        return time.time() - float(meta["stored_at"])
+    except (OSError, ValueError, KeyError):
+        return None
+
+
+def clear_cache(dir: Optional[str]) -> None:
+    resolved = resolve_cache_dir(dir if dir is not None else "")
+    if not resolved:
+        return
+    try:
+        shutil.rmtree(resolved, ignore_errors=True)
+    except OSError:
+        pass

cloudip/cli.py

@@ -0,0 +1,105 @@
+"""Command-line interface: ``cloudip <command> [args]``."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import List
+
+from . import (
+    check_update,
+    clear_cache,
+    get_ips,
+    get_provider,
+    lookup,
+    providers,
+    range_count,
+    update,
+    version,
+)
+
+HELP = """cloudip — cloud provider IP utilities (py-cloudip)
+
+Usage:
+  cloudip lookup <ip>                Reverse-lookup an IP address
+  cloudip get <provider>[,...]       Print CIDRs for one or more providers
+  cloudip provider <ip>              Print provider name for an IP
+  cloudip providers                  List supported providers
+  cloudip version                    Print local data version + range count
+  cloudip check-update               Check if a newer upstream version exists
+  cloudip update                     Force a refresh from cloudip-db
+  cloudip clear-cache                Delete the local cache
+  cloudip help                       Show this help
+
+Data source: rezmoss/cloudip-db
+"""
+
+
+def main(argv: List[str] = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    cmd = argv[0] if argv else None
+    args = argv[1:]
+
+    if cmd in (None, "help", "-h", "--help"):
+        sys.stdout.write(HELP)
+        return 0
+
+    try:
+        if cmd == "lookup":
+            if not args:
+                raise ValueError("usage: cloudip lookup <ip>")
+            r = lookup(args[0])
+            print(json.dumps(r.to_dict(), indent=2))
+            return 0 if r.found else 1
+
+        if cmd == "provider":
+            if not args:
+                raise ValueError("usage: cloudip provider <ip>")
+            p = get_provider(args[0])
+            if not p:
+                print("unknown")
+                return 1
+            print(p)
+            return 0
+
+        if cmd == "get":
+            if not args:
+                raise ValueError("usage: cloudip get <provider>[,<provider>]")
+            want = [s.strip() for s in args[0].split(",") if s.strip()]
+            for e in get_ips(want):
+                print(e.ip_address)
+            return 0
+
+        if cmd == "providers":
+            for p in providers():
+                print(p)
+            return 0
+
+        if cmd == "version":
+            print(f"{version()} ({range_count()} ranges)")
+            return 0
+
+        if cmd == "check-update":
+            result = check_update()
+            print(json.dumps(result.to_dict(), indent=2))
+            return 0 if result.has_update else 1
+
+        if cmd == "update":
+            update()
+            print("updated")
+            return 0
+
+        if cmd == "clear-cache":
+            clear_cache()
+            print("cache cleared")
+            return 0
+
+        sys.stderr.write(f"unknown command: {cmd}\n{HELP}")
+        return 2
+    except Exception as err:  # noqa: BLE001
+        sys.stderr.write(f"error: {err}\n")
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cloudip/constants.py

@@ -0,0 +1,15 @@
+"""Shared constants: provider names, default URLs, and timing defaults."""
+
+PROVIDER_AWS = "aws"
+PROVIDER_GCP = "gcp"
+PROVIDER_AZURE = "azure"
+PROVIDER_CLOUDFLARE = "cloudflare"
+PROVIDER_DIGITALOCEAN = "digitalocean"
+PROVIDER_ORACLE = "oracle"
+
+DEFAULT_BASE_URL = "https://raw.githubusercontent.com/rezmoss/cloudip-db/main/data"
+DEFAULT_DATA_URL = f"{DEFAULT_BASE_URL}/cloudip.msgpack.gz"
+DEFAULT_VERSION_URL = f"{DEFAULT_BASE_URL}/version.json"
+
+HOUR_SECONDS = 60 * 60
+DEFAULT_TTL_SECONDS = 24 * HOUR_SECONDS

cloudip/decode.py

@@ -0,0 +1,44 @@
+"""Decompress + msgpack-decode the database, plus hashing helpers."""
+
+from __future__ import annotations
+
+import gzip
+import hashlib
+
+import msgpack
+
+from .types import Database, Range
+
+
+def gunzip(buf: bytes) -> bytes:
+    return gzip.decompress(buf)
+
+
+def sha256_hex(buf: bytes) -> str:
+    return hashlib.sha256(buf).hexdigest()
+
+
+def decode_database(gz_buf: bytes) -> Database:
+    """Decode a gzipped MessagePack database into a :class:`Database`."""
+    raw = gunzip(gz_buf)
+    obj = msgpack.unpackb(raw, raw=False)
+    providers = list(obj["providers"])
+    ranges = []
+    for r in obj["ranges"]:
+        idx = r["p"]
+        if idx < 0 or idx >= len(providers):
+            raise ValueError(f"cloudip: unknown provider index {idx}")
+        ranges.append(
+            Range(
+                cidr=r["cidr"],
+                provider=providers[idx],
+                region=r.get("r") or None,
+                service=r.get("s") or None,
+            )
+        )
+    return Database(
+        version=obj.get("version", ""),
+        build_time=int(obj.get("build_time", 0)),
+        providers=providers,
+        ranges=ranges,
+    )

cloudip/detector.py

@@ -0,0 +1,296 @@
+"""The Detector: loads data (network -> cache -> embedded) and answers lookups."""
+
+from __future__ import annotations
+
+import threading
+from typing import Dict, List, Optional, Union
+
+from .cache import (
+    cache_age_seconds,
+    clear_cache,
+    read_cache,
+    resolve_cache_dir,
+    write_cache,
+)
+from .constants import (
+    DEFAULT_DATA_URL,
+    DEFAULT_TTL_SECONDS,
+    DEFAULT_VERSION_URL,
+    HOUR_SECONDS,
+    PROVIDER_AWS,
+    PROVIDER_AZURE,
+    PROVIDER_CLOUDFLARE,
+    PROVIDER_DIGITALOCEAN,
+    PROVIDER_GCP,
+    PROVIDER_ORACLE,
+)
+from .decode import decode_database
+from .embedded_loader import load_embedded_gz
+from .source import fetch_data, fetch_version
+from .trie import CIDRTrie
+from .types import (
+    CheckUpdateResult,
+    Database,
+    IPEntry,
+    LookupResult,
+    Provider,
+    VersionInfo,
+)
+
+# Sentinel distinguishing "use default cache dir" from "caching disabled" (None).
+_DEFAULT_DIR = ""
+
+
+class _State:
+    __slots__ = ("db", "trie", "by_provider")
+
+    def __init__(self, db: Database, trie: CIDRTrie, by_provider: Dict[str, List[IPEntry]]):
+        self.db = db
+        self.trie = trie
+        self.by_provider = by_provider
+
+
+def _build_state(db: Database) -> _State:
+    trie = CIDRTrie()
+    by_provider: Dict[str, List[IPEntry]] = {}
+    for r in db.ranges:
+        trie.insert(r)
+        key = r.provider.lower()
+        entry = IPEntry(
+            ip_address=r.cidr,
+            ip_type="ipv6" if ":" in r.cidr else "ipv4",
+            provider=r.provider,
+            region=r.region,
+            service=r.service,
+        )
+        by_provider.setdefault(key, []).append(entry)
+    return _State(db, trie, by_provider)
+
+
+class Detector:
+    """Detects which cloud provider (if any) owns a given IP address.
+
+    Create one with :func:`new_detector` (which loads data eagerly), or construct
+    directly and call :meth:`ready` before use.
+    """
+
+    def __init__(
+        self,
+        data_dir: Optional[str] = _DEFAULT_DIR,
+        auto_update_seconds: float = 0,
+        offline: bool = False,
+        data_url: str = DEFAULT_DATA_URL,
+        version_url: str = DEFAULT_VERSION_URL,
+        verify_sha256: bool = True,
+        ttl_seconds: float = DEFAULT_TTL_SECONDS,
+        timeout: float = 30.0,
+    ) -> None:
+        # An auto-update interval under an hour is clamped up to one hour.
+        if 0 < auto_update_seconds < HOUR_SECONDS:
+            auto_update_seconds = HOUR_SECONDS
+        self._data_dir = resolve_cache_dir(data_dir)
+        self._auto_update_seconds = auto_update_seconds
+        self._offline = offline
+        self._data_url = data_url
+        self._version_url = version_url
+        self._verify_sha256 = verify_sha256
+        self._ttl_seconds = ttl_seconds
+        self._timeout = timeout
+
+        self._state: Optional[_State] = None
+        self._lock = threading.RLock()
+        self._stop_event: Optional[threading.Event] = None
+        self._timer_thread: Optional[threading.Thread] = None
+
+    # -- lifecycle -------------------------------------------------------
+
+    def ready(self) -> "Detector":
+        with self._lock:
+            if self._state is not None:
+                return self
+            self._load_initial()
+        if self._auto_update_seconds > 0 and not self._offline:
+            self._start_auto_update()
+        return self
+
+    def close(self) -> None:
+        if self._stop_event is not None:
+            self._stop_event.set()
+        self._timer_thread = None
+
+    def __enter__(self) -> "Detector":
+        return self.ready()
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    def _start_auto_update(self) -> None:
+        self._stop_event = threading.Event()
+        interval = self._auto_update_seconds
+
+        def _run() -> None:
+            assert self._stop_event is not None
+            while not self._stop_event.wait(interval):
+                try:
+                    self.update()
+                except Exception:
+                    pass  # background refresh is best-effort
+
+        self._timer_thread = threading.Thread(
+            target=_run, name="cloudip-auto-update", daemon=True
+        )
+        self._timer_thread.start()
+
+    # -- data loading ----------------------------------------------------
+
+    def _load_initial(self) -> None:
+        if not self._offline:
+            try:
+                fresh = fetch_data(
+                    self._data_url,
+                    self._version_url,
+                    self._verify_sha256,
+                    timeout=self._timeout,
+                )
+                self._state = _build_state(decode_database(fresh.bytes))
+                if self._data_dir:
+                    write_cache(self._data_dir, fresh.version, fresh.bytes)
+                return
+            except Exception:
+                pass  # fall through to cache / embedded
+
+        if self._data_dir:
+            cached = read_cache(self._data_dir)
+            if cached:
+                age = cache_age_seconds(self._data_dir)
+                fresh_enough = age is not None and (
+                    self._offline or age <= self._ttl_seconds
+                )
+                # Use cache regardless of age when nothing else is available;
+                # being fresh just lets us skip without warning.
+                try:
+                    self._state = _build_state(decode_database(cached.bytes))
+                    if fresh_enough or True:
+                        return
+                except Exception:
+                    pass
+
+        embedded = load_embedded_gz()
+        if embedded is not None:
+            self._state = _build_state(decode_database(embedded))
+            return
+
+        raise RuntimeError(
+            "cloudip: no data available (network failed, no cache, no embedded data)"
+        )
+
+    def update(self) -> None:
+        if self._offline:
+            raise RuntimeError("cloudip: update disabled in offline mode")
+        fresh = fetch_data(
+            self._data_url,
+            self._version_url,
+            self._verify_sha256,
+            timeout=self._timeout,
+        )
+        state = _build_state(decode_database(fresh.bytes))
+        with self._lock:
+            self._state = state
+        if self._data_dir:
+            write_cache(self._data_dir, fresh.version, fresh.bytes)
+
+    def check_update(self) -> CheckUpdateResult:
+        if self._offline:
+            raise RuntimeError("cloudip: update check disabled in offline mode")
+        info = fetch_version(self._version_url, timeout=self._timeout)
+        local = self._state.db.version if self._state else ""
+        return CheckUpdateResult(has_update=info.version > local, info=info)
+
+    def clear_cache(self) -> None:
+        clear_cache(self._data_dir)
+
+    def _require_state(self) -> _State:
+        if self._state is None:
+            raise RuntimeError(
+                "cloudip: detector not ready — call detector.ready() first"
+            )
+        return self._state
+
+    # -- queries ---------------------------------------------------------
+
+    def lookup(self, ip: str) -> LookupResult:
+        r = self._require_state().trie.lookup(ip)
+        if r is None:
+            return LookupResult(found=False)
+        return LookupResult(
+            found=True,
+            provider=r.provider,
+            cidr=r.cidr,
+            ip_type="ipv6" if ":" in r.cidr else "ipv4",
+            region=r.region,
+            service=r.service,
+        )
+
+    def get_provider(self, ip: str) -> Provider:
+        return self.lookup(ip).provider or ""
+
+    def is_cloud_provider(self, ip: str) -> bool:
+        return self.lookup(ip).found
+
+    def is_aws(self, ip: str) -> bool:
+        return self.get_provider(ip) == PROVIDER_AWS
+
+    def is_gcp(self, ip: str) -> bool:
+        return self.get_provider(ip) == PROVIDER_GCP
+
+    def is_azure(self, ip: str) -> bool:
+        return self.get_provider(ip) == PROVIDER_AZURE
+
+    def is_cloudflare(self, ip: str) -> bool:
+        return self.get_provider(ip) == PROVIDER_CLOUDFLARE
+
+    def is_digitalocean(self, ip: str) -> bool:
+        return self.get_provider(ip) == PROVIDER_DIGITALOCEAN
+
+    def is_oracle(self, ip: str) -> bool:
+        return self.get_provider(ip) == PROVIDER_ORACLE
+
+    def get_ips(
+        self, providers: Optional[Union[Provider, List[Provider]]] = None
+    ) -> List[IPEntry]:
+        s = self._require_state()
+        if providers is None:
+            out: List[IPEntry] = []
+            for arr in s.by_provider.values():
+                out.extend(arr)
+            return out
+        want = [providers] if isinstance(providers, str) else list(providers)
+        out = []
+        for p in want:
+            hit = s.by_provider.get(p.lower())
+            if hit:
+                out.extend(hit)
+        return out
+
+    def version(self) -> str:
+        return self._state.db.version if self._state else ""
+
+    def build_time(self) -> int:
+        return self._state.db.build_time if self._state else 0
+
+    def range_count(self) -> int:
+        return len(self._state.db.ranges) if self._state else 0
+
+    def providers(self) -> List[Provider]:
+        return list(self._state.db.providers) if self._state else []
+
+
+def new_detector(**options) -> Detector:
+    """Construct a :class:`Detector` and load its data eagerly."""
+    return Detector(**options).ready()
+
+
+def load_version(
+    version_url: str = DEFAULT_VERSION_URL, timeout: float = 30.0
+) -> VersionInfo:
+    return fetch_version(version_url, timeout=timeout)

cloudip/embedded.py

@@ -0,0 +1,90 @@
+"""Offline-only entry point: uses the bundled database and never touches the network.
+
+Mirrors :mod:`cloudip` but the default detector is created with ``offline=True``
+and no on-disk cache, so it works in air-gapped environments::
+
+    from cloudip import embedded
+    embedded.is_aws("52.94.76.1")   # uses bundled data only
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import List, Optional, Union
+
+from .detector import Detector, new_detector
+from .types import IPEntry, LookupResult, Provider
+
+_default: Optional[Detector] = None
+_default_lock = threading.Lock()
+
+
+def _get_default() -> Detector:
+    global _default
+    if _default is not None:
+        return _default
+    with _default_lock:
+        if _default is None:
+            _default = new_detector(offline=True, data_dir=None)
+    return _default
+
+
+def lookup(ip: str) -> LookupResult:
+    return _get_default().lookup(ip)
+
+
+def get_provider(ip: str) -> Provider:
+    return _get_default().get_provider(ip)
+
+
+def is_cloud_provider(ip: str) -> bool:
+    return _get_default().is_cloud_provider(ip)
+
+
+def is_aws(ip: str) -> bool:
+    return _get_default().is_aws(ip)
+
+
+def is_gcp(ip: str) -> bool:
+    return _get_default().is_gcp(ip)
+
+
+def is_azure(ip: str) -> bool:
+    return _get_default().is_azure(ip)
+
+
+def is_cloudflare(ip: str) -> bool:
+    return _get_default().is_cloudflare(ip)
+
+
+def is_digitalocean(ip: str) -> bool:
+    return _get_default().is_digitalocean(ip)
+
+
+def is_oracle(ip: str) -> bool:
+    return _get_default().is_oracle(ip)
+
+
+def get_ips(
+    providers: Optional[Union[Provider, List[Provider]]] = None
+) -> List[IPEntry]:
+    return _get_default().get_ips(providers)
+
+
+def version() -> str:
+    return _get_default().version()
+
+
+def range_count() -> int:
+    return _get_default().range_count()
+
+
+def providers() -> List[Provider]:
+    return _get_default().providers()
+
+
+def age_days() -> float:
+    """Age of the bundled data in days, based on its build time."""
+    d = _get_default()
+    return (time.time() - d.build_time()) / 86400

cloudip/embedded_loader.py

@@ -0,0 +1,28 @@
+"""Locate and read the embedded fallback database shipped inside the package."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+_DATA_FILE = "cloudip.msgpack.gz"
+
+
+def load_embedded_gz() -> Optional[bytes]:
+    candidates = [
+        Path(__file__).resolve().parent / "data" / _DATA_FILE,
+        Path(__file__).resolve().parent / _DATA_FILE,
+    ]
+    for p in candidates:
+        try:
+            return p.read_bytes()
+        except OSError:
+            continue
+    # Fall back to importlib.resources for zip/installed layouts.
+    try:
+        from importlib.resources import files
+
+        res = files("cloudip").joinpath("data", _DATA_FILE)
+        return res.read_bytes()
+    except (OSError, ModuleNotFoundError, FileNotFoundError, AttributeError):
+        return None

cloudip/source.py

@@ -0,0 +1,56 @@
+"""Network fetching of version metadata and the database, with SHA-256 verification."""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from typing import NamedTuple, Optional
+
+from .constants import DEFAULT_DATA_URL, DEFAULT_VERSION_URL
+from .decode import gunzip, sha256_hex
+from .types import VersionInfo
+
+_USER_AGENT = "py-cloudip"
+
+
+def _get(url: str, timeout: float) -> bytes:
+    req = urllib.request.Request(url, headers={"User-Agent": _USER_AGENT})
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        status = getattr(resp, "status", 200)
+        if status and status >= 400:
+            raise OSError(f"cloudip: HTTP {status} from {url}")
+        return resp.read()
+
+
+def fetch_version(
+    version_url: str = DEFAULT_VERSION_URL, timeout: float = 30.0
+) -> VersionInfo:
+    data = _get(version_url, timeout)
+    return VersionInfo.from_dict(json.loads(data.decode("utf-8")))
+
+
+class FetchedData(NamedTuple):
+    bytes: bytes
+    version: str
+
+
+def fetch_data(
+    data_url: str = DEFAULT_DATA_URL,
+    version_url: str = DEFAULT_VERSION_URL,
+    verify_sha256: bool = True,
+    verify_against: Optional[VersionInfo] = None,
+    timeout: float = 30.0,
+) -> FetchedData:
+    """Download the gzipped database and verify its SHA-256 against version.json."""
+    gz = _get(data_url, timeout)
+    info = verify_against
+    if info is None and (verify_sha256 or True):
+        info = fetch_version(version_url, timeout)
+    if verify_sha256:
+        raw = gunzip(gz)
+        digest = sha256_hex(raw)
+        if digest != info.sha256:
+            raise ValueError(
+                f"cloudip: sha256 mismatch (expected {info.sha256}, got {digest})"
+            )
+    return FetchedData(bytes=gz, version=info.version if info else "")

cloudip/trie.py

@@ -0,0 +1,79 @@
+"""A binary (Patricia-style) trie over CIDR prefixes for longest-prefix matching.
+
+Separate tries are kept for IPv4 (32-bit) and IPv6 (128-bit) addresses. ``lookup``
+descends the trie bit by bit, remembering the most specific (longest-prefix)
+range seen along the path — matching the behaviour of go-cloudip / js-cloudip.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+from typing import Optional
+
+from .types import Range
+
+
+class _Node:
+    __slots__ = ("zero", "one", "range")
+
+    def __init__(self) -> None:
+        self.zero: Optional[_Node] = None
+        self.one: Optional[_Node] = None
+        self.range: Optional[Range] = None
+
+
+def _parse_network(cidr: str):
+    """Return an ip_network for ``cidr`` (host bits allowed), or None if invalid."""
+    try:
+        return ipaddress.ip_network(cidr, strict=False)
+    except ValueError:
+        return None
+
+
+class CIDRTrie:
+    def __init__(self) -> None:
+        self._v4 = _Node()
+        self._v6 = _Node()
+
+    def insert(self, rng: Range) -> None:
+        net = _parse_network(rng.cidr)
+        if net is None:
+            return
+        nbits = 32 if net.version == 4 else 128
+        value = int(net.network_address)
+        root = self._v4 if net.version == 4 else self._v6
+        node = root
+        for i in range(net.prefixlen):
+            bit = (value >> (nbits - 1 - i)) & 1
+            if bit:
+                child = node.one
+                if child is None:
+                    child = _Node()
+                    node.one = child
+            else:
+                child = node.zero
+                if child is None:
+                    child = _Node()
+                    node.zero = child
+            node = child
+        # Keep the first range inserted at a given prefix (stable, like the JS port).
+        if node.range is None:
+            node.range = rng
+
+    def lookup(self, ip: str) -> Optional[Range]:
+        try:
+            addr = ipaddress.ip_address(ip)
+        except ValueError:
+            return None
+        nbits = 32 if addr.version == 4 else 128
+        value = int(addr)
+        node: Optional[_Node] = self._v4 if addr.version == 4 else self._v6
+        best = node.range if node else None
+        for i in range(nbits):
+            if node is None:
+                break
+            bit = (value >> (nbits - 1 - i)) & 1
+            node = node.one if bit else node.zero
+            if node is not None and node.range is not None:
+                best = node.range
+        return best

cloudip/types.py

@@ -0,0 +1,126 @@
+"""Typed data structures used across the library."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+Provider = str
+
+
+@dataclass(frozen=True)
+class Range:
+    """A single CIDR block belonging to a provider."""
+
+    cidr: str
+    provider: Provider
+    region: Optional[str] = None
+    service: Optional[str] = None
+
+
+@dataclass
+class IPEntry:
+    """A forward-lookup entry returned by ``get_ips``."""
+
+    ip_address: str
+    ip_type: str  # "ipv4" | "ipv6"
+    provider: Provider
+    region: Optional[str] = None
+    service: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        out = {
+            "ip_address": self.ip_address,
+            "ip_type": self.ip_type,
+            "provider": self.provider,
+        }
+        if self.region:
+            out["region"] = self.region
+        if self.service:
+            out["service"] = self.service
+        return out
+
+
+@dataclass
+class LookupResult:
+    """The result of a reverse lookup of an IP address."""
+
+    found: bool
+    provider: Optional[Provider] = None
+    region: Optional[str] = None
+    service: Optional[str] = None
+    cidr: Optional[str] = None
+    ip_type: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        """Serialise omitting absent fields, mirroring js-cloudip's JSON output."""
+        if not self.found:
+            return {"found": False}
+        out = {
+            "found": True,
+            "provider": self.provider,
+            "cidr": self.cidr,
+            "ip_type": self.ip_type,
+        }
+        if self.region:
+            out["region"] = self.region
+        if self.service:
+            out["service"] = self.service
+        return out
+
+
+@dataclass
+class VersionInfo:
+    """Contents of cloudip-db's ``version.json``."""
+
+    version: str
+    build_time: int
+    sha256: str
+    ranges: int
+    size: int
+    size_gzip: int
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "VersionInfo":
+        return cls(
+            version=d.get("version", ""),
+            build_time=int(d.get("build_time", 0)),
+            sha256=d.get("sha256", ""),
+            ranges=int(d.get("ranges", 0)),
+            size=int(d.get("size", 0)),
+            size_gzip=int(d.get("size_gzip", 0)),
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "version": self.version,
+            "build_time": self.build_time,
+            "sha256": self.sha256,
+            "ranges": self.ranges,
+            "size": self.size,
+            "size_gzip": self.size_gzip,
+        }
+
+
+@dataclass
+class Database:
+    """The decoded database."""
+
+    version: str
+    build_time: int
+    providers: list = field(default_factory=list)
+    ranges: list = field(default_factory=list)
+
+
+@dataclass
+class CheckUpdateResult:
+    """Result of ``check_update``."""
+
+    has_update: bool
+    info: Optional[VersionInfo] = None
+
+    def to_dict(self) -> dict:
+        out = {"has_update": self.has_update}
+        if self.info is not None:
+            out["info"] = self.info.to_dict()
+        return out

py_cloudip-0.1.0.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: py-cloudip
+Version: 0.1.0
+Summary: Fast cloud-provider IP detection (AWS, GCP, Azure, Cloudflare, DigitalOcean, Oracle)
+Project-URL: Homepage, https://github.com/rezmoss/py-cloudip
+Project-URL: Database, https://github.com/rezmoss/cloudip-db
+Author: Rez Moss
+License: MIT
+License-File: LICENSE
+Keywords: aws,azure,cidr,cloud,cloudflare,gcp,geoip,ip
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.8
+Requires-Dist: msgpack>=1.0
+Description-Content-Type: text/markdown
+
+# py-cloudip
+
+Fast cloud-provider IP detection for Python. Identify whether an IP address
+belongs to **AWS, GCP, Azure, Cloudflare, DigitalOcean, or Oracle Cloud** via
+longest-prefix-match lookups over a Patricia/binary trie.
+
+A Python port of [js-cloudip](https://github.com/rezmoss/js-cloudip) and
+[go-cloudip](https://github.com/rezmoss/go-cloudip), backed by the daily-updated
+[cloudip-db](https://github.com/rezmoss/cloudip-db) MessagePack database.
+
+- **Fast** — binary trie, IPv4 + IPv6, longest-prefix match.
+- **Auto-updating** — fetches fresh data from `cloudip-db` with SHA-256 verification.
+- **Offline-capable** — file cache plus an embedded database bundled in the wheel.
+- **Zero config** — works on first call; one tiny dependency (`msgpack`).
+
+## Install
+
+```bash
+pip install py-cloudip
+```
+
+## Usage
+
+```python
+import cloudip
+
+cloudip.is_aws("52.94.76.1")        # True
+cloudip.get_provider("34.64.0.1")   # "gcp"
+cloudip.is_cloud_provider("1.1.1.1")  # True
+
+r = cloudip.lookup("52.94.76.1")
+# LookupResult(found=True, provider="aws", region="us-east-1", service="EC2",
+#              cidr="52.94.76.0/22", ip_type="ipv4")
+r.to_dict()
+# {"found": True, "provider": "aws", "cidr": "52.94.76.0/22",
+#  "ip_type": "ipv4", "region": "us-east-1", "service": "EC2"}
+
+# Forward lookup: every CIDR for one or more providers
+cloudip.get_ips("cloudflare")        # list[IPEntry]
+cloudip.get_ips(["aws", "gcp"])
+```
+
+### Provider checks
+
+`is_aws`, `is_gcp`, `is_azure`, `is_cloudflare`, `is_digitalocean`, `is_oracle`,
+`is_cloud_provider`.
+
+### Metadata & updates
+
+```python
+cloudip.version()        # "2026-06-05"
+cloudip.range_count()    # 124455
+cloudip.providers()      # ["aws", "gcp", "cloudflare", "azure", "digitalocean", "oracle"]
+cloudip.check_update()   # CheckUpdateResult(has_update=..., info=VersionInfo(...))
+cloudip.update()         # force refresh
+cloudip.clear_cache()
+```
+
+## Custom detector
+
+```python
+detector = cloudip.new_detector(
+    data_dir="./cache",            # None disables file caching; "" = default ~/.cache/py-cloudip
+    auto_update_seconds=86400,     # background refresh (min 1h); 0 disables
+    offline=False,                 # air-gapped mode
+    verify_sha256=True,
+    ttl_seconds=86400,
+)
+detector.lookup("52.94.76.1")
+detector.close()                   # stop the background updater
+# or: with cloudip.Detector(...) as d: ...
+```
+
+## Offline / air-gapped
+
+The `cloudip.embedded` module never touches the network — it uses only the
+database bundled in the package:
+
+```python
+from cloudip import embedded
+embedded.is_aws("52.94.76.1")   # uses bundled data only
+embedded.age_days()             # how old the bundled data is
+```
+
+## CLI
+
+```bash
+cloudip lookup 52.94.76.1
+cloudip provider 34.64.0.1
+cloudip get cloudflare
+cloudip get aws,gcp
+cloudip providers
+cloudip version
+cloudip check-update
+cloudip update
+cloudip clear-cache
+```
+
+(Also runnable as `python -m cloudip`.)
+
+## How it works
+
+1. Fetch `version.json` + `cloudip.msgpack.gz` from `cloudip-db`.
+2. Verify the SHA-256 of the decompressed MessagePack against `version.json`.
+3. Decode and build per-protocol tries for sub-millisecond lookups.
+4. On network failure, fall back to the on-disk cache, then the embedded database.
+
+## License
+
+MIT

py_cloudip-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+cloudip/__init__.py,sha256=88cR58DfEMdmY8YdIf5xPplfVJFhJbIWiY7TDnt3Voo,3459
+cloudip/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+cloudip/cache.py,sha256=gNA3Jb6gXECxZSxkStme8Sp4-5gyTHGw72ns0XL4hxY,1971
+cloudip/cli.py,sha256=mnB2uZDwcgJ-zoHV6GnKhnf_SQrzpw4AoV6NfDKqDt4,2940
+cloudip/constants.py,sha256=g2i85KKfpoj7mOz7Vcu0YTKy5foyxvcuyS7s65YBzLc,510
+cloudip/decode.py,sha256=pJFhyuKq8M3oHAHvQ55uzGgNxkSjV1HCsB4f-w9hiQA,1139
+cloudip/detector.py,sha256=69e9v96bu2l9dSJ1NtyuhNupDCQcKDLT2j4afIa32Ac,9498
+cloudip/embedded.py,sha256=ygKNkuH1XVXetmUgOLYDFs9f_ZZa5_IVfjlwO--VlZE,2064
+cloudip/embedded_loader.py,sha256=s5vs2vpSoeybAGeHGEsvzxeALWBQeN0CulDp_EvPi-E,822
+cloudip/source.py,sha256=E-bRpqIn-cOyOqxMHAO86-6pge9G3UCTiPgk0O22rtE,1778
+cloudip/trie.py,sha256=xO8OWzErHj05cQTdQh8SgWhYIvAriEVFFQ7xvtTUzv8,2501
+cloudip/types.py,sha256=rwwB4LiB5pLT38BvweP8K-yEjcFWu6w3binOQLP9W6o,3049
+cloudip/data/cloudip.msgpack.gz,sha256=6xY4I2ga8IHy-rBw91pKzVbVt6OStIkMfOJyU4FP8uc,759422
+py_cloudip-0.1.0.dist-info/METADATA,sha256=Z39eZy_6-MVpA1bQY1hB6EQw-BMh8eD9jAIQ_xs9gMw,3954
+py_cloudip-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+py_cloudip-0.1.0.dist-info/entry_points.txt,sha256=7NmE7dtFGOsNittGAfyj2Ugl1IRQWc5r_D51LnSLJ9k,45
+py_cloudip-0.1.0.dist-info/licenses/LICENSE,sha256=G3bni7VqsewOml7-B0pMnTufsambmnDHyYLmEmFhmSA,1065
+py_cloudip-0.1.0.dist-info/RECORD,,

py_cloudip-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

py_cloudip-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cloudip = cloudip.cli:main

py_cloudip-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rez Moss
+
+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.