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

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.

2 files changed, 38 insertions, 2 deletions

diff --git a/gitlab/_backends/protocol.py b/gitlab/_backends/protocol.py
new file mode 100644
index 0000000..f89740b
--- /dev/null
+++ 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
index 4ea23a7..fd40baa 100644
--- a/gitlab/_backends/requests_backend.py
+++ b/gitlab/_backends/requests_backend.py
@@ -6,8 +6,10 @@ import requests
 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 @@ class RequestsResponse:
         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()