What you were looking for is just not there. -
go somewhere nice - {% endblock %} + {% extends "layout.html" %} + {% block title %}Page Not Found{% endblock %} + {% block body %} +
What you were looking for is just not there. +
go somewhere nice
+ {% endblock %}
diff --git a/docs/patterns/fabric.rst b/docs/patterns/fabric.rst
index b02ad277..3dbf2146 100644
--- a/docs/patterns/fabric.rst
+++ b/docs/patterns/fabric.rst
@@ -15,7 +15,7 @@ upfront:
- Fabric 1.0 has to be installed locally. This tutorial assumes the
latest version of Fabric.
- The application already has to be a package and requires a working
- `setup.py` file (:ref:`distribute-deployment`).
+ :file:`setup.py` file (:ref:`distribute-deployment`).
- In the following example we are using `mod_wsgi` for the remote
servers. You can of course use your own favourite server there, but
for this example we chose Apache + `mod_wsgi` because it's very easy
@@ -25,14 +25,14 @@ upfront:
Creating the first Fabfile
--------------------------
-A fabfile is what controls what Fabric executes. It is named `fabfile.py`
+A fabfile is what controls what Fabric executes. It is named :file:`fabfile.py`
and executed by the `fab` command. All the functions defined in that file
will show up as `fab` subcommands. They are executed on one or more
hosts. These hosts can be defined either in the fabfile or on the command
line. In this case we will add them to the fabfile.
This is a basic first example that has the ability to upload the current
-sourcecode to the server and install it into a pre-existing
+source code to the server and install it into a pre-existing
virtual environment::
from fabric.api import *
@@ -43,37 +43,26 @@ virtual environment::
env.hosts = ['server1.example.com', 'server2.example.com']
def pack():
- # create a new source distribution as tarball
+ # build the package
local('python setup.py sdist --formats=gztar', capture=False)
def deploy():
- # figure out the release name and version
+ # figure out the package name and version
dist = local('python setup.py --fullname', capture=True).strip()
- # upload the source tarball to the temporary folder on the server
- put('dist/%s.tar.gz' % dist, '/tmp/yourapplication.tar.gz')
- # create a place where we can unzip the tarball, then enter
- # that directory and unzip it
- run('mkdir /tmp/yourapplication')
- with cd('/tmp/yourapplication'):
- run('tar xzf /tmp/yourapplication.tar.gz')
- # now setup the package with our virtual environment's
- # python interpreter
- run('/var/www/yourapplication/env/bin/python setup.py install')
- # now that all is set up, delete the folder again
- run('rm -rf /tmp/yourapplication /tmp/yourapplication.tar.gz')
- # and finally touch the .wsgi file so that mod_wsgi triggers
- # a reload of the application
+ filename = '%s.tar.gz' % dist
+
+ # upload the package to the temporary folder on the server
+ put('dist/%s' % filename, '/tmp/%s' % filename)
+
+ # install the package in the application's virtualenv with pip
+ run('/var/www/yourapplication/env/bin/pip install /tmp/%s' % filename)
+
+ # remove the uploaded package
+ run('rm -r /tmp/%s' % filename)
+
+ # touch the .wsgi file to trigger a reload in mod_wsgi
run('touch /var/www/yourapplication.wsgi')
-The example above is well documented and should be straightforward. Here
-a recap of the most common commands fabric provides:
-
-- `run` - executes a command on a remote server
-- `local` - executes a command on the local machine
-- `put` - uploads a file to the remote server
-- `cd` - changes the directory on the serverside. This has to be used
- in combination with the `with` statement.
-
Running Fabfiles
----------------
@@ -84,9 +73,9 @@ this command::
$ fab pack deploy
However this requires that our server already has the
-``/var/www/yourapplication`` folder created and
-``/var/www/yourapplication/env`` to be a virtual environment. Furthermore
-are we not creating the configuration or `.wsgi` file on the server. So
+:file:`/var/www/yourapplication` folder created and
+:file:`/var/www/yourapplication/env` to be a virtual environment. Furthermore
+are we not creating the configuration or ``.wsgi`` file on the server. So
how do we bootstrap a new server into our infrastructure?
This now depends on the number of servers we want to set up. If we just
@@ -100,22 +89,22 @@ command line::
To setup a new server you would roughly do these steps:
-1. Create the directory structure in ``/var/www``::
+1. Create the directory structure in :file:`/var/www`::
$ mkdir /var/www/yourapplication
$ cd /var/www/yourapplication
$ virtualenv --distribute env
-2. Upload a new `application.wsgi` file to the server and the
- configuration file for the application (eg: `application.cfg`)
+2. Upload a new :file:`application.wsgi` file to the server and the
+ configuration file for the application (eg: :file:`application.cfg`)
-3. Create a new Apache config for `yourapplication` and activate it.
- Make sure to activate watching for changes of the `.wsgi` file so
+3. Create a new Apache config for ``yourapplication`` and activate it.
+ Make sure to activate watching for changes of the ``.wsgi`` file so
that we can automatically reload the application by touching it.
(See :ref:`mod_wsgi-deployment` for more information)
-So now the question is, where do the `application.wsgi` and
-`application.cfg` files come from?
+So now the question is, where do the :file:`application.wsgi` and
+:file:`application.cfg` files come from?
The WSGI File
-------------
@@ -142,7 +131,7 @@ The Configuration File
----------------------
Now as mentioned above, the application will find the correct
-configuration file by looking up the `YOURAPPLICATION_CONFIG` environment
+configuration file by looking up the ``YOURAPPLICATION_CONFIG`` environment
variable. So we have to put the configuration in a place where the
application will able to find it. Configuration files have the unfriendly
quality of being different on all computers, so you do not version them
@@ -151,11 +140,12 @@ usually.
A popular approach is to store configuration files for different servers
in a separate version control repository and check them out on all
servers. Then symlink the file that is active for the server into the
-location where it's expected (eg: ``/var/www/yourapplication``).
+location where it's expected (eg: :file:`/var/www/yourapplication`).
Either way, in our case here we only expect one or two servers and we can
upload them ahead of time by hand.
+
First Deployment
----------------
@@ -168,7 +158,7 @@ can pack up the application and deploy it::
Fabric will now connect to all servers and run the commands as written
down in the fabfile. First it will execute pack so that we have our
tarball ready and then it will execute deploy and upload the source code
-to all servers and install it there. Thanks to the `setup.py` file we
+to all servers and install it there. Thanks to the :file:`setup.py` file we
will automatically pull in the required libraries into our virtual
environment.
@@ -186,11 +176,11 @@ deployment actually fun:
out the latest version on the server and then install. That way you
can also easily go back to older versions.
- hook in testing functionality so that you can deploy to an external
- server and run the testsuite.
+ server and run the test suite.
Working with Fabric is fun and you will notice that it's quite magical to
type ``fab deploy`` and see your application being deployed automatically
to one or more remote servers.
-.. _Fabric: http://fabfile.org/
+.. _Fabric: http://www.fabfile.org/
diff --git a/docs/patterns/favicon.rst b/docs/patterns/favicon.rst
index f7b2f9c8..21ea767f 100644
--- a/docs/patterns/favicon.rst
+++ b/docs/patterns/favicon.rst
@@ -4,7 +4,7 @@ Adding a favicon
A "favicon" is an icon used by browsers for tabs and bookmarks. This helps
to distinguish your website and to give it a unique brand.
-A common question is how to add a favicon to a flask application. First, of
+A common question is how to add a favicon to a Flask application. First, of
course, you need an icon. It should be 16 × 16 pixels and in the ICO file
format. This is not a requirement but a de-facto standard supported by all
relevant browsers. Put the icon in your static directory as
@@ -20,7 +20,7 @@ tag in your HTML. So, for example:
That's all you need for most browsers, however some really old ones do not
support this standard. The old de-facto standard is to serve this file,
with this name, at the website root. If your application is not mounted at
-the root path of the domain you either need to configure the webserver to
+the root path of the domain you either need to configure the web server to
serve the icon at the root or if you can't do that you're out of luck. If
however your application is the root you can simply route a redirect::
@@ -44,10 +44,10 @@ same.
The above will serve the icon via your application and if possible it's
better to configure your dedicated web server to serve it; refer to the
-webserver's documentation.
+web server's documentation.
See also
--------
-* The `Favicon Do you want to log in?
{% endblock %}
-And of course the login template:
+And here is the :file:`login.html` template which also inherits from
+:file:`layout.html`:
.. sourcecode:: html+jinja
@@ -79,7 +78,7 @@ And of course the login template:
{% if error %}
Error: {{ error }}
{% endif %}
- Upload new File
-
'''
@@ -89,7 +94,7 @@ before storing it directly on the filesystem.
filename = "../../../../home/username/.bashrc"
Assuming the number of ``../`` is correct and you would join this with
- the `UPLOAD_FOLDER` the user might have the ability to modify a file on
+ the ``UPLOAD_FOLDER`` the user might have the ability to modify a file on
the server's filesystem he or she should not modify. This does require some
knowledge about how the application looks like, but trust me, hackers
are patient :)
@@ -99,8 +104,11 @@ before storing it directly on the filesystem.
>>> secure_filename('../../../../home/username/.bashrc')
'home_username_.bashrc'
-Now one last thing is missing: the serving of the uploaded files. As of
-Flask 0.5 we can use a function that does that for us::
+Now one last thing is missing: the serving of the uploaded files. In the
+:func:`upload_file()` we redirect the user to
+``url_for('uploaded_file', filename=filename)``, that is, ``/uploads/filename``.
+So we write the :func:`uploaded_file` function to return the file of that name. As
+of Flask 0.5 we can use a function that does that for us::
from flask import send_from_directory
@@ -160,22 +168,17 @@ client asks the server every 5 seconds how much it has transmitted
already. Do you realize the irony? The client is asking for something it
should already know.
-Now there are better solutions to that work faster and more reliable. The
-web changed a lot lately and you can use HTML5, Java, Silverlight or Flash
-to get a nicer uploading experience on the client side. Look at the
-following libraries for some nice examples how to do that:
-
-- `Plupload