mockserver-client 9.0.0__tar.gz → 9.2.0__tar.gz

{mockserver_client-9.0.0 → mockserver_client-9.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mockserver-client
-Version: 9.0.0
+Version: 9.2.0
 Summary: Official Python client for MockServer — create expectations, verify requests, and register dynamic callbacks via WebSocket
 Author-email: James Bloom <jamesdbloom@gmail.com>
 License-Expression: Apache-2.0
@@ -238,6 +238,35 @@ client.when(
 HttpRequest(headers={"keyMatchStyle": "MATCHING_KEY", "X-Tag": ["a", "b"]})
 ```
 
+A value can also be a `DateTimeMatcher`, which matches a header, query or path
+parameter, or cookie holding a date-time before, after or equal to an expected
+value (`now`, `now -1 hours`, or a date-time such as `2026-10-21T00:00:00Z`).
+A plain string such as `"before:2026-01-01"` is always matched literally.
+
+```python
+from mockserver import DateTimeMatcher, HttpRequest
+
+HttpRequest(path="/orders") \
+    .with_header("X-Issued-At", DateTimeMatcher.after("now -1 hours")) \
+    .with_header("If-Modified-Since", DateTimeMatcher.before("now").with_actual_format("rfc1123")) \
+    .with_cookie("seen", DateTimeMatcher.equal_to_date_time("now").with_truncate_actual("startOfDay"))
+```
+
+Each `with_*` option (`with_actual_format`, `with_truncate_expected`,
+`with_truncate_actual`, `with_apply_truncation_last`, `with_zone`, `with_not`)
+returns a new matcher.
+
+A JSONPath or XPath body matcher can take a `DateTimeMatcher` too: the body
+matches when a value the JSONPath selects, or the text of a node the XPath
+selects, is a matching date-time.
+
+```python
+from mockserver import Body, DateTimeMatcher, HttpRequest
+
+HttpRequest(path="/orders", body=Body.json_path("$.order.created", DateTimeMatcher.after("now -1 days")))
+HttpRequest(path="/soap", body=Body.xpath("/order/@expires", None, DateTimeMatcher.after("now")))
+```
+
 ### JWT matcher
 
 Match requests by the claims (and metadata) of a JWT carried in a header. Each
@@ -269,6 +298,32 @@ client.when(
 HttpRequest.request("/secure").with_jwt(Jwt(claims={"sub": "user-123"}))
 ```
 
+### Client IP matcher
+
+Match requests by the client IP address or CIDR range, IPv4 or IPv6. The client address is the TCP peer of the connection, not `X-Forwarded-For`; prefix with `!` to match every other address.
+
+```python
+HttpRequest.request("/internal").with_client_ip("10.0.0.0/8")
+# or HttpRequest(path="/internal", client_ip="!10.0.0.0/8")
+```
+
+### Any-of (logical OR) matcher
+
+`AnyOfRequestDefinition` matches a request when any one of its request matchers does, tried in order. Entries may be `HttpRequest`, `OpenAPIDefinition`, `ConditionalRequestDefinition` or a nested `AnyOfRequestDefinition`; `not_any_of=True` matches requests that match none of them. It serialises to `{"anyOf": [...]}` inside `httpRequest`.
+
+```python
+from mockserver import AnyOfRequestDefinition, HttpRequest, HttpResponse
+
+client.when(
+    AnyOfRequestDefinition.request_any_of(
+        HttpRequest(method="GET", path="/pets"),
+        HttpRequest(method="GET", path="/animals"),
+    )
+).respond(HttpResponse(body="pets or animals"))
+```
+
+`ExplainedExpectation.any_of` (an `AnyOfBranchComparison`) says which entry came closest when none matches.
+
 ### allOf body matcher
 
 Require a request body to satisfy **all** of several body matchers at once.
@@ -329,6 +384,40 @@ expectations = client.retrieve_active_expectations()
 logs = client.retrieve_log_messages()
 ```
 
+### Expectation metadata, unmatched expectations and paging
+
+Label expectations with metadata (string keys, any JSON value). Metadata never
+affects matching; it is returned on retrieve and lets you retrieve or clear
+just your own expectations.
+
+```python
+from mockserver import ExpectationFilter, JSON_NULL, RecordedExpectationsOptions
+
+client.when(HttpRequest.request("/api/users")).with_metadata("owner", "team-a").with_metadata(
+    "ticket", 4211
+).respond(HttpResponse(status_code=200))
+
+mine = client.retrieve_active_expectations_by_metadata("owner", "team-a")
+labelled = client.retrieve_active_expectations_by_metadata_key("owner")
+never_matched = client.retrieve_unmatched_expectations()
+page = client.retrieve_active_expectations(
+    expectation_filter=ExpectationFilter().with_metadata_json_path("$.tags[?(@ == 'smoke')]").with_offset(0).with_limit(20)
+)
+recorded_page = client.retrieve_recorded_expectations(offset=0, limit=50)
+# replay changing responses in order, keep only some request headers, move large bodies into files
+shaped = client.retrieve_recorded_expectations(
+    options=RecordedExpectationsOptions().with_repeats_as_scenarios().with_capture_headers("X-Tenant").with_extract_bodies_larger_than(1024)
+)
+
+client.clear_by_metadata("owner", "team-a")      # str compared as text, other values as JSON
+client.clear_by_metadata_key("ticket")           # any value
+client.clear_unmatched_expectations()
+```
+
+These calls raise `ValueError` before sending anything for a blank key or JSONPath,
+a `None` value (use `..._by_metadata_key` for any value, or `JSON_NULL` for a JSON
+null), a negative offset or limit, or a clear whose filter selects nothing or pages.
+
 ## Control
 
 ```python
@@ -465,6 +554,28 @@ client = MockServerClient(
 )
 ```
 
+## Control-Plane Authentication
+
+When MockServer requires a control-plane JWT, pass the token (or a supplier for a token that is refreshed). The client sends `Authorization: Bearer <token>` on every control-plane request and on the callback WebSocket used by callbacks and breakpoints; a supplier is called again on each reconnect.
+
+```python
+client = MockServerClient("localhost", 1080, control_plane_bearer_token=jwt)
+client = MockServerClient("localhost", 1080, control_plane_bearer_token_supplier=fetch_jwt)
+```
+
+When MockServer accepts control-plane Basic authentication, pass `control_plane_basic_auth=(username, password)` with `secure=True` (MockServer refuses Basic credentials without TLS). They are sent on the same requests and WebSocket; a bearer token, when also set, is sent instead.
+
+```python
+client = MockServerClient("localhost", 1080, secure=True, control_plane_basic_auth=("admin", os.environ["MOCKSERVER_PASSWORD"]))
+```
+
+When MockServer requires mutual TLS for the control plane, pass `client_cert_path` and `client_key_path` (with `secure=True` and, for a private CA, `ca_cert_path`). The client presents that certificate, and trusts that CA, on every control-plane request and on the callback WebSocket.
+
+```python
+client = MockServerClient("localhost", 1080, secure=True, ca_cert_path="ca.pem",
+                          client_cert_path="client-cert.pem", client_key_path="client-key.pem")
+```
+
 ## Domain Model
 
 All domain model classes support builder-style chaining:
@@ -568,7 +679,7 @@ launcher_path = ensure_binary()  # returns Path to the launcher executable
 ```python
 from mockserver.launcher import start
 
-server = start(port=1080, version="9.0.0")
+server = start(port=1080, version="9.2.0")
 # ...
 server.stop()
 ```

{mockserver_client-9.0.0 → mockserver_client-9.2.0}/README.md

@@ -208,6 +208,35 @@ client.when(
 HttpRequest(headers={"keyMatchStyle": "MATCHING_KEY", "X-Tag": ["a", "b"]})
 ```
 
+A value can also be a `DateTimeMatcher`, which matches a header, query or path
+parameter, or cookie holding a date-time before, after or equal to an expected
+value (`now`, `now -1 hours`, or a date-time such as `2026-10-21T00:00:00Z`).
+A plain string such as `"before:2026-01-01"` is always matched literally.
+
+```python
+from mockserver import DateTimeMatcher, HttpRequest
+
+HttpRequest(path="/orders") \
+    .with_header("X-Issued-At", DateTimeMatcher.after("now -1 hours")) \
+    .with_header("If-Modified-Since", DateTimeMatcher.before("now").with_actual_format("rfc1123")) \
+    .with_cookie("seen", DateTimeMatcher.equal_to_date_time("now").with_truncate_actual("startOfDay"))
+```
+
+Each `with_*` option (`with_actual_format`, `with_truncate_expected`,
+`with_truncate_actual`, `with_apply_truncation_last`, `with_zone`, `with_not`)
+returns a new matcher.
+
+A JSONPath or XPath body matcher can take a `DateTimeMatcher` too: the body
+matches when a value the JSONPath selects, or the text of a node the XPath
+selects, is a matching date-time.
+
+```python
+from mockserver import Body, DateTimeMatcher, HttpRequest
+
+HttpRequest(path="/orders", body=Body.json_path("$.order.created", DateTimeMatcher.after("now -1 days")))
+HttpRequest(path="/soap", body=Body.xpath("/order/@expires", None, DateTimeMatcher.after("now")))
+```
+
 ### JWT matcher
 
 Match requests by the claims (and metadata) of a JWT carried in a header. Each
@@ -239,6 +268,32 @@ client.when(
 HttpRequest.request("/secure").with_jwt(Jwt(claims={"sub": "user-123"}))
 ```
 
+### Client IP matcher
+
+Match requests by the client IP address or CIDR range, IPv4 or IPv6. The client address is the TCP peer of the connection, not `X-Forwarded-For`; prefix with `!` to match every other address.
+
+```python
+HttpRequest.request("/internal").with_client_ip("10.0.0.0/8")
+# or HttpRequest(path="/internal", client_ip="!10.0.0.0/8")
+```
+
+### Any-of (logical OR) matcher
+
+`AnyOfRequestDefinition` matches a request when any one of its request matchers does, tried in order. Entries may be `HttpRequest`, `OpenAPIDefinition`, `ConditionalRequestDefinition` or a nested `AnyOfRequestDefinition`; `not_any_of=True` matches requests that match none of them. It serialises to `{"anyOf": [...]}` inside `httpRequest`.
+
+```python
+from mockserver import AnyOfRequestDefinition, HttpRequest, HttpResponse
+
+client.when(
+    AnyOfRequestDefinition.request_any_of(
+        HttpRequest(method="GET", path="/pets"),
+        HttpRequest(method="GET", path="/animals"),
+    )
+).respond(HttpResponse(body="pets or animals"))
+```
+
+`ExplainedExpectation.any_of` (an `AnyOfBranchComparison`) says which entry came closest when none matches.
+
 ### allOf body matcher
 
 Require a request body to satisfy **all** of several body matchers at once.
@@ -299,6 +354,40 @@ expectations = client.retrieve_active_expectations()
 logs = client.retrieve_log_messages()
 ```
 
+### Expectation metadata, unmatched expectations and paging
+
+Label expectations with metadata (string keys, any JSON value). Metadata never
+affects matching; it is returned on retrieve and lets you retrieve or clear
+just your own expectations.
+
+```python
+from mockserver import ExpectationFilter, JSON_NULL, RecordedExpectationsOptions
+
+client.when(HttpRequest.request("/api/users")).with_metadata("owner", "team-a").with_metadata(
+    "ticket", 4211
+).respond(HttpResponse(status_code=200))
+
+mine = client.retrieve_active_expectations_by_metadata("owner", "team-a")
+labelled = client.retrieve_active_expectations_by_metadata_key("owner")
+never_matched = client.retrieve_unmatched_expectations()
+page = client.retrieve_active_expectations(
+    expectation_filter=ExpectationFilter().with_metadata_json_path("$.tags[?(@ == 'smoke')]").with_offset(0).with_limit(20)
+)
+recorded_page = client.retrieve_recorded_expectations(offset=0, limit=50)
+# replay changing responses in order, keep only some request headers, move large bodies into files
+shaped = client.retrieve_recorded_expectations(
+    options=RecordedExpectationsOptions().with_repeats_as_scenarios().with_capture_headers("X-Tenant").with_extract_bodies_larger_than(1024)
+)
+
+client.clear_by_metadata("owner", "team-a")      # str compared as text, other values as JSON
+client.clear_by_metadata_key("ticket")           # any value
+client.clear_unmatched_expectations()
+```
+
+These calls raise `ValueError` before sending anything for a blank key or JSONPath,
+a `None` value (use `..._by_metadata_key` for any value, or `JSON_NULL` for a JSON
+null), a negative offset or limit, or a clear whose filter selects nothing or pages.
+
 ## Control
 
 ```python
@@ -435,6 +524,28 @@ client = MockServerClient(
 )
 ```
 
+## Control-Plane Authentication
+
+When MockServer requires a control-plane JWT, pass the token (or a supplier for a token that is refreshed). The client sends `Authorization: Bearer <token>` on every control-plane request and on the callback WebSocket used by callbacks and breakpoints; a supplier is called again on each reconnect.
+
+```python
+client = MockServerClient("localhost", 1080, control_plane_bearer_token=jwt)
+client = MockServerClient("localhost", 1080, control_plane_bearer_token_supplier=fetch_jwt)
+```
+
+When MockServer accepts control-plane Basic authentication, pass `control_plane_basic_auth=(username, password)` with `secure=True` (MockServer refuses Basic credentials without TLS). They are sent on the same requests and WebSocket; a bearer token, when also set, is sent instead.
+
+```python
+client = MockServerClient("localhost", 1080, secure=True, control_plane_basic_auth=("admin", os.environ["MOCKSERVER_PASSWORD"]))
+```
+
+When MockServer requires mutual TLS for the control plane, pass `client_cert_path` and `client_key_path` (with `secure=True` and, for a private CA, `ca_cert_path`). The client presents that certificate, and trusts that CA, on every control-plane request and on the callback WebSocket.
+
+```python
+client = MockServerClient("localhost", 1080, secure=True, ca_cert_path="ca.pem",
+                          client_cert_path="client-cert.pem", client_key_path="client-key.pem")
+```
+
 ## Domain Model
 
 All domain model classes support builder-style chaining:
@@ -538,7 +649,7 @@ launcher_path = ensure_binary()  # returns Path to the launcher executable
 ```python
 from mockserver.launcher import start
 
-server = start(port=1080, version="9.0.0")
+server = start(port=1080, version="9.2.0")
 # ...
 server.stop()
 ```

{mockserver_client-9.0.0 → mockserver_client-9.2.0}/mockserver/__init__.py

@@ -1,6 +1,8 @@
 from mockserver.models import (
     AfterAction,
     AllOfBody,
+    AnyOfBranchComparison,
+    AnyOfRequestDefinition,
     BinaryResponse,
     BinaryUpstream,
     Body,
@@ -8,6 +10,7 @@ from mockserver.models import (
     CaptureSource,
     ConditionalRequestDefinition,
     ConnectionOptions,
+    DateTimeMatcher,
     CrossProtocolScenario,
     CrossProtocolTrigger,
     Delay,
@@ -18,7 +21,10 @@ from mockserver.models import (
     DnsRequestDefinition,
     DnsResponse,
     Expectation,
+    ExpectationFilter,
+    RecordedExpectationsOptions,
     ExpectationId,
+    JSON_NULL,
     ExpectationStep,
     GraphQLBody,
     GraphQLSubscriptionFilter,
@@ -165,6 +171,8 @@ from mockserver.launcher import (
 __all__ = [
     "AfterAction",
     "AllOfBody",
+    "AnyOfBranchComparison",
+    "AnyOfRequestDefinition",
     "AsyncMockServerClient",
     "BinaryResponse",
     "BinaryUpstream",
@@ -173,6 +181,7 @@ __all__ = [
     "CaptureSource",
     "ConditionalRequestDefinition",
     "ConnectionOptions",
+    "DateTimeMatcher",
     "CrossProtocolScenario",
     "CrossProtocolTrigger",
     "Delay",
@@ -183,7 +192,10 @@ __all__ = [
     "DnsRequestDefinition",
     "DnsResponse",
     "Expectation",
+    "ExpectationFilter",
+    "RecordedExpectationsOptions",
     "ExpectationId",
+    "JSON_NULL",
     "ExpectationStep",
     "GraphQLBody",
     "GraphQLSubscriptionFilter",

{mockserver_client-9.0.0 → mockserver_client-9.2.0}/mockserver/a2a.py

@@ -44,6 +44,7 @@ Example::
 from __future__ import annotations
 
 import json
+import re
 from dataclasses import dataclass, field
 from urllib.parse import urlparse
 
@@ -70,11 +71,31 @@ def _escape_json(value: str | None) -> str:
     return quoted[1:-1]
 
 
+# group 2 consumes the metacharacter after a backslash run, is empty at the end
+# and unset (empty alternative) otherwise, so no lookaround is needed
+_VELOCITY_METACHARACTERS = re.compile(r"(\\+)(?:([$#]|\Z)|)|[$#]")
+_VELOCITY_METACHARACTER_ESCAPES = {"$": "${esc.d}", "#": "${esc.h}", "": ""}
+
+
+def _velocity_escape_match(match: re.Match) -> str:
+    run, following = match.group(1), match.group(2)
+    if run is None:
+        return _VELOCITY_METACHARACTER_ESCAPES[match.group(0)]
+    if following is None:
+        return run
+    return "${esc.b}" * len(run) + _VELOCITY_METACHARACTER_ESCAPES[following]
+
+
 def _escape_velocity(value: str | None) -> str | None:
-    """Escape Velocity metacharacters so literal ``$`` / ``#`` survive rendering."""
+    """Escape Velocity metacharacters so literal ``$`` / ``#`` survive rendering.
+
+    Velocity consumes backslashes written before a reference or directive, so a
+    run of backslashes followed by ``$``, ``#`` or the end of the value is
+    escaped too; other backslashes are literal to Velocity and left as-is.
+    """
     if value is None:
         return None
-    return value.replace("$", "${esc.d}").replace("#", "${esc.h}")
+    return _VELOCITY_METACHARACTERS.sub(_velocity_escape_match, value)
 
 
 def _escape_message_pattern(pattern: str) -> str: