API reference¶

class tool.application.Application(settings=None)¶

A CLI application.

Parameter:	settings – dictionary or path to a YAML file from which the dictionary can be obtained. If None, path to the YAML file is assumed to be in the environment variable TOOL_CONF. If it is empty too, empty configuration is taken.

Usage:

#!/usr/bin/env python

from tool import Application

app = Application('conf.yaml')

if __name__=='__main__':
    app.dispatch()    # process sys.argv and call a command

The code above is a complete management script. Assuming that it’s saved as app.py, you can call it this way:

$ ./app.py shell python
$ ./app.py http serve
$ ./app.py import-some-data

All these commands are exported by certain extensions and handled by dispatch(). See Command-line interface for details.

dispatch()¶

Dispatches commands (CLI).

get_extension(name)¶

Returns a configured extension object with given dotted path.

get_feature(name)¶

Returns a configured extension object for given feature.

class tool.application.WebApplication(*args, **kwargs)¶

A WSGI-enabled Application. Supports common WSGI middleware. Can be configured to run a shell script including a WSGI application server; can be run as a WSGI application itself (i.e. is callable).

Please note that this class does not provide URL routing, web server, templating and other features common for web applications; you need to configure relevant extensions that provide these features. See Extensions for a list of extensions bundled with Tool.

wrap_in(func, *args, **kwargs)¶

Wraps current application in given WSGI middleware. Actually just appends that middleware to the stack so that is can be called later on.

Usage:

app.wrap_in(SharedDataMiddleware, {'/media': 'media'})
app.wrap_in(DebuggedApplication, evalex=True)

...which is identical to this:

app.wsgi_stack.append([SharedDataMiddleware,
                       [{'/media': 'media'], {}])
app.wsgi_stack.append([DebuggedApplication, [], {'evalex': True}])

In rare cases you will need playing directly with the stack; in most cases wrapping is sufficient as long as the order is controlled by you.

It is possible to wrap the WSGI application provided by the ApplicationManager into WSGI middleware without using wrap_in(). However, the resulting WSGI application will not have the Tool API and will only conform to the WSGI API so you won’t be able to use the WebApplication methods:

from tool import WebApplication
from werkzeug import DebuggedApplication

app = WebApplication('conf.yaml')
app = DebuggedApplication(app)   # WRONG!

if __name__=='__main__':
    app.dispatch()   # will NOT work: API is wrapped

Still, this doesn’t matter if you are not going to use the Application API after wrapping it in middleware.

Another option:

app.wsgi_app = DebuggedApplication(app.wsgi_app)

This is much better as it doesn’t hide away the API. However, it does break middleware introspection (see Debugging utilities) so use with care.

In any case, the safest method is WebApplication.wrap_in().

wsgi_app¶

Processes the stack of WSGI applications, wrapping them one in another and executing the result:

app = tool.Application()
app.wrap_in(SharedDataMiddleware, {'/media': 'media'})
app.wrap_in(DebuggedApplication, evalex=True)
>>> app.wsgi_app
<DebuggedApplication>

See, what we get is the last application in the list – or the outermost middleware. This is the real WSGI application.

Result is cached.