pymemcache

Warnings

• breaking Version 4.0.0 dropped official support for Python 2.7, 3.4, and 3.5. Ensure your project uses Python 3.7 or newer before upgrading to v4.0.0.
  Fix: Upgrade to Python 3.7+ or pin pymemcache to <4.0.0.
• gotcha `get()` and `get_many()` methods return values as `bytes`, not `str`. You must explicitly decode the retrieved bytes if you expect a string.
  Fix: After retrieval, use `.decode('utf-8')` (or appropriate encoding) on the returned value: `value.decode('utf-8')`.
• gotcha Memcached keys must adhere to the ASCII protocol and cannot contain spaces, newlines, carriage returns, or null characters by default. Using non-ASCII or illegal characters will raise `MemcacheIllegalInputError`.
  Fix: Ensure keys are ASCII compliant. For unicode keys, instantiate the client with `allow_unicode_keys=True` and ensure consistent encoding (e.g., UTF-8) across clients.
• breaking The `expire` argument (previously `time` in `python-memcached`) for set operations now strictly expects an integer representing seconds. Floating-point values are no longer accepted.
  Fix: Convert any float `expire` values to `int`.
• breaking In version 3.0.0, the serialization API was refactored. Instead of separate `serializer` and `deserializer` arguments, client objects now expect a single `serde` object that implements `serialize` and `deserialize` methods.
  Fix: Update custom serialization logic to use the `serde` object pattern. For example: `client = Client(..., serde=MyCustomSerde())`.
• gotcha Failing to set `connect_timeout` and `timeout` in client constructors can cause your application to block indefinitely if the memcached server is slow or unavailable. This is crucial for production environments.
  Fix: Always provide explicit `connect_timeout` and `timeout` values (e.g., `Client(..., connect_timeout=1, timeout=0.5)`).

Install

• pip install pymemcache Install stable version

Imports

• Client

  from pymemcache.client.base import Client

  Common mistake when migrating from the older 'python-memcached' library.
• HashClient

  from pymemcache.client.hash import HashClient

  While 'HashClient' can be imported directly from 'pymemcache' since v3.3.0, the explicit path 'pymemcache.client.hash' is also widely used and clear.

Quickstart

This quickstart demonstrates how to connect to a memcached server using `pymemcache.Client`, set a key-value pair with an expiration, and retrieve it. Note that `pymemcache` returns values as bytes, requiring explicit decoding for string values.

import os
from pymemcache.client.base import Client

MEMCACHED_HOST = os.environ.get('MEMCACHED_HOST', '127.0.0.1')
MEMCACHED_PORT = int(os.environ.get('MEMCACHED_PORT', '11211'))

# It's highly recommended to set timeouts to prevent blocking indefinitely
client = Client((MEMCACHED_HOST, MEMCACHED_PORT), connect_timeout=1, timeout=0.5)

key = 'my_test_key'
value = 'my_test_value'

# Set a key-value pair
success = client.set(key, value, expire=60) # expire in 60 seconds
print(f"Set '{key}': {value} - Success: {success}")

# Get the value back
retrieved_value = client.get(key)
if retrieved_value:
    # pymemcache returns bytes, decode to string if necessary
    print(f"Retrieved '{key}': {retrieved_value.decode('utf-8')}")
else:
    print(f"Key '{key}' not found or expired.")

client.close()