API Reference


All library API is importable from the root level.


pyramid_sqlalchemy_sessions.config.factory_args_from_settings(settings, maybe_dotted, prefix='session.')

Convert configuration (ini) file settings to a defaults-applied dict suitable as get_session_factory() function arguments. Only validates secret key and model class settings - full validation happens inside the get_session_factory() function.


dictionary of Pyramid app settings (required)
a callable to resolve dotted Python name to a full class (required)
settings names prefix

Returns dictionary of settings, suitable as args for the get_session_factory() function.

Raises ConfigurationError if secret_key or model_class settings are invalid


Generate a random secret key as a string suitable for configuration files. Size is secret key size in bytes.

pyramid_sqlalchemy_sessions.session.get_session_factory(serializer, model_class, **kw)

Return session factory constructed using settings provided by the arguments.


a serializer object (required)
session model object (required)

Other keyword arguments are optional (using library defaults when not provided). See Configuration settings reference for details.

class pyramid_sqlalchemy_sessions.authn.UserSessionAuthenticationPolicy(callback=None, debug=False)

Authentication policy storing user ID in the session. Similar to pyramid.authentication.SessionAuthenticationPolicy, with some differences:

  • uses explicit Userid feature and will only work with session storage implementation from the pyramid_sqlalchemy_sessions package
  • doesn’t need a prefix argument, as the ID is stored explicitly in a dedicated DB column

SQL Alchemy ORM Classes (Mixins)

class pyramid_sqlalchemy_sessions.model.BaseMixin

Base session ORM class mixin. Subclass this mixin to get a minimal working session without any extra features.

class pyramid_sqlalchemy_sessions.model.FullyFeaturedSession

Class providing all features of all mixins together. Use it if you are really using all features, or if you don’t care about running dead code or having unused columns in the DB.

class pyramid_sqlalchemy_sessions.model.UseridMixin

Mixin that enables Userid feature.

class pyramid_sqlalchemy_sessions.model.CSRFMixin

Mixin that enables CSRF feature.

class pyramid_sqlalchemy_sessions.model.IdleMixin

Mixin that enables Idle Timeout feature.

class pyramid_sqlalchemy_sessions.model.AbsoluteMixin

Mixin that enables Absolute Timeout feature.

class pyramid_sqlalchemy_sessions.model.RenewalMixin

Mixin that enables Renewal Timeout feature.

class pyramid_sqlalchemy_sessions.model.ConfigCookieMixin

Mixin that enables Runtime-configurable cookie settings feature.

class pyramid_sqlalchemy_sessions.model.ConfigIdleMixin

Mixin that enables Runtime-configurable Idle Timeout feature.

class pyramid_sqlalchemy_sessions.model.ConfigAbsoluteMixin

Mixin that enables Runtime-configurable Absolute Timeout feature.

class pyramid_sqlalchemy_sessions.model.ConfigRenewalMixin

Mixin that enables Runtime-configurable Renewal Timeout feature.


class pyramid_sqlalchemy_sessions.events.InvalidCookieErrorEvent(request, exception=None)

Pyramid event. Fired when InvalidCookieError is catched

class pyramid_sqlalchemy_sessions.events.CookieCryptoErrorEvent(request, exception=None)

Pyramid event. Fired when CookieCryptoError is catched

class pyramid_sqlalchemy_sessions.events.RenewalViolationEvent(request, exception=None)

Pyramid event. Fired when received cookie contains invalid renewal id, which could be a sign of a stolen session cookie or abnormal browser behavior such as using old cookies restored from a backup.


exception pyramid_sqlalchemy_sessions.exceptions.ConfigurationError

Raised when the session factory has been incorrectly configured.

exception pyramid_sqlalchemy_sessions.exceptions.CookieCryptoError

Raised by serializer when session cookie can’t be decrypted and/or authenticated. Could be a sign of a system problem, user tampering with the cookie, or secret key mismatch.

The library will catch this exception to avoid breaking normal flow of the application. You can subscribe to CookieCryptoErrorEvent event if you want to run additional procedures when it happens.

exception pyramid_sqlalchemy_sessions.exceptions.InconsistentDataError

Raised when inconsistent session data has been found in the DB, which could be a sign of incorrect DB manipulations or misconfiguration.

exception pyramid_sqlalchemy_sessions.exceptions.InvalidCookieError

Raised by serializer when session cookie is invalid prior to decryption/deserializing. Could be a sign of a system problem or user tampering with the cookie.

The library will catch this exception to avoid breaking normal flow of the application. You can subscribe to InvalidCookieErrorEvent event if you want to run additional procedures when it happens.

exception pyramid_sqlalchemy_sessions.exceptions.SettingsError

Runtime settings errors not related to incorrect settings values. Incorrect settings values raise ValueError instead.