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

Merge pull request #2278 from davidism/installation-docs

Browse source 
Rewrite installation docs
This commit is contained in:
David Lord 2017-05-11 14:37:31 -07:00 • committed by GitHub
commit 9dd0a0a29f
1 changed files with 110 additions and 125 deletions
Download patch file Download diff file Expand all files Collapse all files

235
docs/installation.rst
View file

@ -3,188 +3,173 @@
Installation Installation
============ ============
Flask depends on some external libraries, like `Werkzeug Python Version
<http://werkzeug.pocoo.org/>`_ and `Jinja2 <http://jinja.pocoo.org/>`_. --------------
Werkzeug is a toolkit for WSGI, the standard Python interface between web
applications and a variety of servers for both development and deployment.
Jinja2 renders templates.
So how do you get all that on your computer quickly? There are many ways you We recommend using the latest version of Python 3. Flask supports Python 3.3
could do that, but the most kick-ass method is virtualenv, so let's have a look and newer, Python 2.6 and newer, and PyPy.
at that first.
You will need Python 2.6 or newer to get started, so be sure to have an Dependencies
up-to-date Python 2.x installation. For using Flask with Python 3 have a ------------
look at :ref:`python3-support`.
.. _virtualenv: These distributions will be installed automatically when installing Flask.
virtualenv * `Werkzeug`_ implements WSGI, the standard Python interface between
---------- applications and servers.
* `Jinja`_ is a template language that renders the pages your application
serves.
* `MarkupSafe`_ comes with Jinja. It escapes untrusted input when rendering
templates to avoid injection attacks.
* `ItsDangerous`_ securely signs data to ensure its integrity. This is used
to protect Flask's session cookie.
* `Click`_ is a framework for writing command line applications. It provides
the ``flask`` command and allows adding custom management commands.
Virtualenv is probably what you want to use during development, and if you have .. _Werkzeug: http://werkzeug.pocoo.org/
shell access to your production machines, you'll probably want to use it there, .. _Jinja: http://jinja.pocoo.org/
too. .. _MarkupSafe: https://pypi.python.org/pypi/MarkupSafe
.. _ItsDangerous: https://pythonhosted.org/itsdangerous/
.. _Click: http://click.pocoo.org/
What problem does virtualenv solve? If you like Python as much as I do, Optional dependencies
chances are you want to use it for other projects besides Flask-based web ~~~~~~~~~~~~~~~~~~~~~
applications. But the more projects you have, the more likely it is that you
will be working with different versions of Python itself, or at least different
versions of Python libraries. Let's face it: quite often libraries break
backwards compatibility, and it's unlikely that any serious application will
have zero dependencies. So what do you do if two or more of your projects have
conflicting dependencies?
Virtualenv to the rescue! Virtualenv enables multiple side-by-side These distributions will not be installed automatically. Flask will detect and
installations of Python, one for each project. It doesn't actually install use them if you install them.
separate copies of Python, but it does provide a clever way to keep different
project environments isolated. Let's see how virtualenv works.
* `Blinker`_ provides support for :ref:`signals`.
* `SimpleJSON`_ is a fast JSON implementation that is compatible with
Python's ``json`` module. It is preferred for JSON operations if it is
installed.
.. admonition:: A note on python3 and virtualenv .. _Blinker: https://pythonhosted.org/blinker/
.. _SimpleJSON: https://simplejson.readthedocs.io/
If you are planning on using python3 with the virtualenv, you don't need to Virtual environments
install ``virtualenv``. Python3 has built-in support for virtual environments. --------------------
If you are on Mac OS X or Linux, chances are that the following Use a virtual environment to manage the dependencies for your project, both in
command will work for you:: development and in production.
$ sudo pip install virtualenv What problem does a virtual environment solve? The more Python projects you
have, the more likely it is that you need to work with different versions of
Python libraries, or even Python itself. Newer versions of libraries for one
project can break compatibility in another project.
It will probably install virtualenv on your system. Maybe it's even Virtual environments are independent groups of Python libraries, one for each
in your package manager. If you use Ubuntu, try:: project. Packages installed for one project will not affect other projects or
the operating system's packages.
$ sudo apt-get install python-virtualenv Python 3 comes bundled with the :mod:`venv` module to create virtual
environments. If you're using a modern version of Python, you can continue on
to the next section.
If you are on Windows and don't have the ``easy_install`` command, you must If you're using Python 2, see :ref:`install-install-virtualenv` first.
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
commands as above, but without the ``sudo`` prefix.
Creating a virtual environment .. _install-create-env:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Once you have virtualenv installed, just fire up a shell and create Create an environment
your own environment. I usually create a project folder and a :file:`virtenv` ~~~~~~~~~~~~~~~~~~~~~
folder within::
$ mkdir myproject Create a project folder and a :file:`venv` folder within:
$ cd myproject
There is a little change in how you create a virtualenv depending on which python-version you are currently using. .. code-block:: sh
**Python2** mkdir myproject
cd myproject
python3 -m venv venv
:: On Windows:
$ virtualenv virtenv .. code-block:: bat
New python executable in virtenv/bin/python
Installing setuptools, pip............done.
**Python 3.6 and above** py -3 -m venv venv
:: If you needed to install virtualenv because you are on an older version of
Python, use the following command instead:
$ python3 -m venv virtenv .. code-block:: sh
Activating a virtual environment virtualenv venv
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Now, whenever you want to work on a project, you only have to activate the On Windows:
corresponding environment. On OS X and Linux, do the following::
$ . virtenv/bin/activate .. code-block:: bat
If you are a Windows user, the following command is for you:: \Python27\Scripts\virtualenv.exe venv
$ virtenv\Scripts\activate Activate the environment
~~~~~~~~~~~~~~~~~~~~~~~~
Either way, you should now be using your virtualenv (notice how the prompt of Before you work on your project, activate the corresponding environment:
your shell has changed to show the active environment).
And if you want to go back to the real world, use the following command:: .. code-block:: sh
$ deactivate . venv/bin/activate
After doing this, the prompt of your shell should be as familiar as before. On Windows:
Now, let's move on. Enter the following command to get Flask activated in your .. code-block:: bat
virtualenv::
$ pip install Flask venv\Scripts\activate
A few seconds later and you are good to go. Your shell prompt will change to show the name of the activated environment.
Install Flask
-------------
System-Wide Installation Within the activated environment, use the following command to install Flask:
------------------------
This is possible as well, though I do not recommend it. Just run .. code-block:: sh
``pip`` with root privileges::
$ sudo pip install Flask pip install Flask
(On Windows systems, run it in a command-prompt window with administrator Living on the edge
privileges, and leave out ``sudo``.) ~~~~~~~~~~~~~~~~~~
If you want to work with the latest Flask code before it's released, install or
update the code from the master branch:
Living on the Edge .. code-block:: sh
pip install -U https://github.com/pallets/flask/archive/master.tar.gz
.. _install-install-virtualenv:
Install virtualenv
------------------ ------------------
If you want to work with the latest version of Flask, there are two ways: you If you are using Python 2, the venv module is not available. Instead,
can either let ``pip`` pull in the development version, or you can tell install `virtualenv`_.
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:: On Linux, virtualenv is provided by your package manager:
$ git clone https://github.com/pallets/flask.git .. code-block:: sh
Initialized empty Git repository in ~/dev/flask/.git/
$ cd flask
$ virtualenv virtenv
New python executable in virtenv/bin/python
Installing setuptools, pip............done.
$ . virtenv/bin/activate
$ python setup.py develop
...
Finished processing dependencies for Flask
This will pull in the dependencies and activate the git head as the current # Debian, Ubuntu
version inside the virtualenv. Then all you have to do is run ``git pull sudo apt-get install python-virtualenv
origin`` to update to the latest version.
.. _windows-easy-install: # CentOS, Fedora
sudo yum install python-virtualenv
`pip` and `setuptools` on Windows # Arch
--------------------------------- sudo pacman -S python-virtualenv
Sometimes getting the standard "Python packaging tools" like ``pip``, ``setuptools`` If you are on Mac OS X or Windows, download `get-pip.py`_, then:
and ``virtualenv`` can be a little trickier, but nothing very hard. The crucial
package you will need is pip - this will let you install
anything else (like virtualenv). Fortunately there is a "bootstrap script"
you can run to install.
If you don't currently have ``pip``, then `get-pip.py` will install it for you. .. code-block:: sh
`get-pip.py`_ sudo python2 Downloads/get-pip.py
sudo python2 -m pip install virtualenv
It should be double-clickable once you download it. If you already have ``pip``, On Windows, as an administrator:
you can upgrade them by running::
> pip install --upgrade pip setuptools .. code-block:: bat
Most often, once you pull up a command prompt you want to be able to type ``pip`` \Python27\python.exe Downloads\get-pip.py
and ``python`` which will run those things, but this might not automatically happen \Python27\python.exe -m pip install virtualenv
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 Now you can continue to :ref:`install-create-env`.
(e.g :file:`C:\Python27`), then go to :file:`Tools`, then :file:`Scripts`, then find the
:file:`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.
Finally, to install `virtualenv`_, you can simply run::
> pip install virtualenv
Then you can be off on your way following the installation instructions above.
.. _virtualenv: https://virtualenv.pypa.io/
.. _get-pip.py: https://bootstrap.pypa.io/get-pip.py .. _get-pip.py: https://bootstrap.pypa.io/get-pip.py