tipfy.ext.session

This module provides sessions using secure cookies, memcache or datastore. It also offers signed flash messages and signed cookies.

See the extension wiki page.

See in Sessions Tutorial a overview of session usage.

Default configuration

tipfy.ext.session.default_config

Default configuration values for this module. Keys are:

• default_backend: Default session backend when none is specified. Built-in options are datastore, memcache or securecookie. Default is securecookie.
• secret_key: Secret key to generate session cookies. Set this to something random and unguessable. Default is tipfy.REQUIRED_VALUE (an exception is raised if it is not set).
• cookie_name: Name of the cookie to save a session or session id. Default is tipfy.session.
• cookie_args: default keyword arguments to set a cookie or securecookie. Keys are:
  • session_expires: Session expiration time in seconds. Limits the duration of the contents of a cookie, even if a session cookie exists. If None, the contents lasts as long as the cookie is valid. Default is None.
  • max_age: Cookie max age in seconds. Limits the duration of a session cookie. If None, the cookie lasts until the client is closed. Default is None.
  • domain: Domain of the cookie. To work accross subdomains the domain must be set to the main domain with a preceding dot, e.g., cookies set for .mydomain.org will work in foo.mydomain.org and bar.mydomain.org. Default is None, which means that cookies will only work for the current subdomain.
  • path: Path in which the authentication cookie is valid. Default is /.
  • secure: Make the cookie only available via HTTPS.
  • httponly: Disallow JavaScript to access the cookie.
  • force: If True, force cookie to be saved on each request, even if the session data isn’t changed. Default to False.

Middleware

class tipfy.ext.session.SessionMiddleware(backends=None, default_backend=None)

Mixins

class tipfy.ext.session.SessionMixin

A tipfy.RequestHandler that provides access to the current session.

session

A dictionary-like object that is persisted at the end of the request.

get_session(key=None, backend=None, **kwargs)

Returns a session. See SessionStore.get_session().

class tipfy.ext.session.FlashMixin

A mixin that adds get_flash() and set_flash() methods to a tipfy.RequestHandler. Must be used with SessionMiddleware.

get_flash(key=None, backend=None, **kwargs)

Returns a flash message. See SessionStore.get_flash().

set_flash(data, key=None, backend=None, **kwargs)

Sets a flash message. See SessionStore.set_flash().

class tipfy.ext.session.MessagesMixin

A tipfy.RequestHandler mixin for system messages.

messages

A list of status messages to be displayed to the user.

set_message(level, body, title=None, life=None, flash=False)

Adds a status message.

Parameters:

• level – Message level. Common values are “success”, “error”, “info” or “alert”.
• body – Message contents.
• title – Optional message title.
• life – Message life time in seconds. User interface can implement a mechanism to make the message disappear after the elapsed time. If not set, the message is permanent.

Returns:

None.

class tipfy.ext.session.CookieMixin

A mixin that adds set_cookie() and delete_cookie() methods to a tipfy.RequestHandler. Must be used with SessionMiddleware.

class tipfy.ext.session.SecureCookieMixin

A mixin that adds a get_secure_cookie() method to a tipfy.RequestHandler. Must be used with SessionMiddleware.

get_secure_cookie(key, load=True, override=False, **kwargs)

Returns a tracked secure cookie. See SessionStore.get_secure_cookie().

class tipfy.ext.session.AllSessionMixins

All session mixins combined in one.

Session Store

class tipfy.ext.session.SessionStore(request, config, backends, default_backend)

A session store that works with multiple backends. This is responsible for providing and persisting sessions, flash messages, secure cookies and ordinary cookies.

get_session(key=None, backend=None, **kwargs)

Returns a session for a given key. If the session doesn’t exist, a new session is returned.

Parameters:

• key – Cookie unique name. If not provided, uses the cookie_name value configured for this module.
• kwargs –

  Options to save the cookie. Normally not used as the configured defaults are enough for most cases. Possible keywords are same as in werkzeug.contrib.securecookie.SecureCookie.save_cookie:

  • expires
  • session_expires
  • max_age
  • path
  • domain
  • secure
  • httponly
  • force

Returns:

A dictionary-like session object.

get_secure_cookie(key, load=True, override=False, **kwargs)

Returns a secure cookie. Cookies get through this method are registered and automatically saved at the end of request.

Parameters:

• key – Cookie unique name.
• load – True to try to load an existing cookie from the request. If it is not set, a clean secure cookie is returned. False to return a new secure cookie. Default is False.
• override – If True, loads or creates a new cookie instead of reusing one previously set in the session store. Default to False.
• kwargs –

  Options to save the cookie. Normally not used as the configured defaults are enough for most cases.

  See SessionStore.get_session().

Returns:

A werkzeug.contrib.SecureCookie instance.

load_secure_cookie(key)

Loads and returns a secure cookie from request. If it is not set, a new secure cookie is returned.

This cookie must be saved using a response object at the end of a request. To get a cookie that is saved automatically, use SessionStore.get_secure_cookie().

Parameters:

• key – Cookie unique name.

Returns:

A werkzeug.contrib.SecureCookie instance.

create_secure_cookie(data=None)

Returns a new secure cookie.

This cookie must be saved using a response object at the end of a request. To get a cookie that is saved automatically, use SessionStore.get_secure_cookie().

Parameters:

• data – A dictionary to be loaded into the secure cookie.

Returns:

A werkzeug.contrib.SecureCookie instance.

get_flash(key=None, backend=None, **kwargs)

Returns a flash message. Flash messages are deleted when first read.

Parameters:

• key – Cookie unique name. If not provided, uses the flash_cookie_name value configured for this module.
• kwargs –

  Options to save the cookie. Normally not used as the configured defaults are enough for most cases.

  See SessionStore.get_session().

Returns:

The data stored in the flash, or an empty list.

set_flash(data, key=None, backend=None, **kwargs)

Sets a flash message. Flash messages are deleted when first read.

Parameters:

• data – Dictionary to be saved in the flash message.
• key – Cookie unique name. If not provided, uses the flash_cookie_name value configured for this module.
• kwargs –

  Options to save the cookie. Normally not used as the configured defaults are enough for most cases.

  See SessionStore.get_session().

Returns:

None.

set_cookie(key, value, **kwargs)

Registers a cookie or secure cookie to be saved or deleted.

Parameters:

• key – Cookie unique name.
• value – A cookie value or a werkzeug.contrib.SecureCookie instance.
• kwargs –

  Keyword arguments to save the cookie. Normally not used as the configured defaults are enough for most cases.

  See SessionStore.get_session().

Returns:

None.

delete_cookie(key, **kwargs)

Registers a cookie or secure cookie to be deleted.

Parameters:

• key – Cookie unique name.
• kwargs –

  Keyword arguments to delete the cookie. Normally not used as the configured defaults are enough for most cases.

  See SessionStore.get_session().

Returns:

None.

← tipfy.ext.pyamf | tipfy.ext.sharded_counter →