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

ipwhois_python-1.0.2/CHANGELOG.md

@@ -0,0 +1,85 @@
+# 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.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.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipwhois-python
-Version: 1.0.1
+Version: 1.0.2
 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,40 @@ 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
-# Free plan
+# Pass "YOUR_API_KEY" to the constructor for the paid plan; otherwise omit it.
 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
+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
 ```
 
-```python
-# Paid plan
-ipwhois = (
-    IPWhois("YOUR_API_KEY")
-    .set_language("en")
-    .set_fields(["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
-```
+> ⚠️ 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.
 
-> ℹ️ Paid plans additionally support `set_security(True)` (Business+) and
-> `set_rate(True)` (Basic+). See the table above for what's available where.
+> ℹ️ `set_security(True)` requires Business+ and `set_rate(True)` requires
+> Basic+. See the table above for what's available where.
 
 ## HTTPS encryption
 

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

@@ -86,42 +86,40 @@ 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
-# Free plan
+# Pass "YOUR_API_KEY" to the constructor for the paid plan; otherwise omit it.
 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
+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
 ```
 
-```python
-# Paid plan
-ipwhois = (
-    IPWhois("YOUR_API_KEY")
-    .set_language("en")
-    .set_fields(["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
-```
+> ⚠️ 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.
 
-> ℹ️ Paid plans additionally support `set_security(True)` (Business+) and
-> `set_rate(True)` (Basic+). See the table above for what's available where.
+> ℹ️ `set_security(True)` requires Business+ and `set_rate(True)` requires
+> Basic+. See the table above for what's available where.
 
 ## HTTPS encryption
 

{ipwhois_python-1.0.1 → ipwhois_python-1.0.2}/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.0.2}/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.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ipwhois-python"
-version = "1.0.1"
+version = "1.0.2"
 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.0.2}/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.0.2"
 
     #: 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,23 +419,19 @@ 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,
                 }

{ipwhois_python-1.0.1 → ipwhois_python-1.0.2}/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"})
+
+    assert "output=" not in url
+    # Other options next to it still work.
+    assert "lang=en" in url
 
-    # 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
+
+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,10 @@ 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", output="xml")
+        result = IPWhois().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 "Invalid JSON" in result.get("message", "")
+    assert result.get("http_status") == 200

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.