pyramid_redis_sessions¶

Installation¶

It is recommended that you add pyramid_redis_sessions to your pyramid app’s setup.py file so that it will be automatically installed and managed. For instance, in the setup call in your setup.py you can add pyramid_redis_sessions to the requires list:

requires = [
    'pyramid',
    'pyramid_redis_sessions',
]
setup(
  # all your package metadata
  install_requires = requires,
)

But for a quick start, you can also get the package from PyPI with either:

$ easy_install pyramid_redis_sessions

Or if you prefer:

$ pip install pyramid_redis_sessions

For Redis installation notes see Redis Notes.

Configuration¶

Next, configure pyramid_redis_sessions via your Paste config file. Only redis.sessions.secret is required. All other settings are optional.

For complete documentation on the RedisSessionFactory that uses these settings, see API. Otherwise, keep reading for the quick list:

# session settings
redis.sessions.secret = your_cookie_signing_secret
redis.sessions.timeout = 1200

# session cookie settings
redis.sessions.cookie_name = session
redis.sessions.cookie_max_age = max_age_in_seconds
redis.sessions.cookie_path = /
redis.sessions.cookie_domain =
redis.sessions.cookie_secure = False
redis.sessions.cookie_httponly = False
redis.sessions.cookie_on_exception = True

# you can supply a redis connection string as a URL
redis.sessions.url = redis://username:password@localhost:6379/0

# or as individual settings (note: the URL gets preference if you do both)
redis.sessions.host = localhost
redis.sessions.port = 6379
redis.sessions.db = 0
redis.sessions.password = None

# additional options can be supplied to redis-py's StrictRedis
redis.sessions.socket_timeout =
redis.sessions.connection_pool =
redis.sessions.charset = utf-8
redis.sessions.errors = strict
redis.sessions.unix_socket_path =

# in the advanced section we'll cover how to instantiate your own client
redis.sessions.client_callable = my.dotted.python.callable

# along with defining your own serialize and deserialize methods
redis.sessions.serialize = cPickle.dumps
redis.sessions.deserialize = cPickle.loads

# you can specify a prefix to be used with session keys in redis
redis.sessions.prefix = mycoolprefix

# or you can supply your own UID generator callable for session keys
redis.sessions.id_generator = niftyuid

Initialization¶

Lastly, you need to tell Pyramid to use pyramid_redis_sessions as your session factory. The preferred way is adding it with config.include, like this:

def main(global_config, **settings):
    config = Configurator(settings=settings)
    config.include('pyramid_redis_sessions')

Alternately, instead of using the Configurator’s include method, you can activate Pyramid by changing your application’s .ini file, use the following line:

pyramid.includes = pyramid_redis_sessions

The above method is recommended because it’s simpler, idiomatic, and still fully configurable. It even has the added benefit of automatically resolving dotted python paths used in the advanced options (see Advanced Usage).

However, you can also explicitly pass a settings dict to the session_factory_from_settings function. This can be helpful if you configure or modify your settings in code:

from pyramid_redis_sessions import session_factory_from_settings

def main(global_config, **settings):
    config = Configurator(settings=settings)
    session_factory = session_factory_from_settings(settings)
    config.set_session_factory(session_factory)

Adjusting Timeouts Dynamically¶

It’s useful to think of a session as a way to manage online loitering. If you had a brick and mortar store, you wouldn’t want people sitting around for hours at a time not shopping. The session timeout is the physical world equivalent of some tough looking security folk that politely escort loiterers from the building.

But one day the loiterers might be the store owners, or your grandparents, or people you don’t want thrown out after a couple of minutes of not shopping. In the physical world you’d need to spend time training the security team to treat those people specially. In pyramid_redis_sessions, you only need to identify one of these users and call the following method:

request.session.adjust_timeout_for_session(timeout_in_seconds)

This will permanently change the timeout setting for that user’s session for the duration of the session.

Supplying Your Own Redis Client¶

pyramid_redis_sessions makes things easy for most developers by creating a Redis client from settings and storing the client in Pyramid’s registry for later use. However, you may find yourself wanting extra control over how the client is created.

Here are some reasons you might want to build your own client callable:

• you want to use your own wrapper or redis-py’s Redis instead of StrictRedis
• you want to choose from multiple Redis instances or modify connection settings based on the current request

To this or other ends, you can specify a dotted python path to a custom Redis client callable:

redis.sessions.client_callable = app.module.my_connection_getter

If you instantiate the session factory with includeme, Pyramid’s config machinery will follow the dotted path and attempt to return the callable.

However, if you instantiate the session factory in code (even by passing in a settings dict), you must supply the actual python callable rather than a dotted string.

Either way, the python object must be a callable that takes a Pyramid request and the keyword arguments accepted by StrictRedis (you don’t have to use StrictRedis, but those are the Redis-specific settings that will be passed to your callable).

Example:

def get_redis_client(request, **redis_options):
    redis = get_redis_instance_from_somewhere()
    if not redis:
        redis = StrictRedis(**redis_options)
        set_redis_instance_somewhere(redis)
    return redis

Special thanks to raydeo on #pyramid for the idea.

Overriding cPickle¶

By default, pyramid_redis_sessions uses cPickle for serializing and deserializing sessions to and from Redis. cPickle is very fast, stable, and widely used, so I recommend sticking with it unless you have a specific reason not to.

However, because you may very well have a specific reason not to, you can specify the following settings in your config:

redis.sessions.serialize = my_module.my_serializer
redis.sessions.deserialize = my_module.my_deserializer

If you do change the defaults you’re on your own, and it’s assumed that the following holds:

decode(encode(data)) == data

Where data is, at minimum, a python dict of session data.

One possible use case (given that redis does not support encryption or decryption) is supplying an encode function that serializes then encrypts, and a decode function that decrypts then deserializes. However, there will be a performance penalty for encrypting and decrypting all session data all the time. If you only need to encrypt some sensitive data, a simpler solution would be adding the encrypted data to the session and decrypting it when you retrieve it from the session.

Overriding the id_generator¶

pyramid_redis_sessions has a sensible and recommended default for quickly generating unique session keys. You don’t need to specify anything to use it.

However, if you’d like to prefix the keys (typically for visual inspection in redis) you can use:

redis.sessions.prefix = mycoolprefix

And if for any reason you want to generate unique IDs on your own or using a particular UID function, you can specify a callable with:

redis.sessions.id_generator = some_library.some_uid_generating_function

This is useful when you want to increase security at the cost of performance, reduce integrity for greater speed on a small internal app, or any other specialized tradeoff. But again, unless you have highly specialized requirements, please use the default.

Installing Redis¶

The best place to start is the Redis quick start guide.

If you need automated deployment with your application, you can find guides online for Redis deployment via buildout, puppet, chef, etc. If anyone would like to compile a list of recipes for these deployment options, I wholly encourage pull requests with links.

Discussions of Redis security are outside the purview of these docs, but it’s worth noting that Redis will listen on all interfaces by default, potentially exposing your data to the world. You can avoid this with a bind declaration in your redis.conf file such as:

bind 127.0.0.1

You can read more in a blog post discussing this issue here.

Why Redis?¶

Redis is fast, widely deployed, and stable. It works best when your data can fit in memory, but is configurable and still quite fast when you need to sync to disk. There are plenty of existing benchmarks, opinion pieces, and articles if you want to learn about its use cases. But for pyramid_redis_sessions, I’m interested in it specifically for these reasons:

• it really is bleeping fast (choose your own expletive)
• it has a very handy built-in mechanism for setting expirations on keys
• the watch mechanism is a nice, lightweight alternative to full transactions
• session data tends to be important but not mission critical, but if it is...
• it has configurable persistence

Feature Additions/Requests¶

I’m very interested in discussing use cases that pyramid_redis_sessions doesn’t cover but that you’d like to see in your session library.

If you have an idea you want to discuss further, ping me (erasmas) on freenode in #pyramid, or you’re also welcome to submit a pull request.

However, I do ask that you make the request on a new feature.<your feature> branch so that I can spend some time testing the code before merging to master.

Notes on Testing¶

The test suite is written in a way that may be unusual to some, so if you submit a patch I only ask that you follow the testing methodology employed here. On a technical level it boils down to:

1. Parameterizing classes or functions that connect to outside systems
2. In tests, supplying dummy instances of those classes

In practice this means never hardcoding a redis-py StrictRedis instance in pyramid_redis_sessions, and always passing in instances of DummyRedis in tests.

On a philosophical level I see outside processes as swappable strategies, and the purpose of my code is to control how those strategies are employed. For this reason tests in pyramid_redis_session should never need to use Mock.