Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 37 ยท Getting Started

Your First Memcached Client in Python

Use Memcached from Python with pymemcache, handle misses and a down server gracefully, and practice with a MiniMemcached stand-in that runs right in your browser.

Real applications do not type protocol lines. They use a client library that opens connections, encodes values, chooses a server and parses replies. In Python the most popular pure-Python client is pymemcache; PHP has Memcached, Java has spymemcached/XMemcached, Node has memjs, and Go has gomemcache. They all expose the same small set of operations you already know from the protocol.

This lesson shows the real pymemcache code as read-only blocks (it needs a server on port 11211), then rebuilds the same flow with the MiniMemcached stand-in so you can run and change it here.

The real client

Terminal
pip install pymemcache
Python
from pymemcache.client.base import Client

client = Client(("127.0.0.1", 11211), connect_timeout=0.5, timeout=0.5)

client.set("greeting", "hello", expire=300)
print(client.get("greeting"))        # b'hello'  (bytes!)
print(client.get("missing"))         # None
client.delete("greeting")

Three details are worth noticing. Values come back as bytes unless you configure a serializer. A miss returns None, not an exception. And the timeouts are short on purpose: a cache that is slow is worse than no cache, so give it a half second at most and move on.

The stand-in used in this course

MiniMemcached has the same method names and the same return words as the protocol (STORED, NOT_STORED, DELETED, ...). It keeps data in a Python dictionary, uses a fake clock so expiry can be tested instantly, and can limit the number of items to show eviction. It stores Python strings; the real server stores bytes.

Python Set, get and delete with MiniMemcached

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The class prints nothing by itself; every method returns a value so you can see exactly what a real client would hand you.

Cache calls must never break the page

A cache outage should make your site slower, not broken. That means wrapping cache operations so errors are treated as misses. Real clients raise exceptions on connection errors; the helper below imitates that with a server that is "down".

Python Treat a dead cache as a miss

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The user still gets an answer. The database takes more load while the cache is down, which is exactly why you also protect the database (rate limits, connection pools); you will return to this in the chapter on failure.

Serialization: more than strings

Memcached stores bytes. To cache a dictionary or list you must convert it, usually to JSON. pymemcache lets you plug in a serializer and deserializer, and often uses the flags field to remember the type.

Python
import json
from pymemcache.client.base import Client

def to_bytes(key, value):
    if isinstance(value, bytes):
        return value, 0
    if isinstance(value, str):
        return value.encode(), 1
    return json.dumps(value).encode(), 2

def from_bytes(key, data, flags):
    if flags == 0:
        return data
    if flags == 1:
        return data.decode()
    return json.loads(data)

client = Client(("127.0.0.1", 11211), serde=type("S", (), {
    "serialize": staticmethod(to_bytes),
    "deserialize": staticmethod(from_bytes),
}))

The idea is the important part, and you can run it here: the flags value records what kind of data was stored so it can be turned back correctly.

Python Use flags to remember the type

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Be careful with serializers like Python's pickle: unpickling data from a cache that an attacker could write to can run arbitrary code. JSON is safer and works across languages, which matters when a PHP site and a Python service share one cache.

Habits of a good client setup

  • Short timeouts (a few hundred milliseconds) on connect and read.
  • Reuse connections. Opening a TCP connection per request is slow; use a pool or persistent client.
  • Prefix keys with the application and a version, e.g. shop:v3:product:42, so different apps and deploys do not collide.
  • Handle None everywhere: a miss is normal, not exceptional.
  • Log misses and errors as metrics, not as stack traces for every request.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does pymemcache return by default for a key that is not in the cache?

    A miss is normal, so the client returns None. Your code must treat None as 'go load it from the source'.
  2. 2. Why use a short timeout for cache calls?

    If the cache hangs, every request hangs. A tight timeout converts a sick cache into a miss.
  3. 3. What are the flags in a Memcached item often used for in clients?

    Flags are a 32-bit number the server stores untouched. Clients use them as a type tag.
  4. 4. Why is JSON usually safer than pickle for cached values?

    Unpickling runs arbitrary code if the data was tampered with. JSON only produces plain data.

Summary

  • Clients such as pymemcache wrap the protocol: set, get, delete, expiry and serialization.
  • Values are bytes; a miss is None; flags can carry a type tag.
  • Treat any cache error as a miss so an outage slows the site but does not break it.
  • Prefer JSON over pickle, keep timeouts short and prefix your keys.
  • MiniMemcached mirrors the real return words so what you practice here transfers.

Next: Why Caching Works