py-cloudip 0.1.0__tar.gz

py_cloudip-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+cache/
+*.swp

py_cloudip-0.1.0/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.

py_cloudip-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,110 @@
+# 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/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "py-cloudip"
+version = "0.1.0"
+description = "Fast cloud-provider IP detection (AWS, GCP, Azure, Cloudflare, DigitalOcean, Oracle)"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Rez Moss" }]
+keywords = ["cloud", "ip", "aws", "gcp", "azure", "cloudflare", "cidr", "geoip"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Internet",
+    "Topic :: System :: Networking",
+]
+dependencies = ["msgpack>=1.0"]
+
+[project.urls]
+Homepage = "https://github.com/rezmoss/py-cloudip"
+Database = "https://github.com/rezmoss/cloudip-db"
+
+[project.scripts]
+cloudip = "cloudip.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cloudip"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/cloudip/data/cloudip.msgpack.gz" = "cloudip/data/cloudip.msgpack.gz"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/cloudip", "README.md", "LICENSE"]

py_cloudip-0.1.0/src/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

py_cloudip-0.1.0/src/cloudip/__main__.py

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

py_cloudip-0.1.0/src/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

py_cloudip-0.1.0/src/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())

py_cloudip-0.1.0/src/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