websauna.system package

Websauna framework initialization routine.

class websauna.system.DemoInitializer(global_config, settings=None)[source]

Bases: websauna.system.Initializer

Websauna uses internally to run tests, development server.


Configure views for your application.

class websauna.system.Initializer(global_config, settings=None)[source]

Bases: object

Initializer is responsible to ramp up the frameworks and subsystems.

There exist one Initializer instance which you create in your WSGI application constructor.

  • You subclass the default Initializer provider by Websauna
  • You override the methods for the parts where you want to customize the default Websauna behavior
  • You also need to include addons and other Pyramid package configurations. This is usually done by calling self.config.include("your_pyramid_package").
  • You can add your own application specific view initializations, like self.config.scan() for your application Python modules to register @view_config directives in those.

See websauna.system.Initializer.run() for linear initialization order.

Aspect-oriented approach with websauna.utils.aspect.event_source is used to provide hooks for addons to participate initialization process.


We deliberate push imports inside methods, so that it is unlikely we’d have any import time side effects caused by some less elegant solutions, like gevent.

classmethod bootstrap(global_config)[source]

Use as WSGI entry point.

celery = None

Reference to Celery app instance


Configure admin ux.

Register templates and views for admin interface.


Set up authentication and authorization policies.

For more information see Pyramid auth documentation.


CRUD templates and views.


Configure cross-site request forgery subsystem.


Configure database.

  • Set up base model
  • Set up mechanism to create database session for requests
  • Set up transaction machinery

Calls py:func:websauna.system.model.meta.includeme.


Configure federated authentication (OAuth).

Set up Authomatic login services.

Read enabled federated authentication methods from the configuration file.


Configure subsystems for rendering Deform forms.

  • Deform templates
  • Deform JS and CSS
  • CSRf view mapper

Configure models from third party addons and dynamic SQLAlchemy fields which need access to the configuration.

Third party addons might need references to configurable models which are not available at the import time. One of these models is user - you can supply your own user model. However third party addon models might want to build foreign key relationships to this model. Thus, configure_instrumented_models() is an initialization step which is called when database setup is half way there and you want to throw in some extra models in.

This exposes Configurator to SQLAlchemy through websauna.system.model.meta.Base.metadata.pyramid_config variable.


Create and set Pyramid debug logger.

Please note that most o the logging is configured through the configuration file and that should be the primary way to do it.


Configure outgoing email backend and email test views.


Configure all models from your application.

Import related model modules and scan them.

Importing anything with websauna.system.model.meta.Base base class registers this model to an SQLAlchemy model registry for migrations.


Setup pyramid_notebook integration.


Configure system password hashing solution.

By default use Argon 2

For more information see websauna.system.user.password


Configure Redis connection pool.


Root object defines permissions for route URLs which have not their own traversing context.



Configure session storage.


Configure sitemap generation for your site.

By default this is not configured and nothing is done.


Configure static asset views.

By default we serve only core Websauna assets. Override this to add more static asset declarations to your app.


Scan all Python modules with asynchoronous and periodic tasks to be imported.


Configure tweens.


Configure user model, sign in and sign up subsystem.

  • User services
  • Sign in and sign up templates and views
  • User events

Configure forms and schemas used for login and such.

See documentation example.


Plug in user models.

This initialization step connects chosen user model to SQLAlchemy model Base. Also set up websauna.system.user.usermixin.SiteCreator logic - what happens when the first user logs in.


Configure views for your application.


Create Pyramid Configurator instance.

Return type:Configurator

Override to have our own static asset policy.


Override this method to include Websauna addons for your app.

Websauna addons are created with websauna_addon scaffold.

By default do nothing.


Create WSGI application from the current setup.

Parameters:sanity_check – True if perform post-initialization sanity checks.
Returns:WSGI application

Read secrets configuration file.

Stores API keys, such.

Return type:dict

Run the initialization and prepare Pyramid subsystems.

This is the main entry for ramping up a Websauna application. We go through various subsystem inits.


Perform post-initialization sanity checks.

This is run on every startup to check that the database table schema matches our model definitions. If there are un-run migrations this will bail out and do not let the problem to escalate later.

See also: websauna.sanity_check.


Perform any necessary WSGI application wrapping.

Wrap WSGI application to another WSGI application e.g. for the monitoring support. By default support New Relic.

exception websauna.system.RequirementsFailed[source]

Bases: Exception

Websauna minimum requirements were not met.

exception websauna.system.SanityCheckFailed[source]

Bases: Exception

Looks like the application has configuration which would fail to run.


Check for Python and Pyramid requirements.

Return type:bool
Returns:Boolean indicating if Python and Pyramid requirements are met.

Expand all environment variables in a settings dictionary.

ref: http://stackoverflow.com/a/16446566 :rtype: dict :returns: Dictionary with settings

websauna.system.get_init(global_config, settings, init_cls=None)[source]

Get Initializer class instance for WSGI-like app.

TODO: Deprecated. Use Pyramid’s bootstrap() instead.

Reads reference to the initializer from settings, resolves it and creates the initializer instance.

Example 1:

config_uri = argv[1]
init = get_init(dict(__file__=config_uri), settings)
  • global_config – Global config dictionary, having __file__ entry as given by Paster
  • settings – Settings dictionary
  • init_cls – Explicitly give the Initializer class to use, otherwise read websauna.init settings.
Return type:


websauna.system.main(global_config, **settings)[source]

Entry point for creating a Pyramid WSGI application.