Rename LookupError to IpregistryLookupError with backward-compatible alias

Author: laurentpellegrino

CHANGELOG.md

@@ -15,6 +15,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `retry_on_server_error` and `retry_on_too_many_requests` (honoring the `Retry-After` header).
   Transient network errors are now retried too.
 - Add a typed `ErrorCode` enum exposed as `ApiError.error_code`.
+- Add `IpregistryLookupError` as the primary name for per-entry batch lookup errors; the previous
+  `LookupError` name, which shadows the Python builtin, remains available as an alias.
+- Ship a `py.typed` marker so type checkers use the library's annotations.
 - Add automatic splitting of batch lookups larger than the API limit of 1024 items into concurrent
   chunks, tunable with the `max_batch_size` and `batch_concurrency` client options.
 - Add `close()` and context manager support to `IpregistryClient`, plus an optional `session`
@@ -24,6 +27,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   a weekly scheduled workflow running tests against the live API.
 ### Changed
 - Require Python 3.10+.
+- Migrate the project metadata to the standard PEP 621 format.
 - Update all dependencies to their latest versions and remove the dependency on tenacity.
 - Reuse pooled HTTP connections through a `requests.Session` instead of opening a new connection
   per request.
@@ -91,12 +95,13 @@ https://github.com/ipregistry/ipregistry-python#caching
 ## [1.0.0] - 2019-07-28
 - First public release.
 
-[Unreleased]: https://github.com/ipregistry/ipregistry-javascript/compare/4.0.0...HEAD
-[4.0.0]: https://github.com/ipregistry/ipregistry-javascript/releases/tag/3.2.0...4.0.0s
-[3.2.0]: https://github.com/ipregistry/ipregistry-javascript/releases/tag/3.1.0...3.2.0
-[3.1.0]: https://github.com/ipregistry/ipregistry-javascript/releases/tag/3.0.0...3.1.0
-[3.0.0]: https://github.com/ipregistry/ipregistry-javascript/releases/tag/2.0.1...3.0.0
-[2.0.1]: https://github.com/ipregistry/ipregistry-javascript/releases/tag/2.0.0...2.0.1
-[2.0.0]: https://github.com/ipregistry/ipregistry-javascript/releases/tag/1.1.0...2.0.0
-[1.1.0]: https://github.com/ipregistry/ipregistry-javascript/releases/tag/1.0.0...1.1.0
-[1.0.0]: https://github.com/ipregistry/ipregistry-javascript/releases/tag/1.0.0
+[Unreleased]: https://github.com/ipregistry/ipregistry-python/compare/5.0.0...HEAD
+[5.0.0]: https://github.com/ipregistry/ipregistry-python/compare/4.0.0...5.0.0
+[4.0.0]: https://github.com/ipregistry/ipregistry-python/compare/3.2.0...4.0.0
+[3.2.0]: https://github.com/ipregistry/ipregistry-python/compare/3.1.0...3.2.0
+[3.1.0]: https://github.com/ipregistry/ipregistry-python/compare/3.0.0...3.1.0
+[3.0.0]: https://github.com/ipregistry/ipregistry-python/compare/2.0.1...3.0.0
+[2.0.1]: https://github.com/ipregistry/ipregistry-python/compare/2.0.0...2.0.1
+[2.0.0]: https://github.com/ipregistry/ipregistry-python/compare/1.1.0...2.0.0
+[1.1.0]: https://github.com/ipregistry/ipregistry-python/compare/1.0.0...1.1.0
+[1.0.0]: https://github.com/ipregistry/ipregistry-python/releases/tag/1.0.0

README.md

@@ -170,7 +170,7 @@ client = IpregistryClient(IpregistryConfig("YOUR_API_KEY").with_eu_base_url())
 
 All Ipregistry exceptions inherit `IpregistryError` class.
 
-Main subtypes are `ApiError` and `ClientError`.
+Main subtypes are `ApiError` and `ClientError`. Failed entries in batch responses are instances of `IpregistryLookupError` (also available under the legacy alias `LookupError`).
 
 Errors of type _ApiError_ include a `code` field that maps to the one described in the [Ipregistry documentation](https://ipregistry.co/docs/errors), along with a typed `error_code` enum value (`ErrorCode`) that is `None` for unrecognized codes.
 

ipregistry/async_client.py

@@ -21,7 +21,7 @@
                    _merge_batch_responses)
 from .json import AutonomousSystem, IpInfo
 from .model import (ApiResponse, ApiResponseCredits, ApiResponseThrottling,
-                    ClientError, LookupError, RequesterAutonomousSystem,
+                    ClientError, IpregistryLookupError, RequesterAutonomousSystem,
                     RequesterIpInfo, RequesterUserAgent, UserAgent)
 from .request import (DefaultRequestHandler, IpregistryRequestHandler, _backoff_interval,
                       _build_headers, _is_retryable_status, _raise_api_error, _retry_delay)
@@ -63,7 +63,7 @@ async def batch_lookup_asns(self, asns, options):
         try:
             results = response.json().get('results', [])
             parsed_results = [
-                LookupError(data) if 'code' in data else AutonomousSystem(**data)
+                IpregistryLookupError(data) if 'code' in data else AutonomousSystem(**data)
                 for data in results
             ]
             return DefaultRequestHandler.build_api_response(response, parsed_results)
@@ -79,7 +79,7 @@ async def batch_lookup_ips(self, ips, options):
         try:
             results = response.json().get('results', [])
             parsed_results = [
-                LookupError(data) if 'code' in data else IpInfo(**data)
+                IpregistryLookupError(data) if 'code' in data else IpInfo(**data)
                 for data in results
             ]
             return DefaultRequestHandler.build_api_response(response, parsed_results)
@@ -95,7 +95,7 @@ async def batch_parse_user_agents(self, user_agents, options):
         try:
             results = response.json().get('results', [])
             parsed_results = [
-                LookupError(data) if 'code' in data else UserAgent(**data)
+                IpregistryLookupError(data) if 'code' in data else UserAgent(**data)
                 for data in results
             ]
             return DefaultRequestHandler.build_api_response(response, parsed_results)
@@ -244,7 +244,7 @@ async def batch_request(self, items, request_handler_func, **options):
 
         for cached_item_info in sparse_cache:
             if cached_item_info is None:
-                if not isinstance(fresh_item_info[k], LookupError):
+                if not isinstance(fresh_item_info[k], IpregistryLookupError):
                     self._cache.put(_build_cache_key(items[j], options), fresh_item_info[k])
                 result[j] = fresh_item_info[k]
                 k += 1

ipregistry/core.py

@@ -17,7 +17,7 @@
 
 from .cache import IpregistryCache, NoCache
 from .json import AutonomousSystem, IpInfo
-from .model import LookupError, ApiResponse, ApiResponseCredits, ApiResponseThrottling
+from .model import IpregistryLookupError, ApiResponse, ApiResponseCredits, ApiResponseThrottling
 from .request import DefaultRequestHandler, IpregistryRequestHandler
 
 MAX_BATCH_SIZE = 1024
@@ -129,7 +129,7 @@ def batch_request(self, items, request_handler_func, **options):
 
         for cached_item_info in sparse_cache:
             if cached_item_info is None:
-                if not isinstance(fresh_item_info[k], LookupError):
+                if not isinstance(fresh_item_info[k], IpregistryLookupError):
                     self._cache.put(self.__build_cache_key(items[j], options), fresh_item_info[k])
                 result[j] = fresh_item_info[k]
                 k += 1

ipregistry/model.py

@@ -101,10 +101,15 @@ class ClientError(IpregistryError):
    pass
 
 
-class LookupError(ApiError):
+class IpregistryLookupError(ApiError):
     def __init__(self, json: Dict[str, Any]):
         super().__init__(
             code=json.get('code'),
             message=json.get('message'),
             resolution=json.get('resolution')
         )
+
+
+# Backward-compatible alias. Prefer IpregistryLookupError, which does not
+# shadow the Python builtin of the same name.
+LookupError = IpregistryLookupError

ipregistry/request.py

@@ -25,7 +25,7 @@
 import requests
 
 from .model import (ApiError, ApiResponse, ApiResponseCredits, ApiResponseThrottling, AutonomousSystem,
-                    ClientError, IpInfo, LookupError, RequesterAutonomousSystem,
+                    ClientError, IpInfo, IpregistryLookupError, RequesterAutonomousSystem,
                     RequesterIpInfo, RequesterUserAgent, UserAgent)
 
 
@@ -161,7 +161,7 @@ def batch_lookup_asns(self, asns, options):
         try:
             results = response.json().get('results', [])
             parsed_results = [
-                LookupError(data) if 'code' in data else AutonomousSystem(**data)
+                IpregistryLookupError(data) if 'code' in data else AutonomousSystem(**data)
                 for data in results
             ]
             return self.build_api_response(response, parsed_results)
@@ -177,7 +177,7 @@ def batch_lookup_ips(self, ips, options):
         try:
             results = response.json().get('results', [])
             parsed_results = [
-                LookupError(data) if 'code' in data else IpInfo(**data)
+                IpregistryLookupError(data) if 'code' in data else IpInfo(**data)
                 for data in results
             ]
             return self.build_api_response(response, parsed_results)
@@ -193,7 +193,7 @@ def batch_parse_user_agents(self, user_agents, options):
         try:
             results = response.json().get('results', [])
             parsed_results = [
-                LookupError(data) if 'code' in data else UserAgent(**data)
+                IpregistryLookupError(data) if 'code' in data else UserAgent(**data)
                 for data in results
             ]
             return self.build_api_response(response, parsed_results)

tests/test_model.py

@@ -17,7 +17,7 @@
 import unittest
 
 from ipregistry.json import Connection, Currency, CurrencyFormat, IpInfo, UserAgent
-from ipregistry.model import ApiError, ErrorCode, LookupError, RequesterIpInfo
+from ipregistry.model import ApiError, ErrorCode, IpregistryLookupError, LookupError, RequesterIpInfo
 
 
 class TestIpregistryModel(unittest.TestCase):
@@ -97,12 +97,18 @@ def test_error_code_from_code(self):
 
     def test_lookup_error_str(self):
         """
-        Test that str(LookupError) returns the error message
+        Test that str(IpregistryLookupError) returns the error message
         """
-        error = LookupError({'code': 'INVALID_ASN', 'message': 'The ASN is invalid.'})
+        error = IpregistryLookupError({'code': 'INVALID_ASN', 'message': 'The ASN is invalid.'})
         self.assertEqual('The ASN is invalid.', str(error))
         self.assertEqual('INVALID_ASN', error.code)
 
+    def test_lookup_error_backward_compatible_alias(self):
+        """
+        Test that the legacy LookupError name remains usable as an alias
+        """
+        self.assertIs(LookupError, IpregistryLookupError)
+
 
 if __name__ == '__main__':
     unittest.main()