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

ipwhois_python-1.2.0/CHANGELOG.md

@@ -0,0 +1,116 @@
+# Changelog
+
+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
+
+- **The `output` option has been removed.** The library only ever processed
+  JSON responses meaningfully, so `output="xml"` and `output="csv"` were a
+  thin pass-through that returned the raw payload as a string. The option
+  has been dropped from `lookup()`, `bulk_lookup()`, and the constructor's
+  keyword arguments; the `IPWhois.SUPPORTED_OUTPUTS` constant is gone.
+  Passing `output=...` will silently no-op.
+- The 2xx + non-JSON `{"success": True, "raw": ...}` fallback in the
+  response handler (which only existed to support the removed `output`
+  parameter) is gone. The API always returns JSON, so any non-JSON 2xx
+  body is now treated as a transport error and returned as a
+  `success: False` dict.
+
+### Changed
+
+- `set_fields()` docstring now mentions that `"success"` should be included
+  in the field whitelist if you rely on `info["success"]` for error
+  checking — when `fields` is set, the API only returns the fields you list.
+- README "Setting defaults once" section rewritten for clarity: the two
+  ways of passing options (per call vs. as defaults), the available
+  setters, and the `success`-in-`fields` gotcha are now spelled out
+  explicitly. The free/paid example pair was collapsed into a single
+  example, since the setters work identically on both plans.
+- All examples that filter fields (`README.md`, `examples/basic.py`,
+  `examples/defaults.py`) now include `"success"` in the field list.
+
+### Migration
+
+If your code passes `output="json"` you can simply remove it — the library
+always returns the decoded JSON anyway. If you were relying on
+`output="xml"` or `output="csv"` to get the raw payload, that use case is
+no longer supported; call the API directly with `urllib` for those formats.
+
+```python
+# Before (1.0.1):
+info = ipwhois.lookup("8.8.8.8", output="json", fields=["country", "city"])
+
+# After (1.0.2):
+info = ipwhois.lookup("8.8.8.8", fields=["success", "country", "city"])
+```
+
+## [1.0.1] - 2026-05-09
+
+### Changed
+
+- **Renamed the main class `Client` to `IPWhois`** for consistency with the
+  package and brand. The recommended import is now
+  `from ipwhois import IPWhois`. The source module moved from
+  `src/ipwhois/client.py` to `src/ipwhois/ipwhois.py`, and the test module
+  from `tests/test_client.py` to `tests/test_ipwhois.py`. Public behaviour,
+  method signatures, constructor arguments, and return shapes are all
+  unchanged.
+
+### Migration
+
+```python
+# Before (1.0.0):
+from ipwhois import Client
+client = Client("YOUR_API_KEY")
+info   = client.lookup("8.8.8.8")
+
+# After (1.0.1+):
+from ipwhois import IPWhois
+ipwhois = IPWhois("YOUR_API_KEY")
+info    = ipwhois.lookup("8.8.8.8")
+```
+
+The variable name (`client`, `ipwhois`, anything else) is up to you; only
+the class identifier changed.
+
+## [1.0.0] - 2026-05-08
+
+### Added
+
+- Initial release. 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipwhois-python
-Version: 1.0.1
+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
@@ -139,42 +139,59 @@ on the client as a default.
 | ------------ | ------- | -------------------- | ---------------------------------------------------------------------- |
 | `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:
+Every option can be passed two ways: **per call** (as a keyword argument to
+`lookup()` / `bulk_lookup()`) or **once as a default** on the client. Per-call
+options always override the defaults, so it's safe to set sensible defaults
+and only override what differs for a specific call.
+
+Defaults are set with fluent setters — `set_language()`, `set_fields()`,
+`set_security()`, `set_rate()`, `set_timeout()`, `set_connect_timeout()`,
+`set_user_agent()` — and can be chained:
 
 ```python
+from ipwhois import IPWhois
+
 # Free plan
 ipwhois = (
     IPWhois()
     .set_language("en")
-    .set_fields(["country", "city", "flag.emoji"])
+    .set_fields(["success", "country", "city", "flag.emoji"])
     .set_timeout(8)
 )
-
-ipwhois.lookup("8.8.8.8")                  # uses all of the above
-ipwhois.lookup("1.1.1.1", lang="de")       # per-call options override defaults
 ```
 
 ```python
+from ipwhois import IPWhois
+
 # Paid plan
 ipwhois = (
     IPWhois("YOUR_API_KEY")
     .set_language("en")
-    .set_fields(["country", "city", "flag.emoji"])
+    .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:
 
-ipwhois.lookup("8.8.8.8")                  # uses all of the above
-ipwhois.lookup("1.1.1.1", lang="de")       # per-call options override 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
 ```
 
-> ℹ️ Paid plans additionally support `set_security(True)` (Business+) and
-> `set_rate(True)` (Basic+). See the table above for what's available where.
+> ⚠️ When you restrict fields with `set_fields()` (or the per-call `fields=`
+> keyword), the API only returns the fields you ask for. Always include
+> `"success"` in the list if you rely on `info["success"]` for error
+> checking — otherwise the field will be missing on responses.
+
+> ℹ️ `set_security(True)` requires Business+ and `set_rate(True)` requires
+> Basic+. See the table above for what's available where.
 
 ## HTTPS encryption
 
@@ -252,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
@@ -349,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.1 → ipwhois_python-1.2.0}/README.md

@@ -86,42 +86,59 @@ on the client as a default.
 | ------------ | ------- | -------------------- | ---------------------------------------------------------------------- |
 | `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:
+Every option can be passed two ways: **per call** (as a keyword argument to
+`lookup()` / `bulk_lookup()`) or **once as a default** on the client. Per-call
+options always override the defaults, so it's safe to set sensible defaults
+and only override what differs for a specific call.
+
+Defaults are set with fluent setters — `set_language()`, `set_fields()`,
+`set_security()`, `set_rate()`, `set_timeout()`, `set_connect_timeout()`,
+`set_user_agent()` — and can be chained:
 
 ```python
+from ipwhois import IPWhois
+
 # Free plan
 ipwhois = (
     IPWhois()
     .set_language("en")
-    .set_fields(["country", "city", "flag.emoji"])
+    .set_fields(["success", "country", "city", "flag.emoji"])
     .set_timeout(8)
 )
-
-ipwhois.lookup("8.8.8.8")                  # uses all of the above
-ipwhois.lookup("1.1.1.1", lang="de")       # per-call options override defaults
 ```
 
 ```python
+from ipwhois import IPWhois
+
 # Paid plan
 ipwhois = (
     IPWhois("YOUR_API_KEY")
     .set_language("en")
-    .set_fields(["country", "city", "flag.emoji"])
+    .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:
 
-ipwhois.lookup("8.8.8.8")                  # uses all of the above
-ipwhois.lookup("1.1.1.1", lang="de")       # per-call options override 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
 ```
 
-> ℹ️ Paid plans additionally support `set_security(True)` (Business+) and
-> `set_rate(True)` (Basic+). See the table above for what's available where.
+> ⚠️ When you restrict fields with `set_fields()` (or the per-call `fields=`
+> keyword), the API only returns the fields you ask for. Always include
+> `"success"` in the list if you rely on `info["success"]` for error
+> checking — otherwise the field will be missing on responses.
+
+> ℹ️ `set_security(True)` requires Business+ and `set_rate(True)` requires
+> Basic+. See the table above for what's available where.
 
 ## HTTPS encryption
 
@@ -199,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
@@ -296,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.1 → ipwhois_python-1.2.0}/examples/basic.py

@@ -46,7 +46,7 @@ paid = IPWhois("YOUR_API_KEY")
 info = paid.lookup(
     "1.1.1.1",
     lang="en",                                          # localised country/city/...
-    fields=["country", "city", "connection.isp", "flag.emoji"],
+    fields=["success", "country", "city", "connection.isp", "flag.emoji"],
     security=True,                                      # include proxy/vpn/tor flags
     rate=True,                                          # include rate-limit info
 )

{ipwhois_python-1.0.1 → ipwhois_python-1.2.0}/examples/defaults.py

@@ -14,7 +14,7 @@ from ipwhois import IPWhois
 ipwhois = (
     IPWhois("YOUR_API_KEY")
     .set_language("en")
-    .set_fields(["country", "city", "flag.emoji", "connection.isp"])
+    .set_fields(["success", "country", "city", "flag.emoji", "connection.isp"])
     .set_security(True)
     .set_timeout(8)
 )

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ipwhois-python"
-version = "1.0.1"
+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.1 → 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.1"
+    VERSION: str = "1.2.0"
 
     #: Free-plan endpoint host (used when no API key is provided).
     HOST_FREE: str = "ipwho.is"
@@ -78,16 +78,13 @@ class IPWhois:
         "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``.
+            keys: ``lang``, ``fields``, ``security``, ``rate``, ``ssl``,
+            ``timeout``, ``connect_timeout``, ``user_agent``.
         """
         self._api_key: Optional[str] = api_key
         self._user_agent: str = str(
@@ -117,7 +114,7 @@ class IPWhois:
 
         :param ip: IPv4 or IPv6 address. ``None`` (default) = current IP.
         :param options: Per-call options: ``lang``, ``fields``,
-            ``security`` (bool), ``rate`` (bool), ``output``.
+            ``security`` (bool), ``rate`` (bool).
         :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.
@@ -232,10 +229,14 @@ class IPWhois:
     ) -> "IPWhois":
         """Restrict every response to a fixed set of fields by default.
 
+        Include ``"success"`` in the list if you rely on ``info["success"]``
+        for error checking -- when ``fields`` is set, the API only returns
+        the fields you ask for.
+
         :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.
+            ``["success", "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.
@@ -317,17 +318,6 @@ class IPWhois:
                 "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:
@@ -345,9 +335,6 @@ class IPWhois:
         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)):
@@ -432,25 +419,22 @@ class IPWhois:
             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.
+                # The ipwhois API always returns JSON. A non-JSON body means
+                # something went wrong upstream (gateway error page, captive
+                # portal, hijacked response, ...) -- 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}"
+                        f"Invalid JSON returned by ipwhois API "
+                        f"(HTTP {status}): {snippet}"
                     ),
                     "http_status": status,
+                    "error_type": "api",
                 }
 
         if not isinstance(decoded, (dict, list)):
@@ -474,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 = {
@@ -487,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.1 → ipwhois_python-1.2.0}/tests/test_ipwhois.py

@@ -91,14 +91,6 @@ def test_invalid_language_returns_error_dict() -> None:
     assert "klingon" in result.get("message", "")
 
 
-def test_invalid_output_returns_error_dict() -> None:
-    result = IPWhois().lookup("8.8.8.8", output="yaml")
-
-    assert result["success"] is False
-    assert result.get("error_type") == "invalid_argument"
-    assert "yaml" in result.get("message", "")
-
-
 def test_bulk_lookup_refuses_empty_list() -> None:
     result = IPWhois("K").bulk_lookup([])
 
@@ -290,16 +282,24 @@ def test_constructor_tolerates_bad_timeout() -> None:
     assert ipwhois._connect_timeout == 5
 
 
-def test_raw_response_includes_success_true() -> None:
-    # When the API returns non-JSON (output=xml/csv), the wrapper response
-    # must include `success: True` so the documented `if info["success"]`
-    # check from the README still works.
-    ipwhois = IPWhois()
+def test_output_option_is_silently_dropped() -> None:
+    # The `output` parameter was removed in 1.0.2. Passing it must NOT raise
+    # or trip validation -- it's just ignored, and the resulting URL must
+    # not contain an `output=...` query string.
+    ipwhois = IPWhois("K")
+    url = ipwhois._build_url("/8.8.8.8", {"output": "xml", "lang": "en"})
 
-    # Simulate the parsing branch by calling the JSON-decode path with
-    # non-JSON input via a tiny direct test of the internal helper:
-    # we patch _request to bypass the network and feed an XML body.
-    import io
+    assert "output=" not in url
+    # Other options next to it still work.
+    assert "lang=en" in url
+
+
+def test_non_json_response_is_treated_as_error() -> None:
+    # The API always returns JSON. A non-JSON 2xx body now indicates a
+    # transport problem (gateway error page, captive portal, ...) rather
+    # than legitimate XML/CSV output -- the `output` parameter was
+    # removed in 1.0.2. Expect a `success: False` error dict instead of
+    # the old `{"success": True, "raw": ...}` wrapper.
     from unittest.mock import patch
 
     class _FakeResp:
@@ -321,9 +321,127 @@ def test_raw_response_includes_success_true() -> None:
         def getcode(self) -> int:
             return 200
 
-    fake = _FakeResp(b"<xml><ip>8.8.8.8</ip></xml>")
+    fake = _FakeResp(b"<html>captive portal</html>")
+    with patch("urllib.request.urlopen", return_value=fake):
+        result = IPWhois().lookup("8.8.8.8")
+
+    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("8.8.8.8", output="xml")
+        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 True
-    assert result["raw"] == "<xml><ip>8.8.8.8</ip></xml>"
+    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"

ipwhois_python-1.0.1/CHANGELOG.md

@@ -1,41 +0,0 @@
-# Changelog
-
-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.0.1] - 2026-05-09
-
-### Changed
-
-- **Renamed the main class `Client` to `IPWhois`** for consistency with the
-  package and brand. The recommended import is now
-  `from ipwhois import IPWhois`. The source module moved from
-  `src/ipwhois/client.py` to `src/ipwhois/ipwhois.py`, and the test module
-  from `tests/test_client.py` to `tests/test_ipwhois.py`. Public behaviour,
-  method signatures, constructor arguments, and return shapes are all
-  unchanged.
-
-### Migration
-
-```python
-# Before (1.0.0):
-from ipwhois import Client
-client = Client("YOUR_API_KEY")
-info   = client.lookup("8.8.8.8")
-
-# After (1.0.1+):
-from ipwhois import IPWhois
-ipwhois = IPWhois("YOUR_API_KEY")
-info    = ipwhois.lookup("8.8.8.8")
-```
-
-The variable name (`client`, `ipwhois`, anything else) is up to you; only
-the class identifier changed.
-
-## [1.0.0] - 2026-05-08
-
-### Added
-
-- Initial release.