API

Creating Factories

broadway.factory()

Create a Factory preconfigured with the flask configuration schema, whitenoise asset serving, and simple error handling.

factory = broadway.factory()

application = factory('yourapplication')

Factory Objects

class broadway.app.Factory

Bases: object

The factory class creates flask applications. It is an implementation of the application factory pattern.

A factory performs the following tasks:

  • Create a new flask application and configure the it using the environment
  • Setup extensions to use the application
  • Load any blueprints and register them on the application

The factory object is callable, any arguments are passed to the Flask constructor.

factory = Factory()

factory.add_config_schema({
    'DEBUG': {
        'type': bool,
        'default': False,
    },
    'SECRET_KEY': str,
})

factory.add_extension('my_broadway_extension')

factory.add_blueprint('myapp.views:blueprint')

app = factory(__name__)

if __name__ == '__main__':
    app.run()
add_blueprint(blueprint, **options)

Specify a blueprint to be registered with the application.

Additional options will be passed to register_blueprint() when the application is created.

factory = Factory()

factory.add_blueprint('myapp.views:blueprint', url_prefix='/foo')
Parameters:
  • blueprint (str) – import path to blueprint object
  • options (dict) – options to pass to the blueprint
add_blueprints(*blueprints)

Specify multiple blueprints to be registered with the application.

If you need to pass extra arguments to register_blueprint() then see add_blueprint() instead.

factory = Factory()

factory.add_blueprints(
    'myapp.views.auth:blueprint',
    'myapp.views.general:blueprint'
)
Parameters:blueprints (list) – a list of import paths
add_config_schema(schema)

Add keys to the config schema

factory = Factory()

factory.add_config_schema({
    'DEBUG': {
        'type': bool,
        'default': False,
    },
    'SECRET_KEY': str,
})
Parameters:schema (dict) – a dictionary to merge into the config schema
add_extension(extension)

Specify a broadway extension to initialise

factory = Factory()

factory.add_extension('broadway_sqlalchemy')
Parameters:extension (str) – import path to extension
add_extensions(*extensions)

Specify multiple broadway extension to initialise

factory = Factory()

factory.add_extensions(
    'broadway_sqlalchemy',
    'some_extension.intergrations.broadway'
)
Parameters:extensions (list) – a list of import paths

Config Schema

A config schema representing the default configuration values for flask can be found at broadway.config.SCHEMA, this is added by default to any factory created using the factory() method.

Available options are specified in Config Schema.

Built-in Extensions

Broadway ships with a handful of built-in extensions. You load built-in extensions like others using add_extensions().

Please see Extensions for more information.

Error Handling

A default error handler that renders a template when a HTTPException is raised.

Example

factory = broadway.factory()

factory.add_extensions(
    'broadway.errors'
)

Now any HTTP exception will try and render a template from templates/errors/ named after the error code.

<!-- templates/errors/410.html -->
<html>
  <head>
    <title>410 Gone</title>
  </head>

  <body>
    <h1>410 Gone</h1>
  </body>
</html>

You can then either raise a HTTPException subclass or use abort(). Instead of the default response the template will be now rendered.

from flask import abort
from werkzeug.exceptions import Gone

@blueprint.route('/')
def my_view()
    abort(410)

@blueprint.route('/other')
def my_other_view()
    raise Gone()

Whitenoise

A broadway extension to setup WhiteNoise to serve static assets.

WhiteNoise is a production ready WSGI middleware for serving static assets. Once enabled it will serve assets from flasks static folder.

Example

factory = broadway.factory()

factory.add_extensions(
    'broadway.whitenoise'
)

See the White Noise config schema for available options.