aiomcache

0.8.2 verified Fri Apr 17 auth: no python

aiomcache is a minimal pure Python memcached client built for asynchronous applications with `asyncio`. It provides an easy-to-use interface for common memcached operations like set, get, and delete. The current version is 0.8.2, and it is actively maintained within the `aio-libs` project with a moderate release cadence addressing bug fixes and minor features.

pip install aiomcache

Common errors

error aiomcache.exceptions.ClientException: Cannot connect to memcached: [Errno 111] Connection refused ↓

cause The memcached server is either not running, not accessible from the application's host, or configured on a different port than specified in the Client initialization.

fix

Ensure a memcached server is running and reachable on the specified host and port. Verify firewall rules or container network settings if applicable. Check the memcached server logs for issues.

error TypeError: object Client can't be used in 'await' expression ↓

cause The `aiomcache.Client` class itself is not an awaitable object. Only its asynchronous methods (e.g., `set`, `get`, `delete`, `close`) should be awaited.

fix

Initialize the client directly without await: mc = Client(host, port). Then, await its methods like await mc.set(...) or await mc.get(...).

error TypeError: 'NoneType' object is not subscriptable ↓

cause This error often occurs when attempting to access a method or element of a variable that holds `None`. In `aiomcache`, `Client.get()` returns `None` if the key does not exist in memcached, and you are trying to operate on the `None` result.

fix

Always check if the result of Client.get() is not None before attempting to decode, parse, or otherwise use it. Example: value = await mc.get(key); if value is not None: ...

Warnings

breaking Python 3.3 support was dropped with the release of v0.6.0. Projects using older Python versions must upgrade to at least Python 3.4 to use aiomcache >= 0.6.0. ↓

fix Upgrade your Python environment to 3.4 or higher. The current version (0.8.2) requires Python >= 3.8.

gotcha Prior to v0.8.0, the `Client.get()` method mistakenly used a CAS (check-and-set) operation internally. From v0.8.0 onwards, `Client.get()` correctly performs a simple GET. If your application implicitly relied on the CAS behavior of `get` (e.g., for atomicity checks), this change in behavior could be significant. ↓

fix Review code that uses `Client.get()` in versions < 0.8.0. If CAS-like behavior is required, explicitly use `Client.gets()` (available since v0.5.0) for versions >= 0.8.0.

gotcha Versions of aiomcache prior to v0.5.2 had concurrency issues in their connection pool, which could lead to race conditions or unexpected behavior under heavy load. ↓

fix Upgrade to aiomcache v0.5.2 or newer to benefit from the fix for pool concurrency issues. This ensures more robust connection handling in high-concurrency environments.

Imports

Client
```
from aiomcache import Client
```
FlagClient
```
from aiomcache import FlagClient
```
Introduced in v0.8.0 for memcached flags.

Quickstart

This quickstart demonstrates how to initialize `aiomcache.Client`, set, get, and delete data asynchronously. It uses environment variables for host and port, falling back to localhost:11211, and includes error handling and graceful client closure.

import asyncio
import os
from aiomcache import Client

async def main():
    # Connect to memcached using environment variables or fallbacks
    host = os.environ.get('MEMCACHED_HOST', '127.0.0.1')
    port = int(os.environ.get('MEMCACHED_PORT', '11211'))
    
    # Initialize the client (Client itself is not an awaitable)
    mc = Client(host, port)
    
    key = b"my_async_key"
    value = b"my_async_value"

    try:
        # Set a key-value pair
        await mc.set(key, value)
        print(f"Set '{key.decode()}'")

        # Get the value for the key
        retrieved_value = await mc.get(key)
        if retrieved_value:
            print(f"Retrieved '{key.decode()}': '{retrieved_value.decode()}'")
        else:
            print(f"Key '{key.decode()}' not found.")

        # Delete the key
        await mc.delete(key)
        print(f"Deleted '{key.decode()}'")
        
    except Exception as e:
        print(f"An error occurred: {e}")
    finally:
        # Always close the client connection(s)
        await mc.close()
        print("Client closed.")

if __name__ == "__main__":
    asyncio.run(main())