ipdatainfo 0.1.0__tar.gz

ipdatainfo-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e .
+      - run: python -m unittest discover -s tests -t . -v
+      - name: Live smoke test
+        run: IPDATA_LIVE=1 python -m unittest discover -s tests -t . -v -k test_live_lookup

ipdatainfo-0.1.0/.gitignore

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

ipdatainfo-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.1.0] - 2026-07-08
+### Added
+- Initial release: `lookup`, `geo`, `asn`, `batch`, `asn_detail`,
+  `asn_whois_history`, `asn_changes`, `threat_domain`, `threat_hash`,
+  `threat_url`.
+- `IpDataError` typed error; `Client(api_key, base_url, timeout)` constructor.
+- Zero required runtime dependencies (stdlib `urllib`/`json` only).

ipdatainfo-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+Thanks for considering a contribution to `ipdatainfo`.
+
+## Setup
+
+```
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Tests
+
+```
+python -m unittest discover -s tests -t . -v
+```
+
+To include the live smoke test against `https://ipdata.info` (requires network):
+
+```
+IPDATA_LIVE=1 python -m unittest discover -s tests -t . -v
+```
+
+## Pull requests
+
+- Keep changes scoped and add/update tests for behavior changes.
+- Match the method surface in [`docs/sdk-api-contract.md`](https://github.com/IPDataInfo/ipdata-python) —
+  this SDK must stay behaviorally identical to the other official ipdata.info SDKs.
+- Run the test suite before opening a PR.

ipdatainfo-0.1.0/LICENSE

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

ipdatainfo-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: ipdatainfo
+Version: 0.1.0
+Summary: Official Python client for the ipdata.info IP geolocation, ASN, and threat-intelligence API
+Project-URL: Homepage, https://ipdata.info
+Project-URL: Repository, https://github.com/IPDataInfo/ipdata-python
+Project-URL: Documentation, https://ipdata.info/docs/sdks
+Project-URL: Changelog, https://github.com/IPDataInfo/ipdata-python/blob/main/CHANGELOG.md
+Author: ipdata.info
+License-Expression: MIT
+License-File: LICENSE
+Keywords: geoip,ip-api,ip-geolocation,ip-lookup,ipdata,threat-intelligence
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# IPData.info Python SDK — Free IP Geolocation & Threat Intelligence API
+
+[![PyPI](https://img.shields.io/pypi/v/ipdatainfo.svg)](https://pypi.org/project/ipdatainfo/) [![CI](../../actions/workflows/ci.yml/badge.svg)](../../actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+
+Official Python client for [**ipdata.info**](https://ipdata.info) — a free,
+fast IP geolocation, ASN, and threat-intelligence API. Look up country, city,
+ASN, timezone, currency, and security flags (proxy/VPN/Tor/hosting) for any IPv4
+or IPv6 address. Powered by [ipdata.info](https://ipdata.info).
+
+## Get a free API key
+
+The public endpoint is **free — 50 requests/min, no signup, no key**. For higher
+rate limits and batch lookups, [**create a free API key at
+ipdata.info/register**](https://ipdata.info/register) and manage it in your
+[dashboard](https://ipdata.info/dashboard).
+
+## Install
+
+```
+pip install ipdatainfo
+```
+
+## Quickstart
+
+```python
+from ipdatainfo import Client
+
+# Free tier — no API key needed. For higher limits + batch, get a free key
+# at https://ipdata.info/register and use Client(api_key="...").
+client = Client()
+
+info = client.lookup("8.8.8.8")
+print(info.city, info.country, info.asn_org)  # Mountain View United States Google LLC
+```
+
+## Methods
+
+| Method | What it returns |
+|--------|-----------------|
+| `lookup(ip="")` | Full geolocation record (own IP if omitted) |
+| `geo(ip)` | Geo subset (city/region/country/lat/lon/tz) |
+| `asn(ip)` | ASN + ISP/registry for an IP |
+| `batch(ips)` | Many IPs at once (**requires an API key**) |
+| `asn_detail(n)` | ASN detail incl. prefixes |
+| `asn_whois_history(n)` | ASN whois history |
+| `asn_changes()` | ASN change feed |
+| `threat_domain/threat_hash/threat_url(x)` | Threat-intel lookup (domain / file hash / URL) |
+
+Full response schema: [ipdata.info API docs](https://ipdata.info/docs) ·
+[SDK contract](https://ipdata.info/docs/sdks).
+
+## Configuration
+
+```python
+from ipdatainfo import Client
+
+client = Client(
+    api_key="KEY",                        # sent as X-Api-Key; switches to pro.ipdata.info
+    base_url="https://ipdata.info",       # override the host
+    timeout=10.0,                          # seconds
+)
+```
+
+Errors from non-2xx responses are raised as `ipdatainfo.IpDataError` with
+`.status` and `.message`.
+
+## Rate limits
+
+- Free (`ipdata.info`): 50 req/min, no key.
+- Paid (`pro.ipdata.info`): higher limits + `batch`, with an
+  [API key](https://ipdata.info/register).
+
+## Other SDKs
+
+12 official SDKs — see the full list at
+[**ipdata.info/docs/sdks**](https://ipdata.info/docs/sdks): Python, Node.js, Go,
+PHP, Java, Rust, .NET, Kotlin, Swift, Dart, Bash, Objective-C.
+
+## License
+
+MIT © [ipdata.info](https://ipdata.info)

ipdatainfo-0.1.0/README.md

@@ -0,0 +1,81 @@
+# IPData.info Python SDK — Free IP Geolocation & Threat Intelligence API
+
+[![PyPI](https://img.shields.io/pypi/v/ipdatainfo.svg)](https://pypi.org/project/ipdatainfo/) [![CI](../../actions/workflows/ci.yml/badge.svg)](../../actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+
+Official Python client for [**ipdata.info**](https://ipdata.info) — a free,
+fast IP geolocation, ASN, and threat-intelligence API. Look up country, city,
+ASN, timezone, currency, and security flags (proxy/VPN/Tor/hosting) for any IPv4
+or IPv6 address. Powered by [ipdata.info](https://ipdata.info).
+
+## Get a free API key
+
+The public endpoint is **free — 50 requests/min, no signup, no key**. For higher
+rate limits and batch lookups, [**create a free API key at
+ipdata.info/register**](https://ipdata.info/register) and manage it in your
+[dashboard](https://ipdata.info/dashboard).
+
+## Install
+
+```
+pip install ipdatainfo
+```
+
+## Quickstart
+
+```python
+from ipdatainfo import Client
+
+# Free tier — no API key needed. For higher limits + batch, get a free key
+# at https://ipdata.info/register and use Client(api_key="...").
+client = Client()
+
+info = client.lookup("8.8.8.8")
+print(info.city, info.country, info.asn_org)  # Mountain View United States Google LLC
+```
+
+## Methods
+
+| Method | What it returns |
+|--------|-----------------|
+| `lookup(ip="")` | Full geolocation record (own IP if omitted) |
+| `geo(ip)` | Geo subset (city/region/country/lat/lon/tz) |
+| `asn(ip)` | ASN + ISP/registry for an IP |
+| `batch(ips)` | Many IPs at once (**requires an API key**) |
+| `asn_detail(n)` | ASN detail incl. prefixes |
+| `asn_whois_history(n)` | ASN whois history |
+| `asn_changes()` | ASN change feed |
+| `threat_domain/threat_hash/threat_url(x)` | Threat-intel lookup (domain / file hash / URL) |
+
+Full response schema: [ipdata.info API docs](https://ipdata.info/docs) ·
+[SDK contract](https://ipdata.info/docs/sdks).
+
+## Configuration
+
+```python
+from ipdatainfo import Client
+
+client = Client(
+    api_key="KEY",                        # sent as X-Api-Key; switches to pro.ipdata.info
+    base_url="https://ipdata.info",       # override the host
+    timeout=10.0,                          # seconds
+)
+```
+
+Errors from non-2xx responses are raised as `ipdatainfo.IpDataError` with
+`.status` and `.message`.
+
+## Rate limits
+
+- Free (`ipdata.info`): 50 req/min, no key.
+- Paid (`pro.ipdata.info`): higher limits + `batch`, with an
+  [API key](https://ipdata.info/register).
+
+## Other SDKs
+
+12 official SDKs — see the full list at
+[**ipdata.info/docs/sdks**](https://ipdata.info/docs/sdks): Python, Node.js, Go,
+PHP, Java, Rust, .NET, Kotlin, Swift, Dart, Bash, Objective-C.
+
+## License
+
+MIT © [ipdata.info](https://ipdata.info)

ipdatainfo-0.1.0/examples/asn_lookup.py

@@ -0,0 +1,17 @@
+"""ASN lookup example. Run: python examples/asn_lookup.py"""
+
+from ipdatainfo import Client
+
+
+def main() -> None:
+    client = Client()
+
+    brief = client.asn("8.8.8.8")
+    print(f"ASN {brief.asn} ({brief.asn_org}) via {brief.isp}, registry {brief.registry}")
+
+    detail = client.asn_detail(brief.asn)
+    print(f"AS name: {detail.get('as_name')}, IPv4 prefixes: {detail.get('ipv4_prefix_count')}")
+
+
+if __name__ == "__main__":
+    main()

ipdatainfo-0.1.0/examples/batch_lookup.py

@@ -0,0 +1,26 @@
+"""Batch lookup example (requires a paid API key). See https://ipdata.info/register.
+
+Run: IPDATA_API_KEY=your_key python examples/batch_lookup.py
+"""
+
+import os
+
+from ipdatainfo import Client, IpDataError
+
+
+def main() -> None:
+    api_key = os.environ.get("IPDATA_API_KEY")
+    client = Client(api_key=api_key)
+
+    try:
+        results = client.batch(["8.8.8.8", "1.1.1.1"])
+    except IpDataError as exc:
+        print(f"batch failed ({exc.status}): {exc.message}")
+        return
+
+    for info in results:
+        print(f"{info.ip}: {info.city}, {info.country}")
+
+
+if __name__ == "__main__":
+    main()

ipdatainfo-0.1.0/examples/quickstart.py

@@ -0,0 +1,22 @@
+"""Quickstart example for the ipdata.info Python SDK.
+
+Run: python examples/quickstart.py
+"""
+
+from ipdatainfo import Client
+
+
+def main() -> None:
+    # Free tier -- no API key needed. For higher limits + batch, get a free
+    # key at https://ipdata.info/register and use Client(api_key="...").
+    client = Client()
+
+    info = client.lookup("8.8.8.8")
+    print(f"{info.ip} is in {info.city}, {info.country} (ASN {info.asn} — {info.asn_org})")
+
+    threat = client.threat_domain("example.com")
+    print(f"example.com listed as a threat: {threat.listed}")
+
+
+if __name__ == "__main__":
+    main()

ipdatainfo-0.1.0/examples/threat_lookup.py

@@ -0,0 +1,20 @@
+"""Threat-intel lookup example. Run: python examples/threat_lookup.py"""
+
+from ipdatainfo import Client
+
+
+def main() -> None:
+    client = Client()
+
+    domain = client.threat_domain("example.com")
+    print(f"domain example.com listed: {domain.listed}")
+
+    url = client.threat_url("https://example.com/path")
+    print(f"url listed: {url.listed}")
+
+    file_hash = client.threat_hash("d41d8cd98f00b204e9800998ecf8427e")
+    print(f"hash listed: {file_hash.listed}")
+
+
+if __name__ == "__main__":
+    main()

ipdatainfo-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ipdatainfo"
+version = "0.1.0"
+description = "Official Python client for the ipdata.info IP geolocation, ASN, and threat-intelligence API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.8"
+authors = [
+    { name = "ipdata.info" },
+]
+keywords = [
+    "ip-geolocation",
+    "ip-api",
+    "geoip",
+    "ip-lookup",
+    "threat-intelligence",
+    "ipdata",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://ipdata.info"
+Repository = "https://github.com/IPDataInfo/ipdata-python"
+Documentation = "https://ipdata.info/docs/sdks"
+Changelog = "https://github.com/IPDataInfo/ipdata-python/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ipdatainfo"]

ipdatainfo-0.1.0/src/ipdatainfo/__init__.py

@@ -0,0 +1,36 @@
+"""Official Python client for the ipdata.info IP geolocation, ASN, and
+threat-intelligence API. See https://ipdata.info.
+"""
+
+from .client import DEFAULT_BASE_URL, PRO_BASE_URL, Client, __version__
+from .errors import IpDataError
+from .models import (
+    ASNBrief,
+    Connection,
+    Currency,
+    Flag,
+    GeoInfo,
+    IPInfo,
+    Network,
+    Security,
+    ThreatMatch,
+    TimeZone,
+)
+
+__all__ = [
+    "Client",
+    "IpDataError",
+    "DEFAULT_BASE_URL",
+    "PRO_BASE_URL",
+    "__version__",
+    "IPInfo",
+    "GeoInfo",
+    "ASNBrief",
+    "ThreatMatch",
+    "Network",
+    "Flag",
+    "Connection",
+    "TimeZone",
+    "Currency",
+    "Security",
+]

ipdatainfo-0.1.0/src/ipdatainfo/client.py

@@ -0,0 +1,161 @@
+"""HTTP client for the ipdata.info API.
+
+Uses only the standard library (``urllib.request``/``json``) so the package
+has zero required runtime dependencies.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from .errors import IpDataError
+from .models import ASNBrief, GeoInfo, IPInfo, ThreatMatch
+
+#: Free tier host (50 req/min, no key).
+DEFAULT_BASE_URL = "https://ipdata.info"
+#: Paid tier host, used automatically once an API key is set (unless the
+#: caller overrides ``base_url`` explicitly).
+PRO_BASE_URL = "https://pro.ipdata.info"
+
+__version__ = "0.1.0"
+_USER_AGENT = f"ipdatainfo-python/{__version__}"
+
+
+class Client:
+    """ipdata.info API client.
+
+    Args:
+        api_key: Optional API key, sent as the ``X-Api-Key`` header. When
+            set and ``base_url`` is not overridden, the client targets the
+            pro tier host automatically.
+        base_url: API host, no trailing slash. Defaults to the free tier
+            (``https://ipdata.info``), or the pro tier when ``api_key`` is
+            set.
+        timeout: Request timeout in seconds. Defaults to 10.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 10.0,
+    ) -> None:
+        self.api_key = api_key
+        if base_url is not None:
+            self.base_url = base_url.rstrip("/")
+        elif api_key:
+            self.base_url = PRO_BASE_URL
+        else:
+            self.base_url = DEFAULT_BASE_URL
+        self.timeout = timeout
+
+    # -- lookup family -----------------------------------------------------
+
+    def lookup(self, ip: str = "") -> IPInfo:
+        """Return the full record for ``ip``. Empty string = caller's own IP."""
+        data = self._get(f"/json/{urllib.parse.quote(ip, safe='')}")
+        return IPInfo.from_dict(data)
+
+    def geo(self, ip: str) -> GeoInfo:
+        """Return the compact geo subset for ``ip``."""
+        data = self._get(f"/api/v1/{urllib.parse.quote(ip, safe='')}/geo")
+        return GeoInfo.from_dict(data)
+
+    def asn(self, ip: str) -> ASNBrief:
+        """Return the compact ASN subset for ``ip``."""
+        data = self._get(f"/api/v1/{urllib.parse.quote(ip, safe='')}/asn")
+        return ASNBrief.from_dict(data)
+
+    def batch(self, ips: list[str]) -> list[IPInfo]:
+        """Look up many IPs at once. Requires an API key (paid tier)."""
+        data = self._post("/api/v1/batch", ips)
+        if not isinstance(data, list):
+            raise IpDataError(status=200, message="unexpected batch response shape")
+        return [IPInfo.from_dict(item) for item in data]
+
+    # -- ASN metadata --------------------------------------------------
+
+    def asn_detail(self, number: int) -> dict[str, Any]:
+        """Return the detailed ASN record (prefixes, peering) as raw JSON."""
+        return self._get(f"/api/v1/asn/{number}")
+
+    def asn_whois_history(self, number: int) -> dict[str, Any]:
+        """Return the ASN whois history as raw JSON."""
+        return self._get(f"/api/v1/asn/{number}/whois-history")
+
+    def asn_changes(self) -> Any:
+        """Return the ASN change feed as raw JSON."""
+        return self._get("/api/v1/asn-changes")
+
+    # -- threat intel --------------------------------------------------
+
+    def threat_domain(self, domain: str) -> ThreatMatch:
+        """Look up a domain in the threat-intel store."""
+        data = self._get(f"/api/v1/threat/domain/{urllib.parse.quote(domain, safe='')}")
+        return ThreatMatch.from_dict(data)
+
+    def threat_hash(self, hash: str) -> ThreatMatch:
+        """Look up a file hash (md5/sha1/sha256)."""
+        data = self._get(f"/api/v1/threat/hash/{urllib.parse.quote(hash, safe='')}")
+        return ThreatMatch.from_dict(data)
+
+    def threat_url(self, url: str) -> ThreatMatch:
+        """Look up a URL (server falls back to its domain on a miss)."""
+        query = urllib.parse.urlencode({"u": url})
+        data = self._get(f"/api/v1/threat/url?{query}")
+        return ThreatMatch.from_dict(data)
+
+    # -- internals -----------------------------------------------------
+
+    def _get(self, path: str) -> Any:
+        return self._request("GET", path, body=None)
+
+    def _post(self, path: str, payload: Any) -> Any:
+        body = json.dumps(payload).encode("utf-8")
+        return self._request("POST", path, body=body)
+
+    def _request(self, method: str, path: str, body: bytes | None) -> Any:
+        url = self.base_url + path
+        headers = {
+            "User-Agent": _USER_AGENT,
+            "Accept": "application/json",
+        }
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        if self.api_key:
+            headers["X-Api-Key"] = self.api_key
+
+        req = urllib.request.Request(url, data=body, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                raw = resp.read()
+                status = resp.status
+        except urllib.error.HTTPError as exc:
+            raw = exc.read()
+            raise IpDataError(status=exc.code, message=_error_message(raw)) from exc
+        except urllib.error.URLError as exc:
+            raise IpDataError(status=0, message=str(exc.reason)) from exc
+
+        if status < 200 or status >= 300:
+            raise IpDataError(status=status, message=_error_message(raw))
+
+        if not raw:
+            return {}
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise IpDataError(status=status, message=f"decode response: {exc}") from exc
+
+
+def _error_message(raw: bytes) -> str:
+    try:
+        parsed = json.loads(raw)
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        return raw.decode("utf-8", errors="replace")
+    if isinstance(parsed, dict) and parsed.get("error"):
+        return str(parsed["error"])
+    return raw.decode("utf-8", errors="replace")

ipdatainfo-0.1.0/src/ipdatainfo/errors.py

@@ -0,0 +1,18 @@
+"""Error types for the ipdatainfo client."""
+
+from __future__ import annotations
+
+
+class IpDataError(Exception):
+    """Raised for any non-2xx response from the ipdata.info API.
+
+    Attributes:
+        status: HTTP status code of the response.
+        message: Error message parsed from the ``{"error": "..."}`` body,
+            or the raw response body when that shape is absent.
+    """
+
+    def __init__(self, status: int, message: str) -> None:
+        self.status = status
+        self.message = message
+        super().__init__(f"ipdatainfo: HTTP {status}: {message}")

ipdatainfo-0.1.0/src/ipdatainfo/models.py

@@ -0,0 +1,286 @@
+"""Response models for the ipdatainfo client.
+
+All dataclasses tolerate missing and unknown JSON fields: the API omits
+null/empty fields from responses, and future API additions should not break
+older SDK versions. Each model exposes a ``from_dict`` classmethod that reads
+known keys and ignores everything else.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+def _get(data: dict[str, Any], key: str, default: Any = None) -> Any:
+    value = data.get(key, default)
+    return value if value is not None else default
+
+
+@dataclass
+class Network:
+    asn: int = 0
+    as_name: str = ""
+    route: str = ""
+    registry_country: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "Network | None":
+        if not data:
+            return None
+        return cls(
+            asn=_get(data, "asn", 0),
+            as_name=_get(data, "as_name", ""),
+            route=_get(data, "route", ""),
+            registry_country=_get(data, "registry_country", ""),
+        )
+
+
+@dataclass
+class Flag:
+    img: str = ""
+    emoji: str = ""
+    emoji_unicode: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "Flag | None":
+        if not data:
+            return None
+        return cls(
+            img=_get(data, "img", ""),
+            emoji=_get(data, "emoji", ""),
+            emoji_unicode=_get(data, "emoji_unicode", ""),
+        )
+
+
+@dataclass
+class Connection:
+    asn: int = 0
+    org: str = ""
+    isp: str = ""
+    domain: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "Connection | None":
+        if not data:
+            return None
+        return cls(
+            asn=_get(data, "asn", 0),
+            org=_get(data, "org", ""),
+            isp=_get(data, "isp", ""),
+            domain=_get(data, "domain", ""),
+        )
+
+
+@dataclass
+class TimeZone:
+    id: str = ""
+    abbr: str = ""
+    is_dst: bool = False
+    offset: int = 0
+    utc: str = ""
+    current_time: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "TimeZone | None":
+        if not data:
+            return None
+        return cls(
+            id=_get(data, "id", ""),
+            abbr=_get(data, "abbr", ""),
+            is_dst=_get(data, "is_dst", False),
+            offset=_get(data, "offset", 0),
+            utc=_get(data, "utc", ""),
+            current_time=_get(data, "current_time", ""),
+        )
+
+
+@dataclass
+class Currency:
+    name: str = ""
+    code: str = ""
+    symbol: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "Currency | None":
+        if not data:
+            return None
+        return cls(
+            name=_get(data, "name", ""),
+            code=_get(data, "code", ""),
+            symbol=_get(data, "symbol", ""),
+        )
+
+
+@dataclass
+class Security:
+    anonymous: bool = False
+    proxy: bool = False
+    vpn: bool = False
+    tor: bool = False
+    hosting: bool = False
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "Security | None":
+        if not data:
+            return None
+        return cls(
+            anonymous=_get(data, "anonymous", False),
+            proxy=_get(data, "proxy", False),
+            vpn=_get(data, "vpn", False),
+            tor=_get(data, "tor", False),
+            hosting=_get(data, "hosting", False),
+        )
+
+
+@dataclass
+class IPInfo:
+    """Full geolocation record returned by ``lookup``.
+
+    The API omits null/empty fields, so most fields default to a falsy value
+    (empty string, 0, False) when absent.
+    """
+
+    ip: str = ""
+    success: bool = False
+    type: str = ""
+    continent: str = ""
+    continent_code: str = ""
+    country: str = ""
+    country_code: str = ""
+    region: str = ""
+    city: str = ""
+    latitude: float = 0.0
+    longitude: float = 0.0
+    is_eu: bool = False
+    timezone: str = ""
+    zip: str = ""
+    postal: str = ""
+    calling_code: str = ""
+    capital: str = ""
+    borders: str = ""
+    asn: int = 0
+    asn_org: str = ""
+    isp: str = ""
+    registry: str = ""
+    is_proxy: bool = False
+    is_hosting: bool = False
+    network: Network | None = None
+    flag: Flag | None = None
+    connection: Connection | None = None
+    time_zone: TimeZone | None = None
+    currency: Currency | None = None
+    security: Security | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "IPInfo":
+        return cls(
+            ip=_get(data, "ip", ""),
+            success=_get(data, "success", False),
+            type=_get(data, "type", ""),
+            continent=_get(data, "continent", ""),
+            continent_code=_get(data, "continent_code", ""),
+            country=_get(data, "country", ""),
+            country_code=_get(data, "country_code", ""),
+            region=_get(data, "region", ""),
+            city=_get(data, "city", ""),
+            latitude=_get(data, "latitude", 0.0),
+            longitude=_get(data, "longitude", 0.0),
+            is_eu=_get(data, "is_eu", False),
+            timezone=_get(data, "timezone", ""),
+            zip=_get(data, "zip", ""),
+            postal=_get(data, "postal", ""),
+            calling_code=_get(data, "calling_code", ""),
+            capital=_get(data, "capital", ""),
+            borders=_get(data, "borders", ""),
+            asn=_get(data, "asn", 0),
+            asn_org=_get(data, "asn_org", ""),
+            isp=_get(data, "isp", ""),
+            registry=_get(data, "registry", ""),
+            is_proxy=_get(data, "is_proxy", False),
+            is_hosting=_get(data, "is_hosting", False),
+            network=Network.from_dict(data.get("network")),
+            flag=Flag.from_dict(data.get("flag")),
+            connection=Connection.from_dict(data.get("connection")),
+            time_zone=TimeZone.from_dict(data.get("time_zone")),
+            currency=Currency.from_dict(data.get("currency")),
+            security=Security.from_dict(data.get("security")),
+        )
+
+
+@dataclass
+class GeoInfo:
+    """Compact geo subset returned by ``geo``."""
+
+    ip: str = ""
+    city: str = ""
+    region: str = ""
+    country: str = ""
+    country_code: str = ""
+    latitude: float = 0.0
+    longitude: float = 0.0
+    timezone: str = ""
+    zip: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "GeoInfo":
+        return cls(
+            ip=_get(data, "ip", ""),
+            city=_get(data, "city", ""),
+            region=_get(data, "region", ""),
+            country=_get(data, "country", ""),
+            country_code=_get(data, "country_code", ""),
+            latitude=_get(data, "latitude", 0.0),
+            longitude=_get(data, "longitude", 0.0),
+            timezone=_get(data, "timezone", ""),
+            zip=_get(data, "zip", ""),
+        )
+
+
+@dataclass
+class ASNBrief:
+    """Compact ASN subset returned by ``asn``."""
+
+    ip: str = ""
+    asn: int = 0
+    asn_org: str = ""
+    isp: str = ""
+    registry: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ASNBrief":
+        return cls(
+            ip=_get(data, "ip", ""),
+            asn=_get(data, "asn", 0),
+            asn_org=_get(data, "asn_org", ""),
+            isp=_get(data, "isp", ""),
+            registry=_get(data, "registry", ""),
+        )
+
+
+@dataclass
+class ThreatMatch:
+    """Result of a threat-intel lookup. When ``listed`` is False the
+    remaining fields default to empty."""
+
+    value: str = ""
+    ioc_type: str = ""
+    listed: bool = False
+    threat_type: str = ""
+    sources: list[str] = field(default_factory=list)
+    confidence: int = 0
+    first_seen: str = ""
+    last_seen: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ThreatMatch":
+        return cls(
+            value=_get(data, "value", ""),
+            ioc_type=_get(data, "ioc_type", ""),
+            listed=_get(data, "listed", False),
+            threat_type=_get(data, "threat_type", ""),
+            sources=_get(data, "sources", []) or [],
+            confidence=_get(data, "confidence", 0),
+            first_seen=_get(data, "first_seen", ""),
+            last_seen=_get(data, "last_seen", ""),
+        )

ipdatainfo-0.1.0/tests/mock_server.py

@@ -0,0 +1,57 @@
+"""Minimal local mock HTTP server used by the unit tests, mirroring the
+Go SDK's use of ``net/http/httptest``.
+"""
+
+from __future__ import annotations
+
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Callable
+
+
+class MockServer:
+    """Runs a ``BaseHTTPRequestHandler``-backed server on a background thread.
+
+    ``handler_fn`` receives the request path and must return
+    ``(status_code, body_bytes)``.
+    """
+
+    def __init__(self, handler_fn: Callable[[str], tuple[int, bytes]]) -> None:
+        outer = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def _handle(self) -> None:
+                length = int(self.headers.get("Content-Length", 0))
+                if length:
+                    self.rfile.read(length)
+                status, body = outer.handler_fn(self.path)
+                self.send_response(status)
+                self.send_header("Content-Type", "application/json")
+                self.end_headers()
+                self.wfile.write(body)
+
+            def do_GET(self) -> None:  # noqa: N802 (stdlib API name)
+                self._handle()
+
+            def do_POST(self) -> None:  # noqa: N802 (stdlib API name)
+                self._handle()
+
+            def log_message(self, format: str, *args: object) -> None:  # silence
+                pass
+
+        self.handler_fn = handler_fn
+        self.httpd = HTTPServer(("127.0.0.1", 0), Handler)
+        self.thread = threading.Thread(target=self.httpd.serve_forever, daemon=True)
+
+    @property
+    def url(self) -> str:
+        host, port = self.httpd.server_address[:2]
+        return f"http://{host}:{port}"
+
+    def start(self) -> "MockServer":
+        self.thread.start()
+        return self
+
+    def stop(self) -> None:
+        self.httpd.shutdown()
+        self.httpd.server_close()

ipdatainfo-0.1.0/tests/test_client.py

@@ -0,0 +1,73 @@
+"""Unit tests for the ipdatainfo client, using a local mock HTTP server."""
+
+from __future__ import annotations
+
+import unittest
+
+from ipdatainfo import Client, IpDataError
+from ipdatainfo.client import PRO_BASE_URL
+
+from .mock_server import MockServer
+
+
+class TestLookupParsesResponse(unittest.TestCase):
+    def test_lookup_parses_response(self) -> None:
+        body = (
+            b'{"ip":"8.8.8.8","success":true,"type":"IPv4",'
+            b'"country":"United States","country_code":"US","asn":15169,'
+            b'"security":{"tor":false,"proxy":false}}'
+        )
+        seen_paths: list[str] = []
+
+        def handler(path: str) -> tuple[int, bytes]:
+            seen_paths.append(path)
+            return 200, body
+
+        server = MockServer(handler).start()
+        try:
+            client = Client(base_url=server.url)
+            info = client.lookup("8.8.8.8")
+        finally:
+            server.stop()
+
+        self.assertEqual(seen_paths, ["/json/8.8.8.8"])
+        self.assertEqual(info.country_code, "US")
+        self.assertEqual(info.asn, 15169)
+        self.assertIsNotNone(info.security)
+        assert info.security is not None
+        self.assertFalse(info.security.tor)
+
+
+class TestErrorResponse(unittest.TestCase):
+    def test_error_response_raises_ipdata_error(self) -> None:
+        def handler(path: str) -> tuple[int, bytes]:
+            return 403, b'{"error":"batch lookup requires a paid tier API key"}'
+
+        server = MockServer(handler).start()
+        try:
+            client = Client(base_url=server.url)
+            with self.assertRaises(IpDataError) as ctx:
+                client.batch(["8.8.8.8"])
+        finally:
+            server.stop()
+
+        self.assertEqual(ctx.exception.status, 403)
+        self.assertTrue(ctx.exception.message)
+
+
+class TestKeySwitchesToProHost(unittest.TestCase):
+    def test_key_switches_to_pro_host(self) -> None:
+        client = Client(api_key="secret")
+        self.assertEqual(client.base_url, PRO_BASE_URL)
+
+    def test_no_key_uses_free_host(self) -> None:
+        client = Client()
+        self.assertEqual(client.base_url, "https://ipdata.info")
+
+    def test_explicit_base_url_overrides_key_default(self) -> None:
+        client = Client(api_key="secret", base_url="https://example.test")
+        self.assertEqual(client.base_url, "https://example.test")
+
+
+if __name__ == "__main__":
+    unittest.main()

ipdatainfo-0.1.0/tests/test_live_smoke.py

@@ -0,0 +1,24 @@
+"""Live smoke test against the real free-tier endpoint.
+
+Skipped unless IPDATA_LIVE=1 (requires network access).
+"""
+
+from __future__ import annotations
+
+import os
+import unittest
+
+from ipdatainfo import Client
+
+
+@unittest.skipUnless(os.environ.get("IPDATA_LIVE"), "set IPDATA_LIVE=1 to run the live smoke test")
+class TestLiveSmoke(unittest.TestCase):
+    def test_live_lookup(self) -> None:
+        client = Client()
+        info = client.lookup("8.8.8.8")
+        self.assertTrue(info.success)
+        self.assertEqual(info.ip, "8.8.8.8")
+
+
+if __name__ == "__main__":
+    unittest.main()