spoof 2.2.0__tar.gz → 2.2.2__tar.gz

{spoof-2.2.0 → spoof-2.2.2}/CHANGELOG.rst

@@ -1,3 +1,13 @@
+2.2.2 (2026-04-21)
+==================
+
+- Update docs
+
+2.2.1 (2026-04-17)
+==================
+
+- Update docs
+
 2.2.0 (2026-04-13)
 ==================
 

{spoof-2.2.0 → spoof-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spoof
-Version: 2.2.0
+Version: 2.2.2
 Summary: HTTP server for testing environments
 Author-email: Lex Scarisbrick <lex@scarisbrick.org>
 License-Expression: MIT
@@ -57,12 +57,12 @@ Spoof 👻
 A test interface for HTTP
 =========================
 Spoof lets you easily create HTTP servers listening on real network
-sockets. Designed for test environments, what responses to return can be
-configured while an HTTP server is running. Requests can be inspected
-live or after a response is sent.
+sockets. Designed for test environments, what responses to send can be
+configured anytime, including while an HTTP server is running. Requests
+can be inspected live or after a response is sent.
 
-Unlike a traditional HTTP server, where specific methods and paths are
-configured in advance, Spoof accepts and captures *all* requests, sending
+Unlike a conventional HTTP server, where specific methods and paths are
+configured in advance, Spoof accepts and records *all* requests, sending
 whatever responses are queued, or a default response if the queue is empty.
 
 Why would I want this?
@@ -70,13 +70,12 @@ Why would I want this?
 Spoof is all about enabling test-driven development (and refactoring) of
 HTTP client code. Have you ever felt icky patching a client library to
 write tests? Ever been burned by this? Ever wanted to refactor a client
-library, but had no way to prove functionality apart from doing live
-integration testing? Ever wanted mock functionality for HTTP? If you
-answered yes to any of the above, Spoof might be for you.
+library, but had no way to verify behavior apart from doing live
+integration testing? Ever wanted mock for HTTP? If you answered yes to
+any of the above, Spoof might be for you.
 
 Installation and Compatibility
 ==============================
-
 Spoof is available on PyPI:
 
 .. code-block:: console
@@ -91,74 +90,8 @@ Multiple Spoof HTTP servers can be run concurrently, and by default, the port
 number is the next available unused port. With OpenSSL installed, Spoof can
 also provide an SSL/TLS HTTP server. HTTP proxying and IPv6 are also supported.
 
-Request instances
-=================
-Spoof captures each request as a ``SpoofRequestEnv`` instance with the following
-properties:
-
-+-------------------------+----------------------------------------------+
-| Property                | Description                                  |
-+=========================+==============================================+
-| content                 | ``bytes`` object of request content          |
-+-------------------------+----------------------------------------------+
-| contentEncoding         | Value of Content-Encoding header, if present |
-+-------------------------+----------------------------------------------+
-| contentLength           | Value of Content-Length header, if present   |
-+-------------------------+----------------------------------------------+
-| contentType             | Value of Content-Type header, if present     |
-+-------------------------+----------------------------------------------+
-| headers                 | ``http.client.HTTPMessage`` object of headers|
-+-------------------------+----------------------------------------------+
-| json()                  | Convenience to call ``json.loads`` on content|
-+-------------------------+----------------------------------------------+
-| method                  | Request method (e.g. GET, POST, HEAD)        |
-+-------------------------+----------------------------------------------+
-| path                    | Decoded URI path, without query string       |
-+-------------------------+----------------------------------------------+
-| protocol                | Protocol version (e.g. HTTP/1.0)             |
-+-------------------------+----------------------------------------------+
-| queryString             | Anything in URI after ``?``                  |
-+-------------------------+----------------------------------------------+
-| serverName              | Host name of HTTP server                     |
-+-------------------------+----------------------------------------------+
-| serverPort              | Port number of HTTP server                   |
-+-------------------------+----------------------------------------------+
-| uri                     | Raw URI path and query string, if present    |
-+-------------------------+----------------------------------------------+
-
-Example with request properties:
-
-.. code-block:: python
-
-   >>> import requests
-   ... import spoof
-   ...
-   ... with spoof.HTTPServer() as httpd:
-   ...     httpd.defaultResponse = [200, [], None]
-   ...
-   ...     [requests.get(httpd.url + path) for path in ["/a", "/b", "/c"]]
-   ...     [f"{r.method} {r.path} {r.protocol}" for r in httpd.requests]
-   ...
-   [<Response [200]>, <Response [200]>, <Response [200]>]
-   ['GET /a HTTP/1.1', 'GET /b HTTP/1.1', 'GET /c HTTP/1.1']
-
-Response precedence
-===================
-
-Spoof determines what response to send to incoming requests based on
-the following precedence, highest to lowest:
-
-#. Oldest response queued in ``.responses`` using first-in, first-out (FIFO) order
-#. Response stored in ``.defaultResponse`` if no responses are queued
-#. Response stored in ``.errorResponse`` if ``.defaultResponse`` is ``None``
-
-By default, an HTTP error response will be sent to all requests, because
-newly created Spoof instances have no responses queued, and no default
-response set. This requires non-error responses to be explicitly specified.
-
 Response syntax
 ===============
-
 Spoof expects responses to have the following syntax:
 
 .. code-block:: python
@@ -178,13 +111,31 @@ Spoof expects responses to have the following syntax:
    def callback(request):
        return [200, [], request.path]
 
-Queued responses
-================
+Response precedence
+===================
+Spoof determines what response to send to incoming requests based on
+the following precedence, highest to lowest:
+
+#. Oldest response queued in ``.responses`` using first-in, first-out (FIFO) order
+#. Response stored in ``.defaultResponse`` if no responses are queued
+#. Response stored in ``.errorResponse`` if ``.defaultResponse`` is ``None``
+
+By default, Spoof will respond with an **HTTP 503 Service Unavailable** error,
+because newly created Spoof instances have no responses queued and no default
+response set. This requires non-error HTTP responses to be explicitly specified.
 
-Spoof HTTP servers run in a single background thread, so request and
-response order should be predictable. Tests using Spoof should be able
-to use the same fixtures, in the same order, and get the same results. Example
-queueing multiple responses, verifying content, and request paths:
+Response queue
+==============
+Spoof will always try to send a response from ``.responses`` first, before falling
+back to ``.defaultResponse`` if the queue is empty. Backed by a
+`deque <https://docs.python.org/3/library/collections.html#collections.deque>`__
+instance, the ``.responses`` queue supports adding items via ``.responses.append()``
+and ``.responses.extend()``, similar to a regular list.
+
+Spoof HTTP servers run in a single background thread, so response order should
+be predictably serial. Tests using Spoof should be able to use the same fixtures,
+in the same order, and get the same results. Example queueing multiple responses,
+verifying content, and request paths:
 
 .. code-block:: python
 
@@ -203,9 +154,11 @@ queueing multiple responses, verifying content, and request paths:
        assert requests.get(httpd.url + "/oops").status_code == 404
        assert [r.path for r in httpd.requests] == ["/path", "/alt/path", "/oops"]
 
-Callback response
-=================
-Set a callback as the default response (callbacks can also be queued):
+Response default
+================
+Spoof will always try to send a response from ``.responses`` first, before falling
+back to ``.defaultResponse`` if the queue is empty. Example setting a callback as
+a default response:
 
 .. code-block:: python
 
@@ -217,9 +170,69 @@ Set a callback as the default response (callbacks can also be queued):
 
        assert requests.get(httpd.url + "/alt").text == "/alt"
 
+Request history
+===============
+Spoof records each request and appends it to the ``.requests`` property,
+which is backed by a
+`deque <https://docs.python.org/3/library/collections.html#collections.deque>`__
+instance, the same as the ``.responses`` property. Think of it like a pre-parsed access log. Example
+using request history:
+
+.. code-block:: python
+
+   >>> import requests
+   ... import spoof
+   ...
+   ... with spoof.HTTPServer() as httpd:
+   ...     httpd.defaultResponse = [200, [], None]
+   ...
+   ...     [requests.get(httpd.url + path) for path in ["/a", "/b", "/c"]]
+   ...     [f"{r.method} {r.path} {r.protocol}" for r in httpd.requests]
+   ...
+   [<Response [200]>, <Response [200]>, <Response [200]>]
+   ['GET /a HTTP/1.1', 'GET /b HTTP/1.1', 'GET /c HTTP/1.1']
+
+Request properties
+==================
+``SpoofRequestEnv`` instances have the following properties:
+
++-------------------------+----------------------------------------------+
+| Property                | Description                                  |
++=========================+==============================================+
+| content                 | ``bytes`` object of request content          |
++-------------------------+----------------------------------------------+
+| contentEncoding         | Value of Content-Encoding header, if present |
++-------------------------+----------------------------------------------+
+| contentLength           | Value of Content-Length header, if present   |
++-------------------------+----------------------------------------------+
+| contentType             | Value of Content-Type header, if present     |
++-------------------------+----------------------------------------------+
+| headers                 | ``http.client.HTTPMessage`` object of headers|
++-------------------------+----------------------------------------------+
+| json()                  | Convenience to call ``json.loads`` on content|
++-------------------------+----------------------------------------------+
+| method                  | Request method (e.g. GET, POST, HEAD)        |
++-------------------------+----------------------------------------------+
+| path                    | Decoded URI path, without query string       |
++-------------------------+----------------------------------------------+
+| protocol                | Protocol version (e.g. HTTP/1.0)             |
++-------------------------+----------------------------------------------+
+| queryString             | Anything in URI after ``?``                  |
++-------------------------+----------------------------------------------+
+| serverName              | Host name of HTTP server                     |
++-------------------------+----------------------------------------------+
+| serverPort              | Port number of HTTP server                   |
++-------------------------+----------------------------------------------+
+| uri                     | Raw URI path and query string, if present    |
++-------------------------+----------------------------------------------+
+
 SSL/TLS Mode
 ============
-Test queued response with a self-signed SSL/TLS certificate:
+Spoof supports SSL/TLS connectivity by passing an
+`SSLContext <https://docs.python.org/3/library/ssl.html#ssl-contexts>`__,
+or if OpenSSL command line tools are available, creating an ``SSLContext``
+with a self-signed certificate. Configured correctly, this should not raise
+any warnings or errors:
 
 .. code-block:: python
 
@@ -251,8 +264,8 @@ set to the path of the self-signed certificate to silence SSL/TLS errors:
            response = requests.get(httpd.url)
            assert response.text == "No self-signed cert warning!"
 
-If OpenSSL 3.5.0 or later is installed, Post-Quantum Cryptography (PQC)
-key algorithms can be used:
+If `OpenSSL 3.5.0 <https://openssl-library.org/post/2025-04-08-openssl-35-final-release/>`__
+or later is installed, Post-Quantum Cryptography (PQC) key algorithms can be used:
 
 .. code-block:: python
 
@@ -293,8 +306,31 @@ external services. Example usage:
            assert proxy.upstream.requests[0].path == "/ayt"
            assert response.text == "I'm here!"
 
-HTTP on IPv6
-============
+If setting the ``proxies`` option in ``requests`` isn't workable, the
+``https_proxy`` environment variable can be set to the URL of the proxy:
+
+.. code-block:: python
+
+   import os
+   import requests
+   import spoof
+
+   with spoof.SelfSignedSSLContext(commonName="example.spoof") as selfSigned:
+       with spoof.HTTPServer(sslContext=selfSigned.sslContext, proxy=True) as proxy:
+           proxy.upstream.defaultResponse = [200, [], "I'm here!"]
+
+           os.environ["https_proxy"] = proxy.url
+           os.environ["REQUESTS_CA_BUNDLE"] = selfSigned.certFile
+
+           response = requests.get("https://example.spoof/ayt")
+           assert proxy.requests[0].method == "CONNECT"
+           assert proxy.requests[0].path == "example.spoof:443"
+           assert proxy.upstream.requests[0].method == "GET"
+           assert proxy.upstream.requests[0].path == "/ayt"
+           assert response.text == "I'm here!"
+
+IPv6 Mode
+=========
 Setting the ``host`` attribute to an IPv6 address will work as expected. There
 is also an IPv6-only ``spoof.HTTPServer6`` class that can be used if needed to
 only listen on IPv6 sockets.
@@ -325,8 +361,8 @@ only listen on IPv6 sockets.
    'This is also Spoof on IPv6 👀'
    'http://[::1]:54296'
 
-Using a debugger
-================
+Debug mode
+==========
 Setting a callback with a ``breakpoint()`` can allow for live HTTP request
 debugging, including setting custom responses and inspecting requests. Note
 that callbacks can also be queued.
@@ -351,4 +387,3 @@ that callbacks can also be queued.
    (Pdb) response[2] = "content set from pdb"
    (Pdb) c
    'content set from pdb'
-

{spoof-2.2.0 → spoof-2.2.2}/README.rst

@@ -30,12 +30,12 @@ Spoof 👻
 A test interface for HTTP
 =========================
 Spoof lets you easily create HTTP servers listening on real network
-sockets. Designed for test environments, what responses to return can be
-configured while an HTTP server is running. Requests can be inspected
-live or after a response is sent.
+sockets. Designed for test environments, what responses to send can be
+configured anytime, including while an HTTP server is running. Requests
+can be inspected live or after a response is sent.
 
-Unlike a traditional HTTP server, where specific methods and paths are
-configured in advance, Spoof accepts and captures *all* requests, sending
+Unlike a conventional HTTP server, where specific methods and paths are
+configured in advance, Spoof accepts and records *all* requests, sending
 whatever responses are queued, or a default response if the queue is empty.
 
 Why would I want this?
@@ -43,13 +43,12 @@ Why would I want this?
 Spoof is all about enabling test-driven development (and refactoring) of
 HTTP client code. Have you ever felt icky patching a client library to
 write tests? Ever been burned by this? Ever wanted to refactor a client
-library, but had no way to prove functionality apart from doing live
-integration testing? Ever wanted mock functionality for HTTP? If you
-answered yes to any of the above, Spoof might be for you.
+library, but had no way to verify behavior apart from doing live
+integration testing? Ever wanted mock for HTTP? If you answered yes to
+any of the above, Spoof might be for you.
 
 Installation and Compatibility
 ==============================
-
 Spoof is available on PyPI:
 
 .. code-block:: console
@@ -64,74 +63,8 @@ Multiple Spoof HTTP servers can be run concurrently, and by default, the port
 number is the next available unused port. With OpenSSL installed, Spoof can
 also provide an SSL/TLS HTTP server. HTTP proxying and IPv6 are also supported.
 
-Request instances
-=================
-Spoof captures each request as a ``SpoofRequestEnv`` instance with the following
-properties:
-
-+-------------------------+----------------------------------------------+
-| Property                | Description                                  |
-+=========================+==============================================+
-| content                 | ``bytes`` object of request content          |
-+-------------------------+----------------------------------------------+
-| contentEncoding         | Value of Content-Encoding header, if present |
-+-------------------------+----------------------------------------------+
-| contentLength           | Value of Content-Length header, if present   |
-+-------------------------+----------------------------------------------+
-| contentType             | Value of Content-Type header, if present     |
-+-------------------------+----------------------------------------------+
-| headers                 | ``http.client.HTTPMessage`` object of headers|
-+-------------------------+----------------------------------------------+
-| json()                  | Convenience to call ``json.loads`` on content|
-+-------------------------+----------------------------------------------+
-| method                  | Request method (e.g. GET, POST, HEAD)        |
-+-------------------------+----------------------------------------------+
-| path                    | Decoded URI path, without query string       |
-+-------------------------+----------------------------------------------+
-| protocol                | Protocol version (e.g. HTTP/1.0)             |
-+-------------------------+----------------------------------------------+
-| queryString             | Anything in URI after ``?``                  |
-+-------------------------+----------------------------------------------+
-| serverName              | Host name of HTTP server                     |
-+-------------------------+----------------------------------------------+
-| serverPort              | Port number of HTTP server                   |
-+-------------------------+----------------------------------------------+
-| uri                     | Raw URI path and query string, if present    |
-+-------------------------+----------------------------------------------+
-
-Example with request properties:
-
-.. code-block:: python
-
-   >>> import requests
-   ... import spoof
-   ...
-   ... with spoof.HTTPServer() as httpd:
-   ...     httpd.defaultResponse = [200, [], None]
-   ...
-   ...     [requests.get(httpd.url + path) for path in ["/a", "/b", "/c"]]
-   ...     [f"{r.method} {r.path} {r.protocol}" for r in httpd.requests]
-   ...
-   [<Response [200]>, <Response [200]>, <Response [200]>]
-   ['GET /a HTTP/1.1', 'GET /b HTTP/1.1', 'GET /c HTTP/1.1']
-
-Response precedence
-===================
-
-Spoof determines what response to send to incoming requests based on
-the following precedence, highest to lowest:
-
-#. Oldest response queued in ``.responses`` using first-in, first-out (FIFO) order
-#. Response stored in ``.defaultResponse`` if no responses are queued
-#. Response stored in ``.errorResponse`` if ``.defaultResponse`` is ``None``
-
-By default, an HTTP error response will be sent to all requests, because
-newly created Spoof instances have no responses queued, and no default
-response set. This requires non-error responses to be explicitly specified.
-
 Response syntax
 ===============
-
 Spoof expects responses to have the following syntax:
 
 .. code-block:: python
@@ -151,13 +84,31 @@ Spoof expects responses to have the following syntax:
    def callback(request):
        return [200, [], request.path]
 
-Queued responses
-================
+Response precedence
+===================
+Spoof determines what response to send to incoming requests based on
+the following precedence, highest to lowest:
+
+#. Oldest response queued in ``.responses`` using first-in, first-out (FIFO) order
+#. Response stored in ``.defaultResponse`` if no responses are queued
+#. Response stored in ``.errorResponse`` if ``.defaultResponse`` is ``None``
+
+By default, Spoof will respond with an **HTTP 503 Service Unavailable** error,
+because newly created Spoof instances have no responses queued and no default
+response set. This requires non-error HTTP responses to be explicitly specified.
 
-Spoof HTTP servers run in a single background thread, so request and
-response order should be predictable. Tests using Spoof should be able
-to use the same fixtures, in the same order, and get the same results. Example
-queueing multiple responses, verifying content, and request paths:
+Response queue
+==============
+Spoof will always try to send a response from ``.responses`` first, before falling
+back to ``.defaultResponse`` if the queue is empty. Backed by a
+`deque <https://docs.python.org/3/library/collections.html#collections.deque>`__
+instance, the ``.responses`` queue supports adding items via ``.responses.append()``
+and ``.responses.extend()``, similar to a regular list.
+
+Spoof HTTP servers run in a single background thread, so response order should
+be predictably serial. Tests using Spoof should be able to use the same fixtures,
+in the same order, and get the same results. Example queueing multiple responses,
+verifying content, and request paths:
 
 .. code-block:: python
 
@@ -176,9 +127,11 @@ queueing multiple responses, verifying content, and request paths:
        assert requests.get(httpd.url + "/oops").status_code == 404
        assert [r.path for r in httpd.requests] == ["/path", "/alt/path", "/oops"]
 
-Callback response
-=================
-Set a callback as the default response (callbacks can also be queued):
+Response default
+================
+Spoof will always try to send a response from ``.responses`` first, before falling
+back to ``.defaultResponse`` if the queue is empty. Example setting a callback as
+a default response:
 
 .. code-block:: python
 
@@ -190,9 +143,69 @@ Set a callback as the default response (callbacks can also be queued):
 
        assert requests.get(httpd.url + "/alt").text == "/alt"
 
+Request history
+===============
+Spoof records each request and appends it to the ``.requests`` property,
+which is backed by a
+`deque <https://docs.python.org/3/library/collections.html#collections.deque>`__
+instance, the same as the ``.responses`` property. Think of it like a pre-parsed access log. Example
+using request history:
+
+.. code-block:: python
+
+   >>> import requests
+   ... import spoof
+   ...
+   ... with spoof.HTTPServer() as httpd:
+   ...     httpd.defaultResponse = [200, [], None]
+   ...
+   ...     [requests.get(httpd.url + path) for path in ["/a", "/b", "/c"]]
+   ...     [f"{r.method} {r.path} {r.protocol}" for r in httpd.requests]
+   ...
+   [<Response [200]>, <Response [200]>, <Response [200]>]
+   ['GET /a HTTP/1.1', 'GET /b HTTP/1.1', 'GET /c HTTP/1.1']
+
+Request properties
+==================
+``SpoofRequestEnv`` instances have the following properties:
+
++-------------------------+----------------------------------------------+
+| Property                | Description                                  |
++=========================+==============================================+
+| content                 | ``bytes`` object of request content          |
++-------------------------+----------------------------------------------+
+| contentEncoding         | Value of Content-Encoding header, if present |
++-------------------------+----------------------------------------------+
+| contentLength           | Value of Content-Length header, if present   |
++-------------------------+----------------------------------------------+
+| contentType             | Value of Content-Type header, if present     |
++-------------------------+----------------------------------------------+
+| headers                 | ``http.client.HTTPMessage`` object of headers|
++-------------------------+----------------------------------------------+
+| json()                  | Convenience to call ``json.loads`` on content|
++-------------------------+----------------------------------------------+
+| method                  | Request method (e.g. GET, POST, HEAD)        |
++-------------------------+----------------------------------------------+
+| path                    | Decoded URI path, without query string       |
++-------------------------+----------------------------------------------+
+| protocol                | Protocol version (e.g. HTTP/1.0)             |
++-------------------------+----------------------------------------------+
+| queryString             | Anything in URI after ``?``                  |
++-------------------------+----------------------------------------------+
+| serverName              | Host name of HTTP server                     |
++-------------------------+----------------------------------------------+
+| serverPort              | Port number of HTTP server                   |
++-------------------------+----------------------------------------------+
+| uri                     | Raw URI path and query string, if present    |
++-------------------------+----------------------------------------------+
+
 SSL/TLS Mode
 ============
-Test queued response with a self-signed SSL/TLS certificate:
+Spoof supports SSL/TLS connectivity by passing an
+`SSLContext <https://docs.python.org/3/library/ssl.html#ssl-contexts>`__,
+or if OpenSSL command line tools are available, creating an ``SSLContext``
+with a self-signed certificate. Configured correctly, this should not raise
+any warnings or errors:
 
 .. code-block:: python
 
@@ -224,8 +237,8 @@ set to the path of the self-signed certificate to silence SSL/TLS errors:
            response = requests.get(httpd.url)
            assert response.text == "No self-signed cert warning!"
 
-If OpenSSL 3.5.0 or later is installed, Post-Quantum Cryptography (PQC)
-key algorithms can be used:
+If `OpenSSL 3.5.0 <https://openssl-library.org/post/2025-04-08-openssl-35-final-release/>`__
+or later is installed, Post-Quantum Cryptography (PQC) key algorithms can be used:
 
 .. code-block:: python
 
@@ -266,8 +279,31 @@ external services. Example usage:
            assert proxy.upstream.requests[0].path == "/ayt"
            assert response.text == "I'm here!"
 
-HTTP on IPv6
-============
+If setting the ``proxies`` option in ``requests`` isn't workable, the
+``https_proxy`` environment variable can be set to the URL of the proxy:
+
+.. code-block:: python
+
+   import os
+   import requests
+   import spoof
+
+   with spoof.SelfSignedSSLContext(commonName="example.spoof") as selfSigned:
+       with spoof.HTTPServer(sslContext=selfSigned.sslContext, proxy=True) as proxy:
+           proxy.upstream.defaultResponse = [200, [], "I'm here!"]
+
+           os.environ["https_proxy"] = proxy.url
+           os.environ["REQUESTS_CA_BUNDLE"] = selfSigned.certFile
+
+           response = requests.get("https://example.spoof/ayt")
+           assert proxy.requests[0].method == "CONNECT"
+           assert proxy.requests[0].path == "example.spoof:443"
+           assert proxy.upstream.requests[0].method == "GET"
+           assert proxy.upstream.requests[0].path == "/ayt"
+           assert response.text == "I'm here!"
+
+IPv6 Mode
+=========
 Setting the ``host`` attribute to an IPv6 address will work as expected. There
 is also an IPv6-only ``spoof.HTTPServer6`` class that can be used if needed to
 only listen on IPv6 sockets.
@@ -298,8 +334,8 @@ only listen on IPv6 sockets.
    'This is also Spoof on IPv6 👀'
    'http://[::1]:54296'
 
-Using a debugger
-================
+Debug mode
+==========
 Setting a callback with a ``breakpoint()`` can allow for live HTTP request
 debugging, including setting custom responses and inspecting requests. Note
 that callbacks can also be queued.
@@ -324,4 +360,3 @@ that callbacks can also be queued.
    (Pdb) response[2] = "content set from pdb"
    (Pdb) c
    'content set from pdb'
-

{spoof-2.2.0 → spoof-2.2.2}/src/spoof.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spoof
-Version: 2.2.0
+Version: 2.2.2
 Summary: HTTP server for testing environments
 Author-email: Lex Scarisbrick <lex@scarisbrick.org>
 License-Expression: MIT
@@ -57,12 +57,12 @@ Spoof 👻
 A test interface for HTTP
 =========================
 Spoof lets you easily create HTTP servers listening on real network
-sockets. Designed for test environments, what responses to return can be
-configured while an HTTP server is running. Requests can be inspected
-live or after a response is sent.
+sockets. Designed for test environments, what responses to send can be
+configured anytime, including while an HTTP server is running. Requests
+can be inspected live or after a response is sent.
 
-Unlike a traditional HTTP server, where specific methods and paths are
-configured in advance, Spoof accepts and captures *all* requests, sending
+Unlike a conventional HTTP server, where specific methods and paths are
+configured in advance, Spoof accepts and records *all* requests, sending
 whatever responses are queued, or a default response if the queue is empty.
 
 Why would I want this?
@@ -70,13 +70,12 @@ Why would I want this?
 Spoof is all about enabling test-driven development (and refactoring) of
 HTTP client code. Have you ever felt icky patching a client library to
 write tests? Ever been burned by this? Ever wanted to refactor a client
-library, but had no way to prove functionality apart from doing live
-integration testing? Ever wanted mock functionality for HTTP? If you
-answered yes to any of the above, Spoof might be for you.
+library, but had no way to verify behavior apart from doing live
+integration testing? Ever wanted mock for HTTP? If you answered yes to
+any of the above, Spoof might be for you.
 
 Installation and Compatibility
 ==============================
-
 Spoof is available on PyPI:
 
 .. code-block:: console
@@ -91,74 +90,8 @@ Multiple Spoof HTTP servers can be run concurrently, and by default, the port
 number is the next available unused port. With OpenSSL installed, Spoof can
 also provide an SSL/TLS HTTP server. HTTP proxying and IPv6 are also supported.
 
-Request instances
-=================
-Spoof captures each request as a ``SpoofRequestEnv`` instance with the following
-properties:
-
-+-------------------------+----------------------------------------------+
-| Property                | Description                                  |
-+=========================+==============================================+
-| content                 | ``bytes`` object of request content          |
-+-------------------------+----------------------------------------------+
-| contentEncoding         | Value of Content-Encoding header, if present |
-+-------------------------+----------------------------------------------+
-| contentLength           | Value of Content-Length header, if present   |
-+-------------------------+----------------------------------------------+
-| contentType             | Value of Content-Type header, if present     |
-+-------------------------+----------------------------------------------+
-| headers                 | ``http.client.HTTPMessage`` object of headers|
-+-------------------------+----------------------------------------------+
-| json()                  | Convenience to call ``json.loads`` on content|
-+-------------------------+----------------------------------------------+
-| method                  | Request method (e.g. GET, POST, HEAD)        |
-+-------------------------+----------------------------------------------+
-| path                    | Decoded URI path, without query string       |
-+-------------------------+----------------------------------------------+
-| protocol                | Protocol version (e.g. HTTP/1.0)             |
-+-------------------------+----------------------------------------------+
-| queryString             | Anything in URI after ``?``                  |
-+-------------------------+----------------------------------------------+
-| serverName              | Host name of HTTP server                     |
-+-------------------------+----------------------------------------------+
-| serverPort              | Port number of HTTP server                   |
-+-------------------------+----------------------------------------------+
-| uri                     | Raw URI path and query string, if present    |
-+-------------------------+----------------------------------------------+
-
-Example with request properties:
-
-.. code-block:: python
-
-   >>> import requests
-   ... import spoof
-   ...
-   ... with spoof.HTTPServer() as httpd:
-   ...     httpd.defaultResponse = [200, [], None]
-   ...
-   ...     [requests.get(httpd.url + path) for path in ["/a", "/b", "/c"]]
-   ...     [f"{r.method} {r.path} {r.protocol}" for r in httpd.requests]
-   ...
-   [<Response [200]>, <Response [200]>, <Response [200]>]
-   ['GET /a HTTP/1.1', 'GET /b HTTP/1.1', 'GET /c HTTP/1.1']
-
-Response precedence
-===================
-
-Spoof determines what response to send to incoming requests based on
-the following precedence, highest to lowest:
-
-#. Oldest response queued in ``.responses`` using first-in, first-out (FIFO) order
-#. Response stored in ``.defaultResponse`` if no responses are queued
-#. Response stored in ``.errorResponse`` if ``.defaultResponse`` is ``None``
-
-By default, an HTTP error response will be sent to all requests, because
-newly created Spoof instances have no responses queued, and no default
-response set. This requires non-error responses to be explicitly specified.
-
 Response syntax
 ===============
-
 Spoof expects responses to have the following syntax:
 
 .. code-block:: python
@@ -178,13 +111,31 @@ Spoof expects responses to have the following syntax:
    def callback(request):
        return [200, [], request.path]
 
-Queued responses
-================
+Response precedence
+===================
+Spoof determines what response to send to incoming requests based on
+the following precedence, highest to lowest:
+
+#. Oldest response queued in ``.responses`` using first-in, first-out (FIFO) order
+#. Response stored in ``.defaultResponse`` if no responses are queued
+#. Response stored in ``.errorResponse`` if ``.defaultResponse`` is ``None``
+
+By default, Spoof will respond with an **HTTP 503 Service Unavailable** error,
+because newly created Spoof instances have no responses queued and no default
+response set. This requires non-error HTTP responses to be explicitly specified.
 
-Spoof HTTP servers run in a single background thread, so request and
-response order should be predictable. Tests using Spoof should be able
-to use the same fixtures, in the same order, and get the same results. Example
-queueing multiple responses, verifying content, and request paths:
+Response queue
+==============
+Spoof will always try to send a response from ``.responses`` first, before falling
+back to ``.defaultResponse`` if the queue is empty. Backed by a
+`deque <https://docs.python.org/3/library/collections.html#collections.deque>`__
+instance, the ``.responses`` queue supports adding items via ``.responses.append()``
+and ``.responses.extend()``, similar to a regular list.
+
+Spoof HTTP servers run in a single background thread, so response order should
+be predictably serial. Tests using Spoof should be able to use the same fixtures,
+in the same order, and get the same results. Example queueing multiple responses,
+verifying content, and request paths:
 
 .. code-block:: python
 
@@ -203,9 +154,11 @@ queueing multiple responses, verifying content, and request paths:
        assert requests.get(httpd.url + "/oops").status_code == 404
        assert [r.path for r in httpd.requests] == ["/path", "/alt/path", "/oops"]
 
-Callback response
-=================
-Set a callback as the default response (callbacks can also be queued):
+Response default
+================
+Spoof will always try to send a response from ``.responses`` first, before falling
+back to ``.defaultResponse`` if the queue is empty. Example setting a callback as
+a default response:
 
 .. code-block:: python
 
@@ -217,9 +170,69 @@ Set a callback as the default response (callbacks can also be queued):
 
        assert requests.get(httpd.url + "/alt").text == "/alt"
 
+Request history
+===============
+Spoof records each request and appends it to the ``.requests`` property,
+which is backed by a
+`deque <https://docs.python.org/3/library/collections.html#collections.deque>`__
+instance, the same as the ``.responses`` property. Think of it like a pre-parsed access log. Example
+using request history:
+
+.. code-block:: python
+
+   >>> import requests
+   ... import spoof
+   ...
+   ... with spoof.HTTPServer() as httpd:
+   ...     httpd.defaultResponse = [200, [], None]
+   ...
+   ...     [requests.get(httpd.url + path) for path in ["/a", "/b", "/c"]]
+   ...     [f"{r.method} {r.path} {r.protocol}" for r in httpd.requests]
+   ...
+   [<Response [200]>, <Response [200]>, <Response [200]>]
+   ['GET /a HTTP/1.1', 'GET /b HTTP/1.1', 'GET /c HTTP/1.1']
+
+Request properties
+==================
+``SpoofRequestEnv`` instances have the following properties:
+
++-------------------------+----------------------------------------------+
+| Property                | Description                                  |
++=========================+==============================================+
+| content                 | ``bytes`` object of request content          |
++-------------------------+----------------------------------------------+
+| contentEncoding         | Value of Content-Encoding header, if present |
++-------------------------+----------------------------------------------+
+| contentLength           | Value of Content-Length header, if present   |
++-------------------------+----------------------------------------------+
+| contentType             | Value of Content-Type header, if present     |
++-------------------------+----------------------------------------------+
+| headers                 | ``http.client.HTTPMessage`` object of headers|
++-------------------------+----------------------------------------------+
+| json()                  | Convenience to call ``json.loads`` on content|
++-------------------------+----------------------------------------------+
+| method                  | Request method (e.g. GET, POST, HEAD)        |
++-------------------------+----------------------------------------------+
+| path                    | Decoded URI path, without query string       |
++-------------------------+----------------------------------------------+
+| protocol                | Protocol version (e.g. HTTP/1.0)             |
++-------------------------+----------------------------------------------+
+| queryString             | Anything in URI after ``?``                  |
++-------------------------+----------------------------------------------+
+| serverName              | Host name of HTTP server                     |
++-------------------------+----------------------------------------------+
+| serverPort              | Port number of HTTP server                   |
++-------------------------+----------------------------------------------+
+| uri                     | Raw URI path and query string, if present    |
++-------------------------+----------------------------------------------+
+
 SSL/TLS Mode
 ============
-Test queued response with a self-signed SSL/TLS certificate:
+Spoof supports SSL/TLS connectivity by passing an
+`SSLContext <https://docs.python.org/3/library/ssl.html#ssl-contexts>`__,
+or if OpenSSL command line tools are available, creating an ``SSLContext``
+with a self-signed certificate. Configured correctly, this should not raise
+any warnings or errors:
 
 .. code-block:: python
 
@@ -251,8 +264,8 @@ set to the path of the self-signed certificate to silence SSL/TLS errors:
            response = requests.get(httpd.url)
            assert response.text == "No self-signed cert warning!"
 
-If OpenSSL 3.5.0 or later is installed, Post-Quantum Cryptography (PQC)
-key algorithms can be used:
+If `OpenSSL 3.5.0 <https://openssl-library.org/post/2025-04-08-openssl-35-final-release/>`__
+or later is installed, Post-Quantum Cryptography (PQC) key algorithms can be used:
 
 .. code-block:: python
 
@@ -293,8 +306,31 @@ external services. Example usage:
            assert proxy.upstream.requests[0].path == "/ayt"
            assert response.text == "I'm here!"
 
-HTTP on IPv6
-============
+If setting the ``proxies`` option in ``requests`` isn't workable, the
+``https_proxy`` environment variable can be set to the URL of the proxy:
+
+.. code-block:: python
+
+   import os
+   import requests
+   import spoof
+
+   with spoof.SelfSignedSSLContext(commonName="example.spoof") as selfSigned:
+       with spoof.HTTPServer(sslContext=selfSigned.sslContext, proxy=True) as proxy:
+           proxy.upstream.defaultResponse = [200, [], "I'm here!"]
+
+           os.environ["https_proxy"] = proxy.url
+           os.environ["REQUESTS_CA_BUNDLE"] = selfSigned.certFile
+
+           response = requests.get("https://example.spoof/ayt")
+           assert proxy.requests[0].method == "CONNECT"
+           assert proxy.requests[0].path == "example.spoof:443"
+           assert proxy.upstream.requests[0].method == "GET"
+           assert proxy.upstream.requests[0].path == "/ayt"
+           assert response.text == "I'm here!"
+
+IPv6 Mode
+=========
 Setting the ``host`` attribute to an IPv6 address will work as expected. There
 is also an IPv6-only ``spoof.HTTPServer6`` class that can be used if needed to
 only listen on IPv6 sockets.
@@ -325,8 +361,8 @@ only listen on IPv6 sockets.
    'This is also Spoof on IPv6 👀'
    'http://[::1]:54296'
 
-Using a debugger
-================
+Debug mode
+==========
 Setting a callback with a ``breakpoint()`` can allow for live HTTP request
 debugging, including setting custom responses and inspecting requests. Note
 that callbacks can also be queued.
@@ -351,4 +387,3 @@ that callbacks can also be queued.
    (Pdb) response[2] = "content set from pdb"
    (Pdb) c
    'content set from pdb'
-

{spoof-2.2.0 → spoof-2.2.2}/src/spoof.py

@@ -303,7 +303,7 @@ class HTTPServer(object):
         return handlerClass
 
     def start(self):
-        """Starts HTTP server thread."""
+        """Starts HTTP server thread(s)."""
         if self.server is not None:
             message = "server at {0} already started".format(self.url)
             raise RuntimeError(message)
@@ -505,10 +505,10 @@ class SSLContext(object):
         """Creates and returns file paths to self-signed certificate and key
         via OpenSSL command line tool.
 
-        :commonName: string of hostname for X509 certificate
-        :bits: RSA public key length in bits
-        :days: length in days certificate is valid
-        :openssl: name/path string of openssl command
+        :commonName:   string of hostname for X509 certificate
+        :bits:         RSA public key length in bits
+        :days:         length in days certificate is valid
+        :openssl:      name/path string of openssl command
         :keyAlgorithm: key algorithm to use (e.g. mldsa65); ignores ``bits`` arg
         """
         if keyAlgorithm is None: