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