Improve type hints

Author: oschwald

minfraud/models.py

@@ -382,7 +382,7 @@ def __init__(
         is_prepaid: Optional[bool] = None,
         is_virtual: Optional[bool] = None,
         # pylint:disable=redefined-builtin
-        type: Optional[str] = None,
+        type: Optional[str] = None,  # noqa: A002
     ) -> None:
         """Initialize a CreditCard instance."""
         self.issuer = Issuer(**(issuer or {}))

minfraud/request.py

@@ -264,7 +264,7 @@
 }
 
 
-def prepare_report(request: dict[str, Any], validate: bool):
+def prepare_report(request: dict[str, Any], validate: bool) -> dict[str, Any]:
     """Validate and prepare minFraud report."""
     cleaned_request = _copy_and_clean(request)
     if validate:
@@ -279,7 +279,7 @@ def prepare_transaction(
     request: dict[str, Any],
     validate: bool,
     hash_email: bool,
-):
+) -> dict[str, Any]:
     """Validate and prepare minFraud transaction."""
     cleaned_request = _copy_and_clean(request)
     if validate:
@@ -306,7 +306,7 @@ def _copy_and_clean(data: Any) -> Any:
     return data
 
 
-def clean_credit_card(credit_card) -> None:
+def clean_credit_card(credit_card: dict[str, Any]) -> None:
     """Clean the credit_card input of a transaction request."""
     last4 = credit_card.pop("last_4_digits", None)
     if last4:
@@ -318,7 +318,7 @@ def clean_credit_card(credit_card) -> None:
         credit_card["last_digits"] = last4
 
 
-def maybe_hash_email(transaction) -> None:
+def maybe_hash_email(transaction: dict[str, Any]) -> None:
     """Hash email address in transaction, if present."""
     try:
         email = transaction["email"]

minfraud/validation.py

@@ -14,7 +14,7 @@
 from decimal import Decimal
 from typing import Optional
 
-from email_validator import validate_email  # type: ignore
+from email_validator import validate_email
 from voluptuous import (
     All,
     Any,

minfraud/webservice.py

@@ -1,15 +1,15 @@
 """Client for minFraud Score, Insights, and Factors."""
 
+from __future__ import annotations
+
 import json
-from collections.abc import Sequence
 from functools import partial
-from typing import Any, Callable, Optional, Union, cast
+from typing import TYPE_CHECKING, Any, Callable, cast
 
 import aiohttp
 import aiohttp.http
 import requests
 import requests.utils
-from requests.models import Response
 
 from .errors import (
     AuthenticationError,
@@ -23,6 +23,18 @@
 from .request import prepare_report, prepare_transaction
 from .version import __version__
 
+if TYPE_CHECKING:
+    import sys
+    import types
+    from collections.abc import Sequence
+
+    from requests.models import Response
+
+    if sys.version_info >= (3, 11):
+        from typing import Self
+    else:
+        from typing_extensions import Self
+
 _AIOHTTP_UA = f"minFraud-API/{__version__} {aiohttp.http.SERVER_SOFTWARE}"
 
 _REQUEST_UA = f"minFraud-API/{__version__} {requests.utils.default_user_agent()}"
@@ -68,32 +80,35 @@ def _handle_success(
         raw_body: str,
         uri: str,
         model_class: Callable,
-    ) -> Union[Score, Factors, Insights]:
+    ) -> Score | Factors | Insights:
         """Handle successful response."""
         try:
             decoded_body = json.loads(raw_body)
         except ValueError as ex:
-            raise MinFraudError(
+            msg = (
                 "Received a 200 response but could not decode the "
-                f"response as JSON: {raw_body}",
+                f"response as JSON: {raw_body}"
+            )
+            raise MinFraudError(
+                msg,
                 200,
                 uri,
             ) from ex
-        return model_class(**decoded_body)  # type: ignore
+        return model_class(**decoded_body)
 
     def _exception_for_error(
         self,
         status: int,
-        content_type: Optional[str],
+        content_type: str | None,
         raw_body: str,
         uri: str,
-    ) -> Union[
-        AuthenticationError,
-        InsufficientFundsError,
-        InvalidRequestError,
-        HTTPError,
-        PermissionRequiredError,
-    ]:
+    ) -> (
+        AuthenticationError
+        | InsufficientFundsError
+        | InvalidRequestError
+        | HTTPError
+        | PermissionRequiredError
+    ):
         """Return the exception for the error responses."""
         if 400 <= status < 500:
             return self._exception_for_4xx_status(status, content_type, raw_body, uri)
@@ -104,16 +119,16 @@ def _exception_for_error(
     def _exception_for_4xx_status(
         self,
         status: int,
-        content_type: Optional[str],
+        content_type: str | None,
         raw_body: str,
         uri: str,
-    ) -> Union[
-        AuthenticationError,
-        InsufficientFundsError,
-        InvalidRequestError,
-        HTTPError,
-        PermissionRequiredError,
-    ]:
+    ) -> (
+        AuthenticationError
+        | InsufficientFundsError
+        | InvalidRequestError
+        | HTTPError
+        | PermissionRequiredError
+    ):
         """Return exception for error responses with 4xx status codes."""
         if not raw_body:
             return HTTPError(
@@ -161,12 +176,12 @@ def _exception_for_web_service_error(
         code: str,
         status: int,
         uri: str,
-    ) -> Union[
-        InvalidRequestError,
-        AuthenticationError,
-        PermissionRequiredError,
-        InsufficientFundsError,
-    ]:
+    ) -> (
+        InvalidRequestError
+        | AuthenticationError
+        | PermissionRequiredError
+        | InsufficientFundsError
+    ):
         """Return exception for error responses with the JSON body."""
         if code in (
             "ACCOUNT_ID_REQUIRED",
@@ -185,7 +200,7 @@ def _exception_for_web_service_error(
     @staticmethod
     def _exception_for_5xx_status(
         status: int,
-        raw_body: Optional[str],
+        raw_body: str | None,
         uri: str,
     ) -> HTTPError:
         """Return exception for error response with 5xx status codes."""
@@ -199,7 +214,7 @@ def _exception_for_5xx_status(
     @staticmethod
     def _exception_for_unexpected_status(
         status: int,
-        raw_body: Optional[str],
+        raw_body: str | None,
         uri: str,
     ) -> HTTPError:
         """Return exception for responses with unexpected status codes."""
@@ -215,7 +230,7 @@ class AsyncClient(BaseClient):
     """Async client for accessing the minFraud web services."""
 
     _existing_session: aiohttp.ClientSession
-    _proxy: Optional[str]
+    _proxy: str | None
 
     def __init__(
         self,
@@ -224,7 +239,7 @@ def __init__(
         host: str = "minfraud.maxmind.com",
         locales: Sequence[str] = ("en",),
         timeout: float = 60,
-        proxy: Optional[str] = None,
+        proxy: str | None = None,
     ) -> None:
         """Construct AsyncClient.
 
@@ -368,7 +383,7 @@ async def score(
 
     async def report(
         self,
-        report: dict[str, Optional[str]],
+        report: dict[str, str | None],
         validate: bool = True,
     ) -> None:
         """Send a transaction report to the Report Transaction endpoint.
@@ -405,7 +420,7 @@ async def _response_for(
         request: dict[str, Any],
         validate: bool,
         hash_email: bool,
-    ) -> Union[Score, Factors, Insights]:
+    ) -> Score | Factors | Insights:
         """Send request and create response object."""
         prepared_request = prepare_transaction(request, validate, hash_email)
         async with await self._do_request(uri, prepared_request) as response:
@@ -443,17 +458,22 @@ async def close(self) -> None:
         if hasattr(self, "_existing_session"):
             await self._existing_session.close()
 
-    async def __aenter__(self) -> "AsyncClient":
+    async def __aenter__(self) -> Self:
         return self
 
-    async def __aexit__(self, exc_type: None, exc_value: None, traceback: None) -> None:
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: types.TracebackType | None,
+    ) -> None:
         await self.close()
 
 
 class Client(BaseClient):
     """Synchronous client for accessing the minFraud web services."""
 
-    _proxies: Optional[dict[str, str]]
+    _proxies: dict[str, str] | None
     _session: requests.Session
 
     def __init__(
@@ -463,7 +483,7 @@ def __init__(
         host: str = "minfraud.maxmind.com",
         locales: Sequence[str] = ("en",),
         timeout: float = 60,
-        proxy: Optional[str] = None,
+        proxy: str | None = None,
     ) -> None:
         """Construct Client.
 
@@ -619,7 +639,7 @@ def score(
             ),
         )
 
-    def report(self, report: dict[str, Optional[str]], validate: bool = True) -> None:
+    def report(self, report: dict[str, str | None], validate: bool = True) -> None:
         """Send a transaction report to the Report Transaction endpoint.
 
         :param report: A dictionary containing the transaction report to be sent
@@ -654,7 +674,7 @@ def _response_for(
         request: dict[str, Any],
         validate: bool,
         hash_email: bool,
-    ) -> Union[Score, Factors, Insights]:
+    ) -> Score | Factors | Insights:
         """Send request and create response object."""
         prepared_request = prepare_transaction(request, validate, hash_email)
 
@@ -681,8 +701,13 @@ def close(self) -> None:
         """
         self._session.close()
 
-    def __enter__(self) -> "Client":
+    def __enter__(self) -> Self:
         return self
 
-    def __exit__(self, exc_type: None, exc_value: None, traceback: None) -> None:
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: types.TracebackType | None,
+    ) -> None:
         self.close()

pyproject.toml

@@ -10,6 +10,7 @@ dependencies = [
     "email_validator>=2.0.0,<3.0.0",
     "geoip2>=5.0.1,<6.0.0",
     "requests>=2.24.0,<3.0.0",
+    "typing-extensions>=4.13.2",
     "voluptuous",
 ]
 requires-python = ">=3.9"

tests/test_models.py

@@ -1,7 +1,28 @@
-import unittest
-from typing import Any, Union
+from __future__ import annotations
 
-from minfraud.models import *
+import unittest
+from typing import Any
+
+from minfraud.models import (
+    BillingAddress,
+    CreditCard,
+    Device,
+    Disposition,
+    Email,
+    EmailDomain,
+    Factors,
+    GeoIP2Location,
+    Insights,
+    IPAddress,
+    Issuer,
+    Phone,
+    Reason,
+    RiskScoreReason,
+    Score,
+    ScoreIPAddress,
+    ServiceWarning,
+    ShippingAddress,
+)
 
 
 class TestModels(unittest.TestCase):
@@ -23,7 +44,7 @@ def test_shipping_address(self) -> None:
         self.assertEqual(200, address.distance_to_billing_address)
 
     @property
-    def address_dict(self) -> dict[str, Union[bool, float]]:
+    def address_dict(self) -> dict[str, bool | float]:
         return {
             "is_in_ip_country": True,
             "latitude": 43.1,
@@ -32,7 +53,7 @@ def address_dict(self) -> dict[str, Union[bool, float]]:
             "is_postal_in_city": True,
         }
 
-    def check_address(self, address) -> None:
+    def check_address(self, address: BillingAddress | ShippingAddress) -> None:
         self.assertEqual(True, address.is_in_ip_country)
         self.assertEqual(True, address.is_postal_in_city)
         self.assertEqual(100, address.distance_to_ip_location)
@@ -374,7 +395,7 @@ def factors_response(self) -> dict[str, Any]:
             ],
         }
 
-    def check_insights_data(self, insights, uuid) -> None:
+    def check_insights_data(self, insights: Insights | Factors, uuid: str) -> None:
         self.assertEqual("US", insights.ip_address.country.iso_code)
         self.assertEqual(False, insights.ip_address.country.is_in_european_union)
         self.assertEqual(True, insights.credit_card.is_business)
@@ -396,7 +417,7 @@ def check_insights_data(self, insights, uuid) -> None:
         self.assertEqual("INVALID_INPUT", insights.warnings[0].code)
         self.assertIsInstance(insights.warnings, list, "warnings is a list")
 
-    def check_risk_score_reasons_data(self, reasons) -> None:
+    def check_risk_score_reasons_data(self, reasons: list[RiskScoreReason]) -> None:
         self.assertEqual(1, len(reasons))
         self.assertEqual(45, reasons[0].multiplier)
         self.assertEqual(1, len(reasons[0].reasons))