From e9d1fc47bf42bb13fce8799ad7727206610a7eb4 Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Mon, 28 Apr 2014 13:27:13 +0200 Subject: [PATCH] Updated docs for click support --- docs/contents.rst.inc | 2 + docs/quickstart.rst | 93 ++++++++++++++++++++++++++++++------------- docs/server.rst | 50 +++++++++++++++++++++++ docs/shell.rst | 10 +++++ 4 files changed, 127 insertions(+), 28 deletions(-) create mode 100644 docs/server.rst diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc index 17e79500..8b25e61d 100644 --- a/docs/contents.rst.inc +++ b/docs/contents.rst.inc @@ -23,6 +23,8 @@ instructions for web development with Flask. reqcontext blueprints extensions + cli + server shell patterns/index deploying/index diff --git a/docs/quickstart.rst b/docs/quickstart.rst index a4494f43..bce798f8 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -20,16 +20,19 @@ A minimal Flask application looks something like this:: def hello_world(): return 'Hello World!' - if __name__ == '__main__': - app.run() - Just save it as `hello.py` (or something similar) and run it with your Python interpreter. Make sure to not call your application `flask.py` because this would conflict with Flask itself. -:: +To run the application you can either use the ``flask`` command or +python's ``-m`` switch with Flask:: + + $ flask -a hello run + * Running on http://127.0.0.1:5000/ + +or alternatively:: - $ python hello.py + $ python -m flask -a hello run * Running on http://127.0.0.1:5000/ Now head over to `http://127.0.0.1:5000/ `_, and you @@ -51,10 +54,8 @@ So what did that code do? 4. The function is given a name which is also used to generate URLs for that particular function, and returns the message we want to display in the user's browser. -5. Finally we use the :meth:`~flask.Flask.run` function to run the local server - with our application. The ``if __name__ == '__main__':`` makes sure the - server only runs if the script is executed directly from the Python - interpreter and not used as an imported module. +5. Finally we use the Flask development server to run the local server + with our application. To stop the server, hit control-C. @@ -67,37 +68,73 @@ To stop the server, hit control-C. default because in debugging mode a user of the application can execute arbitrary Python code on your computer. - If you have `debug` disabled or trust the users on your network, you can - make the server publicly available simply by changing the call of the - :meth:`~flask.Flask.run` method to look like this:: + If you have the debugger disabled or trust the users on your network, + you can make the server publicly available simply by adding + ``--host=0.0.0.0`` to the command line:: - app.run(host='0.0.0.0') + flask -a hello run --host=0.0.0.0 This tells your operating system to listen on all public IPs. +What to do if the Server does not Start +--------------------------------------- + +In case the ``python -m flask`` fails or ``flask`` does not exist, +there are multiple reasons this might be the case. First of all you need +to look at the error message. + +Old Version of Flask +```````````````````` + +Versions of Flask older than 1.0 use to have different ways to start the +application. In short, the ``flask`` command did not exist, and +neither did ``python -m flask``. In that case you have two options: +either upgrade to newer Flask versions or have a look at the :ref:`server` +docs to see the alternative method for running a server. + +Python older 2.7 +```````````````` + +In case you have a version of Python older than 2.7 ``python -m flask`` +does not work. You can either use ``flask`` or ``python -m +flask.cli`` as an alternative. This is because Python before 2.7 does no +permit packages to act as executable modules. For more information see +:ref:`cli`. + +Invalid Import Name +``````````````````` + +The ``-a`` argument to ``flask`` is the name of the module to import. In +case that module is incorrectly named you will get an import error upon +start (or if debug is enabled when you navigate to the application). It +will tell you what it tried to import and why it failed. + +The most common reason is a typo or because you did not actually create an +``app`` object. .. _debug-mode: Debug Mode ---------- -The :meth:`~flask.Flask.run` method is nice to start a local -development server, but you would have to restart it manually after each -change to your code. That is not very nice and Flask can do better. If -you enable debug support the server will reload itself on code changes, -and it will also provide you with a helpful debugger if things go wrong. +The ``flask`` script is nice to start a local development server, but +you would have to restart it manually after each change to your code. +That is not very nice and Flask can do better. If you enable debug +support the server will reload itself on code changes, and it will also +provide you with a helpful debugger if things go wrong. -There are two ways to enable debugging. Either set that flag on the -application object:: +There are different ways to enable the debug mode. The most obvious one +is the ``--debug`` parameter to the ``flask`` command:: - app.debug = True - app.run() + flask --debug -a hello run -Or pass it as a parameter to run:: +This does the following things: - app.run(debug=True) +1. it activates the debugger +2. it activates the automatic reloader +3. it enables the debug mode on the Flask application. -Both methods have the exact same effect. +There are more parameters that are explained in the :ref:`server` docs. .. admonition:: Attention @@ -236,9 +273,9 @@ below. It tells Flask to behave as though it is handling a request, even though we are interacting with it through a Python shell. Have a look at the explanation below. :ref:`context-locals`). -Why would you want to build URLs using the URL reversing function :func:`~flask.url_for` -instead of hard-coding them into your templates? There are three good reasons -for this: +Why would you want to build URLs using the URL reversing function +:func:`~flask.url_for` instead of hard-coding them into your templates? +There are three good reasons for this: 1. Reversing is often more descriptive than hard-coding the URLs. More importantly, it allows you to change URLs in one go, without having to diff --git a/docs/server.rst b/docs/server.rst new file mode 100644 index 00000000..bd79b7d0 --- /dev/null +++ b/docs/server.rst @@ -0,0 +1,50 @@ +.. _server: + +Development Server +================== + +.. currentmodule:: flask + +Starting with Flask 1.0 there are multiple built-in ways to run a +development server. The best one is the ``flask`` command line utility +but you can also continue using the :meth:`Flask.run` method. + +Command Line +------------ + +The ``flask`` command line script (:ref:`cli`) is strongly recommende for +development because it provides a superior reload experience due to how it +loads the application. The basic usage is like this:: + + $ flask -a my_application --debug run + +This will enable the debugger, the reloader and then start the server on +*http://localhost:5000/*. + +The individual features of the server can be controlled by passing more +arguments to the ``run`` option. For instance the reloader can be +disabled:: + + $ flask -a my_application --debug run --no-reload + +In Code +------- + +The alternative way to start the application is through the +:meth:`Flask.run` method. This will immediately launch a local server +exactly the same way the ``flask`` script does. + +Example:: + + if __name__ == '__main__': + app.run() + +This works well for the common case but it does not work well for +development which is why from Flask 1.0 onwards the ``flask`` method is +recommended. The reason for this is that due to how the reload mechanism +works there are some bizarre side-effects (like executing certain code +twice, sometimes crashing without message or dieing when a syntax or +import error happens). + +It is however still a perfectly valid method for invoking a non automatic +reloading application. diff --git a/docs/shell.rst b/docs/shell.rst index 61b9dc05..f4522c1a 100644 --- a/docs/shell.rst +++ b/docs/shell.rst @@ -26,6 +26,16 @@ context. Generally it's recommended that you read the :ref:`request-context` chapter of the documentation first. +Command Line Interface +---------------------- + +Starting with Flask 1.0 the recommended way to work with the shell is the +``flask shell`` command which does a lot of this automatically for you. +For instance the shell is automatically initialized with a loaded +application context. + +For more information see :ref:`cli`. + Creating a Request Context --------------------------