typing: fix HeaderValueMatcher typing

csernazs · csernazs · commit 3b84156fc598 · 2023-01-21T15:54:12.000+01:00
Replace HeaderValueMatcher with a callable as it impplements the callable
protocol and users can provide a callable also, as it is described in the
howto.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -2,6 +2,22 @@
 Release Notes
 =============
 
+.. _Release Notes_1.0.6-12:
+
+1.0.6-12
+========
+
+.. _Release Notes_1.0.6-12_Bug Fixes:
+
+Bug Fixes
+---------
+
+- Type hinting for header_value_matcher has been fixed. From now, specifying a
+  callable as `Callable[[str, Optional[str], str], bool]` will be accepted
+  also. Providing a `HeaderValueMatcher` object will be also accepted as
+  before, as it provides the same callable signature.
+
+
 .. _Release Notes_1.0.6:
 
 1.0.6
diff --git a/pytest_httpserver/httpserver.py b/pytest_httpserver/httpserver.py
@@ -37,6 +37,8 @@
     Iterable[Tuple[str, Union[str, int]]],
 ]
 
+HVMATCHER_T = Callable[[str, Optional[str], str], bool]
+
 
 class Undefined:
     def __repr__(self):
@@ -289,6 +291,13 @@ class RequestMatcher:
         specified in the request. If multiple values specified for a given key, the first
         value will be used. If multiple values needed to be handled, use ``MultiDict``
         object from werkzeug.
+    :param header_value_matcher: :py:class:`HeaderValueMatcher` that matches
+        values of headers, or a ``Callable[[str, Optional[str], str], bool]``
+        receiving the header key (from `headers`), header value (or `None`) and the expected
+        value (from `headers`) and should return ``True`` if the header matches, ``False`` otherwise.
+    :param json: a python object (eg. a dict) whose value will be compared to the request body after it
+        is loaded as json. If load fails, this matcher will be failed also. *Content-Type* is not checked.
+        If that's desired, add it to the headers parameter.
     """
 
     def __init__(
@@ -299,7 +308,7 @@ def __init__(
         data_encoding: str = "utf-8",
         headers: Optional[Mapping[str, str]] = None,
         query_string: Union[None, QueryMatcher, str, bytes, Mapping] = None,
-        header_value_matcher: Optional[HeaderValueMatcher] = None,
+        header_value_matcher: Optional[HVMATCHER_T] = None,
         json: Any = UNDEFINED,
     ):
 
@@ -322,7 +331,10 @@ def __init__(
         self.data = data
         self.data_encoding = data_encoding
 
-        self.header_value_matcher = HeaderValueMatcher() if header_value_matcher is None else header_value_matcher
+        self.header_value_matcher: HVMATCHER_T = HeaderValueMatcher()
+
+        if header_value_matcher is not None:
+            self.header_value_matcher = header_value_matcher
 
     def __repr__(self):
         """
@@ -939,7 +951,7 @@ def expect_request(
         data_encoding: str = "utf-8",
         headers: Optional[Mapping[str, str]] = None,
         query_string: Union[None, QueryMatcher, str, bytes, Mapping] = None,
-        header_value_matcher: Optional[HeaderValueMatcher] = None,
+        header_value_matcher: Optional[HVMATCHER_T] = None,
         handler_type: HandlerType = HandlerType.PERMANENT,
         json: Any = UNDEFINED,
     ) -> RequestHandler:
@@ -973,7 +985,10 @@ def expect_request(
             specified in the request. If multiple values specified for a given key, the first
             value will be used. If multiple values needed to be handled, use ``MultiDict``
             object from werkzeug.
-        :param header_value_matcher: :py:class:`HeaderValueMatcher` that matches values of headers.
+        :param header_value_matcher: :py:class:`HeaderValueMatcher` that matches
+            values of headers, or a ``Callable[[str, Optional[str], str], bool]``
+            receiving the header key (from `headers`), header value (or `None`) and the expected
+            value (from `headers`) and should return ``True`` if the header matches, ``False`` otherwise.
         :param handler_type: type of handler
         :param json: a python object (eg. a dict) whose value will be compared to the request body after it
             is loaded as json. If load fails, this matcher will be failed also. *Content-Type* is not checked.
@@ -1011,7 +1026,7 @@ def expect_oneshot_request(
         data_encoding: str = "utf-8",
         headers: Optional[Mapping[str, str]] = None,
         query_string: Union[None, QueryMatcher, str, bytes, Mapping] = None,
-        header_value_matcher: Optional[HeaderValueMatcher] = None,
+        header_value_matcher: Optional[HVMATCHER_T] = None,
         json: Any = UNDEFINED,
     ) -> RequestHandler:
         """
@@ -1033,7 +1048,10 @@ def expect_oneshot_request(
             specified in the request. If multiple values specified for a given key, the first
             value will be used. If multiple values needed to be handled, use ``MultiDict``
             object from werkzeug.
-        :param header_value_matcher: :py:class:`HeaderValueMatcher` that matches values of headers.
+        :param header_value_matcher: :py:class:`HeaderValueMatcher` that matches
+            values of headers, or a ``Callable[[str, Optional[str], str], bool]``
+            receiving the header key (from `headers`), header value (or `None`) and the expected
+            value (from `headers`) and should return ``True`` if the header matches, ``False`` otherwise.
         :param json: a python object (eg. a dict) whose value will be compared to the request body after it
             is loaded as json. If load fails, this matcher will be failed also. *Content-Type* is not checked.
             If that's desired, add it to the headers parameter.
@@ -1063,7 +1081,7 @@ def expect_ordered_request(
         data_encoding: str = "utf-8",
         headers: Optional[Mapping[str, str]] = None,
         query_string: Union[None, QueryMatcher, str, bytes, Mapping] = None,
-        header_value_matcher: Optional[HeaderValueMatcher] = None,
+        header_value_matcher: Optional[HVMATCHER_T] = None,
         json: Any = UNDEFINED,
     ) -> RequestHandler:
         """
@@ -1085,7 +1103,10 @@ def expect_ordered_request(
             specified in the request. If multiple values specified for a given key, the first
             value will be used. If multiple values needed to be handled, use ``MultiDict``
             object from werkzeug.
-        :param header_value_matcher: :py:class:`HeaderValueMatcher` that matches values of headers.
+        :param header_value_matcher: :py:class:`HeaderValueMatcher` that matches
+            values of headers, or a ``Callable[[str, Optional[str], str], bool]``
+            receiving the header key (from `headers`), header value (or `None`) and the expected
+            value (from `headers`) and should return ``True`` if the header matches, ``False`` otherwise.
         :param json: a python object (eg. a dict) whose value will be compared to the request body after it
             is loaded as json. If load fails, this matcher will be failed also. *Content-Type* is not checked.
             If that's desired, add it to the headers parameter.
diff --git a/releasenotes/notes/headervaluematcher-type-hinting-fix-f19e7a4d48b0a1d8.yaml b/releasenotes/notes/headervaluematcher-type-hinting-fix-f19e7a4d48b0a1d8.yaml
@@ -0,0 +1,6 @@
+fixes:
+  - |
+    Type hinting for header_value_matcher has been fixed. From now, specifying a
+    callable as ``Callable[[str, Optional[str], str], bool]`` will be accepted
+    also. Providing a ``HeaderValueMatcher`` object will be also accepted as
+    before, as it provides the same callable signature.
diff --git a/tests/examples/test_howto_case_insensitive_matcher.py b/tests/examples/test_howto_case_insensitive_matcher.py
@@ -1,9 +1,14 @@
+from typing import Optional
+
 import requests
 
 from pytest_httpserver import HTTPServer
 
 
-def case_insensitive_matcher(header_name: str, actual: str, expected: str) -> bool:
+def case_insensitive_matcher(header_name: str, actual: Optional[str], expected: str) -> bool:
+    if actual is None:
+        return False
+
     if header_name == "X-Foo":
         return actual.lower() == expected.lower()
     else:
diff --git a/tests/examples/test_howto_header_value_matcher.py b/tests/examples/test_howto_header_value_matcher.py
@@ -1,10 +1,15 @@
+from typing import Optional
+
 import requests
 
 from pytest_httpserver import HeaderValueMatcher
 from pytest_httpserver import HTTPServer
 
 
-def case_insensitive_compare(actual: str, expected: str) -> bool:
+def case_insensitive_compare(actual: Optional[str], expected: str) -> bool:
+    # actual is `None` if it is not specified
+    if actual is None:
+        return False
     return actual.lower() == expected.lower()
 
 
