playground
/
flask
mirror of https://github.com/mitsuhiko/flask.git
1
0
Fork 0
Code Issues Releases Activity
Browse Source

docs: :command:`pip`, :option:`--debug`

pull/1240/head
defuz 10 years ago
parent
936e787cca
commit
02694d609f
14 changed files with 50 additions and 50 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 2
      CHANGES
  2. 20
      docs/cli.rst
  3. 2
      docs/extensions.rst
  4. 18
      docs/installation.rst
  5. 4
      docs/patterns/appfactories.rst
  6. 2
      docs/patterns/celery.rst
  7. 6
      docs/patterns/distribute.rst
  8. 16
      docs/quickstart.rst
  9. 8
      docs/server.rst
  10. 6
      docs/tutorial/dbinit.rst
  11. 2
      docs/tutorial/setup.rst
  12. 4
      docs/upgrading.rst
  13. 4
      flask/app.py
  14. 4
      flask/cli.py

2
CHANGES
Unescape View File

@ -28,7 +28,7 @@ Version 1.0
- Added a workaround for a limitation in Python 3.3's namespace loader. - Added a workaround for a limitation in Python 3.3's namespace loader.
- Added support for explicit root paths when using Python 3.3's namespace - Added support for explicit root paths when using Python 3.3's namespace
packages. packages.
- Added ``flask`` and the ``flask.cli`` module to start the local - Added :command:`flask` and the ``flask.cli`` module to start the local
debug server through the click CLI system. This is recommended over the old debug server through the click CLI system. This is recommended over the old
``flask.run()`` method as it works faster and more reliable due to a ``flask.run()`` method as it works faster and more reliable due to a
different design and also replaces ``Flask-Script``. different design and also replaces ``Flask-Script``.

20
docs/cli.rst
Unescape View File

@ -15,7 +15,7 @@ applications.
Basic Usage Basic Usage
----------- -----------
After installation of Flask you will now find a ``flask`` script installed After installation of Flask you will now find a :command:`flask` script installed
into your virtualenv. If you don't want to install Flask or you have a into your virtualenv. If you don't want to install Flask or you have a
special use-case you can also use ``python -m flask`` to accomplish exactly special use-case you can also use ``python -m flask`` to accomplish exactly
the same. the same.
@ -25,9 +25,9 @@ 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 desire so. register more commands there if they desire so.
For the ``flask`` script to work, an application needs to be discovered. For the :command:`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
(``FLASK_APP``) or the ``--app`` / ``-a`` parameter. It should be the (``FLASK_APP``) or the :option:`--app` / :option:`-a` parameter. It should be the
import path for your application or the path to a Python file. In the import path for your application or the path to a Python file. In the
latter case Flask will attempt to setup the Python path for you latter case Flask will attempt to setup the Python path for you
automatically and discover the module name but that might not always work. automatically and discover the module name but that might not always work.
@ -62,7 +62,7 @@ automatically also activate the correct application name.
Debug Flag Debug Flag
---------- ----------
The ``flask`` script can be run with ``--debug`` or ``--no-debug`` to The :command:`flask` script can be run with :option:`--debug` or :option:`--no-debug` to
automatically flip the debug flag of the application. This can also be automatically flip the debug flag of the application. This can also be
configured by setting ``FLASK_DEBUG`` to ``1`` or ``0``. configured by setting ``FLASK_DEBUG`` to ``1`` or ``0``.
@ -122,7 +122,7 @@ 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 :command:`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
instantiate 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 instantiates the recommendation is to create a separate file that instantiates
@ -145,14 +145,14 @@ it up::
export YOURAPPLICATION_CONFIG=/path/to/config.cfg export YOURAPPLICATION_CONFIG=/path/to/config.cfg
export FLASK_APP=/path/to/autoapp.py export FLASK_APP=/path/to/autoapp.py
From this point onwards ``flask`` will find your application. From this point onwards :command:`flask` will find your application.
.. _custom-scripts: .. _custom-scripts:
Custom Scripts Custom Scripts
-------------- --------------
While the most common way is to use the ``flask`` command, you can also While the most common way is to use the :command:`flask` command, you can also
make your own "driver scripts". Since Flask uses click for the scripts make your own "driver scripts". Since Flask uses click for the scripts
there is no reason you cannot hook these scripts into any click there is no reason you cannot hook these scripts into any click
application. There is one big caveat and that is, that commands application. There is one big caveat and that is, that commands
@ -162,7 +162,7 @@ necessary so that the commands know which Flask application they have to
work with. work with.
To understand why you might want custom scripts you need to understand how To understand why you might want custom scripts you need to understand how
click finds and executes the Flask application. If you use the ``flask`` click finds and executes the Flask application. If you use the :command:`flask`
script you specify the application to work with on the command line or script you specify the application to work with on the command line or
environment variable as an import name. This is simple but it has some environment variable as an import name. This is simple but it has some
limitations. Primarily it does not work with application factory limitations. Primarily it does not work with application factory
@ -223,7 +223,7 @@ step.
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`
decorator for the main script. It accepts a ``--config`` option and decorator for the main script. It accepts a :option:`--config` option and
then stores it in the script info so we can use it to create the then stores it in the script info so we can use it to create the
application. application.
5. All is rounded up by invoking the script. 5. All is rounded up by invoking the script.
@ -239,7 +239,7 @@ both provide custom commands to click as well as not loading your
application unless it has to. The reason for this is added flexibility. 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 :command:`flask` script is still operational on a
basic level. In addition to that it means that the individual commands basic level. In addition to that it means that the individual commands
have the option to avoid creating an instance of the Flask application have the option to avoid creating an instance of the Flask application
unless required. This is very useful as it allows the server commands for unless required. This is very useful as it allows the server commands for

2
docs/extensions.rst
Unescape View File

@ -8,7 +8,7 @@ Finding Extensions
------------------ ------------------
Flask extensions are listed on the `Flask Extension Registry`_ and can be Flask extensions are listed on the `Flask Extension Registry`_ and can be
downloaded with ``easy_install`` or ``pip``. If you add a Flask extension downloaded with :command:`easy_install` or :command:`pip`. If you add a Flask extension
as dependency to your :file:`requirements.txt` or :file:`setup.py` file they are as dependency to your :file:`requirements.txt` or :file:`setup.py` file they are
usually installed with a simple command or when your application installs. usually installed with a simple command or when your application installs.

18
docs/installation.rst
Unescape View File

@ -54,13 +54,13 @@ in your package manager. If you use Ubuntu, try::
$ sudo apt-get install python-virtualenv $ sudo apt-get install python-virtualenv
If you are on Windows and don't have the `easy_install` command, you must If you are on Windows and don't have the :command:`easy_install` command, you must
install it first. Check the :ref:`windows-easy-install` section for more install it first. Check the :ref:`windows-easy-install` section for more
information about how to do that. Once you have it installed, run the same information about how to do that. Once you have it installed, run the same
commands as above, but without the `sudo` prefix. commands as above, but without the :command:`sudo` prefix.
Once you have virtualenv installed, just fire up a shell and create Once you have virtualenv installed, just fire up a shell and create
your own environment. I usually create a project folder and a `venv` your own environment. I usually create a project folder and a :file:`venv`
folder within:: folder within::
$ mkdir myproject $ mkdir myproject
@ -99,19 +99,19 @@ System-Wide Installation
------------------------ ------------------------
This is possible as well, though I do not recommend it. Just run This is possible as well, though I do not recommend it. Just run
`pip` with root privileges:: :command:`pip` with root privileges::
$ sudo pip install Flask $ sudo pip install Flask
(On Windows systems, run it in a command-prompt window with administrator (On Windows systems, run it in a command-prompt window with administrator
privileges, and leave out `sudo`.) privileges, and leave out :command:`sudo`.)
Living on the Edge Living on the Edge
------------------ ------------------
If you want to work with the latest version of Flask, there are two ways: you If you want to work with the latest version of Flask, there are two ways: you
can either let `pip` pull in the development version, or you can tell can either let :command:`pip` pull in the development version, or you can tell
it to operate on a git checkout. Either way, virtualenv is recommended. it to operate on a git checkout. Either way, virtualenv is recommended.
Get the git checkout in a new virtualenv and run in development mode:: Get the git checkout in a new virtualenv and run in development mode::
@ -157,14 +157,14 @@ you can upgrade them by running::
> pip install --upgrade pip setuptools > pip install --upgrade pip setuptools
Most often, once you pull up a command prompt you want to be able to type ``pip`` Most often, once you pull up a command prompt you want to be able to type :command:``pip``
and ``python`` which will run those things, but this might not automatically happen and :command:``python`` which will run those things, but this might not automatically happen
on Windows, because it doesn't know where those executables are (give either a try!). on Windows, because it doesn't know where those executables are (give either a try!).
To fix this, you should be able to navigate to your Python install directory To fix this, you should be able to navigate to your Python install directory
(e.g ``C:\Python27``), then go to ``Tools``, then ``Scripts``; then find the (e.g ``C:\Python27``), then go to ``Tools``, then ``Scripts``; then find the
``win_add2path.py`` file and run that. Open a **new** Command Prompt and ``win_add2path.py`` file and run that. Open a **new** Command Prompt and
check that you can now just type ``python`` to bring up the interpreter. check that you can now just type :command:``python`` to bring up the interpreter.
Finally, to install `virtualenv`_, you can simply run:: Finally, to install `virtualenv`_, you can simply run::

4
docs/patterns/appfactories.rst
Unescape View File

@ -90,14 +90,14 @@ Using Applications
------------------ ------------------
So to use such an application you then have to create the application So to use such an application you then have to create the application
first in a separate file otherwise the ``flask`` command won't be able first in a separate file otherwise the :command:`flask` command won't be able
to find it. Here an example :file:`exampleapp.py` file that creates such to find it. Here an example :file:`exampleapp.py` file that creates such
an application:: an application::
from yourapplication import create_app from yourapplication import create_app
app = create_app('/path/to/config.cfg') app = create_app('/path/to/config.cfg')
It can then be used with the ``flask`` command:: It can then be used with the :command:`flask` command::
flask --app=exampleapp run flask --app=exampleapp run

2
docs/patterns/celery.rst
Unescape View File

@ -13,7 +13,7 @@ Installing Celery
----------------- -----------------
Celery is on the Python Package Index (PyPI), so it can be installed with Celery is on the Python Package Index (PyPI), so it can be installed with
standard Python tools like ``pip`` or ``easy_install``:: standard Python tools like :command:`pip` or :command:`easy_install`::
$ pip install celery $ pip install celery

6
docs/patterns/distribute.rst
Unescape View File

@ -18,9 +18,9 @@ make larger applications easier to distribute:
this system is the entry point support which allows one package to this system is the entry point support which allows one package to
declare an "entry point" another package can hook into to extend the declare an "entry point" another package can hook into to extend the
other package. other package.
- **installation manager**: `easy_install`, which comes with distribute - **installation manager**: :command:`easy_install`, which comes with distribute
can install other libraries for you. You can also use `pip`_ which can install other libraries for you. You can also use :command:`pip`_ which
sooner or later will replace `easy_install` which does more than just sooner or later will replace :command:`easy_install` which does more than just
installing packages for you. installing packages for you.
Flask itself, and all the libraries you can find on the cheeseshop Flask itself, and all the libraries you can find on the cheeseshop

16
docs/quickstart.rst
Unescape View File

@ -24,8 +24,8 @@ Just save it as :file:`hello.py` (or something similar) and run it with your Pyt
interpreter. Make sure to not call your application :file:`flask.py` because this interpreter. Make sure to not call your application :file:`flask.py` because this
would conflict with Flask itself. would conflict with Flask itself.
To run the application you can either use the ``flask`` command or To run the application you can either use the :command:`flask` command or
python's ``-m`` switch with Flask:: python's :option:`-m` switch with Flask::
$ flask -a hello run $ flask -a hello run
* Running on http://127.0.0.1:5000/ * Running on http://127.0.0.1:5000/
@ -79,7 +79,7 @@ To stop the server, hit control-C.
What to do if the Server does not Start What to do if the Server does not Start
--------------------------------------- ---------------------------------------
In case the ``python -m flask`` fails or ``flask`` does not exist, In case the ``python -m flask`` fails or :command:`flask` does not exist,
there are multiple reasons this might be the case. First of all you need there are multiple reasons this might be the case. First of all you need
to look at the error message. to look at the error message.
@ -87,7 +87,7 @@ Old Version of Flask
```````````````````` ````````````````````
Versions of Flask older than 1.0 use to have different ways to start the 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 application. In short, the :command:`flask` command did not exist, and
neither did ``python -m flask``. In that case you have two options: 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` either upgrade to newer Flask versions or have a look at the :ref:`server`
docs to see the alternative method for running a server. docs to see the alternative method for running a server.
@ -96,7 +96,7 @@ Python older 2.7
```````````````` ````````````````
In case you have a version of Python older than 2.7 ``python -m flask`` 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 does not work. You can either use :command:`flask` or ``python -m
flask.cli`` as an alternative. This is because Python before 2.7 does no 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 permit packages to act as executable modules. For more information see
:ref:`cli`. :ref:`cli`.
@ -104,7 +104,7 @@ permit packages to act as executable modules. For more information see
Invalid Import Name Invalid Import Name
``````````````````` ```````````````````
The ``-a`` argument to ``flask`` is the name of the module to import. In The :option:`-a` argument to :command:`flask` is the name of the module to import. In
case that module is incorrectly named you will get an import error upon 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 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. will tell you what it tried to import and why it failed.
@ -117,14 +117,14 @@ The most common reason is a typo or because you did not actually create an
Debug Mode Debug Mode
---------- ----------
The ``flask`` script is nice to start a local development server, but The :command:`flask` script is nice to start a local development server, but
you would have to restart it manually after each change to your code. 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 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 support the server will reload itself on code changes, and it will also
provide you with a helpful debugger if things go wrong. provide you with a helpful debugger if things go wrong.
There are different ways to enable the debug mode. The most obvious one There are different ways to enable the debug mode. The most obvious one
is the ``--debug`` parameter to the ``flask`` command:: is the :option:`--debug` parameter to the :command:`flask` command::
flask --debug -a hello run flask --debug -a hello run

8
docs/server.rst
Unescape View File

@ -6,13 +6,13 @@ Development Server
.. currentmodule:: flask .. currentmodule:: flask
Starting with Flask 1.0 there are multiple built-in ways to run a 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 development server. The best one is the :command:`flask` command line utility
but you can also continue using the :meth:`Flask.run` method. but you can also continue using the :meth:`Flask.run` method.
Command Line Command Line
------------ ------------
The ``flask`` command line script (:ref:`cli`) is strongly recommende for The :command:`flask` command line script (:ref:`cli`) is strongly recommende for
development because it provides a superior reload experience due to how it development because it provides a superior reload experience due to how it
loads the application. The basic usage is like this:: loads the application. The basic usage is like this::
@ -32,7 +32,7 @@ In Code
The alternative way to start the application is through the The alternative way to start the application is through the
:meth:`Flask.run` method. This will immediately launch a local server :meth:`Flask.run` method. This will immediately launch a local server
exactly the same way the ``flask`` script does. exactly the same way the :command:`flask` script does.
Example:: Example::
@ -40,7 +40,7 @@ Example::
app.run() app.run()
This works well for the common case but it does not work well for 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 development which is why from Flask 1.0 onwards the :command:`flask` method is
recommended. The reason for this is that due to how the reload mechanism recommended. The reason for this is that due to how the reload mechanism
works there are some bizarre side-effects (like executing certain code works there are some bizarre side-effects (like executing certain code
twice, sometimes crashing without message or dying when a syntax or twice, sometimes crashing without message or dying when a syntax or

6
docs/tutorial/dbinit.rst
Unescape View File

@ -20,7 +20,7 @@ requires that we provide the path to the database which can introduce
errors. It's a good idea to add a function that initializes the database errors. It's a good idea to add a function that initializes the database
for you to the application. for you to the application.
To do this we can create a function and hook it into the ``flask`` command To do this we can create a function and hook it into the :command:`flask` command
that initializes the database. Let me show you the code first. Just add that initializes the database. Let me show you the code first. Just add
this function below the `connect_db` function in :file:`flaskr.py`:: this function below the `connect_db` function in :file:`flaskr.py`::
@ -37,7 +37,7 @@ this function below the `connect_db` function in :file:`flaskr.py`::
print 'Initialized the database.' print 'Initialized the database.'
The ``app.cli.command()`` decorator registers a new command with the The ``app.cli.command()`` decorator registers a new command with the
``flask`` script. When the command executes Flask will automatically :command:`flask` script. When the command executes Flask will automatically
create a application context for us bound to the right application. create a application context for us bound to the right application.
Within the function we can then access :attr:`flask.g` and other things as Within the function we can then access :attr:`flask.g` and other things as
we would expect. When the script ends, the application context tears down we would expect. When the script ends, the application context tears down
@ -58,7 +58,7 @@ On that cursor there is a method to execute a complete script. Finally we
only have to commit the changes. SQLite 3 and other transactional only have to commit the changes. SQLite 3 and other transactional
databases will not commit unless you explicitly tell it to. databases will not commit unless you explicitly tell it to.
Now it is possible to create a database with the ``flask`` script:: Now it is possible to create a database with the :command:`flask` script::
flask --app=flaskr initdb flask --app=flaskr initdb
Initialized the database. Initialized the database.

2
docs/tutorial/setup.rst
Unescape View File

@ -93,7 +93,7 @@ without problems. Do this with the following command::
flask --app=flaskr --debug run flask --app=flaskr --debug run
The ``--debug`` flag enables or disables the interactive debugger. *Never The :option:`--debug` flag enables or disables the interactive debugger. *Never
leave debug mode activated in a production system*, because it will allow leave debug mode activated in a production system*, because it will allow
users to execute code on the server! users to execute code on the server!

4
docs/upgrading.rst
Unescape View File

@ -14,8 +14,8 @@ This section of the documentation enumerates all the changes in Flask from
release to release and how you can change your code to have a painless release to release and how you can change your code to have a painless
updating experience. updating experience.
If you want to use the `easy_install` command to upgrade your Flask If you want to use the :command:`easy_install` command to upgrade your Flask
installation, make sure to pass it the ``-U`` parameter:: installation, make sure to pass it the :option:`-U` parameter::
$ easy_install -U Flask $ easy_install -U Flask

4
flask/app.py
Unescape View File

@ -523,7 +523,7 @@ class Flask(_PackageBoundObject):
view_func=self.send_static_file) view_func=self.send_static_file)
#: The click command line context for this application. Commands #: The click command line context for this application. Commands
#: registered here show up in the ``flask`` command once the #: registered here show up in the :command:`flask` command once the
#: application has been discovered. The default commands are #: application has been discovered. The default commands are
#: provided by Flask itself and can be overridden. #: provided by Flask itself and can be overridden.
#: #:
@ -773,7 +773,7 @@ class Flask(_PackageBoundObject):
It is not recommended to use this function for development with It is not recommended to use this function for development with
automatic reloading as this is badly supported. Instead you should automatic reloading as this is badly supported. Instead you should
be using the ``flask`` command line script's ``runserver`` be using the :command:`flask` command line script's ``runserver``
support. support.
.. admonition:: Keep in Mind .. admonition:: Keep in Mind

4
flask/cli.py
Unescape View File

@ -267,10 +267,10 @@ class FlaskGroup(AppGroup):
:param add_default_commands: if this is True then the default run and :param add_default_commands: if this is True then the default run and
shell commands wil be added. shell commands wil be added.
:param add_app_option: adds the default ``--app`` option. This gets :param add_app_option: adds the default :option:`--app` option. This gets
automatically disabled if a `create_app` automatically disabled if a `create_app`
callback is defined. callback is defined.
:param add_debug_option: adds the default ``--debug`` option. :param add_debug_option: adds the default :option:`--debug` option.
:param create_app: an optional callback that is passed the script info :param create_app: an optional callback that is passed the script info
and returns the loaded app. and returns the loaded app.
""" """

Write Preview
Loading…
Cancel
Save