This page describes what python-mocket is, the problems it solves, and a map of its major subsystems. It is intended as the entry point for understanding the library before reading detailed documentation on any individual component. For setup instructions, see Getting Started. For a deep dive into internal architecture, see Core Architecture.
python-mocket (package name: mocket) is a socket-level mock framework for Python. It intercepts calls to the standard socket and ssl modules by monkey-patching them at test time, then routes those calls through a registry of pre-registered mock responses instead of real network connections.
The library targets two distinct use cases:
| Use Case | Description |
|---|---|
| Low-level protocol framework | Build and test clients for custom protocols by implementing MocketEntry subclasses |
| Ready-to-use HTTP/HTTPS mock | Drop-in replacement for HTTPretty-style mocking via mocket.mocks.mockhttp |
Because interception happens at the socket layer rather than the HTTP layer, mocket works with any Python HTTP client (requests, httpx, aiohttp, urllib, etc.) and also supports non-HTTP protocols (e.g., Redis).
Sources: README.rst33-46 mocket/__init__.py1-36
Register mock responses for specific method/URL combinations using Entry.single_register() or Entry.register() from mocket.mocks.mockhttp. Both plain HTTP and TLS-wrapped HTTPS connections are supported. See HTTP/HTTPS Mocking.
A basic Redis mock is provided via mocket.mocks.mockredis, demonstrating that the framework is not limited to HTTP. See Redis Protocol.
When truesocket_recording_dir is supplied, real socket traffic is recorded to JSON files on first run and replayed on subsequent runs — similar to VCR.py. See Recording and Playback.
When strict_mode=True is set, any connection attempt to a host not covered by a registered entry raises StrictMocketException. A whitelist (strict_mode_allowed) can exempt specific hosts or (host, port) pairs. See Strict Mode.
Both asyncio and gevent are supported. The decorator async_mocketize and the Mocketizer async context manager (__aenter__/__aexit__) handle coroutine-based tests. See Async Framework Support.
| Integration | Entry Point |
|---|---|
| HTTPretty compatibility | mocket.plugins.httpretty |
| aiohttp connector | mocket.plugins.aiohttp_connector.MocketTCPConnector |
| pook mock engine | mocket.plugins.pook_mock_engine.MocketEngine |
Sources: README.rst74-420 mocket/__init__.py1-36
Everything a test author needs is exported from mocket/__init__.py:
| Symbol | Type | Role |
|---|---|---|
mocketize | decorator | Wraps a sync test function with Mocketizer |
async_mocketize | decorator | Wraps an async test function with Mocketizer |
Mocketizer | class | Context manager that enables/disables mocking |
Mocket | class | Singleton registry holding all entries and recorded requests |
MocketEntry | class | Base class for all mock entries |
MocketSSLContext | class | Replacement for ssl.SSLContext during mocking |
FakeSSLContext | alias | Backward-compatible alias for MocketSSLContext |
Sources: mocket/__init__.py1-36
Subsystem map — shows the primary modules and their dependencies:
Sources: mocket/__init__.py1-36 README.rst33-46
Lifecycle of a mocked request — maps natural-language concepts to code symbols:
Sources: README.rst113-177 mocket/__init__.py1-36
Starting from version 3.7.0, the major version number tracks the most recent supported Python version. The current release is 3.14.1 (see mocket/__init__.py36). The last version with Python 2.7 support was 3.9.4.
| Topic | Wiki Page |
|---|---|
| Installation and first test | Getting Started |
| Internal architecture details | Core Architecture |
Mocket singleton class API | Core Engine (Mocket Class) |
| HTTP mocking how-to | HTTP/HTTPS Mocking |
| VCR recording | Recording and Playback (VCR Mode) |
| Strict mode | Strict Mode |
| HTTPretty compatibility | HTTPretty Compatibility |
| aiohttp integration | aiohttp Integration |
| pook integration | Pook Integration |
| All public symbols | API Reference |
Sources: README.rst1-429 mocket/__init__.py1-36
Refresh this wiki
