Fast, lightweight Sessions middleware for framework (secure cookies, memcache, & SqlAlchemy)
Pull request Compare This branch is 3 commits ahead, 4 commits behind dound:master.
Latest commit dcec6d9 Jan 19, 2013 @stkim1 edit readme
Failed to load latest commit information.
bottlesessions first commit Jan 19, 2013
tests first commit Jan 19, 2013
.DS_Store first commit Jan 19, 2013
.gitignore initial commit Apr 7, 2010
README.markdown edit readme Jan 19, 2013
session.sql first commit Jan 19, 2013



bottle-sessions is a sessions library derived from gae-session for Bottle python framework for ALL session sizes. It is extremely fast, lightweight (one file), and easy to use.


  • Lightweight: One short file and references to very popular Python libraries.
  • Fast and Efficient
    • Uses secure cookies for small sessions to minimize overhead.
    • Uses memcache to minimize read times for larger sessions.
    • Minimizes number of database query() by compactly storing all values in one field.
    • Frequency of writes is minimized by only writing if there is a change, and only once per request (when the response is being sent).
    • Session data is lazily loaded - if you don't use the session for a request, zero overhead is added.
  • Secure: Protected against session hijacking, session fixation, tampering with session data, and XSS attacks.
  • High Availability is ensured by persisting changes to the datastore.
    • If you don't need this, you can use set_quick() and pop_quick() and data will only be changed in memcache.
  • Simple to Use
    • Easily installed as WSGI Middleware.
    • Session values are accessed via a dictionary interface.
    • The session automatically initializes when you first assign a value. Until then, no cookies are set and no writes are done.
    • Sessions expire automatically (based on a lifetime you can specify).
    • Thread-safe.


Python : 2.7.3
MySQL-python : 1.2.4c1
SQLAlchemy : 0.7.9
python-memcached : 1.48


  • Limited to 1MB of data in a session. (to fit in a single memcache entry)



Small sessions are stored in secure cookies. The required cookie_key parameter is used to sign cookies with an HMAC-SHA256 signature. This enables gae-sessions to notice if any change is made to the data by the client (in which case it is discarded). The data itself is stored as a base64-encoded, pickled Python dictionary - tech savvy users could view the values (though they cannot change them). If this is an issue for your application, then disable the use of cookies for storing data for small sessions by calling SessionMiddleware with cookie_only_threshold=0.

The default session lifetime is 7 days. You may configure how long a session lasts by calling SessionMiddleware with a lifetime parameter, e.g., lifetime=datetime.timedelta(hours=2)).

If you want ALL of your changes persisted ONLY to memcache, then create the middleware with no_datastore=True. This will result in faster writes but your session data might be lost at any time! If cookie-only sessions have not been disabled, then small sessions will still be stored in cookies (this is faster than memcache).

You will also want to create a cronjob to periodically remove expired sessions from the datastore. CRON JOB EXAMPLE TO BE ADDED

If you only want session information (including the session ID) to be sent from the client when the user accesses the server over SSL (i.e., when accessing URLs prefixed with "https"), then you will need to manually start the session by calling start(ssl_only=True). An existing session cannot be converted to or from an SSL-only session. Use this option with care - remember that if this option is used, a user's browser will not send any session cookies when requesting non-https URLs.

Example Usage



Author: gae-session, David Underhill
Author: Sung-Taek, Kim Updated: 2012-Jan-15 (v1.0.0)
License: Apache License Version 2.0