Clone wiki

breeze / Home

Getting started

Once breeze is installed, you can create a new application from an existing template (there is only the 'default' template for now) using the breeze-admin command (eg: breeze-admin -c my_app, use breeze-admin --help to see a list of all available options).

Then you can start your application by launching the script located at the root of the application directory.


The default configuration is stored in the module of the breeze directory. You can alter or extend this configuration by adding values in the module of the application. When you start it, the default configuration is updated with your custom settings and can be accessed afterwards through breeze.config.options.

Application structure

The standard application template uses the following structure:

  • app
    • controllers - application controllers (handlers)
    • models - applications models (if you are using an ORM for example)
    • templates - application templates (by default, tornado templates)
  • data - application data files
  • i18n - localization files (gettext, csv, ...)
  • modules - application ui modules
  • static - static files (javascript, css, ...)
    • (...)


The breeze.handlers.BaseHandler handler will fit in most cases, but tornado's RequestHandler, StaticFileHandler and RedirectHandler are still here if you need them.

breeze.handlers.asyncmongohandler and breeze.handlers.mongokithandler contain two handlers to make mongodb accessible more easily.

The route decorator allows you to define your routes on each handler instead of having to put them in a single dict, but you can still create a routes module at the root of your application and define a routes list, it will be loaded automatically.


breeze uses tornado templates by default. Therefore the default template variables from tornado are accessible from your templates, plus some new little things:

  • config: contains the whole configuration
  • isolangs: a {ISO-639-1 code: language name} dict, useful for language selectors
  • dump(var[, ...]): will pprint one or several variables in a <pre> block. If debug_address is set in the configuration, the debug trace will only be shown to the specified IP address
  • nl2br(var): returns var with <br /> tags instead of new lines
  • ucfirst(var): returns var with an uppercase first letter
  • lipsum(count=1, paragraphs=False, fmt="<p>%s</p>", maxwords=10): generates lorem ipsum sentences

Obviously, you can pass new variables to render() and render_string(), or create new handlers with custom template variables.

UI Modules

Just put your modules in the modules directory of your application, and use the breeze.decorators.uimodule decorator on your module class, it will be automatically added to the available modules list.


from tornado.web import UIModule
from breeze.decorators import uimodule

class Test(UIModule):
	def render(self):
		return "Hello world!"


Inheritance and configuration allow you to change almost everything in breeze. Have a look at breeze.bootstrap to understand what happens when you start your application.