fix: strong and consistent typing across the library

BREAKING CHANGE: this change introduces a very strong typing across the library. From now on, we demand that each method returns a single type and converts the results into the specified return type, otherwise it raises a TypeError exception. This should resolve any type checking linter errors within the library as well.

Author: ryshoooo

poetry.lock

@@ -133,7 +133,7 @@ def logic(self) -> str:
         return self._logic
 
     @logic.setter
-    def logic(self, value: str) -> str:
+    def logic(self, value: str) -> None:
         self._logic = value
 
     @property

src/keycloak/authorization/permission.py

@@ -24,6 +24,9 @@
 
 from keycloak.exceptions import KeycloakAuthorizationConfigError
 
+from .permission import Permission
+from .role import Role
+
 
 class Policy:
     """
@@ -172,7 +175,7 @@ def permissions(self) -> list:
     def permissions(self, value: list) -> None:
         self._permissions = value
 
-    def add_role(self, role: dict) -> None:
+    def add_role(self, role: str | Role) -> None:
         """
         Add keycloak role in policy.
 
@@ -185,7 +188,7 @@ def add_role(self, role: dict) -> None:
             raise KeycloakAuthorizationConfigError(error_msg)
         self._roles.append(role)
 
-    def add_permission(self, permission: dict) -> None:
+    def add_permission(self, permission: str | Permission) -> None:
         """
         Add keycloak permission in policy.
 

src/keycloak/authorization/policy.py

@@ -61,7 +61,7 @@ def get_name(self) -> str:
         """
         return self.name
 
-    def __eq__(self, other: str | Role) -> bool:
+    def __eq__(self, other: object) -> bool:
         """
         Eq method.
 

src/keycloak/authorization/role.py

@@ -27,13 +27,16 @@
 try:
     from urllib.parse import urljoin
 except ImportError:  # pragma: no cover
-    from urlparse import urljoin
+    from urlparse import urljoin  # pyright: ignore[reportMissingImports]
+
+from typing import Any
 
 import httpx
 import requests
 from httpx import Response as AsyncResponse
 from requests import Response
 from requests.adapters import HTTPAdapter
+from requests_toolbelt import MultipartEncoder
 
 from .exceptions import KeycloakConnectionError
 
@@ -67,8 +70,8 @@ def __init__(
         self,
         base_url: str,
         headers: dict | None = None,
-        timeout: int = 60,
-        verify: bool = True,
+        timeout: int | None = 60,
+        verify: bool | str = True,
         proxies: dict | None = None,
         cert: str | tuple | None = None,
         max_retries: int = 1,
@@ -112,9 +115,13 @@ def __init__(
             adapter_kwargs = {"max_retries": max_retries}
             if pool_maxsize is not None:
                 adapter_kwargs["pool_maxsize"] = pool_maxsize
-            adapter = HTTPAdapter(**adapter_kwargs)
+            adapter = HTTPAdapter(**adapter_kwargs)  # pyright: ignore[reportArgumentType]
             # adds POST to retry whitelist
-            allowed_methods = set(adapter.max_retries.allowed_methods)
+            allowed_methods = (
+                set(adapter.max_retries.allowed_methods)
+                if adapter.max_retries.allowed_methods
+                else set()
+            )
             allowed_methods.add("POST")
             adapter.max_retries.allowed_methods = frozenset(allowed_methods)
 
@@ -132,8 +139,8 @@ def __init__(
                 max_keepalive_connections=20,
             ),
         )
-        self.async_s.auth = None  # don't let requests add auth headers
-        self.async_s.transport = httpx.AsyncHTTPTransport(retries=1)
+        self.async_s.auth = None  # pyright: ignore[reportAttributeAccessIssue]
+        self.async_s.transport = httpx.AsyncHTTPTransport(retries=1)  # pyright: ignore[reportAttributeAccessIssue]
 
     async def aclose(self) -> None:
         """Close the async connection on delete."""
@@ -146,7 +153,7 @@ def __del__(self) -> None:
             self._s.close()
 
     @property
-    def base_url(self) -> str:
+    def base_url(self) -> str | None:
         """
         Return base url in use for requests to the server.
 
@@ -156,11 +163,11 @@ def base_url(self) -> str:
         return self._base_url
 
     @base_url.setter
-    def base_url(self, value: str) -> None:
+    def base_url(self, value: str | None) -> None:
         self._base_url = value
 
     @property
-    def timeout(self) -> int:
+    def timeout(self) -> int | None:
         """
         Return timeout in use for request to the server.
 
@@ -170,11 +177,11 @@ def timeout(self) -> int:
         return self._timeout
 
     @timeout.setter
-    def timeout(self, value: int) -> None:
+    def timeout(self, value: int | None) -> None:
         self._timeout = value
 
     @property
-    def verify(self) -> bool:
+    def verify(self) -> bool | str:
         """
         Return verify in use for request to the server.
 
@@ -184,11 +191,11 @@ def verify(self) -> bool:
         return self._verify
 
     @verify.setter
-    def verify(self, value: bool) -> None:
+    def verify(self, value: bool | str) -> None:
         self._verify = value
 
     @property
-    def cert(self) -> str | tuple:
+    def cert(self) -> str | tuple | None:
         """
         Return client certificates in use for request to the server.
 
@@ -198,7 +205,7 @@ def cert(self) -> str | tuple:
         return self._cert
 
     @cert.setter
-    def cert(self, value: str | tuple) -> None:
+    def cert(self, value: str | tuple | None) -> None:
         self._cert = value
 
     @property
@@ -216,7 +223,7 @@ def pool_maxsize(self, value: int | None) -> None:
         self._pool_maxsize = value
 
     @property
-    def headers(self) -> dict:
+    def headers(self) -> dict | None:
         """
         Return header request to the server.
 
@@ -226,7 +233,7 @@ def headers(self) -> dict:
         return self._headers
 
     @headers.setter
-    def headers(self, value: dict) -> None:
+    def headers(self, value: dict | None) -> None:
         self._headers = value or {}
 
     def param_headers(self, key: str) -> str | None:
@@ -238,7 +245,7 @@ def param_headers(self, key: str) -> str | None:
         :returns: If the header parameters exist, return its value.
         :rtype: str
         """
-        return self.headers.get(key)
+        return (self.headers or {}).get(key)
 
     def clean_headers(self) -> None:
         """Clear header parameters."""
@@ -264,6 +271,9 @@ def add_param_headers(self, key: str, value: str) -> None:
         :param value: Value to be added.
         :type value: str
         """
+        if self.headers is None:
+            self.headers = {}
+
         self.headers[key] = value
 
     def del_param_headers(self, key: str) -> None:
@@ -273,9 +283,12 @@ def del_param_headers(self, key: str) -> None:
         :param key: Key of the header parameters.
         :type key: str
         """
+        if self.headers is None:
+            return
+
         self.headers.pop(key, None)
 
-    def raw_get(self, path: str, **kwargs: dict) -> Response:
+    def raw_get(self, path: str, **kwargs: Any) -> Response:  # noqa: ANN401
         """
         Submit get request to the path.
 
@@ -287,6 +300,9 @@ def raw_get(self, path: str, **kwargs: dict) -> Response:
         :rtype: Response
         :raises KeycloakConnectionError: HttpError Can't connect to server.
         """
+        if self.base_url is None:
+            msg = "Unable to perform GET call with base_url missing."
+            raise AttributeError(msg)
         try:
             return self._s.get(
                 urljoin(self.base_url, path),
@@ -300,7 +316,7 @@ def raw_get(self, path: str, **kwargs: dict) -> Response:
             msg = "Can't connect to server"
             raise KeycloakConnectionError(msg) from e
 
-    def raw_post(self, path: str, data: dict, **kwargs: dict) -> Response:
+    def raw_post(self, path: str, data: dict | str | MultipartEncoder, **kwargs: Any) -> Response:  # noqa: ANN401
         """
         Submit post request to the path.
 
@@ -314,6 +330,9 @@ def raw_post(self, path: str, data: dict, **kwargs: dict) -> Response:
         :rtype: Response
         :raises KeycloakConnectionError: HttpError Can't connect to server.
         """
+        if self.base_url is None:
+            msg = "Unable to perform POST call with base_url missing."
+            raise AttributeError(msg)
         try:
             return self._s.post(
                 urljoin(self.base_url, path),
@@ -328,7 +347,7 @@ def raw_post(self, path: str, data: dict, **kwargs: dict) -> Response:
             msg = "Can't connect to server"
             raise KeycloakConnectionError(msg) from e
 
-    def raw_put(self, path: str, data: dict, **kwargs: dict) -> Response:
+    def raw_put(self, path: str, data: dict | str, **kwargs: Any) -> Response:  # noqa: ANN401
         """
         Submit put request to the path.
 
@@ -342,6 +361,10 @@ def raw_put(self, path: str, data: dict, **kwargs: dict) -> Response:
         :rtype: Response
         :raises KeycloakConnectionError: HttpError Can't connect to server.
         """
+        if self.base_url is None:
+            msg = "Unable to perform PUT call with base_url missing."
+            raise AttributeError(msg)
+
         try:
             return self._s.put(
                 urljoin(self.base_url, path),
@@ -356,7 +379,7 @@ def raw_put(self, path: str, data: dict, **kwargs: dict) -> Response:
             msg = "Can't connect to server"
             raise KeycloakConnectionError(msg) from e
 
-    def raw_delete(self, path: str, data: dict | None = None, **kwargs: dict) -> Response:
+    def raw_delete(self, path: str, data: dict | None = None, **kwargs: Any) -> Response:  # noqa: ANN401
         """
         Submit delete request to the path.
 
@@ -370,6 +393,10 @@ def raw_delete(self, path: str, data: dict | None = None, **kwargs: dict) -> Res
         :rtype: Response
         :raises KeycloakConnectionError: HttpError Can't connect to server.
         """
+        if self.base_url is None:
+            msg = "Unable to perform DELETE call with base_url missing."
+            raise AttributeError(msg)
+
         try:
             return self._s.delete(
                 urljoin(self.base_url, path),
@@ -384,7 +411,7 @@ def raw_delete(self, path: str, data: dict | None = None, **kwargs: dict) -> Res
             msg = "Can't connect to server"
             raise KeycloakConnectionError(msg) from e
 
-    async def a_raw_get(self, path: str, **kwargs: dict) -> AsyncResponse:
+    async def a_raw_get(self, path: str, **kwargs: Any) -> AsyncResponse:  # noqa: ANN401
         """
         Submit get request to the path.
 
@@ -396,6 +423,10 @@ async def a_raw_get(self, path: str, **kwargs: dict) -> AsyncResponse:
         :rtype: Response
         :raises KeycloakConnectionError: HttpError Can't connect to server.
         """
+        if self.base_url is None:
+            msg = "Unable to perform GET call with base_url missing."
+            raise AttributeError(msg)
+
         try:
             return await self.async_s.get(
                 urljoin(self.base_url, path),
@@ -407,7 +438,12 @@ async def a_raw_get(self, path: str, **kwargs: dict) -> AsyncResponse:
             msg = "Can't connect to server"
             raise KeycloakConnectionError(msg) from e
 
-    async def a_raw_post(self, path: str, data: dict, **kwargs: dict) -> AsyncResponse:
+    async def a_raw_post(
+        self,
+        path: str,
+        data: dict | str | MultipartEncoder,
+        **kwargs: Any,  # noqa: ANN401
+    ) -> AsyncResponse:
         """
         Submit post request to the path.
 
@@ -421,6 +457,10 @@ async def a_raw_post(self, path: str, data: dict, **kwargs: dict) -> AsyncRespon
         :rtype: Response
         :raises KeycloakConnectionError: HttpError Can't connect to server.
         """
+        if self.base_url is None:
+            msg = "Unable to perform POST call with base_url missing."
+            raise AttributeError(msg)
+
         try:
             return await self.async_s.request(
                 method="POST",
@@ -434,7 +474,7 @@ async def a_raw_post(self, path: str, data: dict, **kwargs: dict) -> AsyncRespon
             msg = "Can't connect to server"
             raise KeycloakConnectionError(msg) from e
 
-    async def a_raw_put(self, path: str, data: dict, **kwargs: dict) -> AsyncResponse:
+    async def a_raw_put(self, path: str, data: dict | str, **kwargs: Any) -> AsyncResponse:  # noqa: ANN401
         """
         Submit put request to the path.
 
@@ -448,6 +488,10 @@ async def a_raw_put(self, path: str, data: dict, **kwargs: dict) -> AsyncRespons
         :rtype: Response
         :raises KeycloakConnectionError: HttpError Can't connect to server.
         """
+        if self.base_url is None:
+            msg = "Unable to perform PUT call with base_url missing."
+            raise AttributeError(msg)
+
         try:
             return await self.async_s.put(
                 urljoin(self.base_url, path),
@@ -464,7 +508,7 @@ async def a_raw_delete(
         self,
         path: str,
         data: dict | None = None,
-        **kwargs: dict,
+        **kwargs: Any,  # noqa: ANN401
     ) -> AsyncResponse:
         """
         Submit delete request to the path.
@@ -479,6 +523,10 @@ async def a_raw_delete(
         :rtype: Response
         :raises KeycloakConnectionError: HttpError Can't connect to server.
         """
+        if self.base_url is None:
+            msg = "Unable to perform DELETE call with base_url missing."
+            raise AttributeError(msg)
+
         try:
             return await self.async_s.request(
                 method="DELETE",
@@ -493,7 +541,7 @@ async def a_raw_delete(
             raise KeycloakConnectionError(msg) from e
 
     @staticmethod
-    def _prepare_httpx_request_content(data: dict | str | None) -> dict:
+    def _prepare_httpx_request_content(data: dict | str | None | MultipartEncoder) -> dict:
         """
         Create the correct request content kwarg to `httpx.AsyncClient.request()`.
 
@@ -504,9 +552,13 @@ def _prepare_httpx_request_content(data: dict | str | None) -> dict:
         :returns: A dict mapping the correct kwarg to the request content
         :rtype: dict
         """
+        if isinstance(data, MultipartEncoder):
+            return {"content": data.to_string()}
+
         if isinstance(data, str):
             # Note: this could also accept bytes, Iterable[bytes], or AsyncIterable[bytes]
             return {"content": data}
+
         return {"data": data}
 
     @staticmethod