API Reference¶

Note

All library API is importable from the root level.

Configuration¶

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.

Arguments:

settings: dictionary of Pyramid app settings (required)
maybe_dotted: a callable to resolve dotted Python name to a full class (required)
prefix: 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

pyramid_sqlalchemy_sessions.config.generate_secret_key(size=32)¶: 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.

Arguments:

serializer: a serializer object (required)
model_class: 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.

Events¶

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.

Exceptions¶

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.