0
# pylibmc
1

2
A fast Python wrapper around libmemcached, providing quick and small memcached client functionality. pylibmc offers performance-optimized memcached operations with support for binary protocol, connection pooling, consistent hashing, compression, and SASL authentication.
3

4
## Package Information
5

6
- **Package Name**: pylibmc
7
- **Language**: Python
8
- **Installation**: `pip install pylibmc`
9
- **Requirements**: libmemcached development libraries
10

11
## Core Imports
12

13
```python
14
import pylibmc
15
```
16

17
Common usage patterns:
18

19
```python
20
from pylibmc import Client, ClientPool, ThreadMappedPool
21
```
22

23
## Basic Usage
24

25
```python
26
import pylibmc
27

28
# Create a client connection
29
client = pylibmc.Client(["localhost:11211"], binary=True)
30

31
# Configure behaviors for optimal performance
32
client.behaviors = {
33
    "tcp_nodelay": True,
34
    "ketama": True,
35
    "no_block": True
36
}
37

38
# Basic operations
39
client.set("key", "value", time=3600)  # Set with 1 hour expiration
40
value = client.get("key")  # Get value
41
client.delete("key")  # Delete key
42

43
# Multi operations for efficiency  
44
client.set_multi({"key1": "value1", "key2": "value2"})
45
results = client.get_multi(["key1", "key2"])
46

47
# Atomic operations
48
client.set("counter", "10")
49
client.incr("counter", 5)  # Increment by 5
50
client.decr("counter", 2)  # Decrement by 2
51

52
# Connection pooling for thread safety
53
pool = pylibmc.ClientPool()
54
pool.fill(client, 10)  # Fill pool with 10 clients
55

56
with pool.reserve() as pooled_client:
57
    pooled_client.set("pooled_key", "pooled_value")
58
```
59

60
## Architecture
61

62
pylibmc provides a layered architecture for high-performance memcached access:
63

64
- **C Extension Core** (`_pylibmc`): Direct libmemcached bindings providing raw performance
65
- **Python Client Wrapper** (`Client`): Enhanced interface with behavior management and mapping operations
66
- **Connection Pooling** (`ClientPool`, `ThreadMappedPool`): Thread-safe client sharing patterns
67
- **Configuration System**: Comprehensive behavior and callback configuration for optimization
68

69
This design maximizes performance through C-level operations while providing Python-friendly interfaces for development productivity.
70

71
## Capabilities
72

73
### Utility Functions
74

75
Module-level utility functions for information and diagnostics.
76

77
```python { .api }
78
def build_info() -> str:
79
    """Get build information string with versions and feature support."""
80
```
81

82
### Administrative Functions
83

84
Server administration and monitoring operations.
85

86
```python { .api }
87
def get_stats(args: str = "") -> dict:
88
    """Get server statistics for all connected servers."""
89

90
def disconnect_all() -> None:
91
    """Disconnect from all servers and close connections."""
92

93
def flush_all(time: int = 0) -> bool:
94
    """Flush all items from all servers."""
95
```
96

97
### Auto-Configuration
98

99
Automatic configuration for cloud cache services.
100

101
```python { .api }
102
def elasticache(address: str = '127.0.0.1:11211', config_key: bytes = b'cluster', 
103
                mc_key: str = 'AmazonElastiCache:cluster') -> Client:
104
    """Auto-configure client for AWS ElastiCache clusters."""
105
```
106

107
### Client Operations
108

109
Core memcached operations including get, set, delete, cas, append, prepend operations. Supports both single-key and multi-key batch operations for efficiency.
110

111
```python { .api }
112
def get(key: str, default=None): ...
113
def set(key: str, value, time: int = 0, min_compress_len: int = 0, compress_level: int = -1) -> bool: ...
114
def delete(key: str) -> bool: ...
115
def cas(key: str, value, cas: int, time: int = 0) -> bool: ...
116
def get_multi(keys: list, key_prefix: str = None) -> dict: ...
117
def set_multi(keys: dict, time: int = 0, key_prefix: str = None, min_compress_len: int = 0, compress_level: int = -1) -> list: ...
118
```
119

120
[Client Operations](./client-operations.md)
121

122
### Connection Pooling
123

124
Thread-safe connection pooling implementations for high-concurrency applications. Includes queue-based pooling and thread-mapped pooling strategies.
125

126
```python { .api }
127
class ClientPool:
128
    def __init__(mc=None, n_slots: int = 0): ...
129
    def reserve(block: bool = False): ...
130
    def fill(mc, n_slots: int): ...
131

132
class ThreadMappedPool:
133
    def __init__(master): ...
134
    def reserve(): ...
135
    def relinquish(): ...
136
```
137

138
[Connection Pooling](./connection-pooling.md)
139

140
### Configuration and Behaviors
141

142
Comprehensive behavior management for performance tuning and feature configuration. Includes hash algorithms, distribution methods, timeouts, and protocol options.
143

144
```python { .api }
145
def get_behaviors() -> dict: ...
146
def set_behaviors(behaviors: dict): ...
147

148
# Available behavior constants
149
hashers: dict  # Hash algorithm mappings
150
distributions: dict  # Distribution algorithm mappings
151
all_behaviors: list  # All available behavior names
152
```
153

154
[Configuration](./configuration.md)
155

156
### Error Handling
157

158
Complete exception hierarchy for robust error handling, covering connection issues, protocol errors, and operational failures.
159

160
```python { .api }
161
class Error(Exception): ...
162
class CacheMiss(Error): ...
163
class ConnectionError(Error): ...
164
class ServerError(Error): ...
165
# ... and 20+ other specific exception types
166
```
167

168
[Error Handling](./error-handling.md)
169

170
### Test Utilities
171

172
Development and testing utilities for creating test clients and checking server availability.
173

174
```python { .api }
175
def make_test_client(cls=Client, env=None, server_type="tcp", host="127.0.0.1", 
176
                     port=11211, **kwds) -> Client:
177
    """Create test client with default configuration."""
178

179
def is_alive(addr: str) -> bool:
180
    """Check if memcached server at address is alive."""
181

182
def get_version(addr: str) -> str:
183
    """Get version string from memcached server."""
184
```
185

186
## Types
187

188
```python { .api }
189
class Client:
190
    """Main memcached client providing all operations."""
191
    def __init__(servers: list, behaviors: dict = None, binary: bool = False, 
192
                 username: str = None, password: str = None): ...
193

194
class ClientPool:
195
    """Queue-based client pool for thread safety."""
196
    def __init__(mc=None, n_slots: int = 0): ...
197

198
class ThreadMappedPool(dict):
199
    """Thread-mapped client pool with per-thread clients."""
200
    def __init__(master): ...
201

202
class BehaviorDict(dict):
203
    """Dictionary that syncs behavior changes to client."""
204
    def __init__(client, *args, **kwargs): ...
205
```