pylibmc

Warnings

• breaking Version 1.6.0 introduced partial incompatibility with older versions, specifically affecting interoperability with `python-memcached` due to a flag conflict. Unicode strings are now stored as UTF-8 instead of being pickled by default.
  Fix: For interoperability with older clients or Python 2/3, explicitly set the `pickle_protocol` behavior (e.g., `mc.behaviors['pickle_protocol'] = 2`).
• gotcha pylibmc is a C extension and requires the `libmemcached` C library (including development headers) to be installed on your system before `pip install pylibmc`. Without it, installation will fail with compilation errors like 'libmemcached/memcached.h: No such file or directory'.
  Fix: Install `libmemcached-dev` (Debian/Ubuntu), `libmemcached-devel` (RHEL/CentOS), or `libmemcached` (Homebrew on macOS) using your system's package manager. For example: `sudo apt-get install libmemcached-dev python3-dev`.
• gotcha For SASL authentication, typically required by cloud memcached providers, the system-level `libsasl2-modules` (or equivalent) must be installed. Failure to do so will result in 'FAILED TO SEND AUTHENTICATION TO SERVER' errors.
  Fix: Install `libsasl2-modules` (Debian/Ubuntu) or equivalent on your operating system.
• gotcha In multithreaded environments, a single `pylibmc.Client` object is not thread-safe and can lead to issues. For safe and performant concurrent access, pooling mechanisms are necessary.
  Fix: Use `pylibmc.ThreadMappedPool` or other pooling helpers provided by the library to manage client instances per thread.
• gotcha The `behaviors` configuration for `pylibmc.Client` can be set either via the constructor's `behaviors` keyword argument (newer versions) or by modifying the `mc.behaviors` attribute after instantiation (older versions). Mixing or using only the attribute in older versions could lead to unexpected behavior.
  Fix: For robust compatibility, especially if supporting older `pylibmc` versions, set behaviors using `mc.behaviors = {...}` after client creation, or ensure you are passing `behaviors` as a keyword argument if on a modern `pylibmc` version.
• gotcha There are reports of an exception being swallowed on startup under Python 3.13 that has a fix in the GitHub repository but has not been included in a release since 2022. This suggests potential compatibility issues with Python 3.13 and newer.
  Fix: If encountering issues on Python 3.13+, consider checking the latest development branch for fixes or using a slightly older Python version until a new `pylibmc` release.

Install

• pip install pylibmc Install pylibmc (requires system libmemcached)

Imports

• Client

  from pylibmc import Client

• ThreadMappedPool

  from pylibmc import ThreadMappedPool

Quickstart

This quickstart demonstrates how to connect to a memcached server using `pylibmc.Client`, perform basic `set`, `get`, and `delete` operations, and handle optional SASL authentication using environment variables. It highlights setting expiry times and utilizing the binary protocol.

import pylibmc
import os

# Memcached server addresses, can be an environment variable (e.g., for MemCachier).
# For local testing, use ['127.0.0.1:11211']. Multiple servers can be listed.
servers = os.environ.get('MEMCACHIER_SERVERS', '127.0.0.1:11211').split(',')
username = os.environ.get('MEMCACHIER_USERNAME', '')
password = os.environ.get('MEMCACHIER_PASSWORD', '')

# Initialize client. 'binary=True' enables the binary protocol, 'tcp_nodelay' improves performance.
# SASL authentication is used if username and password are provided.
if username and password:
    mc = pylibmc.Client(servers, binary=True, behaviors={"tcp_nodelay": True}, username=username, password=password)
else:
    mc = pylibmc.Client(servers, binary=True, behaviors={"tcp_nodelay": True})

# Basic operations
key = "my_test_key"
value = "Hello from pylibmc!"

# Set a value with an expiry of 60 seconds
success_set = mc.set(key, value, time=60)
print(f"Set '{key}' to '{value}': {success_set}")

# Get the value
retrieved_value = mc.get(key)
print(f"Retrieved '{key}': {retrieved_value}")

# Set multiple values
mc.set_multi({"key1": "value1", "key2": 123})
print(f"Retrieved 'key1': {mc.get('key1')}")

# Delete a key
success_delete = mc.delete(key)
print(f"Deleted '{key}': {success_delete}")
print(f"'{key}' after deletion: {mc.get(key)}")