grip-client 0.1.1__tar.gz

grip_client-0.1.1/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: grip-client
+Version: 0.1.1
+Summary: Python client for the GRIP API
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.31
+Provides-Extra: cachetools
+Requires-Dist: cachetools>=5; extra == "cachetools"
+Provides-Extra: redis
+Requires-Dist: redis>=5; extra == "redis"
+Provides-Extra: mmdb
+Requires-Dist: filelock>=3; extra == "mmdb"
+Requires-Dist: maxminddb>=2; extra == "mmdb"
+Requires-Dist: pycountry>=24; extra == "mmdb"
+Provides-Extra: cache
+Requires-Dist: cachetools>=5; extra == "cache"
+Requires-Dist: redis>=5; extra == "cache"

grip_client-0.1.1/README.md

@@ -0,0 +1,74 @@
+# grip-client
+
+## Python client for the GRIP API.
+
+```python
+from grip_client.rest import GRIPClient
+
+client = GRIPClient(token="token", timeout=5.0)
+response = client.response_ip("8.8.8.8")
+
+print(response.ip)
+print(response.country_iso)
+```
+
+#### Optional in-memory caching:
+
+```python
+from grip_client.rest import GRIPClient, CachetoolsCache
+
+client = GRIPClient(
+    token="token",
+    cache=CachetoolsCache(ttl=300, maxsize=1024),
+)
+response = client.response_ip("8.8.8.8")
+```
+
+#### Optional Redis caching:
+
+```python
+from grip_client.rest import GRIPClient, RedisCache
+
+client = GRIPClient(
+    token="token",
+    cache=RedisCache.from_url("redis://localhost:6379/0", ttl=300),
+)
+response = client.response_ip("8.8.8.8")
+```
+
+## MMDB local lookup:
+
+Features:
+
+- MMDB downloads use the gzipped asset by default, and cache the decompressed `.mmdb` on disk.
+- Files are updated asynchronously every hour.
+- Reader is thread-safe
+
+```python
+from grip_client.mmdb import GRIPMMDBClient
+
+mmdb = GRIPMMDBClient(token="token")
+res = mmdb.lookup("8.8.8.8")
+
+print(
+    f"{res.asn.network_operator=}, "
+    f"{res.country.country_iso=}, "
+    f"{res.anonymous.is_anonymous=}"
+)
+
+```
+
+#### Individual MMDBs can be used directly:
+
+```python
+from grip_client.mmdb import GRIPMMDB, GRIPMMDBKind
+
+anonymous = GRIPMMDB(
+    kind=GRIPMMDBKind.GRIP_ANONYMOUS,
+    max_age_seconds=3600,
+    token="token"
+)
+
+if anonymous.is_anonymous("8.8.8.8"):
+    print("skip API lookup")
+```

grip_client-0.1.1/grip_client/__init__.py

@@ -0,0 +1,5 @@
+from grip_client.mmdb import GRIPMMDBClient
+from grip_client.rest import GRIPClient
+from grip_client.enums import AccessType, OrgType
+
+__all__ = ["GRIPClient", "GRIPMMDBClient", "AccessType", "OrgType"]

grip_client-0.1.1/grip_client/enums.py

@@ -0,0 +1,33 @@
+from enum import StrEnum
+
+
+class AccessType(StrEnum):
+    """
+    How the network is used
+    """
+
+    # Consumer access networks, usually under OrgType.ISP
+    RESIDENTIAL = "residential"  # cable/dsl/fiber to homes / CGNAT
+    MOBILE = "mobile"  # cellular / CGNAT
+    SATELLITE = "satellite"  # starlink, viasat, etc.
+
+    # Hosting infrastructure, usually under OrgType.HOSTING
+    DATACENTER = "datacenter"  # cloud / hosting / colo
+
+    # Corporate, institutional, and internal networks. Typical OrgType BUSINESS, EDUCATION, GOVERNMENT
+    ENTERPRISE = "enterprise"
+
+    UNKNOWN = "unknown"
+
+
+class OrgType(StrEnum):
+    """
+    What kind of organization owns the network/ASN/prefix
+    """
+
+    BUSINESS = "business"
+    EDUCATION = "education"
+    GOVERNMENT = "government"
+    HOSTING = "hosting"
+    ISP = "isp"
+    UNKNOWN = "unknown"

grip_client-0.1.1/grip_client/exceptions.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class GRIPAPIError(Exception):
+    def __init__(
+        self,
+        *,
+        status_code: int | None,
+        message: str,
+        detail: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.detail = detail

grip_client-0.1.1/grip_client/metadata.py

@@ -0,0 +1,8 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("grip-client")
+except PackageNotFoundError:
+    __version__ = "0+unknown"
+
+USER_AGENT = f"grip-client/{__version__}"

grip_client-0.1.1/grip_client/mmdb/__init__.py

@@ -0,0 +1,17 @@
+from grip_client.mmdb.client import GRIPMMDB, GRIPMMDBClient, GRIPMMDBKind
+from grip_client.mmdb.models import (
+    GRIPAnonymousRecord,
+    GRIPAsnRecord,
+    GRIPCountryRecord,
+    GRIPMMDBLookupResult,
+)
+
+__all__ = [
+    "GRIPAnonymousRecord",
+    "GRIPAsnRecord",
+    "GRIPCountryRecord",
+    "GRIPMMDB",
+    "GRIPMMDBClient",
+    "GRIPMMDBKind",
+    "GRIPMMDBLookupResult",
+]

grip_client-0.1.1/grip_client/mmdb/client.py

@@ -0,0 +1,338 @@
+from __future__ import annotations
+
+import gzip
+import logging
+import os
+import threading
+import time
+from concurrent.futures import Future, ThreadPoolExecutor
+from email.utils import formatdate, parsedate_to_datetime
+from enum import StrEnum
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import Any, Iterable
+from ipaddress import IPv4Address, IPv6Address
+
+import requests
+
+from grip_client.metadata import USER_AGENT
+from grip_client.exceptions import GRIPAPIError
+from grip_client.mmdb.models import (
+    GRIPAnonymousRecord,
+    GRIPCountryRecord,
+    GRIPAsnRecord,
+    GRIPMMDBLookupResult,
+)
+
+
+class GRIPMMDBKind(StrEnum):
+    GRIP_ANONYMOUS = "grip_anonymous"
+    GRIP_COUNTRY = "grip_country"
+    GRIP_ASN = "grip_asn_accesstype"
+    GRIP_WHOIS = "grip_whois"
+
+
+logger = logging.getLogger(__name__)
+
+
+class GRIPMMDBClient:
+    def __init__(
+        self,
+        kinds: Iterable[GRIPMMDBKind | str] = (
+            GRIPMMDBKind.GRIP_ANONYMOUS,
+            GRIPMMDBKind.GRIP_COUNTRY,
+            GRIPMMDBKind.GRIP_ASN,
+        ),
+        **mmdb_options: Any,
+    ) -> None:
+        self._dbs = {
+            (kind.value if isinstance(kind, GRIPMMDBKind) else kind): GRIPMMDB(
+                kind,
+                **mmdb_options,
+            )
+            for kind in kinds
+        }
+
+    def lookup(
+        self, ip_address: str | IPv4Address | IPv6Address
+    ) -> GRIPMMDBLookupResult:
+        raw = {kind: db.lookup(ip_address) for kind, db in self._dbs.items()}
+
+        return GRIPMMDBLookupResult(
+            anonymous=(
+                GRIPAnonymousRecord.from_dict(raw[GRIPMMDBKind.GRIP_ANONYMOUS])
+                if GRIPMMDBKind.GRIP_ANONYMOUS in raw
+                else None
+            ),
+            country=(
+                GRIPCountryRecord.from_dict(raw[GRIPMMDBKind.GRIP_COUNTRY])
+                if GRIPMMDBKind.GRIP_COUNTRY in raw
+                else None
+            ),
+            asn=(
+                GRIPAsnRecord.from_dict(raw[GRIPMMDBKind.GRIP_ASN])
+                if GRIPMMDBKind.GRIP_ASN in raw
+                else None
+            ),
+            raw=raw,
+        )
+
+    def refresh(self, *, block: bool = True):
+        futures = [db.refresh(block=False) for db in self._dbs.values()]
+        if not block:
+            return futures
+        return [future.result() for future in futures]
+
+    def close(self) -> None:
+        for db in self._dbs.values():
+            db.close()
+
+
+class GRIPMMDB:
+    def __init__(
+        self,
+        kind: GRIPMMDBKind | str,
+        *,
+        base_url: str = "https://grip.net",
+        download_url: str | None = None,
+        cache_dir: str | Path | None = None,
+        max_age_seconds: int = 3600,
+        download_timeout: float | None = 60.0,
+        token: str | None = None,
+        download_on_init: bool = True,
+    ) -> None:
+        self.kind = kind.value if isinstance(kind, GRIPMMDBKind) else kind
+        self.filename = f"{self.kind}.mmdb"
+        self.download_filename = f"{self.filename}.gz"
+        self.base_url = base_url.rstrip("/")
+        self.download_url = (
+            download_url or f"{self.base_url}/files/{self.download_filename}"
+        )
+        self.cache_dir = (
+            Path(cache_dir) if cache_dir is not None else _default_cache_dir()
+        )
+        self.max_age_seconds = max_age_seconds
+        self.download_timeout = download_timeout
+        self.lock_timeout_seconds = download_timeout
+        self.token = token
+        self.path = self.cache_dir / self.filename
+        self.lock_path = self.cache_dir / f".{self.filename}.lock"
+
+        self._executor = ThreadPoolExecutor(max_workers=1)
+        self._future: Future[Path] | None = None
+        self._lock = threading.Lock()
+        self._reader: Any | None = None
+        self._reader_mtime_ns: int | None = None
+        self._reader_lock = threading.RLock()
+        self._remote_last_checked_at: float | None = None
+
+        if download_on_init and self.is_stale():
+            self.refresh(block=False)
+
+    def __enter__(self) -> "GRIPMMDB":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def lookup(
+        self, ip_address: str | IPv4Address | IPv6Address
+    ) -> dict[str, Any] | None:
+        self._ensure_available()
+        with self._reader_lock:
+            result = self._get_reader().get(ip_address)
+
+        if result is None:
+            return None
+        if not isinstance(result, dict):
+            raise ValueError(f"MMDB lookup returned a non-object value for {ip_address}")
+        return result
+
+    def is_anonymous(self, ip_address: str | IPv4Address | IPv6Address) -> bool:
+        return self.anonymous_lookup(ip_address).is_anonymous
+
+    def country_iso(self, ip_address: str | IPv4Address | IPv6Address) -> str | None:
+        return self.country_lookup(ip_address).country_iso
+
+    def anonymous_lookup(
+        self, ip_address: str | IPv4Address | IPv6Address
+    ) -> GRIPAnonymousRecord:
+        if self.kind != GRIPMMDBKind.GRIP_ANONYMOUS.value:
+            raise ValueError(
+                f"{GRIPMMDBKind.GRIP_ANONYMOUS.value} MMDB required, got {self.kind!r}."
+            )
+        result = self.lookup(ip_address)
+        return GRIPAnonymousRecord.from_dict(result)
+
+    def country_lookup(
+        self, ip_address: str | IPv4Address | IPv6Address
+    ) -> GRIPCountryRecord:
+        if self.kind != GRIPMMDBKind.GRIP_COUNTRY.value:
+            raise ValueError(
+                f"{GRIPMMDBKind.GRIP_COUNTRY.value} MMDB required, got {self.kind!r}."
+            )
+        result = self.lookup(ip_address)
+        return GRIPCountryRecord.from_dict(result)
+
+    def asn_lookup(self, ip_address: str | IPv4Address | IPv6Address) -> GRIPAsnRecord:
+        if self.kind != GRIPMMDBKind.GRIP_ASN.value:
+            raise ValueError(
+                f"{GRIPMMDBKind.GRIP_ASN.value} MMDB required, " f"got {self.kind!r}."
+            )
+        result = self.lookup(ip_address)
+        return GRIPAsnRecord.from_dict(result)
+
+    def is_stale(self) -> bool:
+        if not self.path.exists():
+            return True
+        age_seconds = time.time() - self.path.stat().st_mtime
+        return age_seconds > self.max_age_seconds
+
+    def refresh(self, *, block: bool = True) -> Path | Future[Path]:
+        future = self._ensure_download_started()
+        if block:
+            return future.result()
+        return future
+
+    def close(self) -> None:
+        self._close_reader()
+        self._executor.shutdown(wait=False, cancel_futures=False)
+
+    def _ensure_available(self) -> None:
+        if self.path.exists() and self.path.stat().st_size > 0:
+            if self.is_stale() and self._should_check_remote():
+                self.refresh(block=False)
+            return
+        logger.warning("Downloading mmdb file...")
+        self.refresh(block=True)
+
+    def _should_check_remote(self) -> bool:
+        # If file on disk is older than max_age_seconds, but the remote
+        #  file isn't updated, check remote at most every 60 seconds.
+        now = time.time()
+        if (
+            self._remote_last_checked_at is not None
+            and now - self._remote_last_checked_at < 60
+        ):
+            return False
+
+        self._remote_last_checked_at = now
+        return True
+
+    def _ensure_download_started(self) -> Future[Path]:
+        with self._lock:
+            if self._future is None or self._future.done():
+                self._future = self._executor.submit(self._download)
+            return self._future
+
+    def _download(self) -> Path:
+        try:
+            from filelock import FileLock
+        except ImportError as error:
+            raise ImportError(
+                "Install grip-client[mmdb] to use MMDB download locking."
+            ) from error
+
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        tmp_path: Path | None = None
+        headers = {
+            "Accept": "application/octet-stream",
+            "User-Agent": USER_AGENT,
+        }
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+
+        try:
+            with FileLock(str(self.lock_path), timeout=self.lock_timeout_seconds):
+                if self.path.exists() and self.path.stat().st_size > 0:
+                    headers["If-Modified-Since"] = formatdate(
+                        self.path.stat().st_mtime,
+                        usegmt=True,
+                    )
+
+                with requests.get(
+                    self.download_url,
+                    headers=headers,
+                    stream=True,
+                    timeout=self.download_timeout,
+                ) as response:
+                    if response.status_code == 304:
+                        self._validate_file(self.path)
+                        return self.path
+
+                    response.raise_for_status()
+                    last_modified = response.headers.get("Last-Modified")
+
+                    with NamedTemporaryFile(
+                        dir=self.cache_dir,
+                        prefix=f".{self.filename}.",
+                        delete=False,
+                    ) as tmp:
+                        tmp_path = Path(tmp.name)
+                        with gzip.GzipFile(fileobj=response.raw, mode="rb") as gzipped:
+                            while True:
+                                chunk = gzipped.read(1024 * 1024)
+                                if not chunk:
+                                    break
+                                tmp.write(chunk)
+
+                self._validate_file(tmp_path)
+                os.replace(tmp_path, self.path)
+                if last_modified is not None:
+                    try:
+                        modified_at = parsedate_to_datetime(last_modified).timestamp()
+                        os.utime(self.path, (modified_at, modified_at))
+                    except (TypeError, ValueError, OSError, OverflowError):
+                        pass
+                self._close_reader()
+                return self.path
+        except requests.RequestException as error:
+            response = getattr(error, "response", None)
+            raise GRIPAPIError(
+                status_code=response.status_code if response is not None else None,
+                message=(
+                    f"GRIP MMDB download failed with HTTP {response.status_code}"
+                    if response is not None
+                    else "GRIP MMDB download failed"
+                ),
+                detail=response.text if response is not None else str(error),
+            ) from error
+        finally:
+            if tmp_path is not None and tmp_path.exists():
+                tmp_path.unlink()
+
+    def _get_reader(self) -> Any:
+        self._validate_file(self.path)
+        current_mtime_ns = self.path.stat().st_mtime_ns
+        if self._reader is not None and self._reader_mtime_ns == current_mtime_ns:
+            return self._reader
+
+        self._close_reader()
+
+        try:
+            import maxminddb
+        except ImportError as error:
+            raise ImportError(
+                "Install grip-client[mmdb] to use GRIPMMDB lookups."
+            ) from error
+
+        self._reader = maxminddb.open_database(self.path)
+        self._reader_mtime_ns = current_mtime_ns
+        return self._reader
+
+    def _close_reader(self) -> None:
+        with self._reader_lock:
+            if self._reader is not None:
+                self._reader.close()
+            self._reader = None
+            self._reader_mtime_ns = None
+
+    def _validate_file(self, path: Path) -> None:
+        if not path.exists():
+            raise FileNotFoundError(f"MMDB file does not exist: {path}")
+        if path.stat().st_size <= 0:
+            raise ValueError(f"MMDB file is empty: {path}")
+
+
+def _default_cache_dir() -> Path:
+    return Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "grip-client"

grip_client-0.1.1/grip_client/mmdb/models.py

@@ -0,0 +1,104 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+from grip_client.enums import AccessType
+
+
+@dataclass(frozen=True)
+class GRIPAnonymousRecord:
+    is_cloud: bool = False
+    is_proxy: bool = False
+    is_vpn: bool = False
+    is_org_hosting: bool = False
+    is_asn_hosting: bool = False
+    is_access_type_hosting: bool = False
+    is_density_anon: bool = False
+    is_anonymous: bool = False
+    raw: dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "GRIPAnonymousRecord":
+        if data is None:
+            return cls()
+
+        return cls(
+            is_cloud=bool(data.get("is_cloud", False)),
+            is_proxy=bool(data.get("is_proxy", False)),
+            is_vpn=bool(data.get("is_vpn", False)),
+            is_org_hosting=bool(data.get("is_org_hosting", False)),
+            is_asn_hosting=bool(data.get("is_asn_hosting", False)),
+            is_access_type_hosting=bool(data.get("is_access_type_hosting", False)),
+            is_density_anon=bool(data.get("is_density_anon", False)),
+            is_anonymous=bool(data.get("is_anonymous", False)),
+            raw=data,
+        )
+
+
+@dataclass(frozen=True)
+class GRIPCountryRecord:
+    geofeed_country_iso: str | None = None
+    registered_country_iso: str | None = None
+    announced_country_iso: str | None = None
+    country_iso: str | None = None
+    source: str | None = None
+    geofeed_conflict: bool = False
+    raw: dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "GRIPCountryRecord":
+        if data is None:
+            return cls()
+
+        return cls(
+            geofeed_country_iso=data.get("geofeed_country_iso") or None,
+            registered_country_iso=data.get("registered_country_iso") or None,
+            announced_country_iso=data.get("announced_country_iso") or None,
+            country_iso=data.get("country_iso") or None,
+            source=data.get("source") or None,
+            geofeed_conflict=bool(data.get("geofeed_conflict", False)),
+            raw=data,
+        )
+
+    @property
+    def country(self) -> Any | None:
+        if self.country_iso is None:
+            return None
+
+        try:
+            import pycountry
+        except ImportError as error:
+            raise ImportError(
+                "Install grip-client[mmdb] to use GRIPCountryRecord.country."
+            ) from error
+
+        return pycountry.countries.get(alpha_2=self.country_iso)
+
+
+@dataclass(frozen=True)
+class GRIPAsnRecord:
+    asn: int | None = None
+    network_operator: str | None= None
+    access_type: AccessType | None= None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "GRIPAsnRecord":
+        if data is None:
+            return cls()
+        return cls(
+            asn=data.get("asn") or None,
+            network_operator=data.get("network_operator") or None,
+            access_type=(
+                AccessType(data["access_type"]) if data.get("access_type") else None
+            ),
+            raw=data,
+        )
+
+
+
+@dataclass(frozen=True)
+class GRIPMMDBLookupResult:
+    anonymous: GRIPAnonymousRecord | None = None
+    country: GRIPCountryRecord | None = None
+    asn: GRIPAsnRecord | None = None
+    raw: dict[str, dict[str, Any] | None] = field(default_factory=dict)

grip_client-0.1.1/grip_client/rest/__init__.py

@@ -0,0 +1,13 @@
+from grip_client.rest.cache import CacheBackend, CachetoolsCache, MappingCache, RedisCache
+from grip_client.rest.client import GRIPClient
+from grip_client.rest.models import GRIPIpResponse, LocationFlat
+
+__all__ = [
+    "CacheBackend",
+    "CachetoolsCache",
+    "GRIPClient",
+    "GRIPIpResponse",
+    "LocationFlat",
+    "MappingCache",
+    "RedisCache",
+]

grip_client-0.1.1/grip_client/rest/cache.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import json
+from collections.abc import MutableMapping
+from typing import Any, Protocol
+
+
+JsonObject = dict[str, Any]
+
+
+class CacheBackend(Protocol):
+    def get(self, key: str) -> JsonObject | None:
+        ...
+
+    def set(self, key: str, value: JsonObject) -> None:
+        ...
+
+
+class MappingCache:
+    def __init__(self, cache: MutableMapping[str, JsonObject] | None = None) -> None:
+        self.cache: MutableMapping[str, JsonObject] = cache if cache is not None else {}
+
+    def get(self, key: str) -> JsonObject | None:
+        return self.cache.get(key)
+
+    def set(self, key: str, value: JsonObject) -> None:
+        self.cache[key] = value
+
+
+class CachetoolsCache(MappingCache):
+    def __init__(self, *, ttl: int = 300, maxsize: int = 1024) -> None:
+        try:
+            from cachetools import TTLCache
+        except ImportError as error:
+            raise ImportError(
+                "Install grip-client[cachetools] to use CachetoolsCache."
+            ) from error
+
+        super().__init__(TTLCache(maxsize=maxsize, ttl=ttl))
+
+
+class RedisCache:
+    def __init__(
+        self,
+        redis_client: Any,
+        *,
+        ttl: int = 300,
+        prefix: str = "grip-client",
+    ) -> None:
+        self.redis_client = redis_client
+        self.ttl = ttl
+        self.prefix = prefix.rstrip(":")
+
+    @classmethod
+    def from_url(
+        cls,
+        url: str,
+        *,
+        ttl: int = 300,
+        prefix: str = "grip-client",
+        **kwargs: Any,
+    ) -> "RedisCache":
+        try:
+            from redis import Redis
+        except ImportError as error:
+            raise ImportError("Install grip-client[redis] to use RedisCache.") from error
+
+        return cls(Redis.from_url(url, **kwargs), ttl=ttl, prefix=prefix)
+
+    def get(self, key: str) -> JsonObject | None:
+        value = self.redis_client.get(self._key(key))
+        if value is None:
+            return None
+        if isinstance(value, bytes):
+            value = value.decode("utf-8")
+
+        parsed = json.loads(value)
+        if not isinstance(parsed, dict):
+            return None
+        return parsed
+
+    def set(self, key: str, value: JsonObject) -> None:
+        payload = json.dumps(value, separators=(",", ":"))
+        self.redis_client.setex(self._key(key), self.ttl, payload)
+
+    def _key(self, key: str) -> str:
+        return f"{self.prefix}:{key}"

grip_client-0.1.1/grip_client/rest/client.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+import requests
+
+from grip_client.metadata import USER_AGENT
+from grip_client.exceptions import GRIPAPIError
+from grip_client.rest.cache import CacheBackend
+from grip_client.rest.models import GRIPIpResponse
+
+
+class GRIPClient:
+
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        base_url: str = "https://grip.net",
+        timeout: float | None = 30.0,
+        cache: CacheBackend | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self.cache = cache
+
+    def response_ip(self, ip_address: str) -> GRIPIpResponse:
+        data = self._request_json(
+            "GET",
+            f"/ip/{quote(ip_address, safe='')}",
+            cacheable=True,
+        )
+        return GRIPIpResponse.from_dict(data)
+
+    def get_ip(self, ip_address: str) -> GRIPIpResponse:
+        return self.response_ip(ip_address)
+
+    def _request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        cacheable: bool = False,
+    ) -> dict[str, Any]:
+        cache_key = self._cache_key(method, path)
+        if cacheable and self.cache is not None:
+            cached = self.cache.get(cache_key)
+            if cached is not None:
+                return cached
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+
+        try:
+            response = requests.request(
+                method=method,
+                url=f"{self.base_url}{path}",
+                headers=headers,
+                timeout=self.timeout,
+            )
+        except requests.RequestException as error:
+            raise GRIPAPIError(
+                status_code=None,
+                message="GRIP API request failed",
+                detail=str(error),
+            ) from error
+
+        if response.status_code != 200:
+            raise self._api_error(response)
+
+        if not response.content:
+            return {}
+
+        try:
+            parsed = response.json()
+        except ValueError as error:
+            raise GRIPAPIError(
+                status_code=response.status_code,
+                message="GRIP API returned invalid JSON",
+            ) from error
+
+        if not isinstance(parsed, dict):
+            raise GRIPAPIError(
+                status_code=None,
+                message="GRIP API returned a non-object JSON response",
+            )
+
+        if cacheable and self.cache is not None:
+            self.cache.set(cache_key, parsed)
+
+        return parsed
+
+    def _cache_key(self, method: str, path: str) -> str:
+        return f"{method.upper()} {path}"
+
+    def _api_error(self, response: requests.Response) -> GRIPAPIError:
+        try:
+            detail: Any = response.json()
+        except ValueError:
+            detail = response.text
+
+        return GRIPAPIError(
+            status_code=response.status_code,
+            message=f"GRIP API request failed with HTTP {response.status_code}",
+            detail=detail,
+        )

grip_client-0.1.1/grip_client/rest/models.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from grip_client.enums import AccessType, OrgType
+
+JsonObject = dict[str, Any]
+
+
+@dataclass(frozen=True)
+class LocationFlat:
+    geoname_id: int | None
+
+    continent_iso: str | None = None
+    continent_name: str | None = None
+
+    country_iso: str | None = None
+    country_name: str | None = None
+
+    subdivision_1_iso: str | None = None
+    subdivision_1_name: str | None = None
+    subdivision_2_iso: str | None = None
+    subdivision_2_name: str | None = None
+
+    city_name: str | None = None
+    metro_name: str | None = None
+
+    timezone: str | None = None
+    is_in_european_union: bool | None = None
+
+
+@dataclass(frozen=True)
+class GRIPIpResponse:
+    ip: str
+    announced_prefix: JsonObject | None
+    whois_registration: JsonObject
+    location: JsonObject
+    ip_exploded: str
+    country_iso: str | None
+    is_bogon: bool = False
+    is_anycast: bool = False
+    is_crawler: bool = False
+    is_abuser: bool = False
+    is_cgnat: bool = False
+    is_anonymous: bool = False
+    access_type: AccessType | None = None
+    predictions: JsonObject = field(default_factory=dict)
+    privacy: JsonObject = field(default_factory=dict)
+    cloud: list[JsonObject] = field(default_factory=list)
+    relay: list[JsonObject] = field(default_factory=list)
+    vpn: list[JsonObject] = field(default_factory=list)
+    proxy: list[JsonObject] = field(default_factory=list)
+    tags: list[JsonObject] = field(default_factory=list)
+    dns: JsonObject | None = None
+    probe: JsonObject | None = None
+    raw: JsonObject = field(default_factory=dict, repr=False, compare=False)
+
+    @property
+    def isp(self) -> str | None:
+        return self.announced_prefix.get("owner_name", None)
+
+    @property
+    def company(self) -> str | None:
+        return self.whois_registration["network"].get("owner_name", None)
+
+    @property
+    def org_type(self) -> OrgType | None:
+        org_type = self.announced_prefix.get("organization", {}).get("org_type", None)
+        return OrgType(org_type) if org_type else None
+
+    @property
+    def is_anonymous_vpn(self) -> bool:
+        return self.is_anonymous and len(self.vpn) > 0
+
+    @property
+    def is_hosting(self) -> bool:
+        return self.org_type == OrgType.HOSTING or len(self.cloud) > 0
+
+    @property
+    def is_private_relay(self) -> bool:
+        return len(self.relay) > 0
+
+    @property
+    def is_residential_proxy(self) -> bool:
+        return self.is_anonymous and len(self.proxy) > 0
+
+    @property
+    def is_like_residential_proxy(self) -> bool:
+        return self.is_residential_proxy or self.privacy.get(
+            "residential_proxy_density_30d_base_network", 0
+        ) > (1 / 3)
+
+    @property
+    def location_flat(self) -> LocationFlat:
+        scope = self.location.get("scope")
+        if scope is None:
+            return LocationFlat(geoname_id=None)
+        loc_scope = self.location[scope]
+        loc = self.location
+        return LocationFlat(
+            geoname_id=loc_scope["geoname_id"],
+            continent_iso=loc["continent"].get("iso_code") if loc["continent"] else None,
+            continent_name=loc["continent"].get("name") if loc["continent"] else None,
+            country_iso=loc["country"].get("iso_code") if loc["country"] else None,
+            country_name=loc["country"].get("name") if loc["country"] else None,
+            subdivision_1_iso=(
+                loc["subdivision_1"].get("iso_code") if loc["subdivision_1"] else None
+            ),
+            subdivision_1_name=(
+                loc["subdivision_1"].get("name") if loc["subdivision_1"] else None
+            ),
+            subdivision_2_iso=(
+                loc["subdivision_2"].get("iso_code") if loc["subdivision_2"] else None
+            ),
+            subdivision_2_name=(
+                loc["subdivision_2"].get("name") if loc["subdivision_2"] else None
+            ),
+            city_name=loc["city"].get("name") if loc["city"] else None,
+            metro_name=loc["metro"].get("name") if loc["metro"] else None,
+            timezone=loc["timezone"],
+            # todo: ---v
+            is_in_european_union=loc.get("is_in_european_union", None),
+        )
+
+    @classmethod
+    def from_dict(cls, data: JsonObject) -> "GRIPIpResponse":
+        return cls(
+            ip=data["ip"],
+            announced_prefix=data.get("announced_prefix", None),
+            whois_registration=data["whois_registration"],
+            location=data["location"],
+            ip_exploded=data["ip_exploded"],
+            country_iso=data["country_iso"],
+            access_type=AccessType(data["access_type"]),
+            is_bogon=bool(data.get("is_bogon", False)),
+            is_anycast=bool(data.get("is_anycast", False)),
+            is_crawler=bool(data.get("is_crawler", False)),
+            is_abuser=bool(data.get("is_abuser", False)),
+            is_cgnat=bool(data.get("is_cgnat", False)),
+            is_anonymous=bool(data.get("is_anonymous", False)),
+            predictions=data.get("predictions", {}),
+            privacy=data.get("privacy", {}),
+            cloud=data.get("cloud", []),
+            relay=data.get("relay", []),
+            vpn=data.get("vpn", []),
+            proxy=data.get("proxy", []),
+            tags=data.get("tags", []),
+            dns=data.get("dns", None),
+            probe=data.get("probe", None),
+            raw=data,
+        )

grip_client-0.1.1/grip_client.egg-info/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: grip-client
+Version: 0.1.1
+Summary: Python client for the GRIP API
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.31
+Provides-Extra: cachetools
+Requires-Dist: cachetools>=5; extra == "cachetools"
+Provides-Extra: redis
+Requires-Dist: redis>=5; extra == "redis"
+Provides-Extra: mmdb
+Requires-Dist: filelock>=3; extra == "mmdb"
+Requires-Dist: maxminddb>=2; extra == "mmdb"
+Requires-Dist: pycountry>=24; extra == "mmdb"
+Provides-Extra: cache
+Requires-Dist: cachetools>=5; extra == "cache"
+Requires-Dist: redis>=5; extra == "cache"

grip_client-0.1.1/grip_client.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+grip_client/__init__.py
+grip_client/enums.py
+grip_client/exceptions.py
+grip_client/metadata.py
+grip_client.egg-info/PKG-INFO
+grip_client.egg-info/SOURCES.txt
+grip_client.egg-info/dependency_links.txt
+grip_client.egg-info/requires.txt
+grip_client.egg-info/top_level.txt
+grip_client/mmdb/__init__.py
+grip_client/mmdb/client.py
+grip_client/mmdb/models.py
+grip_client/rest/__init__.py
+grip_client/rest/cache.py
+grip_client/rest/client.py
+grip_client/rest/models.py

grip_client-0.1.1/grip_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

grip_client-0.1.1/grip_client.egg-info/requires.txt

@@ -0,0 +1,16 @@
+requests>=2.31
+
+[cache]
+cachetools>=5
+redis>=5
+
+[cachetools]
+cachetools>=5
+
+[mmdb]
+filelock>=3
+maxminddb>=2
+pycountry>=24
+
+[redis]
+redis>=5

grip_client-0.1.1/grip_client.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+dist
+grip_client

grip_client-0.1.1/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "grip-client"
+version = "0.1.1"
+description = "Python client for the GRIP API"
+requires-python = ">=3.10"
+dependencies = ["requests>=2.31"]
+
+[project.optional-dependencies]
+cachetools = ["cachetools>=5"]
+redis = ["redis>=5"]
+mmdb = ["filelock>=3", "maxminddb>=2", "pycountry>=24"]
+cache = ["cachetools>=5", "redis>=5"]
+
+[tool.setuptools.packages.find]
+where = ["."]

grip_client-0.1.1/setup.cfg

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