ipwhois-python 1.0.0__py3-none-any.whl

ipwhois/__init__.py

@@ -0,0 +1,11 @@
+"""Official Python client for the ipwhois.io IP Geolocation API.
+
+See :class:`ipwhois.Client` for usage. The library never raises -- every
+failure comes back inside the response dict with ``success`` set to ``False``
+and a ``message``.
+"""
+
+from .client import Client
+
+__all__ = ["Client", "__version__"]
+__version__ = Client.VERSION

ipwhois/client.py

@@ -0,0 +1,518 @@
+"""Python client for the ipwhois.io IP Geolocation API.
+
+Quick start
+-----------
+    # Free plan (no API key, ~1 request/second per client IP)
+    client = ipwhois.Client()
+    info   = client.lookup("8.8.8.8")
+
+    # Paid plan (with API key, higher limits, bulk, security data, ...)
+    client = ipwhois.Client("YOUR_API_KEY")
+    info   = client.lookup("8.8.8.8", lang="en", security=True)
+
+    # Bulk lookup -- up to 100 IPs in one call (paid only)
+    rows = client.bulk_lookup(["8.8.8.8", "1.1.1.1", "208.67.222.222"])
+
+    # HTTPS is enabled by default. Pass ssl=False to fall back to HTTP.
+
+Error handling
+--------------
+The library never raises. All errors -- invalid input, network failure,
+API-level errors (bad IP, bad key, rate limit, ...) -- are returned in the
+response dict with ``success`` set to ``False`` and a ``message``. Just check
+``info["success"]`` after every call.
+"""
+
+from __future__ import annotations
+
+import json
+import socket
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Iterable, List, Optional, Union
+
+__all__ = ["Client"]
+
+# Public type alias: a single API response (lookup or whole-batch error).
+Response = Dict[str, Any]
+# Public type alias: a bulk response -- list on success, error dict otherwise.
+BulkResponse = Union[List[Response], Response]
+
+
+class Client:
+    """Client for the ipwhois.io IP Geolocation API.
+
+    The same class is used for both the Free and Paid plans -- the only
+    difference is whether you pass an API key. See module docstring for
+    a quick start.
+
+    The library never raises. Every failure -- invalid IP, bad API key, rate
+    limit, network outage, bad options -- comes back inside the response dict
+    with ``success`` set to ``False`` and a ``message``.
+    """
+
+    #: Library version, used in the default User-Agent header.
+    VERSION: str = "1.0.0"
+
+    #: Free-plan endpoint host (used when no API key is provided).
+    HOST_FREE: str = "ipwho.is"
+
+    #: Paid-plan endpoint host (used when an API key is provided).
+    HOST_PAID: str = "ipwhois.pro"
+
+    #: Maximum number of IP addresses allowed in a single bulk request.
+    BULK_LIMIT: int = 100
+
+    #: Languages supported by the ``lang`` parameter.
+    SUPPORTED_LANGUAGES: tuple = (
+        "en",
+        "ru",
+        "de",
+        "es",
+        "pt-BR",
+        "fr",
+        "zh-CN",
+        "ja",
+    )
+
+    #: Output formats supported by the ``output`` parameter.
+    SUPPORTED_OUTPUTS: tuple = ("json", "xml", "csv")
+
+    def __init__(self, api_key: Optional[str] = None, **options: Any) -> None:
+        """Create a new client.
+
+        :param api_key: Your ipwhois.io API key. Omit for the free plan.
+        :param options: Optional defaults applied to every request. Recognised
+            keys: ``lang``, ``fields``, ``security``, ``rate``, ``output``,
+            ``ssl``, ``timeout``, ``connect_timeout``, ``user_agent``.
+        """
+        self._api_key: Optional[str] = api_key
+        self._user_agent: str = str(
+            options.pop("user_agent", f"ipwhois-python/{self.VERSION}")
+        )
+        self._timeout: int = _coerce_positive_int(options.pop("timeout", 10), 10)
+        self._connect_timeout: int = _coerce_positive_int(
+            options.pop("connect_timeout", 5), 5
+        )
+        self._ssl: bool = bool(options.pop("ssl", True))
+
+        # Anything left is a request-level default (lang, fields, ...).
+        self._defaults: Dict[str, Any] = options
+
+    # ------------------------------------------------------------------ #
+    # Public API                                                         #
+    # ------------------------------------------------------------------ #
+
+    def lookup(self, ip: Optional[str] = None, **options: Any) -> Response:
+        """Look up information for a single IP address.
+
+        Pass ``None`` (or call without arguments) to look up the caller's own
+        public IP, as documented at https://ipwhois.io/documentation.
+
+        The library never raises -- check ``result["success"]`` after every
+        call.
+
+        :param ip: IPv4 or IPv6 address. ``None`` (default) = current IP.
+        :param options: Per-call options: ``lang``, ``fields``,
+            ``security`` (bool), ``rate`` (bool), ``output``.
+        :returns: Decoded JSON response. On any error (API, network, bad
+            input) the dict contains ``success`` set to ``False`` and a
+            ``message``. The library never raises.
+        """
+        error = self._validate_options(options)
+        if error is not None:
+            return error
+
+        path = "/" + urllib.parse.quote(ip, safe="") if ip is not None else "/"
+        url = self._build_url(path, options)
+
+        result = self._request(url)
+        # Single lookup always parses to a dict in practice -- but in the
+        # unlikely case the API returns a list, normalise to an error dict
+        # so the caller's `result["success"]` check stays valid.
+        if isinstance(result, list):
+            return {
+                "success": False,
+                "message": "Unexpected list response from single lookup endpoint.",
+                "error_type": "api",
+            }
+        return result
+
+    def bulk_lookup(
+        self, ips: Iterable[str], **options: Any
+    ) -> BulkResponse:
+        """Look up information for multiple IP addresses in a single request.
+
+        Uses the GET / comma-separated form documented at
+        https://ipwhois.io/documentation/bulk -- up to 100 addresses per call.
+        Each address counts as one credit.
+
+        Available on the Business and Unlimited plans only.
+
+        Per-IP errors are returned inline with ``success`` set to ``False``
+        for the affected entry; the rest of the batch is still usable. If
+        the whole call fails, the response is a single error dict with
+        ``success`` set to ``False`` instead of a list.
+
+        :param ips: Up to 100 IPv4/IPv6 addresses (mixable).
+        :param options: Per-call options (same keys as :meth:`lookup`).
+        :returns: List of per-IP results on success; a single error dict on
+            whole-batch failure. The library never raises.
+        """
+        # Strings and bytes are iterable in Python -- without this guard,
+        # bulk_lookup("8.8.8.8") would lookup each character. Reject them
+        # explicitly with a helpful message.
+        if ips is None:
+            return {
+                "success": False,
+                "message": "Bulk lookup requires an iterable of IP addresses.",
+                "error_type": "invalid_argument",
+            }
+        if isinstance(ips, (str, bytes, bytearray)):
+            return {
+                "success": False,
+                "message": (
+                    "Bulk lookup requires an iterable of IP strings, not a "
+                    "single string. Use lookup() for a single IP."
+                ),
+                "error_type": "invalid_argument",
+            }
+
+        try:
+            ip_list = [str(ip) for ip in ips]
+        except TypeError:
+            return {
+                "success": False,
+                "message": "Bulk lookup requires an iterable of IP addresses.",
+                "error_type": "invalid_argument",
+            }
+
+        if not ip_list:
+            return {
+                "success": False,
+                "message": "Bulk lookup requires at least one IP address.",
+                "error_type": "invalid_argument",
+            }
+        if len(ip_list) > self.BULK_LIMIT:
+            return {
+                "success": False,
+                "message": (
+                    f"Bulk lookup accepts at most {self.BULK_LIMIT} IP "
+                    f"addresses per call, got {len(ip_list)}."
+                ),
+                "error_type": "invalid_argument",
+            }
+
+        error = self._validate_options(options)
+        if error is not None:
+            return error
+
+        # The API accepts addresses joined by commas -- the commas themselves
+        # must NOT be URL-encoded, otherwise the path is misinterpreted.
+        joined = ",".join(urllib.parse.quote(ip, safe="") for ip in ip_list)
+        url = self._build_url("/bulk/" + joined, options)
+
+        return self._request(url)
+
+    # -- Fluent setters ------------------------------------------------- #
+
+    def set_language(self, lang: str) -> "Client":
+        """Set the default language used when none is supplied per call.
+
+        :param lang: One of :attr:`SUPPORTED_LANGUAGES`.
+        """
+        self._defaults["lang"] = lang
+        return self
+
+    def set_fields(
+        self, fields: Union[str, Iterable[str], None]
+    ) -> "Client":
+        """Restrict every response to a fixed set of fields by default.
+
+        :param fields: An iterable of field names, e.g.
+            ``["country", "city", "flag.emoji"]``. A pre-joined comma-separated
+            string is also accepted and passed through unchanged. Pass
+            ``None`` to clear any previously-set default.
+        """
+        # Strings are iterable in Python, so list("country,city") would
+        # explode into individual characters. Keep strings as strings.
+        # `None` clears the default (consistent with "never raises": calling
+        # set_fields(None) shouldn't blow up). Anything that's not iterable
+        # at all is stringified rather than raising.
+        if fields is None:
+            self._defaults.pop("fields", None)
+        elif isinstance(fields, str):
+            self._defaults["fields"] = fields
+        else:
+            try:
+                self._defaults["fields"] = list(fields)
+            except TypeError:
+                self._defaults["fields"] = str(fields)
+        return self
+
+    def set_security(self, enabled: bool) -> "Client":
+        """Enable or disable threat-detection data on every call by default."""
+        self._defaults["security"] = bool(enabled)
+        return self
+
+    def set_rate(self, enabled: bool) -> "Client":
+        """Enable or disable the ``rate`` block in responses by default."""
+        self._defaults["rate"] = bool(enabled)
+        return self
+
+    def set_timeout(self, seconds: Any) -> "Client":
+        """Set the per-request total timeout in seconds (default: 10).
+
+        Bad values (non-numeric, negative) silently fall back to the default,
+        in keeping with the library's "never raises" contract.
+        """
+        self._timeout = _coerce_positive_int(seconds, self._timeout)
+        return self
+
+    def set_connect_timeout(self, seconds: Any) -> "Client":
+        """Set the connection timeout in seconds (default: 5).
+
+        Note: Python's :mod:`urllib` exposes a single timeout that covers
+        both the connect and read phases. This value is stored for API
+        parity with the PHP client; the effective ceiling for the whole
+        request is :meth:`set_timeout`.
+
+        Bad values (non-numeric, negative) silently fall back to the
+        previous value, in keeping with the library's "never raises"
+        contract.
+        """
+        self._connect_timeout = _coerce_positive_int(
+            seconds, self._connect_timeout
+        )
+        return self
+
+    def set_user_agent(self, user_agent: str) -> "Client":
+        """Override the User-Agent header sent with every request."""
+        self._user_agent = str(user_agent)
+        return self
+
+    # ------------------------------------------------------------------ #
+    # Internals                                                          #
+    # ------------------------------------------------------------------ #
+
+    def _validate_options(self, options: Dict[str, Any]) -> Optional[Response]:
+        """Validate per-call options.
+
+        :returns: An error dict on the first invalid option, or ``None`` if
+            everything looks OK.
+        """
+        merged = {**self._defaults, **options}
+
+        lang = merged.get("lang")
+        if lang is not None and lang not in self.SUPPORTED_LANGUAGES:
+            return {
+                "success": False,
+                "message": (
+                    f'Unsupported language "{lang}". Supported: '
+                    f"{', '.join(self.SUPPORTED_LANGUAGES)}."
+                ),
+                "error_type": "invalid_argument",
+            }
+
+        output = merged.get("output")
+        if output is not None and output not in self.SUPPORTED_OUTPUTS:
+            return {
+                "success": False,
+                "message": (
+                    f'Unsupported output format "{output}". Supported: '
+                    f"{', '.join(self.SUPPORTED_OUTPUTS)}."
+                ),
+                "error_type": "invalid_argument",
+            }
+
+        return None
+
+    def _build_url(self, path: str, options: Dict[str, Any]) -> str:
+        """Build the full URL for a given path + options."""
+        host = self.HOST_PAID if self._api_key is not None else self.HOST_FREE
+
+        # Per-call options win over defaults.
+        merged = {**self._defaults, **options}
+
+        query: List[tuple] = []
+
+        if self._api_key is not None:
+            query.append(("key", self._api_key))
+
+        if "lang" in merged and merged["lang"] is not None:
+            query.append(("lang", str(merged["lang"])))
+
+        if "output" in merged and merged["output"] is not None:
+            query.append(("output", str(merged["output"])))
+
+        if "fields" in merged and merged["fields"] is not None:
+            fields = merged["fields"]
+            if isinstance(fields, (list, tuple)):
+                fields = ",".join(str(f) for f in fields)
+            query.append(("fields", str(fields)))
+
+        if merged.get("security"):
+            query.append(("security", "1"))
+
+        if merged.get("rate"):
+            query.append(("rate", "1"))
+
+        scheme = "https" if self._ssl else "http"
+        url = f"{scheme}://{host}{path}"
+        if query:
+            url += "?" + urllib.parse.urlencode(query)
+
+        return url
+
+    def _request(self, url: str) -> Union[Response, List[Any]]:
+        """Perform a GET request and return the decoded JSON body.
+
+        On any error returns an error dict with ``success`` set to ``False``;
+        on bulk success returns the parsed JSON list directly.
+        """
+        req = urllib.request.Request(
+            url,
+            headers={
+                "Accept": "application/json",
+                "User-Agent": self._user_agent,
+            },
+            method="GET",
+        )
+
+        status: int
+        body: str
+        headers: Dict[str, str]
+
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                status = int(getattr(resp, "status", resp.getcode()))
+                headers = {k.lower(): v for k, v in resp.headers.items()}
+                raw = resp.read()
+                body = raw.decode("utf-8", errors="replace")
+        except urllib.error.HTTPError as e:
+            # 4xx / 5xx -- read the body and normalise into an error dict
+            # below, the same way a 2xx response with success=false is.
+            status = int(e.code)
+            try:
+                headers = {
+                    k.lower(): v for k, v in (e.headers or {}).items()
+                }
+            except Exception:
+                headers = {}
+            try:
+                body = e.read().decode("utf-8", errors="replace")
+            except Exception:
+                body = ""
+        except urllib.error.URLError as e:
+            return {
+                "success": False,
+                "message": f"Network error: {e.reason}",
+                "error_type": "network",
+            }
+        except socket.timeout:
+            return {
+                "success": False,
+                "message": (
+                    f"Network error: timed out after {self._timeout}s"
+                ),
+                "error_type": "network",
+            }
+        except (TimeoutError, OSError) as e:
+            return {
+                "success": False,
+                "message": f"Network error: {e}",
+                "error_type": "network",
+            }
+
+        decoded: Any = None
+        if body:
+            try:
+                decoded = json.loads(body)
+            except json.JSONDecodeError:
+                # Non-JSON output is legitimate when output=xml or output=csv
+                # was requested -- return a thin wrapper so the caller still
+                # gets the raw payload. `success: True` is added so the
+                # documented `if info["success"]` check stays valid for raw
+                # responses too.
+                if 200 <= status < 300:
+                    return {"success": True, "raw": body}
+
+                # Non-JSON 4xx/5xx -- synthesise an error dict so the caller
+                # can handle it the same way as a normal API error.
+                snippet = " ".join(body.split())
+                if len(snippet) > 200:
+                    snippet = snippet[:200] + "\u2026"
+                return {
+                    "success": False,
+                    "message": (
+                        f"HTTP {status} returned by ipwhois API: {snippet}"
+                    ),
+                    "http_status": status,
+                }
+
+        if not isinstance(decoded, (dict, list)):
+            decoded = {} if decoded is None else {"value": decoded}
+
+        # For HTTP errors, normalise into a `success: False` dict so the
+        # caller doesn't have to inspect HTTP status separately.
+        if status >= 400:
+            if isinstance(decoded, dict):
+                if decoded.get("success") is False:
+                    # The API already shaped the error correctly -- just enrich it.
+                    decoded["http_status"] = status
+                else:
+                    message = str(
+                        decoded.get(
+                            "message", f"HTTP {status} returned by ipwhois API"
+                        )
+                    )
+                    decoded = {
+                        "success": False,
+                        "message": message,
+                        "http_status": status,
+                    }
+
+                if status == 429 and "retry-after" in headers:
+                    try:
+                        decoded["retry_after"] = int(headers["retry-after"])
+                    except (TypeError, ValueError):
+                        pass
+            else:
+                # List response with error status -- wrap as an error dict.
+                decoded = {
+                    "success": False,
+                    "message": f"HTTP {status} returned by ipwhois API",
+                    "http_status": status,
+                }
+                if status == 429 and "retry-after" in headers:
+                    try:
+                        decoded["retry_after"] = int(headers["retry-after"])
+                    except (TypeError, ValueError):
+                        pass
+
+        # For HTTP 2xx with `success: false` (e.g. "Invalid IP address",
+        # "Reserved range") we just pass the body through -- it is already
+        # shaped correctly by the API.
+
+        return decoded
+
+
+def _coerce_positive_int(value: Any, default: int) -> int:
+    """Coerce ``value`` to a positive int, falling back to ``default``.
+
+    Mirrors PHP's lenient ``(int)`` cast so that a stray ``"foo"`` passed
+    via constructor kwargs or :meth:`Client.set_timeout` doesn't blow up
+    the whole client. ``None``, non-numeric strings, ``True``/``False``
+    edge cases, negative numbers and zero all map to ``default``.
+    """
+    if value is None or isinstance(value, bool):
+        return default
+    try:
+        coerced = int(value)
+    except (TypeError, ValueError):
+        return default
+    if coerced <= 0:
+        return default
+    return coerced
+

ipwhois_python-1.0.0.dist-info/METADATA

@@ -0,0 +1,370 @@
+Metadata-Version: 2.4
+Name: ipwhois-python
+Version: 1.0.0
+Summary: Official Python client for the ipwhois.io IP Geolocation API. Simple, dependency-free, supports single and bulk IP lookups.
+Project-URL: Homepage, https://ipwhois.io
+Project-URL: Documentation, https://ipwhois.io/documentation
+Project-URL: Source, https://github.com/IPWhois/ipwhois-python
+Project-URL: Issues, https://github.com/IPWhois/ipwhois-python/issues
+Author: ipwhois.io
+License: MIT License
+        
+        Copyright (c) 2026 ipwhois.io
+        
+        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.
+License-File: LICENSE
+Keywords: geoip,geolocation,ip-api,ip-geolocation,ip-locator,ip-lookup,ipwhois
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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
+
+# ipwhois-python
+
+[![PyPI Version](https://img.shields.io/pypi/v/ipwhois-python.svg)](https://pypi.org/project/ipwhois-python/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/ipwhois-python.svg)](https://pypi.org/project/ipwhois-python/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Official, dependency-free Python client for the [ipwhois.io](https://ipwhois.io) IP Geolocation API.
+
+- ✅ Single and bulk IP lookups (IPv4 and IPv6)
+- ✅ Works with both the **Free** and **Paid** plans
+- ✅ HTTPS by default
+- ✅ Localisation, field selection, threat detection, rate info
+- ✅ Never raises — all errors returned as `success: False` dicts
+- ✅ No external dependencies — only the Python standard library
+- ✅ Python 3.8+
+
+## Installation
+
+```bash
+pip install ipwhois-python
+```
+
+## Free vs Paid plan
+
+The same `Client` class is used for both plans. The only difference is whether
+you pass an API key:
+
+- **Free plan** — create the client **without arguments**. No API key, no
+  signup required. Suitable for low-traffic and non-commercial use.
+- **Paid plan** — create the client **with your API key** from
+  <https://ipwhois.io>. Higher limits, plus access to bulk lookups and
+  threat-detection data.
+
+```python
+from ipwhois import Client
+
+free = Client()                 # Free plan — no API key
+paid = Client("YOUR_API_KEY")   # Paid plan — with API key
+```
+
+Everything else (`lookup()`, options, error handling) is identical.
+
+## Quick start — Free plan (no API key)
+
+```python
+from ipwhois import Client
+
+client = Client()  # no API key
+
+info = client.lookup("8.8.8.8")
+
+print(info["country"], info["flag"]["emoji"])
+# → United States 🇺🇸
+
+print(f"{info['city']}, {info['region']}")
+# → Mountain View, California
+```
+
+## Quick start — Paid plan (with API key)
+
+Get an API key at <https://ipwhois.io> and pass it to the constructor:
+
+```python
+from ipwhois import Client
+
+client = Client("YOUR_API_KEY")  # with API key
+
+info = client.lookup("8.8.8.8")
+
+print(info["country"], info["flag"]["emoji"])
+# → United States 🇺🇸
+
+print(f"{info['city']}, {info['region']}")
+# → Mountain View, California
+```
+
+> ℹ️ Pass nothing to look up your own public IP: `client.lookup()` — works
+> on both plans.
+
+## Lookup options
+
+Every option below can be passed per call as a keyword argument, or set once
+on the client as a default.
+
+| Option       | Type    | Plans needed         | Description                                                            |
+| ------------ | ------- | -------------------- | ---------------------------------------------------------------------- |
+| `lang`       | str     | Free + Paid          | One of: `en`, `ru`, `de`, `es`, `pt-BR`, `fr`, `zh-CN`, `ja`           |
+| `fields`     | list    | Free + Paid          | Restrict the response to specific fields (e.g. `["country", "city"]`)  |
+| `output`     | str     | Free + Paid          | `json` (default), `xml`, `csv`                                         |
+| `rate`       | bool    | Basic and above      | Include the `rate` block (`limit`, `remaining`)                        |
+| `security`   | bool    | Business and above   | Include the `security` block (proxy/vpn/tor/hosting)                   |
+
+### Setting defaults once
+
+If you make many calls with the same options, set them once and forget:
+
+```python
+# Free plan
+client = (
+    Client()
+    .set_language("en")
+    .set_fields(["country", "city", "flag.emoji"])
+    .set_timeout(8)
+)
+
+client.lookup("8.8.8.8")                  # uses all of the above
+client.lookup("1.1.1.1", lang="de")       # per-call options override defaults
+```
+
+```python
+# Paid plan
+client = (
+    Client("YOUR_API_KEY")
+    .set_language("en")
+    .set_fields(["country", "city", "flag.emoji"])
+    .set_timeout(8)
+)
+
+client.lookup("8.8.8.8")                  # uses all of the above
+client.lookup("1.1.1.1", lang="de")       # per-call options override defaults
+```
+
+> ℹ️ Paid plans additionally support `set_security(True)` (Business+) and
+> `set_rate(True)` (Basic+). See the table above for what's available where.
+
+## HTTPS encryption
+
+By default, all requests are sent over HTTPS. If you need to disable it (for
+example, in environments without an up-to-date CA bundle), pass `ssl=False`
+to the constructor:
+
+```python
+from ipwhois import Client
+
+# Free plan
+client = Client(ssl=False)
+```
+
+```python
+from ipwhois import Client
+
+# Paid plan
+client = Client("YOUR_API_KEY", ssl=False)
+```
+
+> ℹ️ HTTPS is strongly recommended for production traffic — your API key is
+> sent in the query string and would otherwise travel in clear text.
+
+## Bulk lookup (Paid plan only)
+
+The bulk endpoint sends **up to 100 IPs** in a single GET request. Each
+address counts as one credit. Available on the **Business** and **Unlimited**
+plans.
+
+```python
+from ipwhois import Client
+
+client = Client("YOUR_API_KEY")
+
+results = client.bulk_lookup([
+    "8.8.8.8",
+    "1.1.1.1",
+    "208.67.222.222",
+    "2c0f:fb50:4003::",     # IPv6 is fine — mix freely
+])
+
+for row in results:
+    if row.get("success") is False:
+        # Per-IP errors (e.g. "Invalid IP address") are returned inline,
+        # they do NOT raise — the rest of the batch is still usable.
+        print(f"skip {row['ip']}: {row['message']}")
+        continue
+    print(f"{row['ip']} → {row['country']}")
+```
+
+> ℹ️ Bulk requires an API key. Calling `bulk_lookup()` without one will fail
+> at the API level.
+
+## Error handling
+
+**The library never raises.** Every failure — invalid IP, bad API key, rate
+limit, network outage, bad options — comes back inside the response dict
+with `success` set to `False` and a `message`. Just check
+`info["success"]` after every call:
+
+```python
+info = client.lookup("8.8.8.8")
+
+if not info["success"]:
+    print(f"Lookup failed: {info['message']}")
+    return
+
+print(info["country"])
+```
+
+This means an outage of the ipwhois.io API (or of your machine's DNS,
+connection, etc.) will never surface as an unhandled exception in your
+application — you decide how to react.
+
+### Error response fields
+
+Every error response contains `success: False` and a `message`. Some errors
+include extra fields you can branch on:
+
+| Field          | When it's present                                                            |
+| -------------- | ---------------------------------------------------------------------------- |
+| `error_type`   | `'network'` or `'invalid_argument'` — for non-API errors                     |
+| `http_status`  | On HTTP 4xx / 5xx responses                                                  |
+| `retry_after`  | On HTTP 429 if the API sent a `Retry-After` header                           |
+
+```python
+import time
+
+info = client.lookup("8.8.8.8")
+
+if not info["success"]:
+    if info.get("http_status") == 429:
+        time.sleep(info.get("retry_after", 60))
+        # ...retry
+
+    if info.get("error_type") == "network":
+        # DNS failure, connection refused, timeout, ...
+        pass
+
+    print(f"Error: {info['message']}")
+```
+
+## Response shape
+
+A successful response includes (depending on your plan and selected options):
+
+```jsonc
+{
+    "ip": "8.8.4.4",
+    "success": true,
+    "type": "IPv4",
+    "continent": "North America",
+    "continent_code": "NA",
+    "country": "United States",
+    "country_code": "US",
+    "region": "California",
+    "region_code": "CA",
+    "city": "Mountain View",
+    "latitude": 37.3860517,
+    "longitude": -122.0838511,
+    "is_eu": false,
+    "postal": "94039",
+    "calling_code": "1",
+    "capital": "Washington D.C.",
+    "borders": "CA,MX",
+    "flag": {
+        "img": "https://cdn.ipwhois.io/flags/us.svg",
+        "emoji": "🇺🇸",
+        "emoji_unicode": "U+1F1FA U+1F1F8"
+    },
+    "connection": {
+        "asn": 15169,
+        "org": "Google LLC",
+        "isp": "Google LLC",
+        "domain": "google.com"
+    },
+    "timezone": {
+        "id": "America/Los_Angeles",
+        "abbr": "PDT",
+        "is_dst": true,
+        "offset": -25200,
+        "utc": "-07:00",
+        "current_time": "2026-05-08T14:31:48-07:00"
+    },
+    "currency": {
+        "name": "US Dollar",
+        "code": "USD",
+        "symbol": "$",
+        "plural": "US dollars",
+        "exchange_rate": 1
+    },
+    "security": {
+        "anonymous": false,
+        "proxy": false,
+        "vpn": false,
+        "tor": false,
+        "hosting": false
+    },
+    "rate": {
+        "limit": 250000,
+        "remaining": 50155
+    }
+}
+```
+
+For the full field reference, see the [official documentation](https://ipwhois.io/documentation).
+
+An **error** response looks like:
+
+```jsonc
+{
+    "success": false,
+    "message": "Invalid IP address",
+    "http_status": 400          // present for HTTP 4xx / 5xx
+    // "retry_after": 60        // additionally present on HTTP 429 if the API sent a Retry-After header
+    // "error_type": "network"  // present for non-API errors: 'network', 'invalid_argument'
+}
+```
+
+## Requirements
+
+- Python **3.8** or newer
+- No third-party dependencies — only the standard library (`urllib`, `json`)
+
+## Contributing
+
+Issues and pull requests are welcome on
+[GitHub](https://github.com/IPWhois/ipwhois-python).
+
+## License
+
+[MIT](LICENSE) © ipwhois.io

ipwhois_python-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+ipwhois/__init__.py,sha256=ZkvjwG4qYOnZ8djE9hALcn9T5Dha9Xtd492MiI44ljg,334
+ipwhois/client.py,sha256=BZlW_5IWmouW56sb2P92k-3hvBRxkuyCGO3XiDX7RZ4,19817
+ipwhois/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ipwhois_python-1.0.0.dist-info/METADATA,sha256=g4FYt16U69-cbb6KJSUrW6F0YOFHWDKUb7-u-tF9Xcc,11950
+ipwhois_python-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ipwhois_python-1.0.0.dist-info/licenses/LICENSE,sha256=zgvmP294VITHu3lcEF0NYGFlRwktZ1Z9NaIC-88Jj-Q,1067
+ipwhois_python-1.0.0.dist-info/RECORD,,

ipwhois_python-1.0.0.dist-info/WHEEL

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

ipwhois_python-1.0.0.dist-info/licenses/LICENSE

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