pytest_httpserver 1.0.10__tar.gz → 1.0.11__tar.gz

{pytest_httpserver-1.0.10 → pytest_httpserver-1.0.11}/CHANGES.rst

@@ -2,6 +2,23 @@
 Release Notes
 =============
 
+.. _Release Notes_1.0.11:
+
+1.0.11
+======
+
+.. _Release Notes_1.0.11_New Features:
+
+New Features
+------------
+
+- Hooks API
+
+- New methods added to query for matching requests in the log.
+
+- Threading support to serve requests in parallel
+
+
 .. _Release Notes_1.0.10:
 
 1.0.10

{pytest_httpserver-1.0.10 → pytest_httpserver-1.0.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pytest_httpserver
-Version: 1.0.10
+Version: 1.0.11
 Summary: pytest-httpserver is a httpserver for pytest
 Home-page: https://github.com/csernazs/pytest-httpserver
 License: MIT

{pytest_httpserver-1.0.10 → pytest_httpserver-1.0.11}/doc/api.rst

@@ -24,6 +24,13 @@ RequestHandler
         :inherited-members:
 
 
+RequestMatcher
+~~~~~~~~~~~~~~
+
+    .. autoclass:: RequestMatcher
+        :members:
+
+
 BlockingHTTPServer
 ~~~~~~~~~~~~~~~~~~
 
@@ -93,3 +100,19 @@ by the user.
 
     .. autoclass:: pytest_httpserver.httpserver.RequestHandlerList
         :members:
+
+
+pytest_httpserver.hooks
+-----------------------
+
+.. automodule:: pytest_httpserver.hooks
+
+
+    .. autoclass:: pytest_httpserver.hooks.Chain
+        :members:
+
+    .. autoclass:: pytest_httpserver.hooks.Delay
+        :members:
+
+    .. autoclass:: pytest_httpserver.hooks.Garbage
+        :members:

{pytest_httpserver-1.0.10 → pytest_httpserver-1.0.11}/doc/conf.py

@@ -24,6 +24,7 @@ from typing import Dict
 
 sys.path.insert(0, os.path.abspath(".."))
 
+import doc.patch
 
 # -- General configuration ------------------------------------------------
 
@@ -37,11 +38,12 @@ sys.path.insert(0, os.path.abspath(".."))
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.autosectionlabel",
 ]
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", (None, "python-inv.txt")),
-    "werkzeug": ("https://werkzeug.palletsprojects.com/en/2.1.x", None),
+    "werkzeug": ("https://werkzeug.palletsprojects.com/en/3.0.x", None),
 }
 
 # Add any paths that contain templates here, relative to this directory.
@@ -66,7 +68,7 @@ author = "Zsolt Cserna"
 # built documents.
 #
 # The short X.Y version.
-version = "1.0.10"
+version = "1.0.11"
 # The full version, including alpha/beta/rc tags.
 release = version
 

{pytest_httpserver-1.0.10 → pytest_httpserver-1.0.11}/doc/howto.rst

@@ -512,3 +512,149 @@ Example:
 
 .. literalinclude :: ../tests/examples/test_example_blocking_httpserver.py
    :language: python
+
+
+Querying the log
+----------------
+
+*pytest-httpserver* keeps a log of request-response pairs in a python list. This
+log can be accessed by the ``log`` attibute of the httpserver instance, but
+there are methods made specifically to query the log.
+
+Each of the log querying methods accepts a
+:py:class:`pytest_httpserver.RequestMatcher` object which uses the same matching
+logic which is used by the server itself. Its parameters are the same to the
+parameters specified for the server's `except_request` (and the similar) methods.
+
+The methods for querying:
+
+* :py:meth:`pytest_httpserver.HTTPServer.get_matching_requests_count` returns
+  how many requests are matching in the log as an int
+
+* :py:meth:`pytest_httpserver.HTTPServer.assert_request_made` asserts the given
+  amount of requests are matching in the log. By default it checks for one (1)
+  request but other value can be specified. For example, 0 can be specified to
+  check for requests not made.
+
+* :py:meth:`pytest_httpserver.HTTPServer.iter_matching_requests` is a generator
+  yielding Request-Response tuples of the matching entries in the log. This
+  offers greater flexibility (compared to the other methods)
+
+Example:
+
+.. literalinclude :: ../tests/examples/test_howto_log_querying.py
+   :language: python
+
+
+Serving requests in parallel
+----------------------------
+
+*pytest-httpserver*  serves the request in a single-threaded, blocking way. That
+means that if multiple requests are made to it, those will be served one by one.
+
+There can be cases where parallel processing is required, for those cases
+*pytest-httpserver* allows running a server which start one thread per request
+handler, so the requests are served in parallel way (depending on Global
+Interpreter Lock this is not truly parallel, but from the I/O point of view it
+is).
+
+To set this up, you have two possibilities.
+
+
+Overriding httpserver fixture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+One is to customize how the HTTPServer object is created. This is possible by
+defining the following fixture:
+
+.. code:: python
+
+    @pytest.fixture(scope="session")
+    def make_httpserver() -> Iterable[HTTPServer]:
+        server = HTTPServer(threaded=True)  # set threaded=True to enable thread support
+        server.start()
+        yield server
+        server.clear()
+        if server.is_running():
+            server.stop()
+
+
+This will override the ``httpserver`` fixture in your tests.
+
+Creating a different httpserver fixture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This way, you can create a different httpserver fixture and you can use it
+besides the main one.
+
+.. code:: python
+
+    @pytest.fixture()
+    def threaded() -> Iterable[HTTPServer]:
+        server = HTTPServer(threaded=True)
+        server.start()
+        yield server
+        server.clear()
+        if server.is_running():
+            server.stop()
+
+
+    def test_threaded(threaded: HTTPServer): ...
+
+
+This will start and stop the server for each tests, which causes about 0.5
+seconds waiting when the server is stopped. It won't override the ``httpserver``
+fixture so you can keep the original single-threaded behavior.
+
+.. warning::
+    Handler threads which are still running when the test is finished, will be
+    left behind and won't be join()ed between the tests. If you want to ensure
+    that all threads are properly cleaned up and you want to wait for them,
+    consider using the second option (:ref:`Creating a different httpserver fixture`)
+    described above.
+
+
+Adding side effects
+-------------------
+
+Sometimes there's a need to add side effects to the handling of the requests.
+Such side effect could be adding some amount of delay to the serving or adding
+some garbage to response data.
+
+While these can be achieved by using
+:py:meth:`pytest_httpserver.RequestHandler.respond_with_handler` where you can
+implement your own function to serve the request, *pytest-httpserver* provides a
+hooks API where you can add side effects to request handlers such as
+:py:meth:`pytest_httpserver.RequestHandler.respond_with_json` and others.
+This allows to use the existing API of registering handlers.
+
+Example:
+
+.. literalinclude :: ../tests/examples/test_howto_hooks.py
+    :language: python
+
+:py:mod:`pytest_httpserver.hooks` module provides some pre-defined hooks to
+use.
+
+You can implement your own hook as well. The requirement is to have a callable
+object (a function) ``Callable[[Request, Response], Response]``. In details:
+
+* Parameter :py:class:`werkzeug.Request` which represents the request
+  sent by the client.
+
+* Parameter :py:class:`werkzeug.Response` which represents the response
+  made by the handler.
+
+* Returns a :py:class:`werkzeug.Response` object which represents the
+  response will be returned to the client.
+
+
+Example:
+
+.. literalinclude :: ../tests/examples/test_howto_custom_hooks.py
+    :language: python
+
+``with_post_hook`` can be called multiple times, in this case *pytest-httpserver*
+will register the hooks, and hooks will be called sequentially, one by one. Each
+hook will receive the response what the previous hook returned, and the last
+hook called will return the final response which will be sent back to the client.

pytest_httpserver-1.0.11/doc/patch.py

@@ -0,0 +1,16 @@
+# this is required to make sphinx able to find references for classes put inside
+# typing.TYPE_CHECKING block
+
+from ssl import SSLContext
+
+from werkzeug import Request
+from werkzeug import Response
+
+import pytest_httpserver.blocking_httpserver
+import pytest_httpserver.httpserver
+
+pytest_httpserver.httpserver.SSLContext = SSLContext
+pytest_httpserver.blocking_httpserver.SSLContext = SSLContext
+
+pytest_httpserver.blocking_httpserver.Request = Request
+pytest_httpserver.blocking_httpserver.Response = Response

{pytest_httpserver-1.0.10 → pytest_httpserver-1.0.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pytest_httpserver"
-version = "1.0.10"
+version = "1.0.11"
 description = "pytest-httpserver is a httpserver for pytest"
 authors = ["Zsolt Cserna <cserna.zsolt@gmail.com>"]
 license = "MIT"
@@ -38,43 +38,43 @@ pytest_httpserver = "pytest_httpserver.pytest_plugin"
 optional = true
 
 [tool.poetry.group.develop.dependencies]
-pre-commit = "^2.20.0"
-requests = "^2.28.1"
-Sphinx = "^5.1.1"
-sphinx-rtd-theme = "^1.0.0"
-reno = "^3.5.0"
-mypy = "^0.971"
-types-requests = "^2.28.9"
-pytest = "^7.1.3"
-pytest-cov = ">=3,<5"
+pre-commit = ">=2.20,<4.0"
+requests = "*"
+Sphinx = ">=5.1.1,<8.0.0"
+sphinx-rtd-theme = ">=1,<3"
+reno = "*"
+types-requests = "*"
+pytest = ">=7.1.3,<9.0.0"
+pytest-cov = ">=3,<6"
 coverage = ">=6.4.4,<8.0.0"
-types-toml = "^0.10.8"
+types-toml = "*"
 toml = "^0.10.2"
-black = "^23.1.0"
-ruff = "^0.2.1"
+black = "*"
+ruff = "*"
+mypy = "*"
 
 
 [tool.poetry.group.doc]
 optional = true
 
 [tool.poetry.group.doc.dependencies]
-Sphinx = "^5.1.1"
-sphinx-rtd-theme = "^1.0.0"
+Sphinx = ">=5.1.1,<8.0.0"
+sphinx-rtd-theme = ">=1,<3"
 
 
 [tool.poetry.group.test]
 optional = true
 
 [tool.poetry.group.test.dependencies]
-pytest = "^7.1.3"
-pytest-cov = ">=3,<5"
-coverage = ">=6.4.4,<8.0.0"
-requests = "^2.28.1"
-mypy = "^0.971"
-types-requests = "^2.28.9"
-pre-commit = "^2.20.0"
-types-toml = "^0.10.8"
-toml = "^0.10.2"
+pytest = "*"
+pytest-cov = "*"
+coverage = "*"
+requests = "*"
+types-requests = "*"
+pre-commit = "*"
+types-toml = "*"
+toml = "*"
+mypy = "*"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]
@@ -87,7 +87,7 @@ markers = [
 ]
 
 [tool.mypy]
-files = ["pytest_httpserver", "scripts", "tests", "doc"]
+files = ["pytest_httpserver", "scripts", "tests"]
 implicit_reexport = false
 
 

{pytest_httpserver-1.0.10 → pytest_httpserver-1.0.11}/pytest_httpserver/__init__.py

@@ -2,6 +2,7 @@
 This is package provides the main API for the pytest_httpserver package.
 
 """
+
 __all__ = [
     "HTTPServer",
     "HTTPServerError",
@@ -10,6 +11,7 @@ __all__ = [
     "WaitingSettings",
     "HeaderValueMatcher",
     "RequestHandler",
+    "RequestMatcher",
     "URIPattern",
     "URI_DEFAULT",
     "METHOD_ALL",
@@ -27,5 +29,6 @@ from .httpserver import HTTPServer
 from .httpserver import HTTPServerError
 from .httpserver import NoHandlerError
 from .httpserver import RequestHandler
+from .httpserver import RequestMatcher
 from .httpserver import URIPattern
 from .httpserver import WaitingSettings

{pytest_httpserver-1.0.10 → pytest_httpserver-1.0.11}/pytest_httpserver/blocking_httpserver.py

@@ -18,8 +18,8 @@ from pytest_httpserver.httpserver import URIPattern
 if TYPE_CHECKING:
     from ssl import SSLContext
 
-    from werkzeug.wrappers import Request
-    from werkzeug.wrappers import Response
+    from werkzeug import Request
+    from werkzeug import Response
 
 
 class BlockingRequestHandler(RequestHandlerBase):

pytest_httpserver-1.0.11/pytest_httpserver/hooks.py

@@ -0,0 +1,103 @@
+"""
+Hooks for pytest-httpserver
+"""
+
+import os
+import time
+from typing import Callable
+
+from werkzeug import Request
+from werkzeug import Response
+
+
+class Chain:
+    """
+    Combine multiple hooks into one callable object
+
+    Hooks specified will be called one by one.
+
+    Each hook will receive the response object made by the previous hook,
+    similar to reduce.
+    """
+
+    def __init__(self, *args: Callable[[Request, Response], Response]):
+        """
+        :param *args: callable objects specified in the same order they should
+            be called.
+        """
+        self._hooks = args
+
+    def __call__(self, request: Request, response: Response) -> Response:
+        """
+        Calls the callable object one by one. The second and further callable
+        objects receive the response returned by the previous one, while the
+        first one receives the original response object.
+        """
+        for hook in self._hooks:
+            response = hook(request, response)
+        return response
+
+
+class Delay:
+    """
+    Delays returning the response
+    """
+
+    def __init__(self, seconds: float):
+        """
+        :param seconds: seconds to sleep before returning the response
+        """
+        self._seconds = seconds
+
+    def _sleep(self):
+        """
+        Sleeps for the seconds specified in the constructor
+        """
+        time.sleep(self._seconds)
+
+    def __call__(self, _request: Request, response: Response) -> Response:
+        """
+        Delays returning the response object for the time specified in the
+        constructor. Returns the original response unmodified.
+        """
+        self._sleep()
+        return response
+
+
+class Garbage:
+    def __init__(self, prefix_size: int = 0, suffix_size: int = 0):
+        """
+        Adds random bytes to the beginning or to the end of the response data.
+
+        :param prefix_size: amount of random bytes to be added to the beginning
+            of the response data
+
+        :param suffix_size: amount of random bytes to be added to the end
+            of the response data
+
+        """
+        assert prefix_size >= 0, "prefix_size should be positive integer"
+        assert suffix_size >= 0, "suffix_size should be positive integer"
+        self._prefix_size = prefix_size
+        self._suffix_size = suffix_size
+
+    def _get_garbage_bytes(self, size: int) -> bytes:
+        """
+        Returns the specified amount of random bytes.
+
+        :param size: amount of bytes to return
+        """
+        return os.urandom(size)
+
+    def __call__(self, _request: Request, response: Response) -> Response:
+        """
+        Adds random bytes to the beginning or to the end of the response data.
+
+        New random bytes will be generated for every call.
+
+        Returns the modified response object.
+        """
+        prefix = self._get_garbage_bytes(self._prefix_size)
+        suffix = self._get_garbage_bytes(self._suffix_size)
+        response.set_data(prefix + response.get_data() + suffix)
+        return response

{pytest_httpserver-1.0.10 → pytest_httpserver-1.0.11}/pytest_httpserver/httpserver.py

@@ -26,11 +26,11 @@ from typing import Tuple
 from typing import Union
 
 import werkzeug.http
+from werkzeug import Request
+from werkzeug import Response
 from werkzeug.datastructures import Authorization
 from werkzeug.datastructures import MultiDict
 from werkzeug.serving import make_server
-from werkzeug.wrappers import Request
-from werkzeug.wrappers import Response
 
 if TYPE_CHECKING:
     from ssl import SSLContext
@@ -495,7 +495,7 @@ class RequestHandlerBase(abc.ABC):
         """
         Prepares a response with raw data.
 
-        For detailed description please see the :py:class:`werkzeug.wrappers.Response` object as the
+        For detailed description please see the :py:class:`werkzeug.Response` object as the
         parameters are analogue.
 
         :param response_data: a string or bytes object representing the body of the response
@@ -529,6 +529,11 @@ class RequestHandler(RequestHandlerBase):
     def __init__(self, matcher: RequestMatcher):
         self.matcher = matcher
         self.request_handler: Callable[[Request], Response] | None = None
+        self._hooks: list[Callable[[Request, Response], Response]] = []
+
+    def with_post_hook(self, hook: Callable[[Request, Response], Response]):
+        self._hooks.append(hook)
+        return self
 
     def respond(self, request: Request) -> Response:
         """
@@ -546,7 +551,11 @@ class RequestHandler(RequestHandlerBase):
                 "Matching request handler found but no response defined: {} {}".format(request.method, request.path)
             )
         else:
-            return self.request_handler(request)
+            response = self.request_handler(request)
+
+            for hook in self._hooks:
+                response = hook(request, response)
+            return response
 
     def respond_with_handler(self, func: Callable[[Request], Response]):
         """
@@ -598,11 +607,12 @@ class HTTPServerBase(abc.ABC):  # pylint: disable=too-many-instance-attributes
     :param host: the host or IP where the server will listen
     :param port: the TCP port where the server will listen
     :param ssl_context: the ssl context object to use for https connections
+    :param threaded: whether to handle concurrent requests in separate threads
 
     .. py:attribute:: log
 
         Attribute containing the list of two-element tuples. Each tuple contains
-        :py:class:`werkzeug.wrappers.Request` and :py:class:`werkzeug.wrappers.Response` object which represents the
+        :py:class:`werkzeug.Request` and :py:class:`werkzeug.Response` object which represents the
         incoming request and the outgoing response which happened during the lifetime
         of the server.
 
@@ -619,6 +629,8 @@ class HTTPServerBase(abc.ABC):  # pylint: disable=too-many-instance-attributes
         host: str,
         port: int,
         ssl_context: SSLContext | None = None,
+        *,
+        threaded: bool = False,
     ):
         """
         Initializes the instance.
@@ -632,6 +644,7 @@ class HTTPServerBase(abc.ABC):  # pylint: disable=too-many-instance-attributes
         self.handler_errors: list[Exception] = []
         self.log: list[tuple[Request, Response]] = []
         self.ssl_context = ssl_context
+        self.threaded = threaded
         self.no_handler_status_code = 500
 
     def __repr__(self):
@@ -730,11 +743,11 @@ class HTTPServerBase(abc.ABC):  # pylint: disable=too-many-instance-attributes
         This method returns immediately (e.g. does not block), and it's the caller's
         responsibility to stop the server (by calling :py:meth:`stop`) when it is no longer needed).
 
-        If the sever is not stopped by the caller and execution reaches the end, the
+        If the server is not stopped by the caller and execution reaches the end, the
         program needs to be terminated by Ctrl+C or by signal as it will not terminate until
         the thread is stopped.
 
-        If the sever is already running :py:class:`HTTPServerError` will be raised. If you are
+        If the server is already running :py:class:`HTTPServerError` will be raised. If you are
         unsure, call :py:meth:`is_running` first.
 
         There's a context interface of this class which stops the server when the context block ends.
@@ -742,7 +755,9 @@ class HTTPServerBase(abc.ABC):  # pylint: disable=too-many-instance-attributes
         if self.is_running():
             raise HTTPServerError("Server is already running")
 
-        self.server = make_server(self.host, self.port, self.application, ssl_context=self.ssl_context)
+        self.server = make_server(
+            self.host, self.port, self.application, ssl_context=self.ssl_context, threaded=self.threaded
+        )
         self.port = self.server.port  # Update port (needed if `port` was set to 0)
         self.server_thread = threading.Thread(target=self.thread_target)
         self.server_thread.start()
@@ -900,6 +915,8 @@ class HTTPServer(HTTPServerBase):  # pylint: disable=too-many-instance-attribute
     :param default_waiting_settings: the waiting settings object to use as default settings for :py:meth:`wait` context
         manager
 
+    :param threaded: whether to handle concurrent requests in separate threads
+
     .. py:attribute:: no_handler_status_code
 
         Attribute containing the http status code (int) which will be the response
@@ -916,11 +933,13 @@ class HTTPServer(HTTPServerBase):  # pylint: disable=too-many-instance-attribute
         port=DEFAULT_LISTEN_PORT,
         ssl_context: SSLContext | None = None,
         default_waiting_settings: WaitingSettings | None = None,
+        *,
+        threaded: bool = False,
     ):
         """
         Initializes the instance.
         """
-        super().__init__(host, port, ssl_context)
+        super().__init__(host, port, ssl_context, threaded=threaded)
 
         self.ordered_handlers: list[RequestHandler] = []
         self.oneshot_handlers = RequestHandlerList()
@@ -1333,3 +1352,73 @@ class HTTPServer(HTTPServerBase):  # pylint: disable=too-many-instance-attribute
                 )
         if self._waiting_settings.raise_assertions and not waiting.result:
             self.check_assertions()
+
+    def iter_matching_requests(self, matcher: RequestMatcher) -> Iterable[tuple[Request, Response]]:
+        """
+        Queries log for matching requests.
+
+
+        :param matcher: the matcher object to match requests
+        :return: an iterator with request-response pair from the log
+        """
+
+        for request, response in self.log:
+            if matcher.match(request):
+                yield (request, response)
+
+    def get_matching_requests_count(self, matcher: RequestMatcher) -> int:
+        """
+        Queries the log for matching requests, returning the number of log
+        entries matching for the specified matcher.
+
+        :param matcher: the matcher object to match requests
+        :return: the number of log entries matching
+        """
+        return len(list(self.iter_matching_requests(matcher)))
+
+    def assert_request_made(self, matcher: RequestMatcher, *, count: int = 1):
+        """
+        Check the amount of log entries matching for the matcher specified. By
+        default it verifies that exactly one request matching for the matcher
+        specified. The expected count can be customized with the count kwarg
+        (including zero, which asserts that no requests made for the given
+        matcher).
+
+        :param matcher: the matcher object to match requests
+        :param count: the expected number of matches in the log
+        :return: ``None`` if the assert succeeded, raises
+            :py:class:`AssertionError` if not.
+        """
+
+        matching_count = self.get_matching_requests_count(matcher)
+        if matching_count != count:
+            similar_requests: list[Request] = []
+            for request, _ in self.log:
+                if request.path == matcher.uri:
+                    similar_requests.append(request)
+
+            assert_msg_lines = [
+                f"Matching request found {matching_count} times but expected {count} times.",
+                f"Expected request: {matcher}",
+            ]
+
+            if similar_requests:
+                assert_msg_lines.append(f"Found {len(similar_requests)} similar request(s):")
+                for request in similar_requests:
+                    assert_msg_lines.extend(
+                        (
+                            "--- Similar Request Start",
+                            f"Path: {request.path}",
+                            f"Method: {request.method}",
+                            f"Body: {request.get_data()!r}",
+                            f"Headers: {request.headers}",
+                            f"Query String: {request.query_string.decode('utf-8')!r}",
+                            "--- Similar Request End",
+                        )
+                    )
+            else:
+                assert_msg_lines.append("No similar requests found.")
+
+            assert_msg = "\n".join(assert_msg_lines) + "\n"
+
+            assert matching_count == count, assert_msg