beaker

library1.14.1pypypi✓ verified 89d ago

Beaker is a Python library providing robust caching and session management functionality, including WSGI middleware for web applications and decorators for standalone scripts. It supports various back-ends like file, memory, Memcached, Redis, MongoDB, and SQLAlchemy. The library is actively maintained, with the current stable version being 1.13.0.

database web-framework http-networking

pip install beaker

package ↗homepage ↗

INSTALL

IMPORT

SIG · BEAKER

beaker

databasepythonv1.14.1

Install

1.8s avg

Import

162ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.14.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.169s · 19.6MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.8s · import 0.155s · 20MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SessionMiddleware

✓ from beaker.middleware import SessionMiddleware

✗ from beaker import SessionMiddleware

SessionMiddleware resides within the middleware submodule.

CacheManager

✓ from beaker.cache import CacheManager

✗ from beaker import CacheManager

CacheManager is part of the cache submodule.

This quickstart demonstrates how to integrate Beaker's `SessionMiddleware` with a basic WSGI application. It configures a file-based session to track a counter across requests. Make sure the `data_dir` and `lock_dir` paths exist or are writable by the application.

import os from wsgiref.simple_server import make_server from beaker.middleware import SessionMiddleware def simple_app(environ, start_response): session = environ['beaker.session'] if 'counter' in session: session['counter'] += 1 else: session['counter'] = 1 response_body = [ f'The current counter is: {session["counter"]}\n'.encode('utf-8'), b'Visit this page again to increment.' ] status = '200 OK' headers = [('Content-type', 'text/plain')] start_response(status, headers) return response_body # Configure session options session_opts = { 'session.type': 'file', 'session.cookie_expires': True, 'session.data_dir': './data/sessions/data', 'session.lock_dir': './data/sessions/lock' } # Wrap the WSGI application with SessionMiddleware application = SessionMiddleware(simple_app, session_opts) # Run a simple WSGI server if __name__ == '__main__': httpd = make_server('', 8000, application) print("Serving on port 8000...") print("You can view the application at http://localhost:8000") try: httpd.serve_forever() except KeyboardInterrupt: print("Shutting down server.") # To clean up: remove the ./data/sessions directory created by the example.

Debug

Known issues

gotchaWhen using file-based or DBM backends, ensure the `session.data_dir` and `session.lock_dir` (or `cache.data_dir`, `cache.lock_dir`) directories are writable by the application. In production, these should be persistent and properly managed.

fix

Create the specified directories and set appropriate permissions (e.g., `os.makedirs('./data/sessions/data', exist_ok=True)`) or choose different backend types suitable for your deployment.

affects: All versions

deprecatedStoring arbitrary Python objects in sessions using the default `pickle` serializer can lead to security vulnerabilities and issues with unpickleable objects. It is recommended to switch to `json` serialization if your session data permits.

fix

Configure `session.data_serializer = 'json'` in your session options. Ensure all data stored in the session is JSON-serializable. Otherwise, only store basic, trusted, and serializable Python types.

affects: All versions

gotchaThe `memory` backend for sessions is process-local. Session data will be lost if the application process restarts. This backend is generally suitable for development only.

fix

For production environments, use persistent backends like `file`, `dbm`, `memcached`, `redis`, or `mongodb` for session storage to ensure data survives process restarts.

affects: All versions

breakingIn `beaker` versions prior to 1.9.1, `async` was used as a variable name in some internal code, which became a keyword in Python 3.7. This can lead to `SyntaxError` when running on Python 3.7 or newer.

fix

Upgrade Beaker to version 1.9.1 or higher. The fix was included in release 1.9.1 (2018-04-09).

affects: <1.9.1

Errors

Common errors & fixes

<type 'exceptions.KeyError'> at / 'beaker.session'

The `SessionMiddleware` was not correctly applied to the WSGI application, or the application code is attempting to access `environ['beaker.session']` before it has been made available by the middleware.

fix

Ensure your WSGI application is wrapped by `SessionMiddleware` with proper configuration, e.g., `application = SessionMiddleware(your_app, session_opts)`.

TypeError: can't pickle <_io.TextIOWrapper object at ...>

You are attempting to store an object in the session that cannot be serialized by Python's `pickle` module, which is Beaker's default serializer.

fix

Refactor your code to store only primitive types or objects that are known to be pickleable. Alternatively, configure Beaker to use a different serializer: `session_opts = {..., 'session.data_serializer': 'json'}` (if your data is JSON-compatible).

SyntaxError: invalid syntax (on a line containing 'async')

You are running an older version of Beaker (<1.9.1) on Python 3.7 or newer, where 'async' became a reserved keyword, causing a syntax error in Beaker's internal code.

fix

Upgrade the Beaker library to version 1.9.1 or later (`pip install --upgrade beaker`) to resolve the keyword conflict.

Upgrade

Version history

1.14.1latest on PyPI · released May 30, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

24 hits · last 30 days

node

Anthropic

OpenAI (training)

Resources

packagehttps://pypi.org/project/beaker/ ↗

homepagehttps://beaker.readthedocs.io/ ↗