Skip to main content

Stubsmith Python SDK

Instrument outbound HTTP calls made by your Python application and forward them, request and response, to the Stubsmith ingest service for capture, anonymization, and replay.

Supports both requests and httpx (sync and async). Sending is non-blocking and fire-and-forget: a background daemon thread drains a bounded queue; any failure (network, serialization, queue overflow) is silently discarded and never propagates to your application.

Masking is applied in this SDK, in your own process, before any capture leaves it: the ingest service receives masked bodies plus structural names (field paths, header names, query-parameter names), never original values. A field with no explicit keep rule is masked, so a field the rules do not mention cannot leak. The server does not inspect values; the only content rules it enforces are replacing image bodies with a placeholder, and storing a path under its path pattern.


Install

# with requests support
pip install "stubsmith[requests]"

# with httpx support
pip install "stubsmith[httpx]"

# both
pip install "stubsmith[requests,httpx]"

Quickstart

import stubsmith

# One-liner: instruments both requests and httpx (whichever is importable)
client = stubsmith.install(api_key="sk-your-project-key")

# Now every outbound call is captured automatically:
import requests
resp = requests.get("https://api.stripe.com/v1/charges")

import httpx
resp = httpx.get("https://api.example.com/users")

Or configure via environment variables and call install() with no arguments:

export STUBSMITH_URL="https://ingest.stubsmith.dev/v1/captures"
export STUBSMITH_API_KEY="sk-your-project-key"
import stubsmith
stubsmith.install()

Selective instrumentation

from stubsmith import StubSmith

client = StubSmith(url="...", api_key="sk-...")
client.instrument_requests()   # only requests
# client.instrument_httpx()    # only httpx

# Remove patches later:
client.uninstrument()

Configuration

Parameter Default Description
url $STUBSMITH_URL / https://ingest.stubsmith.dev/v1/captures Full URL of the ingest endpoint
api_key $STUBSMITH_API_KEY Bearer token; empty value auto-disables the client
enabled True Master switch (also auto-disabled when api_key is absent)
timeout 5 (seconds) HTTP timeout for ingest POST
max_body_bytes 65536 (64 KiB) Retained for compatibility; no longer truncates anything
max_payload_bytes 10485760 (10 MiB) Largest capture payload sent. Over it, bodies are omitted rather than cut. Must match the server's limit
max_queue_bytes 33554432 (32 MiB) Ceiling on bytes held in the send queue, separate from queue_maxsize
compress True gzip capture payloads over 1 KiB before sending
sample_rate 1.0 Fraction of calls to forward (0.0 - 1.0)
queue_maxsize 1000 Bound on the background queue; excess items are dropped
flush_timeout $STUBSMITH_FLUSH_TIMEOUT / 1.0 (seconds) How long process exit waits for queued captures to drain. 0 disables the wait
backend_url $STUBSMITH_BACKEND_URL / https://app.stubsmith.dev/api API the masking rules are fetched from. A second host, not the ingest host
rules_poll_interval 60.0 (seconds) How often the rules cache re-polls the API for rule changes
wait_for_rules 0 (do not wait) Seconds install() blocks for the first rules sync. Raise it for short scripts (see below)
debug $STUBSMITH_DEBUG Log send and sync failures to stderr. Does not change the fire-and-forget contract

An explicit argument always wins over the environment variable, which is read only when the argument is omitted, and only once, when the client is built. install(api_key="sk-from-arg") authenticates with sk-from-arg even if $STUBSMITH_API_KEY is set to something else; nothing re-reads the environment later. That matters when the key comes from a database row or a settings table rather than the process environment.

Every parameter above is accepted by stubsmith.install(). All of them except wait_for_rules, which is a property of installation rather than of the client, are also accepted by StubSmith().

What gets patched

install() patches exactly four things, and only those:

Patched Not patched
requests.sessions.Session.request requests.request, requests.get, requests.post, ...
requests.sessions.Session.send urllib, urllib3, http.client
httpx.Client.send aiohttp
httpx.AsyncClient.send anything below the adapter (sockets, retries)

The module-level requests helpers need no patch of their own: every one of them builds a Session and calls Session.request. Patching Session.send as well covers the other entry point, a caller that builds its own PreparedRequest and sends it, which some client libraries do.

Both patch points route through each other, and send() re-enters itself once per redirect hop, so capture happens in the outermost patched frame only: one call produces one capture, and a redirect chain produces one capture describing the request you made rather than the hop it landed on. The guard is per-thread, so concurrent calls do not mask each other.

Nothing below the requests adapter is patched. urllib3 retries and socket level behaviour are invisible to the SDK, and traffic sent through urllib, http.client or aiohttp is not captured at all.

Because the patch lands on Session.request and not on the helpers, the obvious hand-rolled health check is wrong:

# WRONG - reports a working install as broken. requests.request is never patched.
assert requests.request.__module__ != "requests.api"

# Right
assert stubsmith.is_installed()

stubsmith.is_installed() returns True only while a live client is installed in this process: False before install(), False after close(), and False in a forked child whose client could not be revived.

Network egress and background threads

install() talks to two hosts, which matters if you allow-list egress:

Host Direction Purpose
ingest.stubsmith.dev outbound POST masked captures (POST /v1/captures)
app.stubsmith.dev outbound GET masking rules (GET /v1/sdk/sync), polled every rules_poll_interval seconds (default 60)

Both are overridable (url and backend_url) for a project pointed at a different environment.

The SDK sends only over https. A plain http:// URL is accepted only for localhost, 127.0.0.1 and ::1, for a backend on your own machine. With any other http:// URL for url or backend_url, install() logs a warning and capture stays off, so nothing is sent; stubsmith pull and fixtures() raise an error instead. The SDK never follows a redirect: a 3xx answer is treated as an error, so the API key is never re-sent to another URL.

It also starts exactly two daemon threads: stubsmith-sender (drains the capture queue) and stubsmith-rules-cache (polls for rules).

Those names are Python-level only. CPython does not set the operating system's thread name from Thread(name=...), so a native thread dump or /proc/<pid>/task/*/comm shows python for both and tells you nothing. To check for them, read threading.enumerate():

[t.name for t in threading.enumerate() if t.name.startswith("stubsmith-")]

To assert that capture is armed, use stubsmith.is_installed() rather than inspecting threads at all.

Captures are compressed in transit

Payloads over 1 KiB are sent with Content-Encoding: gzip. Masked bodies are dominated by repeated "<masked>", so they compress by roughly two orders of magnitude: a 219 KB body measures 843 bytes gzipped, and a real capture measured 111,110 bytes uncompressed against 477 on the wire. Set compress=False to disable.

The size ceiling is applied before compression, on the uncompressed payload, and stays there. Limiting compressed bytes instead would be a decompression bomb: at these ratios a payload comfortably under the limit compressed can expand to hundreds of megabytes on the server.

Bodies are never truncated

A captured body is recorded whole or not at all. There is no byte count at which a JSON document is still a JSON document, so cutting one to fit produces a sample that cannot parse and is indistinguishable from an API that genuinely returned malformed JSON. Replaying such a sample raises JSONDecodeError and the blame lands upstream, on a failure that never happened.

When an assembled payload exceeds max_payload_bytes, both bodies are dropped together and the capture is sent with bodies_omitted. The server records the request shape, its occurrence count and the response variant, stores no sample, and raises a dashboard alert. The endpoint stays visible; nothing half-captured is stored.

Both bodies go, not only the larger, so the outcome does not depend on which side happened to be big and no consumer has to reason about a capture with one body present.

The SDK logs a warning naming the endpoint and the sizes, once per endpoint rather than per call. Fire-and-forget means never break your application, not never say anything: an endpoint whose payloads are permanently too large is a condition worth knowing about, and silence is what kept the earlier truncation behaviour unnoticed.

max_payload_bytes must match the server's limit, because they measure the same thing. If the SDK's were larger, captures between the two limits would be masked, queued, transmitted and then discarded by the server.

An unreachable rules API degrades open, not closed. A failed sync is logged at debug level and leaves the last known-good rules in place; it never raises and never stops capture. Because masking is fail-closed, a client that has never reached the API masks everything and still delivers captures: you get novel=true and no cleartext, not silence. A rejected key (401) behaves the same way.

install() is idempotent and fork-safe

Calling install() again returns the client already installed in this process rather than building another one, so a plugin registry or framework hook that fires repeatedly cannot accumulate threads. Arguments are ignored on those subsequent calls; call close() on the existing client first to reconfigure.

fork() copies only the calling thread, so a forked child would otherwise inherit a dead sender and a queue nothing drains. The client re-arms itself in the child, which is what makes install() in a pre-fork master work: gunicorn --preload, uWSGI, Celery's default pool and Odoo's worker model all capture in every worker. The child starts from an empty queue, because the parent still holds anything that was pending at the moment of the fork and will send it itself.

Both properties matter together in an embedded plugin. Odoo, for example, calls a module's post_load once in the pre-fork master and _register_hook on every registry load: the first needs fork safety to capture anything at all under workers > 0, the second needs idempotence not to leak a pair of threads per reload. Either call site works, and calling from both is harmless. On a version before 0.2.0 neither holds, so install per worker instead and guard on the pid.

An outage cannot block your application

Captures are masked on the calling thread (CPU only, no I/O) and handed to a bounded queue with a non-blocking put. A daemon thread does the HTTP POST and swallows every exception. If the ingest service is slow, unreachable or returning errors, your request path is unaffected: the queue fills, excess captures are dropped, and nothing propagates to your code.

Measured with the ingest host blackholed, so every POST runs to its timeout: a median of 0.32 ms and a p95 of 0.45 ms added to an instrumented call.

The one place an outage is visible is process exit, where an atexit hook waits for the queue to drain. That wait is capped at flush_timeout, and is abandoned as soon as a send fails, so an unreachable endpoint costs about a second rather than the full budget. Set STUBSMITH_FLUSH_TIMEOUT=0 in a serverless function or anywhere else exit latency is billed; captures still in the queue are discarded.

Errors are swallowed, refusals are not. Ingest can accept the HTTP request and still decline the capture: at the fingerprint cap it answers 200 with {"ok": false, "error": "fingerprint_limit_reached"}, and a quarantined or rejected shape answers 422 with the same ok: false body. The SDK reads that body and logs one WARNING on the stubsmith logger per distinct error code per process, naming the code, the HTTP status, the consequence and the remedy. Once per code rather than per capture, so a capped project cannot flood a test run; never raised, so the fire-and-forget contract holds. With debug on, the full response body is also logged for every refusal.


How it works

  1. install() / instrument_requests() / instrument_httpx() patches requests.sessions.Session.request and .send, plus httpx.Client.send / httpx.AsyncClient.send (idempotent; repeated calls are a no-op, see What gets patched).
  2. Each call is timed; request headers/body and response status/headers/body are captured without consuming streams - if you opened a streaming response the SDK skips the body rather than interfering.
  3. Captures are placed on an in-process queue.Queue; a daemon thread drains it and POSTs to POST /v1/captures with Authorization: Bearer <api_key>.
  4. On process exit an atexit handler flushes the queue (bounded timeout).

What a capture looks like on the wire

This is the artifact to hand a security reviewer. Given this call, against an endpoint whose fingerprint has not been approved yet (the worst case for disclosure, since no keep rule exists):

requests.get(
    "https://api.example.com/v1/orders/1042?limit=50&include=customer",
    headers={"X-Request-Id": "abc-123"},
)

returning this response body:

{
  "id": "4c1f2a80-2f1e-4a2f-9f7a-2b1c6f0d9e11",
  "customer": {"name": "Alice Martin", "email": "alice@example.com"},
  "iban": "NL91ABNA0417164300",
  "amount": "149.95",
  "paid": true
}

the SDK sends exactly this to POST https://ingest.stubsmith.dev/v1/captures, with Authorization: Bearer <your project key> and User-Agent: stubsmith-sdk/0.6.0:

{
  "sdk_version": "0.6.0",
  "sdk_masked": true,
  "sdk_rule_version": "0",
  "domain": "api.example.com",
  "path_template": "/v1/orders/{id}",
  "path": "/v1/orders/{id}?limit=%3Cmasked%3E&include=%3Cmasked%3E",
  "method": "GET",
  "status": 200,
  "req_fingerprint": "0ac4da02636b9927",
  "resp_fingerprint": "2004bc1bf2471fe533f",
  "key_paths": [],
  "resp_key_paths": [
    "id", "customer", "customer.name", "customer.email",
    "iban", "amount", "paid"
  ],
  "req_header_names": ["accept", "accept-encoding", "connection", "user-agent", "x-request-id"],
  "resp_header_names": ["content-type", "date", "server"],
  "query_names": ["limit", "include"],
  "headers": {
    "User-Agent": "<masked>",
    "Accept-Encoding": "gzip, deflate, zstd",
    "Accept": "*/*",
    "Connection": "<masked>",
    "X-Request-Id": "<masked>"
  },
  "req_body": "<masked>",
  "resp_headers": {
    "Server": "<masked>",
    "Date": "<masked>",
    "content-type": "application/json"
  },
  "resp_body": "{\"id\": \"<masked>\", \"customer\": {\"name\": \"<masked>\", \"email\": \"<masked>\"}, \"iban\": \"<masked>\", \"amount\": \"<masked>\", \"paid\": false}",
  "novel": true,
  "resp_value_types": {
    "id": "uuid",
    "customer.name": "free_text",
    "customer.email": "email",
    "iban": "iban",
    "amount": "decimal_amount"
  },
  "source": "python-requests",
  "duration": 2
}

Reading it:

  • No original value appears in this capture, including in the URL: the path is templated (1042 becomes {id}) and query values are masked while their names survive. paid: true masked to false because a boolean's masked form is false, not because the value was read. The literal values here are "Accept": "*/*" and "Accept-Encoding", allowlisted transport headers a stub needs in order to be replayed.
  • Six header values are always sent as they are, in requests and responses: content-type, content-length, accept, accept-encoding, host and transfer-encoding. Every other header value, user-agent, cache-control and accept-language included, is <masked> unless a keep rule keeps it. Header names, like JSON keys, form field names and query parameter names, are structure and are sent as they are. In a form body that is all key=value pairs, whatever stands before each = is a name, so free text such as Hi Bob, ref=123 sends Hi Bob, ref as a name.
  • key_paths and resp_key_paths are names only. They are what you review in the Request Types editor, and what a field_rules entry addresses.
  • resp_fingerprint is the status code followed by a 16-character digest. 2004bc1bf2471fe533f is 200 and 4bc1bf2471fe533f, not a 19-character hash: the same response shape returned with a different status is a different recorded response. req_fingerprint carries no prefix.
  • novel: true and sdk_rule_version: "0" say no approved rules were in effect, which is why everything is masked. Once you approve the fingerprint with keep rules, the kept scalars appear here verbatim - that is the point of the review step, and the only way a real value deliberately reaches Stubsmith. A keep rule can sit on a body field, a query parameter or a header. Two things fall outside it: a path segment that neither the normalisation heuristic (all digits, UUID-shaped, or 16 or more hex characters) nor one of your curated request-type templates collapses, which is sent as written, and the allowlisted transport headers above.
  • resp_value_types is a label, not a masking decision. The SDK reads each value to recognise its format, so "iban" means the string parsed as an IBAN. Only the label is sent. Nothing is masked or kept because of a label: that is decided by your rules alone.
  • sdk_masked: true is what the ingest service requires; a payload without it is rejected with 400 sdk_required, so an unmasked body cannot be posted through this endpoint at all.

To see this for your own traffic before pointing the SDK at Stubsmith, run python -m http.server-style ingest of your own: set url="http://127.0.0.1:PORT/v1/captures" and log what arrives.


Fingerprint value discrimination

By default the SDK fingerprints each request by its body structure (key-paths), query parameter names, and Content-Type. Endpoints that multiplex operations via a body field (e.g. {"action": "login"} vs {"action": "delete_user"}) therefore produce a single fingerprint, which means a single review and a single privacy-rule set for both variants.

Enable value discrimination on action in the Stubsmith UI or via the API and the SDK will automatically include that field's value in the hash:

# No SDK change required - configure via the UI or API, then the SDK picks up the
# new value paths on its next rules-sync poll (default: every 60 seconds).
import stubsmith
stubsmith.install(url="...", api_key="sk-...")

import requests
requests.post("https://api.example.com/rpc", json={"action": "login", "username": "alice"})
# → fingerprint A  (action=login)

requests.post("https://api.example.com/rpc", json={"action": "delete_user", "user_id": 42})
# → fingerprint B  (action=delete_user) - separate review, separate rules

See the fingerprinting documentation for the hash mechanics, all three configuration methods, and the privacy guarantees.


Offline replay in tests

stubsmith.replay() serves recorded responses to your code's outbound HTTP calls. Inside the block no network call is made and the dependency does not need to be running.

import stubsmith

def test_charge_is_declined():
    with stubsmith.replay():
        with pytest.raises(CardDeclined):
            PaymentClient().charge(amount_cents=950_000, currency="USD")

Fetch the bundle once and commit it:

export STUBSMITH_API_KEY=<your project key>
stubsmith pull --out .stubsmith/bundle.json

python -m stubsmith pull does the same thing. It resolves the package from sys.path, so it runs a checkout without installing it, and it cannot pick up a stale installed copy in place of the one you are working on.

From then on the test suite needs no key, no network and no pull step - it reads the committed file. Refresh it when the recording should change: the upstream API's shape changed, you added a call the bundle does not cover, or you approved new fingerprints. Treat it like a lockfile or a golden file: an occasional, reviewed, committed change.

replay() finds the bundle without configuration - an explicit path, then $STUBSMITH_BUNDLE, then an upward search from the working directory that stops at the first directory containing .git or pyproject.toml. Pass a path or a dict to be explicit:

with stubsmith.replay("tests/data/bundle.json"):
    ...

Every recorded response, not just the newest

replay() serves one response per request shape: the newest recording of the status that occurred most often. That leaves everything else in the recording unexercised, which is usually where the bugs are. Stubsmith keeps a rolling window of recent samples for each distinct response a shape returned, so the 429 and the 500 your API really produced are sitting there unused.

replay_all() runs the block once per recorded response. Pass statuses to loop one kind:

def test_parses_every_recorded_success():
    for attempt in stubsmith.replay_all(statuses={200}):
        with attempt:
            result = connector.sync_orders()
        assert result.orders is not None


def test_degrades_on_every_recorded_failure():
    for attempt in stubsmith.replay_all(statuses={429, 500}):
        with attempt:
            with pytest.raises((RateLimited, UpstreamUnavailable)):
                connector.sync_orders()

Filter by status unless you have a reason not to. It decides what a red build means. Unfiltered, the loop feeds successes and failures into one test body, so the body has to hold for both; the day a 500 first appears in the window, assertions written when only 200s existed start failing, and the build breaks because the recording changed rather than because the code did. That is the opposite of what a failing test should tell you.

Filtered, every pass is the same kind of response, the assertions can be specific, and a failure means your code cannot handle a response your API genuinely returns. The filter also bounds the work: unfiltered, the pass count is roughly (samples per response) x (distinct statuses) and grows with traffic on its own.

A shape with recordings but none of the requested status raises StubNotFound, naming the filter and listing the statuses it does have. Serving a different one would make the loop assert against a response it was told to exclude.

If you do loop unfiltered, assert only on what every recording shares:

for attempt in stubsmith.replay_all():
    with attempt:
        try:
            result = connector.sync_orders()
        except (RateLimited, UpstreamUnavailable):
            continue          # a recorded failure, surfaced as a declared one
    assert result.orders is not None

You never name an endpoint. Which ones a pass touches is discovered by running your code, so this works for a connector whose call sequence you would rather not spell out, and for one whose sequence changes between passes because it branches on the response it got: an endpoint first reached on pass four still gets looped from its own first recording.

Pass one serves exactly what replay() serves, so a test that passes under replay() still passes on the first pass. Iteration stops when every shape that was actually touched has served its last recording. A shape with a shorter window keeps serving its final recording rather than raising, so one endpoint's thin history never truncates the loop for everything else.

What this asks of the test body is real: it runs against a 200 on one pass and possibly a 500 on the next, so the assertions have to hold across the whole recorded range. That is the point, and it is also why replay() remains the right tool for a test written against one known response.

To pin a single response instead, pass select:

def test_backs_off_when_rate_limited():
    with stubsmith.replay(select=stubsmith.by_status(429)):
        with pytest.raises(RateLimited):
            connector.sync_orders()

by_status raises StubNotFound when no recording of that status exists, rather than quietly serving a different one - a rate-limit test that silently ran against a 200 would pass while testing nothing. select receives every recording as a list and returns one, so any other rule is a lambda away.

Either way, served() reports what actually ran, so a test can assert coverage instead of assuming it:

with stubsmith.replay() as r:
    connector.sync_orders()
assert {s.status for s in r.served()} == {200}

Each entry carries endpoint, status, capture_id, captured_at, and index/total/exhausted describing its place in the shape's window.

Getting the window into the bundle

A default bundle holds one recording per response, so replay_all() would give one pass per status. Ask for the window explicitly:

stubsmith pull --endpoint "GET /admin/orders" --samples all \
  --out tests/bundles/admin-orders.json

--samples above 1 requires --endpoint: the full window for a whole project is not served. Repeat --endpoint to cover several in one file, which is one request per endpoint, merged for you:

stubsmith pull --samples all \
  --endpoint "GET /admin/orders" \
  --endpoint "GET /admin/products" \
  --out tests/bundles/admin.json

Per-endpoint scoping is what you want anyway: a project-wide bundle is capped at 2000 request shapes, and what it drops is reported in truncated rather than carried.

Or fetch at collection time, with no file involved:

BUNDLE = stubsmith.fetch_bundle("GET /admin/orders", samples="all")

def test_every_recorded_response():
    for attempt in stubsmith.replay_all(BUNDLE):
        with attempt:
            connector.list_orders()

Fetch once at module level, not per test - it is a blocking HTTP call. It needs a live key wherever the tests run, and live recordings roll as the window rolls, so a failure you see today may not reproduce next week. Fetch live while iterating locally; commit a pulled bundle for CI.

That split matters more under replay_all() than under replay(). With a committed bundle the loop runs the same passes until someone re-pulls, and a new recording arrives as a reviewable file change. Fetching live, the number of passes and the responses in them change as staging traffic changes, so a build can turn red with no commit behind it.

Matching

A request is matched on (domain, method, path_template, fingerprint). The fingerprint covers body key-paths, query parameter names and the normalised content-type - not values, and not the host or path, which is why the other three parts of the key are needed. Every body-less GET shares one fingerprint.

Dynamic path segments are templated from the recording, so /api/users/4821 matches a stub recorded as /api/users/{id}.

When nothing matches

StubNotFound is raised with a diff of what was sent against the closest recording, naming the fields that differ. It never falls through to the network, so a test cannot silently start calling a real service.

A stub whose fingerprint has no recorded captures is reported as degraded by stubsmith pull and raises the same error at replay time, rather than serving an empty response.

See examples/fixtures-testing/ for a complete worked example: a real service, a client instrumented with the SDK, traffic captured and reviewed, and a test suite that passes with the service stopped.

Single-fixture helpers

stubsmith.testing handles individual fixture files rather than a whole bundle, for cases where you want one recorded exchange registered against responses:

pip install "stubsmith[testing]"
from stubsmith import testing

bundle = testing.load_bundle("fixtures/get_user.json")
testing.register_template(responses, bundle, base_url="http://api")

It also provides assert_request_matches_fixture and assert_body_schemas_match as contract guards. For a normal test suite replay() is the simpler path - it covers every recorded endpoint at once and needs no per-fixture registration.


Masking and placeholders

Values are masked in the SDK, before a capture is uploaded: the server never receives the originals. A field with no keep rule is replaced. A kept value is sent as it is: the SDK has no built-in patterns of its own, so only your keep rules, field masks and regex masks decide what is masked.

By default the replacement is a constant ("<masked>", 0, False) matching the original's type.

Setting STUBSMITH_MASK_SALT to any non-empty string switches on format-preserving placeholders for fields carrying a semantic type hint (email, uuid, iso8601, e164, iban, url, decimal_amount, integer_id, opaque_token, free_text). The replacement then has the same shape as the original - a parseable timestamp, an RFC 4122 UUID, an IBAN with a correct mod-97 checksum - so code that parses or validates these values still works against a recording. The same salt and value always produce the same placeholder, which preserves uniqueness and cross-field references. The salt never leaves the process.

The salt only affects fields that carry a semantic type hint, and those hints come from an approved fingerprint's field_rules. Before a fingerprint has been reviewed the capture reports sdk_rule_version: 0, no field has a type hint, and every masked value is the constant form no matter what the salt is set to. Setting a salt and seeing "<masked>" therefore means "not approved yet", not "salt ignored".

Two types are never format-preserved, regardless of salt: currency_code and country_code. Booleans are refused for the same reason. Their domains are small enough that a keyed hash could be reversed with a lookup table. Use action: keep for those fields instead - they are rarely sensitive.


Changelog

0.8.1

The SDK sends only over https. Captures, the rules sync, stubsmith pull and fixtures() used to send to any URL they were given, including a plain http:// one, so a mistyped STUBSMITH_URL sent captures and the API key unencrypted. A plain http:// URL is now accepted only for localhost, 127.0.0.1 and ::1. With any other http:// URL for url or backend_url, install() logs a warning and capture stays off, and nothing is sent. stubsmith pull and fixtures() raise an error. The SDK also no longer follows redirects: it used to re-send the API key to wherever a 3xx pointed, including a plain http:// URL, and now treats a 3xx as an error. What to check: if you point the SDK at your own backend over plain http on another host, put it behind https, and point it at the final URL, not one that redirects.

0.8.0

The SDK no longer scrubs kept values for emails and card numbers. Earlier releases replaced email addresses and 16-digit numbers inside kept strings with <masked>, but only until the project had any global rule, so some projects had this and others did not. It is removed. What decides masking is now only your own rules: a field without a keep rule is masked as before, and a kept field is sent as it is, even when it holds an email address or a card number.

What to check: look at the fields you keep. If a kept field can hold an email address, a card number or other personal data, remove the keep rule, or add a field mask or regex mask for it in the project's global rules.

Value-type labels never mask. The SDK still recognises formats such as email or iban and reports them as labels in req_value_types and resp_value_types. A label is only a label: it never masks or keeps a value.

A customer rule that cannot be used masks instead of being skipped. A regex mask whose pattern does not compile used to be dropped without a word, so the values it was meant to mask went out, and a malformed entry in the project's global rules (for example a pattern that is not a string) made the SDK ignore all of them, field masks included. Now the valid rules still apply, every kept string is masked while such an entry is in the rules, and one WARNING on the stubsmith logger names it. Fix or remove the entry to get kept values back.

Fixed: a free-text body labelled as a form is masked as a whole. A request or response body with Content-Type: application/x-www-form-urlencoded that is not key=value pairs, such as free text, was sent with the whole text as a field name. A form body in which any &-separated part has no = is now sent as <masked>, and no field names or value types are taken from it.

Fixed: URL credentials are no longer sent. For a URL such as http://user:password@host/, the capture's domain held user:password@host. It now holds only the host and port. replay() matches such a URL on its host and port as well. A bundle pulled from captures recorded with such a URL by an earlier release holds the credentials in its domain and no longer matches; record and pull it again.

User-Agent, Cache-Control and Accept-Language values are masked by default. All three can carry data about your users or your customers, so they are no longer on the header allowlist. In requests and responses their values are sent as <masked> unless you keep them: a header.user-agent, header.cache-control or header.accept-language keep rule for the request, resp_header.user-agent, resp_header.cache-control or resp_header.accept-language for the response. The names are still sent. Replayed responses carry Cache-Control: <masked> unless you keep resp_header.cache-control. The six values still sent as they are: content-type, content-length, accept, accept-encoding, host and transfer-encoding.

Regex masks are not run on very long strings. While a regex mask is active, a kept string longer than 65,536 characters is masked without running any pattern, so a pattern that backtracks badly cannot stall your requests.

Turning off automatic ID grouping in paths. The SDK turns path segments that look like IDs (all digits, a UUID, or 16 or more hex characters) into {id}. A project can now turn that off with the dashboard setting "Group IDs in paths automatically". When it is off, only the project's path patterns group paths, and every other segment is sent as written. The SDK reads the setting from project_settings in the rules sync, and replay reads it from the bundle, so replay groups paths the way capture did. Until a sync says otherwise the setting is on, which is the behaviour of earlier releases.

Captures made before the first sync wait for it. A capture processed before the first rules sync used to be sent with IDs grouped even on a project that turned grouping off, so the same endpoint could arrive as /orders/{id} and then as /orders/123. The sender now holds such a capture, for at most 5 seconds from client start, until the sync arrives, and then applies the project's setting. If no sync arrives in that time it is sent as before, and a flush(), including the one at exit, sends held captures at once. The application's own requests are never delayed.

Value-type labels and ID rules come from a shared spec. The labels the SDK reports for observed values and the rules for ID segments are generated from tools/classifiers/classifiers.json, the same spec the Stubsmith server uses. Captures now carry classifier_spec_version, so the server can tell which version of the labels a capture used. The labels and rules themselves are unchanged.

0.7.1

A 404 from rules sync no longer sends cleartext. When GET /v1/sdk/sync answered 404, usually because backend_url pointed at the wrong host or path, the SDK fell back to the old /v1/anonymizer/rules endpoint and treated every request as already reviewed. Bodies and query values went out with only the named fields masked, marked novel: false. That fallback is gone. A 404 now leaves the rules as they were, so a request without synced rules is masked in full and marked novel, and one WARNING on the stubsmith logger names the 404 and the configured backend_url. rules_synced stays False until a sync succeeds.

Project field masks apply to kept fields. Once rules had synced, the field_masks of the project's global rule sets were ignored, so a field kept by a path rule went out as is even when its name was listed as a field mask, for example a kept password. A field whose name matches a field mask is now masked even when a rule keeps it: a JSON key and everything beneath it, a form field, a query parameter or a header. Names compare case-insensitively.

0.7.0

Ingest refusals are reported. Ingest can accept the request and still decline the capture: at the fingerprint cap it answers 200 with {"ok": false, "error": "fingerprint_limit_reached"}, and a quarantined or rejected shape answers 422 with the same ok: false body. The SDK read the status and discarded the body, so a project at its cap recorded nothing new and said nothing, even in debug mode. The body is now parsed and each distinct error code is logged once per process at WARNING on the stubsmith logger, with the code, HTTP status, consequence and remedy. Nothing is raised and nothing blocks. With debug on, the full response body is also logged for every refusal.

0.6.0

Captures are gzipped in transit. Payloads over 1 KiB are sent with Content-Encoding: gzip. Masked bodies compress by roughly two orders of magnitude, so this is close to free bandwidth; compress=False disables it. The size ceiling is still applied to the uncompressed payload, because limiting compressed bytes would let a payload under the limit expand to hundreds of megabytes on the server.

body_encoding is honoured on replay. The field records that a stored body is not the response itself: the SDK sets it to base64 when it substitutes a 1x1 placeholder for an image. Replay ignored it, so an image recording was served as base64 text to code expecting image bytes. It is now decoded, and an unrecognised or malformed encoding falls back to the literal text rather than raising, so a stub's encoding cannot take a test suite down.

0.5.0

Bodies are never truncated. A body is recorded whole or not at all. Truncating to max_body_bytes sliced JSON mid-token and stored a document that could not parse, with nothing in the payload to say so, so a truncated capture looked exactly like an API that had returned malformed JSON. A replayed sample raised JSONDecodeError and consumers reported an upstream failure that had never happened.

New: max_payload_bytes, default 10 MiB. The size question is answered on the assembled payload rather than on individual bodies, because that is the quantity the server can also measure. Over the ceiling both bodies are omitted and bodies_omitted is set: the server records the request shape, its occurrence count and the response variant, stores no sample, and raises a dashboard alert, so the endpoint stays visible without anything half-captured being stored. The SDK logs a warning naming the endpoint and sizes, once per endpoint.

New: max_queue_bytes, default 32 MiB. queue_maxsize bounds items, not bytes, so with megabyte-scale payloads a full queue could hold gigabytes inside the application the SDK is instrumenting.

max_body_bytes is still accepted and no longer truncates anything.

0.4.0

New: replay_all(statuses={...}). Loops only recordings of the given statuses, so one loop can be exhaustive about success bodies and another about failure handling, with assertions specific to each. Without it a loop mixes both into one test body, and a status entering the window later breaks assertions written when only the other kind existed, turning a red build into news about the recording rather than about the code. A shape with recordings but none of the requested status raises StubNotFound naming the filter, rather than substituting a response the loop was told to exclude.

stubsmith pull --endpoint can be repeated. --samples above 1 needs an endpoint, so covering several endpoints previously meant one pull per endpoint and merging the files by hand. Each endpoint is now one request and the responses are merged, deduplicating fingerprints and carrying truncated through.

Corrected: the background threads are not named at the OS level. The egress section said they were "identifiable in a thread dump", which sent at least one reader to /proc/<pid>/task/*/comm, where CPython shows python for both because it does not set the native thread name from Thread(name=...). The names are visible through threading.enumerate(); is_installed() is the supported way to check that capture is armed.

Nothing in this release changes existing behaviour: replay() with no arguments serves the same response it did in 0.2.0, and a bundle pulled without --samples is byte-identical.

0.3.0

New: replay_all(), for looping every recorded response. replay() serves one response per request shape, the newest recording of the most frequent status, which leaves the rest of the rolling sample window unexercised: the 429 and the 500 the API really returned are recorded and never tested against. replay_all() runs a block once per recording.

No endpoint is named: which shapes a pass touches is discovered by running your code, so a connector whose call sequence changes between passes, because it branches on the response it got, still works. An endpoint first reached on a later pass is looped from its own first recording rather than starting partway through. Pass one serves exactly what replay() serves, so moving an existing test to replay_all() does not change what the first pass asserts.

New: replay(select=...) and by_status(). Pin a single recorded response, for a test written against one known outcome. by_status() raises StubNotFound when no recording of that status exists rather than serving a different one, so a rate-limit test cannot silently pass against a 200.

New: ReplayContext.served(). Reports which recordings actually ran, with the endpoint, status, capture_id, captured_at and position in the shape's window, so a test can assert its coverage instead of assuming it.

New: fetch_bundle() and stubsmith pull --samples. A bundle carries one recording per response by default, so --samples N or --samples all is what puts the window into one; it requires --endpoint, since the full window for a whole project is not served. fetch_bundle() fetches without going through a file, for a suite that wants current recordings at collection time. Previously the only route to that was importing stubsmith.cli._fetch_bundle, which is private and carried no compatibility promise.

0.2.0

Captures are no longer lost in forked workers. Threads do not survive fork(), so a child inherited a dead sender and a queue nothing would drain: under gunicorn --preload, uWSGI or Celery, where install() runs in a master and workers are forked, every capture in every worker was enqueued and silently discarded. The client now re-arms itself in the child.

install() is idempotent. It returns the client already installed in this process instead of building another one. Previously each call added a sender thread, a rules-cache poller, an atexit hook and a 60-second backend poll, and left every client but the most recent inert while still polling.

Key paths are reported from every array element, not just the first. For an array whose first entry is a scalar or null, the shape of the objects after it was never reported, so those fields could not be given a keep rule and stayed masked with no way to discover why. This changes the fingerprint of any request or response containing arrays whose elements differ in shape: those endpoints reappear in the review queue as novel and need approving once more. Approvals for every other endpoint are unaffected.

A prepared request sent with Session.send() is now captured. Only Session.request was patched, so a caller that built its own PreparedRequest was silently invisible: no error, no fingerprint. Both entry points are patched now, with capture in the outermost frame only, so a single call still produces exactly one capture and a redirect chain still produces one.

install() accepts flush_timeout. It was settable only by constructing StubSmith directly or through $STUBSMITH_FLUSH_TIMEOUT, which a process that does not control its own environment could not use.

New: stubsmith.is_installed(). A supported way to assert that capture is armed, instead of guessing at which attribute the patch replaced.

Documented: what gets patched, both egress hosts, both thread names, argument versus environment precedence, and an annotated capture payload. The README previously said masking was applied server-side, which is the opposite of what the SDK does.

Process exit no longer waits on an unreachable ingest host. The at-exit flush had the same five-second budget as an explicit flush(), so a short-lived script or serverless invocation paid it in full whenever Stubsmith was unreachable. The budget is now one second, configurable with flush_timeout or $STUBSMITH_FLUSH_TIMEOUT, and abandoned as soon as a send fails.


Development / tests

python3 -m venv .venv && . .venv/bin/activate
pip install -e '.[test]'
python -m pytest -q

Metadata

Release files for stubsmith 0.8.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for stubsmith 0.8.1
File Size Uploaded Provenance Actions
stubsmith-0.8.1.tar.gz 235.2 kB With provenance Details for stubsmith-0.8.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for stubsmith 0.8.1
File Interpreter ABI Platform Actions
stubsmith-0.8.1-py3-none-any.whl Python 3 none any Details for stubsmith-0.8.1-py3-none-any.whl

Total release size: 355.5 kB

Release files / stubsmith-0.8.1.tar.gz

Download URL stubsmith-0.8.1.tar.gz
Size 235.2 kB
Tags Source
SHA-256 checksum
How to use checksums
5c2e7cbb40b3a8910ffab6b94a30fda711964b8fc789fef5530938917c312efd
BLAKE2b-256 checksum
How to use checksums
b23484e73c65d29dbdc37b065be9b4e674cb3d6c0d0569d866de73474443b6e5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

Release files / stubsmith-0.8.1-py3-none-any.whl

Download URL stubsmith-0.8.1-py3-none-any.whl
Size 120.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cc3e64bff4574eaa5ea19de847e7e4cd9b26ac182bdb576e65d411dddd6c3aa6
BLAKE2b-256 checksum
How to use checksums
aebcc961579c3bb35e3fcc8b2e92b46ddb6efbaee7b8075449f5487e73bf4481
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

Security for stubsmith 0.8.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for stubsmith-0.8.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page