Use TypedDicts to better describe return values

Author: JerrySmidt

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "postcode-eu-api-client"
-version = "1.0.1"
+version = "1.0.2"
 description = "Python client for the Postcode.eu API"
 license = "BSD-2-Clause"
 readme = "README.md"

src/postcode_eu_api_client/client.py

@@ -3,7 +3,7 @@
 import re
 import sys
 import importlib.metadata
-from typing import Any, cast
+from typing import Any
 from urllib.parse import quote
 
 try:
@@ -25,12 +25,23 @@
     UnexpectedException,
 )
 
+from .types import (
+    DutchAddressResult,
+    AutocompleteResult,
+    AutocompleteAddressResult,
+    SupportedCountry,
+    DutchAddressDistanceResult,
+    DutchPostcodeRange,
+    ValidationResult,
+    ClientAccount,
+    AccountInfo,
+)
 
 class Client:
-    SESSION_HEADER_KEY = 'X-Autocomplete-Session'
-    SESSION_HEADER_VALUE_VALIDATION = r'^[a-z\d\-_.]{8,64}$'
+    SESSION_HEADER_KEY: str = 'X-Autocomplete-Session'
+    SESSION_HEADER_VALUE_VALIDATION: str = r'^[a-z\d\-_.]{8,64}$'
 
-    _SERVER_URL = 'https://api.postcode.eu/'
+    _SERVER_URL: str = 'https://api.postcode.eu/'
 
     def __init__(self, key: str, secret: str, platform: str):
         """
@@ -41,13 +52,13 @@ def __init__(self, key: str, secret: str, platform: str):
             secret: The Postcode.eu API secret, provided when registering an account.
             platform: A platform identifier, short description of the platform using the API client.
         """
-        self._key = key
-        self._secret = secret
-        self._platform = platform
+        self._key: str = key
+        self._secret: str = secret
+        self._platform: str = platform
         self._most_recent_response_headers: dict[str, list[str]] = {}
 
         # Create a persistent session for connection reuse
-        self._session = requests.Session()
+        self._session: requests.Session = requests.Session()
         self._session.auth = (self._key, self._secret)
         self._session.headers.update({
             'User-Agent': self._get_user_agent()
@@ -60,7 +71,7 @@ def international_autocomplete(
         session: str,
         language: str | None = None,
         building_list_mode: str | None = None
-    ) -> dict[str, Any]:
+    ) -> AutocompleteResult:
         """
         Autocomplete international addresses.
 
@@ -80,7 +91,7 @@ def international_autocomplete(
 
         return self._api_get(path, session)
 
-    def international_get_details(self, context: str, session: str) -> dict[str, Any]:
+    def international_get_details(self, context: str, session: str) -> AutocompleteAddressResult:
         """
         Get address information based on the provided autocomplete context.
 
@@ -91,21 +102,20 @@ def international_get_details(self, context: str, session: str) -> dict[str, Any
 
         return self._api_get(path, session)
 
-    def international_get_supported_countries(self) -> list[dict[str, str]]:
+    def international_get_supported_countries(self) -> list[SupportedCountry]:
         """
         Fetches list of supported countries. Recommended to cache the result.
 
         https://developer.postcode.eu/documentation/international/v1/Autocomplete/getSupportedCountries
         """
-        response = self._api_get('international/v1/supported-countries', None)
-        return cast(list[dict[str, str]], response)
+        return self._api_get('international/v1/supported-countries', None)
 
     def dutch_address_by_postcode(
         self,
         postcode: str,
         house_number: int,
         house_number_addition: str | None = None
-    ) -> dict[str, Any]:
+    ) -> DutchAddressResult:
         """
         Get an address based on its unique combination of postcode, house number and house number addition.
 
@@ -128,7 +138,7 @@ def dutch_address_by_postcode(
 
         return self._api_get('/'.join(url_parts), None)
 
-    def dutch_address_rd(self, rd_x: float, rd_y: float) -> dict[str, Any]:
+    def dutch_address_rd(self, rd_x: float, rd_y: float) -> DutchAddressDistanceResult:
         """
         Get the closest Dutch address based on Dutch Rijksdriehoeksmeting coordinates.
 
@@ -142,7 +152,7 @@ def dutch_address_rd(self, rd_x: float, rd_y: float) -> dict[str, Any]:
 
         return self._api_get('/'.join(url_parts), None)
 
-    def dutch_address_lat_lon(self, latitude: float, longitude: float) -> dict[str, Any]:
+    def dutch_address_lat_lon(self, latitude: float, longitude: float) -> DutchAddressDistanceResult:
         """
         Get the closest Dutch address based on latitude and longitude.
 
@@ -156,7 +166,7 @@ def dutch_address_lat_lon(self, latitude: float, longitude: float) -> dict[str,
 
         return self._api_get('/'.join(url_parts), None)
 
-    def dutch_address_bag_number_designation(self, bag_number_designation_id: str) -> dict[str, Any]:
+    def dutch_address_bag_number_designation(self, bag_number_designation_id: str) -> DutchAddressResult:
         """
         Get the unique Dutch address connected to a BAG Number Designation ID ("Nummeraanduiding ID").
 
@@ -169,7 +179,7 @@ def dutch_address_bag_number_designation(self, bag_number_designation_id: str) -
 
         return self._api_get('/'.join(url_parts), None)
 
-    def dutch_address_bag_addressable_object(self, bag_addressable_object_id: str) -> dict[str, Any]:
+    def dutch_address_bag_addressable_object(self, bag_addressable_object_id: str) -> list[DutchAddressResult]:
         """
         Get the Dutch address(es) connected to a BAG Addressable Object ID.
 
@@ -182,7 +192,7 @@ def dutch_address_bag_addressable_object(self, bag_addressable_object_id: str) -
 
         return self._api_get('/'.join(url_parts), None)
 
-    def dutch_address_postcode_ranges(self, postcode: str) -> dict[str, Any]:
+    def dutch_address_postcode_ranges(self, postcode: str) -> list[DutchPostcodeRange]:
         """
         Get all streets and house number ranges for the provided postcode.
 
@@ -211,7 +221,7 @@ def validate(
         building: str | None = None,
         region: str | None = None,
         street_and_building: str | None = None
-    ) -> dict[str, Any]:
+    ) -> ValidationResult:
         """
         Validate a full address, correcting and completing all parts of the address.
 
@@ -231,7 +241,7 @@ def validate(
             'streetAndBuilding': street_and_building,
         }
 
-        parameters = []
+        parameters: list[str] = []
         for key, value in variables.items():
             if value is not None:
                 parameters.append(f'{key}={quote(value, safe="")}')
@@ -242,7 +252,7 @@ def validate(
 
         return self._api_get(path, None)
 
-    def get_country(self, country: str) -> dict[str, Any]:
+    def get_country(self, country: str) -> SupportedCountry:
         """
         Get country information.
 
@@ -273,7 +283,7 @@ def create_client_account(
         invoice_address_country_iso: str,
         invoice_contact_name: str | None = None,
         is_test: bool = False
-    ) -> dict[str, Any]:
+    ) -> ClientAccount:
         """
         Create an account for your client. The new account will be linked to your reseller account.
 
@@ -308,7 +318,7 @@ def create_client_account(
 
         return self._api_post('reseller/v1/client', post_data)
 
-    def account_info(self) -> dict[str, Any]:
+    def account_info(self) -> AccountInfo:
         """
         Retrieve basic account information for the currently authenticated account.
 
@@ -337,19 +347,19 @@ def _validate_session_header(self, session: str) -> None:
         if not re.match(self.SESSION_HEADER_VALUE_VALIDATION, session, re.IGNORECASE):
             raise InvalidSessionValueException(
                 f'Session value `{session}` does not conform to `{self.SESSION_HEADER_VALUE_VALIDATION}`, '
-                'please refer to the API documentation for further information.'
+                + 'please refer to the API documentation for further information.'
             )
 
-    def _api_get(self, path: str, session: str | None) -> dict[str, Any]:
+    def _api_get(self, path: str, session: str | None) -> Any:
         """Perform a GET call to the API."""
         url = self._SERVER_URL + path
-        headers = {}
+        headers: dict[str, str] = {}
         if session is not None:
             headers[self.SESSION_HEADER_KEY] = session
 
         return self._request('GET', url, headers=headers)
 
-    def _api_post(self, path: str, post_data: dict[str, Any]) -> dict[str, Any]:
+    def _api_post(self, path: str, post_data: dict[str, Any]) -> Any:
         """Perform a POST call to the API."""
         url = self._SERVER_URL + path
         return self._request('POST', url, data=post_data)

src/postcode_eu_api_client/types.py

@@ -0,0 +1,137 @@
+from typing import TypedDict, Literal, Any, TypeAlias
+
+class DutchAddressResult(TypedDict):
+    street: str
+    streetNen: str
+    houseNumber: int
+    houseNumberAddition: str | None
+    postcode: str
+    city: str
+    cityShort: str
+    cityId: str
+    municipality: str
+    municipalityShort: str
+    municipalityId: str
+    province: str
+    rdX: int | None
+    rdY: int | None
+    latitude: float | None
+    longitude: float | None
+    bagNumberDesignationId: str | None
+    bagAddressableObjectId: str | None
+    addressType: str
+    purposes: list[str] | None
+    surfaceArea: int | None
+    houseNumberAdditions: list[str]
+
+class AutocompleteMatch(TypedDict):
+    value: str
+    label: str
+    description: str
+    precision: str
+    context: str
+    highlights: list[list[int]]
+
+class AutocompleteResult(TypedDict):
+    newContext: str | None
+    matches: list[AutocompleteMatch]
+
+class AutocompleteAddress(TypedDict):
+    country: str
+    locality: str
+    street: str
+    postcode: str
+    building: str
+    buildingNumber: int | None
+    buildingNumberAddition: str | None
+
+class AddressLocation(TypedDict):
+    latitude: float
+    longitude: float
+    precision: Literal['Address', 'Street', 'PostalCode', 'Locality']
+
+class AddressCountry(TypedDict):
+    name: str
+    iso3Code: str
+    iso2Code: str
+
+AddressDetails: TypeAlias = dict[str, Any]
+
+class AutocompleteAddressResult(TypedDict):
+    language: str
+    address: AutocompleteAddress
+    mailLines: list[str]
+    location: AddressLocation | None
+    isPoBox: bool
+    country: AddressCountry
+    details: AddressDetails
+
+class SupportedCountry(TypedDict):
+    name: str
+    iso2: str
+    iso3: str
+
+class DutchAddressDistanceResult(TypedDict):
+    address: DutchAddressResult
+    distance: float
+
+class DutchPostcodeRange(TypedDict):
+    street: str
+    streetNen: str
+    startHouseNumber: int
+    endHouseNumber: int
+    houseNumberType: str
+    city: str
+    cityShort: str
+    cityId: str
+    municipality: str
+    municipalityShort: str
+    municipalityId: str
+    province: str
+
+class ValidationMatchStatus(TypedDict):
+    grade: str
+    validationLevel: str
+    isAmbiguous: bool
+
+class ValidationMatchAddress(TypedDict):
+    country: str
+    locality: str | None
+    street: str | None
+    postcode: str | None
+    building: str | None
+    buildingNumber: int | None
+    buildingNumberAddition: str | None
+    region: str | None
+
+class ValidationMatch(TypedDict):
+    status: ValidationMatchStatus
+    language: str
+    address: ValidationMatchStatus
+    mailLines: list[str]
+    location: AddressLocation | None
+    isPoBox: bool
+    country: AddressCountry
+    details: AddressDetails | None
+
+class ValidationResult(TypedDict):
+    country: AddressCountry
+    matches: list[ValidationMatch]
+
+class ClientAccount(TypedDict):
+    accountId: int
+    key: str
+    secret: str
+
+class AccountSubscription(TypedDict):
+    startDate: str
+    limit: int
+    usage: int
+
+class AccountInfo(TypedDict):
+    name: str
+    hasAccess: bool
+    countries: list[str]
+    adminEmail: str
+    contactEmail: str
+    subscription: AccountSubscription