You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

245 lines
7.6 KiB

.. _larger-applications:
Larger Applications
===================
For larger applications it's a good idea to use a package instead of a
module. That is quite simple. Imagine a small application looks like
this::
/yourapplication
/yourapplication.py
/static
/style.css
/templates
layout.html
index.html
login.html
...
Simple Packages
---------------
To convert that into a larger one, just create a new folder
`yourapplication` inside the existing one and move everything below it.
Then rename `yourapplication.py` to `__init__.py`. (Make sure to delete
all `.pyc` files first, otherwise things would most likely break)
You should then end up with something like that::
/yourapplication
/yourapplication
/__init__.py
/static
/style.css
/templates
layout.html
index.html
login.html
...
But how do you run your application now? The naive ``python
yourapplication/__init__.py`` will not work. Let's just say that Python
does not want modules in packages to be the startup file. But that is not
a big problem, just add a new file called `runserver.py` next to the inner
`yourapplication` folder with the following contents::
from yourapplication import app
app.run(debug=True)
What did we gain from this? Now we can restructure the application a bit
into multiple modules. The only thing you have to remember is the
following quick checklist:
1. the `Flask` application object creation has to be in the
`__init__.py` file. That way each module can import it safely and the
`__name__` variable will resolve to the correct package.
2. all the view functions (the ones with a :meth:`~flask.Flask.route`
decorator on top) have to be imported when in the `__init__.py` file.
Not the object itself, but the module it is in. Do the importing at
the *bottom* of the file.
Here's an example `__init__.py`::
from flask import Flask
app = Flask(__name__)
import yourapplication.views
And this is what `views.py` would look like::
from yourapplication import app
@app.route('/')
def index():
return 'Hello World!'
You should then end up with something like that::
/yourapplication
/yourapplication
/__init__.py
/views.py
/static
/style.css
/templates
layout.html
index.html
login.html
...
.. admonition:: Circular Imports
Every Python programmer hates them, and yet we just added some:
circular imports (That's when two modules depend on each other. In this
case `views.py` depends on `__init__.py`). Be advised that this is a
bad idea in general but here it is actually fine. The reason for this is
that we are not actually using the views in `__init__.py` and just
ensuring the module is imported and we are doing that at the bottom of
the file.
There are still some problems with that approach but if you want to use
decorators there is no way around that. Check out the
:ref:`becomingbig` section for some inspiration how to deal with that.
.. _working-with-modules:
Working with Modules
--------------------
For larger applications with more than a dozen views it makes sense to
split the views into modules. First let's look at the typical structure of
such an application::
/yourapplication
/yourapplication
/__init__.py
/views
__init__.py
admin.py
frontend.py
/static
/style.css
/templates
layout.html
index.html
login.html
...
The views are stored in the `yourapplication.views` package. Just make
sure to place an empty `__init__.py` file in there. Let's start with the
`admin.py` file in the view package.
First we have to create a :class:`~flask.Module` object with the name of
the package. This works very similar to the :class:`~flask.Flask` object
you have already worked with, it just does not support all of the methods,
but most of them are the same.
Long story short, here's a nice and concise example::
from flask import Module
admin = Module(__name__)
@admin.route('/')
def index():
pass
@admin.route('/login')
def login():
pass
@admin.route('/logout')
def logout():
pass
Do the same with the `frontend.py` and then make sure to register the
modules in the application (`__init__.py`) like this::
from flask import Flask
from yourapplication.views.admin import admin
from yourapplication.views.frontend import frontend
app = Flask(__name__)
app.register_module(admin)
app.register_module(frontend)
So what is different when working with modules? It mainly affects URL
generation. Remember the :func:`~flask.url_for` function? When not
working with modules it accepts the name of the function as first
argument. This first argument is called the "endpoint". When you are
working with modules you can use the name of the function like you did
without, when generating modules from a function or template in the same
module. If you want to generate the URL to another module, prefix it with
the name of the module and a dot.
Confused? Let's clear that up with some examples. Imagine you have a
method in one module (say `admin`) and you want to redirect to a
different module (say `frontend`). This would look like this::
@admin.route('/to_frontend')
def to_frontend():
return redirect(url_for('frontend.index'))
@frontend.route('/')
def index():
return "I'm the frontend index"
Now let's say we only want to redirect to a different function in the same
module. Then we can either use the full qualified endpoint name like we
did in the example above, or we just use the function name::
@frontend.route('/to_index')
def to_index():
return redirect(url_for('index'))
@frontend.route('/')
def index():
return "I'm the index"
.. _modules-and-resources:
Modules and Resources
---------------------
.. versionadded:: 0.5
If a module is located inside an actual Python package it may contain
static files and templates. Imagine you have an application like this::
/yourapplication
__init__.py
/apps
/frontend
__init__.py
views.py
/static
style.css
/templates
index.html
about.html
...
/admin
__init__.py
views.py
/static
style.css
/templates
list_items.html
show_item.html
...
The static folders automatically become exposed as URLs. For example if
the `admin` module is exported with an URL prefix of ``/admin`` you can
access the style css from its static folder by going to
``/admin/static/style.css``. The URL endpoint for the static files of the
admin would be ``'admin.static'``, similar to how you refer to the regular
static folder of the whole application as ``'static'``.
If you want to refer to the templates you just have to prefix it with the
name of the module. So for the admin it would be
``render_template('admin/list_items.html')`` and so on. It is not
possible to refer to templates without the prefixed module name. This is
explicit unlike URL rules.