ipclues 0.1.0__tar.gz

ipclues-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: ipclues
+Version: 0.1.0
+Summary: Official IPClues SDK for Python
+Keywords: ip,geolocation,network-intelligence,ipclues,api
+Author: Rufai Limantawa
+Author-email: Rufai Limantawa <rufailimantawa@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Dist: ruff>=0.17.3 ; extra == 'dev'
+Requires-Dist: twine>=7.0 ; extra == 'dev'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://ipclues.com
+Project-URL: Repository, https://github.com/ipclues/python-sdk
+Project-URL: Issues, https://github.com/ipclues/python-sdk/issues
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# IPClues Python SDK
+
+Official Python SDK for the [IPClues](https://ipclues.com) IP intelligence API.
+
+## Requirements
+
+- Python 3.10+
+- An IPClues API key
+
+## Install
+
+```bash
+python -m pip install ipclues
+```
+
+## Quick start
+
+```python
+import os
+from ipclues import Client, Database
+
+client = Client("YOUR_API_KEY")
+
+response = client.lookup(
+    "1.1.1.1",
+    db=[Database.GEO_I3_LITE, Database.NET_I3_IDENTITY],
+)
+
+print(response.data)
+print(response.metadata.status)
+print(response.metadata.credits_remaining)
+print(response.metadata.database_versions)
+```
+
+## Response behavior
+
+The SDK wraps the API response body and HTTP metadata:
+
+- `response.data`: original decoded response body.
+- `response.metadata.status`: HTTP status code.
+- `response.metadata.request_id`: `I3-Request-Id` header.
+- `response.metadata.credits_charged` and `credits_remaining`: credit usage headers.
+- `response.metadata.databases` and `database_versions`: response database headers.
+- `response.metadata.rate_limit`: parsed rate-limit headers.
+
+HTTP error responses such as 401, 402, and 429 are returned as `APIResponse` objects too. Network failures and timeouts raise exceptions.
+
+## License
+
+MIT

ipclues-0.1.0/README.md

@@ -0,0 +1,50 @@
+# IPClues Python SDK
+
+Official Python SDK for the [IPClues](https://ipclues.com) IP intelligence API.
+
+## Requirements
+
+- Python 3.10+
+- An IPClues API key
+
+## Install
+
+```bash
+python -m pip install ipclues
+```
+
+## Quick start
+
+```python
+import os
+from ipclues import Client, Database
+
+client = Client("YOUR_API_KEY")
+
+response = client.lookup(
+    "1.1.1.1",
+    db=[Database.GEO_I3_LITE, Database.NET_I3_IDENTITY],
+)
+
+print(response.data)
+print(response.metadata.status)
+print(response.metadata.credits_remaining)
+print(response.metadata.database_versions)
+```
+
+## Response behavior
+
+The SDK wraps the API response body and HTTP metadata:
+
+- `response.data`: original decoded response body.
+- `response.metadata.status`: HTTP status code.
+- `response.metadata.request_id`: `I3-Request-Id` header.
+- `response.metadata.credits_charged` and `credits_remaining`: credit usage headers.
+- `response.metadata.databases` and `database_versions`: response database headers.
+- `response.metadata.rate_limit`: parsed rate-limit headers.
+
+HTTP error responses such as 401, 402, and 429 are returned as `APIResponse` objects too. Network failures and timeouts raise exceptions.
+
+## License
+
+MIT

ipclues-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["uv_build>=0.13.6,<0.14"]
+build-backend = "uv_build"
+
+[project]
+name = "ipclues"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "Official IPClues SDK for Python"
+readme = "README.md"
+license = "MIT"
+keywords = [
+    "ip",
+    "geolocation",
+    "network-intelligence",
+    "ipclues",
+    "api",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "Rufai Limantawa"
+email = "rufailimantawa@gmail.com"
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.17.3",
+    "twine>=7.0",
+]
+
+[project.urls]
+Homepage = "https://ipclues.com"
+Repository = "https://github.com/ipclues/python-sdk"
+Issues = "https://github.com/ipclues/python-sdk/issues"
+
+[tool.uv]
+package = true
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"

ipclues-0.1.0/pyproject.toml.orig

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["uv_build>=0.13.6,<0.14"]
+build-backend = "uv_build"
+
+[project]
+name = "ipclues"
+version = "0.1.0"
+requires-python = ">=3.10"
+authors = [{ name = "Rufai Limantawa", email = "rufailimantawa@gmail.com" }]
+description = "Official IPClues SDK for Python"
+readme = "README.md"
+license = "MIT"
+keywords = ["ip", "geolocation", "network-intelligence", "ipclues", "api"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["ruff>=0.17.3", "twine>=7.0"]
+
+[project.urls]
+Homepage = "https://ipclues.com"
+Repository = "https://github.com/ipclues/python-sdk"
+Issues = "https://github.com/ipclues/python-sdk/issues"
+
+[tool.uv]
+package = true
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"

ipclues-0.1.0/src/ipclues/__init__.py

@@ -0,0 +1,14 @@
+from .client import Client
+from .database import Database
+from .exceptions import IPCluesError
+from .response import APIResponse, APIResponseData, RateLimitMetadata, ResponseMetadata
+
+__all__ = [
+    "APIResponse",
+    "APIResponseData",
+    "Client",
+    "Database",
+    "IPCluesError",
+    "RateLimitMetadata",
+    "ResponseMetadata",
+]

ipclues-0.1.0/src/ipclues/client.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlencode
+from urllib.request import Request, urlopen
+
+from .database import Database
+from .exceptions import IPCluesError
+from .response import APIResponse, APIResponseData, make_response
+
+
+class Client:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.ipclues.com/v1",
+        timeout: float = 10.0,
+    ) -> None:
+        if not api_key.strip():
+            raise ValueError("IPClues API key is required")
+        if timeout <= 0:
+            raise ValueError("Timeout must be a positive number")
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+
+    def lookup(
+        self,
+        ip: str,
+        *,
+        db: Database | list[Database] | tuple[Database, ...] | None = None,
+    ) -> APIResponse[APIResponseData]:
+        if not ip.strip():
+            raise ValueError("IP address is required")
+
+        query = ""
+        if db is not None:
+            databases = [db] if isinstance(db, Database) else list(db)
+            if not databases:
+                raise ValueError("At least one database must be selected")
+            if not all(isinstance(item, Database) for item in databases):
+                raise ValueError("Every database must be a Database enum")
+            query = "?" + urlencode({"db": ",".join(item.value for item in databases)})
+
+        url = f"{self._base_url}/lookup/ip/{quote(ip, safe='')}{query}"
+        request = Request(
+            url,
+            headers={
+                "Authorization": f"Bearer {self._api_key}",
+                "Accept": "application/json",
+            },
+        )
+
+        try:
+            with urlopen(request, timeout=self._timeout) as response:
+                return make_response(
+                    response.status,
+                    getattr(response, "reason", ""),
+                    response.headers,
+                    response.read(),
+                )
+        except HTTPError as error:
+            # HTTPError contains the response body and headers; return the envelope.
+            try:
+                return make_response(
+                    error.code, error.reason, error.headers, error.read()
+                )
+            finally:
+                error.close()
+        except URLError as error:
+            raise IPCluesError(f"IPClues request failed: {error.reason}") from error

ipclues-0.1.0/src/ipclues/database.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+
+class Database(str, Enum):
+    GEO_I3_LITE = "geoi3-lite"
+    GEO_I3_COUNTRY = "geoi3-country"
+    NET_I3_IDENTITY = "neti3-identity"

ipclues-0.1.0/src/ipclues/exceptions.py

@@ -0,0 +1,2 @@
+class IPCluesError(Exception):
+    """Base exception for IPClues SDK request failures."""

ipclues-0.1.0/src/ipclues/response.py

@@ -0,0 +1,116 @@
+import json
+import re
+from dataclasses import dataclass
+from http import HTTPStatus
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+APIResponseData = dict[str, Any]
+
+
+def integer(value: str | None) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def database_versions(value: str | None) -> dict[str, str] | None:
+    if not value:
+        return None
+    result: dict[str, str] = {}
+    for item in value.split(","):
+        key, separator, version = item.partition("=")
+        if separator and key.strip() and version.strip():
+            result[key.strip()] = version.strip()
+    return result or None
+
+
+def decode_body(raw: bytes) -> Any:
+    text = raw.decode("utf-8", errors="replace")
+    if not text:
+        return None
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return text
+
+
+def make_response(
+    status: int, phrase: str, headers: Any, raw: bytes
+) -> "APIResponse"[Any]:
+    try:
+        reason = HTTPStatus(status).phrase
+    except ValueError:
+        reason = phrase or ""
+
+    databases = headers.get("I3-Databases")
+    metadata = ResponseMetadata(
+        status=status,
+        reason=reason,
+        request_id=headers.get("I3-Request-Id"),
+        credits_charged=integer(headers.get("I3-Credits-Charged")),
+        credits_remaining=integer(headers.get("I3-Credits-Remaining")),
+        databases=(
+            [item.strip() for item in databases.split(",") if item.strip()]
+            if databases
+            else None
+        ),
+        database_versions=database_versions(headers.get("I3-Database-Versions")),
+        rate_limit=rate_limit(
+            headers.get("Ratelimit"),
+            headers.get("Ratelimit-Policy"),
+            headers.get("Retry-After"),
+        ),
+    )
+    return APIResponse(data=decode_body(raw), metadata=metadata)
+
+
+def rate_limit(
+    value: str | None, policy_value: str | None, retry_value: str | None
+) -> "RateLimitMetadata":
+    def parameter(source: str | None, name: str) -> int | None:
+        match = re.search(rf"(?:^|;)\s*{name}=(\d+)", source or "")
+        return integer(match.group(1)) if match else None
+
+    match = re.match(r'^"?([^";]+)"?', value or "")
+    policy_match = re.match(r'^"?([^";]+)"?', policy_value or "")
+
+    return RateLimitMetadata(
+        policy=(
+            match.group(1) if match else policy_match.group(1) if policy_match else None
+        ),
+        limit=parameter(value, "q"),
+        remaining=parameter(value, "r"),
+        reset=parameter(value, "t"),
+        retry_after=integer(retry_value),
+    )
+
+
+@dataclass(frozen=True)
+class APIResponse(Generic[T]):
+    data: T
+    metadata: "ResponseMetadata"
+
+
+@dataclass(frozen=True)
+class RateLimitMetadata:
+    policy: str | None = None
+    limit: int | None = None
+    remaining: int | None = None
+    reset: int | None = None
+    retry_after: int | None = None
+
+
+@dataclass(frozen=True)
+class ResponseMetadata:
+    status: int
+    reason: str
+    request_id: str | None = None
+    credits_charged: int | None = None
+    credits_remaining: int | None = None
+    databases: list[str] | None = None
+    database_versions: dict[str, str] | None = None
+    rate_limit: RateLimitMetadata | None = None