Skip to content

Commit f8776ac

Browse files
committed
Documentation updates for the new static_path parameter
1 parent 1ad36da commit f8776ac

File tree

5 files changed

+59
-18
lines changed

5 files changed

+59
-18
lines changed

CHANGES

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,11 @@ Release date to be announced, codename to be selected
1717
deprecated for :func:`flask.send_file` because it was unreliable.
1818
Pass filenames instead or attach your own etags and provide a
1919
proper mimetype by hand.
20+
- Static file handling for modules now requires the name of the
21+
static folder to be supplied explicitly. The previous autodetection
22+
was not reliable and caused issues on Google's App Engine. Until
23+
1.0 the old behaviour will continue to work but issue dependency
24+
warnings.
2025

2126
Version 0.6.1
2227
-------------

docs/patterns/packages.rst

Lines changed: 25 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -231,18 +231,31 @@ static files and templates. Imagine you have an application like this::
231231
show_item.html
232232
...
233233

234-
The static folders automatically become exposed as URLs. For example if
235-
the `admin` module is exported with an URL prefix of ``/admin`` you can
236-
access the style css from its static folder by going to
237-
``/admin/static/style.css``. The URL endpoint for the static files of the
238-
admin would be ``'admin.static'``, similar to how you refer to the regular
239-
static folder of the whole application as ``'static'``.
240-
241-
If you want to refer to the templates you just have to prefix it with the
242-
name of the module. So for the admin it would be
243-
``render_template('admin/list_items.html')`` and so on. It is not
244-
possible to refer to templates without the prefixed module name. This is
245-
explicit unlike URL rules.
234+
The static folders become exposed as URLs when the `static_path`
235+
parameter is passed to the Module::
236+
237+
mod = Module(__name__, static_path='static')
238+
239+
The endpoint of that export will always be ``'modulename.static'``, even
240+
if the name of the folder is something else. For example if the `admin`
241+
module is exported with an URL prefix of ``/admin`` you can access the
242+
style css from its static folder by going to ``/admin/static/style.css``.
243+
244+
Templates are automatically looked up in a folder named ``templates`` when
245+
it's there. It is not necessary (and currently not possible) to specify
246+
the name of that folder to the constructor. If you want to refer to the
247+
templates you just have to prefix it with the name of the module. So for
248+
the admin it would be ``render_template('admin/list_items.html')`` and so
249+
on. It is not possible to refer to templates without the prefixed module
250+
name. This is explicit unlike URL rules.
251+
252+
.. versionchanged:: 0.7
253+
In previous versions of Flask the lookup for the static files for
254+
modules happened automatically when a folder named ``'static'`` was in
255+
the directory of the module. This caused various issues with multiple
256+
modules in the same folder and especially on Google's App Engine, so
257+
this was changed with 0.7. The old behaviour will stick around until
258+
Flask 1.0 but will issue deprecation warnings.
246259

247260
.. admonition:: References to Static Folders
248261

docs/upgrading.rst

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,24 @@ New code::
4444

4545
return send_file(my_file_object, add_etags=False)
4646

47+
The other big change was the switch of implicit static exports to explicit
48+
static exports. Previously the presence of a folder named ``'static'``
49+
in the root path of an application or module created a URL rule and
50+
endpoint that serves static files. The problem with this is that when
51+
multiple modules are in the same package all of them would share the same
52+
static folder. Furthermore on Google App Engine static files are deployed
53+
to a separate server which broke the autodetection.
54+
55+
With the new system you have to explicitly pass the name of the static
56+
folder to the module::
57+
58+
mod = Module(__name__, static_path='static')
59+
60+
This also allows you to change the name of the static folder used.
61+
62+
The deprecated behaviour will stay around until Flask 1.0 but issue
63+
deprecation warnings.
64+
4765
Version 0.6
4866
-----------
4967

flask/app.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ class Flask(_PackageBoundObject):
9393
:param static_path: can be used to specify a different path for the
9494
static folder. Defaults to ``'static'``. Setting
9595
this to `None` disables the default folder for
96-
static files.
96+
static files on the application.
9797
"""
9898

9999
#: The class that is used for request objects. See :class:`~flask.Request`

flask/module.py

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ def _register(state):
2929
from warnings import warn
3030
warn(DeprecationWarning('With Flask 0.7 the static folder '
3131
'for modules became explicit due to problems with the '
32-
'existing system on Google Appengine and multiple '
32+
'existing system on Google App Engine and multiple '
3333
'modules with the same prefix.\n'
3434
'Pass ``static_path=\'static\'`` to the Module '
3535
'constructor if you want to use static folders.\n'
@@ -118,10 +118,15 @@ def login():
118118
when registering the module with the application.
119119
:param subdomain: used to set the subdomain setting for URL rules that
120120
do not have a subdomain setting set.
121-
:param static_path: can be used to specify a different path for the
122-
static files on the web. Defaults to ``/static``.
123-
This does not affect the folder the files are served
124-
*from*.
121+
:param static_path: when specified this points to a folder (relative to
122+
the module's root path) that is exposed on the web.
123+
By default nothing is exposed although for backwards
124+
compatibility with older versions of Flask it will
125+
check if a folder named "static" exists and
126+
automatically set the `static_path` to ``'static'``
127+
if it finds a folder with that name. This
128+
functionality however is deprecated and will
129+
vanish in Flask 1.0.
125130
"""
126131
_backwards_compat_static_path = False
127132

0 commit comments

Comments
 (0)