Add type annotations for BankID API responses (#78)

* Add TypedDict implementations of API responses.

* Set asyncio_default_fixture_loop_scope.

This will silence a deprecation warning from pytest-asyncio.

pytest-dev/pytest-asyncio#924

* Use session scope for cert_and_key fixture.

Author: Majsvaffla

bankid/asyncclient.py

@@ -4,6 +4,15 @@
 
 from bankid.baseclient import BankIDClientBaseclass
 from bankid.exceptions import get_json_error_class
+from bankid.responses import (
+    AuthenticateResponse,
+    CollectCompleteResponse,
+    CollectFailedResponse,
+    CollectPendingResponse,
+    PhoneAuthenticateResponse,
+    PhoneSignResponse,
+    SignResponse,
+)
 
 
 class BankIDAsyncClient(BankIDClientBaseclass[httpx.AsyncClient]):
@@ -32,7 +41,7 @@ async def authenticate(
         user_visible_data: Union[str, None]  = None,
         user_non_visible_data: Union[str, None]  = None,
         user_visible_data_format: Union[str, None]  = None,
-    ) -> Dict[str, str]:
+    ) -> AuthenticateResponse:
         """Request an authentication order. The :py:meth:`collect` method
         is used to query the status of the order.
 
@@ -62,8 +71,8 @@ async def authenticate(
             this parameter indicates that userVisibleData holds formatting characters which
             potentially make for a more pleasant user experience.
         :type user_visible_data_format: str
-        :return: The order response.
-        :rtype: dict
+        :return: The order response parsed as a dict.
+        :rtype: AuthenticateResponse
         :raises BankIDError: raises a subclass of this error
                              when error has been returned from server.
 
@@ -91,7 +100,7 @@ async def phone_authenticate(
         user_visible_data: Union[str, None] = None,
         user_non_visible_data: Union[str, None] = None,
         user_visible_data_format: Union[str, None] = None,
-    ) -> Dict[str, str]:
+    ) -> PhoneAuthenticateResponse:
         """Initiates an authentication order when the user is talking
         to the RP over the phone. The :py:meth:`collect` method
         is used to query the status of the order.
@@ -123,8 +132,8 @@ async def phone_authenticate(
             this parameter indicates that userVisibleData holds formatting characters which
             potentially make for a more pleasant user experience.
         :type user_visible_data_format: str
-        :return: The order response.
-        :rtype: dict
+        :return: The order response parsed as a dict.
+        :rtype: PhoneAuthenticateResponse
         :raises BankIDError: raises a subclass of this error
                              when error has been returned from server.
 
@@ -155,7 +164,7 @@ async def sign(
         requirement: Union[Dict[str, Any], None] = None,
         user_non_visible_data: Union[str, None] = None,
         user_visible_data_format: Union[str, None] = None,
-    ) -> Dict[str, str]:
+    ) -> SignResponse:
         """Request a signing order. The :py:meth:`collect` method
         is used to query the status of the order.
 
@@ -183,8 +192,8 @@ async def sign(
             this parameter indicates that userVisibleData holds formatting characters which
             potentially make for a more pleasant user experience.
         :type user_visible_data_format: str
-        :return: The order response.
-        :rtype: dict
+        :return: The order response parsed as a dict.
+        :rtype: SignResponse
         :raises BankIDError: raises a subclass of this error
                      when error has been returned from server.
 
@@ -212,7 +221,7 @@ async def phone_sign(
         requirement: Union[Dict[str, Any], None] = None,
         user_non_visible_data: Union[str, None] = None,
         user_visible_data_format: Union[str, None] = None,
-    ) -> Dict[str, str]:
+    ) -> PhoneSignResponse:
         """Initiates an authentication order when the user is talking to
         the RP over the phone. The :py:meth:`collect` method
         is used to query the status of the order.
@@ -242,8 +251,8 @@ async def phone_sign(
             this parameter indicates that userVisibleData holds formatting characters which
             potentially make for a more pleasant user experience.
         :type user_visible_data_format: str
-        :return: The order response.
-        :rtype: dict
+        :return: The order response parsed as a dict.
+        :rtype: PhoneSignResponse
         :raises BankIDError: raises a subclass of this error
                      when error has been returned from server.
 
@@ -267,7 +276,7 @@ async def phone_sign(
         else:
             raise get_json_error_class(response)
 
-    async def collect(self, order_ref: str) -> dict:
+    async def collect(self, order_ref: str) -> Union[CollectPendingResponse, CollectCompleteResponse, CollectFailedResponse]:
         """Collects the result of a sign or auth order using the
         ``orderRef`` as reference.
 
@@ -326,8 +335,8 @@ async def collect(self, order_ref: str) -> dict:
 
         :param order_ref: The ``orderRef`` UUID returned from auth or sign.
         :type order_ref: str
-        :return: The CollectResponse parsed to a dictionary.
-        :rtype: dict
+        :return: The order response parsed to a dict.
+        :rtype: Union[CollectPendingResponse, CollectCompleteResponse, CollectFailedResponse]
         :raises BankIDError: raises a subclass of this error
                              when error has been returned from server.
 

bankid/baseclient.py

@@ -1,7 +1,7 @@
 import base64
 import ssl
 from datetime import datetime
-from typing import Tuple, Dict, Any, Union, TypeVar, Generic
+from typing import Any, Dict, Generic, Tuple, TypeVar, Union
 from urllib.parse import urljoin
 
 from bankid.qr import generate_qr_code_content

bankid/responses.py

@@ -0,0 +1,67 @@
+from typing_extensions import Literal, NotRequired, TypedDict
+
+class SignResponse(TypedDict):
+    orderRef: str
+    autoStartToken: str
+    qrStartToken: str
+    qrStartSecret: str
+
+
+class PhoneSignResponse(TypedDict):
+    orderRef: str
+
+
+class AuthenticateResponse(TypedDict):
+    orderRef: str
+    autoStartToken: str
+    qrStartToken: str
+    qrStartSecret: str
+
+
+class PhoneAuthenticateResponse(TypedDict):
+    orderRef: str
+
+
+class Device(TypedDict):
+    ipAddress: str
+    uhi: str
+
+
+class StepUp(TypedDict):
+    mrtd: bool
+
+
+class User(TypedDict):
+    personalNumber: str
+    name: str
+    givenName: str
+    surname: str
+
+
+class CompletionData(TypedDict):
+    user: User
+    device: Device
+    stepUp: StepUp
+    bankIdIssueDate: str
+    signature: str
+    ocspResponse: str
+    risk: NotRequired[str]
+
+
+class _CollectResponse(TypedDict):
+    orderRef: str
+
+
+class CollectPendingResponse(_CollectResponse):
+    status: Literal["pending"]
+    hintCode: str
+
+
+class CollectCompleteResponse(_CollectResponse):
+    status: Literal["complete"]
+    completionData: CompletionData
+
+
+class CollectFailedResponse(_CollectResponse):
+    status: Literal["failed"]
+    hintCode: str

bankid/syncclient.py

@@ -4,6 +4,15 @@
 
 from bankid.baseclient import BankIDClientBaseclass
 from bankid.exceptions import get_json_error_class
+from bankid.responses import (
+    AuthenticateResponse,
+    CollectCompleteResponse,
+    CollectFailedResponse,
+    CollectPendingResponse,
+    PhoneAuthenticateResponse,
+    PhoneSignResponse,
+    SignResponse,
+)
 
 
 class BankIDClient(BankIDClientBaseclass[httpx.Client]):
@@ -32,7 +41,7 @@ def authenticate(
         user_visible_data: Union[str, None] = None,
         user_non_visible_data: Union[str, None] = None,
         user_visible_data_format: Union[str, None] = None,
-    ) -> Dict[str, str]:
+    ) -> AuthenticateResponse:
         """Request an authentication order. The :py:meth:`collect` method
         is used to query the status of the order.
 
@@ -62,8 +71,8 @@ def authenticate(
             this parameter indicates that userVisibleData holds formatting characters which
             potentially make for a more pleasant user experience.
         :type user_visible_data_format: str
-        :return: The order response.
-        :rtype: dict
+        :return: The order response parsed to a dict.
+        :rtype: AuthenticateResponse
         :raises BankIDError: raises a subclass of this error
                              when error has been returned from server.
 
@@ -91,7 +100,7 @@ def phone_authenticate(
         user_visible_data: Union[str, None] = None,
         user_non_visible_data: Union[str, None] = None,
         user_visible_data_format: Union[str, None] = None,
-    ) -> Dict[str, str]:
+    ) -> PhoneAuthenticateResponse:
         """Initiates an authentication order when the user is talking
         to the RP over the phone. The :py:meth:`collect` method
         is used to query the status of the order.
@@ -123,8 +132,8 @@ def phone_authenticate(
             this parameter indicates that userVisibleData holds formatting characters which
             potentially make for a more pleasant user experience.
         :type user_visible_data_format: str
-        :return: The order response.
-        :rtype: dict
+        :return: The order response parsed to a dict.
+        :rtype: PhoneAuthenticateResponse
         :raises BankIDError: raises a subclass of this error
                              when error has been returned from server.
 
@@ -155,7 +164,7 @@ def sign(
         requirement: Union[Dict[str, Any], None] = None,
         user_non_visible_data: Union[str, None] = None,
         user_visible_data_format: Union[str, None] = None,
-    ) -> Dict[str, str]:
+    ) -> SignResponse:
         """Request a signing order. The :py:meth:`collect` method
         is used to query the status of the order.
 
@@ -183,8 +192,8 @@ def sign(
             this parameter indicates that userVisibleData holds formatting characters which
             potentially make for a more pleasant user experience.
         :type user_visible_data_format: str
-        :return: The order response.
-        :rtype: dict
+        :return: The order response parsed to a dict.
+        :rtype: SignResponse
         :raises BankIDError: raises a subclass of this error
                      when error has been returned from server.
 
@@ -211,7 +220,7 @@ def phone_sign(
         requirement: Union[Dict[str, Any], None] = None,
         user_non_visible_data: Union[str, None] = None,
         user_visible_data_format: Union[str, None] = None,
-    ) -> Dict[str, str]:
+    ) -> PhoneSignResponse:
         """Initiates an authentication order when the user is talking to
         the RP over the phone.  The :py:meth:`collect` method
         is used to query the status of the order.
@@ -241,8 +250,8 @@ def phone_sign(
             this parameter indicates that userVisibleData holds formatting characters which
             potentially make for a more pleasant user experience.
         :type user_visible_data_format: str
-        :return: The order response.
-        :rtype: dict
+        :return: The order response parsed to a dict.
+        :rtype: PhoneSignResponse
         :raises BankIDError: raises a subclass of this error
                      when error has been returned from server.
 
@@ -266,7 +275,7 @@ def phone_sign(
         else:
             raise get_json_error_class(response)
 
-    def collect(self, order_ref: str) -> dict:
+    def collect(self, order_ref: str) -> Union[CollectPendingResponse, CollectCompleteResponse, CollectFailedResponse]:
         """Collects the result of a sign or auth order using the
         ``orderRef`` as reference.
 
@@ -325,8 +334,8 @@ def collect(self, order_ref: str) -> dict:
 
         :param order_ref: The ``orderRef`` UUID returned from auth or sign.
         :type order_ref: str
-        :return: The CollectResponse parsed to a dictionary.
-        :rtype: dict
+        :return: The order response parsed to a dict.
+        :rtype: Union[CollectPendingResponse, CollectCompleteResponse, CollectFailedResponse]
         :raises BankIDError: raises a subclass of this error
                              when error has been returned from server.
 

setup.cfg

@@ -1,2 +1,5 @@
 [wheel]
 universal=1
+
+[tool:pytest]
+asyncio_default_fixture_loop_scope = session

tests/conftest.py

@@ -11,7 +11,7 @@ def ip_address() -> str:
     return "127.0.0.1"
 
 
-@pytest.fixture()
+@pytest.fixture(scope="session")
 def cert_and_key() -> Tuple[str, str]:
     cert, key = get_test_cert_and_key()
     return str(cert), str(key)