ipwhois-python 1.0.2__tar.gz → 1.2.0__tar.gz

{ipwhois_python-1.0.2 → ipwhois_python-1.2.0}/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to `ipwhois-python` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-05-10
+
+### Added
+
+- Every error response now carries an `error_type` field, including errors
+  returned by the API. The new value `'api'` joins the existing `'network'`
+  and `'invalid_argument'` codes, so callers can branch on the category of
+  any failure with a single `info["error_type"]` check — no need to combine
+  `success` with `http_status` to distinguish API vs. non-API errors.
+  Applies to HTTP 4xx / 5xx responses, malformed JSON bodies, and HTTP 2xx
+  responses where the API itself sets `success: false` (e.g. "Invalid IP
+  address", "Reserved range").
+
+### Changed
+
+- `retry_after` is now only attached to HTTP 429 responses on the **free
+  plan** (`ipwho.is`). The paid endpoint (`ipwhois.pro`) does not send a
+  `Retry-After` header, so reading it on paid plans is now skipped and the
+  field will not appear there. Behaviour on the free plan is unchanged.
+- README "Setting defaults once" section now shows the Free and Paid plans
+  as two separate code blocks, matching the layout used in "Quick start"
+  and "HTTPS encryption". The setters work identically on both plans, so
+  the lookup-override snippet is shared underneath.
+- README "Error response fields" table now lists `message` explicitly (it
+  has always been present on every error response) and the `error_type`
+  row covers the new `'api'` value as well.
+- The `_request()` HTTP-error code path was lightly refactored so the
+  `Retry-After` header is parsed in one place instead of two (one for the
+  dict branch and one for the list branch). No behaviour change beyond the
+  free-plan gating noted above.
+
 ## [1.0.2] - 2026-05-10
 
 ### Removed

{ipwhois_python-1.0.2 → ipwhois_python-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipwhois-python
-Version: 1.0.2
+Version: 1.2.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
@@ -154,14 +154,33 @@ Defaults are set with fluent setters — `set_language()`, `set_fields()`,
 `set_user_agent()` — and can be chained:
 
 ```python
-# Pass "YOUR_API_KEY" to the constructor for the paid plan; otherwise omit it.
+from ipwhois import IPWhois
+
+# Free plan
 ipwhois = (
     IPWhois()
     .set_language("en")
     .set_fields(["success", "country", "city", "flag.emoji"])
     .set_timeout(8)
 )
+```
 
+```python
+from ipwhois import IPWhois
+
+# Paid plan
+ipwhois = (
+    IPWhois("YOUR_API_KEY")
+    .set_language("en")
+    .set_fields(["success", "country", "city", "flag.emoji"])
+    .set_timeout(8)
+)
+```
+
+Either client behaves the same way at call time — per-call options always
+win over the defaults:
+
+```python
 ipwhois.lookup("8.8.8.8")              # uses lang=en, the field whitelist, and timeout=8
 ipwhois.lookup("1.1.1.1", lang="de")   # overrides lang for this single call only
 ```
@@ -250,14 +269,16 @@ 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:
+Every error response contains `success: False`, a human-readable `message`,
+and an `error_type` so you can branch on the category of the failure. 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                           |
+| Field          | When it's present                                                                            |
+| -------------- | -------------------------------------------------------------------------------------------- |
+| `message`      | Always — human-readable description of what went wrong                                       |
+| `error_type`   | Always — one of `'api'`, `'network'`, or `'invalid_argument'`                                |
+| `http_status`  | On HTTP 4xx / 5xx responses                                                                  |
+| `retry_after`  | On HTTP 429 — **free plan only** (the paid endpoint does not send a `Retry-After` header)    |
 
 ```python
 import time
@@ -347,9 +368,9 @@ An **error** response looks like:
 {
     "success": false,
     "message": "Invalid IP address",
+    "error_type": "api",        // 'api' / 'network' / 'invalid_argument'
     "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'
+    // "retry_after": 60        // additionally present on HTTP 429 — free plan only
 }
 ```
 

{ipwhois_python-1.0.2 → ipwhois_python-1.2.0}/README.md

@@ -101,14 +101,33 @@ Defaults are set with fluent setters — `set_language()`, `set_fields()`,
 `set_user_agent()` — and can be chained:
 
 ```python
-# Pass "YOUR_API_KEY" to the constructor for the paid plan; otherwise omit it.
+from ipwhois import IPWhois
+
+# Free plan
 ipwhois = (
     IPWhois()
     .set_language("en")
     .set_fields(["success", "country", "city", "flag.emoji"])
     .set_timeout(8)
 )
+```
 
+```python
+from ipwhois import IPWhois
+
+# Paid plan
+ipwhois = (
+    IPWhois("YOUR_API_KEY")
+    .set_language("en")
+    .set_fields(["success", "country", "city", "flag.emoji"])
+    .set_timeout(8)
+)
+```
+
+Either client behaves the same way at call time — per-call options always
+win over the defaults:
+
+```python
 ipwhois.lookup("8.8.8.8")              # uses lang=en, the field whitelist, and timeout=8
 ipwhois.lookup("1.1.1.1", lang="de")   # overrides lang for this single call only
 ```
@@ -197,14 +216,16 @@ 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:
+Every error response contains `success: False`, a human-readable `message`,
+and an `error_type` so you can branch on the category of the failure. 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                           |
+| Field          | When it's present                                                                            |
+| -------------- | -------------------------------------------------------------------------------------------- |
+| `message`      | Always — human-readable description of what went wrong                                       |
+| `error_type`   | Always — one of `'api'`, `'network'`, or `'invalid_argument'`                                |
+| `http_status`  | On HTTP 4xx / 5xx responses                                                                  |
+| `retry_after`  | On HTTP 429 — **free plan only** (the paid endpoint does not send a `Retry-After` header)    |
 
 ```python
 import time
@@ -294,9 +315,9 @@ An **error** response looks like:
 {
     "success": false,
     "message": "Invalid IP address",
+    "error_type": "api",        // 'api' / 'network' / 'invalid_argument'
     "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'
+    // "retry_after": 60        // additionally present on HTTP 429 — free plan only
 }
 ```
 

{ipwhois_python-1.0.2 → ipwhois_python-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ipwhois-python"
-version = "1.0.2"
+version = "1.2.0"
 description = "Official Python client for the ipwhois.io IP Geolocation API. Simple, dependency-free, supports single and bulk IP lookups."
 readme = "README.md"
 license = { file = "LICENSE" }

{ipwhois_python-1.0.2 → ipwhois_python-1.2.0}/src/ipwhois/ipwhois.py

@@ -55,7 +55,7 @@ class IPWhois:
     """
 
     #: Library version, used in the default User-Agent header.
-    VERSION: str = "1.0.2"
+    VERSION: str = "1.2.0"
 
     #: Free-plan endpoint host (used when no API key is provided).
     HOST_FREE: str = "ipwho.is"
@@ -434,6 +434,7 @@ class IPWhois:
                         f"(HTTP {status}): {snippet}"
                     ),
                     "http_status": status,
+                    "error_type": "api",
                 }
 
         if not isinstance(decoded, (dict, list)):
@@ -457,12 +458,6 @@ class IPWhois:
                         "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 = {
@@ -470,11 +465,32 @@ class IPWhois:
                     "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
+
+            # `Retry-After` is only emitted by the free-plan endpoint
+            # (ipwho.is); the paid endpoint (ipwhois.pro) does not send the
+            # header, so don't try to read it there.
+            if (
+                status == 429
+                and self._api_key is None
+                and "retry-after" in headers
+            ):
+                try:
+                    decoded["retry_after"] = int(headers["retry-after"])
+                except (TypeError, ValueError):
+                    pass
+
+        # Tag every API-shaped error (`success: False` returned by the API,
+        # on any HTTP status) with `error_type: 'api'` so callers can branch
+        # on the category alongside the non-API codes ('network',
+        # 'environment', 'invalid_argument'). HTTP 2xx + success=false bodies
+        # (e.g. "Invalid IP address", "Reserved range") are otherwise passed
+        # through untouched.
+        if (
+            isinstance(decoded, dict)
+            and decoded.get("success") is False
+            and "error_type" not in decoded
+        ):
+            decoded["error_type"] = "api"
 
         # For HTTP 2xx with `success: false` (e.g. "Invalid IP address",
         # "Reserved range") we just pass the body through -- it is already

{ipwhois_python-1.0.2 → ipwhois_python-1.2.0}/tests/test_ipwhois.py

@@ -328,3 +328,120 @@ def test_non_json_response_is_treated_as_error() -> None:
     assert result["success"] is False
     assert "Invalid JSON" in result.get("message", "")
     assert result.get("http_status") == 200
+    assert result.get("error_type") == "api"
+
+
+# --------------------------------------------------------------------- #
+# Response shaping -- the urllib layer is stubbed via mock.patch so      #
+# the suite can exercise error tagging without making real HTTP calls.  #
+# --------------------------------------------------------------------- #
+
+
+class _FakeOkResp:
+    """Minimal stand-in for a urllib response context manager (HTTP 2xx)."""
+
+    def __init__(self, status: int, body: bytes, headers: dict) -> None:
+        self.status = status
+        self._body = body
+        self.headers = headers
+
+    def __enter__(self) -> "_FakeOkResp":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        return None
+
+    def read(self) -> bytes:
+        return self._body
+
+    def getcode(self) -> int:
+        return self.status
+
+
+def _fake_http_error(status: int, body: bytes, headers: dict):
+    """Build a urllib.error.HTTPError for status >= 400.
+
+    The 4xx / 5xx code path inside ``_request`` is reached via this
+    exception, not via the success branch, so tests that target it have
+    to make ``urlopen`` raise.
+    """
+    import io
+    import urllib.error
+
+    return urllib.error.HTTPError(
+        url="https://example.test",
+        code=status,
+        msg="error",
+        hdrs=headers,  # type: ignore[arg-type]
+        fp=io.BytesIO(body),
+    )
+
+
+def test_2xx_with_success_false_is_tagged_as_api_error() -> None:
+    # The API returns 200 with `success: False` for things like
+    # "Reserved range" or "Invalid IP address" -- these should be passed
+    # through without `http_status` (which is reserved for 4xx/5xx),
+    # but tagged with `error_type: 'api'` so callers can branch on the
+    # category the same way they branch on 'network' / 'environment' /
+    # 'invalid_argument'.
+    from unittest.mock import patch
+
+    body = (
+        b'{"success": false, "message": "Reserved range", "ip": "127.0.0.1"}'
+    )
+    fake = _FakeOkResp(200, body, headers={})
+    with patch("urllib.request.urlopen", return_value=fake):
+        result = IPWhois().lookup("127.0.0.1")
+
+    assert result["success"] is False
+    assert result.get("message") == "Reserved range"
+    assert result.get("ip") == "127.0.0.1"
+    assert "http_status" not in result
+    assert result.get("error_type") == "api"
+
+
+def test_4xx_response_is_normalised_with_error_type_api() -> None:
+    from unittest.mock import patch
+
+    body = b'{"success": false, "message": "Invalid API key"}'
+    err = _fake_http_error(401, body, headers={})
+    with patch("urllib.request.urlopen", side_effect=err):
+        result = IPWhois("BAD").lookup("8.8.8.8")
+
+    assert result["success"] is False
+    assert result.get("http_status") == 401
+    assert result.get("message") == "Invalid API key"
+    assert result.get("error_type") == "api"
+
+
+def test_429_on_free_plan_attaches_retry_after() -> None:
+    # The free-plan endpoint (ipwho.is) sends `Retry-After` on rate-limit
+    # responses; the client surfaces it as `retry_after`.
+    from unittest.mock import patch
+
+    body = b'{"success": false, "message": "Rate limited"}'
+    err = _fake_http_error(429, body, headers={"retry-after": "42"})
+    with patch("urllib.request.urlopen", side_effect=err):
+        result = IPWhois().lookup("8.8.8.8")  # free plan -- no API key
+
+    assert result["success"] is False
+    assert result.get("http_status") == 429
+    assert result.get("retry_after") == 42
+    assert result.get("error_type") == "api"
+
+
+def test_429_on_paid_plan_does_not_attach_retry_after() -> None:
+    # The paid endpoint (ipwhois.pro) does not send `Retry-After`. Even
+    # if a header is present (proxies, test stubs, ...), the client
+    # ignores it on paid plans so `retry_after` will not appear.
+    from unittest.mock import patch
+
+    body = b'{"success": false, "message": "Rate limited"}'
+    err = _fake_http_error(429, body, headers={"retry-after": "42"})
+    with patch("urllib.request.urlopen", side_effect=err):
+        result = IPWhois("KEY").lookup("8.8.8.8")  # paid plan
+
+    assert result["success"] is False
+    assert result.get("http_status") == 429
+    assert "retry_after" not in result
+    assert result.get("error_type") == "api"