Overview

Relevant source files

• README.rst
• mocket/__init__.py

Purpose and Scope

This document provides a high-level introduction to the Mocket library, explaining its purpose as a socket mock framework for testing network-dependent Python applications. It covers the fundamental concepts, architecture, and capabilities of the system. For installation and setup instructions, see Getting Started. For detailed technical architecture, see Core Architecture. For practical usage examples, see User Guide.

Sources: README.rst1-58

What is Mocket?

Mocket (pronounced /ˈmɔ.kɛt/) is a socket mock framework that intercepts network operations at the Python standard library level. It works by monkey-patching the socket and ssl modules, allowing complete control over network I/O without requiring modifications to application code or client libraries.

The library's tagline summarizes its scope: "A socket mock framework for all kinds of socket animals, web-clients included - with gevent/asyncio/SSL support."

Mocket serves two primary use cases:

Use Case	Description	Example
Low-level framework	Building custom mocks for new protocols or databases	Implementing a mock for a proprietary binary protocol
Ready-to-use mock	Testing HTTP/HTTPS/Redis calls from any client library	Mocking requests.get() or redis.StrictRedis() calls

Sources: README.rst27-45 mocket/__init__.py1-34

Key Capabilities

Mocket provides the following core capabilities:

• Universal Socket Interception: Patches socket.socket, ssl.SSLContext, and related functions to redirect all network operations
• Protocol Support: Built-in HTTP/HTTPS and Redis protocol implementations
• Async Framework Support: Works with asyncio, gevent, and trio through @async_mocketize
• Recording and Replay: VCR-style recording of real network traffic to JSON files for test fixture generation
• Strict Mode: Prevents accidental real network access during tests with configurable exceptions
• Library Compatibility: Drop-in replacement for HTTPretty, backend for Pook, integration with aiohttp
• Request Verification: Collects all requests for inspection and assertion in tests

Sources: README.rst33-91 mocket/__init__.py4-32

System Architecture

The following diagram maps Mocket's conceptual layers to the actual code entities that implement them:

Sources: mocket/__init__.py1-34 mocket/mocket.py1-50 mocket/entry.py1-30 mocket/inject.py1-50

Core Components

Mocket Core (Mocket class)

The Mocket class serves as the global state manager and central registry for all mocking operations. It maintains:

• _entries: Dictionary mapping (host, port) tuples to lists of MocketEntry objects
• _requests: List of all captured network requests
• _truesocket_recording_dir: Directory path for VCR-style recording

Key methods include:

Method	Purpose	File Reference
enable()	Activates mocking by triggering mocket.inject	mocket/mocket.py
disable()	Restores original socket/ssl modules	mocket/mocket.py
register()	Adds a MocketEntry to the registry	mocket/mocket.py
collect()	Records request data for later inspection	mocket/mocket.py
last_request()	Returns the most recent captured request	mocket/mocket.py
get_entry()	Finds matching entry for a given host/port/data	mocket/mocket.py

Sources: mocket/mocket.py1-100

Entry System (MocketEntry class)

MocketEntry defines mock responses and request matching logic. Subclasses specialize for different protocols:

Sources: mocket/entry.py1-50 mocket/mocks/mockhttp.py1-100 mocket/mocks/mockredis.py1-50

Module Injection (mocket.inject)

The mocket.inject module performs the critical monkey-patching that enables Mocket to intercept network operations. When Mocket.enable() is called, this module:

1. Stores references to original socket.socket, ssl.SSLContext, socket.create_connection, etc.
2. Replaces them with Mocket's implementations (MocketSocket, MocketSSLContext, etc.)
3. Restores originals when Mocket.disable() is called

Sources: mocket/inject.py1-100

Socket Implementation (MocketSocket)

MocketSocket is a mock implementation of socket.socket that simulates network I/O using in-memory buffers:

• Connection: connect((host, port)) queries Mocket.get_entry() for matching entries
• Sending: sendall(data) writes to internal buffer and calls Mocket.collect()
• Receiving: recv(bufsize) reads from internal buffer populated by entry responses
• Recording: When no entry matches and recording is enabled, uses _true_socket for real I/O

Sources: mocket/socket.py1-200

Usage Patterns

Mocket supports three activation patterns:

Decorator Pattern

Sources: README.rst142-155

Context Manager Pattern

Sources: README.rst158-173

Direct API Pattern

Sources: mocket/mocket.py1-50

Operational Modes

Mocket operates in different modes based on configuration:

Sources: README.rst179-208 README.rst263-286

When to Use Mocket

Mocket is appropriate for:

Scenario	Reason
Testing HTTP/HTTPS clients	Works with any library (requests, httpx, urllib) without client-specific mocking
Testing custom protocols	Low-level socket control allows mocking any TCP-based protocol
Preventing network access	Strict mode ensures tests don't make real network calls
Generating test fixtures	Recording mode captures real API responses for replay
Testing async code	Native support for asyncio, gevent, trio via @async_mocketize
Redis client testing	Built-in Redis protocol mock with mockredis

Mocket may not be suitable for:

• UDP protocol mocking (focuses on TCP)
• Testing code that needs real network timing/latency behavior
• Scenarios where higher-level HTTP mocking (like responses library) is sufficient

Sources: README.rst33-45 README.rst74-91

Version Compatibility

As of version 3.7.0, Mocket's major version follows Python's version numbering to indicate the most recent Python version supported. The current version is 3.14.0, indicating Python 3.14 support.

Note: The last version compatible with Python 2.7 is 3.9.4. No further backports or bugfixes will be made for Python 2.7 except through commercial support.

Sources: README.rst60-64 mocket/__init__.py34