Welcome to Flask-Runner’s documentation!¶
Flask-Runner provides a set of standard command line arguments for Flask applications built on top of Flask-Script.
Example code¶
In its simplest usage, an application can create and initialize a Runner object as follows:
from flask import Flask
from flask.ext.runner import Runner
app = Flask(__name__)
runner = Runner(app)
@app.route('/')
def hello_world():
return 'Hello World!'
if __name__ == '__main__':
runner.run()
This application now has command line options that expose many of the configuration options that can be sent as arguments to app.run():
$ python hello.py --help
usage: hello.py [-h] [-t HOST] [-p PORT] [--threaded] [--processes PROCESSES]
[--passthrough-errors] [-d] [-r] [--noeval] [--extra FILE]
[--profile] [--profile-count COUNT]
[--profile-percent PERCENT] [--profile-regex REGEX]
[--profile-dir DIR] [--lint]
Runs the Flask development server i.e. app.run()
optional arguments:
-h, --help show this help message and exit
-t HOST, --host HOST
-p PORT, --port PORT
--threaded
--processes PROCESSES
--passthrough-errors
-d, --no-debug
-r, --no-reload
--noeval disable exception evaluation in the debugger
--reload-extra FILE additional file for the reloader to watch for changes
--profile run the profiler for each request
--profile-count COUNT
restrict profiler output to the top COUNT lines
--profile-percent PERCENT
restrict profiler output to the top PERCENT lines
--profile-regex REGEX
filter profiler output with REGEX
--profile-dir DIR write profiler results one file per request in folder
DIR
--lint run the lint validation middleware
Below are some example ways in which the application can be invoked.
To start server with all defaults (listen on http://127.0.0.1:5000 with debugger and reloader):
$ python hello.py
To listen on the public IP addresses:
$ python hello.py --host 0.0.0.0
To listen on port 8080:
$ python hello.py --port 8080
To disable the interactive debugger:
$ python hello.py --no-debug
To disable evaluation of expressions on the debugger:
$ python hello.py --noeval
To disable the interactive debugger and the reloader:
$ python hello.py --no-debug --no-reload
To enable the interactive reloader and make it watch config.txt and babel.cfg in addition to the application source files:
$ python hello.py --reload-extra config.txt --reload-extra babel.cfg
To run the Werkzeug profiler on each request showing the top 30 lines:
$ python hello.py --profile --profile-count 30
To run the Werkzeug lint middleware:
$ python hello.py --lint
Advanced Usage¶
Flask-Runner is built on top of Flask-Script and it exposes all the classes and functions of that extension with some minor additions. The following example creates a manage.py
script:
from flask import Flask
from flask.ext.runner import Manager
app = Flask(__name__)
manager = Manager(app)
@app.route('/')
def hello_world():
return 'Hello World!'
if __name__ == '__main__':
manager.run()
Note that the Manager
class is imported from flask.ext.runner
instead of flask.ext.script
. This enhanced version of the Manager class provides three default commands:
$ python manage.py
Please provide a command:
runserver Runs the Flask development server i.e. app.run()
shell Runs a Python shell inside Flask application context.
test Runs unit tests.
The runserver
command exposes the same options available when using the Runner
wrapper described above. The shell
option is the same as in Flask-Script. The test
command will run unit tests using nose
.
Refer to the Flask-Script documentation for information on adding custom commands.