feat(backends): use PEP544 protocols for structural subtyping (#2442)

Liora Milbaum · web-flow · commit 4afeaff0361a · 2023-02-12T13:14:49.000+01:00
The purpose of this change is to track API changes described in https://github.com/python-gitlab/python-gitlab/blob/main/docs/api-levels.rst, for example, for package versioning and breaking change announcements in case of protocol changes. This is MVP implementation to be used by #2435.
diff --git a/gitlab/_backends/protocol.py b/gitlab/_backends/protocol.py
@@ -0,0 +1,34 @@
+import abc
+import sys
+from typing import Any, Dict, Optional, Union
+
+import requests
+from requests_toolbelt.multipart.encoder import MultipartEncoder  # type: ignore
+
+if sys.version_info >= (3, 8):
+    from typing import Protocol
+else:
+    from typing_extensions import Protocol
+
+
+class BackendResponse(Protocol):
+    @abc.abstractmethod
+    def __init__(self, response: requests.Response) -> None:
+        ...
+
+
+class Backend(Protocol):
+    @abc.abstractmethod
+    def http_request(
+        self,
+        method: str,
+        url: str,
+        json: Optional[Union[Dict[str, Any], bytes]],
+        data: Optional[Union[Dict[str, Any], MultipartEncoder]],
+        params: Optional[Any],
+        timeout: Optional[float],
+        verify: Optional[Union[bool, str]],
+        stream: Optional[bool],
+        **kwargs: Any,
+    ) -> BackendResponse:
+        ...
diff --git a/gitlab/_backends/requests_backend.py b/gitlab/_backends/requests_backend.py
@@ -6,8 +6,10 @@
 from requests.structures import CaseInsensitiveDict
 from requests_toolbelt.multipart.encoder import MultipartEncoder  # type: ignore
 
+from . import protocol
 
-class RequestsResponse:
+
+class RequestsResponse(protocol.BackendResponse):
     def __init__(self, response: requests.Response) -> None:
         self._response: requests.Response = response
 
@@ -35,7 +37,7 @@ def json(self) -> Any:
         return self._response.json()
 
 
-class RequestsBackend:
+class RequestsBackend(protocol.Backend):
     def __init__(self, session: Optional[requests.Session] = None) -> None:
         self._client: requests.Session = session or requests.Session()
 
