Merge pull request #226 from noirbizarre/style/typing

Typing analysis and public type aliases
jamielennox · May 15, 2023 · fc19034 · fc19034
2 parents 799ac71 + fb0ae61
commit fc19034
Show file tree

Hide file tree

Showing 11 changed files with 157 additions and 75 deletions.
diff --git a/.github/workflows/flake8.yaml → .github/workflows/lint.yaml b/.github/workflows/flake8.yaml → .github/workflows/lint.yaml
@@ -20,6 +20,10 @@ jobs:
         python -m pip install --upgrade pip
         pip install -r requirements.txt
         pip install flake8
+        pip install -r typing-requirements.txt
 
     - name: Lint with flake8
       run: flake8 requests_mock tests
+
+    - name: Lint type hinting with MyPy
+      run: mypy requests_mock
diff --git a/releasenotes/notes/public-type-aliases-f389506932adfa2c.yaml b/releasenotes/notes/public-type-aliases-f389506932adfa2c.yaml
@@ -0,0 +1,14 @@
+---
+features:
+  - |
+    Exposes some public type aliases (for type hinting only, they can't be instanciated) 
+    for the types intended to be used by `requests_mock` users. 
+    The following types are now exposed:
+    - `requests_mock.Context` used in callbacks
+    - `requests_mock.Request` used in callbacks, which is a `requests.PreparedRequest` proxy.
+    - `requests_mock.Callback[T]` which is the callbacks type.
+
+fixes:
+  - |
+    Some typing inconsistencies have been fixed. 
+    Especially for `request` object in signatures which is in fact a `requests_mock.Request` object.
diff --git a/requests_mock/__init__.pyi b/requests_mock/__init__.pyi
@@ -1,7 +1,33 @@
 # Stubs for requests_mock
 
-from requests_mock.adapter import ANY as ANY, Adapter as Adapter
-from requests_mock.exceptions import MockException as MockException, NoMockAddress as NoMockAddress
-from requests_mock.mocker import DELETE as DELETE, GET as GET, HEAD as HEAD, Mocker as Mocker, MockerCore as MockerCore, OPTIONS as OPTIONS, PATCH as PATCH, POST as POST, PUT as PUT, mock as mock
-from requests_mock.request import _RequestObjectProxy as _RequestObjectProxy
-from requests_mock.response import CookieJar as CookieJar, create_response as create_response
+from requests_mock.adapter import (
+    ANY as ANY, 
+    Adapter as Adapter, 
+    Callback as Callback, 
+    AdditionalMatcher as AdditionalMatcher,
+)
+from requests_mock.exceptions import (
+    MockException as MockException, 
+    NoMockAddress as NoMockAddress,
+)
+from requests_mock.mocker import (
+    DELETE as DELETE, 
+    GET as GET, 
+    HEAD as HEAD,
+    Mocker as Mocker,
+    MockerCore as MockerCore,
+    OPTIONS as OPTIONS,
+    PATCH as PATCH,
+    POST as POST,
+    PUT as PUT,
+    mock as mock,
+)
+from requests_mock.request import (
+    Request as Request,
+    _RequestObjectProxy as _RequestObjectProxy,  # For backward compatibility
+)
+from requests_mock.response import (
+    CookieJar as CookieJar,
+    create_response as create_response,
+    Context as Context,
+)
diff --git a/requests_mock/adapter.pyi b/requests_mock/adapter.pyi
@@ -2,24 +2,29 @@
 
 from http.cookiejar import CookieJar
 from io import IOBase
-from typing import Any, Callable, Dict, List, NewType, Optional, Pattern, Type, Union
+from typing import Any, Callable, Dict, List, NewType, Optional, Pattern, Type, TypeVar, Union
 
-from requests import Request, Response
+from requests import Response
 from requests.adapters import BaseAdapter
-from requests.packages.urllib3.response import HTTPResponse
+from urllib3.response import HTTPResponse
 
-from requests_mock.request import _RequestObjectProxy
-from requests_mock.response import _Context
+from requests_mock.request import Request
+from requests_mock.response import Context
 
 AnyMatcher = NewType("AnyMatcher", object)
 
 ANY: AnyMatcher = ...
 
+T = TypeVar('T')
+Callback = Callable[[Request, Context], T]
+Matcher = Callable[[Request], Optional[Response]]
+AdditionalMatcher = Callable[[Request], bool]
+
 class _RequestHistoryTracker:
-    request_history: List[_RequestObjectProxy] = ...
+    request_history: List[Request] = ...
     def __init__(self) -> None: ...
     @property
-    def last_request(self) -> Optional[_RequestObjectProxy]: ...
+    def last_request(self) -> Optional[Request]: ...
     @property
     def called(self) -> bool: ...
     @property
@@ -30,9 +35,19 @@ class _RequestHistoryTracker:
 class _RunRealHTTP(Exception): ...
 
 class _Matcher(_RequestHistoryTracker):
-    def __init__(self, method: Any, url: Any, responses: Any, complete_qs: Any, request_headers: Any, additional_matcher: Any, real_http: Any, case_sensitive: Any) -> None: ...
+    def __init__(
+        self, 
+        method: Any, 
+        url: Any, 
+        responses: Any, 
+        complete_qs: Any, 
+        request_headers: Any, 
+        additional_matcher: AdditionalMatcher, 
+        real_http: Any, 
+        case_sensitive: Any
+    ) -> None: ...
     def __call__(self, request: Request) -> Optional[Response]: ...
-
+    
 class Adapter(BaseAdapter, _RequestHistoryTracker):
     def __init__(self, case_sensitive: bool = ...) -> None: ...
     def register_uri(
@@ -47,14 +62,14 @@ class Adapter(BaseAdapter, _RequestHistoryTracker):
         reason: str = ...,
         headers: Dict[str, str] = ...,
         cookies: Union[CookieJar, Dict[str, str]] = ...,
-        json: Union[Any, Callable[[_RequestObjectProxy, _Context], Any]] = ...,
-        text: Union[str, Callable[[_RequestObjectProxy, _Context], str]] = ...,
-        content: Union[bytes, Callable[[_RequestObjectProxy, _Context], bytes]] = ...,
-        body: Union[IOBase, Callable[[_RequestObjectProxy, _Context], IOBase]] = ...,
+        json: Union[Any, Callback[Any]] = ...,
+        text: Union[str, Callback[str]] = ...,
+        content: Union[bytes, Callback[bytes]] = ...,
+        body: Union[IOBase, Callback[IOBase]] = ...,
         raw: HTTPResponse = ...,
         exc: Union[Exception, Type[Exception]] = ...,
-        additional_matcher: Callable[[_RequestObjectProxy], bool] = ...,
+        additional_matcher: AdditionalMatcher = ...,
         **kwargs: Any
     ) -> _Matcher: ...
-    def add_matcher(self, matcher: Callable[[Request], Optional[Response]]) -> None: ...
-    def reset(self) -> None: ...
+    def add_matcher(self, matcher: Matcher) -> None: ...
+    def reset(self) -> None: ...
diff --git a/requests_mock/contrib/_pytest_plugin.pyi b/requests_mock/contrib/_pytest_plugin.pyi
@@ -0,0 +1,6 @@
+
+from typing import Literal, Optional, Union
+
+
+_case_type = Optional[str]
+_case_default = Union[Literal['false'], Literal[False]]
diff --git a/requests_mock/mocker.pyi b/requests_mock/mocker.pyi
@@ -5,12 +5,11 @@ from http.cookiejar import CookieJar
 from io import IOBase
 from typing import Any, Callable, Dict, List, Optional, Pattern, Type, TypeVar, Union
 
-from requests import Request, Response, Session
-from requests.packages.urllib3.response import HTTPResponse
+from requests import Response, Session
+from urllib3.response import HTTPResponse
 
-from requests_mock.adapter import AnyMatcher, _Matcher
-from requests_mock.request import _RequestObjectProxy
-from requests_mock.response import _Context
+from requests_mock.adapter import AnyMatcher, _Matcher, Callback, AdditionalMatcher
+from requests_mock.request import Request
 
 DELETE: str
 GET: str
@@ -27,9 +26,9 @@ class MockerCore:
     def stop(self) -> None: ...
     def add_matcher(self, matcher: Callable[[Request], Optional[Response]]) -> None: ...
     @property
-    def request_history(self) -> List[_RequestObjectProxy]: ...
+    def request_history(self) -> List[Request]: ...
     @property
-    def last_request(self) -> Optional[_RequestObjectProxy]: ...
+    def last_request(self) -> Optional[Request]: ...
     @property
     def called(self) -> bool: ...
     @property
@@ -51,13 +50,13 @@ class MockerCore:
       reason: str = ...,
       headers: Dict[str, str] = ...,
       cookies: Union[CookieJar, Dict[str, str]] = ...,
-      json: Union[Any, Callable[[_RequestObjectProxy, _Context], Any]] = ...,
-      text: Union[str, Callable[[_RequestObjectProxy, _Context], str]] = ...,
-      content: Union[bytes, Callable[[_RequestObjectProxy, _Context], bytes]] = ...,
-      body: Union[IOBase, Callable[[_RequestObjectProxy, _Context], IOBase]] = ...,
+      json: Union[Any, Callback[Any]] = ...,
+      text: Union[str, Callback[str]] = ...,
+      content: Union[bytes, Callback[bytes]] = ...,
+      body: Union[IOBase, Callback[IOBase]] = ...,
       raw: HTTPResponse = ...,
       exc: Union[Exception, Type[Exception]] = ...,
-      additional_matcher: Callable[[_RequestObjectProxy], bool] = ...,
+      additional_matcher: AdditionalMatcher = ...,
       json_encoder: Optional[Type[JSONEncoder]] = ...,
       **kwargs: Any,
     ) -> _Matcher: ...
@@ -74,13 +73,13 @@ class MockerCore:
       reason: str = ...,
       headers: Dict[str, str] = ...,
       cookies: Union[CookieJar, Dict[str, str]] = ...,
-      json: Union[Any, Callable[[_RequestObjectProxy, _Context], Any]] = ...,
-      text: Union[str, Callable[[_RequestObjectProxy, _Context], str]] = ...,
-      content: Union[bytes, Callable[[_RequestObjectProxy, _Context], bytes]] = ...,
-      body: Union[IOBase, Callable[[_RequestObjectProxy, _Context], IOBase]] = ...,
+      json: Union[Any, Callback[Any]] = ...,
+      text: Union[str, Callback[str]] = ...,
+      content: Union[bytes, Callback[bytes]] = ...,
+      body: Union[IOBase, Callback[IOBase]] = ...,
       raw: HTTPResponse = ...,
       exc: Union[Exception, Type[Exception]] = ...,
-      additional_matcher: Callable[[_RequestObjectProxy], bool] = ...,
+      additional_matcher: AdditionalMatcher = ...,
       json_encoder: Optional[Type[JSONEncoder]] = ...,
       **kwargs: Any,
     ) -> _Matcher: ...
@@ -96,13 +95,13 @@ class MockerCore:
       reason: str = ...,
       headers: Dict[str, str] = ...,
       cookies: Union[CookieJar, Dict[str, str]] = ...,
-      json: Union[Any, Callable[[_RequestObjectProxy, _Context], Any]] = ...,
-      text: Union[str, Callable[[_RequestObjectProxy, _Context], str]] = ...,
-      content: Union[bytes, Callable[[_RequestObjectProxy, _Context], bytes]] = ...,
-      body: Union[IOBase, Callable[[_RequestObjectProxy, _Context], IOBase]] = ...,
+      json: Union[Any, Callback[Any]] = ...,
+      text: Union[str, Callback[str]] = ...,
+      content: Union[bytes, Callback[bytes]] = ...,
+      body: Union[IOBase, Callback[IOBase]] = ...,
       raw: HTTPResponse = ...,
       exc: Union[Exception, Type[Exception]] = ...,
-      additional_matcher: Callable[[_RequestObjectProxy], bool] = ...,
+      additional_matcher: AdditionalMatcher = ...,
       json_encoder: Optional[Type[JSONEncoder]] = ...,
       **kwargs: Any,
     ) -> _Matcher: ...
@@ -118,13 +117,13 @@ class MockerCore:
       reason: str = ...,
       headers: Dict[str, str] = ...,
       cookies: Union[CookieJar, Dict[str, str]] = ...,
-      json: Union[Any, Callable[[_RequestObjectProxy, _Context], Any]] = ...,
-      text: Union[str, Callable[[_RequestObjectProxy, _Context], str]] = ...,
-      content: Union[bytes, Callable[[_RequestObjectProxy, _Context], bytes]] = ...,
-      body: Union[IOBase, Callable[[_RequestObjectProxy, _Context], IOBase]] = ...,
+      json: Union[Any, Callback[Any]] = ...,
+      text: Union[str, Callback[str]] = ...,
+      content: Union[bytes, Callback[bytes]] = ...,
+      body: Union[IOBase, Callback[IOBase]] = ...,
       raw: HTTPResponse = ...,
       exc: Union[Exception, Type[Exception]] = ...,
-      additional_matcher: Callable[[_RequestObjectProxy], bool] = ...,
+      additional_matcher: AdditionalMatcher = ...,
       json_encoder: Optional[Type[JSONEncoder]] = ...,
       **kwargs: Any,
     ) -> _Matcher: ...
@@ -140,13 +139,13 @@ class MockerCore:
       reason: str = ...,
       headers: Dict[str, str] = ...,
       cookies: Union[CookieJar, Dict[str, str]] = ...,
-      json: Union[Any, Callable[[_RequestObjectProxy, _Context], Any]] = ...,
-      text: Union[str, Callable[[_RequestObjectProxy, _Context], str]] = ...,
-      content: Union[bytes, Callable[[_RequestObjectProxy, _Context], bytes]] = ...,
-      body: Union[IOBase, Callable[[_RequestObjectProxy, _Context], IOBase]] = ...,
+      json: Union[Any, Callback[Any]] = ...,
+      text: Union[str, Callback[str]] = ...,
+      content: Union[bytes, Callback[bytes]] = ...,
+      body: Union[IOBase, Callback[IOBase]] = ...,
       raw: HTTPResponse = ...,
       exc: Union[Exception, Type[Exception]] = ...,
-      additional_matcher: Callable[[_RequestObjectProxy], bool] = ...,
+      additional_matcher: AdditionalMatcher = ...,
       json_encoder: Optional[Type[JSONEncoder]] = ...,
       **kwargs: Any,
     ) -> _Matcher: ...
@@ -162,13 +161,13 @@ class MockerCore:
       reason: str = ...,
       headers: Dict[str, str] = ...,
       cookies: Union[CookieJar, Dict[str, str]] = ...,
-      json: Union[Any, Callable[[_RequestObjectProxy, _Context], Any]] = ...,
-      text: Union[str, Callable[[_RequestObjectProxy, _Context], str]] = ...,
-      content: Union[bytes, Callable[[_RequestObjectProxy, _Context], bytes]] = ...,
-      body: Union[IOBase, Callable[[_RequestObjectProxy, _Context], IOBase]] = ...,
+      json: Union[Any, Callback[Any]] = ...,
+      text: Union[str, Callback[str]] = ...,
+      content: Union[bytes, Callback[bytes]] = ...,
+      body: Union[IOBase, Callback[IOBase]] = ...,
       raw: HTTPResponse = ...,
       exc: Union[Exception, Type[Exception]] = ...,
-      additional_matcher: Callable[[_RequestObjectProxy], bool] = ...,
+      additional_matcher: AdditionalMatcher = ...,
       json_encoder: Optional[Type[JSONEncoder]] = ...,
       **kwargs: Any,
     ) -> _Matcher: ...
@@ -184,13 +183,13 @@ class MockerCore:
       reason: str = ...,
       headers: Dict[str, str] = ...,
       cookies: Union[CookieJar, Dict[str, str]] = ...,
-      json: Union[Any, Callable[[_RequestObjectProxy, _Context], Any]] = ...,
-      text: Union[str, Callable[[_RequestObjectProxy, _Context], str]] = ...,
-      content: Union[bytes, Callable[[_RequestObjectProxy, _Context], bytes]] = ...,
-      body: Union[IOBase, Callable[[_RequestObjectProxy, _Context], IOBase]] = ...,
+      json: Union[Any, Callback[Any]] = ...,
+      text: Union[str, Callback[str]] = ...,
+      content: Union[bytes, Callback[bytes]] = ...,
+      body: Union[IOBase, Callback[IOBase]] = ...,
       raw: HTTPResponse = ...,
       exc: Union[Exception, Type[Exception]] = ...,
-      additional_matcher: Callable[[_RequestObjectProxy], bool] = ...,
+      additional_matcher: AdditionalMatcher = ...,
       json_encoder: Optional[Type[JSONEncoder]] = ...,
       **kwargs: Any,
     ) -> _Matcher: ...
@@ -206,13 +205,13 @@ class MockerCore:
       reason: str = ...,
       headers: Dict[str, str] = ...,
       cookies: Union[CookieJar, Dict[str, str]] = ...,
-      json: Union[Any, Callable[[_RequestObjectProxy, _Context], Any]] = ...,
-      text: Union[str, Callable[[_RequestObjectProxy, _Context], str]] = ...,
-      content: Union[bytes, Callable[[_RequestObjectProxy, _Context], bytes]] = ...,
-      body: Union[IOBase, Callable[[_RequestObjectProxy, _Context], IOBase]] = ...,
+      json: Union[Any, Callback[Any]] = ...,
+      text: Union[str, Callback[str]] = ...,
+      content: Union[bytes, Callback[bytes]] = ...,
+      body: Union[IOBase, Callback[IOBase]] = ...,
       raw: HTTPResponse = ...,
       exc: Union[Exception, Type[Exception]] = ...,
-      additional_matcher: Callable[[_RequestObjectProxy], bool] = ...,
+      additional_matcher: AdditionalMatcher = ...,
       json_encoder: Optional[Type[JSONEncoder]] = ...,
       **kwargs: Any,
     ) -> _Matcher: ...
@@ -228,13 +227,13 @@ class MockerCore:
       reason: str = ...,
       headers: Dict[str, str] = ...,
       cookies: Union[CookieJar, Dict[str, str]] = ...,
-      json: Union[Any, Callable[[_RequestObjectProxy, _Context], Any]] = ...,
-      text: Union[str, Callable[[_RequestObjectProxy, _Context], str]] = ...,
-      content: Union[bytes, Callable[[_RequestObjectProxy, _Context], bytes]] = ...,
-      body: Union[IOBase, Callable[[_RequestObjectProxy, _Context], IOBase]] = ...,
+      json: Union[Any, Callback[Any]] = ...,
+      text: Union[str, Callback[str]] = ...,
+      content: Union[bytes, Callback[bytes]] = ...,
+      body: Union[IOBase, Callback[IOBase]] = ...,
       raw: HTTPResponse = ...,
       exc: Union[Exception, Type[Exception]] = ...,
-      additional_matcher: Callable[[_RequestObjectProxy], bool] = ...,
+      additional_matcher: AdditionalMatcher = ...,
       json_encoder: Optional[Type[JSONEncoder]] = ...,
       **kwargs: Any,
     ) -> _Matcher: ...

diff --git a/requests_mock/request.pyi b/requests_mock/request.pyi
@@ -35,4 +35,7 @@ class _RequestObjectProxy:
     def text(self) -> str: ...
     def json(self, **kwargs: Any) -> Any: ...
     @property
-    def matcher(self) -> Any: ...
+    def matcher(self) -> Any: ...
+
+
+Request = _RequestObjectProxy
diff --git a/requests_mock/response.pyi b/requests_mock/response.pyi
@@ -1,6 +1,6 @@
 # Stubs for requests_mock.response
 
-from typing import Any, Dict, Optional
+from typing import Any, Dict
 
 import six
 
@@ -34,3 +34,5 @@ class _Context:
 class _MatcherResponse:
     def __init__(self, **kwargs: Any) -> None: ...
     def get_response(self, request: Request) -> Response: ...
+
+Context = _Context
diff --git a/setup.cfg b/setup.cfg
@@ -50,3 +50,7 @@ fixture =
 [entry_points]
 pytest11 =
     requests_mock = requests_mock.contrib._pytest_plugin
+
+[mypy]
+[mypy-fixtures]
+ignore_missing_imports = True