wireproxy: The Python Proxy That Turns Packet Surgery Into Normal Code

Most proxies make you think like an operator. wireproxy asks you to think like a programmer. Its useful trick is that a synchronous Python script can steer an asynchronous interception engine without forcing you to babysit event loops or addon lifecycles.

That matters when the job is not passive observation. It matters when you want to pause one request, rewrite a body, synthesize a response, or wait until a very specific call appears before continuing a test. The project is interesting because it hides the machinery without hiding the control surface.

The proxy that behaves like a Python object

The core experience is simple: create the proxy, point traffic at it, then talk to requests and responses as if they were ordinary Python objects. Instead of treating network interception as a separate toolchain, wireproxy makes it feel like application code with a few powerful methods attached.

That design choice changes the rhythm of testing. A browser automation flow can wait for a request, inspect its parameters, mutate the payload, and decide whether to forward it or short-circuit it. The proxy is still doing proxy work, but the user sees a compact API.

from wireproxy import create

proxy = create(port=8080)

@proxy.request_interceptor
def on_request(request):
    if request.path.startswith('/checkout'):
        request.params['debug'] = '1'
        return request.mock_response(status=503, body='temporarily unavailable')

match = proxy.wait_for_request('/api/session')
print(match.url, match.method)

Why the wrapper matters

The interesting gap here is between what browser tools expose and what wire-level interception exposes. Browser automation can click and type, and proxy tools can inspect traffic, but wireproxy tries to unify both into one programmable workflow.

That makes it especially useful for integration tests. The classic pattern is waiting for a network event that proves a side effect happened. In a normal proxy setup, that often means scraping logs or wiring together separate tools. Here, it can be a direct method call.

The result is less ceremony. Instead of building a little operational stack around your test, you get a proxy surface that feels like part of the test itself.

Under the hood: thread, event loop, addon

The architecture is opinionated. A backend entry point starts the proxy in a background thread, while the server layer bridges the synchronous user script and the asynchronous mitmproxy core. The handler sits in the middle and translates low-level flow events into wireproxy's simpler request and response objects.

# Conceptual flow, simplified
proxy = create(port=8080)

# 1. create() starts a background thread
# 2. server.py installs the addon into the proxy master
# 3. handler.py receives request/response events
# 4. request.py wraps the raw flow into a friendlier object
# 5. inspect.py lets the script wait for matching traffic

The key abstraction is the bridge. The user's code stays synchronous, but the proxy engine does not have to be. That means the library can preserve the ergonomics of ordinary Python while still doing the asynchronous work needed to intercept traffic reliably.

The request object is the real product

wireproxy is not just about catching requests. It is about making requests editable. The simplified Request and Response wrappers hide the raw flow objects and expose properties for the pieces people actually want to change: URL parameters, bodies, headers, and content-aware rewrites.

That matters because proxy work is usually fiddly. If changing one field means manually reconstructing another, the tool becomes brittle. Here, the object model tries to keep those edits local and predictable.

req = proxy.wait_for_request('/api/session')

req.params['debug'] = '1'
req.headers['X-Test-Mode'] = 'on'
req.body = b'{"state":"patched"}'

# The object stays the same, but the traffic changes.

The sharpest tradeoff: vendoring the core

The most consequential design choice is the bundled mitmproxy code under wireproxy/thirdparty/mitmproxy/. That buys version control and reduces dependency drift. It also means the project owns more of the maintenance burden than a thin wrapper would.

This is not a neutral choice. Vendoring makes the system more self-contained, but it also means updates are manual, security fixes are less automatic, and the project takes on a larger surface area than a pure adapter layer would.

How it compares to the usual tools

wireproxy is easiest to understand in contrast with the usual choices. Browser-native tools give you UI control but less network-level shape. Direct mitmproxy scripting gives you power but asks you to live closer to the engine. Manual proxy tools are excellent for inspection, but they are less natural when the real requirement is, "control this from code."

The point is not that wireproxy is universally better. It is that it optimizes for a specific job: code-driven traffic control with just enough abstraction to keep the test readable.

Who this is for

This is for QA engineers, infra-minded developers, and browser automation builders who want a programmable proxy surface instead of a GUI. It is also for anyone who has ever needed to wait for a request, rewrite it, and decide the next step without leaving Python.

It is not the simplest option for passive traffic inspection. If all you need is a one-off look at outbound requests, a standard proxy viewer may be enough. wireproxy earns its keep when interception itself becomes part of the test logic.