python-memcached Client

Warnings

• breaking The `delete()` method's return value changed in version 1.62. It now returns `1` for successful deletion ('DELETED') and `0` for 'NOT_FOUND' or server errors. Previously, its behavior might have been less consistent or different depending on the server response.
  Fix: Update code to expect `0` for not found/errors and `1` for success when checking `delete()` results.
• breaking Support for Python 2.6, 3.2, and 3.3 was officially dropped in version 1.59.
  Fix: Upgrade to a supported Python version (e.g., Python 3.6+).
• breaking Version 1.59 introduced changes to how FLAGS are set, which can break compatibility with older `python-memcached` clients, particularly regarding the handling of strings versus bytes. Keys set by v1.58 as strings might be returned as bytes on v1.59, requiring explicit decoding.
  Fix: Ensure all clients in your system are running compatible `python-memcached` versions. Implement explicit encoding/decoding if encountering `bytes` where `str` is expected, or consider a custom serializer/deserializer.
• deprecated The `time` argument for the `delete()` method was removed in version 1.58 when not explicitly set, as it is deprecated in the memcached server itself. While `python-memcached` likely handles this gracefully, relying on it is discouraged.
  Fix: Avoid passing the `time` argument to `delete()`. Memcached `delete` operations are immediate and do not support an expiration time.
• gotcha The `python-memcached` library is in maintenance mode, with `pymemcache` positioned as a more actively developed and feature-rich alternative. New projects or those requiring active enhancements might consider `pymemcache` instead.
  Fix: Evaluate `pymemcache` for new development. For existing projects, be aware that active feature development for `python-memcached` is minimal.
• gotcha Memcached itself has limits on key and value sizes: keys can be at most 250 bytes, and values typically have a maximum size of 1MB. Attempting to store larger items will fail.
  Fix: Design your caching strategy to store smaller, frequently accessed data. For larger objects, consider sharding the data or using an alternative storage solution.
• gotcha By default, `python-memcached` uses Python's `pickle` module to serialize and deserialize complex Python objects (like lists, dictionaries, or custom classes) when storing them. This can have security implications if untrusted data is deserialized, and may also be slower or less efficient than custom serialization (e.g., JSON for simple data structures).
  Fix: For security-sensitive applications, ensure that only trusted data is unpickled. For better interoperability or performance, explicitly serialize/deserialize complex objects using formats like JSON before passing them to `set()` and after receiving them from `get()`.

Install

• pip install python-memcached Install with pip

Imports

• Client

  from memcache import Client

  The top-level package name is `memcache`, not `python_memcached` as one might infer from the PyPI slug.

Quickstart

This quickstart demonstrates how to connect to a Memcached server, set and retrieve string values, store and retrieve Python objects (which are automatically pickled/unpickled), and delete keys using `python-memcached`.

import memcache
import os

# Connect to a memcached server. Use environment variable for host if available.
# Default to localhost:11211 if MEMCACHED_SERVER is not set.
MEMCACHED_SERVER = os.environ.get('MEMCACHED_SERVER', '127.0.0.1:11211')
mc = memcache.Client([MEMCACHED_SERVER], debug=0)

# Set a key-value pair with an expiration time of 60 seconds
mc.set("my_key", "Hello, Memcached!", time=60)
print(f"Set 'my_key': 'Hello, Memcached!' (expires in 60s)")

# Get the value for the key
value = mc.get("my_key")
print(f"Got 'my_key': {value}")

# Set a complex object (will be pickled by default)
sample_object = {"name": "Test User", "id": 123}
mc.set("user_data", sample_object)
print(f"Set 'user_data': {sample_object}")

# Retrieve the complex object
retrieved_object = mc.get("user_data")
print(f"Got 'user_data': {retrieved_object}")

# Delete a key
mc.delete("my_key")
print(f"Deleted 'my_key'.")

# Try to get deleted key
deleted_value = mc.get("my_key")
print(f"Attempt to get 'my_key' after deletion: {deleted_value} (should be None)")