0
# Client Operations
1

2
Core memcached operations for data storage, retrieval, and manipulation. These operations form the foundation of memcached functionality and support both single-key and efficient multi-key batch operations.
3

4
## Capabilities
5

6
### Data Retrieval
7

8
Retrieve values from memcached using keys, with support for default values and CAS (Compare-And-Store) operations.
9

10
```python { .api }
11
def get(key: str, default=None):
12
    """
13
    Get a single value from memcached.
14
    
15
    Parameters:
16
    - key (str): The key to retrieve
17
    - default: Value to return if key is not found
18
    
19
    Returns:
20
    Value stored at key, or default if not found
21
    
22
    Raises:
23
    - Error: On connection or protocol errors
24
    """
25

26
def gets(key: str):
27
    """
28
    Get a value with its CAS identifier for atomic updates.
29
    
30
    Parameters:
31
    - key (str): The key to retrieve
32
    
33
    Returns:
34
    tuple: (value, cas_id) or (None, None) if key not found
35
    
36
    Raises:
37
    - Error: On connection or protocol errors
38
    """
39

40
def get_multi(keys: list, key_prefix: str = None) -> dict:
41
    """
42
    Efficiently retrieve multiple keys in a single operation.
43
    
44
    Parameters:
45
    - keys (list): List of keys to retrieve
46
    - key_prefix (str, optional): Prefix to add to all keys
47
    
48
    Returns:
49
    dict: Mapping of found keys to their values
50
    
51
    Raises:
52
    - Error: On connection or protocol errors
53
    """
54
```
55

56
### Data Storage
57

58
Store values in memcached with various storage modes and optional compression.
59

60
```python { .api }
61
def set(key: str, value, time: int = 0, min_compress_len: int = 0, compress_level: int = -1) -> bool:
62
    """
63
    Store a value unconditionally.
64
    
65
    Parameters:
66
    - key (str): Storage key
67
    - value: Value to store (any serializable type)
68
    - time (int): Expiration time in seconds (0 = no expiration)
69
    - min_compress_len (int): Minimum size to trigger compression
70
    - compress_level (int): Compression level (-1 = default)
71
    
72
    Returns:
73
    bool: True if successful, False otherwise
74
    
75
    Raises:
76
    - Error: On connection or protocol errors
77
    """
78

79
def add(key: str, value, time: int = 0, min_compress_len: int = 0, compress_level: int = -1) -> bool:
80
    """
81
    Store a value only if the key doesn't exist.
82
    
83
    Parameters:
84
    - key (str): Storage key
85
    - value: Value to store (any serializable type)
86
    - time (int): Expiration time in seconds (0 = no expiration)
87
    - min_compress_len (int): Minimum size to trigger compression
88
    - compress_level (int): Compression level (-1 = default)
89
    
90
    Returns:
91
    bool: True if stored, False if key already exists
92
    
93
    Raises:
94
    - Error: On connection or protocol errors
95
    """
96

97
def replace(key: str, value, time: int = 0, min_compress_len: int = 0, compress_level: int = -1) -> bool:
98
    """
99
    Store a value only if the key already exists.
100
    
101
    Parameters:
102
    - key (str): Storage key
103
    - value: Value to store (any serializable type)
104
    - time (int): Expiration time in seconds (0 = no expiration)
105
    - min_compress_len (int): Minimum size to trigger compression
106
    - compress_level (int): Compression level (-1 = default)
107
    
108
    Returns:
109
    bool: True if replaced, False if key doesn't exist
110
    
111
    Raises:
112
    - Error: On connection or protocol errors
113
    """
114

115
def cas(key: str, value, cas: int, time: int = 0) -> bool:
116
    """
117
    Store a value using Compare-And-Store for atomic updates.
118
    
119
    Parameters:
120
    - key (str): Storage key
121
    - value: Value to store (any serializable type)
122
    - cas (int): CAS identifier from gets() operation
123
    - time (int): Expiration time in seconds (0 = no expiration)
124
    
125
    Returns:
126
    bool: True if CAS succeeded, False if CAS mismatch
127
    
128
    Raises:
129
    - Error: On connection or protocol errors
130
    """
131

132
def set_multi(keys: dict, time: int = 0, key_prefix: str = None, min_compress_len: int = 0, compress_level: int = -1) -> list:
133
    """
134
    Store multiple key-value pairs efficiently.
135
    
136
    Parameters:
137
    - keys (dict): Mapping of keys to values
138
    - time (int): Expiration time in seconds (0 = no expiration)
139
    - key_prefix (str, optional): Prefix to add to all keys
140
    - min_compress_len (int): Minimum size to trigger compression
141
    - compress_level (int): Compression level (-1 = default)
142
    
143
    Returns:
144
    list: Keys that failed to be stored
145
    
146
    Raises:
147
    - Error: On connection or protocol errors
148
    """
149

150
def add_multi(keys: dict, time: int = 0, key_prefix: str = None, min_compress_len: int = 0, compress_level: int = -1) -> list:
151
    """
152
    Add multiple key-value pairs (only if keys don't exist).
153
    
154
    Parameters:
155
    - keys (dict): Mapping of keys to values
156
    - time (int): Expiration time in seconds (0 = no expiration)
157
    - key_prefix (str, optional): Prefix to add to all keys
158
    - min_compress_len (int): Minimum size to trigger compression
159
    - compress_level (int): Compression level (-1 = default)
160
    
161
    Returns:
162
    list: Keys that already existed and weren't added
163
    
164
    Raises:
165
    - Error: On connection or protocol errors
166
    """
167
```
168

169
### Data Removal
170

171
Remove data from memcached storage.
172

173
```python { .api }
174
def delete(key: str) -> bool:
175
    """
176
    Delete a key from memcached.
177
    
178
    Parameters:
179
    - key (str): Key to delete
180
    
181
    Returns:
182
    bool: True if deleted, False if key didn't exist
183
    
184
    Raises:
185
    - Error: On connection or protocol errors
186
    """
187

188
def delete_multi(keys: list, key_prefix: str = None) -> bool:
189
    """
190
    Delete multiple keys efficiently.
191
    
192
    Parameters:
193
    - keys (list): List of keys to delete
194
    - key_prefix (str, optional): Prefix to add to all keys
195
    
196
    Returns:
197
    bool: True if all deletes succeeded, False otherwise
198
    
199
    Raises:
200
    - Error: On connection or protocol errors
201
    """
202
```
203

204
### String Operations
205

206
Append or prepend data to existing string values.
207

208
```python { .api }
209
def append(key: str, value, time: int = 0, min_compress_len: int = 0, compress_level: int = -1) -> bool:
210
    """
211
    Append data to an existing key's value.
212
    
213
    Parameters:
214
    - key (str): Existing key
215
    - value: Data to append (string or bytes)
216
    - time (int): New expiration time (0 = unchanged)
217
    - min_compress_len (int): Minimum size to trigger compression  
218
    - compress_level (int): Compression level (-1 = default)
219
    
220
    Returns:
221
    bool: True if successful, False if key doesn't exist
222
    
223
    Raises:
224
    - Error: On connection or protocol errors
225
    """
226

227
def prepend(key: str, value, time: int = 0, min_compress_len: int = 0, compress_level: int = -1) -> bool:
228
    """
229
    Prepend data to an existing key's value.
230
    
231
    Parameters:
232
    - key (str): Existing key
233
    - value: Data to prepend (string or bytes)
234
    - time (int): New expiration time (0 = unchanged)
235
    - min_compress_len (int): Minimum size to trigger compression
236
    - compress_level (int): Compression level (-1 = default)
237
    
238
    Returns:
239
    bool: True if successful, False if key doesn't exist
240
    
241
    Raises:
242
    - Error: On connection or protocol errors
243
    """
244
```
245

246
### Atomic Operations
247

248
Atomic increment and decrement operations for numeric values.
249

250
```python { .api }
251
def incr(key: str, delta: int = 1) -> int:
252
    """
253
    Atomically increment a numeric value.
254
    
255
    Parameters:
256
    - key (str): Key containing numeric value
257
    - delta (int): Amount to increment by
258
    
259
    Returns:
260
    int: New value after increment
261
    
262
    Raises:
263
    - Error: On connection or protocol errors
264
    - CacheMiss: If key doesn't exist
265
    """
266

267
def decr(key: str, delta: int = 1) -> int:
268
    """
269
    Atomically decrement a numeric value.
270
    
271
    Parameters:
272
    - key (str): Key containing numeric value  
273
    - delta (int): Amount to decrement by
274
    
275
    Returns:
276
    int: New value after decrement
277
    
278
    Raises:
279
    - Error: On connection or protocol errors
280
    - CacheMiss: If key doesn't exist
281
    """
282

283
def incr_multi(keys: list, key_prefix: str = None, delta: int = 1):
284
    """
285
    Atomically increment multiple numeric values.
286
    
287
    Parameters:
288
    - keys (list): List of keys containing numeric values
289
    - key_prefix (str, optional): Prefix to add to all keys
290
    - delta (int): Amount to increment by
291
    
292
    Returns:
293
    None (use get_multi to retrieve new values)
294
    
295
    Raises:
296
    - Error: On connection or protocol errors
297
    """
298
```
299

300
### Utility Operations
301

302
Additional operations for cache management and diagnostics.
303

304
```python { .api }
305
def touch(key: str, seconds: int) -> bool:
306
    """
307
    Update expiration time of an existing key without changing its value.
308
    
309
    Parameters:
310
    - key (str): Key to update
311
    - seconds (int): New expiration time from now
312
    
313
    Returns:
314
    bool: True if successful, False if key doesn't exist
315
    
316
    Raises:
317
    - Error: On connection or protocol errors
318
    """
319

320
def hash(key: str) -> int:
321
    """
322
    Get the hash value for a key using the configured hash algorithm.
323
    
324
    Parameters:
325
    - key (str): Key to hash
326
    
327
    Returns:
328
    int: Hash value
329
    """
330

331
def flush_all(time: int = 0) -> bool:
332
    """
333
    Flush all items from all servers.
334
    
335
    Parameters:
336
    - time (int): Delay before flushing (0 = immediate)
337
    
338
    Returns:
339
    bool: True if successful
340
    
341
    Raises:
342
    - Error: On connection or protocol errors
343
    """
344
```
345

346
### Mapping Interface
347

348
Dictionary-like access to memcached operations.
349

350
```python { .api }
351
def __getitem__(key: str):
352
    """Dict-like key access: value = client[key]"""
353

354
def __setitem__(key: str, value):
355
    """Dict-like key assignment: client[key] = value"""
356

357
def __delitem__(key: str):
358
    """Dict-like key deletion: del client[key]"""
359

360
def __contains__(key: str) -> bool:
361
    """Dict-like membership test: key in client"""
362
```
363

364
### Serialization and Internal Operations
365

366
Low-level operations for data serialization and internal client management.
367

368
```python { .api }
369
def serialize(value) -> tuple:
370
    """
371
    Serialize a Python object for storage in memcached.
372
    
373
    Parameters:
374
    - value: Python object to serialize
375
    
376
    Returns:
377
    tuple: (serialized_data, flags) for memcached storage
378
    """
379

380
def deserialize(data: bytes, flags: int):
381
    """
382
    Deserialize data retrieved from memcached back to Python object.
383
    
384
    Parameters:
385
    - data (bytes): Serialized data from memcached
386
    - flags (int): Flags indicating serialization method used
387
    
388
    Returns:
389
    Deserialized Python object
390
    """
391

392
def clone() -> Client:
393
    """
394
    Create a copy of the client with identical configuration.
395
    Used by connection pools for thread-safe client sharing.
396
    
397
    Returns:
398
    Client: New client instance with same configuration
399
    """
400
```
401

402
## Usage Examples
403

404
### Basic Operations
405

406
```python
407
import pylibmc
408

409
client = pylibmc.Client(["localhost:11211"])
410

411
# Store and retrieve data
412
client.set("user:123", {"name": "Alice", "age": 30})
413
user_data = client.get("user:123")
414

415
# Use mapping interface
416
client["config:timeout"] = 300
417
timeout = client["config:timeout"]
418
del client["config:timeout"]
419
```
420

421
### Batch Operations  
422

423
```python
424
# Efficient multi-key operations
425
users = {
426
    "user:1": {"name": "Alice"},
427
    "user:2": {"name": "Bob"},
428
    "user:3": {"name": "Charlie"}
429
}
430

431
failed_keys = client.set_multi(users)
432
if not failed_keys:
433
    print("All users stored successfully")
434

435
# Retrieve multiple users
436
user_data = client.get_multi(["user:1", "user:2", "user:3"])
437
```
438

439
### Atomic Operations
440

441
```python
442
# Initialize counter
443
client.set("page_views", "0")
444

445
# Increment atomically
446
new_count = client.incr("page_views", 1)
447
print(f"Page views: {new_count}")
448

449
# Decrement if needed  
450
client.decr("page_views", 1)
451
```
452

453
### Compare-And-Store
454

455
```python
456
# Atomic update using CAS
457
value, cas_id = client.gets("user:123")
458
if value:
459
    value["last_seen"] = "2024-01-01"
460
    success = client.cas("user:123", value, cas_id)
461
    if not success:
462
        print("Another client modified the value")
463
```