This page is the parent section for all practical, user-facing documentation for python-mocket. It covers how to activate mocking, register entries, verify requests, and configure advanced behaviors like strict mode and VCR recording. It assumes the library is already installed; for installation instructions see page 2. For an explanation of how mocket works internally, see page 3.
Each major feature is described briefly below, with a pointer to its dedicated sub-page.
There are two ways to activate mocket in a test: a decorator or a context manager. Both ultimately call the same underlying lifecycle. Once mocket is active, you register mock entries before making real network calls.
Workflow diagram: activating mocket and registering a mock
Sources: mocket/decorators/base.py1-100 mocket/mocket.py1-100 mocket/inject.py1-100 mocket/socket.py1-100
| Feature | Primary Classes / Functions | Sub-page |
|---|---|---|
| Sync decorator | mocketize | 4.1 |
| Async decorator | async_mocketize | 4.1 |
| Context manager | Mocketizer | 4.1 |
| HTTP/HTTPS mocking | Entry, Response in mockhttp | 4.2 |
| SSL interception | MocketSSLContext, MocketSSLSocket | 4.3 |
| VCR recording/playback | MocketRecordStorage, truesocket_recording_dir | 4.4 |
| Strict mode | MocketMode.STRICT, StrictMocketException | 4.5 |
| Request verification | Mocket.assert_fail_if_entries_not_served(), Mocket.last_request() | 4.6 |
Mocket provides three activation mechanisms, all defined in mocket/decorators/base.py and exported from mocket/__init__.py.
| Mechanism | Signature | Use Case |
|---|---|---|
@mocketize | mocketize(func=None, *, truesocket_recording_dir=None, strict_mode=False, strict_mode_allowed=None, namespace=None) | Sync test function |
@async_mocketize | Same parameters | Async test function (async def) |
Mocketizer() | Same parameters as a constructor | with block anywhere in code |
All three ultimately delegate to Mocketizer.__enter__ / Mocketizer.__exit__ (or their async equivalents). The Mocketizer.factory() class method derives the namespace from the calling test function name when none is supplied.
See 4.1 for full parameter documentation.
Mock entries are the records that tell mocket what to return for a given request. The most important entry type is Entry from mocket/mocks/mockhttp.py.
Diagram: entry registration and matching
Sources: mocket/mocks/mockhttp.py1-100 mocket/mocket.py1-100
Key methods on Entry (from mocket/mocks/mockhttp.py):
| Method | Description |
|---|---|
Entry.single_register(method, url, body, headers, status, exception, match_querystring, can_handle_fun) | Registers one entry that responds once and stays registered |
Entry.register(method, url, responses) | Registers an entry with multiple ordered Response objects |
Key Entry class attributes for HTTP methods:
Entry.GETEntry.POSTEntry.PUTEntry.PATCHEntry.DELETEEntry.OPTIONSEntry.HEADSee 4.2 for the full HTTP mocking guide, including can_handle_fun and query string matching.
All activation mechanisms accept the same set of configuration parameters. These are passed either to @mocketize(...) / @async_mocketize(...) or to Mocketizer(...).
Sources: mocket/decorators/base.py1-100 mocket/mocket.py1-100 mocket/recording.py1-100
| Parameter | Type | Default | Effect |
|---|---|---|---|
truesocket_recording_dir | str or None | None | When set, real traffic is recorded to JSON; subsequent runs replay from disk |
strict_mode | bool | False | Raises StrictMocketException for any connection not matched by a registered entry |
strict_mode_allowed | list | None | Hosts or (host, port) pairs exempt from strict mode |
namespace | str or None | Auto | Used as the stem of the recording JSON filename |
See 4.4 for recording details and 4.5 for strict mode details.
After a test runs, you can assert that all registered entries were actually consumed and inspect what was received.
| Method | Location | Purpose |
|---|---|---|
Mocket.assert_fail_if_entries_not_served() | mocket/mocket.py | Raises AssertionError if any entry was never matched |
Mocket.last_request() | mocket/mocket.py | Returns the most recent recorded request object |
Mocket.request_list() | mocket/mocket.py | Returns all recorded requests in order |
Mocket.has_requests() | mocket/mocket.py | Returns True if any requests were made |
Mocket.remove_last_request() | mocket/mocket.py | Removes the most recent entry from _requests |
See 4.6 for full verification documentation.
All primary user-facing symbols are re-exported from mocket/__init__.py:
Sources: mocket/__init__.py1-50 mocket/decorators/base.py1-50 mocket/mocket.py1-50 mocket/ssl/context.py1-50
Protocol-specific entry types are imported from their own modules:
| Import Path | Class | Protocol |
|---|---|---|
mocket.mocks.mockhttp | Entry, Response | HTTP / HTTPS |
mocket.mocks.mockredis | Entry, Redisizer | Redis |
mocketize, async_mocketize, and Mocketizer, including the factory() namespace derivation and async lifecycle.Entry and Response objects, query string matching, custom can_handle_fun, and client compatibility.MocketSSLContext and MocketSSLSocket intercept TLS connections.truesocket_recording_dir VCR workflow using MocketRecordStorage.StrictMocketException, MocketMode.STRICT, and whitelisting with strict_mode_allowed.