maya-chen/flask
1
0
Fork 0
forked from orbit-oss/flask
Code Pull requests Activity

Docs: fixes

Browse source
This commit is contained in:
Julen Ruiz Aizpuru 2014-05-07 22:32:43 +02:00
parent 1b77a3fb11
commit a700cb2a76
1 changed files with 16 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

33
docs/cli.rst
View file

@ -23,7 +23,7 @@ the same.
The way this script works is by providing access to all the commands on The way this script works is by providing access to all the commands on
your Flask application's :attr:`Flask.cli` instance as well as some your Flask application's :attr:`Flask.cli` instance as well as some
built-in commands that are always there. Flask extensions can also built-in commands that are always there. Flask extensions can also
register more commands there if they so desire. register more commands there if they desire so.
For the ``flask`` script to work, an application needs to be discovered. For the ``flask`` script to work, an application needs to be discovered.
The two most common ways are either an environment variable The two most common ways are either an environment variable
@ -106,8 +106,8 @@ Factory Functions
In case you are using factory functions to create your application (see In case you are using factory functions to create your application (see
:ref:`app-factories`) you will discover that the ``flask`` command cannot :ref:`app-factories`) you will discover that the ``flask`` command cannot
work with them directly. Flask won't be able to figure out how to work with them directly. Flask won't be able to figure out how to
instanciate your application properly by itself. Because of this reason instantiate your application properly by itself. Because of this reason
the recommendation is to create a separate file that instanciates the recommendation is to create a separate file that instantiates
applications. This is by far not the only way to make this work. Another applications. This is by far not the only way to make this work. Another
is the :ref:`custom-scripts` support. is the :ref:`custom-scripts` support.
@ -115,8 +115,7 @@ For instance if you have a factory function that creates an application
from a filename you could make a separate file that creates such an from a filename you could make a separate file that creates such an
application from an environment variable. application from an environment variable.
For instance this could be a file named ``autoapp.py`` with these This could be a file named ``autoapp.py`` with these contents::
contents::
import os import os
from yourapplication import create_app from yourapplication import create_app
@ -162,8 +161,8 @@ We won't go into detail now about the differences but if you are curious
you can have a look at the :ref:`script-info-object` section to learn all you can have a look at the :ref:`script-info-object` section to learn all
about it. about it.
To explain all of this here an example ``manage.py`` script that manages a To explain all of this, here is an example ``manage.py`` script that
hypothetical wiki application. We will go through the details manages a hypothetical wiki application. We will go through the details
afterwards:: afterwards::
import click import click
@ -185,12 +184,12 @@ afterwards::
That's a lot of code for not much, so let's go through all parts step by That's a lot of code for not much, so let's go through all parts step by
step. step.
1. At first we import regular ``click`` as well as the click extensions 1. First we import the ``click`` library as well as the click extensions
from the ``flask.cli`` package. Primarily we are here interested from the ``flask.cli`` package. Primarily we are here interested
in the :class:`~flask.cli.FlaskGroup` click group and the in the :class:`~flask.cli.FlaskGroup` click group and the
:func:`~flask.cli.script_info_option` decorator. :func:`~flask.cli.script_info_option` decorator.
2. The next thing we do is defining a function that is invoked with the 2. The next thing we do is defining a function that is invoked with the
script info object (:ref:`script-info-object`) from flask and it's script info object (:ref:`script-info-object`) from Flask and its
purpose is to fully import and create the application. This can purpose is to fully import and create the application. This can
either directly import an application object or create it (see either directly import an application object or create it (see
:ref:`app-factories`). :ref:`app-factories`).
@ -200,9 +199,9 @@ step.
will come back to this later. will come back to this later.
3. Next step is to create a :class:`FlaskGroup`. In this case we just 3. Next step is to create a :class:`FlaskGroup`. In this case we just
make an empty function with a help doc string that just does nothing make an empty function with a help doc string that just does nothing
and then pass the ``create_wiki_app`` function as factory function. and then pass the ``create_wiki_app`` function as a factory function.
Whenever click now needs to operate on a flask application it will Whenever click now needs to operate on a Flask application it will
call that function with the script info and ask for it to be created. call that function with the script info and ask for it to be created.
4. In step 2 you could see that the config is passed to the actual 4. In step 2 you could see that the config is passed to the actual
creation function. This config comes from the :func:`script_info_option` creation function. This config comes from the :func:`script_info_option`
@ -223,11 +222,11 @@ application unless it has to. The reason for this is added flexibility.
This way an application can provide custom commands, but even in the This way an application can provide custom commands, but even in the
absence of an application the ``flask`` script is still operational on a absence of an application the ``flask`` script is still operational on a
basic level. In addition to that does it mean that the individual basic level. In addition to that it means that the individual commands
commands have the option to not create an instance of the Flask have the option to avoid creating an instance of the Flask application
application unless required. This is very useful as it allows the server unless required. This is very useful as it allows the server commands for
command for instance, the load the application on first request instead of instance to load the application on a first request instead of
immediately to give a better debug experience. immediately, therefore giving a better debug experience.
All of this is provided through the :class:`flask.cli.ScriptInfo` object All of this is provided through the :class:`flask.cli.ScriptInfo` object
and some helper utilities around. The basic way it operates is that when and some helper utilities around. The basic way it operates is that when
@ -239,4 +238,4 @@ the :func:`flask.cli.script_info_option` decorator was added.
One Flask actually needs the individual Flask application it will invoke One Flask actually needs the individual Flask application it will invoke
the :meth:`flask.cli.ScriptInfo.load_app` method. This happens when the the :meth:`flask.cli.ScriptInfo.load_app` method. This happens when the
server starts, when the shell is launched or when the script looks for an server starts, when the shell is launched or when the script looks for an
application provided click command. application-provided click command.