1Large Applications as Packages
2==============================
3
4Imagine a simple flask application structure that looks like this::
5
6    /yourapplication
7        yourapplication.py
8        /static
9            style.css
10        /templates
11            layout.html
12            index.html
13            login.html
14            ...
15
16While this is fine for small applications, for larger applications
17it's a good idea to use a package instead of a module.
18The :doc:`/tutorial/index` is structured to use the package pattern,
19see the :gh:`example code <examples/tutorial>`.
20
21Simple Packages
22---------------
23
24To convert that into a larger one, just create a new folder
25:file:`yourapplication` inside the existing one and move everything below it.
26Then rename :file:`yourapplication.py` to :file:`__init__.py`.  (Make sure to delete
27all ``.pyc`` files first, otherwise things would most likely break)
28
29You should then end up with something like that::
30
31    /yourapplication
32        /yourapplication
33            __init__.py
34            /static
35                style.css
36            /templates
37                layout.html
38                index.html
39                login.html
40                ...
41
42But how do you run your application now?  The naive ``python
43yourapplication/__init__.py`` will not work.  Let's just say that Python
44does not want modules in packages to be the startup file.  But that is not
45a big problem, just add a new file called :file:`setup.py` next to the inner
46:file:`yourapplication` folder with the following contents::
47
48    from setuptools import setup
49
50    setup(
51        name='yourapplication',
52        packages=['yourapplication'],
53        include_package_data=True,
54        install_requires=[
55            'flask',
56        ],
57    )
58
59In order to run the application you need to export an environment variable
60that tells Flask where to find the application instance:
61
62.. tabs::
63
64   .. group-tab:: Bash
65
66      .. code-block:: text
67
68         $ export FLASK_APP=yourapplication
69
70   .. group-tab:: CMD
71
72      .. code-block:: text
73
74         > set FLASK_APP=yourapplication
75
76   .. group-tab:: Powershell
77
78      .. code-block:: text
79
80         > $env:FLASK_APP = "yourapplication"
81
82If you are outside of the project directory make sure to provide the exact
83path to your application directory. Similarly you can turn on the
84development features like this:
85
86.. tabs::
87
88   .. group-tab:: Bash
89
90      .. code-block:: text
91
92         $ export FLASK_ENV=development
93
94   .. group-tab:: CMD
95
96      .. code-block:: text
97
98         > set FLASK_ENV=development
99
100   .. group-tab:: Powershell
101
102      .. code-block:: text
103
104         > $env:FLASK_ENV = "development"
105
106In order to install and run the application you need to issue the following
107commands::
108
109    $ pip install -e .
110    $ flask run
111
112What did we gain from this?  Now we can restructure the application a bit
113into multiple modules.  The only thing you have to remember is the
114following quick checklist:
115
1161. the `Flask` application object creation has to be in the
117   :file:`__init__.py` file.  That way each module can import it safely and the
118   `__name__` variable will resolve to the correct package.
1192. all the view functions (the ones with a :meth:`~flask.Flask.route`
120   decorator on top) have to be imported in the :file:`__init__.py` file.
121   Not the object itself, but the module it is in. Import the view module
122   **after the application object is created**.
123
124Here's an example :file:`__init__.py`::
125
126    from flask import Flask
127    app = Flask(__name__)
128
129    import yourapplication.views
130
131And this is what :file:`views.py` would look like::
132
133    from yourapplication import app
134
135    @app.route('/')
136    def index():
137        return 'Hello World!'
138
139You should then end up with something like that::
140
141    /yourapplication
142        setup.py
143        /yourapplication
144            __init__.py
145            views.py
146            /static
147                style.css
148            /templates
149                layout.html
150                index.html
151                login.html
152                ...
153
154.. admonition:: Circular Imports
155
156   Every Python programmer hates them, and yet we just added some:
157   circular imports (That's when two modules depend on each other.  In this
158   case :file:`views.py` depends on :file:`__init__.py`).  Be advised that this is a
159   bad idea in general but here it is actually fine.  The reason for this is
160   that we are not actually using the views in :file:`__init__.py` and just
161   ensuring the module is imported and we are doing that at the bottom of
162   the file.
163
164   There are still some problems with that approach but if you want to use
165   decorators there is no way around that.  Check out the
166   :doc:`/becomingbig` section for some inspiration how to deal with that.
167
168
169Working with Blueprints
170-----------------------
171
172If you have larger applications it's recommended to divide them into
173smaller groups where each group is implemented with the help of a
174blueprint.  For a gentle introduction into this topic refer to the
175:doc:`/blueprints` chapter of the documentation.
176