orbit-oss/flask
4
4
Fork 2
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Compare commits

base: orbit-oss:main
Branches Tags
orbit-oss:main
orbit-oss:stable
orbit-oss:automatic-options
orbit-oss:workflow
orbit-oss:3.1.3
orbit-oss:3.1.2
orbit-oss:3.1.1
orbit-oss:3.1.0
orbit-oss:2.3.x
orbit-oss:2.2.x
orbit-oss:2.1.x
orbit-oss:2.0.x
orbit-oss:1.1.x
orbit-oss:1.0.x
orbit-oss:0.12.x
orbit-oss:3.0.3
orbit-oss:3.0.2
orbit-oss:3.0.1
orbit-oss:3.0.0
orbit-oss:2.3.3
orbit-oss:2.2.5
orbit-oss:2.3.2
orbit-oss:2.3.1
orbit-oss:2.3.0
orbit-oss:2.2.4
orbit-oss:2.2.3
orbit-oss:2.2.2
orbit-oss:2.2.1
orbit-oss:2.2.0
orbit-oss:2.1.3
orbit-oss:2.1.2
orbit-oss:2.1.1
orbit-oss:2.1.0
orbit-oss:2.0.3
orbit-oss:2.0.2
orbit-oss:2.0.1
orbit-oss:1.1.4
orbit-oss:1.1.3
orbit-oss:2.0.0
orbit-oss:2.0.0rc2
orbit-oss:2.0.0rc1
orbit-oss:1.1.2
orbit-oss:0.12.5
orbit-oss:1.1.1
orbit-oss:1.1.0
orbit-oss:1.0.4
orbit-oss:1.0.3
orbit-oss:1.0.2
orbit-oss:1.0.1
orbit-oss:0.12.4
orbit-oss:1.0
orbit-oss:0.12.3
orbit-oss:0.12.2
orbit-oss:0.12.1
orbit-oss:0.12
orbit-oss:0.11.1
orbit-oss:0.11
orbit-oss:0.10.1
orbit-oss:0.10
orbit-oss:0.9
orbit-oss:0.8.1
orbit-oss:0.8
orbit-oss:0.7.2
orbit-oss:0.7.1
orbit-oss:0.7
orbit-oss:0.6.1
orbit-oss:0.6
orbit-oss:0.5
orbit-oss:0.4
orbit-oss:0.3.1
orbit-oss:0.3
orbit-oss:0.2
orbit-oss:0.1
..
compare: orbit-oss:0.3.1
Branches Tags
orbit-oss:main
orbit-oss:stable
orbit-oss:automatic-options
orbit-oss:workflow
orbit-oss:3.1.3
orbit-oss:3.1.2
orbit-oss:3.1.1
orbit-oss:3.1.0
orbit-oss:2.3.x
orbit-oss:2.2.x
orbit-oss:2.1.x
orbit-oss:2.0.x
orbit-oss:1.1.x
orbit-oss:1.0.x
orbit-oss:0.12.x
orbit-oss:3.0.3
orbit-oss:3.0.2
orbit-oss:3.0.1
orbit-oss:3.0.0
orbit-oss:2.3.3
orbit-oss:2.2.5
orbit-oss:2.3.2
orbit-oss:2.3.1
orbit-oss:2.3.0
orbit-oss:2.2.4
orbit-oss:2.2.3
orbit-oss:2.2.2
orbit-oss:2.2.1
orbit-oss:2.2.0
orbit-oss:2.1.3
orbit-oss:2.1.2
orbit-oss:2.1.1
orbit-oss:2.1.0
orbit-oss:2.0.3
orbit-oss:2.0.2
orbit-oss:2.0.1
orbit-oss:1.1.4
orbit-oss:1.1.3
orbit-oss:2.0.0
orbit-oss:2.0.0rc2
orbit-oss:2.0.0rc1
orbit-oss:1.1.2
orbit-oss:0.12.5
orbit-oss:1.1.1
orbit-oss:1.1.0
orbit-oss:1.0.4
orbit-oss:1.0.3
orbit-oss:1.0.2
orbit-oss:1.0.1
orbit-oss:0.12.4
orbit-oss:1.0
orbit-oss:0.12.3
orbit-oss:0.12.2
orbit-oss:0.12.1
orbit-oss:0.12
orbit-oss:0.11.1
orbit-oss:0.11
orbit-oss:0.10.1
orbit-oss:0.10
orbit-oss:0.9
orbit-oss:0.8.1
orbit-oss:0.8
orbit-oss:0.7.2
orbit-oss:0.7.1
orbit-oss:0.7
orbit-oss:0.6.1
orbit-oss:0.6
orbit-oss:0.5
orbit-oss:0.4
orbit-oss:0.3.1
orbit-oss:0.3
orbit-oss:0.2
orbit-oss:0.1

5 commits
main ... 0.3.1

Author SHA1 Message Date
Armin Ronacher
6b3e616cf9 Fixed build process 2010-05-28 21:21:28 +02:00
Armin Ronacher
bf2b2f25f9 Added missing message 2010-05-28 21:07:28 +02:00
Armin Ronacher
a1cd92e459 Removed some unused code 2010-05-28 21:07:06 +02:00
Armin Ronacher
218178164f Fixed an error reporting bug with flask.Config.from_envvar 2010-05-28 21:06:39 +02:00
Armin Ronacher
2e83bd1f50 This branch will be 0.3.1 2010-05-28 20:48:21 +02:00
294 changed files with 7809 additions and 34647 deletions
Download patch file Download diff file Expand all files Collapse all files

17
.devcontainer/devcontainer.json
View file

@ -1,17 +0,0 @@
{
"name": "pallets/flask",
"image": "mcr.microsoft.com/devcontainers/python:3",
"customizations": {
"vscode": {
"settings": {
"python.defaultInterpreterPath": "${workspaceFolder}/.venv",
"python.terminal.activateEnvInCurrentTerminal": true,
"python.terminal.launchArgs": [
"-X",
"dev"
]
}
}
},
"onCreateCommand": ".devcontainer/on-create-command.sh"
}

7
.devcontainer/on-create-command.sh
View file

@ -1,7 +0,0 @@
#!/bin/bash
set -e
python3 -m venv --upgrade-deps .venv
. .venv/bin/activate
pip install -r requirements/dev.txt
pip install -e .
pre-commit install --install-hooks

13
.editorconfig
View file

@ -1,13 +0,0 @@
root = true
[*]
indent_style = space
indent_size = 4
insert_final_newline = true
trim_trailing_whitespace = true
end_of_line = lf
charset = utf-8
max_line_length = 88
[*.{css,html,js,json,jsx,scss,ts,tsx,yaml,yml}]
indent_size = 2

27
.github/ISSUE_TEMPLATE/bug-report.md vendored
View file

@ -1,27 +0,0 @@
---
name: Bug report
about: Report a bug in Flask (not other projects which depend on Flask)
---
<!--
This issue tracker is a tool to address bugs in Flask itself. Please use
GitHub Discussions or the Pallets Discord for questions about your own code.
Replace this comment with a clear outline of what the bug is.
-->
<!--
Describe how to replicate the bug.
Include a minimal reproducible example that demonstrates the bug.
Include the full traceback if there was an exception.
-->
<!--
Describe the expected behavior that should have happened but didn't.
-->
Environment:
- Python version:
- Flask version:

11
.github/ISSUE_TEMPLATE/config.yml vendored
View file

@ -1,11 +0,0 @@
blank_issues_enabled: false
contact_links:
- name: Security issue
url: https://github.com/pallets/flask/security/advisories/new
about: Do not report security issues publicly. Create a private advisory.
- name: Questions on GitHub Discussions
url: https://github.com/pallets/flask/discussions/
about: Ask questions about your own code on the Discussions tab.
- name: Questions on Discord
url: https://discord.gg/pallets
about: Ask questions about your own code on our Discord chat.

15
.github/ISSUE_TEMPLATE/feature-request.md vendored
View file

@ -1,15 +0,0 @@
---
name: Feature request
about: Suggest a new feature for Flask
---
<!--
Replace this comment with a description of what the feature should do.
Include details such as links to relevant specs or previous discussions.
-->
<!--
Replace this comment with an example of the problem which this feature
would resolve. Is this problem solvable without changes to Flask, such
as by subclassing or using an extension?
-->

25
.github/pull_request_template.md vendored
View file

@ -1,25 +0,0 @@
<!--
Before opening a PR, open a ticket describing the issue or feature the
PR will address. An issue is not required for fixing typos in
documentation, or other simple non-code changes.
Replace this comment with a description of the change. Describe how it
addresses the linked ticket.
-->
<!--
Link to relevant issues or previous PRs, one per line. Use "fixes" to
automatically close an issue.
fixes #<issue number>
-->
<!--
Ensure each step in CONTRIBUTING.rst is complete, especially the following:
- Add tests that demonstrate the correct behavior of the change. Tests
should fail without the change.
- Add or update relevant docs, in the docs folder and in code.
- Add an entry in CHANGES.rst summarizing the change and linking to the issue.
- Add `.. versionchanged::` entries in any relevant code docs.
-->

26
.github/workflows/lock.yaml vendored
View file

@ -1,26 +0,0 @@
name: Lock inactive closed issues
# Lock closed issues that have not received any further activity for two weeks.
# This does not close open issues, only humans may do that. It is easier to
# respond to new issues with fresh examples rather than continuing discussions
# on old issues.
on:
schedule:
- cron: '0 0 * * *'
permissions: {}
concurrency:
group: lock
cancel-in-progress: true
jobs:
lock:
runs-on: ubuntu-latest
permissions:
issues: write
pull-requests: write
discussions: write
steps:
- uses: dessant/lock-threads@7266a7ce5c1df01b1c6db85bf8cd86c737dadbe7 # v6.0.0
with:
issue-inactive-days: 14
pr-inactive-days: 14
discussion-inactive-days: 14

29
.github/workflows/pre-commit.yaml vendored
View file

@ -1,29 +0,0 @@
name: pre-commit
on:
pull_request:
push:
branches: [main, stable]
permissions: {}
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true
jobs:
main:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
persist-credentials: false
- uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
with:
enable-cache: true
prune-cache: false
- uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
id: setup-python
with:
python-version-file: pyproject.toml
- uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
with:
path: ~/.cache/pre-commit
key: pre-commit|${{ hashFiles('pyproject.toml', '.pre-commit-config.yaml') }}
- run: uv run --locked --no-default-groups --group pre-commit pre-commit run --show-diff-on-failure --color=always --all-files

62
.github/workflows/publish.yaml vendored
View file

@ -1,62 +0,0 @@
name: Publish
on:
push:
tags: ['*']
permissions: {}
concurrency:
group: publish-${{ github.event.push.ref }}
cancel-in-progress: true
jobs:
build:
runs-on: ubuntu-latest
outputs:
artifact-id: ${{ steps.upload-artifact.outputs.artifact-id }}
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
persist-credentials: false
- uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
with:
enable-cache: false
prune-cache: false
- uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
with:
python-version-file: pyproject.toml
- run: echo "SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)" >> $GITHUB_ENV
- run: uv build
- uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
id: upload-artifact
with:
name: dist
path: dist/
if-no-files-found: error
create-release:
needs: [build]
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
with:
artifact-ids: ${{ needs.build.outputs.artifact-id }}
path: dist/
- name: create release
run: gh release create --draft --repo ${GITHUB_REPOSITORY} ${GITHUB_REF_NAME} dist/*
env:
GH_TOKEN: ${{ github.token }}
publish-pypi:
needs: [build]
environment:
name: publish
url: https://pypi.org/project/Flask/${{ github.ref_name }}
runs-on: ubuntu-latest
permissions:
id-token: write
steps:
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
with:
artifact-ids: ${{ needs.build.outputs.artifact-id }}
path: dist/
- uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
with:
packages-dir: "dist/"

63
.github/workflows/tests.yaml vendored
View file

@ -1,63 +0,0 @@
name: Tests
on:
pull_request:
paths-ignore: ['docs/**', 'README.md']
push:
branches: [main, stable]
paths-ignore: ['docs/**', 'README.md']
permissions: {}
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true
jobs:
tests:
name: ${{ matrix.name || matrix.python }}
runs-on: ${{ matrix.os || 'ubuntu-latest' }}
strategy:
fail-fast: false
matrix:
include:
- {python: '3.14'}
- {python: '3.14t'}
- {name: Windows, python: '3.14', os: windows-latest}
- {name: Mac, python: '3.14', os: macos-latest}
- {python: '3.13'}
- {python: '3.12'}
- {python: '3.11'}
- {python: '3.10'}
- {name: PyPy, python: 'pypy-3.11', tox: pypy3.11}
- {name: Minimum Versions, python: '3.14', tox: tests-min}
- {name: Development Versions, python: '3.10', tox: tests-dev}
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
persist-credentials: false
- uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
with:
enable-cache: true
prune-cache: false
- uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
with:
python-version: ${{ matrix.python }}
- run: uv run --locked --no-default-groups --group dev tox run
env:
TOX_ENV: ${{ matrix.tox || format('py{0}', matrix.python) }}
typing:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
persist-credentials: false
- uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
with:
enable-cache: true
prune-cache: false
- uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
with:
python-version-file: pyproject.toml
- name: cache mypy
uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
with:
path: ./.mypy_cache
key: mypy|${{ hashFiles('pyproject.toml') }}
- run: uv run --locked --no-default-groups --group dev tox run -e typing

22
.github/workflows/zizmor.yaml vendored
View file

@ -1,22 +0,0 @@
name: GitHub Actions security analysis with zizmor
on:
pull_request:
paths: ["**/*.yaml?"]
push:
branches: [main, stable]
paths: ["**/*.yaml?"]
permissions: {}
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true
jobs:
zizmor:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
persist-credentials: false
- uses: zizmorcore/zizmor-action@71321a20a9ded102f6e9ce5718a2fcec2c4f70d8 # v0.5.2
with:
advanced-security: false
annotations: true

15
.gitignore vendored
View file

@ -1,8 +1,7 @@
.idea/ .DS_Store
.vscode/ *.pyc
__pycache__/ *.pyo
dist/ env
.coverage* dist
htmlcov/ *.egg-info
.tox/ _mailinglist
docs/_build/

3
.gitmodules vendored Normal file
View file

@ -0,0 +1,3 @@
[submodule "docs/_themes"]
path = docs/_themes
url = git://github.com/mitsuhiko/flask-sphinx-themes.git

23
.pre-commit-config.yaml
View file

@ -1,23 +0,0 @@
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: 5e2fb545eba1ea9dc051f6f962d52fe8f76a9794 # frozen: v0.15.13
hooks:
- id: ruff-check
- id: ruff-format
- repo: https://github.com/astral-sh/uv-pre-commit
rev: fa60a193803535a9e2accdb3ca4b1b584b1150cb # frozen: 0.11.15
hooks:
- id: uv-lock
- repo: https://github.com/codespell-project/codespell
rev: 2ccb47ff45ad361a21071a7eedda4c37e6ae8c5a # frozen: v2.4.2
hooks:
- id: codespell
args: ['--write-changes']
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c # frozen: v6.0.0
hooks:
- id: check-merge-conflict
- id: debug-statements
- id: fix-byte-order-marker
- id: trailing-whitespace
- id: end-of-file-fixer

10
.readthedocs.yaml
View file

@ -1,10 +0,0 @@
version: 2
build:
os: ubuntu-24.04
tools:
python: '3.13'
commands:
- asdf plugin add uv
- asdf install uv latest
- asdf global uv latest
- uv run --group docs sphinx-build -W -b dirhtml docs $READTHEDOCS_OUTPUT/html

14
AUTHORS Normal file
View file

@ -0,0 +1,14 @@
Flask is written and maintained by Armin Ronacher and
various contributors:
Development Lead
````````````````
- Armin Ronacher <armin.ronacher@active-4.com>
Patches and Suggestions
```````````````````````
- Chris Edgemon
- Chris Grindstaff
- Florent Xicluna

61
CHANGES Normal file
View file

@ -0,0 +1,61 @@
Flask Changelog
===============
Here you can see the full list of changes between each Flask release.
Version 0.4
-----------
Release date to be announced, codename to be selected.
Version 0.3.1
-------------
Bugfix release, released May 28th
- fixed a error reporting bug with :meth:`flask.Config.from_envvar`
- removed some unused code from flask
- release does no longer include development leftover files (.git
folder for themes, built documentation in zip and pdf file and
some .pyc files)
Version 0.3
-----------
Released on May 28th, codename Schnaps
- added support for categories for flashed messages.
- the application now configures a :class:`logging.Handler` and will
log request handling exceptions to that logger when not in debug
mode. This makes it possible to receive mails on server errors
for example.
- added support for context binding that does not require the use of
the with statement for playing in the console.
- the request context is now available within the with statement making
it possible to further push the request context or pop it.
- added support for configurations.
Version 0.2
-----------
Released on May 12th, codename Jägermeister
- various bugfixes
- integrated JSON support
- added :func:`~flask.get_template_attribute` helper function.
- :meth:`~flask.Flask.add_url_rule` can now also register a
view function.
- refactored internal request dispatching.
- server listens on 127.0.0.1 by default now to fix issues with chrome.
- added external URL support.
- added support for :func:`~flask.send_file`
- module support and internal request handling refactoring
to better support pluggable applications.
- sessions can be set to be permanent now on a per-session basis.
- better error reporting on missing secret keys.
- added support for Google Appengine.
Version 0.1
-----------
First public preview release.

1665
CHANGES.rst
View file

File diff suppressed because it is too large Load diff

32
LICENSE Normal file
View file

@ -0,0 +1,32 @@
Copyright (c) 2010 by Armin Ronacher and contributors. See AUTHORS
for more details.
Some rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided
with the distribution.
* The names of the contributors may not be used to endorse or
promote products derived from this software without specific
prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

28
LICENSE.txt
View file

@ -1,28 +0,0 @@
Copyright 2010 Pallets
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

10
MANIFEST.in Normal file
View file

@ -0,0 +1,10 @@
include Makefile CHANGES LICENSE AUTHORS
recursive-include tests *
recursive-include examples *
recursive-include docs *
recursive-exclude docs *.pyc
recursive-exclude docs *.pyo
recursive-exclude examples *.pyc
recursive-exclude examples *.pyo
prune docs/_build
prune docs/_themes/.git

22
Makefile Normal file
View file

@ -0,0 +1,22 @@
.PHONY: clean-pyc test upload-docs
all: clean-pyc test
test:
python tests/flask_tests.py
release:
python setup.py release sdist upload
clean-pyc:
find . -name '*.pyc' -exec rm -f {} +
find . -name '*.pyo' -exec rm -f {} +
find . -name '*~' -exec rm -f {} +
upload-docs:
$(MAKE) -C docs html dirhtml latex
$(MAKE) -C docs/_build/latex all-pdf
cd docs/_build/; mv html flask-docs; zip -r flask-docs.zip flask-docs; mv flask-docs html
scp -r docs/_build/dirhtml/* pocoo.org:/var/www/flask.pocoo.org/docs/
scp -r docs/_build/latex/Flask.pdf pocoo.org:/var/www/flask.pocoo.org/docs/flask-docs.pdf
scp -r docs/_build/flask-docs.zip pocoo.org:/var/www/flask.pocoo.org/docs/

36
README Normal file
View file

@ -0,0 +1,36 @@
// Flask //
web development, one drop at a time
~ What is Flask?
Flask is a microframework for Python based on Werkzeug
and Jinja2. It's intended for small scale applications
and was developped with best intentions in mind.
~ Is it ready?
A preview release is out now, and I'm hoping for some
input about what you want from a microframework and
how it should look like. Consider the API to slightly
improve over time.
~ What do I need?
Jinja 2.4 and Werkzeug 0.6.1. `easy_install` will
install them for you if you do `easy_install Flask==dev`.
I encourage you to use a virtualenv. Check the docs for
complete installation and usage instructions.
~ Where are the docs?
Go to http://flask.pocoo.org/ for a prebuilt version of
the current documentation. Otherwise build them yourself
from the sphinx sources in the docs folder.
~ Where can I get help?
Either use the #pocoo IRC channel on irc.freenode.net or
ask on the mailinglist: http://flask.pocoo.org/mailinglist/

53
README.md
View file

@ -1,53 +0,0 @@
<div align="center"><img src="https://raw.githubusercontent.com/pallets/flask/refs/heads/stable/docs/_static/flask-name.svg" alt="" height="150"></div>
# Flask
Flask is a lightweight [WSGI] web application framework. It is designed
to make getting started quick and easy, with the ability to scale up to
complex applications. It began as a simple wrapper around [Werkzeug]
and [Jinja], and has become one of the most popular Python web
application frameworks.
Flask offers suggestions, but doesn't enforce any dependencies or
project layout. It is up to the developer to choose the tools and
libraries they want to use. There are many extensions provided by the
community that make adding new functionality easy.
[WSGI]: https://wsgi.readthedocs.io/
[Werkzeug]: https://werkzeug.palletsprojects.com/
[Jinja]: https://jinja.palletsprojects.com/
## A Simple Example
```python
# save this as app.py
from flask import Flask
app = Flask(__name__)
@app.route("/")
def hello():
return "Hello, World!"
```
```
$ flask run
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
```
## Donate
The Pallets organization develops and supports Flask and the libraries
it uses. In order to grow the community of contributors and users, and
allow the maintainers to devote more time to the projects, [please
donate today].
[please donate today]: https://palletsprojects.com/donate
## Contributing
See our [detailed contributing documentation][contrib] for many ways to
contribute, including reporting issues, requesting features, asking or answering
questions, and making PRs.
[contrib]: https://palletsprojects.com/contributing/

290
artwork/logo-full.svg Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 77 KiB

1
docs/.gitignore vendored Normal file
View file

@ -0,0 +1 @@
_build

124
docs/Makefile
View file

@ -1,20 +1,118 @@
# Minimal makefile for Sphinx documentation # Makefile for Sphinx documentation
# #
# You can set these variables from the command line, and also # You can set these variables from the command line.
# from the environment for the first two. SPHINXOPTS =
SPHINXOPTS ?= SPHINXBUILD = sphinx-build
SPHINXBUILD ?= sphinx-build PAPER =
SOURCEDIR = .
BUILDDIR = _build BUILDDIR = _build
# Put it first so that "make" without argument is like "make help". # Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp epub latex changes linkcheck doctest
help: help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) @echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
.PHONY: help Makefile clean:
-rm -rf $(BUILDDIR)/*
# Catch-all target: route all unknown targets to Sphinx using the new html:
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
%: Makefile @echo
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Flask.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Flask.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) _build/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/Flask"
@echo "# ln -s _build/devhelp $$HOME/.local/share/devhelp/Flask"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
"run these through (pdf)latex."
latexpdf: latex
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
@echo "Running LaTeX files through pdflatex..."
make -C _build/latex all-pdf
@echo "pdflatex finished; the PDF files are in _build/latex."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."

BIN
docs/_static/debugger.png vendored
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 203 KiB

After

Width:  |  Height:  |  Size: 121 KiB

Before After
Before After

15
docs/_static/flask-icon.svg vendored
View file

@ -1,15 +0,0 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="100%" height="100%" viewBox="0 0 500 500" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
<rect id="Icon" x="0" y="0" width="500" height="500" style="fill:none;"/>
<clipPath id="_clip1">
<rect x="0" y="0" width="500" height="500"/>
</clipPath>
<g clip-path="url(#_clip1)">
<g>
<path d="M224.446,59.975c-0.056,-4.151 -0.483,-5.543 -2.7,-6.823c-2.104,-1.393 -5.288,-1.421 -8.329,-0.085l-204.674,87.64c-3.042,1.336 -5.913,4.008 -7.448,6.908c-1.535,2.899 -1.705,5.97 -0.511,8.158l17.084,31.384l0.228,0.369c1.847,2.928 6.026,3.696 10.29,1.82l1.251,-0.54c5.344,22.4 14.1,50.429 25.783,70.413l178.294,-79.794c-2.559,-23.14 -9.552,-89.602 -9.268,-119.479l0,0.029Z" style="fill:#3babc3;fill-rule:nonzero;"/>
<path d="M238.603,205.776l-171.698,76.838c10.091,19.132 22.542,39.428 37.722,58.986c50.429,-25.698 100.887,-51.396 151.316,-77.094c-3.269,-8.471 -6.452,-17.653 -17.34,-58.73Z" style="fill:#3babc3;fill-rule:nonzero;"/>
<path d="M497.601,388.846l-12.139,-18.535c-1.819,-2.018 -4.633,-2.786 -7.106,-1.791l-15.578,5.999c-1.848,-2.047 -4.52,-2.815 -7.135,-1.791c-5.089,1.99 -10.206,4.008 -15.294,5.998c-1.649,0.625 -2.104,1.847 -1.791,3.439l0.995,4.861c-28.711,3.099 -77.236,1.564 -120.701,-32.577c-19.216,-15.066 -37.239,-36.386 -52.277,-66.206l-144.75,73.768c26.466,29.08 59.697,54.864 100.973,70.385c57.422,21.633 130.593,23.679 222.838,-13.475l0.512,2.616c0.455,2.928 3.98,6.026 8.755,4.15l15.323,-5.97c5.258,-1.99 5.287,-6.026 4.519,-8.641l19.729,-7.704c2.217,-0.853 9.096,-6.169 3.183,-14.526l-0.056,-0Z" style="fill:#3babc3;fill-rule:nonzero;"/>
</g>
</g>
</svg>
Side by side

Before

Width:  |  Height:  |  Size: 2 KiB

17
docs/_static/flask-logo.svg vendored
View file

@ -1,17 +0,0 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="100%" height="100%" viewBox="0 0 500 500" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
<rect id="Logo" x="0" y="0" width="500" height="500" style="fill:none;"/>
<g>
<path id="Box" d="M500,50l0,400c0,27.596 -22.404,50 -50,50l-400,0c-27.596,0 -50,-22.404 -50,-50l0,-400c0,-27.596 22.404,-50 50,-50l400,0c27.596,0 50,22.404 50,50Z" style="fill:url(#_Linear1);"/>
<path id="Shadow" d="M500,398.646l0,51.354c0,27.596 -22.404,50 -50,50l-94.111,0l-170.452,-170.451c13.541,12.279 29.511,22.845 48.242,29.888c34.453,12.98 78.356,14.208 133.703,-8.084l0.307,1.569c0.273,1.757 2.388,3.616 5.253,2.49l9.193,-3.582c3.156,-1.194 3.173,-3.616 2.712,-5.185l11.837,-4.622c1.331,-0.512 5.458,-3.701 1.91,-8.716l-0.034,0l-7.283,-11.12c-1.091,-1.211 -2.78,-1.672 -4.264,-1.075l-9.346,3.599c-1.109,-1.228 -2.712,-1.688 -4.281,-1.074c-3.054,1.194 -6.124,2.404 -9.177,3.598c-0.989,0.376 -1.262,1.109 -1.074,2.064l0.597,2.917c-17.227,1.859 -46.342,0.938 -72.421,-19.547c-11.53,-9.039 -22.343,-21.831 -31.366,-39.723l-83.923,42.769l-13.246,-10.755c30.258,-15.419 60.532,-30.837 90.79,-46.256c-1.961,-5.083 -3.872,-10.592 -10.404,-35.238l-98.082,43.893l-11.828,-11.828l106.976,-47.876c-1.534,-13.88 -5.728,-53.736 -5.56,-71.67l-0,-0.017c-0.027,-1.894 -0.184,-2.827 -0.85,-3.504l266.182,266.182Zm-388.562,-185.436c1.272,1.164 3.414,1.356 5.594,0.397l0.75,-0.324c0.645,2.703 1.373,5.543 2.181,8.452l-8.525,-8.525Z" style="fill:#3b808b;"/>
<g id="Icon">
<path d="M234.668,135.985c-0.034,-2.49 -0.29,-3.326 -1.62,-4.094c-1.263,-0.835 -3.173,-0.852 -4.998,-0.051l-122.804,52.584c-1.825,0.802 -3.548,2.405 -4.469,4.145c-0.921,1.74 -1.023,3.582 -0.307,4.895l10.251,18.83l0.136,0.222c1.109,1.757 3.616,2.217 6.175,1.091l0.75,-0.324c3.207,13.441 8.46,30.258 15.47,42.248l106.976,-47.876c-1.535,-13.884 -5.731,-53.761 -5.56,-71.687l-0,0.017Z" style="fill:#fff;fill-rule:nonzero;"/>
<path d="M243.162,223.466l-103.019,46.103c6.055,11.478 13.525,23.656 22.633,35.391c30.258,-15.419 60.532,-30.837 90.79,-46.256c-1.961,-5.083 -3.872,-10.592 -10.404,-35.238Z" style="fill:#fff;fill-rule:nonzero;"/>
<path d="M398.56,333.307l-7.283,-11.12c-1.091,-1.211 -2.78,-1.672 -4.264,-1.075l-9.346,3.599c-1.109,-1.228 -2.712,-1.688 -4.281,-1.074c-3.054,1.194 -6.124,2.404 -9.177,3.598c-0.989,0.376 -1.262,1.109 -1.074,2.064l0.597,2.917c-17.227,1.859 -46.342,0.938 -72.421,-19.547c-11.53,-9.039 -22.343,-21.831 -31.366,-39.723l-86.85,44.26c15.879,17.449 35.818,32.919 60.584,42.231c34.453,12.98 78.356,14.208 133.703,-8.084l0.307,1.569c0.273,1.757 2.388,3.616 5.253,2.49l9.193,-3.582c3.156,-1.194 3.173,-3.616 2.712,-5.185l11.837,-4.622c1.331,-0.512 5.458,-3.701 1.91,-8.716l-0.034,0Z" style="fill:#fff;fill-rule:nonzero;"/>
</g>
</g>
<defs>
<linearGradient id="_Linear1" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(3.06162e-14,500,-500,3.06162e-14,267.59,0)"><stop offset="0" style="stop-color:#bdddeb;stop-opacity:1"/><stop offset="1" style="stop-color:#53a9d1;stop-opacity:1"/></linearGradient>
</defs>
</svg>
Side by side

Before

Width:  |  Height:  |  Size: 3.4 KiB

23
docs/_static/flask-name.svg vendored
View file

@ -1,23 +0,0 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="100%" height="100%" viewBox="0 0 706 300" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
<g>
<path id="Name" d="M420.35,117.6l-37.65,-0c-4.4,-0 -7.475,0.85 -9.225,2.55c-1.75,1.7 -2.625,4.65 -2.625,8.85l-0,14.85l39.15,-0l-1.5,18.6l-37.65,-0l-0,43.35l-20.85,-0l-0,-85.05c-0,-7.9 1.725,-13.5 5.175,-16.8c3.45,-3.3 9.375,-4.95 17.775,-4.95l47.4,-0l0,18.6Z" style="fill-rule:nonzero;"/>
<path d="M455.75,205.8l-19.5,0.15l-0,-112.95l19.5,-0l-0,112.8Z" style="fill-rule:nonzero;"/>
<path d="M535.7,205.8l-13.05,-0l-6,-10.35l-20.85,11.25c-11.6,-0 -19.4,-4.2 -23.4,-12.6c-2,-4.1 -3.375,-8.525 -4.125,-13.275c-0.75,-4.75 -1.125,-9.7 -1.125,-14.85c-0,-5.15 0.05,-8.95 0.15,-11.4c0.1,-2.45 0.35,-5.3 0.75,-8.55c0.4,-3.25 0.975,-5.975 1.725,-8.175c0.75,-2.2 1.825,-4.475 3.225,-6.825c1.4,-2.35 3.1,-4.225 5.1,-5.625c4.5,-3.1 10.35,-4.65 17.55,-4.65l20.55,-0l19.5,-1.2l-0,86.25Zm-19.5,-27.3l-0,-40.2l-14.85,-0c-5.5,-0 -9.325,2.1 -11.475,6.3c-2.15,4.2 -3.225,10.475 -3.225,18.825c-0,8.35 1.025,14.225 3.075,17.625c2.05,3.4 5.925,5.1 11.625,5.1l14.85,-7.65Z" style="fill-rule:nonzero;"/>
<path d="M615.65,182.1l0,2.25c-0.6,7.5 -3.775,13.15 -9.525,16.95c-5.75,3.8 -12.925,5.7 -21.525,5.7c-12.7,-0 -21.6,-2.3 -26.7,-6.9c-4.7,-4.2 -7.05,-10.4 -7.05,-18.6l0,-1.8l17.7,0c0,4.6 1.2,7.75 3.6,9.45c2.4,1.7 6.55,2.55 12.45,2.55c8,0 12,-2.9 12,-8.7c0,-4.8 -1.4,-8 -4.2,-9.6c-1.3,-0.8 -2.95,-1.4 -4.95,-1.8l-15.15,-2.55c-13.2,-2.1 -19.8,-10.35 -19.8,-24.75c0,-8 2.925,-14.225 8.775,-18.675c5.85,-4.45 13.275,-6.675 22.275,-6.675c20.5,0 30.75,8.85 30.75,26.55l0,1.95l-16.95,0c-0.2,-4.7 -1.45,-7.9 -3.75,-9.6c-2.3,-1.7 -5.525,-2.55 -9.675,-2.55c-4.15,0 -7.275,0.825 -9.375,2.475c-2.1,1.65 -3.15,3.475 -3.15,5.475c0,5.7 2.3,8.95 6.9,9.75l18.15,3.3c12.8,2.4 19.2,11 19.2,25.8Z" style="fill-rule:nonzero;"/>
<path d="M705.65,205.8l-23.4,-0l-22.5,-30.3l-8.55,12.15l0,18.15l-19.5,-0l0,-112.8l19.5,-0l0,71.25l27.3,-40.65l22.05,-0l-28.05,38.4l33.15,43.8Z" style="fill-rule:nonzero;"/>
<g id="Logo">
<path id="Box" d="M300,30l0,240c0,16.557 -13.443,30 -30,30l-240,-0c-16.557,-0 -30,-13.443 -30,-30l0,-240c0,-16.557 13.443,-30 30,-30l240,0c16.557,0 30,13.443 30,30Z" style="fill:url(#_Linear1);"/>
<path id="Shadow" d="M300,239.188l0,30.812c0,16.557 -13.443,30 -30,30l-56.467,-0l-102.271,-102.271c8.125,7.368 17.707,13.707 28.945,17.933c20.672,7.788 47.014,8.525 80.222,-4.85l0.184,0.941c0.164,1.054 1.433,2.17 3.152,1.494l5.516,-2.149c1.893,-0.716 1.904,-2.169 1.627,-3.111l7.103,-2.773c0.798,-0.307 3.274,-2.221 1.146,-5.23l-0.021,0l-4.37,-6.672c-0.655,-0.727 -1.668,-1.003 -2.558,-0.645l-5.608,2.16c-0.665,-0.737 -1.627,-1.013 -2.569,-0.645c-1.832,0.716 -3.674,1.443 -5.505,2.159c-0.594,0.225 -0.758,0.665 -0.645,1.239l0.358,1.749c-10.336,1.116 -27.805,0.563 -43.452,-11.727c-6.918,-5.424 -13.406,-13.099 -18.82,-23.835l-50.354,25.662l-7.947,-6.453c18.154,-9.251 36.319,-18.502 54.474,-27.754c-1.177,-3.049 -2.323,-6.355 -6.243,-21.143l-58.849,26.336l-7.097,-7.096l64.186,-28.726c-0.921,-8.328 -3.437,-32.242 -3.336,-43.002l-0,-0.01c-0.016,-1.137 -0.111,-1.697 -0.51,-2.103l159.709,159.71Zm-233.137,-111.262c0.763,0.699 2.048,0.814 3.356,0.238l0.45,-0.194c0.387,1.622 0.824,3.325 1.309,5.071l-5.115,-5.115Z" style="fill:#3b808b;"/>
<g id="Icon">
<path d="M140.801,81.591c-0.021,-1.494 -0.174,-1.996 -0.972,-2.456c-0.758,-0.502 -1.904,-0.512 -2.999,-0.031l-73.683,31.551c-1.095,0.481 -2.128,1.443 -2.681,2.486c-0.552,1.044 -0.614,2.149 -0.184,2.937l6.151,11.298l0.081,0.133c0.666,1.055 2.17,1.331 3.705,0.655l0.45,-0.194c1.924,8.064 5.076,18.155 9.282,25.349l64.186,-28.726c-0.921,-8.33 -3.439,-32.257 -3.336,-43.012l-0,0.01Z" style="fill:#fff;fill-rule:nonzero;"/>
<path d="M145.897,134.079l-61.811,27.662c3.633,6.887 8.115,14.194 13.58,21.235c18.154,-9.251 36.319,-18.502 54.474,-27.754c-1.177,-3.049 -2.323,-6.355 -6.243,-21.143Z" style="fill:#fff;fill-rule:nonzero;"/>
<path d="M239.136,199.984l-4.37,-6.672c-0.655,-0.727 -1.668,-1.003 -2.558,-0.645l-5.608,2.16c-0.665,-0.737 -1.627,-1.013 -2.569,-0.645c-1.832,0.716 -3.674,1.443 -5.505,2.159c-0.594,0.225 -0.758,0.665 -0.645,1.239l0.358,1.749c-10.336,1.116 -27.805,0.563 -43.452,-11.727c-6.918,-5.424 -13.406,-13.099 -18.82,-23.835l-52.11,26.557c9.528,10.469 21.491,19.751 36.35,25.338c20.672,7.788 47.014,8.525 80.222,-4.85l0.184,0.941c0.164,1.054 1.433,2.17 3.152,1.494l5.516,-2.149c1.893,-0.716 1.904,-2.169 1.627,-3.111l7.103,-2.773c0.798,-0.307 3.274,-2.221 1.146,-5.23l-0.021,0Z" style="fill:#fff;fill-rule:nonzero;"/>
</g>
</g>
</g>
<defs>
<linearGradient id="_Linear1" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(1.83697e-14,300,-300,1.83697e-14,160.554,0)"><stop offset="0" style="stop-color:#bdddeb;stop-opacity:1"/><stop offset="1" style="stop-color:#53a9d1;stop-opacity:1"/></linearGradient>
</defs>
</svg>
Side by side

Before

Width:  |  Height:  |  Size: 5.2 KiB

BIN
docs/_static/flask.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 9.7 KiB

BIN
docs/_static/flaskr.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 52 KiB

BIN
docs/_static/logo-full.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 20 KiB

BIN
docs/_static/pycharm-run-config.png vendored
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 97 KiB

BIN
docs/_static/touch-icon.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 3.5 KiB

21
docs/_templates/sidebarintro.html vendored Normal file
View file

@ -0,0 +1,21 @@
<h3>About Flask</h3>
<p>
Flask is a micro webdevelopment framework for Python. You are currently
looking at the documentation of the development version. Things are
not stable yet, but if you have some feedback,
<a href="mailto:armin.ronacher@active-4.com">let me know</a>.
</p>
<h3>Other Formats</h3>
<p>
You can download the documentation in other formats as well:
</p>
<ul>
<li><a href="http://flask.pocoo.org/docs/flask-docs.pdf">as PDF</a>
<li><a href="http://flask.pocoo.org/docs/flask-docs.zip">as zipped HTML</a>
</ul>
<h3>Useful Links</h3>
<ul>
<li><a href="http://flask.pocoo.org/">The Flask Website</a></li>
<li><a href="http://pypi.python.org/pypi/Flask">Flask @ PyPI</a></li>
<li><a href="http://github.com/mitsuhiko/flask">Flask @ github</a></li>
</ul>

3
docs/_templates/sidebarlogo.html vendored Normal file
View file

@ -0,0 +1,3 @@
<p class="logo"><a href="{{ pathto(master_doc) }}">
<img class="logo" src="{{ pathto('_static/flask.png', 1) }}" alt="Logo"/>
</a></p>

1
docs/_themes Submodule

@ -0,0 +1 @@
Subproject commit 0d8f3d85558168647632c768bdea7d58cf6f8e42

778
docs/api.rst
View file

@ -1,9 +1,11 @@
.. _api:
API API
=== ===
.. module:: flask .. module:: flask
This part of the documentation covers all the interfaces of Flask. For This part of the documentation covers all the interfaces of Flask. For
parts where Flask depends on external libraries, we document the most parts where Flask depends on external libraries, we document the most
important right here and provide links to the canonical documentation. important right here and provide links to the canonical documentation.
@ -16,10 +18,10 @@ Application Object
:inherited-members: :inherited-members:
Blueprint Objects Module Objects
----------------- --------------
.. autoclass:: Blueprint .. autoclass:: Module
:members: :members:
:inherited-members: :inherited-members:
@ -27,149 +29,182 @@ Incoming Request Data
--------------------- ---------------------
.. autoclass:: Request .. autoclass:: Request
:members:
:inherited-members:
:exclude-members: json_module
.. data:: request .. class:: request
A proxy to the request data for the current request, an instance of To access incoming request data, you can use the global `request`
:class:`.Request`. object. Flask parses incoming request data for you and gives you
access to it through that global object. Internally Flask makes
sure that you always get the correct data for the active thread if you
are in a multithreaded environment.
This is only available when a :doc:`request context </appcontext>` is The request object is an instance of a :class:`~werkzeug.Request`
active. subclass and provides all of the attributes Werkzeug defines. This
just shows a quick overview of the most important ones.
This is a proxy. See :ref:`context-visibility` for more information. .. attribute:: form
A :class:`~werkzeug.MultiDict` with the parsed form data from `POST`
or `PUT` requests. Please keep in mind that file uploads will not
end up here, but instead in the :attr:`files` attribute.
.. attribute:: args
A :class:`~werkzeug.MultiDict` with the parsed contents of the query
string. (The part in the URL after the question mark).
.. attribute:: values
A :class:`~werkzeug.CombinedMultiDict` with the contents of both
:attr:`form` and :attr:`args`.
.. attribute:: cookies
A :class:`dict` with the contents of all cookies transmitted with
the request.
.. attribute:: stream
If the incoming form data was not encoded with a known mimetype
the data is stored unmodified in this stream for consumption. Most
of the time it is a better idea to use :attr:`data` which will give
you that data as a string. The stream only returns the data once.
.. attribute:: data
Contains the incoming request data as string in case it came with
a mimetype Flask does not handle.
.. attribute:: files
A :class:`~werkzeug.MultiDict` with files uploaded as part of a
`POST` or `PUT` request. Each file is stored as
:class:`~werkzeug.FileStorage` object. It basically behaves like a
standard file object you know from Python, with the difference that
it also has a :meth:`~werkzeug.FileStorage.save` function that can
store the file on the filesystem.
.. attribute:: environ
The underlying WSGI environment.
.. attribute:: method
The current request method (``POST``, ``GET`` etc.)
.. attribute:: path
.. attribute:: script_root
.. attribute:: url
.. attribute:: base_url
.. attribute:: url_root
Provides different ways to look at the current URL. Imagine your
application is listening on the following URL::
http://www.example.com/myapplication
And a user requests the following URL::
http://www.example.com/myapplication/page.html?x=y
In this case the values of the above mentioned attributes would be
the following:
============= ======================================================
`path` ``/page.html``
`script_root` ``/myapplication``
`base_url` ``http://www.example.com/myapplication/page.html``
`url` ``http://www.example.com/myapplication/page.html?x=y``
`url_root` ``http://www.example.com/myapplication/``
============= ======================================================
.. attribute:: is_xhr
`True` if the request was triggered via a JavaScript
`XMLHttpRequest`. This only works with libraries that support the
``X-Requested-With`` header and set it to `XMLHttpRequest`.
Libraries that do that are prototype, jQuery and Mochikit and
probably some more.
.. attribute:: json
Contains the parsed body of the JSON request if the mimetype of
the incoming data was `application/json`. This requires Python 2.6
or an installed version of simplejson.
Response Objects Response Objects
---------------- ----------------
.. autoclass:: flask.Response .. autoclass:: flask.Response
:members: :members: set_cookie, data, mimetype
:inherited-members:
:exclude-members: json_module .. attribute:: headers
A :class:`Headers` object representing the response headers.
.. attribute:: status_code
The response status as integer.
Sessions Sessions
-------- --------
If you have set :attr:`Flask.secret_key` (or configured it from If you have the :attr:`Flask.secret_key` set you can use sessions in Flask
:data:`SECRET_KEY`) you can use sessions in Flask applications. A session makes applications. A session basically makes it possible to remember
it possible to remember information from one request to another. The way Flask information from one request to another. The way Flask does this is by
does this is by using a signed cookie. The user can look at the session using a signed cookie. So the user can look at the session contents, but
contents, but can't modify it unless they know the secret key, so make sure to not modify it unless he knows the secret key, so make sure to set that to
set that to something complex and unguessable. something complex and unguessable.
To access the current session you can use the :data:`.session` proxy. To access the current session you can use the :class:`session` object:
.. data:: session .. class:: session
A proxy to the session data for the current request, an instance of The session object works pretty much like an ordinary dict, with the
:class:`.SessionMixin`. difference that it keeps track on modifications.
This is only available when a :doc:`request context </appcontext>` is The following attributes are interesting:
active.
This is a proxy. See :ref:`context-visibility` for more information. .. attribute:: new
The session object works like a dict but tracks assignment and access to its `True` if the session is new, `False` otherwise.
keys. It cannot track modifications to mutable values, you need to set
:attr:`~.SessionMixin.modified` manually when modifying a list, dict, etc.
.. code-block:: python .. attribute:: modified
# appending to a list is not detected `True` if the session object detected a modification. Be advised
session["numbers"].append(42) that modifications on mutable structures are not picked up
automatically, in that situation you have to explicitly set the
attribute to `True` yourself. Here an example::
# this change is not picked up because a mutable object (here
# a list) is changed.
session['objects'].append(42)
# so mark it as modified yourself # so mark it as modified yourself
session.modified = True session.modified = True
The session is persisted across requests using a cookie. By default the .. attribute:: permanent
users's browser will clear the cookie when it is closed. Set
:attr:`~.SessionMixin.permanent` to ``True`` to persist the cookie for
:data:`PERMANENT_SESSION_LIFETIME`.
If set to `True` the session life for
Session Interface :attr:`~flask.Flask.permanent_session_lifetime` seconds. The
----------------- default is 31 days. If set to `False` (which is the default) the
session will be deleted when the user closes the browser.
.. versionadded:: 0.8
The session interface provides a simple way to replace the session
implementation that Flask is using.
.. currentmodule:: flask.sessions
.. autoclass:: SessionInterface
:members:
.. autoclass:: SecureCookieSessionInterface
:members:
.. autoclass:: SecureCookieSession
:members:
.. autoclass:: NullSession
:members:
.. autoclass:: SessionMixin
:members:
.. admonition:: Notice
The :data:`PERMANENT_SESSION_LIFETIME` config can be an integer or ``timedelta``.
The :attr:`~flask.Flask.permanent_session_lifetime` attribute is always a
``timedelta``.
Test Client
-----------
.. currentmodule:: flask.testing
.. autoclass:: FlaskClient
:members:
Test CLI Runner
---------------
.. currentmodule:: flask.testing
.. autoclass:: FlaskCliRunner
:members:
Application Globals Application Globals
------------------- -------------------
.. currentmodule:: flask
To share data that is valid for one request only from one function to To share data that is valid for one request only from one function to
another, a global variable is not good enough because it would break in another, a global variable is not good enough because it would break in
threaded environments. Flask provides you with a special object that threaded environments. Flask provides you with a special object that
ensures it is only valid for the active request and that will return ensures it is only valid for the active request and that will return
different values for each request. In a nutshell: it does the right different values for each request. In a nutshell: it does the right
thing, like it does for :data:`.request` and :data:`.session`. thing, like it does for :class:`request` and :class:`session`.
.. data:: g .. data:: g
A proxy to a namespace object used to store data during a single request or Just store on this whatever you want. For example a database
app context. An instance of :attr:`.Flask.app_ctx_globals_class`, which connection or the user that is currently logged in.
defaults to :class:`._AppCtxGlobals`.
This is a good place to store resources during a request. For example, a
:meth:`~.Flask.before_request` function could load a user object from a
session id, then set ``g.user`` to be used in the view function.
This is only available when an :doc:`app context </appcontext>` is active.
This is a proxy. See :ref:`context-visibility` for more information.
.. versionchanged:: 0.10
Bound to the application context instead of the request context.
.. autoclass:: flask.ctx._AppCtxGlobals
:members:
Useful Functions and Classes Useful Functions and Classes
@ -177,37 +212,28 @@ Useful Functions and Classes
.. data:: current_app .. data:: current_app
A proxy to the :class:`.Flask` application handling the current request or Points to the application handling the request. This is useful for
other activity. extensions that want to support multiple applications running side
by side.
This is useful to access the application without needing to import it, or if
it can't be imported, such as when using the application factory pattern or
in blueprints and extensions.
This is only available when an :doc:`app context </appcontext>` is active.
This is a proxy. See :ref:`context-visibility` for more information.
.. autofunction:: has_request_context
.. autofunction:: copy_current_request_context
.. autofunction:: has_app_context
.. autofunction:: url_for .. autofunction:: url_for
.. autofunction:: abort .. function:: abort(code)
Raises an :exc:`~werkzeug.exception.HTTPException` for the given
status code. For example to abort request handling with a page not
found exception, you would call ``abort(404)``.
:param code: the HTTP error code.
.. autofunction:: redirect .. autofunction:: redirect
.. autofunction:: make_response
.. autofunction:: after_this_request
.. autofunction:: send_file .. autofunction:: send_file
.. autofunction:: send_from_directory .. autofunction:: escape
.. autoclass:: Markup
:members: escape, unescape, striptags
Message Flashing Message Flashing
---------------- ----------------
@ -216,63 +242,47 @@ Message Flashing
.. autofunction:: get_flashed_messages .. autofunction:: get_flashed_messages
Returning JSON
JSON Support --------------
------------
.. module:: flask.json
Flask uses Python's built-in :mod:`json` module for handling JSON by
default. The JSON implementation can be changed by assigning a different
provider to :attr:`flask.Flask.json_provider_class` or
:attr:`flask.Flask.json`. The functions provided by ``flask.json`` will
use methods on ``app.json`` if an app context is active.
Jinja's ``|tojson`` filter is configured to use the app's JSON provider.
The filter marks the output with ``|safe``. Use it to render data inside
HTML ``<script>`` tags.
.. sourcecode:: html+jinja
<script>
const names = {{ names|tojson }};
renderChart(names, {{ axis_data|tojson }});
</script>
.. autofunction:: jsonify .. autofunction:: jsonify
.. autofunction:: dumps .. data:: json
.. autofunction:: dump If JSON support is picked up, this will be the module that Flask is
using to parse and serialize JSON. So instead of doing this yourself::
.. autofunction:: loads try:
import simplejson as json
except ImportError:
import json
.. autofunction:: load You can instead just do this::
.. autoclass:: flask.json.provider.JSONProvider from flask import json
:members:
:member-order: bysource
.. autoclass:: flask.json.provider.DefaultJSONProvider For usage examples, read the :mod:`json` documentation.
:members:
:member-order: bysource
.. automodule:: flask.json.tag The :func:`~json.dumps` function of this json module is also available
as filter called ``|tojson`` in Jinja2. Note that inside `script`
tags no escaping must take place, so make sure to disable escaping
with ``|safe`` if you intend to use it inside `script` tags:
.. sourcecode:: html+jinja
<script type=text/javascript>
doSomethingWith({{ user.username|tojson|safe }});
</script>
Note that the ``|tojson`` filter escapes forward slashes properly.
Template Rendering Template Rendering
------------------ ------------------
.. currentmodule:: flask
.. autofunction:: render_template .. autofunction:: render_template
.. autofunction:: render_template_string .. autofunction:: render_template_string
.. autofunction:: stream_template
.. autofunction:: stream_template_string
.. autofunction:: get_template_attribute .. autofunction:: get_template_attribute
Configuration Configuration
@ -280,429 +290,3 @@ Configuration
.. autoclass:: Config .. autoclass:: Config
:members: :members:
Stream Helpers
--------------
.. autofunction:: stream_with_context
Useful Internals
----------------
.. autoclass:: flask.ctx.AppContext
:members:
.. data:: flask.globals.app_ctx
A proxy to the active :class:`.AppContext`.
This is an internal object that is essential to how Flask handles requests.
Accessing this should not be needed in most cases. Most likely you want
:data:`.current_app`, :data:`.g`, :data:`.request`, and :data:`.session` instead.
This is only available when a :doc:`request context </appcontext>` is
active.
This is a proxy. See :ref:`context-visibility` for more information.
.. class:: flask.ctx.RequestContext
.. deprecated:: 3.2
Merged with :class:`AppContext`. This alias will be removed in Flask 4.0.
.. data:: flask.globals.request_ctx
.. deprecated:: 3.2
Merged with :data:`.app_ctx`. This alias will be removed in Flask 4.0.
.. autoclass:: flask.blueprints.BlueprintSetupState
:members:
.. _core-signals-list:
Signals
-------
Signals are provided by the `Blinker`_ library. See :doc:`signals` for an introduction.
.. _blinker: https://blinker.readthedocs.io/
.. data:: template_rendered
This signal is sent when a template was successfully rendered. The
signal is invoked with the instance of the template as `template`
and the context as dictionary (named `context`).
Example subscriber::
def log_template_renders(sender, template, context, **extra):
sender.logger.debug('Rendering template "%s" with context %s',
template.name or 'string template',
context)
from flask import template_rendered
template_rendered.connect(log_template_renders, app)
.. data:: flask.before_render_template
:noindex:
This signal is sent before template rendering process. The
signal is invoked with the instance of the template as `template`
and the context as dictionary (named `context`).
Example subscriber::
def log_template_renders(sender, template, context, **extra):
sender.logger.debug('Rendering template "%s" with context %s',
template.name or 'string template',
context)
from flask import before_render_template
before_render_template.connect(log_template_renders, app)
.. data:: request_started
This signal is sent when the request context is set up, before
any request processing happens. Because the request context is already
bound, the subscriber can access the request with the standard global
proxies such as :class:`~flask.request`.
Example subscriber::
def log_request(sender, **extra):
sender.logger.debug('Request context is set up')
from flask import request_started
request_started.connect(log_request, app)
.. data:: request_finished
This signal is sent right before the response is sent to the client.
It is passed the response to be sent named `response`.
Example subscriber::
def log_response(sender, response, **extra):
sender.logger.debug('Request context is about to close down. '
'Response: %s', response)
from flask import request_finished
request_finished.connect(log_response, app)
.. data:: got_request_exception
This signal is sent when an unhandled exception happens during
request processing, including when debugging. The exception is
passed to the subscriber as ``exception``.
This signal is not sent for
:exc:`~werkzeug.exceptions.HTTPException`, or other exceptions that
have error handlers registered, unless the exception was raised from
an error handler.
This example shows how to do some extra logging if a theoretical
``SecurityException`` was raised:
.. code-block:: python
from flask import got_request_exception
def log_security_exception(sender, exception, **extra):
if not isinstance(exception, SecurityException):
return
security_logger.exception(
f"SecurityException at {request.url!r}",
exc_info=exception,
)
got_request_exception.connect(log_security_exception, app)
.. data:: request_tearing_down
This signal is sent when the request is tearing down. This is always
called, even if an exception is caused. Currently functions listening
to this signal are called after the regular teardown handlers, but this
is not something you can rely on.
Example subscriber::
def close_db_connection(sender, **extra):
session.close()
from flask import request_tearing_down
request_tearing_down.connect(close_db_connection, app)
As of Flask 0.9, this will also be passed an `exc` keyword argument
that has a reference to the exception that caused the teardown if
there was one.
.. data:: appcontext_tearing_down
This signal is sent when the app context is tearing down. This is always
called, even if an exception is caused. Currently functions listening
to this signal are called after the regular teardown handlers, but this
is not something you can rely on.
Example subscriber::
def close_db_connection(sender, **extra):
session.close()
from flask import appcontext_tearing_down
appcontext_tearing_down.connect(close_db_connection, app)
This will also be passed an `exc` keyword argument that has a reference
to the exception that caused the teardown if there was one.
.. data:: appcontext_pushed
This signal is sent when an application context is pushed. The sender
is the application. This is usually useful for unittests in order to
temporarily hook in information. For instance it can be used to
set a resource early onto the `g` object.
Example usage::
from contextlib import contextmanager
from flask import appcontext_pushed
@contextmanager
def user_set(app, user):
def handler(sender, **kwargs):
g.user = user
with appcontext_pushed.connected_to(handler, app):
yield
And in the testcode::
def test_user_me(self):
with user_set(app, 'john'):
c = app.test_client()
resp = c.get('/users/me')
assert resp.data == 'username=john'
.. versionadded:: 0.10
.. data:: appcontext_popped
This signal is sent when an application context is popped. The sender
is the application. This usually falls in line with the
:data:`appcontext_tearing_down` signal.
.. versionadded:: 0.10
.. data:: message_flashed
This signal is sent when the application is flashing a message. The
messages is sent as `message` keyword argument and the category as
`category`.
Example subscriber::
recorded = []
def record(sender, message, category, **extra):
recorded.append((message, category))
from flask import message_flashed
message_flashed.connect(record, app)
.. versionadded:: 0.10
Class-Based Views
-----------------
.. versionadded:: 0.7
.. currentmodule:: None
.. autoclass:: flask.views.View
:members:
.. autoclass:: flask.views.MethodView
:members:
.. _url-route-registrations:
URL Route Registrations
-----------------------
Generally there are three ways to define rules for the routing system:
1. You can use the :meth:`flask.Flask.route` decorator.
2. You can use the :meth:`flask.Flask.add_url_rule` function.
3. You can directly access the underlying Werkzeug routing system
which is exposed as :attr:`flask.Flask.url_map`.
Variable parts in the route can be specified with angular brackets
(``/user/<username>``). By default a variable part in the URL accepts any
string without a slash however a different converter can be specified as
well by using ``<converter:name>``.
Variable parts are passed to the view function as keyword arguments.
The following converters are available:
=========== ===============================================
`string` accepts any text without a slash (the default)
`int` accepts integers
`float` like `int` but for floating point values
`path` like the default but also accepts slashes
`any` matches one of the items provided
`uuid` accepts UUID strings
=========== ===============================================
Custom converters can be defined using :attr:`flask.Flask.url_map`.
Here are some examples::
@app.route('/')
def index():
pass
@app.route('/<username>')
def show_user(username):
pass
@app.route('/post/<int:post_id>')
def show_post(post_id):
pass
An important detail to keep in mind is how Flask deals with trailing
slashes. The idea is to keep each URL unique so the following rules
apply:
1. If a rule ends with a slash and is requested without a slash by the
user, the user is automatically redirected to the same page with a
trailing slash attached.
2. If a rule does not end with a trailing slash and the user requests the
page with a trailing slash, a 404 not found is raised.
This is consistent with how web servers deal with static files. This
also makes it possible to use relative link targets safely.
You can also define multiple rules for the same function. They have to be
unique however. Defaults can also be specified. Here for example is a
definition for a URL that accepts an optional page::
@app.route('/users/', defaults={'page': 1})
@app.route('/users/page/<int:page>')
def show_users(page):
pass
This specifies that ``/users/`` will be the URL for page one and
``/users/page/N`` will be the URL for page ``N``.
If a URL contains a default value, it will be redirected to its simpler
form with a 308 redirect. In the above example, ``/users/page/1`` will
be redirected to ``/users/``. If your route handles ``GET`` and ``POST``
requests, make sure the default route only handles ``GET``, as redirects
can't preserve form data. ::
@app.route('/region/', defaults={'id': 1})
@app.route('/region/<int:id>', methods=['GET', 'POST'])
def region(id):
pass
Here are the parameters that :meth:`~flask.Flask.route` and
:meth:`~flask.Flask.add_url_rule` accept. The only difference is that
with the route parameter the view function is defined with the decorator
instead of the `view_func` parameter.
=============== ==========================================================
`rule` the URL rule as string
`endpoint` the endpoint for the registered URL rule. Flask itself
assumes that the name of the view function is the name
of the endpoint if not explicitly stated.
`view_func` the function to call when serving a request to the
provided endpoint. If this is not provided one can
specify the function later by storing it in the
:attr:`~flask.Flask.view_functions` dictionary with the
endpoint as key.
`defaults` A dictionary with defaults for this rule. See the
example above for how defaults work.
`subdomain` specifies the rule for the subdomain in case subdomain
matching is in use. If not specified the default
subdomain is assumed.
`**options` the options to be forwarded to the underlying
:class:`~werkzeug.routing.Rule` object. A change to
Werkzeug is handling of method options. methods is a list
of methods this rule should be limited to (``GET``, ``POST``
etc.). By default a rule just listens for ``GET`` (and
implicitly ``HEAD``). Starting with Flask 0.6, ``OPTIONS`` is
implicitly added and handled by the standard request
handling. They have to be specified as keyword arguments.
=============== ==========================================================
View Function Options
---------------------
For internal usage the view functions can have some attributes attached to
customize behavior the view function would normally not have control over.
The following attributes can be provided optionally to either override
some defaults to :meth:`~flask.Flask.add_url_rule` or general behavior:
- `__name__`: The name of a function is by default used as endpoint. If
endpoint is provided explicitly this value is used. Additionally this
will be prefixed with the name of the blueprint by default which
cannot be customized from the function itself.
- `methods`: If methods are not provided when the URL rule is added,
Flask will look on the view function object itself if a `methods`
attribute exists. If it does, it will pull the information for the
methods from there.
- `provide_automatic_options`: if this attribute is set Flask will
either force enable or disable the automatic implementation of the
HTTP ``OPTIONS`` response. This can be useful when working with
decorators that want to customize the ``OPTIONS`` response on a per-view
basis.
- `required_methods`: if this attribute is set, Flask will always add
these methods when registering a URL rule even if the methods were
explicitly overridden in the ``route()`` call.
Full example::
def index():
if request.method == 'OPTIONS':
# custom options handling here
...
return 'Hello World!'
index.provide_automatic_options = False
index.methods = ['GET', 'OPTIONS']
app.add_url_rule('/', index)
.. versionadded:: 0.8
The `provide_automatic_options` functionality was added.
Command Line Interface
----------------------
.. currentmodule:: flask.cli
.. autoclass:: FlaskGroup
:members:
.. autoclass:: AppGroup
:members:
.. autoclass:: ScriptInfo
:members:
.. autofunction:: load_dotenv
.. autofunction:: with_appcontext
.. autofunction:: pass_script_info
Marks a function so that an instance of :class:`ScriptInfo` is passed
as first argument to the click callback.
.. autodata:: run_command
.. autodata:: shell_command

187
docs/appcontext.rst
View file

@ -1,187 +0,0 @@
The App and Request Context
===========================
The context keeps track of data and objects during a request, CLI command, or
other activity. Rather than passing this data around to every function, the
:data:`.current_app`, :data:`.g`, :data:`.request`, and :data:`.session` proxies
are accessed instead.
When handling a request, the context is referred to as the "request context"
because it contains request data in addition to application data. Otherwise,
such as during a CLI command, it is referred to as the "app context". During an
app context, :data:`.current_app` and :data:`.g` are available, while during a
request context :data:`.request` and :data:`.session` are also available.
Purpose of the Context
----------------------
The context and proxies help solve two development issues: circular imports, and
passing around global data during a request.
The :class:`.Flask` application object has attributes, such as
:attr:`~.Flask.config`, that are useful to access within views and other
functions. However, importing the ``app`` instance within the modules in your
project is prone to circular import issues. When using the
:doc:`app factory pattern </patterns/appfactories>` or writing reusable
:doc:`blueprints </blueprints>` or :doc:`extensions </extensions>` there won't
be an ``app`` instance to import at all.
When the application handles a request, it creates a :class:`.Request` object.
Because a *worker* handles only one request at a time, the request data can be
considered global to that worker during that request. Passing it as an argument
through every function during the request becomes verbose and redundant.
Flask solves these issues with the *active context* pattern. Rather than
importing an ``app`` directly, or having to pass it and the request through to
every single function, you import and access the proxies, which point to the
currently active application and request data. This is sometimes referred to
as "context local" data.
Context During Setup
--------------------
If you try to access :data:`.current_app`, :data:`.g`, or anything that uses it,
outside an app context, you'll get this error message:
.. code-block:: pytb
RuntimeError: Working outside of application context.
Attempted to use functionality that expected a current application to be
set. To solve this, set up an app context using 'with app.app_context()'.
See the documentation on app context for more information.
If you see that error while configuring your application, such as when
initializing an extension, you can push a context manually since you have direct
access to the ``app``. Use :meth:`.Flask.app_context` in a ``with`` block.
.. code-block:: python
def create_app():
app = Flask(__name__)
with app.app_context():
init_db()
return app
If you see that error somewhere else in your code not related to setting up the
application, it most likely indicates that you should move that code into a view
function or CLI command.
Context During Testing
----------------------
See :doc:`/testing` for detailed information about managing the context during
tests.
If you try to access :data:`.request`, :data:`.session`, or anything that uses
it, outside a request context, you'll get this error message:
.. code-block:: pytb
RuntimeError: Working outside of request context.
Attempted to use functionality that expected an active HTTP request. See the
documentation on request context for more information.
This will probably only happen during tests. If you see that error somewhere
else in your code not related to testing, it most likely indicates that you
should move that code into a view function.
The primary way to solve this is to use :meth:`.Flask.test_client` to simulate
a full request.
If you only want to unit test one function, rather than a full request, use
:meth:`.Flask.test_request_context` in a ``with`` block.
.. code-block:: python
def generate_report(year):
format = request.args.get("format")
...
with app.test_request_context(
"/make_report/2017", query_string={"format": "short"}
):
generate_report()
.. _context-visibility:
Visibility of the Context
-------------------------
The context will have the same lifetime as an activity, such as a request, CLI
command, or ``with`` block. Various callbacks and signals registered with the
app will be run during the context.
When a Flask application handles a request, it pushes a request context
to set the active application and request data. When it handles a CLI command,
it pushes an app context to set the active application. When the activity ends,
it pops that context. Proxy objects like :data:`.request`, :data:`.session`,
:data:`.g`, and :data:`.current_app`, are accessible while the context is pushed
and active, and are not accessible after the context is popped.
The context is unique to each thread (or other worker type). The proxies cannot
be passed to another worker, which has a different context space and will not
know about the active context in the parent's space.
Besides being scoped to each worker, the proxy object has a separate type and
identity than the proxied real object. In some cases you'll need access to the
real object, rather than the proxy. Use the
:meth:`~.LocalProxy._get_current_object` method in those cases.
.. code-block:: python
app = current_app._get_current_object()
my_signal.send(app)
Lifecycle of the Context
------------------------
Flask dispatches a request in multiple stages which can affect the request,
response, and how errors are handled. See :doc:`/lifecycle` for a list of all
the steps, callbacks, and signals during each request. The following are the
steps directly related to the context.
- The app context is pushed, the proxies are available.
- The :data:`.appcontext_pushed` signal is sent.
- The request is dispatched.
- Any :meth:`.Flask.teardown_request` decorated functions are called.
- The :data:`.request_tearing_down` signal is sent.
- Any :meth:`.Flask.teardown_appcontext` decorated functions are called.
- The :data:`.appcontext_tearing_down` signal is sent.
- The app context is popped, the proxies are no longer available.
- The :data:`.appcontext_popped` signal is sent.
The teardown callbacks are called by the context when it is popped. They are
called even if there is an unhandled exception during dispatch. They may be
called multiple times in some test scenarios. This means there is no guarantee
that any other parts of the request dispatch have run. Be sure to write these
functions in a way that does not depend on other callbacks. All callbacks are
called even if any raise an error.
How the Context Works
---------------------
Context locals are implemented using Python's :mod:`contextvars` and Werkzeug's
:class:`~werkzeug.local.LocalProxy`. Python's contextvars are a low level
structure to manage data local to a thread or coroutine. ``LocalProxy`` wraps
the contextvar so that access to any attributes and methods is forwarded to the
object stored in the contextvar.
The context is tracked like a stack, with the active context at the top of the
stack. Flask manages pushing and popping contexts during requests, CLI commands,
testing, ``with`` blocks, etc. The proxies access attributes on the active
context.
Because it is a stack, other contexts may be pushed to change the proxies during
an already active context. This is not a common pattern, but can be used in
advanced use cases. For example, a Flask application can be used as WSGI
middleware, calling another wrapped Flask app from a view.

119
docs/async-await.rst
View file

@ -1,119 +0,0 @@
.. _async_await:
Using ``async`` and ``await``
=============================
.. versionadded:: 2.0
Routes, error handlers, before request, after request, and teardown
functions can all be coroutine functions if Flask is installed with the
``async`` extra (``pip install flask[async]``). This allows views to be
defined with ``async def`` and use ``await``.
.. code-block:: python
@app.route("/get-data")
async def get_data():
data = await async_db_query(...)
return jsonify(data)
Pluggable class-based views also support handlers that are implemented as
coroutines. This applies to the :meth:`~flask.views.View.dispatch_request`
method in views that inherit from the :class:`flask.views.View` class, as
well as all the HTTP method handlers in views that inherit from the
:class:`flask.views.MethodView` class.
Performance
-----------
Async functions require an event loop to run. Flask, as a WSGI
application, uses one worker to handle one request/response cycle.
When a request comes in to an async view, Flask will start an event loop
in a thread, run the view function there, then return the result.
Each request still ties up one worker, even for async views. The upside
is that you can run async code within a view, for example to make
multiple concurrent database queries, HTTP requests to an external API,
etc. However, the number of requests your application can handle at one
time will remain the same.
**Async is not inherently faster than sync code.** Async is beneficial
when performing concurrent IO-bound tasks, but will probably not improve
CPU-bound tasks. Traditional Flask views will still be appropriate for
most use cases, but Flask's async support enables writing and using
code that wasn't possible natively before.
Background tasks
----------------
Async functions will run in an event loop until they complete, at
which stage the event loop will stop. This means any additional
spawned tasks that haven't completed when the async function completes
will be cancelled. Therefore you cannot spawn background tasks, for
example via ``asyncio.create_task``.
If you wish to use background tasks it is best to use a task queue to
trigger background work, rather than spawn tasks in a view
function. With that in mind you can spawn asyncio tasks by serving
Flask with an ASGI server and utilising the asgiref WsgiToAsgi adapter
as described in :doc:`deploying/asgi`. This works as the adapter creates
an event loop that runs continually.
When to use Quart instead
-------------------------
Flask's async support is less performant than async-first frameworks due
to the way it is implemented. If you have a mainly async codebase it
would make sense to consider `Quart`_. Quart is a reimplementation of
Flask based on the `ASGI`_ standard instead of WSGI. This allows it to
handle many concurrent requests, long running requests, and websockets
without requiring multiple worker processes or threads.
It has also already been possible to :doc:`run Flask with Gevent </gevent>` to
get many of the benefits of async request handling. Gevent patches low-level
Python functions to accomplish this, whereas ``async``/``await`` and ASGI use
standard, modern Python capabilities. Deciding whether you should use gevent
with Flask, or Quart, or something else is ultimately up to understanding the
specific needs of your project.
.. _Quart: https://quart.palletsprojects.com
.. _ASGI: https://asgi.readthedocs.io
Extensions
----------
Flask extensions predating Flask's async support do not expect async views.
If they provide decorators to add functionality to views, those will probably
not work with async views because they will not await the function or be
awaitable. Other functions they provide will not be awaitable either and
will probably be blocking if called within an async view.
Extension authors can support async functions by utilising the
:meth:`flask.Flask.ensure_sync` method. For example, if the extension
provides a view function decorator add ``ensure_sync`` before calling
the decorated function,
.. code-block:: python
def extension(func):
@wraps(func)
def wrapper(*args, **kwargs):
... # Extension logic
return current_app.ensure_sync(func)(*args, **kwargs)
return wrapper
Check the changelog of the extension you want to use to see if they've
implemented async support, or make a feature request or PR to them.
Other event loops
-----------------
At the moment Flask only supports :mod:`asyncio`. It's possible to override
:meth:`flask.Flask.ensure_sync` to change how async functions are wrapped to use
a different library. See :ref:`gevent-asyncio` for an example.

56
docs/becomingbig.rst Normal file
View file

@ -0,0 +1,56 @@
.. _becomingbig:
Becoming Big
============
Your application is becoming more and more complex? Flask is really not
designed for large scale applications and does not attempt to do so, but
that does not mean you picked the wrong tool in the first place.
Flask is powered by Werkzeug and Jinja2, two libraries that are in use at
a number of large websites out there and all Flask does is bring those
two together. Being a microframework, Flask is literally a single file.
What that means for large applications is that it's probably a good idea
to take the code from Flask and put it into a new module within the
applications and expand on that.
What Could Be Improved?
-----------------------
For instance it makes a lot of sense to change the way endpoints (the
names of the functions / URL rules) are handled to also take the module
name into account. Right now the function name is the URL name, but
imagine you have a large application consisting of multiple components.
In that case, it makes a lot of sense to use dotted names for the URL
endpoints.
Here are some suggestions for how Flask can be modified to better
accommodate large-scale applications:
- get rid of the decorator function registering which causes a lot
of troubles for applications that have circular dependencies. It
also requires that the whole application is imported when the system
initializes or certain URLs will not be available right away. A
better solution would be to have one module with all URLs in there and
specifying the target functions explicitly or by name and importing
them when needed.
- switch to explicit request object passing. This requires more typing
(because you now have something to pass around) but it makes it a
whole lot easier to debug hairy situations and to test the code.
- integrate the `Babel`_ i18n package or `SQLAlchemy`_ directly into the
core framework.
.. _Babel: http://babel.edgewall.org/
.. _SQLAlchemy: http://www.sqlalchemy.org/
Why does Flask not do all that by Default?
------------------------------------------
There is a huge difference between a small application that only has to
handle a couple of requests per second and with an overall code complexity
of less than 4000 lines of code and something of larger scale. At some
point it becomes important to integrate external systems, different
storage backends and more.
If Flask was designed with all these contingencies in mind, it would be a
much more complex framework and harder to get started with.

315
docs/blueprints.rst
View file

@ -1,315 +0,0 @@
Modular Applications with Blueprints
====================================
.. currentmodule:: flask
.. versionadded:: 0.7
Flask uses a concept of *blueprints* for making application components and
supporting common patterns within an application or across applications.
Blueprints can greatly simplify how large applications work and provide a
central means for Flask extensions to register operations on applications.
A :class:`Blueprint` object works similarly to a :class:`Flask`
application object, but it is not actually an application. Rather it is a
*blueprint* of how to construct or extend an application.
Why Blueprints?
---------------
Blueprints in Flask are intended for these cases:
* Factor an application into a set of blueprints. This is ideal for
larger applications; a project could instantiate an application object,
initialize several extensions, and register a collection of blueprints.
* Register a blueprint on an application at a URL prefix and/or subdomain.
Parameters in the URL prefix/subdomain become common view arguments
(with defaults) across all view functions in the blueprint.
* Register a blueprint multiple times on an application with different URL
rules.
* Provide template filters, static files, templates, and other utilities
through blueprints. A blueprint does not have to implement applications
or view functions.
* Register a blueprint on an application for any of these cases when
initializing a Flask extension.
A blueprint in Flask is not a pluggable app because it is not actually an
application -- it's a set of operations which can be registered on an
application, even multiple times. Why not have multiple application
objects? You can do that (see :doc:`/patterns/appdispatch`), but your
applications will have separate configs and will be managed at the WSGI
layer.
Blueprints instead provide separation at the Flask level, share
application config, and can change an application object as necessary with
being registered. The downside is that you cannot unregister a blueprint
once an application was created without having to destroy the whole
application object.
The Concept of Blueprints
-------------------------
The basic concept of blueprints is that they record operations to execute
when registered on an application. Flask associates view functions with
blueprints when dispatching requests and generating URLs from one endpoint
to another.
My First Blueprint
------------------
This is what a very basic blueprint looks like. In this case we want to
implement a blueprint that does simple rendering of static templates::
from flask import Blueprint, render_template, abort
from jinja2 import TemplateNotFound
simple_page = Blueprint('simple_page', __name__,
template_folder='templates')
@simple_page.route('/', defaults={'page': 'index'})
@simple_page.route('/<page>')
def show(page):
try:
return render_template(f'pages/{page}.html')
except TemplateNotFound:
abort(404)
When you bind a function with the help of the ``@simple_page.route``
decorator, the blueprint will record the intention of registering the
function ``show`` on the application when it's later registered.
Additionally it will prefix the endpoint of the function with the
name of the blueprint which was given to the :class:`Blueprint`
constructor (in this case also ``simple_page``). The blueprint's name
does not modify the URL, only the endpoint.
Registering Blueprints
----------------------
So how do you register that blueprint? Like this::
from flask import Flask
from yourapplication.simple_page import simple_page
app = Flask(__name__)
app.register_blueprint(simple_page)
If you check the rules registered on the application, you will find
these::
>>> app.url_map
Map([<Rule '/static/<filename>' (HEAD, OPTIONS, GET) -> static>,
<Rule '/<page>' (HEAD, OPTIONS, GET) -> simple_page.show>,
<Rule '/' (HEAD, OPTIONS, GET) -> simple_page.show>])
The first one is obviously from the application itself for the static
files. The other two are for the `show` function of the ``simple_page``
blueprint. As you can see, they are also prefixed with the name of the
blueprint and separated by a dot (``.``).
Blueprints however can also be mounted at different locations::
app.register_blueprint(simple_page, url_prefix='/pages')
And sure enough, these are the generated rules::
>>> app.url_map
Map([<Rule '/static/<filename>' (HEAD, OPTIONS, GET) -> static>,
<Rule '/pages/<page>' (HEAD, OPTIONS, GET) -> simple_page.show>,
<Rule '/pages/' (HEAD, OPTIONS, GET) -> simple_page.show>])
On top of that you can register blueprints multiple times though not every
blueprint might respond properly to that. In fact it depends on how the
blueprint is implemented if it can be mounted more than once.
Nesting Blueprints
------------------
It is possible to register a blueprint on another blueprint.
.. code-block:: python
parent = Blueprint('parent', __name__, url_prefix='/parent')
child = Blueprint('child', __name__, url_prefix='/child')
parent.register_blueprint(child)
app.register_blueprint(parent)
The child blueprint will gain the parent's name as a prefix to its
name, and child URLs will be prefixed with the parent's URL prefix.
.. code-block:: python
url_for('parent.child.create')
/parent/child/create
In addition a child blueprint's will gain their parent's subdomain,
with their subdomain as prefix if present i.e.
.. code-block:: python
parent = Blueprint('parent', __name__, subdomain='parent')
child = Blueprint('child', __name__, subdomain='child')
parent.register_blueprint(child)
app.register_blueprint(parent)
url_for('parent.child.create', _external=True)
"child.parent.domain.tld"
Blueprint-specific before request functions, etc. registered with the
parent will trigger for the child. If a child does not have an error
handler that can handle a given exception, the parent's will be tried.
Blueprint Resources
-------------------
Blueprints can provide resources as well. Sometimes you might want to
introduce a blueprint only for the resources it provides.
Blueprint Resource Folder
`````````````````````````
Like for regular applications, blueprints are considered to be contained
in a folder. While multiple blueprints can originate from the same folder,
it does not have to be the case and it's usually not recommended.
The folder is inferred from the second argument to :class:`Blueprint` which
is usually `__name__`. This argument specifies what logical Python
module or package corresponds to the blueprint. If it points to an actual
Python package that package (which is a folder on the filesystem) is the
resource folder. If it's a module, the package the module is contained in
will be the resource folder. You can access the
:attr:`Blueprint.root_path` property to see what the resource folder is::
>>> simple_page.root_path
'/Users/username/TestProject/yourapplication'
To quickly open sources from this folder you can use the
:meth:`~Blueprint.open_resource` function::
with simple_page.open_resource('static/style.css') as f:
code = f.read()
Static Files
````````````
A blueprint can expose a folder with static files by providing the path
to the folder on the filesystem with the ``static_folder`` argument.
It is either an absolute path or relative to the blueprint's location::
admin = Blueprint('admin', __name__, static_folder='static')
By default the rightmost part of the path is where it is exposed on the
web. This can be changed with the ``static_url_path`` argument. Because the
folder is called ``static`` here it will be available at the
``url_prefix`` of the blueprint + ``/static``. If the blueprint
has the prefix ``/admin``, the static URL will be ``/admin/static``.
The endpoint is named ``blueprint_name.static``. You can generate URLs
to it with :func:`url_for` like you would with the static folder of the
application::
url_for('admin.static', filename='style.css')
However, if the blueprint does not have a ``url_prefix``, it is not
possible to access the blueprint's static folder. This is because the
URL would be ``/static`` in this case, and the application's ``/static``
route takes precedence. Unlike template folders, blueprint static
folders are not searched if the file does not exist in the application
static folder.
Templates
`````````
If you want the blueprint to expose templates you can do that by providing
the `template_folder` parameter to the :class:`Blueprint` constructor::
admin = Blueprint('admin', __name__, template_folder='templates')
For static files, the path can be absolute or relative to the blueprint
resource folder.
The template folder is added to the search path of templates but with a lower
priority than the actual application's template folder. That way you can
easily override templates that a blueprint provides in the actual application.
This also means that if you don't want a blueprint template to be accidentally
overridden, make sure that no other blueprint or actual application template
has the same relative path. When multiple blueprints provide the same relative
template path the first blueprint registered takes precedence over the others.
So if you have a blueprint in the folder ``yourapplication/admin`` and you
want to render the template ``'admin/index.html'`` and you have provided
``templates`` as a `template_folder` you will have to create a file like
this: :file:`yourapplication/admin/templates/admin/index.html`. The reason
for the extra ``admin`` folder is to avoid getting our template overridden
by a template named ``index.html`` in the actual application template
folder.
To further reiterate this: if you have a blueprint named ``admin`` and you
want to render a template called :file:`index.html` which is specific to this
blueprint, the best idea is to lay out your templates like this::
yourpackage/
blueprints/
admin/
templates/
admin/
index.html
__init__.py
And then when you want to render the template, use :file:`admin/index.html` as
the name to look up the template by. If you encounter problems loading
the correct templates enable the ``EXPLAIN_TEMPLATE_LOADING`` config
variable which will instruct Flask to print out the steps it goes through
to locate templates on every ``render_template`` call.
Building URLs
-------------
If you want to link from one page to another you can use the
:func:`url_for` function just like you normally would do just that you
prefix the URL endpoint with the name of the blueprint and a dot (``.``)::
url_for('admin.index')
Additionally if you are in a view function of a blueprint or a rendered
template and you want to link to another endpoint of the same blueprint,
you can use relative redirects by prefixing the endpoint with a dot only::
url_for('.index')
This will link to ``admin.index`` for instance in case the current request
was dispatched to any other admin blueprint endpoint.
Blueprint Error Handlers
------------------------
Blueprints support the ``errorhandler`` decorator just like the :class:`Flask`
application object, so it is easy to make Blueprint-specific custom error
pages.
Here is an example for a "404 Page Not Found" exception::
@simple_page.errorhandler(404)
def page_not_found(e):
return render_template('pages/404.html')
Most errorhandlers will simply work as expected; however, there is a caveat
concerning handlers for 404 and 405 exceptions. These errorhandlers are only
invoked from an appropriate ``raise`` statement or a call to ``abort`` in another
of the blueprint's view functions; they are not invoked by, e.g., an invalid URL
access. This is because the blueprint does not "own" a certain URL space, so
the application instance has no way of knowing which blueprint error handler it
should run if given an invalid URL. If you would like to execute different
handling strategies for these errors based on URL prefixes, they may be defined
at the application level using the ``request`` proxy object::
@app.errorhandler(404)
@app.errorhandler(405)
def _handle_api_error(ex):
if request.path.startswith('/api/'):
return jsonify(error=str(ex)), ex.code
else:
return ex
See :doc:`/errorhandling`.

1
docs/changelog.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../CHANGES

4
docs/changes.rst
View file

@ -1,4 +0,0 @@
Changes
=======
.. include:: ../CHANGES.rst

556
docs/cli.rst
View file

@ -1,556 +0,0 @@
.. currentmodule:: flask
Command Line Interface
======================
Installing Flask installs the ``flask`` script, a `Click`_ command line
interface, in your virtualenv. Executed from the terminal, this script gives
access to built-in, extension, and application-defined commands. The ``--help``
option will give more information about any commands and options.
.. _Click: https://click.palletsprojects.com/
Application Discovery
---------------------
The ``flask`` command is installed by Flask, not your application; it must be
told where to find your application in order to use it. The ``--app``
option is used to specify how to load the application.
While ``--app`` supports a variety of options for specifying your
application, most use cases should be simple. Here are the typical values:
(nothing)
The name "app" or "wsgi" is imported (as a ".py" file, or package),
automatically detecting an app (``app`` or ``application``) or
factory (``create_app`` or ``make_app``).
``--app hello``
The given name is imported, automatically detecting an app (``app``
or ``application``) or factory (``create_app`` or ``make_app``).
----
``--app`` has three parts: an optional path that sets the current working
directory, a Python file or dotted import path, and an optional variable
name of the instance or factory. If the name is a factory, it can optionally
be followed by arguments in parentheses. The following values demonstrate these
parts:
``--app src/hello``
Sets the current working directory to ``src`` then imports ``hello``.
``--app hello.web``
Imports the path ``hello.web``.
``--app hello:app2``
Uses the ``app2`` Flask instance in ``hello``.
``--app 'hello:create_app("dev")'``
The ``create_app`` factory in ``hello`` is called with the string ``'dev'``
as the argument.
If ``--app`` is not set, the command will try to import "app" or
"wsgi" (as a ".py" file, or package) and try to detect an application
instance or factory.
Within the given import, the command looks for an application instance named
``app`` or ``application``, then any application instance. If no instance is
found, the command looks for a factory function named ``create_app`` or
``make_app`` that returns an instance.
If parentheses follow the factory name, their contents are parsed as
Python literals and passed as arguments and keyword arguments to the
function. This means that strings must still be in quotes.
Run the Development Server
--------------------------
The :func:`run <cli.run_command>` command will start the development server. It
replaces the :meth:`Flask.run` method in most cases. ::
$ flask --app hello run
* Serving Flask app "hello"
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
.. warning:: Do not use this command to run your application in production.
Only use the development server during development. The development server
is provided for convenience, but is not designed to be particularly secure,
stable, or efficient. See :doc:`/deploying/index` for how to run in production.
If another program is already using port 5000, you'll see
``OSError: [Errno 98]`` or ``OSError: [WinError 10013]`` when the
server tries to start. See :ref:`address-already-in-use` for how to
handle that.
Debug Mode
~~~~~~~~~~
In debug mode, the ``flask run`` command will enable the interactive debugger and the
reloader by default, and make errors easier to see and debug. To enable debug mode, use
the ``--debug`` option.
.. code-block:: console
$ flask --app hello run --debug
* Serving Flask app "hello"
* Debug mode: on
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
* Restarting with inotify reloader
* Debugger is active!
* Debugger PIN: 223-456-919
The ``--debug`` option can also be passed to the top level ``flask`` command to enable
debug mode for any command. The following two ``run`` calls are equivalent.
.. code-block:: console
$ flask --app hello --debug run
$ flask --app hello run --debug
Watch and Ignore Files with the Reloader
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When using debug mode, the reloader will trigger whenever your Python code or imported
modules change. The reloader can watch additional files with the ``--extra-files``
option. Multiple paths are separated with ``:``, or ``;`` on Windows.
.. code-block:: text
$ flask run --extra-files file1:dirA/file2:dirB/
* Running on http://127.0.0.1:8000/
* Detected change in '/path/to/file1', reloading
The reloader can also ignore files using :mod:`fnmatch` patterns with the
``--exclude-patterns`` option. Multiple patterns are separated with ``:``, or ``;`` on
Windows.
Open a Shell
------------
To explore the data in your application, you can start an interactive Python
shell with the :func:`shell <cli.shell_command>` command. An application
context will be active, and the app instance will be imported. ::
$ flask shell
Python 3.10.0 (default, Oct 27 2021, 06:59:51) [GCC 11.1.0] on linux
App: example [production]
Instance: /home/david/Projects/pallets/flask/instance
>>>
Use :meth:`~Flask.shell_context_processor` to add other automatic imports.
.. _dotenv:
Environment Variables From dotenv
---------------------------------
The ``flask`` command supports setting any option for any command with
environment variables. The variables are named like ``FLASK_OPTION`` or
``FLASK_COMMAND_OPTION``, for example ``FLASK_APP`` or
``FLASK_RUN_PORT``.
Rather than passing options every time you run a command, or environment
variables every time you open a new terminal, you can use Flask's dotenv
support to set environment variables automatically.
If `python-dotenv`_ is installed, running the ``flask`` command will set
environment variables defined in the files ``.env`` and ``.flaskenv``.
You can also specify an extra file to load with the ``--env-file``
option. Dotenv files can be used to avoid having to set ``--app`` or
``FLASK_APP`` manually, and to set configuration using environment
variables similar to how some deployment services work.
Variables set on the command line are used over those set in :file:`.env`,
which are used over those set in :file:`.flaskenv`. :file:`.flaskenv` should be
used for public variables, such as ``FLASK_APP``, while :file:`.env` should not
be committed to your repository so that it can set private variables.
Directories are scanned upwards from the directory you call ``flask``
from to locate the files.
The files are only loaded by the ``flask`` command or calling
:meth:`~Flask.run`. If you would like to load these files when running in
production, you should call :func:`~cli.load_dotenv` manually.
.. _python-dotenv: https://github.com/theskumar/python-dotenv#readme
Setting Command Options
~~~~~~~~~~~~~~~~~~~~~~~
Click is configured to load default values for command options from
environment variables. The variables use the pattern
``FLASK_COMMAND_OPTION``. For example, to set the port for the run
command, instead of ``flask run --port 8000``:
.. tabs::
.. group-tab:: Bash
.. code-block:: text
$ export FLASK_RUN_PORT=8000
$ flask run
* Running on http://127.0.0.1:8000/
.. group-tab:: Fish
.. code-block:: text
$ set -x FLASK_RUN_PORT 8000
$ flask run
* Running on http://127.0.0.1:8000/
.. group-tab:: CMD
.. code-block:: text
> set FLASK_RUN_PORT=8000
> flask run
* Running on http://127.0.0.1:8000/
.. group-tab:: Powershell
.. code-block:: text
> $env:FLASK_RUN_PORT = 8000
> flask run
* Running on http://127.0.0.1:8000/
These can be added to the ``.flaskenv`` file just like ``FLASK_APP`` to
control default command options.
Disable dotenv
~~~~~~~~~~~~~~
The ``flask`` command will show a message if it detects dotenv files but
python-dotenv is not installed.
.. code-block:: bash
$ flask run
* Tip: There are .env files present. Do "pip install python-dotenv" to use them.
You can tell Flask not to load dotenv files even when python-dotenv is
installed by setting the ``FLASK_SKIP_DOTENV`` environment variable.
This can be useful if you want to load them manually, or if you're using
a project runner that loads them already. Keep in mind that the
environment variables must be set before the app loads or it won't
configure as expected.
.. tabs::
.. group-tab:: Bash
.. code-block:: text
$ export FLASK_SKIP_DOTENV=1
$ flask run
.. group-tab:: Fish
.. code-block:: text
$ set -x FLASK_SKIP_DOTENV 1
$ flask run
.. group-tab:: CMD
.. code-block:: text
> set FLASK_SKIP_DOTENV=1
> flask run
.. group-tab:: Powershell
.. code-block:: text
> $env:FLASK_SKIP_DOTENV = 1
> flask run
Environment Variables From virtualenv
-------------------------------------
If you do not want to install dotenv support, you can still set environment
variables by adding them to the end of the virtualenv's :file:`activate`
script. Activating the virtualenv will set the variables.
.. tabs::
.. group-tab:: Bash
Unix Bash, :file:`.venv/bin/activate`::
$ export FLASK_APP=hello
.. group-tab:: Fish
Fish, :file:`.venv/bin/activate.fish`::
$ set -x FLASK_APP hello
.. group-tab:: CMD
Windows CMD, :file:`.venv\\Scripts\\activate.bat`::
> set FLASK_APP=hello
.. group-tab:: Powershell
Windows Powershell, :file:`.venv\\Scripts\\activate.ps1`::
> $env:FLASK_APP = "hello"
It is preferred to use dotenv support over this, since :file:`.flaskenv` can be
committed to the repository so that it works automatically wherever the project
is checked out.
Custom Commands
---------------
The ``flask`` command is implemented using `Click`_. See that project's
documentation for full information about writing commands.
This example adds the command ``create-user`` that takes the argument
``name``. ::
import click
from flask import Flask
app = Flask(__name__)
@app.cli.command("create-user")
@click.argument("name")
def create_user(name):
...
::
$ flask create-user admin
This example adds the same command, but as ``user create``, a command in a
group. This is useful if you want to organize multiple related commands. ::
import click
from flask import Flask
from flask.cli import AppGroup
app = Flask(__name__)
user_cli = AppGroup('user')
@user_cli.command('create')
@click.argument('name')
def create_user(name):
...
app.cli.add_command(user_cli)
::
$ flask user create demo
See :ref:`testing-cli` for an overview of how to test your custom
commands.
Registering Commands with Blueprints
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If your application uses blueprints, you can optionally register CLI
commands directly onto them. When your blueprint is registered onto your
application, the associated commands will be available to the ``flask``
command. By default, those commands will be nested in a group matching
the name of the blueprint.
.. code-block:: python
from flask import Blueprint
bp = Blueprint('students', __name__)
@bp.cli.command('create')
@click.argument('name')
def create(name):
...
app.register_blueprint(bp)
.. code-block:: text
$ flask students create alice
You can alter the group name by specifying the ``cli_group`` parameter
when creating the :class:`Blueprint` object, or later with
:meth:`app.register_blueprint(bp, cli_group='...') <Flask.register_blueprint>`.
The following are equivalent:
.. code-block:: python
bp = Blueprint('students', __name__, cli_group='other')
# or
app.register_blueprint(bp, cli_group='other')
.. code-block:: text
$ flask other create alice
Specifying ``cli_group=None`` will remove the nesting and merge the
commands directly to the application's level:
.. code-block:: python
bp = Blueprint('students', __name__, cli_group=None)
# or
app.register_blueprint(bp, cli_group=None)
.. code-block:: text
$ flask create alice
Application Context
~~~~~~~~~~~~~~~~~~~
Commands added using the Flask app's :attr:`~Flask.cli` or
:class:`~flask.cli.FlaskGroup` :meth:`~cli.AppGroup.command` decorator
will be executed with an application context pushed, so your custom
commands and parameters have access to the app and its configuration. The
:func:`~cli.with_appcontext` decorator can be used to get the same
behavior, but is not needed in most cases.
.. code-block:: python
import click
from flask.cli import with_appcontext
@click.command()
@with_appcontext
def do_work():
...
app.cli.add_command(do_work)
Plugins
-------
Flask will automatically load commands specified in the ``flask.commands``
`entry point`_. This is useful for extensions that want to add commands when
they are installed. Entry points are specified in :file:`pyproject.toml`:
.. code-block:: toml
[project.entry-points."flask.commands"]
my-command = "my_extension.commands:cli"
.. _entry point: https://packaging.python.org/tutorials/packaging-projects/#entry-points
Inside :file:`my_extension/commands.py` you can then export a Click
object::
import click
@click.command()
def cli():
...
Once that package is installed in the same virtualenv as your Flask project,
you can run ``flask my-command`` to invoke the command.
.. _custom-scripts:
Custom Scripts
--------------
When you are using the app factory pattern, it may be more convenient to define
your own Click script. Instead of using ``--app`` and letting Flask load
your application, you can create your own Click object and export it as a
`console script`_ entry point.
Create an instance of :class:`~cli.FlaskGroup` and pass it the factory::
import click
from flask import Flask
from flask.cli import FlaskGroup
def create_app():
app = Flask('wiki')
# other setup
return app
@click.group(cls=FlaskGroup, create_app=create_app)
def cli():
"""Management script for the Wiki application."""
Define the entry point in :file:`pyproject.toml`:
.. code-block:: toml
[project.scripts]
wiki = "wiki:cli"
Install the application in the virtualenv in editable mode and the custom
script is available. Note that you don't need to set ``--app``. ::
$ pip install -e .
$ wiki run
.. admonition:: Errors in Custom Scripts
When using a custom script, if you introduce an error in your
module-level code, the reloader will fail because it can no longer
load the entry point.
The ``flask`` command, being separate from your code, does not have
this issue and is recommended in most cases.
.. _console script: https://packaging.python.org/tutorials/packaging-projects/#console-scripts
PyCharm Integration
-------------------
PyCharm Professional provides a special Flask run configuration to run the development
server. For the Community Edition, and for other commands besides ``run``, you need to
create a custom run configuration. These instructions should be similar for any other
IDE you use.
In PyCharm, with your project open, click on *Run* from the menu bar and go to *Edit
Configurations*. You'll see a screen similar to this:
.. image:: _static/pycharm-run-config.png
:align: center
:class: screenshot
:alt: Screenshot of PyCharm run configuration.
Once you create a configuration for the ``flask run``, you can copy and change it to
call any other command.
Click the *+ (Add New Configuration)* button and select *Python*. Give the configuration
a name such as "flask run".
Click the *Script path* dropdown and change it to *Module name*, then input ``flask``.
The *Parameters* field is set to the CLI command to execute along with any arguments.
This example uses ``--app hello run --debug``, which will run the development server in
debug mode. ``--app hello`` should be the import or file with your Flask app.
If you installed your project as a package in your virtualenv, you may uncheck the
*PYTHONPATH* options. This will more accurately match how you deploy later.
Click *OK* to save and close the configuration. Select the configuration in the main
PyCharm window and click the play button next to it to run the server.
Now that you have a configuration for ``flask run``, you can copy that configuration and
change the *Parameters* argument to run a different CLI command.

304
docs/conf.py
View file

@ -1,101 +1,243 @@
import packaging.version # -*- coding: utf-8 -*-
from pallets_sphinx_themes import get_version #
from pallets_sphinx_themes import ProjectLink # Flask documentation build configuration file, created by
# sphinx-quickstart on Tue Apr 6 15:24:58 2010.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# Project -------------------------------------------------------------- import sys, os
project = "Flask" # If extensions (or modules to document with autodoc) are in another directory,
copyright = "2010 Pallets" # add these directories to sys.path here. If the directory is relative to the
author = "Pallets" # documentation root, use os.path.abspath to make it absolute, like shown here.
release, version = get_version("Flask") sys.path.append(os.path.abspath('_themes'))
# General -------------------------------------------------------------- # -- General configuration -----------------------------------------------------
default_role = "code" # If your documentation needs a minimal Sphinx version, state it here.
extensions = [ #needs_sphinx = '1.0'
"sphinx.ext.autodoc",
"sphinx.ext.extlinks", # Add any Sphinx extension module names here, as strings. They can be extensions
"sphinx.ext.intersphinx", # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
"sphinxcontrib.log_cabinet", extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
"sphinx_tabs.tabs",
"pallets_sphinx_themes", # Add any paths that contain templates here, relative to this directory.
] templates_path = ['_templates']
autodoc_member_order = "bysource"
autodoc_typehints = "description" # The suffix of source filenames.
autodoc_preserve_defaults = True source_suffix = '.rst'
extlinks = {
"issue": ("https://github.com/pallets/flask/issues/%s", "#%s"), # The encoding of source files.
"pr": ("https://github.com/pallets/flask/pull/%s", "#%s"), #source_encoding = 'utf-8-sig'
"ghsa": ("https://github.com/pallets/flask/security/advisories/GHSA-%s", "GHSA-%s"),
} # The master toctree document.
intersphinx_mapping = { master_doc = 'index'
"python": ("https://docs.python.org/3/", None),
"werkzeug": ("https://werkzeug.palletsprojects.com/", None), # General information about the project.
"click": ("https://click.palletsprojects.com/", None), project = u'Flask'
"jinja": ("https://jinja.palletsprojects.com/", None), copyright = u'2010, Armin Ronacher'
"itsdangerous": ("https://itsdangerous.palletsprojects.com/", None),
"sqlalchemy": ("https://docs.sqlalchemy.org/", None), import pkg_resources
"wtforms": ("https://wtforms.readthedocs.io/", None),
"blinker": ("https://blinker.readthedocs.io/", None), # The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
release = __import__('pkg_resources').get_distribution('Flask').version
if 'dev' in release:
release = release.split('dev')[0] + 'dev'
version = '.'.join(release.split('.')[:2])
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
html_theme = 'flask'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
html_theme_options = {
'touch_icon': 'touch-icon.png'
} }
# HTML ----------------------------------------------------------------- # Add any paths that contain custom themes here, relative to this directory.
html_theme_path = ['_themes']
html_theme = "flask" # The name for this set of Sphinx documents. If None, it defaults to
html_theme_options = {"index_sidebar_logo": False} # "<project> v<release> documentation".
html_context = { #html_title = None
"project_links": [
ProjectLink("Donate", "https://palletsprojects.com/donate"), # A shorter title for the navigation bar. Default is the same as html_title.
ProjectLink("PyPI Releases", "https://pypi.org/project/Flask/"), #html_short_title = None
ProjectLink("Source Code", "https://github.com/pallets/flask/"),
ProjectLink("Issue Tracker", "https://github.com/pallets/flask/issues/"), # The name of an image file (relative to this directory) to place at the top
ProjectLink("Chat", "https://discord.gg/pallets"), # of the sidebar. Do not set, template magic!
] #html_logo = None
}
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
html_sidebars = { html_sidebars = {
"index": ["project.html", "localtoc.html", "searchbox.html", "ethicalads.html"], 'index': ['sidebarintro.html', 'sourcelink.html', 'searchbox.html'],
"**": ["localtoc.html", "relations.html", "searchbox.html", "ethicalads.html"], '**': ['sidebarlogo.html', 'localtoc.html', 'relations.html',
'sourcelink.html', 'searchbox.html']
} }
singlehtml_sidebars = {"index": ["project.html", "localtoc.html", "ethicalads.html"]}
html_static_path = ["_static"]
html_favicon = "_static/flask-icon.svg"
html_logo = "_static/flask-logo.svg"
html_title = f"Flask Documentation ({version})"
html_show_sourcelink = False
gettext_uuid = True # Additional templates that should be rendered to pages, maps page names to
gettext_compact = False # template names.
#html_additional_pages = {}
# Local Extensions ----------------------------------------------------- # If false, no module index is generated.
html_use_modindex = False
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
html_show_sphinx = False
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = ''
# Output file base name for HTML help builder.
htmlhelp_basename = 'Flaskdoc'
def github_link(name, rawtext, text, lineno, inliner, options=None, content=None): # -- Options for LaTeX output --------------------------------------------------
app = inliner.document.settings.env.app
release = app.config.release
base_url = "https://github.com/pallets/flask/tree/"
if text.endswith(">"): # Grouping the document tree into LaTeX files. List of tuples
words, text = text[:-1].rsplit("<", 1) # (source start file, target name, title, author, documentclass [howto/manual]).
words = words.strip() latex_documents = [
else: ('latexindex', 'Flask.tex', u'Flask Documentation',
words = None u'Armin Ronacher', 'manual'),
]
if packaging.version.parse(release).is_devrelease: # Documents to append as an appendix to all manuals.
url = f"{base_url}main/{text}" #latex_appendices = []
else:
url = f"{base_url}{release}/{text}"
if words is None: # If false, no module index is generated.
words = url latex_use_modindex = False
from docutils.nodes import reference latex_elements = {
from docutils.parsers.rst.roles import set_classes 'fontpkg': r'\usepackage{mathpazo}',
'papersize': 'a4paper',
'pointsize': '12pt',
'preamble': r'\usepackage{flaskstyle}'
}
latex_use_parts = True
options = options or {} latex_additional_files = ['flaskstyle.sty', 'logo.pdf']
set_classes(options)
node = reference(rawtext, words, refuri=url, **options)
return [node], []
def setup(app): # -- Options for Epub output ---------------------------------------------------
app.add_role("gh", github_link)
# Bibliographic Dublin Core info.
#epub_title = ''
#epub_author = ''
#epub_publisher = ''
#epub_copyright = ''
# The language of the text. It defaults to the language option
# or en if the language is not set.
#epub_language = ''
# The scheme of the identifier. Typical schemes are ISBN or URL.
#epub_scheme = ''
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#epub_identifier = ''
# A unique identification for the text.
#epub_uid = ''
# HTML files that should be inserted before the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_pre_files = []
# HTML files shat should be inserted after the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_post_files = []
# A list of files that should not be packed into the epub file.
#epub_exclude_files = []
# The depth of the table of contents in toc.ncx.
#epub_tocdepth = 3
intersphinx_mapping = {
'http://docs.python.org/dev': None,
'http://werkzeug.pocoo.org/documentation/dev/': None,
'http://www.sqlalchemy.org/docs/': None,
'http://wtforms.simplecodes.com/docs/0.5/': None
}
pygments_style = 'flask_theme_support.FlaskyStyle'

823
docs/config.rst
View file

@ -1,14 +1,17 @@
.. _config:
Configuration Handling Configuration Handling
====================== ======================
Applications need some kind of configuration. There are different settings .. versionadded:: 0.3
you might want to change depending on the application environment like
toggling the debug mode, setting the secret key, and other such Applications need some kind of configuration. There are different things
environment-specific things. you might want to change. Like toggling debug mode, the secret key and a
lot of very similar things.
The way Flask is designed usually requires the configuration to be The way Flask is designed usually requires the configuration to be
available when the application starts up. You can hard code the available when the application starts up. You can either hardcode the
configuration in the code, which for many small applications is not configuration in the code which for many small applications is not
actually that bad, but there are better ways. actually that bad, but there are better ways.
Independent of how you load your config, there is a config object Independent of how you load your config, there is a config object
@ -18,7 +21,6 @@ object. This is the place where Flask itself puts certain configuration
values and also where extensions can put their configuration values. But values and also where extensions can put their configuration values. But
this is also where you can have your own configuration. this is also where you can have your own configuration.
Configuration Basics Configuration Basics
-------------------- --------------------
@ -26,814 +28,97 @@ The :attr:`~flask.Flask.config` is actually a subclass of a dictionary and
can be modified just like any dictionary:: can be modified just like any dictionary::
app = Flask(__name__) app = Flask(__name__)
app.config['TESTING'] = True app.config['DEBUG'] = True
Certain configuration values are also forwarded to the Certain configuration values are also forwarded to the
:attr:`~flask.Flask` object so you can read and write them from there:: :attr:`~flask.Flask` object so that you can read and write them from
there::
app.testing = True app.debug = True
To update multiple keys at once you can use the :meth:`dict.update` To update multiple keys at once you can use the :meth:`dict.update`
method:: method::
app.config.update( app.config.update(
TESTING=True, DEBUG=True,
SECRET_KEY='192b9bdd22ab9ed4d12e236c78afcb9a393ec15f71bbf5dc987d54727823bcbf' SECRET_KEY='...'
) )
Debug Mode
----------
The :data:`DEBUG` config value is special because it may behave inconsistently if
changed after the app has begun setting up. In order to set debug mode reliably, use the
``--debug`` option on the ``flask`` or ``flask run`` command. ``flask run`` will use the
interactive debugger and reloader by default in debug mode.
.. code-block:: text
$ flask --app hello run --debug
Using the option is recommended. While it is possible to set :data:`DEBUG` in your
config or code, this is strongly discouraged. It can't be read early by the
``flask run`` command, and some systems or extensions may have already configured
themselves based on a previous value.
Builtin Configuration Values Builtin Configuration Values
---------------------------- ----------------------------
The following configuration values are used internally by Flask: The following configuration values are used internally by Flask:
.. py:data:: DEBUG .. tabularcolumns:: |p{6.5cm}|p{8.5cm}|
Whether debug mode is enabled. When using ``flask run`` to start the development =============================== =========================================
server, an interactive debugger will be shown for unhandled exceptions, and the ``DEBUG`` enable/disable debug mode
server will be reloaded when code changes. The :attr:`~flask.Flask.debug` attribute ``SECRET_KEY`` the secret key
maps to this config key. This is set with the ``FLASK_DEBUG`` environment variable. ``SESSION_COOKIE_NAME`` the name of the session cookie
It may not behave as expected if set in code. ``PERMANENT_SESSION_LIFETIME`` the lifetime of a permanent session as
:class:`datetime.timedelta` object.
**Do not enable debug mode when deploying in production.** ``USE_X_SENDFILE`` enable/disable x-sendfile
=============================== =========================================
Default: ``False``
Configuring from Files
.. py:data:: TESTING ----------------------
Enable testing mode. Exceptions are propagated rather than handled by Configuration becomes more useful if you can configure from a file. And
the app's error handlers. Extensions may also change their behavior to ideally that file would be outside of the actual application package that
facilitate easier testing. You should enable this in your own tests. you can install the package with distribute (:ref:`distribute-deployment`)
and still modify that file afterwards.
Default: ``False``
So a common pattern is this::
.. py:data:: PROPAGATE_EXCEPTIONS
Exceptions are re-raised rather than being handled by the app's error
handlers. If not set, this is implicitly true if ``TESTING`` or ``DEBUG``
is enabled.
Default: ``None``
.. py:data:: TRAP_HTTP_EXCEPTIONS
If there is no handler for an ``HTTPException``-type exception, re-raise it
to be handled by the interactive debugger instead of returning it as a
simple error response.
Default: ``False``
.. py:data:: TRAP_BAD_REQUEST_ERRORS
Trying to access a key that doesn't exist from request dicts like ``args``
and ``form`` will return a 400 Bad Request error page. Enable this to treat
the error as an unhandled exception instead so that you get the interactive
debugger. This is a more specific version of ``TRAP_HTTP_EXCEPTIONS``. If
unset, it is enabled in debug mode.
Default: ``None``
.. py:data:: SECRET_KEY
A secret key that will be used for securely signing the session cookie
and can be used for any other security related needs by extensions or your
application. It should be a long random ``bytes`` or ``str``. For
example, copy the output of this to your config::
$ python -c 'import secrets; print(secrets.token_hex())'
'192b9bdd22ab9ed4d12e236c78afcb9a393ec15f71bbf5dc987d54727823bcbf'
**Do not reveal the secret key when posting questions or committing code.**
Default: ``None``
.. py:data:: SECRET_KEY_FALLBACKS
A list of old secret keys that can still be used for unsigning. This allows
a project to implement key rotation without invalidating active sessions or
other recently-signed secrets.
Keys should be removed after an appropriate period of time, as checking each
additional key adds some overhead.
Order should not matter, but the default implementation will test the last
key in the list first, so it might make sense to order oldest to newest.
Flask's built-in secure cookie session supports this. Extensions that use
:data:`SECRET_KEY` may not support this yet.
Default: ``None``
.. versionadded:: 3.1
.. py:data:: SESSION_COOKIE_NAME
The name of the session cookie. Can be changed in case you already have a
cookie with the same name.
Default: ``'session'``
.. py:data:: SESSION_COOKIE_DOMAIN
The value of the ``Domain`` parameter on the session cookie. If not set, browsers
will only send the cookie to the exact domain it was set from. Otherwise, they
will send it to any subdomain of the given value as well.
Not setting this value is more restricted and secure than setting it.
Default: ``None``
.. warning::
If this is changed after the browser created a cookie is created with
one setting, it may result in another being created. Browsers may send
send both in an undefined order. In that case, you may want to change
:data:`SESSION_COOKIE_NAME` as well or otherwise invalidate old sessions.
.. versionchanged:: 2.3
Not set by default, does not fall back to ``SERVER_NAME``.
.. py:data:: SESSION_COOKIE_PATH
The path that the session cookie will be valid for. If not set, the cookie
will be valid underneath ``APPLICATION_ROOT`` or ``/`` if that is not set.
Default: ``None``
.. py:data:: SESSION_COOKIE_HTTPONLY
Browsers will not allow JavaScript access to cookies marked as "HTTP only"
for security.
Default: ``True``
.. py:data:: SESSION_COOKIE_SECURE
Browsers will only send cookies with requests over HTTPS if the cookie is
marked "secure". The application must be served over HTTPS for this to make
sense.
Default: ``False``
.. py:data:: SESSION_COOKIE_PARTITIONED
Browsers will send cookies based on the top-level document's domain, rather
than only the domain of the document setting the cookie. This prevents third
party cookies set in iframes from "leaking" between separate sites.
Browsers are beginning to disallow non-partitioned third party cookies, so
you need to mark your cookies partitioned if you expect them to work in such
embedded situations.
Enabling this implicitly enables :data:`SESSION_COOKIE_SECURE` as well, as
it is only valid when served over HTTPS.
Default: ``False``
.. versionadded:: 3.1
.. py:data:: SESSION_COOKIE_SAMESITE
Restrict how cookies are sent with requests from external sites. Can
be set to ``'Lax'`` (recommended) or ``'Strict'``.
See :ref:`security-cookie`.
Default: ``None``
.. versionadded:: 1.0
.. py:data:: PERMANENT_SESSION_LIFETIME
If ``session.permanent`` is true, the cookie's expiration will be set this
number of seconds in the future. Can either be a
:class:`datetime.timedelta` or an ``int``.
Flask's default cookie implementation validates that the cryptographic
signature is not older than this value.
Default: ``timedelta(days=31)`` (``2678400`` seconds)
.. py:data:: SESSION_REFRESH_EACH_REQUEST
Control whether the cookie is sent with every response when
``session.permanent`` is true. Sending the cookie every time (the default)
can more reliably keep the session from expiring, but uses more bandwidth.
Non-permanent sessions are not affected.
Default: ``True``
.. py:data:: USE_X_SENDFILE
When serving files, set the ``X-Sendfile`` header instead of serving the
data with Flask. Some web servers, such as Apache, recognize this and serve
the data more efficiently. This only makes sense when using such a server.
Default: ``False``
.. py:data:: SEND_FILE_MAX_AGE_DEFAULT
When serving files, set the cache control max age to this number of
seconds. Can be a :class:`datetime.timedelta` or an ``int``.
Override this value on a per-file basis using
:meth:`~flask.Flask.get_send_file_max_age` on the application or
blueprint.
If ``None``, ``send_file`` tells the browser to use conditional
requests will be used instead of a timed cache, which is usually
preferable.
Default: ``None``
.. py:data:: TRUSTED_HOSTS
Validate :attr:`.Request.host` and other attributes that use it against
these trusted values. Raise a :exc:`~werkzeug.exceptions.SecurityError` if
the host is invalid, which results in a 400 error. If it is ``None``, all
hosts are valid. Each value is either an exact match, or can start with
a dot ``.`` to match any subdomain.
Validation is done during routing against this value. ``before_request`` and
``after_request`` callbacks will still be called.
Default: ``None``
.. versionadded:: 3.1
.. py:data:: SERVER_NAME
Inform the application what host and port it is bound to.
Must be set if ``subdomain_matching`` is enabled, to be able to extract the
subdomain from the request.
Must be set for ``url_for`` to generate external URLs outside of a
request context.
Default: ``None``
.. versionchanged:: 3.1
Does not restrict requests to only this domain, for both
``subdomain_matching`` and ``host_matching``.
.. versionchanged:: 1.0
Does not implicitly enable ``subdomain_matching``.
.. versionchanged:: 2.3
Does not affect ``SESSION_COOKIE_DOMAIN``.
.. py:data:: APPLICATION_ROOT
Inform the application what path it is mounted under by the application /
web server. This is used for generating URLs outside the context of a
request (inside a request, the dispatcher is responsible for setting
``SCRIPT_NAME`` instead; see :doc:`/patterns/appdispatch`
for examples of dispatch configuration).
Will be used for the session cookie path if ``SESSION_COOKIE_PATH`` is not
set.
Default: ``'/'``
.. py:data:: PREFERRED_URL_SCHEME
Use this scheme for generating external URLs when not in a request context.
Default: ``'http'``
.. py:data:: MAX_CONTENT_LENGTH
The maximum number of bytes that will be read during this request. If
this limit is exceeded, a 413 :exc:`~werkzeug.exceptions.RequestEntityTooLarge`
error is raised. If it is set to ``None``, no limit is enforced at the
Flask application level. However, if it is ``None`` and the request has no
``Content-Length`` header and the WSGI server does not indicate that it
terminates the stream, then no data is read to avoid an infinite stream.
Each request defaults to this config. It can be set on a specific
:attr:`.Request.max_content_length` to apply the limit to that specific
view. This should be set appropriately based on an application's or view's
specific needs.
Default: ``None``
.. versionadded:: 0.6
.. py:data:: MAX_FORM_MEMORY_SIZE
The maximum size in bytes any non-file form field may be in a
``multipart/form-data`` body. If this limit is exceeded, a 413
:exc:`~werkzeug.exceptions.RequestEntityTooLarge` error is raised. If it is
set to ``None``, no limit is enforced at the Flask application level.
Each request defaults to this config. It can be set on a specific
:attr:`.Request.max_form_memory_parts` to apply the limit to that specific
view. This should be set appropriately based on an application's or view's
specific needs.
Default: ``500_000``
.. versionadded:: 3.1
.. py:data:: MAX_FORM_PARTS
The maximum number of fields that may be present in a
``multipart/form-data`` body. If this limit is exceeded, a 413
:exc:`~werkzeug.exceptions.RequestEntityTooLarge` error is raised. If it
is set to ``None``, no limit is enforced at the Flask application level.
Each request defaults to this config. It can be set on a specific
:attr:`.Request.max_form_parts` to apply the limit to that specific view.
This should be set appropriately based on an application's or view's
specific needs.
Default: ``1_000``
.. versionadded:: 3.1
.. py:data:: TEMPLATES_AUTO_RELOAD
Reload templates when they are changed. If not set, it will be enabled in
debug mode.
Default: ``None``
.. py:data:: EXPLAIN_TEMPLATE_LOADING
Log debugging information tracing how a template file was loaded. This can
be useful to figure out why a template was not loaded or the wrong file
appears to be loaded.
Default: ``False``
.. py:data:: MAX_COOKIE_SIZE
Warn if cookie headers are larger than this many bytes. Defaults to
``4093``. Larger cookies may be silently ignored by browsers. Set to
``0`` to disable the warning.
.. py:data:: PROVIDE_AUTOMATIC_OPTIONS
Set to ``False`` to disable the automatic addition of OPTIONS
responses. This can be overridden per route by altering the
``provide_automatic_options`` attribute.
.. versionadded:: 0.4
``LOGGER_NAME``
.. versionadded:: 0.5
``SERVER_NAME``
.. versionadded:: 0.6
``MAX_CONTENT_LENGTH``
.. versionadded:: 0.7
``PROPAGATE_EXCEPTIONS``, ``PRESERVE_CONTEXT_ON_EXCEPTION``
.. versionadded:: 0.8
``TRAP_BAD_REQUEST_ERRORS``, ``TRAP_HTTP_EXCEPTIONS``,
``APPLICATION_ROOT``, ``SESSION_COOKIE_DOMAIN``,
``SESSION_COOKIE_PATH``, ``SESSION_COOKIE_HTTPONLY``,
``SESSION_COOKIE_SECURE``
.. versionadded:: 0.9
``PREFERRED_URL_SCHEME``
.. versionadded:: 0.10
``JSON_AS_ASCII``, ``JSON_SORT_KEYS``, ``JSONIFY_PRETTYPRINT_REGULAR``
.. versionadded:: 0.11
``SESSION_REFRESH_EACH_REQUEST``, ``TEMPLATES_AUTO_RELOAD``,
``LOGGER_HANDLER_POLICY``, ``EXPLAIN_TEMPLATE_LOADING``
.. versionchanged:: 1.0
``LOGGER_NAME`` and ``LOGGER_HANDLER_POLICY`` were removed. See
:doc:`/logging` for information about configuration.
Added :data:`ENV` to reflect the :envvar:`FLASK_ENV` environment
variable.
Added :data:`SESSION_COOKIE_SAMESITE` to control the session
cookie's ``SameSite`` option.
Added :data:`MAX_COOKIE_SIZE` to control a warning from Werkzeug.
.. versionchanged:: 2.2
Removed ``PRESERVE_CONTEXT_ON_EXCEPTION``.
.. versionchanged:: 2.3
``JSON_AS_ASCII``, ``JSON_SORT_KEYS``, ``JSONIFY_MIMETYPE``, and
``JSONIFY_PRETTYPRINT_REGULAR`` were removed. The default ``app.json`` provider has
equivalent attributes instead.
.. versionchanged:: 2.3
``ENV`` was removed.
.. versionadded:: 3.1
Added :data:`PROVIDE_AUTOMATIC_OPTIONS` to control the default
addition of autogenerated OPTIONS responses.
Configuring from Python Files
-----------------------------
Configuration becomes more useful if you can store it in a separate file, ideally
located outside the actual application package. You can deploy your application, then
separately configure it for the specific deployment.
A common pattern is this::
app = Flask(__name__) app = Flask(__name__)
app.config.from_object('yourapplication.default_settings') app.config.from_object('yourapplication.default_settings')
app.config.from_envvar('YOURAPPLICATION_SETTINGS') app.config.from_envvar('YOURAPPLICATION_SETTINGS')
This first loads the configuration from the What this does is first loading the configuration from the
`yourapplication.default_settings` module and then overrides the values `yourapplication.default_settings` module and then overrides the values
with the contents of the file the :envvar:`YOURAPPLICATION_SETTINGS` with the contents of the file the :envvar:`YOURAPPLICATION_SETTINGS`
environment variable points to. This environment variable can be set environment variable points to. This environment variable can be set on
in the shell before starting the server: Linux or OS X with the export command in the shell before starting the
server::
.. tabs:: $ export YOURAPPLICATION_SETTINGS=/path/to/settings.cfg
$ python run-app.py
* Running on http://127.0.0.1:5000/
* Restarting with reloader...
.. group-tab:: Bash On Windows systems use the `set` builtin instead::
.. code-block:: text >set YOURAPPLICATION_SETTINGS=\path\to\settings.cfg
$ export YOURAPPLICATION_SETTINGS=/path/to/settings.cfg
$ flask run
* Running on http://127.0.0.1:5000/
.. group-tab:: Fish
.. code-block:: text
$ set -x YOURAPPLICATION_SETTINGS /path/to/settings.cfg
$ flask run
* Running on http://127.0.0.1:5000/
.. group-tab:: CMD
.. code-block:: text
> set YOURAPPLICATION_SETTINGS=\path\to\settings.cfg
> flask run
* Running on http://127.0.0.1:5000/
.. group-tab:: Powershell
.. code-block:: text
> $env:YOURAPPLICATION_SETTINGS = "\path\to\settings.cfg"
> flask run
* Running on http://127.0.0.1:5000/
The configuration files themselves are actual Python files. Only values The configuration files themselves are actual Python files. Only values
in uppercase are actually stored in the config object later on. So make in uppercase are actually stored in the config object later on. So make
sure to use uppercase letters for your config keys. sure to use uppercase letters for your config keys.
Here is an example of a configuration file:: Here an example configuration file::
# Example configuration DEBUG = False
SECRET_KEY = '192b9bdd22ab9ed4d12e236c78afcb9a393ec15f71bbf5dc987d54727823bcbf' SECRET_KEY = '?\xbf,\xb4\x8d\xa3"<\x9c\xb0@\x0f5\xab,w\xee\x8d$0\x13\x8b83'
Make sure to load the configuration very early on, so that extensions have Make sure to load the configuration very early on so that extensions have
the ability to access the configuration when starting up. There are other the ability to access the configuration when starting up. There are other
methods on the config object as well to load from individual files. For a methods on the config object as well to load from individual files. For a
complete reference, read the :class:`~flask.Config` object's complete reference, read the :class:`~flask.Config` object's
documentation. documentation.
Configuring from Data Files
---------------------------
It is also possible to load configuration from a file in a format of
your choice using :meth:`~flask.Config.from_file`. For example to load
from a TOML file:
.. code-block:: python
import tomllib
app.config.from_file("config.toml", load=tomllib.load, text=False)
Or from a JSON file:
.. code-block:: python
import json
app.config.from_file("config.json", load=json.load)
Configuring from Environment Variables
--------------------------------------
In addition to pointing to configuration files using environment
variables, you may find it useful (or necessary) to control your
configuration values directly from the environment. Flask can be
instructed to load all environment variables starting with a specific
prefix into the config using :meth:`~flask.Config.from_prefixed_env`.
Environment variables can be set in the shell before starting the
server:
.. tabs::
.. group-tab:: Bash
.. code-block:: text
$ export FLASK_SECRET_KEY="5f352379324c22463451387a0aec5d2f"
$ export FLASK_MAIL_ENABLED=false
$ flask run
* Running on http://127.0.0.1:5000/
.. group-tab:: Fish
.. code-block:: text
$ set -x FLASK_SECRET_KEY "5f352379324c22463451387a0aec5d2f"
$ set -x FLASK_MAIL_ENABLED false
$ flask run
* Running on http://127.0.0.1:5000/
.. group-tab:: CMD
.. code-block:: text
> set FLASK_SECRET_KEY="5f352379324c22463451387a0aec5d2f"
> set FLASK_MAIL_ENABLED=false
> flask run
* Running on http://127.0.0.1:5000/
.. group-tab:: Powershell
.. code-block:: text
> $env:FLASK_SECRET_KEY = "5f352379324c22463451387a0aec5d2f"
> $env:FLASK_MAIL_ENABLED = "false"
> flask run
* Running on http://127.0.0.1:5000/
The variables can then be loaded and accessed via the config with a key
equal to the environment variable name without the prefix i.e.
.. code-block:: python
app.config.from_prefixed_env()
app.config["SECRET_KEY"] # Is "5f352379324c22463451387a0aec5d2f"
The prefix is ``FLASK_`` by default. This is configurable via the
``prefix`` argument of :meth:`~flask.Config.from_prefixed_env`.
Values will be parsed to attempt to convert them to a more specific type
than strings. By default :func:`json.loads` is used, so any valid JSON
value is possible, including lists and dicts. This is configurable via
the ``loads`` argument of :meth:`~flask.Config.from_prefixed_env`.
When adding a boolean value with the default JSON parsing, only "true"
and "false", lowercase, are valid values. Keep in mind that any
non-empty string is considered ``True`` by Python.
It is possible to set keys in nested dictionaries by separating the
keys with double underscore (``__``). Any intermediate keys that don't
exist on the parent dict will be initialized to an empty dict.
.. code-block:: text
$ export FLASK_MYAPI__credentials__username=user123
.. code-block:: python
app.config["MYAPI"]["credentials"]["username"] # Is "user123"
On Windows, environment variable keys are always uppercase, therefore
the above example would end up as ``MYAPI__CREDENTIALS__USERNAME``.
For even more config loading features, including merging and
case-insensitive Windows support, try a dedicated library such as
Dynaconf_, which includes integration with Flask.
.. _Dynaconf: https://www.dynaconf.com/
Configuration Best Practices Configuration Best Practices
---------------------------- ----------------------------
The downside with the approach mentioned earlier is that it makes testing The downside with the approach mentioned earlier is that it makes testing
a little harder. There is no single 100% solution for this problem in a little harder. There is no one 100% solution for this problem in
general, but there are a couple of things you can keep in mind to improve general, but there are a couple of things you can do to improve that
that experience: experience:
1. Create your application in a function and register blueprints on it. 1. create your application in a function and register modules on it.
That way you can create multiple instances of your application with That way you can create multiple instances of your application with
different configurations attached which makes unit testing a lot different configurations attached which makes unittesting a lot
easier. You can use this to pass in configuration as needed. easier. You can use this to pass in configuration as needed.
2. Do not write code that needs the configuration at import time. If you 2. Do not write code that needs the configuration at import time. If you
limit yourself to request-only accesses to the configuration you can limit yourself to request-only accesses to the configuration you can
reconfigure the object later on as needed. reconfigure the object later on as needed.
3. Make sure to load the configuration very early on, so that
extensions can access the configuration when calling ``init_app``.
.. _config-dev-prod:
Development / Production
------------------------
Most applications need more than one configuration. There should be at
least separate configurations for the production server and the one used
during development. The easiest way to handle this is to use a default
configuration that is always loaded and part of the version control, and a
separate configuration that overrides the values as necessary as mentioned
in the example above::
app = Flask(__name__)
app.config.from_object('yourapplication.default_settings')
app.config.from_envvar('YOURAPPLICATION_SETTINGS')
Then you just have to add a separate :file:`config.py` file and export
``YOURAPPLICATION_SETTINGS=/path/to/config.py`` and you are done. However
there are alternative ways as well. For example you could use imports or
subclassing.
What is very popular in the Django world is to make the import explicit in
the config file by adding ``from yourapplication.default_settings
import *`` to the top of the file and then overriding the changes by hand.
You could also inspect an environment variable like
``YOURAPPLICATION_MODE`` and set that to `production`, `development` etc
and import different hard-coded files based on that.
An interesting pattern is also to use classes and inheritance for
configuration::
class Config(object):
TESTING = False
class ProductionConfig(Config):
DATABASE_URI = 'mysql://user@localhost/foo'
class DevelopmentConfig(Config):
DATABASE_URI = "sqlite:////tmp/foo.db"
class TestingConfig(Config):
DATABASE_URI = 'sqlite:///:memory:'
TESTING = True
To enable such a config you just have to call into
:meth:`~flask.Config.from_object`::
app.config.from_object('configmodule.ProductionConfig')
Note that :meth:`~flask.Config.from_object` does not instantiate the class
object. If you need to instantiate the class, such as to access a property,
then you must do so before calling :meth:`~flask.Config.from_object`::
from configmodule import ProductionConfig
app.config.from_object(ProductionConfig())
# Alternatively, import via string:
from werkzeug.utils import import_string
cfg = import_string('configmodule.ProductionConfig')()
app.config.from_object(cfg)
Instantiating the configuration object allows you to use ``@property`` in
your configuration classes::
class Config(object):
"""Base config, uses staging database server."""
TESTING = False
DB_SERVER = '192.168.1.56'
@property
def DATABASE_URI(self): # Note: all caps
return f"mysql://user@{self.DB_SERVER}/foo"
class ProductionConfig(Config):
"""Uses production database server."""
DB_SERVER = '192.168.19.32'
class DevelopmentConfig(Config):
DB_SERVER = 'localhost'
class TestingConfig(Config):
DB_SERVER = 'localhost'
DATABASE_URI = 'sqlite:///:memory:'
There are many different ways and it's up to you how you want to manage
your configuration files. However here a list of good recommendations:
- Keep a default configuration in version control. Either populate the
config with this default configuration or import it in your own
configuration files before overriding values.
- Use an environment variable to switch between the configurations.
This can be done from outside the Python interpreter and makes
development and deployment much easier because you can quickly and
easily switch between different configs without having to touch the
code at all. If you are working often on different projects you can
even create your own script for sourcing that activates a virtualenv
and exports the development configuration for you.
- Use a tool like `fabric`_ to push code and configuration separately
to the production server(s).
.. _fabric: https://www.fabfile.org/
.. _instance-folders:
Instance Folders
----------------
.. versionadded:: 0.8
Flask 0.8 introduces instance folders. Flask for a long time made it
possible to refer to paths relative to the application's folder directly
(via :attr:`Flask.root_path`). This was also how many developers loaded
configurations stored next to the application. Unfortunately however this
only works well if applications are not packages in which case the root
path refers to the contents of the package.
With Flask 0.8 a new attribute was introduced:
:attr:`Flask.instance_path`. It refers to a new concept called the
“instance folder”. The instance folder is designed to not be under
version control and be deployment specific. It's the perfect place to
drop things that either change at runtime or configuration files.
You can either explicitly provide the path of the instance folder when
creating the Flask application or you can let Flask autodetect the
instance folder. For explicit configuration use the `instance_path`
parameter::
app = Flask(__name__, instance_path='/path/to/instance/folder')
Please keep in mind that this path *must* be absolute when provided.
If the `instance_path` parameter is not provided the following default
locations are used:
- Uninstalled module::
/myapp.py
/instance
- Uninstalled package::
/myapp
/__init__.py
/instance
- Installed module or package::
$PREFIX/lib/pythonX.Y/site-packages/myapp
$PREFIX/var/myapp-instance
``$PREFIX`` is the prefix of your Python installation. This can be
``/usr`` or the path to your virtualenv. You can print the value of
``sys.prefix`` to see what the prefix is set to.
Since the config object provided loading of configuration files from
relative filenames we made it possible to change the loading via filenames
to be relative to the instance path if wanted. The behavior of relative
paths in config files can be flipped between “relative to the application
root” (the default) to “relative to instance folder” via the
`instance_relative_config` switch to the application constructor::
app = Flask(__name__, instance_relative_config=True)
Here is a full example of how to configure Flask to preload the config
from a module and then override the config from a file in the instance
folder if it exists::
app = Flask(__name__, instance_relative_config=True)
app.config.from_object('yourapplication.default_settings')
app.config.from_pyfile('application.cfg', silent=True)
The path to the instance folder can be found via the
:attr:`Flask.instance_path`. Flask also provides a shortcut to open a
file from the instance folder with :meth:`Flask.open_instance_resource`.
Example usage for both::
filename = os.path.join(app.instance_path, 'application.cfg')
with open(filename) as f:
config = f.read()
# or via open_instance_resource:
with app.open_instance_resource('application.cfg') as f:
config = f.read()

45
docs/contents.rst.inc Normal file
View file

@ -0,0 +1,45 @@
User's Guide
------------
This part of the documentation is written text and should give you an idea
how to work with Flask. It's a series of step-by-step instructions for
web development.
.. toctree::
:maxdepth: 2
foreword
installation
quickstart
tutorial/index
testing
errorhandling
config
shell
patterns/index
deploying/index
becomingbig
API Reference
-------------
If you are looking for information on a specific function, class or
method, this part of the documentation is for you.
.. toctree::
:maxdepth: 2
api
Additional Notes
----------------
Design notes, legal information and changelog are here for the interested.
.. toctree::
:maxdepth: 2
design
license
upgrading
changelog

8
docs/contributing.rst
View file

@ -1,8 +0,0 @@
Contributing
============
See the Pallets `detailed contributing documentation <contrib_>`_ for many ways
to contribute, including reporting issues, requesting features, asking or
answering questions, and making PRs.
.. _contrib: https://palletsprojects.com/contributing/

99
docs/debugging.rst
View file

@ -1,99 +0,0 @@
Debugging Application Errors
============================
In Production
-------------
**Do not run the development server, or enable the built-in debugger, in
a production environment.** The debugger allows executing arbitrary
Python code from the browser. It's protected by a pin, but that should
not be relied on for security.
Use an error logging tool, such as Sentry, as described in
:ref:`error-logging-tools`, or enable logging and notifications as
described in :doc:`/logging`.
If you have access to the server, you could add some code to start an
external debugger if ``request.remote_addr`` matches your IP. Some IDE
debuggers also have a remote mode so breakpoints on the server can be
interacted with locally. Only enable a debugger temporarily.
The Built-In Debugger
---------------------
The built-in Werkzeug development server provides a debugger which shows
an interactive traceback in the browser when an unhandled error occurs
during a request. This debugger should only be used during development.
.. image:: _static/debugger.png
:align: center
:class: screenshot
:alt: screenshot of debugger in action
.. warning::
The debugger allows executing arbitrary Python code from the
browser. It is protected by a pin, but still represents a major
security risk. Do not run the development server or debugger in a
production environment.
The debugger is enabled by default when the development server is run in debug mode.
.. code-block:: text
$ flask --app hello run --debug
When running from Python code, passing ``debug=True`` enables debug mode, which is
mostly equivalent.
.. code-block:: python
app.run(debug=True)
:doc:`/server` and :doc:`/cli` have more information about running the debugger and
debug mode. More information about the debugger can be found in the `Werkzeug
documentation <https://werkzeug.palletsprojects.com/debug/>`__.
External Debuggers
------------------
External debuggers, such as those provided by IDEs, can offer a more
powerful debugging experience than the built-in debugger. They can also
be used to step through code during a request before an error is raised,
or if no error is raised. Some even have a remote mode so you can debug
code running on another machine.
When using an external debugger, the app should still be in debug mode, otherwise Flask
turns unhandled errors into generic 500 error pages. However, the built-in debugger and
reloader should be disabled so they don't interfere with the external debugger.
.. code-block:: text
$ flask --app hello run --debug --no-debugger --no-reload
When running from Python:
.. code-block:: python
app.run(debug=True, use_debugger=False, use_reloader=False)
Disabling these isn't required, an external debugger will continue to work with the
following caveats.
- If the built-in debugger is not disabled, it will catch unhandled exceptions before
the external debugger can.
- If the reloader is not disabled, it could cause an unexpected reload if code changes
during a breakpoint.
- The development server will still catch unhandled exceptions if the built-in
debugger is disabled, otherwise it would crash on any error. If you want that (and
usually you don't) pass ``passthrough_errors=True`` to ``app.run``.
.. code-block:: python
app.run(
debug=True, passthrough_errors=True,
use_debugger=False, use_reloader=False
)

66
docs/deploying/apache-httpd.rst
View file

@ -1,66 +0,0 @@
Apache httpd
============
`Apache httpd`_ is a fast, production level HTTP server. When serving
your application with one of the WSGI servers listed in :doc:`index`, it
is often good or necessary to put a dedicated HTTP server in front of
it. This "reverse proxy" can handle incoming requests, TLS, and other
security and performance concerns better than the WSGI server.
httpd can be installed using your system package manager, or a pre-built
executable for Windows. Installing and running httpd itself is outside
the scope of this doc. This page outlines the basics of configuring
httpd to proxy your application. Be sure to read its documentation to
understand what features are available.
.. _Apache httpd: https://httpd.apache.org/
Domain Name
-----------
Acquiring and configuring a domain name is outside the scope of this
doc. In general, you will buy a domain name from a registrar, pay for
server space with a hosting provider, and then point your registrar
at the hosting provider's name servers.
To simulate this, you can also edit your ``hosts`` file, located at
``/etc/hosts`` on Linux. Add a line that associates a name with the
local IP.
Modern Linux systems may be configured to treat any domain name that
ends with ``.localhost`` like this without adding it to the ``hosts``
file.
.. code-block:: python
:caption: ``/etc/hosts``
127.0.0.1 hello.localhost
Configuration
-------------
The httpd configuration is located at ``/etc/httpd/conf/httpd.conf`` on
Linux. It may be different depending on your operating system. Check the
docs and look for ``httpd.conf``.
Remove or comment out any existing ``DocumentRoot`` directive. Add the
config lines below. We'll assume the WSGI server is listening locally at
``http://127.0.0.1:8000``.
.. code-block:: apache
:caption: ``/etc/httpd/conf/httpd.conf``
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
ProxyPass / http://127.0.0.1:8000/
RequestHeader set X-Forwarded-Proto http
RequestHeader set X-Forwarded-Prefix /
The ``LoadModule`` lines might already exist. If so, make sure they are
uncommented instead of adding them manually.
Then :doc:`proxy_fix` so that your application uses the ``X-Forwarded``
headers. ``X-Forwarded-For`` and ``X-Forwarded-Host`` are automatically
set by ``ProxyPass``.

27
docs/deploying/asgi.rst
View file

@ -1,27 +0,0 @@
ASGI
====
If you'd like to use an ASGI server you will need to utilise WSGI to
ASGI middleware. The asgiref
`WsgiToAsgi <https://github.com/django/asgiref#wsgi-to-asgi-adapter>`_
adapter is recommended as it integrates with the event loop used for
Flask's :ref:`async_await` support. You can use the adapter by
wrapping the Flask app,
.. code-block:: python
from asgiref.wsgi import WsgiToAsgi
from flask import Flask
app = Flask(__name__)
...
asgi_app = WsgiToAsgi(app)
and then serving the ``asgi_app`` with the ASGI server, e.g. using
`Hypercorn <https://github.com/pgjones/hypercorn>`_,
.. sourcecode:: text
$ hypercorn module:asgi_app

50
docs/deploying/cgi.rst Normal file
View file

@ -0,0 +1,50 @@
CGI
===
If all other deployment methods do not work, CGI will work for sure. CGI
is supported by all major servers but usually has a less-than-optimal
performance.
This is also the way you can use a Flask application on Google's
`App Engine`_, there however the execution does happen in a CGI-like
environment. The application's performance is unaffected because of that.
.. admonition:: Watch Out
Please make sure in advance that your ``app.run()`` call you might
have in your application file, is inside an ``if __name__ ==
'__main__':`` or moved to a separate file. Just make sure it's not
called because this will always start a local WSGI server which we do
not want if we deploy that application to CGI / app engine.
.. _App Engine: http://code.google.com/appengine/
Creating a `.cgi` file
----------------------
First you need to create the CGI application file. Let's call it
`yourapplication.cgi`::
#!/usr/bin/python
from wsgiref.handlers import CGIHandler
from yourapplication import app
CGIHandler().run(app)
If you're running Python 2.4 you will need the :mod:`wsgiref` package. Python
2.5 and higher ship this as part of the standard library.
Server Setup
------------
Usually there are two ways to configure the server. Either just copy the
`.cgi` into a `cgi-bin` (and use `mod_rerwite` or something similar to
rewrite the URL) or let the server point to the file directly.
In Apache for example you can put a like like this into the config:
.. sourcecode:: apache
ScriptAlias /app /path/to/the/application.cgi
For more information consult the documentation of your webserver.

8
docs/deploying/eventlet.rst
View file

@ -1,8 +0,0 @@
:orphan:
eventlet
========
`Eventlet is no longer maintained.`__ Use :doc:`/deploying/gevent` instead.
__ https://eventlet.readthedocs.io

138
docs/deploying/fastcgi.rst Normal file
View file

@ -0,0 +1,138 @@
FastCGI
=======
A very popular deployment setup on servers like `lighttpd`_ and `nginx`_
is FastCGI. To use your WSGI application with any of them you will need
a FastCGI server first.
The most popular one is `flup`_ which we will use for this guide. Make
sure to have it installed.
.. admonition:: Watch Out
Please make sure in advance that your ``app.run()`` call you might
have in your application file, is inside an ``if __name__ ==
'__main__':`` or moved to a separate file. Just make sure it's not
called because this will always start a local WSGI server which we do
not want if we deploy that application to FastCGI.
Creating a `.fcgi` file
-----------------------
First you need to create the FastCGI server file. Let's call it
`yourapplication.fcgi`::
#!/usr/bin/python
from flup.server.fcgi import WSGIServer
from yourapplication import app
WSGIServer(app).run()
This is enough for Apache to work, however lighttpd and nginx need a
socket to communicate with the FastCGI server. For that to work you
need to pass the path to the socket to the
:class:`~flup.server.fcgi.WSGIServer`::
WSGIServer(application, bindAddress='/path/to/fcgi.sock').run()
The path has to be the exact same path you define in the server
config.
Save the `yourapplication.fcgi` file somewhere you will find it again.
It makes sense to have that in `/var/www/yourapplication` or something
similar.
Make sure to set the executable bit on that file so that the servers
can execute it:
.. sourcecode:: text
# chmod +x /var/www/yourapplication/yourapplication.fcgi
Configuring lighttpd
--------------------
A basic FastCGI configuration for lighttpd looks like that::
fastcgi.server = ("/yourapplication" =>
"yourapplication" => (
"socket" => "/tmp/yourapplication-fcgi.sock",
"bin-path" => "/var/www/yourapplication/yourapplication.fcgi",
"check-local" => "disable"
)
)
This configuration binds the application to `/yourapplication`. If you
want the application to work in the URL root you have to work around a
lighttpd bug with the :class:`~werkzeug.contrib.fixers.LighttpdCGIRootFix`
middleware.
Make sure to apply it only if you are mounting the application the URL
root.
Configuring nginx
-----------------
Installing FastCGI applications on nginx is a bit tricky because by default
some FastCGI parameters are not properly forwarded.
A basic FastCGI configuration for nginx looks like this::
location /yourapplication/ {
include fastcgi_params;
if ($uri ~ ^/yourapplication/(.*)?) {
set $path_url $1;
}
fastcgi_param PATH_INFO $path_url;
fastcgi_param SCRIPT_NAME /yourapplication;
fastcgi_pass unix:/tmp/yourapplication-fcgi.sock;
}
This configuration binds the application to `/yourapplication`. If you want
to have it in the URL root it's a bit easier because you don't have to figure
out how to calculate `PATH_INFO` and `SCRIPT_NAME`::
location /yourapplication/ {
include fastcgi_params;
fastcgi_param PATH_INFO $fastcgi_script_name;
fastcgi_param SCRIPT_NAME "";
fastcgi_pass unix:/tmp/yourapplication-fcgi.sock;
}
Since Nginx doesn't load FastCGI apps, you have to do it by yourself. You
can either write an `init.d` script for that or execute it inside a screen
session::
$ screen
$ /var/www/yourapplication/yourapplication.fcgi
Debugging
---------
FastCGI deployments tend to be hard to debug on most webservers. Very often the
only thing the server log tells you is something along the lines of "premature
end of headers". In order to debug the application the only thing that can
really give you ideas why it breaks is switching to the correct user and
executing the application by hand.
This example assumes your application is called `application.fcgi` and that your
webserver user is `www-data`::
$ su www-data
$ cd /var/www/yourapplication
$ python application.fcgi
Traceback (most recent call last):
File "yourapplication.fcg", line 4, in <module>
ImportError: No module named yourapplication
In this case the error seems to be "yourapplication" not being on the python
path. Common problems are:
- relative paths being used. Don't rely on the current working directory
- the code depending on environment variables that are not set by the
web server.
- different python interpreters being used.
.. _lighttpd: http://www.lighttpd.net/
.. _nginx: http://nginx.net/
.. _flup: http://trac.saddi.com/flup

76
docs/deploying/gevent.rst
View file

@ -1,76 +0,0 @@
gevent
======
Prefer using :doc:`gunicorn` or :doc:`uwsgi` with gevent workers rather
than using `gevent`_ directly. Gunicorn and uWSGI provide much more
configurable and production-tested servers.
`gevent`_ allows writing asynchronous, coroutine-based code that looks
like standard synchronous Python. It uses `greenlet`_ to enable task
switching without writing ``async/await`` or using ``asyncio``. This is
not the same as Python's ``async/await``, or the ASGI server spec.
gevent provides a WSGI server that can handle many connections at once
instead of one per worker process. See :doc:`/gevent` for more
information about enabling it in your application.
.. _gevent: https://www.gevent.org/
.. _greenlet: https://greenlet.readthedocs.io/en/latest/
Installing
----------
When using gevent, greenlet>=1.0 is required. When using PyPy,
PyPy>=7.3.7 is required.
Create a virtualenv, install your application, then install ``gevent``.
.. code-block:: text
$ cd hello-app
$ python -m venv .venv
$ . .venv/bin/activate
$ pip install . # install your application
$ pip install gevent
Running
-------
To use gevent to serve your application, write a script that imports its
``WSGIServer``, as well as your app or app factory.
.. code-block:: python
:caption: ``wsgi.py``
from gevent.pywsgi import WSGIServer
from hello import create_app
app = create_app()
http_server = WSGIServer(("127.0.0.1", 8000), app)
http_server.serve_forever()
.. code-block:: text
$ python wsgi.py
No output is shown when the server starts.
Binding Externally
------------------
gevent should not be run as root because it would cause your
application code to run as root, which is not secure. However, this
means it will not be possible to bind to port 80 or 443. Instead, a
reverse proxy such as :doc:`nginx` or :doc:`apache-httpd` should be used
in front of gevent.
You can bind to all external IPs on a non-privileged port by using
``0.0.0.0`` in the server arguments shown in the previous section. Don't
do this when using a reverse proxy setup, otherwise it will be possible
to bypass the proxy.
``0.0.0.0`` is not a valid address to navigate to, you'd use a specific
IP address in your browser.

116
docs/deploying/gunicorn.rst
View file

@ -1,116 +0,0 @@
Gunicorn
========
`Gunicorn`_ is a pure Python WSGI server with simple configuration and
multiple worker implementations for performance tuning.
* It tends to integrate easily with hosting platforms.
* It does not support Windows (but does run on WSL).
* It is easy to install as it does not require additional dependencies
or compilation.
* It has built-in async worker support using gevent.
This page outlines the basics of running Gunicorn. Be sure to read its
`documentation`_ and use ``gunicorn --help`` to understand what features
are available.
.. _Gunicorn: https://gunicorn.org/
.. _documentation: https://docs.gunicorn.org/
Installing
----------
Gunicorn is easy to install, as it does not require external
dependencies or compilation. It runs on Windows only under WSL.
Create a virtualenv, install your application, then install
``gunicorn``.
.. code-block:: text
$ cd hello-app
$ python -m venv .venv
$ . .venv/bin/activate
$ pip install . # install your application
$ pip install gunicorn
Running
-------
The only required argument to Gunicorn tells it how to load your Flask
application. The syntax is ``{module_import}:{app_variable}``.
``module_import`` is the dotted import name to the module with your
application. ``app_variable`` is the variable with the application. It
can also be a function call (with any arguments) if you're using the
app factory pattern.
.. code-block:: text
# equivalent to 'from hello import app'
$ gunicorn -w 4 'hello:app'
# equivalent to 'from hello import create_app; create_app()'
$ gunicorn -w 4 'hello:create_app()'
Starting gunicorn 20.1.0
Listening at: http://127.0.0.1:8000 (x)
Using worker: sync
Booting worker with pid: x
Booting worker with pid: x
Booting worker with pid: x
Booting worker with pid: x
The ``-w`` option specifies the number of processes to run; a starting
value could be ``CPU * 2``. The default is only 1 worker, which is
probably not what you want for the default worker type.
Logs for each request aren't shown by default, only worker info and
errors are shown. To show access logs on stdout, use the
``--access-logfile=-`` option.
Binding Externally
------------------
Gunicorn should not be run as root because it would cause your
application code to run as root, which is not secure. However, this
means it will not be possible to bind to port 80 or 443. Instead, a
reverse proxy such as :doc:`nginx` or :doc:`apache-httpd` should be used
in front of Gunicorn.
You can bind to all external IPs on a non-privileged port using the
``-b 0.0.0.0`` option. Don't do this when using a reverse proxy setup,
otherwise it will be possible to bypass the proxy.
.. code-block:: text
$ gunicorn -w 4 -b 0.0.0.0 'hello:create_app()'
Listening at: http://0.0.0.0:8000 (x)
``0.0.0.0`` is not a valid address to navigate to, you'd use a specific
IP address in your browser.
Async with gevent
-----------------
The default sync worker is appropriate for most use cases. If you need numerous,
long running, concurrent connections, Gunicorn provides an asynchronous worker
using `gevent`_. This is not the same as Python's ``async/await``, or the ASGI
server spec. See :doc:`/gevent` for more information about enabling it in your
application.
.. _gevent: https://www.gevent.org/
When using gevent, greenlet>=1.0 is required. When using PyPy, PyPy>=7.3.7 is
required.
.. code-block:: text
$ gunicorn -k gevent 'hello:create_app()'
Starting gunicorn 20.1.0
Listening at: http://127.0.0.1:8000 (x)
Using worker: gevent
Booting worker with pid: x

87
docs/deploying/index.rst
View file

@ -1,78 +1,19 @@
Deploying to Production Deployment Options
======================= ==================
After developing your application, you'll want to make it available Depending on what you have available there are multiple ways to run Flask
publicly to other users. When you're developing locally, you're probably applications. A very common method is to use the builtin server during
using the built-in development server, debugger, and reloader. These development and maybe behind a proxy for simple applications, but there
should not be used in production. Instead, you should use a dedicated are more options available.
WSGI server or hosting platform, some of which will be described here.
"Production" means "not development", which applies whether you're If you have a different WSGI server look up the server documentation about
serving your application publicly to millions of users or privately / how to use a WSGI app with it. Just remember that your application object
locally to a single user. **Do not use the development server when is the actual WSGI application.
deploying to production. It is intended for use only during local
development. It is not designed to be particularly secure, stable, or
efficient.**
Self-Hosted Options
-------------------
Flask is a WSGI *application*. A WSGI *server* is used to run the
application, converting incoming HTTP requests to the standard WSGI
environ, and converting outgoing WSGI responses to HTTP responses.
The primary goal of these docs is to familiarize you with the concepts
involved in running a WSGI application using a production WSGI server
and HTTP server. There are many WSGI servers and HTTP servers, with many
configuration possibilities. The pages below discuss the most common
servers, and show the basics of running each one. The next section
discusses platforms that can manage this for you.
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 2
gunicorn mod_wsgi
waitress cgi
mod_wsgi fastcgi
uwsgi others
gevent
asgi
WSGI servers have HTTP servers built-in. However, a dedicated HTTP
server may be safer, more efficient, or more capable. Putting an HTTP
server in front of the WSGI server is called a "reverse proxy."
.. toctree::
:maxdepth: 1
proxy_fix
nginx
apache-httpd
This list is not exhaustive, and you should evaluate these and other
servers based on your application's needs. Different servers will have
different capabilities, configuration, and support.
Hosting Platforms
-----------------
There are many services available for hosting web applications without
needing to maintain your own server, networking, domain, etc. Some
services may have a free tier up to a certain time or bandwidth. Many of
these services use one of the WSGI servers described above, or a similar
interface. The links below are for some of the most common platforms,
which have instructions for Flask, WSGI, or Python.
- `PythonAnywhere <https://help.pythonanywhere.com/pages/Flask/>`_
- `Google App Engine <https://cloud.google.com/appengine/docs/standard/python3/building-app>`_
- `Google Cloud Run <https://cloud.google.com/run/docs/quickstarts/build-and-deploy/deploy-python-service>`_
- `AWS Elastic Beanstalk <https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create-deploy-python-flask.html>`_
- `Microsoft Azure <https://docs.microsoft.com/en-us/azure/app-service/quickstart-python>`_
This list is not exhaustive, and you should evaluate these and other
services based on your application's needs. Different services will have
different capabilities, configuration, pricing, and support.
You'll probably need to :doc:`proxy_fix` when using most hosting
platforms.

175
docs/deploying/mod_wsgi.rst
View file

@ -1,94 +1,135 @@
mod_wsgi mod_wsgi (Apache)
======== =================
`mod_wsgi`_ is a WSGI server integrated with the `Apache httpd`_ server. If you are using the `Apache`_ webserver you should consider using `mod_wsgi`_.
The modern `mod_wsgi-express`_ command makes it easy to configure and
start the server without needing to write Apache httpd configuration.
* Tightly integrated with Apache httpd. .. admonition:: Watch Out
* Supports Windows directly.
* Requires a compiler and the Apache development headers to install.
* Does not require a reverse proxy setup.
This page outlines the basics of running mod_wsgi-express, not the more Please make sure in advance that your ``app.run()`` call you might
complex installation and configuration with httpd. Be sure to read the have in your application file, is inside an ``if __name__ ==
`mod_wsgi-express`_, `mod_wsgi`_, and `Apache httpd`_ documentation to '__main__':`` or moved to a separate file. Just make sure it's not
understand what features are available. called because this will always start a local WSGI server which we do
not want if we deploy that application to mod_wsgi.
.. _mod_wsgi-express: https://pypi.org/project/mod-wsgi/ .. _Apache: http://httpd.apache.org/
.. _mod_wsgi: https://modwsgi.readthedocs.io/
.. _Apache httpd: https://httpd.apache.org/
Installing `mod_wsgi`
---------------------
Installing If you don't have `mod_wsgi` installed yet you have to either install it using
---------- a package manager or compile it yourself.
Installing mod_wsgi requires a compiler and the Apache server and The mod_wsgi `installation instructions`_ cover source installations on UNIX
development headers installed. You will get an error if they are not. systems.
How to install them depends on the OS and package manager that you use.
Create a virtualenv, install your application, then install If you are using ubuntu / debian you can apt-get it and activate it as follows:
``mod_wsgi``.
.. code-block:: text .. sourcecode:: text
$ cd hello-app # apt-get install libapache2-mod-wsgi
$ python -m venv .venv
$ . .venv/bin/activate
$ pip install . # install your application
$ pip install mod_wsgi
On FreeBSD install `mod_wsgi` by compiling the `www/mod_wsgi` port or by using
pkg_add:
Running .. sourcecode:: text
-------
The only argument to ``mod_wsgi-express`` specifies a script containing # pkg_add -r mod_wsgi
your Flask application, which must be called ``application``. You can
write a small script to import your app with this name, or to create it
if using the app factory pattern.
.. code-block:: python If you are using pkgsrc you can install `mod_wsgi` by compiling the
:caption: ``wsgi.py`` `www/ap2-wsgi` package.
from hello import app If you encounter segfaulting child processes after the first apache reload you
can safely ignore them. Just restart the server.
application = app Creating a `.wsgi` file
-----------------------
.. code-block:: python To run your application you need a `yourapplication.wsgi` file. This file
:caption: ``wsgi.py`` contains the code `mod_wsgi` is executing on startup to get the application
object. The object called `application` in that file is then used as
application.
from hello import create_app For most applications the following file should be sufficient::
application = create_app() from yourapplication import app as application
Now run the ``mod_wsgi-express start-server`` command. If you don't have a factory function for application creation but a singleton
instance you can directly import that one as `application`.
.. code-block:: text Store that file somewhere that you will find it again (e.g.:
`/var/www/yourapplication`) and make sure that `yourapplication` and all
the libraries that are in use are on the python load path. If you don't
want to install it system wide consider using a `virtual python`_ instance.
$ mod_wsgi-express start-server wsgi.py --processes 4 Configuring Apache
The ``--processes`` option specifies the number of worker processes to
run; a starting value could be ``CPU * 2``.
Logs for each request aren't show in the terminal. If an error occurs,
its information is written to the error log file shown when starting the
server.
Binding Externally
------------------ ------------------
Unlike the other WSGI servers in these docs, mod_wsgi can be run as The last thing you have to do is to create an Apache configuration file for
root to bind to privileged ports like 80 and 443. However, it must be your application. In this example we are telling `mod_wsgi` to execute the
configured to drop permissions to a different user and group for the application under a different user for security reasons:
worker processes.
For example, if you created a ``hello`` user and group, you should .. sourcecode:: apache
install your virtualenv and application as that user, then tell
mod_wsgi to drop to that user after starting.
.. code-block:: text <VirtualHost *>
ServerName example.com
$ sudo /home/hello/.venv/bin/mod_wsgi-express start-server \ WSGIDaemonProcess yourapplication user=user1 group=group1 threads=5
/home/hello/wsgi.py \ WSGIScriptAlias / /var/www/yourapplication/yourapplication.wsgi
--user hello --group hello --port 80 --processes 4
<Directory /var/www/yourapplication>
WSGIProcessGroup yourapplication
WSGIApplicationGroup %{GLOBAL}
Order deny,allow
Allow from all
</Directory>
</VirtualHost>
For more information consult the `mod_wsgi wiki`_.
.. _mod_wsgi: http://code.google.com/p/modwsgi/
.. _installation instructions: http://code.google.com/p/modwsgi/wiki/QuickInstallationGuide
.. _virtual python: http://pypi.python.org/pypi/virtualenv
.. _mod_wsgi wiki: http://code.google.com/p/modwsgi/wiki/
Toubleshooting
--------------
If your application does not run, follow this guide to troubleshoot:
**Problem:** Application does not run, errorlog shows SystemExit ignored
You have a ``app.run()`` call in your application file that is not
guarded by an ``if __name__ == '__main__':`` condition. Either remove
that :meth:`~flask.Flask.run` call from the file and move it into a
separate `run.py` file or put it into such an if block.
**Problem:** application gives permission errors
Probably caused by your application running as the wrong user. Make
sure the folders the application needs access to have the proper
privileges set and the application runs as the correct user (``user``
and ``group`` parameter to the `WSGIDaemonProcess` directive)
**Problem:** application dies with an error on print
Keep in mind that mod_wsgi disallows doing anything with
:data:`sys.stdout` and :data:`sys.stderr`. You can disable this
protection from the config by setting the `WSGIRestrictStdout` to
``off``:
.. sourcecode:: apache
WSGIRestrictStdout Off
Alternatively you can also replace the standard out in the .wsgi file
with a different stream::
import sys
sys.stdout = sys.stderr
**Problem:** accessing resources gives IO errors
Your application probably is a single .py file you symlinked into the
site-packages folder. Please be aware that this does not work,
instead you either have to put the folder into the pythonpath the file
is stored in, or convert your application into a package.
The reason for this is that for non-installed Packages, the module
filename is used to locate the resources and for symlinks the wrong
filename is picked up.

69
docs/deploying/nginx.rst
View file

@ -1,69 +0,0 @@
nginx
=====
`nginx`_ is a fast, production level HTTP server. When serving your
application with one of the WSGI servers listed in :doc:`index`, it is
often good or necessary to put a dedicated HTTP server in front of it.
This "reverse proxy" can handle incoming requests, TLS, and other
security and performance concerns better than the WSGI server.
Nginx can be installed using your system package manager, or a pre-built
executable for Windows. Installing and running Nginx itself is outside
the scope of this doc. This page outlines the basics of configuring
Nginx to proxy your application. Be sure to read its documentation to
understand what features are available.
.. _nginx: https://nginx.org/
Domain Name
-----------
Acquiring and configuring a domain name is outside the scope of this
doc. In general, you will buy a domain name from a registrar, pay for
server space with a hosting provider, and then point your registrar
at the hosting provider's name servers.
To simulate this, you can also edit your ``hosts`` file, located at
``/etc/hosts`` on Linux. Add a line that associates a name with the
local IP.
Modern Linux systems may be configured to treat any domain name that
ends with ``.localhost`` like this without adding it to the ``hosts``
file.
.. code-block:: python
:caption: ``/etc/hosts``
127.0.0.1 hello.localhost
Configuration
-------------
The nginx configuration is located at ``/etc/nginx/nginx.conf`` on
Linux. It may be different depending on your operating system. Check the
docs and look for ``nginx.conf``.
Remove or comment out any existing ``server`` section. Add a ``server``
section and use the ``proxy_pass`` directive to point to the address the
WSGI server is listening on. We'll assume the WSGI server is listening
locally at ``http://127.0.0.1:8000``.
.. code-block:: nginx
:caption: ``/etc/nginx.conf``
server {
listen 80;
server_name _;
location / {
proxy_pass http://127.0.0.1:8000/;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Prefix /;
}
}
Then :doc:`proxy_fix` so that your application uses these headers.

63
docs/deploying/others.rst Normal file
View file

@ -0,0 +1,63 @@
Other Servers
=============
There are popular servers written in Python that allow the execution of
WSGI applications as well. Keep in mind though that some of these servers
were written for very specific applications and might not work as well for
standard WSGI application such as Flask powered ones.
Tornado
--------
`Tornado`_ is an open source version of the scalable, non-blocking web
server and tools that power `FriendFeed`_. Because it is non-blocking and
uses epoll, it can handle thousands of simultaneous standing connections,
which means it is ideal for real-time web services. Integrating this
service with Flask is a trivial task::
from tornado.wsgi import WSGIContainer
from tornado.httpserver import HTTPServer
from tornado.ioloop import IOLoop
from yourapplication import app
http_server = HTTPServer(WSGIContainer(app))
http_server.listen(5000)
IOLoop.instance().start()
.. _Tornado: http://www.tornadoweb.org/
.. _FriendFeed: http://friendfeed.com/
Gevent
-------
`Gevent`_ is a coroutine-based Python networking library that uses
`greenlet`_ to provide a high-level synchronous API on top of `libevent`_
event loop::
from gevent.wsgi import WSGIServer
from yourapplication import app
http_server = WSGIServer(('', 5000), app)
http_server.serve_forever()
.. _Gevent: http://www.gevent.org/
.. _greenlet: http://codespeak.net/py/0.9.2/greenlet.html
.. _libevent: http://monkey.org/~provos/libevent/
Gunicorn
--------
`Gunicorn`_ 'Green Unicorn' is a WSGI HTTP Server for UNIX. It's a pre-fork
worker model ported from Ruby's Unicorn project. It supports both `eventlet`_
and `greenlet`_. Running a Flask application on this server is quite simple::
gunicorn myproject:app
.. _Gunicorn: http://gunicorn.org/
.. _eventlet: http://eventlet.net/
.. _greenlet: http://codespeak.net/py/0.9.2/greenlet.html

33
docs/deploying/proxy_fix.rst
View file

@ -1,33 +0,0 @@
Tell Flask it is Behind a Proxy
===============================
When using a reverse proxy, or many Python hosting platforms, the proxy
will intercept and forward all external requests to the local WSGI
server.
From the WSGI server and Flask application's perspectives, requests are
now coming from the HTTP server to the local address, rather than from
the remote address to the external server address.
HTTP servers should set ``X-Forwarded-`` headers to pass on the real
values to the application. The application can then be told to trust and
use those values by wrapping it with the
:doc:`werkzeug:middleware/proxy_fix` middleware provided by Werkzeug.
This middleware should only be used if the application is actually
behind a proxy, and should be configured with the number of proxies that
are chained in front of it. Not all proxies set all the headers. Since
incoming headers can be faked, you must set how many proxies are setting
each header so the middleware knows what to trust.
.. code-block:: python
from werkzeug.middleware.proxy_fix import ProxyFix
app.wsgi_app = ProxyFix(
app.wsgi_app, x_for=1, x_proto=1, x_host=1, x_prefix=1
)
Remember, only apply this middleware if you are behind a proxy, and set
the correct number of proxies that set each header. It can be a security
issue if you get this configuration wrong.

143
docs/deploying/uwsgi.rst
View file

@ -1,143 +0,0 @@
uWSGI
=====
`uWSGI`_ is a fast, compiled server suite with extensive configuration
and capabilities beyond a basic server.
* It can be very performant due to being a compiled program.
* It is complex to configure beyond the basic application, and has so
many options that it can be difficult for beginners to understand.
* It does not support Windows (but does run on WSL).
* It requires a compiler to install in some cases.
This page outlines the basics of running uWSGI. Be sure to read its
documentation to understand what features are available.
.. _uWSGI: https://uwsgi-docs.readthedocs.io/en/latest/
Installing
----------
uWSGI has multiple ways to install it. The most straightforward is to
install the ``pyuwsgi`` package, which provides precompiled wheels for
common platforms. However, it does not provide SSL support, which can be
provided with a reverse proxy instead.
Create a virtualenv, install your application, then install ``pyuwsgi``.
.. code-block:: text
$ cd hello-app
$ python -m venv .venv
$ . .venv/bin/activate
$ pip install . # install your application
$ pip install pyuwsgi
If you have a compiler available, you can install the ``uwsgi`` package
instead. Or install the ``pyuwsgi`` package from sdist instead of wheel.
Either method will include SSL support.
.. code-block:: text
$ pip install uwsgi
# or
$ pip install --no-binary pyuwsgi pyuwsgi
Running
-------
The most basic way to run uWSGI is to tell it to start an HTTP server
and import your application.
.. code-block:: text
$ uwsgi --http 127.0.0.1:8000 --master -p 4 -w hello:app
*** Starting uWSGI 2.0.20 (64bit) on [x] ***
*** Operational MODE: preforking ***
mounting hello:app on /
spawned uWSGI master process (pid: x)
spawned uWSGI worker 1 (pid: x, cores: 1)
spawned uWSGI worker 2 (pid: x, cores: 1)
spawned uWSGI worker 3 (pid: x, cores: 1)
spawned uWSGI worker 4 (pid: x, cores: 1)
spawned uWSGI http 1 (pid: x)
If you're using the app factory pattern, you'll need to create a small
Python file to create the app, then point uWSGI at that.
.. code-block:: python
:caption: ``wsgi.py``
from hello import create_app
app = create_app()
.. code-block:: text
$ uwsgi --http 127.0.0.1:8000 --master -p 4 -w wsgi:app
The ``--http`` option starts an HTTP server at 127.0.0.1 port 8000. The
``--master`` option specifies the standard worker manager. The ``-p``
option starts 4 worker processes; a starting value could be ``CPU * 2``.
The ``-w`` option tells uWSGI how to import your application
Binding Externally
------------------
uWSGI should not be run as root with the configuration shown in this doc
because it would cause your application code to run as root, which is
not secure. However, this means it will not be possible to bind to port
80 or 443. Instead, a reverse proxy such as :doc:`nginx` or
:doc:`apache-httpd` should be used in front of uWSGI. It is possible to
run uWSGI as root securely, but that is beyond the scope of this doc.
uWSGI has optimized integration with `Nginx uWSGI`_ and
`Apache mod_proxy_uwsgi`_, and possibly other servers, instead of using
a standard HTTP proxy. That configuration is beyond the scope of this
doc, see the links for more information.
.. _Nginx uWSGI: https://uwsgi-docs.readthedocs.io/en/latest/Nginx.html
.. _Apache mod_proxy_uwsgi: https://uwsgi-docs.readthedocs.io/en/latest/Apache.html#mod-proxy-uwsgi
You can bind to all external IPs on a non-privileged port using the
``--http 0.0.0.0:8000`` option. Don't do this when using a reverse proxy
setup, otherwise it will be possible to bypass the proxy.
.. code-block:: text
$ uwsgi --http 0.0.0.0:8000 --master -p 4 -w wsgi:app
``0.0.0.0`` is not a valid address to navigate to, you'd use a specific
IP address in your browser.
Async with gevent
-----------------
The default sync worker is appropriate for most use cases. If you need numerous,
long running, concurrent connections, uWSGI provides an asynchronous worker
using `gevent`_. This is not the same as Python's ``async/await``, or the ASGI
server spec. See :doc:`/gevent` for more information about enabling it in your
application.
.. _gevent: https://www.gevent.org/
When using gevent, greenlet>=1.0 is required. When using PyPy, PyPy>=7.3.7 is
required.
.. code-block:: text
$ uwsgi --http 127.0.0.1:8000 --master --gevent 100 -w wsgi:app
*** Starting uWSGI 2.0.20 (64bit) on [x] ***
*** Operational MODE: async ***
mounting hello:app on /
spawned uWSGI master process (pid: x)
spawned uWSGI worker 1 (pid: x, cores: 100)
spawned uWSGI http 1 (pid: x)
*** running gevent loop engine [addr:x] ***

75
docs/deploying/waitress.rst
View file

@ -1,75 +0,0 @@
Waitress
========
`Waitress`_ is a pure Python WSGI server.
* It is easy to configure.
* It supports Windows directly.
* It is easy to install as it does not require additional dependencies
or compilation.
* It does not support streaming requests, full request data is always
buffered.
* It uses a single process with multiple thread workers.
This page outlines the basics of running Waitress. Be sure to read its
documentation and ``waitress-serve --help`` to understand what features
are available.
.. _Waitress: https://docs.pylonsproject.org/projects/waitress/
Installing
----------
Create a virtualenv, install your application, then install
``waitress``.
.. code-block:: text
$ cd hello-app
$ python -m venv .venv
$ . .venv/bin/activate
$ pip install . # install your application
$ pip install waitress
Running
-------
The only required argument to ``waitress-serve`` tells it how to load
your Flask application. The syntax is ``{module}:{app}``. ``module`` is
the dotted import name to the module with your application. ``app`` is
the variable with the application. If you're using the app factory
pattern, use ``--call {module}:{factory}`` instead.
.. code-block:: text
# equivalent to 'from hello import app'
$ waitress-serve --host 127.0.0.1 hello:app
# equivalent to 'from hello import create_app; create_app()'
$ waitress-serve --host 127.0.0.1 --call hello:create_app
Serving on http://127.0.0.1:8080
The ``--host`` option binds the server to local ``127.0.0.1`` only.
Logs for each request aren't shown, only errors are shown. Logging can
be configured through the Python interface instead of the command line.
Binding Externally
------------------
Waitress should not be run as root because it would cause your
application code to run as root, which is not secure. However, this
means it will not be possible to bind to port 80 or 443. Instead, a
reverse proxy such as :doc:`nginx` or :doc:`apache-httpd` should be used
in front of Waitress.
You can bind to all external IPs on a non-privileged port by not
specifying the ``--host`` option. Don't do this when using a reverse
proxy setup, otherwise it will be possible to bypass the proxy.
``0.0.0.0`` is not a valid address to navigate to, you'd use a specific
IP address in your browser.

150
docs/design.rst
View file

@ -34,19 +34,19 @@ Would look like this instead::
return 'Hello World!' return 'Hello World!'
There are three major reasons for this. The most important one is that There are three major reasons for this. The most important one is that
implicit application objects require that there may only be one instance at implicit application objects require that there may only be one class at
the time. There are ways to fake multiple applications with a single the time. There are ways to fake multiple application with a single
application object, like maintaining a stack of applications, but this application object, like maintaining a stack of applications, but this
causes some problems I won't outline here in detail. Now the question is: causes some problems I won't outline here in detail. Now the question is:
when does a microframework need more than one application at the same when does a microframework need more than one application at the same
time? A good example for this is unit testing. When you want to test time? A good example for this is unittesting. When you want to test
something it can be very helpful to create a minimal application to test something it can be very helpful to create a minimal application to test
specific behavior. When the application object is deleted everything it specific behavior. When the application object is deleted everything it
allocated will be freed again. allocated will be freed again.
Another thing that becomes possible when you have an explicit object lying Another thing that becomes possible when you have an explicit object laying
around in your code is that you can subclass the base class around in your code is that you can subclass the base class
(:class:`~flask.Flask`) to alter specific behavior. This would not be (:class:`~flask.Flask`) to alter specific behaviour. This would not be
possible without hacks if the object were created ahead of time for you possible without hacks if the object were created ahead of time for you
based on a class that is not exposed to you. based on a class that is not exposed to you.
@ -73,33 +73,13 @@ want to apply a WSGI middleware, just wrap it and you're done (though
there are better ways to do that so that you do not lose the reference there are better ways to do that so that you do not lose the reference
to the application object :meth:`~flask.Flask.wsgi_app`). to the application object :meth:`~flask.Flask.wsgi_app`).
Furthermore this design makes it possible to use a factory function to
create the application which is very helpful for unit testing and similar
things (:doc:`/patterns/appfactories`).
The Routing System
------------------
Flask uses the Werkzeug routing system which was designed to
automatically order routes by complexity. This means that you can declare
routes in arbitrary order and they will still work as expected. This is a
requirement if you want to properly implement decorator based routing
since decorators could be fired in undefined order when the application is
split into multiple modules.
Another design decision with the Werkzeug routing system is that routes
in Werkzeug try to ensure that URLs are unique. Werkzeug will go quite far
with that in that it will automatically redirect to a canonical URL if a route
is ambiguous.
One Template Engine One Template Engine
------------------- -------------------
Flask decides on one template engine: Jinja. Why doesn't Flask have a Flask decides on one template engine: Jinja2. Why doesn't Flask have a
pluggable template engine interface? You can obviously use a different pluggable template engine interface? You can obviously use a different
template engine, but Flask will still configure Jinja for you. While template engine, but Flask will still configure Jinja2 for you. While
that limitation that Jinja is *always* configured will probably go away, that limitation that Jinja2 is *always* configured will probably go away,
the decision to bundle one template engine and use that will not. the decision to bundle one template engine and use that will not.
Template engines are like programming languages and each of those engines Template engines are like programming languages and each of those engines
@ -107,50 +87,30 @@ has a certain understanding about how things work. On the surface they
all work the same: you tell the engine to evaluate a template with a set all work the same: you tell the engine to evaluate a template with a set
of variables and take the return value as string. of variables and take the return value as string.
But that's about where similarities end. Jinja for example has an But that's about where similarities end. Jinja2 for example has an
extensive filter system, a certain way to do template inheritance, extensive filter system, a certain way to do template inheritance, support
support for reusable blocks (macros) that can be used from inside for reusable blocks (macros) that can be used from inside templates and
templates and also from Python code, supports iterative template also from Python code, uses unicode for all operations, supports
rendering, configurable syntax and more. On the other hand an engine iterative template rendering, configurable syntax and more. On the other
like Genshi is based on XML stream evaluation, template inheritance by hand an engine like Genshi is based on XML stream evaluation, template
taking the availability of XPath into account and more. Mako on the inheritance by taking the availability of XPath into account and more.
other hand treats templates similar to Python modules. Mako on the other hand treats templates similar to Python modules.
When it comes to connecting a template engine with an application or When it comes to connecting a template engine with an application or
framework there is more than just rendering templates. For instance, framework there is more than just rendering templates. For instance,
Flask uses Jinja's extensive autoescaping support. Also it provides Flask uses Jinja2's extensive autoescaping support. Also it provides
ways to access macros from Jinja templates. ways to access macros from Jinja2 templates.
A template abstraction layer that would not take the unique features of A template abstraction layer that would not take the unique features of
the template engines away is a science on its own and a too large the template engines away is a science on its own and a too large
undertaking for a microframework like Flask. undertaking for a microframework like Flask.
Furthermore extensions can then easily depend on one template language
being present. You can easily use your own templating language, but an
extension could still depend on Jinja itself.
Micro with Dependencies
What does "micro" mean?
----------------------- -----------------------
“Micro” does not mean that your whole web application has to fit into a single
Python file (although it certainly can), nor does it mean that Flask is lacking
in functionality. The "micro" in microframework means Flask aims to keep the
core simple but extensible. Flask won't make many decisions for you, such as
what database to use. Those decisions that it does make, such as what
templating engine to use, are easy to change. Everything else is up to you, so
that Flask can be everything you need and nothing you don't.
By default, Flask does not include a database abstraction layer, form
validation or anything else where different libraries already exist that can
handle that. Instead, Flask supports extensions to add such functionality to
your application as if it was implemented in Flask itself. Numerous extensions
provide database integration, form validation, upload handling, various open
authentication technologies, and more. Flask may be "micro", but it's ready for
production use on a variety of needs.
Why does Flask call itself a microframework and yet it depends on two Why does Flask call itself a microframework and yet it depends on two
libraries (namely Werkzeug and Jinja). Why shouldn't it? If we look libraries (namely Werkzeug and Jinja2). Why shouldn't it? If we look
over to the Ruby side of web development there we have a protocol very over to the Ruby side of web development there we have a protocol very
similar to WSGI. Just that it's called Rack there, but besides that it similar to WSGI. Just that it's called Rack there, but besides that it
looks very much like a WSGI rendition for Ruby. But nearly all looks very much like a WSGI rendition for Ruby. But nearly all
@ -169,61 +129,19 @@ infrastructure, packages with dependencies are no longer an issue and
there are very few reasons against having libraries that depend on others. there are very few reasons against having libraries that depend on others.
Context Locals Thread Locals
-------------- -------------
Flask uses special context locals and proxies to provide access to the Flask uses thread local objects (context local objects in fact, they
current app and request data to any code running during a request, CLI command, support greenlet contexts as well) for request, session and an extra
etc. Context locals are specific to the worker handling the activity, such as a object you can put your own things on (:data:`~flask.g`). Why is that and
thread, process, coroutine, or greenlet. isn't that a bad idea?
The context and proxies help solve two development issues: circular imports, and Yes it is usually not such a bright idea to use thread locals. They cause
passing around global data. :data:`.current_app` can be used to access the troubles for servers that are not based on the concept of threads and make
application object without needing to import the app object directly, avoiding large applications harder to maintain. However Flask is just not designed
circular import issues. :data:`.request`, :data:`.session`, and :data:`.g` can for large applications or asynchronous servers. Flask wants to make it
be imported to access the current data for the request, rather than needing to quick and easy to write a traditional web application.
pass them as arguments through every single function in your project.
Also see the :ref:`becomingbig` section of the documentation for some
Async/await and ASGI support inspiration for larger applications based on Flask.
----------------------------
Flask supports ``async`` coroutines for view functions by executing the
coroutine on a separate thread instead of using an event loop on the
main thread as an async-first (ASGI) framework would. This is necessary
for Flask to remain backwards compatible with extensions and code built
before ``async`` was introduced into Python. This compromise introduces
a performance cost compared with the ASGI frameworks, due to the
overhead of the threads.
Due to how tied to WSGI Flask's code is, it's not clear if it's possible
to make the ``Flask`` class support ASGI and WSGI at the same time. Work
is currently being done in Werkzeug to work with ASGI, which may
eventually enable support in Flask as well.
See :doc:`/async-await` for more discussion.
What Flask is, What Flask is Not
--------------------------------
Flask will never have a database layer. It will not have a form library
or anything else in that direction. Flask itself just bridges to Werkzeug
to implement a proper WSGI application and to Jinja to handle templating.
It also binds to a few common standard library packages such as logging.
Everything else is up for extensions.
Why is this the case? Because people have different preferences and
requirements and Flask could not meet those if it would force any of this
into the core. The majority of web applications will need a template
engine in some sort. However not every application needs a SQL database.
As your codebase grows, you are free to make the design decisions appropriate
for your project. Flask will continue to provide a very simple glue layer to
the best that Python has to offer. You can implement advanced patterns in
SQLAlchemy or another database tool, introduce non-relational data persistence
as appropriate, and take advantage of framework-agnostic tools built for WSGI,
the Python web interface.
The idea of Flask is to build a good foundation for all applications.
Everything else is up to you or extensions.

733
docs/errorhandling.rst
View file

@ -1,523 +1,236 @@
.. _application-errors:
Handling Application Errors Handling Application Errors
=========================== ===========================
Applications fail, servers fail. Sooner or later you will see an exception .. versionadded:: 0.3
in production. Even if your code is 100% correct, you will still see
exceptions from time to time. Why? Because everything else involved will Applications fail, server fail. Sooner or later you will see an exception
fail. Here are some situations where perfectly fine code can lead to server in production. Even if your code is 100% correct, you will still see
exceptions from time to time. Why? Because everything else involved will
fail. Here some situations where perfectly fine code can lead to server
errors: errors:
- the client terminated the request early and the application was still - the client terminated the request early and the application was still
reading from the incoming data reading from the incoming data.
- the database server was overloaded and could not handle the query - the database server was overloaded and could not handle the query.
- a filesystem is full - a filesystem is full
- a harddrive crashed - a harddrive crashed
- a backend server overloaded - a backend server overloaded
- a programming error in a library you are using - a programming error in a library you are using
- network connection of the server to another system failed - network connection of the server to another system failed.
And that's just a small sample of issues you could be facing. So how do we And that's just a small sample of issues you could be facing. So how to
deal with that sort of problem? By default if your application runs in deal with that sort of problem? By default if your application runs in
production mode, and an exception is raised Flask will display a very simple production mode, Flask will display a very simple page for you and log the
page for you and log the exception to the :attr:`~flask.Flask.logger`. exception to the :attr:`~flask.Flask.logger`.
But there is more you can do, and we will cover some better setups to deal But there is more you can do, and we will cover some better setups to deal
with errors including custom exceptions and 3rd party tools. with errors.
Error Mails
.. _error-logging-tools: -----------
Error Logging Tools If the application runs in production mode (which it will do on your
------------------- server) you won't see any log messages by default. Why that? Flask tries
to be a zero-configuration framework and where should it drop the logs for
Sending error mails, even if just for critical ones, can become you if there is no configuration. Guessing is not a good idea because
overwhelming if enough users are hitting the error and log files are changes are, the place it guessed is not the place where the user has the
typically never looked at. This is why we recommend using `Sentry permission to create a logfile. Also, for most small applications nobody
<https://sentry.io/>`_ for dealing with application errors. It's will look at the logs anyways.
available as a source-available project `on GitHub
<https://github.com/getsentry/sentry>`_ and is also available as a `hosted version In fact, I promise you right now that if you configure a logfile for the
<https://sentry.io/signup/>`_ which you can try for free. Sentry application errors you will never look at it except for debugging an issue
aggregates duplicate errors, captures the full stack trace and local when a user reported it for you. What you want instead is a mail the
variables for debugging, and sends you mails based on new errors or second the exception happened. Then you get an alert and you can do
frequency thresholds. something about it.
To use Sentry you need to install the ``sentry-sdk`` client with extra Flask is using the Python builtin logging system and that one can actually
``flask`` dependencies. send you mails for errors which is probably what you want. Here is how
you can configure the Flask logger to send you mails for exceptions::
.. code-block:: text
ADMINS = ['yourname@example.com']
$ pip install sentry-sdk[flask] if not app.debug:
import logging
And then add this to your Flask app: from logging.handlers import SMTPHandler
mail_handler = SMTPHandler('127.0.0.1',
.. code-block:: python 'server-error@example.com',
ADMINS, 'YourApplication Failed')
import sentry_sdk mail_handler.setLevel(logging.ERROR)
from sentry_sdk.integrations.flask import FlaskIntegration app.logger.addHandler(mail_handler)
sentry_sdk.init('YOUR_DSN_HERE', integrations=[FlaskIntegration()]) So what just happened? We created a new
:class:`~logging.handlers.SMTPHandler` that will send mails with the mail
The ``YOUR_DSN_HERE`` value needs to be replaced with the DSN value you server listening on ``127.0.0.1`` to all the `ADMINS` from the address
get from your Sentry installation. *server-error@example.com* with the subject "YourApplication Failed". If
your mail server requires credentials these can also provided, for that
After installation, failures leading to an Internal Server Error check out the documentation for the :class:`~logging.handlers.SMTPHandler`.
are automatically reported to Sentry and from there you can
receive error notifications. We also tell the handler to only send errors and more critical messages.
Because we certainly don't want to get a mail for warnings or other
See also: useless logs that might happen during request handling.
- Sentry also supports catching errors from a worker queue Before you run that in production, please also look at :ref:`log-format`
(RQ, Celery, etc.) in a similar fashion. See the `Python SDK docs to put more information into that error mail. That will save you from a
<https://docs.sentry.io/platforms/python/>`__ for more information. lot of frustration.
- `Flask-specific documentation <https://docs.sentry.io/platforms/python/guides/flask/>`__
Logging to a File
Error Handlers -----------------
--------------
Even if you get mails, you probably also want to log warnings. It's a
When an error occurs in Flask, an appropriate `HTTP status code good idea to keep as much information around that might be required to
<https://developer.mozilla.org/en-US/docs/Web/HTTP/Status>`__ will be debug a problem. Please note that Flask itself will not issue any
returned. 400-499 indicate errors with the client's request data, or warnings in the core system, so it's your responsibility to warn in the
about the data requested. 500-599 indicate errors with the server or code if something seems odd.
application itself.
There are a couple of handlers provided by the logging system out of the
You might want to show custom error pages to the user when an error occurs. box but not all of them are useful for basic error logging. The most
This can be done by registering error handlers. interesting are probably the following:
An error handler is a function that returns a response when a type of error is - :class:`~logging.handlers.FileHandler` - logs messages to a file on the
raised, similar to how a view is a function that returns a response when a filesystem.
request URL is matched. It is passed the instance of the error being handled, - :class:`~logging.handlers.RotatingFileHandler` - logs messages to a file
which is most likely a :exc:`~werkzeug.exceptions.HTTPException`. on the filesystem and will rotate after a certain number of messages.
- :class:`~logging.handlers.NTEventLogHandler` - will log to the system
The status code of the response will not be set to the handler's code. Make event log of a Windows system. If you are deploying on a Windows box,
sure to provide the appropriate HTTP status code when returning a response from this is what you want to use.
a handler. - :class:`~logging.handlers.SysLogHandler` - sends logs to a UNIX
syslog.
Registering Once you picked your log handler, do like you did with the SMTP handler
``````````` above, just make sure to use a lower setting (I would recommend
`WARNING`)::
Register handlers by decorating a function with
:meth:`~flask.Flask.errorhandler`. Or use if not app.debug:
:meth:`~flask.Flask.register_error_handler` to register the function later. import logging
Remember to set the error code when returning the response. from logging.handlers import TheHandlerYouWant
file_handler = TheHandlerYouWant(...)
.. code-block:: python file_handler.setLevel(logging.WARNING)
app.logger.addHandler(file_handler)
@app.errorhandler(werkzeug.exceptions.BadRequest)
def handle_bad_request(e): .. _log-format:
return 'bad request!', 400
Controlling the Log Format
# or, without the decorator --------------------------
app.register_error_handler(400, handle_bad_request)
By default a handler will only write the message string into a file or
:exc:`werkzeug.exceptions.HTTPException` subclasses like send you that message as mail. But a log record stores more information
:exc:`~werkzeug.exceptions.BadRequest` and their HTTP codes are interchangeable and it makes a lot of sense to configure your logger to also contain that
when registering handlers. (``BadRequest.code == 400``) information so that you have a better idea of why that error happened, and
more importantly, where it did.
Non-standard HTTP codes cannot be registered by code because they are not known
by Werkzeug. Instead, define a subclass of A formatter can be instanciated with a format string. Note that
:class:`~werkzeug.exceptions.HTTPException` with the appropriate code and tracebacks are appended to the log entry automatically. You don't have to
register and raise that exception class. do that in the log formatter format string.
.. code-block:: python Here some example setups:
class InsufficientStorage(werkzeug.exceptions.HTTPException): Email
code = 507 `````
description = 'Not enough storage space.'
::
app.register_error_handler(InsufficientStorage, handle_507)
from logging import Formatter
raise InsufficientStorage() mail_handler.setFormatter(Formatter('''
Message type: %(levelname)s
Handlers can be registered for any exception class, not just Location: %(pathname)s:%(lineno)d
:exc:`~werkzeug.exceptions.HTTPException` subclasses or HTTP status Module: %(module)s
codes. Handlers can be registered for a specific class, or for all subclasses Function: %(funcName)s
of a parent class. Time: %(asctime)s
Message:
Handling
```````` %(message)s
'''))
When building a Flask application you *will* run into exceptions. If some part
of your code breaks while handling a request (and you have no error handlers File logging
registered), a "500 Internal Server Error" ````````````
(:exc:`~werkzeug.exceptions.InternalServerError`) will be returned by default.
Similarly, "404 Not Found" ::
(:exc:`~werkzeug.exceptions.NotFound`) error will occur if a request is sent to an unregistered route.
If a route receives an unallowed request method, a "405 Method Not Allowed" from logging import Formatter
(:exc:`~werkzeug.exceptions.MethodNotAllowed`) will be raised. These are all file_handler.setFormatter(Formatter(
subclasses of :class:`~werkzeug.exceptions.HTTPException` and are provided by '%(astime)s %(levelname)s: %(message)s '
default in Flask. '[in %(pathname)s:%(lineno)d]'
))
Flask gives you the ability to raise any HTTP exception registered by
Werkzeug. However, the default HTTP exceptions return simple exception
pages. You might want to show custom error pages to the user when an error occurs. Complex Log Formatting
This can be done by registering error handlers. ``````````````````````
When Flask catches an exception while handling a request, it is first looked up by code. Here is a list of useful formatting variables for the format string. Note
If no handler is registered for the code, Flask looks up the error by its class hierarchy; the most specific handler is chosen. that this list is not complete, consult the official documentation of the
If no handler is registered, :class:`~werkzeug.exceptions.HTTPException` subclasses show a :mod:`logging` package for a full list.
generic message about their code, while other exceptions are converted to a
generic "500 Internal Server Error". .. tabularcolumns:: |p{3cm}|p{12cm}|
For example, if an instance of :exc:`ConnectionRefusedError` is raised, +------------------+----------------------------------------------------+
and a handler is registered for :exc:`ConnectionError` and | Format | Description |
:exc:`ConnectionRefusedError`, the more specific :exc:`ConnectionRefusedError` +==================+====================================================+
handler is called with the exception instance to generate the response. | ``%(levelname)s``| Text logging level for the message |
| | (``'DEBUG'``, ``'INFO'``, ``'WARNING'``, |
Handlers registered on the blueprint take precedence over those registered | | ``'ERROR'``, ``'CRITICAL'``). |
globally on the application, assuming a blueprint is handling the request that +------------------+----------------------------------------------------+
raises the exception. However, the blueprint cannot handle 404 routing errors | ``%(pathname)s`` | Full pathname of the source file where the |
because the 404 occurs at the routing level before the blueprint can be | | logging call was issued (if available). |
determined. +------------------+----------------------------------------------------+
| ``%(filename)s`` | Filename portion of pathname. |
+------------------+----------------------------------------------------+
Generic Exception Handlers | ``%(module)s`` | Module (name portion of filename). |
`````````````````````````` +------------------+----------------------------------------------------+
| ``%(funcName)s`` | Name of function containing the logging call. |
It is possible to register error handlers for very generic base classes +------------------+----------------------------------------------------+
such as ``HTTPException`` or even ``Exception``. However, be aware that | ``%(lineno)d`` | Source line number where the logging call was |
these will catch more than you might expect. | | issued (if available). |
+------------------+----------------------------------------------------+
For example, an error handler for ``HTTPException`` might be useful for turning | ``%(asctime)s`` | Human-readable time when the LogRecord` was |
the default HTML errors pages into JSON. However, this | | created. By default this is of the form |
handler will trigger for things you don't cause directly, such as 404 | | ``"2003-07-08 16:49:45,896"`` (the numbers after |
and 405 errors during routing. Be sure to craft your handler carefully | | the comma are millisecond portion of the time). |
so you don't lose information about the HTTP error. | | This can be changed by subclassing the formatter |
| | and overriding the |
.. code-block:: python | | :meth:`~logging.Formatter.formatTime` method. |
+------------------+----------------------------------------------------+
from flask import json | ``%(message)s`` | The logged message, computed as ``msg % args`` |
from werkzeug.exceptions import HTTPException +------------------+----------------------------------------------------+
@app.errorhandler(HTTPException) If you want to further customize the formatting, you can subclass the
def handle_exception(e): formatter. The formatter has three interesting methods:
"""Return JSON instead of HTML for HTTP errors."""
# start with the correct headers and status code from the error :meth:`~logging.Formatter.format`:
response = e.get_response() handles the actual formatting. It is passed a
# replace the body with JSON :class:`~logging.LogRecord` object and has to return the formatted
response.data = json.dumps({ string.
"code": e.code, :meth:`~logging.Formatter.formatTime`:
"name": e.name, called for `asctime` formatting. If you want a different time format
"description": e.description, you can override this method.
}) :meth:`~logging.Formatter.formatException`
response.content_type = "application/json" called for exception formatting. It is passed a :attr:`~sys.exc_info`
return response tuple and has to return a string. The default is usually fine, you
don't have to override it.
An error handler for ``Exception`` might seem useful for changing how
all errors, even unhandled ones, are presented to the user. However, For more information, head over to the official documentation.
this is similar to doing ``except Exception:`` in Python, it will
capture *all* otherwise unhandled errors, including all HTTP status
codes. Other Libraries
---------------
In most cases it will be safer to register handlers for more
specific exceptions. Since ``HTTPException`` instances are valid WSGI So far we only configured the logger your application created itself.
responses, you could also pass them through directly. Other libraries might log themselves as well. For example, SQLAlchemy use
logging heavily in the core. While there is a method to configure all
.. code-block:: python loggers at once in the :mod:`logging` package, I would not recommend using
it. There might be a situation in which you want to have multiple
from werkzeug.exceptions import HTTPException separate applications running side by side in the same Python interpreter
and then it becomes impossible to have different logging setups for those.
@app.errorhandler(Exception)
def handle_exception(e): Instead, I would recommend figuring out which loggers you are interested
# pass through HTTP errors in, getting the loggers with the :func:`~logging.getLogger` function and
if isinstance(e, HTTPException): iterating over them to attach handlers::
return e
from logging import getLogger
# now you're handling non-HTTP exceptions only loggers = [app.logger, getLogger('sqlalchemy'),
return render_template("500_generic.html", e=e), 500 getLogger('otherlibrary')]
for logger in loggers:
Error handlers still respect the exception class hierarchy. If you logger.addHandler(mail_handler)
register handlers for both ``HTTPException`` and ``Exception``, the logger.addHandler(file_handler)
``Exception`` handler will not handle ``HTTPException`` subclasses
because the ``HTTPException`` handler is more specific.
Unhandled Exceptions
````````````````````
When there is no error handler registered for an exception, a 500
Internal Server Error will be returned instead. See
:meth:`flask.Flask.handle_exception` for information about this
behavior.
If there is an error handler registered for ``InternalServerError``,
this will be invoked. As of Flask 1.1.0, this error handler will always
be passed an instance of ``InternalServerError``, not the original
unhandled error.
The original error is available as ``e.original_exception``.
An error handler for "500 Internal Server Error" will be passed uncaught
exceptions in addition to explicit 500 errors. In debug mode, a handler
for "500 Internal Server Error" will not be used. Instead, the
interactive debugger will be shown.
Custom Error Pages
------------------
Sometimes when building a Flask application, you might want to raise a
:exc:`~werkzeug.exceptions.HTTPException` to signal to the user that
something is wrong with the request. Fortunately, Flask comes with a handy
:func:`~flask.abort` function that aborts a request with a HTTP error from
werkzeug as desired. It will also provide a plain black and white error page
for you with a basic description, but nothing fancy.
Depending on the error code it is less or more likely for the user to
actually see such an error.
Consider the code below, we might have a user profile route, and if the user
fails to pass a username we can raise a "400 Bad Request". If the user passes a
username and we can't find it, we raise a "404 Not Found".
.. code-block:: python
from flask import abort, render_template, request
# a username needs to be supplied in the query args
# a successful request would be like /profile?username=jack
@app.route("/profile")
def user_profile():
username = request.arg.get("username")
# if a username isn't supplied in the request, return a 400 bad request
if username is None:
abort(400)
user = get_user(username=username)
# if a user can't be found by their username, return 404 not found
if user is None:
abort(404)
return render_template("profile.html", user=user)
Here is another example implementation for a "404 Page Not Found" exception:
.. code-block:: python
from flask import render_template
@app.errorhandler(404)
def page_not_found(e):
# note that we set the 404 status explicitly
return render_template('404.html'), 404
When using :doc:`/patterns/appfactories`:
.. code-block:: python
from flask import Flask, render_template
def page_not_found(e):
return render_template('404.html'), 404
def create_app(config_filename):
app = Flask(__name__)
app.register_error_handler(404, page_not_found)
return app
An example template might be this:
.. code-block:: html+jinja
{% extends "layout.html" %}
{% block title %}Page Not Found{% endblock %}
{% block body %}
<h1>Page Not Found</h1>
<p>What you were looking for is just not there.
<p><a href="{{ url_for('index') }}">go somewhere nice</a>
{% endblock %}
Further Examples
````````````````
The above examples wouldn't actually be an improvement on the default
exception pages. We can create a custom 500.html template like this:
.. code-block:: html+jinja
{% extends "layout.html" %}
{% block title %}Internal Server Error{% endblock %}
{% block body %}
<h1>Internal Server Error</h1>
<p>Oops... we seem to have made a mistake, sorry!</p>
<p><a href="{{ url_for('index') }}">Go somewhere nice instead</a>
{% endblock %}
It can be implemented by rendering the template on "500 Internal Server Error":
.. code-block:: python
from flask import render_template
@app.errorhandler(500)
def internal_server_error(e):
# note that we set the 500 status explicitly
return render_template('500.html'), 500
When using :doc:`/patterns/appfactories`:
.. code-block:: python
from flask import Flask, render_template
def internal_server_error(e):
return render_template('500.html'), 500
def create_app():
app = Flask(__name__)
app.register_error_handler(500, internal_server_error)
return app
When using :doc:`/blueprints`:
.. code-block:: python
from flask import Blueprint
blog = Blueprint('blog', __name__)
# as a decorator
@blog.errorhandler(500)
def internal_server_error(e):
return render_template('500.html'), 500
# or with register_error_handler
blog.register_error_handler(500, internal_server_error)
Blueprint Error Handlers
------------------------
In :doc:`/blueprints`, most error handlers will work as expected.
However, there is a caveat concerning handlers for 404 and 405
exceptions. These error handlers are only invoked from an appropriate
``raise`` statement or a call to ``abort`` in another of the blueprint's
view functions; they are not invoked by, e.g., an invalid URL access.
This is because the blueprint does not "own" a certain URL space, so
the application instance has no way of knowing which blueprint error
handler it should run if given an invalid URL. If you would like to
execute different handling strategies for these errors based on URL
prefixes, they may be defined at the application level using the
``request`` proxy object.
.. code-block:: python
from flask import jsonify, render_template
# at the application level
# not the blueprint level
@app.errorhandler(404)
def page_not_found(e):
# if a request is in our blog URL space
if request.path.startswith('/blog/'):
# we return a custom blog 404 page
return render_template("blog/404.html"), 404
else:
# otherwise we return our generic site-wide 404 page
return render_template("404.html"), 404
@app.errorhandler(405)
def method_not_allowed(e):
# if a request has the wrong method to our API
if request.path.startswith('/api/'):
# we return a json saying so
return jsonify(message="Method Not Allowed"), 405
else:
# otherwise we return a generic site-wide 405 page
return render_template("405.html"), 405
Returning API Errors as JSON
----------------------------
When building APIs in Flask, some developers realise that the built-in
exceptions are not expressive enough for APIs and that the content type of
:mimetype:`text/html` they are emitting is not very useful for API consumers.
Using the same techniques as above and :func:`~flask.json.jsonify` we can return JSON
responses to API errors. :func:`~flask.abort` is called
with a ``description`` parameter. The error handler will
use that as the JSON error message, and set the status code to 404.
.. code-block:: python
from flask import abort, jsonify
@app.errorhandler(404)
def resource_not_found(e):
return jsonify(error=str(e)), 404
@app.route("/cheese")
def get_one_cheese():
resource = get_resource()
if resource is None:
abort(404, description="Resource not found")
return jsonify(resource)
We can also create custom exception classes. For instance, we can
introduce a new custom exception for an API that can take a proper human readable message,
a status code for the error and some optional payload to give more context
for the error.
This is a simple example:
.. code-block:: python
from flask import jsonify, request
class InvalidAPIUsage(Exception):
status_code = 400
def __init__(self, message, status_code=None, payload=None):
super().__init__()
self.message = message
if status_code is not None:
self.status_code = status_code
self.payload = payload
def to_dict(self):
rv = dict(self.payload or ())
rv['message'] = self.message
return rv
@app.errorhandler(InvalidAPIUsage)
def invalid_api_usage(e):
return jsonify(e.to_dict()), e.status_code
# an API app route for getting user information
# a correct request might be /api/user?user_id=420
@app.route("/api/user")
def user_api(user_id):
user_id = request.arg.get("user_id")
if not user_id:
raise InvalidAPIUsage("No user id provided!")
user = get_user(user_id=user_id)
if not user:
raise InvalidAPIUsage("No such user!", status_code=404)
return jsonify(user.to_dict())
A view can now raise that exception with an error message. Additionally
some extra payload can be provided as a dictionary through the `payload`
parameter.
Logging
-------
See :doc:`/logging` for information about how to log exceptions, such as
by emailing them to admins.
Debugging
---------
See :doc:`/debugging` for information about how to debug errors in
development and production.

305
docs/extensiondev.rst
View file

@ -1,305 +0,0 @@
Flask Extension Development
===========================
.. currentmodule:: flask
Extensions are extra packages that add functionality to a Flask
application. While `PyPI`_ contains many Flask extensions, you may not
find one that fits your need. If this is the case, you can create your
own, and publish it for others to use as well.
This guide will show how to create a Flask extension, and some of the
common patterns and requirements involved. Since extensions can do
anything, this guide won't be able to cover every possibility.
The best ways to learn about extensions are to look at how other
extensions you use are written, and discuss with others. Discuss your
design ideas with others on our `Discord Chat`_ or
`GitHub Discussions`_.
The best extensions share common patterns, so that anyone familiar with
using one extension won't feel completely lost with another. This can
only work if collaboration happens early.
Naming
------
A Flask extension typically has ``flask`` in its name as a prefix or
suffix. If it wraps another library, it should include the library name
as well. This makes it easy to search for extensions, and makes their
purpose clearer.
A general Python packaging recommendation is that the install name from
the package index and the name used in ``import`` statements should be
related. The import name is lowercase, with words separated by
underscores (``_``). The install name is either lower case or title
case, with words separated by dashes (``-``). If it wraps another
library, prefer using the same case as that library's name.
Here are some example install and import names:
- ``Flask-Name`` imported as ``flask_name``
- ``flask-name-lower`` imported as ``flask_name_lower``
- ``Flask-ComboName`` imported as ``flask_comboname``
- ``Name-Flask`` imported as ``name_flask``
The Extension Class and Initialization
--------------------------------------
All extensions will need some entry point that initializes the
extension with the application. The most common pattern is to create a
class that represents the extension's configuration and behavior, with
an ``init_app`` method to apply the extension instance to the given
application instance.
.. code-block:: python
class HelloExtension:
def __init__(self, app=None):
if app is not None:
self.init_app(app)
def init_app(self, app):
app.before_request(...)
It is important that the app is not stored on the extension, don't do
``self.app = app``. The only time the extension should have direct
access to an app is during ``init_app``, otherwise it should use
:data:`.current_app`.
This allows the extension to support the application factory pattern,
avoids circular import issues when importing the extension instance
elsewhere in a user's code, and makes testing with different
configurations easier.
.. code-block:: python
hello = HelloExtension()
def create_app():
app = Flask(__name__)
hello.init_app(app)
return app
Above, the ``hello`` extension instance exists independently of the
application. This means that other modules in a user's project can do
``from project import hello`` and use the extension in blueprints before
the app exists.
The :attr:`Flask.extensions` dict can be used to store a reference to
the extension on the application, or some other state specific to the
application. Be aware that this is a single namespace, so use a name
unique to your extension, such as the extension's name without the
"flask" prefix.
Adding Behavior
---------------
There are many ways that an extension can add behavior. Any setup
methods that are available on the :class:`Flask` object can be used
during an extension's ``init_app`` method.
A common pattern is to use :meth:`~Flask.before_request` to initialize
some data or a connection at the beginning of each request, then
:meth:`~Flask.teardown_request` to clean it up at the end. This can be
stored on :data:`.g`, discussed more below.
A more lazy approach is to provide a method that initializes and caches
the data or connection. For example, a ``ext.get_db`` method could
create a database connection the first time it's called, so that a view
that doesn't use the database doesn't create a connection.
Besides doing something before and after every view, your extension
might want to add some specific views as well. In this case, you could
define a :class:`Blueprint`, then call :meth:`~Flask.register_blueprint`
during ``init_app`` to add the blueprint to the app.
Configuration Techniques
------------------------
There can be multiple levels and sources of configuration for an
extension. You should consider what parts of your extension fall into
each one.
- Configuration per application instance, through ``app.config``
values. This is configuration that could reasonably change for each
deployment of an application. A common example is a URL to an
external resource, such as a database. Configuration keys should
start with the extension's name so that they don't interfere with
other extensions.
- Configuration per extension instance, through ``__init__``
arguments. This configuration usually affects how the extension
is used, such that it wouldn't make sense to change it per
deployment.
- Configuration per extension instance, through instance attributes
and decorator methods. It might be more ergonomic to assign to
``ext.value``, or use a ``@ext.register`` decorator to register a
function, after the extension instance has been created.
- Global configuration through class attributes. Changing a class
attribute like ``Ext.connection_class`` can customize default
behavior without making a subclass. This could be combined
per-extension configuration to override defaults.
- Subclassing and overriding methods and attributes. Making the API of
the extension itself something that can be overridden provides a
very powerful tool for advanced customization.
The :class:`~flask.Flask` object itself uses all of these techniques.
It's up to you to decide what configuration is appropriate for your
extension, based on what you need and what you want to support.
Configuration should not be changed after the application setup phase is
complete and the server begins handling requests. Configuration is
global, any changes to it are not guaranteed to be visible to other
workers.
Data During a Request
---------------------
When writing a Flask application, the :data:`~flask.g` object is used to
store information during a request. For example the
:doc:`tutorial <tutorial/database>` stores a connection to a SQLite
database as ``g.db``. Extensions can also use this, with some care.
Since ``g`` is a single global namespace, extensions must use unique
names that won't collide with user data. For example, use the extension
name as a prefix, or as a namespace.
.. code-block:: python
# an internal prefix with the extension name
g._hello_user_id = 2
# or an internal prefix as a namespace
from types import SimpleNamespace
g._hello = SimpleNamespace()
g._hello.user_id = 2
The data in ``g`` lasts for an application context. An application context is
active during a request, CLI command, or ``with app.app_context()`` block. If
you're storing something that should be closed, use
:meth:`~flask.Flask.teardown_appcontext` to ensure that it gets closed when the
app context ends. If it should only be valid during a request, or would not be
used in the CLI outside a request, use :meth:`~flask.Flask.teardown_request`.
Views and Models
----------------
Your extension views might want to interact with specific models in your
database, or some other extension or data connected to your application.
For example, let's consider a ``Flask-SimpleBlog`` extension that works
with Flask-SQLAlchemy to provide a ``Post`` model and views to write
and read posts.
The ``Post`` model needs to subclass the Flask-SQLAlchemy ``db.Model``
object, but that's only available once you've created an instance of
that extension, not when your extension is defining its views. So how
can the view code, defined before the model exists, access the model?
One method could be to use :doc:`views`. During ``__init__``, create
the model, then create the views by passing the model to the view
class's :meth:`~views.View.as_view` method.
.. code-block:: python
class PostAPI(MethodView):
def __init__(self, model):
self.model = model
def get(self, id):
post = self.model.query.get(id)
return jsonify(post.to_json())
class BlogExtension:
def __init__(self, db):
class Post(db.Model):
id = db.Column(primary_key=True)
title = db.Column(db.String, nullable=False)
self.post_model = Post
def init_app(self, app):
api_view = PostAPI.as_view(model=self.post_model)
db = SQLAlchemy()
blog = BlogExtension(db)
db.init_app(app)
blog.init_app(app)
Another technique could be to use an attribute on the extension, such as
``self.post_model`` from above. Add the extension to ``app.extensions``
in ``init_app``, then access
``current_app.extensions["simple_blog"].post_model`` from views.
You may also want to provide base classes so that users can provide
their own ``Post`` model that conforms to the API your extension
expects. So they could implement ``class Post(blog.BasePost)``, then
set it as ``blog.post_model``.
As you can see, this can get a bit complex. Unfortunately, there's no
perfect solution here, only different strategies and tradeoffs depending
on your needs and how much customization you want to offer. Luckily,
this sort of resource dependency is not a common need for most
extensions. Remember, if you need help with design, ask on our
`Discord Chat`_ or `GitHub Discussions`_.
Recommended Extension Guidelines
--------------------------------
Flask previously had the concept of "approved extensions", where the
Flask maintainers evaluated the quality, support, and compatibility of
the extensions before listing them. While the list became too difficult
to maintain over time, the guidelines are still relevant to all
extensions maintained and developed today, as they help the Flask
ecosystem remain consistent and compatible.
1. An extension requires a maintainer. In the event an extension author
would like to move beyond the project, the project should find a new
maintainer and transfer access to the repository, documentation,
PyPI, and any other services. The `Pallets-Eco`_ organization on
GitHub allows for community maintenance with oversight from the
Pallets maintainers.
2. The naming scheme is *Flask-ExtensionName* or *ExtensionName-Flask*.
It must provide exactly one package or module named
``flask_extension_name``.
3. The extension must use an open source license. The Python web
ecosystem tends to prefer BSD or MIT. It must be open source and
publicly available.
4. The extension's API must have the following characteristics:
- It must support multiple applications running in the same Python
process. Use ``current_app`` instead of ``self.app``, store
configuration and state per application instance.
- It must be possible to use the factory pattern for creating
applications. Use the ``ext.init_app()`` pattern.
5. From a clone of the repository, an extension with its dependencies
must be installable in editable mode with ``pip install -e .``.
6. It must ship tests that can be invoked with a common tool like
``tox -e py``, ``nox -s test`` or ``pytest``. If not using ``tox``,
the test dependencies should be specified in a requirements file.
The tests must be part of the sdist distribution.
7. A link to the documentation or project website must be in the PyPI
metadata or the readme. The documentation should use the Flask theme
from the `Official Pallets Themes`_.
8. The extension's dependencies should not use upper bounds or assume
any particular version scheme, but should use lower bounds to
indicate minimum compatibility support. For example,
``sqlalchemy>=1.4``.
9. Indicate the versions of Python supported using ``python_requires=">=version"``.
Flask and Pallets policy is to support all Python versions that are not
within six months of end of life (EOL). See Python's `EOL calendar`_ for
timing.
.. _PyPI: https://pypi.org/search/?c=Framework+%3A%3A+Flask
.. _Discord Chat: https://discord.gg/pallets
.. _GitHub Discussions: https://github.com/pallets/flask/discussions
.. _Official Pallets Themes: https://pypi.org/project/Pallets-Sphinx-Themes/
.. _Pallets-Eco: https://github.com/pallets-eco
.. _EOL calendar: https://devguide.python.org/versions/

48
docs/extensions.rst
View file

@ -1,48 +0,0 @@
Extensions
==========
Extensions are extra packages that add functionality to a Flask
application. For example, an extension might add support for sending
email or connecting to a database. Some extensions add entire new
frameworks to help build certain types of applications, like a REST API.
Finding Extensions
------------------
Flask extensions are usually named "Flask-Foo" or "Foo-Flask". You can
search PyPI for packages tagged with `Framework :: Flask <pypi_>`_.
Using Extensions
----------------
Consult each extension's documentation for installation, configuration,
and usage instructions. Generally, extensions pull their own
configuration from :attr:`app.config <flask.Flask.config>` and are
passed an application instance during initialization. For example,
an extension called "Flask-Foo" might be used like this::
from flask_foo import Foo
foo = Foo()
app = Flask(__name__)
app.config.update(
FOO_BAR='baz',
FOO_SPAM='eggs',
)
foo.init_app(app)
Building Extensions
-------------------
While `PyPI <pypi_>`_ contains many Flask extensions, you may not find
an extension that fits your need. If this is the case, you can create
your own, and publish it for others to use as well. Read
:doc:`extensiondev` to develop your own Flask extension.
.. _pypi: https://pypi.org/search/?c=Framework+%3A%3A+Flask

86
docs/flaskext.py Normal file
View file

@ -0,0 +1,86 @@
# flasky extensions. flasky pygments style based on tango style
from pygments.style import Style
from pygments.token import Keyword, Name, Comment, String, Error, \
Number, Operator, Generic, Whitespace, Punctuation, Other, Literal
class FlaskyStyle(Style):
background_color = "#f8f8f8"
default_style = ""
styles = {
# No corresponding class for the following:
#Text: "", # class: ''
Whitespace: "underline #f8f8f8", # class: 'w'
Error: "#a40000 border:#ef2929", # class: 'err'
Other: "#000000", # class 'x'
Comment: "italic #8f5902", # class: 'c'
Comment.Preproc: "noitalic", # class: 'cp'
Keyword: "bold #004461", # class: 'k'
Keyword.Constant: "bold #004461", # class: 'kc'
Keyword.Declaration: "bold #004461", # class: 'kd'
Keyword.Namespace: "bold #004461", # class: 'kn'
Keyword.Pseudo: "bold #004461", # class: 'kp'
Keyword.Reserved: "bold #004461", # class: 'kr'
Keyword.Type: "bold #004461", # class: 'kt'
Operator: "#582800", # class: 'o'
Operator.Word: "bold #004461", # class: 'ow' - like keywords
Punctuation: "bold #000000", # class: 'p'
# because special names such as Name.Class, Name.Function, etc.
# are not recognized as such later in the parsing, we choose them
# to look the same as ordinary variables.
Name: "#000000", # class: 'n'
Name.Attribute: "#c4a000", # class: 'na' - to be revised
Name.Builtin: "#004461", # class: 'nb'
Name.Builtin.Pseudo: "#3465a4", # class: 'bp'
Name.Class: "#000000", # class: 'nc' - to be revised
Name.Constant: "#000000", # class: 'no' - to be revised
Name.Decorator: "#888", # class: 'nd' - to be revised
Name.Entity: "#ce5c00", # class: 'ni'
Name.Exception: "bold #cc0000", # class: 'ne'
Name.Function: "#000000", # class: 'nf'
Name.Property: "#000000", # class: 'py'
Name.Label: "#f57900", # class: 'nl'
Name.Namespace: "#000000", # class: 'nn' - to be revised
Name.Other: "#000000", # class: 'nx'
Name.Tag: "bold #004461", # class: 'nt' - like a keyword
Name.Variable: "#000000", # class: 'nv' - to be revised
Name.Variable.Class: "#000000", # class: 'vc' - to be revised
Name.Variable.Global: "#000000", # class: 'vg' - to be revised
Name.Variable.Instance: "#000000", # class: 'vi' - to be revised
Number: "#990000", # class: 'm'
Literal: "#000000", # class: 'l'
Literal.Date: "#000000", # class: 'ld'
String: "#4e9a06", # class: 's'
String.Backtick: "#4e9a06", # class: 'sb'
String.Char: "#4e9a06", # class: 'sc'
String.Doc: "italic #8f5902", # class: 'sd' - like a comment
String.Double: "#4e9a06", # class: 's2'
String.Escape: "#4e9a06", # class: 'se'
String.Heredoc: "#4e9a06", # class: 'sh'
String.Interpol: "#4e9a06", # class: 'si'
String.Other: "#4e9a06", # class: 'sx'
String.Regex: "#4e9a06", # class: 'sr'
String.Single: "#4e9a06", # class: 's1'
String.Symbol: "#4e9a06", # class: 'ss'
Generic: "#000000", # class: 'g'
Generic.Deleted: "#a40000", # class: 'gd'
Generic.Emph: "italic #000000", # class: 'ge'
Generic.Error: "#ef2929", # class: 'gr'
Generic.Heading: "bold #000080", # class: 'gh'
Generic.Inserted: "#00A000", # class: 'gi'
Generic.Output: "#888", # class: 'go'
Generic.Prompt: "#745334", # class: 'gp'
Generic.Strong: "bold #000000", # class: 'gs'
Generic.Subheading: "bold #800080", # class: 'gu'
Generic.Traceback: "bold #a40000", # class: 'gt'
}

118
docs/flaskstyle.sty Normal file
View file

@ -0,0 +1,118 @@
\definecolor{TitleColor}{rgb}{0,0,0}
\definecolor{InnerLinkColor}{rgb}{0,0,0}
\renewcommand{\maketitle}{%
\begin{titlepage}%
\let\footnotesize\small
\let\footnoterule\relax
\ifsphinxpdfoutput
\begingroup
% This \def is required to deal with multi-line authors; it
% changes \\ to ', ' (comma-space), making it pass muster for
% generating document info in the PDF file.
\def\\{, }
\pdfinfo{
/Author (\@author)
/Title (\@title)
}
\endgroup
\fi
\begin{flushright}%
%\sphinxlogo%
{\center
\vspace*{3cm}
\includegraphics{logo.pdf}
\vspace{3cm}
\par
{\rm\Huge \@title \par}%
{\em\LARGE \py@release\releaseinfo \par}
{\large
\@date \par
\py@authoraddress \par
}}%
\end{flushright}%\par
\@thanks
\end{titlepage}%
\cleardoublepage%
\setcounter{footnote}{0}%
\let\thanks\relax\let\maketitle\relax
%\gdef\@thanks{}\gdef\@author{}\gdef\@title{}
}
\fancypagestyle{normal}{
\fancyhf{}
\fancyfoot[LE,RO]{{\thepage}}
\fancyfoot[LO]{{\nouppercase{\rightmark}}}
\fancyfoot[RE]{{\nouppercase{\leftmark}}}
\fancyhead[LE,RO]{{ \@title, \py@release}}
\renewcommand{\headrulewidth}{0.4pt}
\renewcommand{\footrulewidth}{0.4pt}
}
\fancypagestyle{plain}{
\fancyhf{}
\fancyfoot[LE,RO]{{\thepage}}
\renewcommand{\headrulewidth}{0pt}
\renewcommand{\footrulewidth}{0.4pt}
}
\titleformat{\section}{\Large}%
{\py@TitleColor\thesection}{0.5em}{\py@TitleColor}{\py@NormalColor}
\titleformat{\subsection}{\large}%
{\py@TitleColor\thesubsection}{0.5em}{\py@TitleColor}{\py@NormalColor}
\titleformat{\subsubsection}{}%
{\py@TitleColor\thesubsubsection}{0.5em}{\py@TitleColor}{\py@NormalColor}
\titleformat{\paragraph}{\large}%
{\py@TitleColor}{0em}{\py@TitleColor}{\py@NormalColor}
\ChNameVar{\raggedleft\normalsize}
\ChNumVar{\raggedleft \bfseries\Large}
\ChTitleVar{\raggedleft \rm\Huge}
\renewcommand\thepart{\@Roman\c@part}
\renewcommand\part{%
\pagestyle{empty}
\if@noskipsec \leavevmode \fi
\cleardoublepage
\vspace*{6cm}%
\@afterindentfalse
\secdef\@part\@spart}
\def\@part[#1]#2{%
\ifnum \c@secnumdepth >\m@ne
\refstepcounter{part}%
\addcontentsline{toc}{part}{\thepart\hspace{1em}#1}%
\else
\addcontentsline{toc}{part}{#1}%
\fi
{\parindent \z@ %\center
\interlinepenalty \@M
\normalfont
\ifnum \c@secnumdepth >\m@ne
\rm\Large \partname~\thepart
\par\nobreak
\fi
\MakeUppercase{\rm\Huge #2}%
\markboth{}{}\par}%
\nobreak
\vskip 8ex
\@afterheading}
\def\@spart#1{%
{\parindent \z@ %\center
\interlinepenalty \@M
\normalfont
\huge \bfseries #1\par}%
\nobreak
\vskip 3ex
\@afterheading}
% use inconsolata font
\usepackage{inconsolata}
% fix single quotes, for inconsolata. (does not work)
%%\usepackage{textcomp}
%%\begingroup
%% \catcode`'=\active
%% \g@addto@macro\@noligs{\let'\textsinglequote}
%% \endgroup
%%\endinput

91
docs/foreword.rst Normal file
View file

@ -0,0 +1,91 @@
Foreword
========
Read this before you get started with Flask. This hopefully answers some
questions about the intention of the project, what it aims at and when you
should or should not be using it.
What does Micro Mean?
---------------------
The micro in microframework for me means on the one hand being small in
size and complexity but on the other hand also that the complexity of the
applications that are written with these frameworks do not exceed a
certain size. A microframework like Flask sacrifices a few things in
order to be approachable and to be as concise as possible.
For example Flask uses thread local objects internally so that you don't
have to pass objects around from function to function within a request in
order to stay threadsafe. While this is a really easy approach and saves
you a lot of time, it also does not scale well to large applications.
It's especially painful for more complex unittests and when you suddenly
have to deal with code being executed outside of the context of a request
(for example if you have cronjobs).
Flask provides some tools to deal with the downsides of this approach but
the core problem of this approach obviously stays. It is also based on
convention over configuration which means that a lot of things are
preconfigured in Flask and will work well for smaller applications but not
so much for larger ones (where and how it looks for templates, static
files etc.)
But don't worry if your application suddenly grows larger than it was
initially and you're afraid Flask might not grow with it. Even with
larger frameworks you sooner or later will find out that you need
something the framework just cannot do for you without modification.
If you are ever in that situation, check out the :ref:`becomingbig`
chapter.
A Framework and An Example
--------------------------
Flask is not only a microframework, it is also an example. Based on
Flask, there will be a series of blog posts that explain how to create a
framework. Flask itself is just one way to implement a framework on top
of existing libraries. Unlike many other microframeworks Flask does not
try to implement anything on its own, it reuses existing code.
Web Development is Dangerous
----------------------------
I'm not even joking. Well, maybe a little. If you write a web
application you are probably allowing users to register and leave their
data on your server. The users are entrusting you with data. And even if
you are the only user that might leave data in your application, you still
want that data to be stored in a secure manner.
Unfortunately there are many ways security of a web application can be
compromised. Flask protects you against one of the most common security
problems of modern web applications: cross site scripting (XSS). Unless
you deliberately mark insecure HTML as secure Flask (and the underlying
Jinja2 template engine) have you covered. But there are many more ways to
cause security problems.
Whenever something is dangerous where you have to watch out, the
documentation will tell you so. Some of the security concerns of web
development are far more complex than one might think and often we all end
up in situations where we think "well, this is just far fetched, how could
that possibly be exploited" and then an intelligent guy comes along and
figures a way out to exploit that application. And don't think, your
application is not important enough for hackers to take notice. Depending
on the kind of attack, chances are there are automated botnets out there
trying to figure out how to fill your database with viagra advertisements.
So always keep that in mind when doing web development.
Target Audience
---------------
Is Flask for you? If your application small-ish and does not depend on
too complex database structures, Flask is the Framework for you. It was
designed from the ground up to be easy to use, based on established
principles, good intentions and on top of two established libraries in
widespread usage. Recent versions of Flask scale nicely within reasonable
bounds and if you grow larger, you won't have any troubles adjusting Flask
for your new application size.
If you suddenly discover that your application grows larger than
originally intended, head over to the :ref:`becomingbig` section to see
some possible solutions for larger applications.
Satisfied? Then head over to the :ref:`installation`.

125
docs/gevent.rst
View file

@ -1,125 +0,0 @@
Async with Gevent
=================
`Gevent`_ patches Python's standard library to run within special async workers
called `greenlets`_. Gevent has existed since long before Python's native
asyncio was available, and Flask has always worked with it.
.. _gevent: https://www.gevent.org
.. _greenlets: https://greenlet.readthedocs.io
Gevent is a reliable way to handle numerous, long lived, concurrent connections,
and to achieve similar capabilities to ASGI and asyncio. This works without
needing to write ``async def`` or ``await`` anywhere, but relies on gevent and
greenlet's low level manipulation of the Python interpreter.
Deciding whether you should use gevent with Flask, or `Quart`_, or something
else, is ultimately up to understanding the specific needs of your project.
.. _quart: https://quart.palletsprojects.com
Enabling gevent
---------------
You need to apply gevent's patching as early as possible in your code. This
enables gevent's underlying event loop and converts many Python internals to run
inside it. Add the following at the top of your project's module or top
``__init__.py``:
.. code-block:: python
import gevent.monkey
gevent.monkey.patch_all()
When deploying in production, use :doc:`/deploying/gunicorn` or
:doc:`/deploying/uwsgi` with a gevent worker, as described on those pages.
To run concurrent tasks within your own code, such as views, use
|gevent.spawn|_:
.. |gevent.spawn| replace:: ``gevent.spawn()``
.. _gevent.spawn: https://www.gevent.org/api/gevent.html#gevent.spawn
.. code-block:: python
@app.post("/send")
def send_email():
gevent.spawn(email.send, to="example@example.example", text="example")
return "Email is being sent."
If you need to access :data:`request` or other Flask context globals within the
spawned function, decorate the function with :func:`.stream_with_context` or
:func:`.copy_current_request_context`. Prefer passing the exact data you need
when spawning the function, rather than using the decorators.
.. note::
When using gevent, greenlet>=1.0 is required. When using PyPy, PyPy>=7.3.7
is required.
.. _gevent-asyncio:
Combining with ``async``/``await``
----------------------------------
Gevent's patching does not interact well with Flask's built-in asyncio support.
If you want to use Gevent and asyncio in the same app, you'll need to override
:meth:`flask.Flask.async_to_sync` to run async functions inside gevent.
.. code-block:: python
import gevent.monkey
gevent.monkey.patch_all()
import asyncio
from flask import Flask, request
loop = asyncio.EventLoop()
gevent.spawn(loop.run_forever)
class GeventFlask(Flask):
def async_to_sync(self, func):
def run(*args, **kwargs):
coro = func(*args, **kwargs)
future = asyncio.run_coroutine_threadsafe(coro, loop)
return future.result()
return run
app = GeventFlask(__name__)
@app.get("/")
async def greet():
await asyncio.sleep(1)
return f"Hello, {request.args.get("name", "World")}!"
This starts an asyncio event loop in a gevent worker. Async functions are
scheduled on that event loop. This may still have limitations, and may need to
be modified further when using other asyncio implementations.
libuv
~~~~~
`libuv`_ is another event loop implementation that `gevent supports`_. There's
also a project called `uvloop`_ that enables libuv in asyncio. If you want to
use libuv, use gevent's support, not uvloop. It may be possible to further
modify the ``async_to_sync`` code from the previous section to work with uvloop,
but that's not currently known.
.. _libuv: https://libuv.org/
.. _gevent supports: https://www.gevent.org/loop_impls.html
.. _uvloop: https://uvloop.readthedocs.io/
To enable gevent's libuv support, add the following at the *very* top of your
code, before ``gevent.monkey.patch_all()``:
.. code-block:: python
import gevent
gevent.config.loop = "libuv"
import gevent.monkey
gevent.monkey.patch_all()

101
docs/index.rst
View file

@ -1,89 +1,30 @@
.. rst-class:: hide-header :orphan:
Welcome to Flask Welcome to Flask
================ ================
.. image:: _static/flask-name.svg .. image:: _static/logo-full.png
:align: center :alt: The Flask Logo with Subtitle
:height: 200px :class: floatingflask
Welcome to Flask's documentation. Flask is a lightweight WSGI web application framework. Welcome to Flask's documentation. This documentation is divided in
It is designed to make getting started quick and easy, with the ability to scale up to different parts. I would suggest to get started with the
complex applications. :ref:`installation` and then heading over to the :ref:`quickstart`.
Besides the quickstart there is also a more detailed :ref:`tutorial` that
shows how to create a complete (albeit small) application with Flask. If
you rather want to dive into all the internal parts of Flask, check out
the :ref:`api` documentation. Common patterns are described in the
:ref:`patterns` section.
Get started with :doc:`installation` Flask also depends on two external libraries: the `Jinja2`_ template
and then get an overview with the :doc:`quickstart`. There is also a engine and the `Werkzeug`_ WSGI toolkit. both of which are not documented
more detailed :doc:`tutorial/index` that shows how to create a small but here. If you want to dive into their documentation check out the
complete application with Flask. Common patterns are described in the following links:
:doc:`patterns/index` section. The rest of the docs describe each
component of Flask in detail, with a full reference in the :doc:`api`
section.
Flask depends on the `Werkzeug`_ WSGI toolkit, the `Jinja`_ template engine, and the - `Jinja2 Documentation <http://jinja.pocoo.org/2/documentation/>`_
`Click`_ CLI toolkit. Be sure to check their documentation as well as Flask's when - `Werkzeug Documentation <http://werkzeug.pocoo.org/documentation/>`_
looking for information.
.. _Werkzeug: https://werkzeug.palletsprojects.com .. _Jinja2: http://jinja.pocoo.org/2/
.. _Jinja: https://jinja.palletsprojects.com .. _Werkzeug: http://werkzeug.pocoo.org/
.. _Click: https://click.palletsprojects.com
.. include:: contents.rst.inc
User's Guide
------------
Flask provides configuration and conventions, with sensible defaults, to get started.
This section of the documentation explains the different parts of the Flask framework
and how they can be used, customized, and extended. Beyond Flask itself, look for
community-maintained extensions to add even more functionality.
.. toctree::
:maxdepth: 2
installation
quickstart
tutorial/index
templating
testing
errorhandling
debugging
logging
config
signals
views
lifecycle
appcontext
blueprints
extensions
cli
server
shell
patterns/index
web-security
deploying/index
gevent
async-await
API Reference
-------------
If you are looking for information on a specific function, class or
method, this part of the documentation is for you.
.. toctree::
:maxdepth: 2
api
Additional Notes
----------------
.. toctree::
:maxdepth: 2
design
extensiondev
contributing
license
changes

284
docs/installation.rst
View file

@ -1,143 +1,175 @@
.. _installation:
Installation Installation
============ ============
Flask is a microframework and yet it depends on external libraries. There
are various ways how you can install that library and this explains each
way and why there are multiple ways.
Python Version Flask depends on two external libraries: `Werkzeug
-------------- <http://werkzeug.pocoo.org/>`_ and `Jinja2 <http://jinja.pocoo.org/2/>`_.
The first one is responsible for interfacing WSGI the latter for rendering
templates. Now you are maybe asking, what is WSGI? WSGI is a standard
in Python that is basically responsible for ensuring that your application
is behaving in a specific way so that you can run it on different
environments (for example on a local development server, on an Apache2, on
lighttpd, on Google's App Engine or whatever you have in mind).
We recommend using the latest version of Python. Flask supports Python 3.10 and newer. So how do you get all that on your computer in no time? The most kick-ass
method is virtualenv, so let's look at that first.
.. _virtualenv:
virtualenv
----------
Virtualenv is what you want to use during development and in production if
you have shell access. So first: what does virtualenv do? If you are
like me and you like Python, chances are you want to use it for another
project as well. Now the more projects you have, the more likely it is
that you will be working with different versions of Python itself or at
least an individual library. Because let's face it: quite often libraries
break backwards compatibility and it's unlikely that your application will
not have any dependencies, that just won't happen. So virtualenv to the
rescue!
It basically makes it possible to have multiple side-by-side
"installations" of Python, each for your own project. It's not actually
an installation but a clever way to keep things separated.
So let's see how that works!
If you are on OS X or Linux chances are that one of the following two
commands will work for you::
$ sudo easy_install virtualenv
or even better::
$ sudo pip install virtualenv
Chances are you have virtualenv installed on your system then. Maybe it's
even in your package manager (on ubuntu try ``sudo apt-get install
python-virtualenv``).
If you are on Windows and missing the `easy_install` command you have to
install it first. Check the :ref:`windows-easy-install` section for more
information about how to do that. Once you have it installed, run the
same commands as above, but without the `sudo` part.
So now that you have virtualenv running just fire up a shell and create
your own environment. I usually create a folder and a `env` folder
within::
$ mkdir myproject
$ cd myproject
$ virtualenv env
New python executable in env/bin/python
Installing setuptools............done.
Now you only have to activate it, whenever you work with it. On OS X and
Linux do the following::
$ . env/bin/activate
(Note the whitespace between the dot and the script name. This means
execute this file in context of the shell. If the dot does not work for
whatever reason in your shell, try substituting it with ``source``)
If you are a Windows user, the following command is for you::
$ env\scripts\activate
Either way, you should now be using your virtualenv (see how the prompt of
your shell has changed to show the virtualenv).
Now you can just enter the following command to get Flask activated in
your virtualenv::
$ easy_install Flask
A few seconds later you are good to go.
Dependencies System Wide Installation
------------ ------------------------
These distributions will be installed automatically when installing Flask. This is possible as well, but I would not recommend it. Just run
`easy_install` with root rights::
* `Werkzeug`_ implements WSGI, the standard Python interface between sudo easy_install Flask
applications and servers.
* `Jinja`_ is a template language that renders the pages your application
serves.
* `MarkupSafe`_ comes with Jinja. It escapes untrusted input when rendering
templates to avoid injection attacks.
* `ItsDangerous`_ securely signs data to ensure its integrity. This is used
to protect Flask's session cookie.
* `Click`_ is a framework for writing command line applications. It provides
the ``flask`` command and allows adding custom management commands.
* `Blinker`_ provides support for :doc:`signals`.
.. _Werkzeug: https://palletsprojects.com/p/werkzeug/ (Run it in an Admin shell on Windows systems and without the `sudo`).
.. _Jinja: https://palletsprojects.com/p/jinja/
.. _MarkupSafe: https://palletsprojects.com/p/markupsafe/
.. _ItsDangerous: https://palletsprojects.com/p/itsdangerous/
.. _Click: https://palletsprojects.com/p/click/
.. _Blinker: https://blinker.readthedocs.io/
Optional dependencies Living on the Edge
~~~~~~~~~~~~~~~~~~~~~ ------------------
These distributions will not be installed automatically. Flask will detect and You want to work with the latest version of Flask, there are two ways: you
use them if you install them. can either let `easy_install` pull in the development version or tell it
to operate on a git checkout. Either way it's recommended to do that in a
virtualenv.
* `python-dotenv`_ enables support for :ref:`dotenv` when running ``flask`` Get the git checkout in a new virtualenv and run in develop mode::
commands.
* `Watchdog`_ provides a faster, more efficient reloader for the development
server.
.. _python-dotenv: https://github.com/theskumar/python-dotenv#readme $ git clone http://github.com/mitsuhiko/flask.git
.. _watchdog: https://pythonhosted.org/watchdog/ Initialized empty Git repository in ~/dev/flask/.git/
$ cd flask
$ virtualenv env
$ . env/bin/activate
New python executable in env/bin/python
Installing setuptools............done.
$ python setup.py develop
...
Finished processing dependencies for Flask
This will pull in the dependencies and activate the git head as current
version. Then you just have to ``git pull origin`` to get the latest
version.
To just get the development version without git, do this instead::
$ mkdir flask
$ cd flask
$ virtualenv env
$ . env/bin/activate
New python executable in env/bin/python
Installing setuptools............done.
$ easy_install Flask==dev
...
Finished processing dependencies for Flask==dev
.. _windows-easy-install:
`easy_install` on Windows
-------------------------
On Windows installation of `easy_install` is a little bit tricker because
on Windows slightly different rules apply, but it's not a biggy. The
easiest way to accomplish that is downloading the `ez_setup.py`_ file and
running it. (Double clicking should do the trick)
Once you have done that it's important to add the `easy_install` command
and other Python scripts to the path. To do that you have to add the
Python installation's Script folder to the `PATH` variable.
To do that, right-click on your "Computer" desktop icon and click
"Properties". On Windows Vista and Windows 7 then click on "Advanced System
settings", on Windows XP click on the "Advanced" tab instead. Then click
on the "Environment variables" button and double click on the "Path"
variable in the "System variables" section.
There append the path of your Python interpreter's Script folder to the
end of the last (make sure you delimit it from existing values with a
semicolon). Assuming you are using Python 2.6 on the default path, add
the following value::
;C:\Python26\Scripts
Then you are done. To check that it worked, open the cmd and execute
"easy_install". If you have UAC enabled it should prompt you for admin
privileges.
greenlet .. _ez_setup.py: http://peak.telecommunity.com/dist/ez_setup.py
~~~~~~~~
You may choose to use :doc:`/gevent` with your application. In this case,
greenlet>=1.0 is required. When using PyPy, PyPy>=7.3.7 is required.
These are not minimum supported versions, they only indicate the first
versions that added necessary features. You should use the latest
versions of each.
Virtual environments
--------------------
Use a virtual environment to manage the dependencies for your project, both in
development and in production.
What problem does a virtual environment solve? The more Python projects you
have, the more likely it is that you need to work with different versions of
Python libraries, or even Python itself. Newer versions of libraries for one
project can break compatibility in another project.
Virtual environments are independent groups of Python libraries, one for each
project. Packages installed for one project will not affect other projects or
the operating system's packages.
Python comes bundled with the :mod:`venv` module to create virtual
environments.
.. _install-create-env:
Create an environment
~~~~~~~~~~~~~~~~~~~~~
Create a project folder and a :file:`.venv` folder within:
.. tabs::
.. group-tab:: macOS/Linux
.. code-block:: text
$ mkdir myproject
$ cd myproject
$ python3 -m venv .venv
.. group-tab:: Windows
.. code-block:: text
> mkdir myproject
> cd myproject
> py -3 -m venv .venv
.. _install-activate-env:
Activate the environment
~~~~~~~~~~~~~~~~~~~~~~~~
Before you work on your project, activate the corresponding environment:
.. tabs::
.. group-tab:: macOS/Linux
.. code-block:: text
$ . .venv/bin/activate
.. group-tab:: Windows
.. code-block:: text
> .venv\Scripts\activate
Your shell prompt will change to show the name of the activated
environment.
Install Flask
-------------
Within the activated environment, use the following command to install
Flask:
.. code-block:: sh
$ pip install Flask
Flask is now installed. Check out the :doc:`/quickstart` or go to the
:doc:`Documentation Overview </index>`.

6
docs/latexindex.rst Normal file
View file

@ -0,0 +1,6 @@
:orphan:
Flask Documentation
===================
.. include:: contents.rst.inc

24
docs/license.rst
View file

@ -1,5 +1,21 @@
BSD-3-Clause License License
==================== =======
.. literalinclude:: ../LICENSE.txt Flask is licensed under a three clause `BSD License`_. It basically
:language: text means: do whatever you want with it as long as the copyright in Flask
sticks around, the conditions are not modified and the disclaimer is
present. Furthermore you must not use the names of the authors to promote
derivates of the software without written consent.
.. _BSD License:
http://en.wikipedia.org/wiki/BSD_licenses#3-clause_license_.28.22New_BSD_License.22.29
Authors
-------
.. include:: ../AUTHORS
License Text
------------
.. include:: ../LICENSE

171
docs/lifecycle.rst
View file

@ -1,171 +0,0 @@
Application Structure and Lifecycle
===================================
Flask makes it pretty easy to write a web application. But there are quite a few
different parts to an application and to each request it handles. Knowing what happens
during application setup, serving, and handling requests will help you know what's
possible in Flask and how to structure your application.
Application Setup
-----------------
The first step in creating a Flask application is creating the application object. Each
Flask application is an instance of the :class:`.Flask` class, which collects all
configuration, extensions, and views.
.. code-block:: python
from flask import Flask
app = Flask(__name__)
app.config.from_mapping(
SECRET_KEY="dev",
)
app.config.from_prefixed_env()
@app.route("/")
def index():
return "Hello, World!"
This is known as the "application setup phase", it's the code you write that's outside
any view functions or other handlers. It can be split up between different modules and
sub-packages, but all code that you want to be part of your application must be imported
in order for it to be registered.
All application setup must be completed before you start serving your application and
handling requests. This is because WSGI servers divide work between multiple workers, or
can be distributed across multiple machines. If the configuration changed in one worker,
there's no way for Flask to ensure consistency between other workers.
Flask tries to help developers catch some of these setup ordering issues by showing an
error if setup-related methods are called after requests are handled. In that case
you'll see this error:
The setup method 'route' can no longer be called on the application. It has already
handled its first request, any changes will not be applied consistently.
Make sure all imports, decorators, functions, etc. needed to set up the application
are done before running it.
However, it is not possible for Flask to detect all cases of out-of-order setup. In
general, don't do anything to modify the ``Flask`` app object and ``Blueprint`` objects
from within view functions that run during requests. This includes:
- Adding routes, view functions, and other request handlers with ``@app.route``,
``@app.errorhandler``, ``@app.before_request``, etc.
- Registering blueprints.
- Loading configuration with ``app.config``.
- Setting up the Jinja template environment with ``app.jinja_env``.
- Setting a session interface, instead of the default itsdangerous cookie.
- Setting a JSON provider with ``app.json``, instead of the default provider.
- Creating and initializing Flask extensions.
Serving the Application
-----------------------
Flask is a WSGI application framework. The other half of WSGI is the WSGI server. During
development, Flask, through Werkzeug, provides a development WSGI server with the
``flask run`` CLI command. When you are done with development, use a production server
to serve your application, see :doc:`deploying/index`.
Regardless of what server you're using, it will follow the :pep:`3333` WSGI spec. The
WSGI server will be told how to access your Flask application object, which is the WSGI
application. Then it will start listening for HTTP requests, translate the request data
into a WSGI environ, and call the WSGI application with that data. The WSGI application
will return data that is translated into an HTTP response.
#. Browser or other client makes HTTP request.
#. WSGI server receives request.
#. WSGI server converts HTTP data to WSGI ``environ`` dict.
#. WSGI server calls WSGI application with the ``environ``.
#. Flask, the WSGI application, does all its internal processing to route the request
to a view function, handle errors, etc.
#. Flask translates View function return into WSGI response data, passes it to WSGI
server.
#. WSGI server creates and send an HTTP response.
#. Client receives the HTTP response.
Middleware
~~~~~~~~~~
The WSGI application above is a callable that behaves in a certain way. Middleware
is a WSGI application that wraps another WSGI application. It's a similar concept to
Python decorators. The outermost middleware will be called by the server. It can modify
the data passed to it, then call the WSGI application (or further middleware) that it
wraps, and so on. And it can take the return value of that call and modify it further.
From the WSGI server's perspective, there is one WSGI application, the one it calls
directly. Typically, Flask is the "real" application at the end of the chain of
middleware. But even Flask can call further WSGI applications, although that's an
advanced, uncommon use case.
A common middleware you'll see used with Flask is Werkzeug's
:class:`~werkzeug.middleware.proxy_fix.ProxyFix`, which modifies the request to look
like it came directly from a client even if it passed through HTTP proxies on the way.
There are other middleware that can handle serving static files, authentication, etc.
How a Request is Handled
------------------------
For us, the interesting part of the steps above is when Flask gets called by the WSGI
server (or middleware). At that point, it will do quite a lot to handle the request and
generate the response. At the most basic, it will match the URL to a view function, call
the view function, and pass the return value back to the server. But there are many more
parts that you can use to customize its behavior.
#. WSGI server calls the Flask object, which calls :meth:`.Flask.wsgi_app`.
#. An :class:`.AppContext` object is created. This converts the WSGI ``environ``
dict into a :class:`.Request` object.
#. The :doc:`app context <appcontext>` is pushed, which makes
:data:`.current_app`, :data:`.g`, :data:`.request`, and :data:`.session`
available.
#. The :data:`.appcontext_pushed` signal is sent.
#. The URL is matched against the URL rules registered with the :meth:`~.Flask.route`
decorator during application setup. If there is no match, the error - usually a 404,
405, or redirect - is stored to be handled later.
#. The :data:`.request_started` signal is sent.
#. Any :meth:`~.Flask.url_value_preprocessor` decorated functions are called.
#. Any :meth:`~.Flask.before_request` decorated functions are called. If any of
these function returns a value it is treated as the response immediately.
#. If the URL didn't match a route a few steps ago, that error is raised now.
#. The :meth:`~.Flask.route` decorated view function associated with the matched URL
is called and returns a value to be used as the response.
#. If any step so far raised an exception, and there is an :meth:`~.Flask.errorhandler`
decorated function that matches the exception class or HTTP error code, it is
called to handle the error and return a response.
#. Whatever returned a response value - a before request function, the view, or an
error handler, that value is converted to a :class:`.Response` object.
#. Any :func:`~.after_this_request` decorated functions are called, which can modify
the response object. They are then cleared.
#. Any :meth:`~.Flask.after_request` decorated functions are called, which can modify
the response object.
#. The session is saved, persisting any modified session data using the app's
:attr:`~.Flask.session_interface`.
#. The :data:`.request_finished` signal is sent.
#. If any step so far raised an exception, and it was not handled by an error handler
function, it is handled now. HTTP exceptions are treated as responses with their
corresponding status code, other exceptions are converted to a generic 500 response.
The :data:`.got_request_exception` signal is sent.
#. The response object's status, headers, and body are returned to the WSGI server.
#. Any :meth:`~.Flask.teardown_request` decorated functions are called.
#. The :data:`.request_tearing_down` signal is sent.
#. Any :meth:`~.Flask.teardown_appcontext` decorated functions are called.
#. The :data:`.appcontext_tearing_down` signal is sent.
#. The app context is popped, :data:`.current_app`, :data:`.g`, :data:`.request`,
and :data:`.session` are no longer available.
#. The :data:`.appcontext_popped` signal is sent.
When executing a CLI command or plain app context without request data, the same
order of steps is followed, omitting the steps that refer to the request.
A :class:`Blueprint` can add handlers for these events that are specific to the
blueprint. The handlers for a blueprint will run if the blueprint
owns the route that matches the request.
There are even more decorators and customization points than this, but that aren't part
of every request lifecycle. They're more specific to certain things you might use during
a request, such as templates, building URLs, or handling JSON data. See the rest of this
documentation, as well as the :doc:`api` to explore further.

183
docs/logging.rst
View file

@ -1,183 +0,0 @@
Logging
=======
Flask uses standard Python :mod:`logging`. Messages about your Flask
application are logged with :meth:`app.logger <flask.Flask.logger>`,
which takes the same name as :attr:`app.name <flask.Flask.name>`. This
logger can also be used to log your own messages.
.. code-block:: python
@app.route('/login', methods=['POST'])
def login():
user = get_user(request.form['username'])
if user.check_password(request.form['password']):
login_user(user)
app.logger.info('%s logged in successfully', user.username)
return redirect(url_for('index'))
else:
app.logger.info('%s failed to log in', user.username)
abort(401)
If you don't configure logging, Python's default log level is usually
'warning'. Nothing below the configured level will be visible.
Basic Configuration
-------------------
When you want to configure logging for your project, you should do it as soon
as possible when the program starts. If :meth:`app.logger <flask.Flask.logger>`
is accessed before logging is configured, it will add a default handler. If
possible, configure logging before creating the application object.
This example uses :func:`~logging.config.dictConfig` to create a logging
configuration similar to Flask's default, except for all logs::
from logging.config import dictConfig
dictConfig({
'version': 1,
'formatters': {'default': {
'format': '[%(asctime)s] %(levelname)s in %(module)s: %(message)s',
}},
'handlers': {'wsgi': {
'class': 'logging.StreamHandler',
'stream': 'ext://flask.logging.wsgi_errors_stream',
'formatter': 'default'
}},
'root': {
'level': 'INFO',
'handlers': ['wsgi']
}
})
app = Flask(__name__)
Default Configuration
`````````````````````
If you do not configure logging yourself, Flask will add a
:class:`~logging.StreamHandler` to :meth:`app.logger <flask.Flask.logger>`
automatically. During requests, it will write to the stream specified by the
WSGI server in ``environ['wsgi.errors']`` (which is usually
:data:`sys.stderr`). Outside a request, it will log to :data:`sys.stderr`.
Removing the Default Handler
````````````````````````````
If you configured logging after accessing
:meth:`app.logger <flask.Flask.logger>`, and need to remove the default
handler, you can import and remove it::
from flask.logging import default_handler
app.logger.removeHandler(default_handler)
Email Errors to Admins
----------------------
When running the application on a remote server for production, you probably
won't be looking at the log messages very often. The WSGI server will probably
send log messages to a file, and you'll only check that file if a user tells
you something went wrong.
To be proactive about discovering and fixing bugs, you can configure a
:class:`logging.handlers.SMTPHandler` to send an email when errors and higher
are logged. ::
import logging
from logging.handlers import SMTPHandler
mail_handler = SMTPHandler(
mailhost='127.0.0.1',
fromaddr='server-error@example.com',
toaddrs=['admin@example.com'],
subject='Application Error'
)
mail_handler.setLevel(logging.ERROR)
mail_handler.setFormatter(logging.Formatter(
'[%(asctime)s] %(levelname)s in %(module)s: %(message)s'
))
if not app.debug:
app.logger.addHandler(mail_handler)
This requires that you have an SMTP server set up on the same server. See the
Python docs for more information about configuring the handler.
Injecting Request Information
-----------------------------
Seeing more information about the request, such as the IP address, may help
debugging some errors. You can subclass :class:`logging.Formatter` to inject
your own fields that can be used in messages. You can change the formatter for
Flask's default handler, the mail handler defined above, or any other
handler. ::
from flask import has_request_context, request
from flask.logging import default_handler
class RequestFormatter(logging.Formatter):
def format(self, record):
if has_request_context():
record.url = request.url
record.remote_addr = request.remote_addr
else:
record.url = None
record.remote_addr = None
return super().format(record)
formatter = RequestFormatter(
'[%(asctime)s] %(remote_addr)s requested %(url)s\n'
'%(levelname)s in %(module)s: %(message)s'
)
default_handler.setFormatter(formatter)
mail_handler.setFormatter(formatter)
Other Libraries
---------------
Other libraries may use logging extensively, and you want to see relevant
messages from those logs too. The simplest way to do this is to add handlers
to the root logger instead of only the app logger. ::
from flask.logging import default_handler
root = logging.getLogger()
root.addHandler(default_handler)
root.addHandler(mail_handler)
Depending on your project, it may be more useful to configure each logger you
care about separately, instead of configuring only the root logger. ::
for logger in (
logging.getLogger(app.name),
logging.getLogger('sqlalchemy'),
logging.getLogger('other_package'),
):
logger.addHandler(default_handler)
logger.addHandler(mail_handler)
Werkzeug
````````
Werkzeug logs basic request/response information to the ``'werkzeug'`` logger.
If the root logger has no handlers configured, Werkzeug adds a
:class:`~logging.StreamHandler` to its logger.
Flask Extensions
````````````````
Depending on the situation, an extension may choose to log to
:meth:`app.logger <flask.Flask.logger>` or its own named logger. Consult each
extension's documentation for details.

BIN
docs/logo.pdf Normal file
View file

Binary file not shown.

142
docs/make.bat
View file

@ -1,35 +1,139 @@
@ECHO OFF @ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" ( if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build set SPHINXBUILD=sphinx-build
) )
set SOURCEDIR=.
set BUILDDIR=_build set BUILDDIR=_build
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
if NOT "%PAPER%" == "" (
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
)
if "%1" == "" goto help if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL if "%1" == "help" (
if errorlevel 9009 ( :help
echo. echo.Please use `make ^<target^>` where ^<target^> is one of
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx echo. html to make standalone HTML files
echo.installed, then set the SPHINXBUILD environment variable to point echo. dirhtml to make HTML files named index.html in directories
echo.to the full path of the 'sphinx-build' executable. Alternatively you echo. singlehtml to make a single large HTML file
echo.may add the Sphinx directory to PATH. echo. pickle to make pickle files
echo. echo. json to make JSON files
echo.If you don't have Sphinx installed, grab it from echo. htmlhelp to make HTML files and a HTML help project
echo.http://sphinx-doc.org/ echo. qthelp to make HTML files and a qthelp project
exit /b 1 echo. devhelp to make HTML files and a Devhelp project
echo. epub to make an epub
echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
echo. changes to make an overview over all changed/added/deprecated items
echo. linkcheck to check all external links for integrity
echo. doctest to run all doctests embedded in the documentation if enabled
goto end
) )
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% if "%1" == "clean" (
goto end for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
del /q /s %BUILDDIR%\*
goto end
)
:help if "%1" == "html" (
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/html.
goto end
)
if "%1" == "dirhtml" (
%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
goto end
)
if "%1" == "singlehtml" (
%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
goto end
)
if "%1" == "pickle" (
%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
echo.
echo.Build finished; now you can process the pickle files.
goto end
)
if "%1" == "json" (
%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
echo.
echo.Build finished; now you can process the JSON files.
goto end
)
if "%1" == "htmlhelp" (
%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
echo.
echo.Build finished; now you can run HTML Help Workshop with the ^
.hhp project file in %BUILDDIR%/htmlhelp.
goto end
)
if "%1" == "qthelp" (
%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
echo.
echo.Build finished; now you can run "qcollectiongenerator" with the ^
.qhcp project file in %BUILDDIR%/qthelp, like this:
echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Flask.qhcp
echo.To view the help file:
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Flask.ghc
goto end
)
if "%1" == "devhelp" (
%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% _build/devhelp
echo.
echo.Build finished.
goto end
)
if "%1" == "epub" (
%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
echo.
echo.Build finished. The epub file is in %BUILDDIR%/epub.
goto end
)
if "%1" == "latex" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
echo.
echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "changes" (
%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
echo.
echo.The overview file is in %BUILDDIR%/changes.
goto end
)
if "%1" == "linkcheck" (
%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
echo.
echo.Link check complete; look for any errors in the above output ^
or in %BUILDDIR%/linkcheck/output.txt.
goto end
)
if "%1" == "doctest" (
%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
echo.
echo.Testing of doctests in the sources finished, look at the ^
results in %BUILDDIR%/doctest/output.txt.
goto end
)
:end :end
popd

189
docs/patterns/appdispatch.rst
View file

@ -1,189 +0,0 @@
Application Dispatching
=======================
Application dispatching is the process of combining multiple Flask
applications on the WSGI level. You can combine not only Flask
applications but any WSGI application. This would allow you to run a
Django and a Flask application in the same interpreter side by side if
you want. The usefulness of this depends on how the applications work
internally.
The fundamental difference from :doc:`packages` is that in this case you
are running the same or different Flask applications that are entirely
isolated from each other. They run different configurations and are
dispatched on the WSGI level.
Working with this Document
--------------------------
Each of the techniques and examples below results in an ``application``
object that can be run with any WSGI server. For development, use the
``flask run`` command to start a development server. For production, see
:doc:`/deploying/index`.
.. code-block:: python
from flask import Flask
app = Flask(__name__)
@app.route('/')
def hello_world():
return 'Hello World!'
Combining Applications
----------------------
If you have entirely separated applications and you want them to work next
to each other in the same Python interpreter process you can take
advantage of the :class:`werkzeug.wsgi.DispatcherMiddleware`. The idea
here is that each Flask application is a valid WSGI application and they
are combined by the dispatcher middleware into a larger one that is
dispatched based on prefix.
For example you could have your main application run on ``/`` and your
backend interface on ``/backend``.
.. code-block:: python
from werkzeug.middleware.dispatcher import DispatcherMiddleware
from frontend_app import application as frontend
from backend_app import application as backend
application = DispatcherMiddleware(frontend, {
'/backend': backend
})
Dispatch by Subdomain
---------------------
Sometimes you might want to use multiple instances of the same application
with different configurations. Assuming the application is created inside
a function and you can call that function to instantiate it, that is
really easy to implement. In order to develop your application to support
creating new instances in functions have a look at the
:doc:`appfactories` pattern.
A very common example would be creating applications per subdomain. For
instance you configure your webserver to dispatch all requests for all
subdomains to your application and you then use the subdomain information
to create user-specific instances. Once you have your server set up to
listen on all subdomains you can use a very simple WSGI application to do
the dynamic application creation.
The perfect level for abstraction in that regard is the WSGI layer. You
write your own WSGI application that looks at the request that comes and
delegates it to your Flask application. If that application does not
exist yet, it is dynamically created and remembered.
.. code-block:: python
from threading import Lock
class SubdomainDispatcher:
def __init__(self, domain, create_app):
self.domain = domain
self.create_app = create_app
self.lock = Lock()
self.instances = {}
def get_application(self, host):
host = host.split(':')[0]
assert host.endswith(self.domain), 'Configuration error'
subdomain = host[:-len(self.domain)].rstrip('.')
with self.lock:
app = self.instances.get(subdomain)
if app is None:
app = self.create_app(subdomain)
self.instances[subdomain] = app
return app
def __call__(self, environ, start_response):
app = self.get_application(environ['HTTP_HOST'])
return app(environ, start_response)
This dispatcher can then be used like this:
.. code-block:: python
from myapplication import create_app, get_user_for_subdomain
from werkzeug.exceptions import NotFound
def make_app(subdomain):
user = get_user_for_subdomain(subdomain)
if user is None:
# if there is no user for that subdomain we still have
# to return a WSGI application that handles that request.
# We can then just return the NotFound() exception as
# application which will render a default 404 page.
# You might also redirect the user to the main page then
return NotFound()
# otherwise create the application for the specific user
return create_app(user)
application = SubdomainDispatcher('example.com', make_app)
Dispatch by Path
----------------
Dispatching by a path on the URL is very similar. Instead of looking at
the ``Host`` header to figure out the subdomain one simply looks at the
request path up to the first slash.
.. code-block:: python
from threading import Lock
from wsgiref.util import shift_path_info
class PathDispatcher:
def __init__(self, default_app, create_app):
self.default_app = default_app
self.create_app = create_app
self.lock = Lock()
self.instances = {}
def get_application(self, prefix):
with self.lock:
app = self.instances.get(prefix)
if app is None:
app = self.create_app(prefix)
if app is not None:
self.instances[prefix] = app
return app
def __call__(self, environ, start_response):
app = self.get_application(_peek_path_info(environ))
if app is not None:
shift_path_info(environ)
else:
app = self.default_app
return app(environ, start_response)
def _peek_path_info(environ):
segments = environ.get("PATH_INFO", "").lstrip("/").split("/", 1)
if segments:
return segments[0]
return None
The big difference between this and the subdomain one is that this one
falls back to another application if the creator function returns ``None``.
.. code-block:: python
from myapplication import create_app, default_app, get_user_for_prefix
def make_app(prefix):
user = get_user_for_prefix(prefix)
if user is not None:
return create_app(user)
application = PathDispatcher(default_app, make_app)

91
docs/patterns/appfactories.rst
View file

@ -1,11 +1,13 @@
.. _app-factories:
Application Factories Application Factories
===================== =====================
If you are already using packages and blueprints for your application If you are already using packages and modules for your application
(:doc:`/blueprints`) there are a couple of really nice ways to further improve (:ref:`packages`) there are couple of really nice ways to further improve
the experience. A common pattern is creating the application object when the experience. A common pattern is creating the application object when
the blueprint is imported. But if you move the creation of this object the module is imported. But if you move the creation of this object,
into a function, you can then create multiple instances of this app later. into a function, you can then create multiple instances of this and later.
So why would you want to do this? So why would you want to do this?
@ -28,23 +30,20 @@ The idea is to set up the application in a function. Like this::
app = Flask(__name__) app = Flask(__name__)
app.config.from_pyfile(config_filename) app.config.from_pyfile(config_filename)
from yourapplication.model import db
db.init_app(app)
from yourapplication.views.admin import admin from yourapplication.views.admin import admin
from yourapplication.views.frontend import frontend from yourapplication.views.frontend import frontend
app.register_blueprint(admin) app.register_module(admin)
app.register_blueprint(frontend) app.register_module(frontend)
return app return app
The downside is that you cannot use the application object in the blueprints The downside is that you cannot use the application object in the modules
at import time. You can however use it from within a request. How do you at import time. You can however use it from within a request. How do you
get access to the application with the config? Use get access the application with the config? Use
:data:`~flask.current_app`:: :data:`~flask.current_app`::
from flask import current_app, Blueprint, render_template from flask import current_app, Module, render_template
admin = Blueprint('admin', __name__, url_prefix='/admin') admin = Module(__name__, url_prefix='/admin')
@admin.route('/') @admin.route('/')
def index(): def index():
@ -52,67 +51,25 @@ get access to the application with the config? Use
Here we look up the name of a template in the config. Here we look up the name of a template in the config.
Factories & Extensions
----------------------
It's preferable to create your extensions and app factories so that the
extension object does not initially get bound to the application.
Using `Flask-SQLAlchemy <https://flask-sqlalchemy.palletsprojects.com/>`_,
as an example, you should not do something along those lines::
def create_app(config_filename):
app = Flask(__name__)
app.config.from_pyfile(config_filename)
db = SQLAlchemy(app)
But, rather, in model.py (or equivalent)::
db = SQLAlchemy()
and in your application.py (or equivalent)::
def create_app(config_filename):
app = Flask(__name__)
app.config.from_pyfile(config_filename)
from yourapplication.model import db
db.init_app(app)
Using this design pattern, no application-specific state is stored on the
extension object, so one extension object can be used for multiple apps.
For more information about the design of extensions refer to :doc:`/extensiondev`.
Using Applications Using Applications
------------------ ------------------
To run such an application, you can use the :command:`flask` command: So to use such an application you then have to create the application
first. Here an example `run.py` file that runs such an application::
.. code-block:: text from yourapplication import create_app
app = create_app('/path/to/config.cfg')
$ flask --app hello run app.run()
Flask will automatically detect the factory if it is named
``create_app`` or ``make_app`` in ``hello``. You can also pass arguments
to the factory like this:
.. code-block:: text
$ flask --app 'hello:create_app(local_auth=True)' run
Then the ``create_app`` factory in ``hello`` is called with the keyword
argument ``local_auth=True``. See :doc:`/cli` for more detail.
Factory Improvements Factory Improvements
-------------------- --------------------
The factory function above is not very clever, but you can improve it. The factory function from above is not very clever so far, you can improve
The following changes are straightforward to implement: it. The following changes are straightforward and possible:
1. Make it possible to pass in configuration values for unit tests so that 1. make it possible to pass in configuration values for unittests so that
you don't have to create config files on the filesystem. you don't have to create config files on the filesystem
2. Call a function from a blueprint when the application is setting up so 2. call a function from a module when the application is setting up so
that you have a place to modify attributes of the application (like that you have a place to modify attributes of the application (like
hooking in before/after request handlers etc.) hooking in before / after request handlers etc.)
3. Add in WSGI middlewares when the application is being created if necessary. 3. Add in WSGI middlewares when the application is creating if necessary.

61
docs/patterns/caching.rst
View file

@ -1,3 +1,5 @@
.. _caching-pattern:
Caching Caching
======= =======
@ -8,9 +10,60 @@ still be good enough if they were 5 minutes old. So then the idea is that
you actually put the result of that calculation into a cache for some you actually put the result of that calculation into a cache for some
time. time.
Flask itself does not provide caching for you, but `Flask-Caching`_, an Flask itself does not provide caching for you, but Werkzeug, one of the
extension for Flask does. Flask-Caching supports various backends, and it is libraries it is based on, has some very basic cache support. It supports
even possible to develop your own caching backend. multiple cache backends, normally you want to use a memcached server.
Setting up a Cache
------------------
.. _Flask-Caching: https://flask-caching.readthedocs.io/en/latest/ You create a cache object once and keep it around, similar to how
:class:`~flask.Flask` objects are created. If you are using the
development server you can create a
:class:`~werkzeug.contrib.cache.SimpleCache` object, that one is a simple
cache that keeps the item stored in the memory of the Python interpreter::
from werkzeug.contrib.cache import SimpleCache
cache = SimpleCache()
If you want to use memcached, make sure to have one of the memcache modules
supported (you get them from `PyPI <http://pypi.python.org/>`_) and a
memcached server running somewhere. This is how you connect to such an
memcached server then::
from werkzeug.contrib.cache import MemcachedCache
cache = MemcachedCache(['127.0.0.1:11211'])
If you are using App Engine, you can connect to the App Engine memcache
server easily::
from werkzeug.contrib.cache import GAEMemcachedCache
cache = GAEMemcachedCache()
Using a Cache
-------------
Now how can one use such a cache? There are two very important
operations: :meth:`~werkzeug.contrib.cache.BaseCache.get` and
:meth:`~werkzeug.contrib.cache.BaseCache.set`. This is how to use them:
To get an item from the cache call
:meth:`~werkzeug.contrib.cache.BaseCache.get` with a string as key name.
If something is in the cache, it is returned. Otherwise that function
will return `None`::
rv = cache.get('my-item')
To add items to the cache, use the :meth:`~werkzeug.contrib.cache.BaseCache.set`
method instead. The first argument is the key and the second the value
that should be set. Also a timeout can be provided after which the cache
will automatically remove item.
Here a full example how this looks like normally::
def get_my_item():
rv = cache.get('my-item')
if rv is None:
rv = calculate_value()
cache.set('my-item', rv, timeout=5 * 60)
return rv

242
docs/patterns/celery.rst
View file

@ -1,242 +0,0 @@
Background Tasks with Celery
============================
If your application has a long running task, such as processing some uploaded data or
sending email, you don't want to wait for it to finish during a request. Instead, use a
task queue to send the necessary data to another process that will run the task in the
background while the request returns immediately.
`Celery`_ is a powerful task queue that can be used for simple background tasks as well
as complex multi-stage programs and schedules. This guide will show you how to configure
Celery using Flask. Read Celery's `First Steps with Celery`_ guide to learn how to use
Celery itself.
.. _Celery: https://celery.readthedocs.io
.. _First Steps with Celery: https://celery.readthedocs.io/en/latest/getting-started/first-steps-with-celery.html
The Flask repository contains `an example <https://github.com/pallets/flask/tree/main/examples/celery>`_
based on the information on this page, which also shows how to use JavaScript to submit
tasks and poll for progress and results.
Install
-------
Install Celery from PyPI, for example using pip:
.. code-block:: text
$ pip install celery
Integrate Celery with Flask
---------------------------
You can use Celery without any integration with Flask, but it's convenient to configure
it through Flask's config, and to let tasks access the Flask application.
Celery uses similar ideas to Flask, with a ``Celery`` app object that has configuration
and registers tasks. While creating a Flask app, use the following code to create and
configure a Celery app as well.
.. code-block:: python
from celery import Celery, Task
def celery_init_app(app: Flask) -> Celery:
class FlaskTask(Task):
def __call__(self, *args: object, **kwargs: object) -> object:
with app.app_context():
return self.run(*args, **kwargs)
celery_app = Celery(app.name, task_cls=FlaskTask)
celery_app.config_from_object(app.config["CELERY"])
celery_app.set_default()
app.extensions["celery"] = celery_app
return celery_app
This creates and returns a ``Celery`` app object. Celery `configuration`_ is taken from
the ``CELERY`` key in the Flask configuration. The Celery app is set as the default, so
that it is seen during each request. The ``Task`` subclass automatically runs task
functions with a Flask app context active, so that services like your database
connections are available.
.. _configuration: https://celery.readthedocs.io/en/stable/userguide/configuration.html
Here's a basic ``example.py`` that configures Celery to use Redis for communication. We
enable a result backend, but ignore results by default. This allows us to store results
only for tasks where we care about the result.
.. code-block:: python
from flask import Flask
app = Flask(__name__)
app.config.from_mapping(
CELERY=dict(
broker_url="redis://localhost",
result_backend="redis://localhost",
task_ignore_result=True,
),
)
celery_app = celery_init_app(app)
Point the ``celery worker`` command at this and it will find the ``celery_app`` object.
.. code-block:: text
$ celery -A example worker --loglevel INFO
You can also run the ``celery beat`` command to run tasks on a schedule. See Celery's
docs for more information about defining schedules.
.. code-block:: text
$ celery -A example beat --loglevel INFO
Application Factory
-------------------
When using the Flask application factory pattern, call the ``celery_init_app`` function
inside the factory. It sets ``app.extensions["celery"]`` to the Celery app object, which
can be used to get the Celery app from the Flask app returned by the factory.
.. code-block:: python
def create_app() -> Flask:
app = Flask(__name__)
app.config.from_mapping(
CELERY=dict(
broker_url="redis://localhost",
result_backend="redis://localhost",
task_ignore_result=True,
),
)
app.config.from_prefixed_env()
celery_init_app(app)
return app
To use ``celery`` commands, Celery needs an app object, but that's no longer directly
available. Create a ``make_celery.py`` file that calls the Flask app factory and gets
the Celery app from the returned Flask app.
.. code-block:: python
from example import create_app
flask_app = create_app()
celery_app = flask_app.extensions["celery"]
Point the ``celery`` command to this file.
.. code-block:: text
$ celery -A make_celery worker --loglevel INFO
$ celery -A make_celery beat --loglevel INFO
Defining Tasks
--------------
Using ``@celery_app.task`` to decorate task functions requires access to the
``celery_app`` object, which won't be available when using the factory pattern. It also
means that the decorated tasks are tied to the specific Flask and Celery app instances,
which could be an issue during testing if you change configuration for a test.
Instead, use Celery's ``@shared_task`` decorator. This creates task objects that will
access whatever the "current app" is, which is a similar concept to Flask's blueprints
and app context. This is why we called ``celery_app.set_default()`` above.
Here's an example task that adds two numbers together and returns the result.
.. code-block:: python
from celery import shared_task
@shared_task(ignore_result=False)
def add_together(a: int, b: int) -> int:
return a + b
Earlier, we configured Celery to ignore task results by default. Since we want to know
the return value of this task, we set ``ignore_result=False``. On the other hand, a task
that didn't need a result, such as sending an email, wouldn't set this.
Calling Tasks
-------------
The decorated function becomes a task object with methods to call it in the background.
The simplest way is to use the ``delay(*args, **kwargs)`` method. See Celery's docs for
more methods.
A Celery worker must be running to run the task. Starting a worker is shown in the
previous sections.
.. code-block:: python
from flask import request
@app.post("/add")
def start_add() -> dict[str, object]:
a = request.form.get("a", type=int)
b = request.form.get("b", type=int)
result = add_together.delay(a, b)
return {"result_id": result.id}
The route doesn't get the task's result immediately. That would defeat the purpose by
blocking the response. Instead, we return the running task's result id, which we can use
later to get the result.
Getting Results
---------------
To fetch the result of the task we started above, we'll add another route that takes the
result id we returned before. We return whether the task is finished (ready), whether it
finished successfully, and what the return value (or error) was if it is finished.
.. code-block:: python
from celery.result import AsyncResult
@app.get("/result/<id>")
def task_result(id: str) -> dict[str, object]:
result = AsyncResult(id)
return {
"ready": result.ready(),
"successful": result.successful(),
"value": result.result if result.ready() else None,
}
Now you can start the task using the first route, then poll for the result using the
second route. This keeps the Flask request workers from being blocked waiting for tasks
to finish.
The Flask repository contains `an example <https://github.com/pallets/flask/tree/main/examples/celery>`_
using JavaScript to submit tasks and poll for progress and results.
Passing Data to Tasks
---------------------
The "add" task above took two integers as arguments. To pass arguments to tasks, Celery
has to serialize them to a format that it can pass to other processes. Therefore,
passing complex objects is not recommended. For example, it would be impossible to pass
a SQLAlchemy model object, since that object is probably not serializable and is tied to
the session that queried it.
Pass the minimal amount of data necessary to fetch or recreate any complex data within
the task. Consider a task that will run when the logged in user asks for an archive of
their data. The Flask request knows the logged in user, and has the user object queried
from the database. It got that by querying the database for a given id, so the task can
do the same thing. Pass the user's id rather than the user object.
.. code-block:: python
@shared_task
def generate_user_archive(user_id: str) -> None:
user = db.session.get(User, user_id)
...
generate_user_archive.delay(current_user.id)

44
docs/patterns/deferredcallbacks.rst
View file

@ -1,44 +0,0 @@
Deferred Request Callbacks
==========================
One of the design principles of Flask is that response objects are created and
passed down a chain of potential callbacks that can modify them or replace
them. When the request handling starts, there is no response object yet. It is
created as necessary either by a view function or by some other component in
the system.
What happens if you want to modify the response at a point where the response
does not exist yet? A common example for that would be a
:meth:`~flask.Flask.before_request` callback that wants to set a cookie on the
response object.
One way is to avoid the situation. Very often that is possible. For instance
you can try to move that logic into a :meth:`~flask.Flask.after_request`
callback instead. However, sometimes moving code there makes it
more complicated or awkward to reason about.
As an alternative, you can use :func:`~flask.after_this_request` to register
callbacks that will execute after only the current request. This way you can
defer code execution from anywhere in the application, based on the current
request.
At any time during a request, we can register a function to be called at the
end of the request. For example you can remember the current language of the
user in a cookie in a :meth:`~flask.Flask.before_request` callback::
from flask import request, after_this_request
@app.before_request
def detect_user_language():
language = request.cookies.get('user_lang')
if language is None:
language = guess_language_from_request()
# when the response exists, set a cookie with the language
@after_this_request
def remember_language(response):
response.set_cookie('user_lang', language)
return response
g.language = language

162
docs/patterns/distribute.rst Normal file
View file

@ -0,0 +1,162 @@
.. _distribute-deployment:
Deploying with Distribute
=========================
`distribute`_, formerly setuptools, is an extension library that is
commonly used to (like the name says) distribute Python libraries and
extensions. It extends distutils, a basic module installation system
shipped with Python to also support various more complex constructs that
make larger applications easier to distribute:
- **support for dependencies**: a library or application can declare a
list of other libraries it depends on which will be installed
automatically for you.
- **package registry**: setuptools registers your package with your
Python installation. This makes it possible to query information
provided by one package from another package. The best known feature of
this system is the entry point support which allows one package to
declare an "entry point" another package can hook into to extend the
other package.
- **installation manager**: `easy_install`, which comes with distribute
can install other libraries for you. You can also use `pip`_ which
sooner or later will replace `easy_install` which does more than just
installing packages for you.
Flask itself, and all the libraries you can find on the cheeseshop
are distributed with either distribute, the older setuptools or distutils.
In this case we assume your application is called
`yourapplication.py` and you are not using a module, but a :ref:`package
<larger-applications>`. Distributing resources with standard modules is
not supported by `distribute`_ so we will not bother with it. If you have
not yet converted your application into a package, head over to the
:ref:`larger-applications` pattern to see how this can be done.
Basic Setup Script
------------------
Because you have Flask running, you either have setuptools or distribute
available on your system anyways. If you do not, fear not, there is a
script to install it for you: `distribute_setup.py`_. Just download and
run with your Python interpreter.
Standard disclaimer applies: :ref:`you better use a virtualenv
<virtualenv>`.
Your setup code always goes into a file named `setup.py` next to your
application. The name of the file is only convention, but because
everybody will look for a file with that name, you better not change it.
Yes, even if you are using `distribute`, you are importing from a package
called `setuptools`. `distribute` is fully backwards compatible with
`setuptools`, so it also uses the same import name.
A basic `setup.py` file for a Flask application looks like this::
from setuptools import setup
setup(
name='Your Application',
version='1.0',
long_description=__doc__,
packages=['yourapplication'],
include_package_data=True,
zip_safe=False,
install_requires=['Flask']
)
Please keep in mind that you have to list subpackages explicitly. If you
want distribute to lookup the packages for you automatically, you can use
the `find_packages` function::
from setuptools import setup, find_packages
setup(
...
packages=find_packages()
)
Most parameters to the `setup` function should be self explanatory,
`include_package_data` and `zip_safe` might not be.
`include_package_data` tells distribute to look for a `MANIFEST.in` file
and install all the entries that match as package data. We will use this
to distribute the static files and templates along with the Python module
(see :ref:`distributing-resources`). The `zip_safe` flag can be used to
force or prevent zip Archive creation. In general you probably don't want
your packages to be installed as zip files because some tools do not
support them and they make debugging a lot harder.
.. _distributing-resources:
Distributing Resources
----------------------
If you try to install the package you just created, you will notice that
folders like `static` or `templates` are not installed for you. The
reason for this is that distribute does not know which files to add for
you. What you should do, is to create a `MANIFEST.in` file next to your
`setup.py` file. This file lists all the files that should be added to
your tarball::
recursive-include yourapplication/templates *
recursive-include yourapplication/static *
Don't forget that even if you enlist them in your `MANIFEST.in` file, they
won't be installed for you unless you set the `include_package_data`
parameter of the `setup` function to `True`!
Declaring Dependencies
----------------------
Dependencies are declared in the `install_requires` parameter as list.
Each item in that list is the name of a package that should be pulled from
PyPI on installation. By default it will always use the most recent
version, but you can also provide minimum and maximum version
requirements. Here some examples::
install_requires=[
'Flask>=0.2',
'SQLAlchemy>=0.6',
'BrokenPackage>=0.7,<=1.0'
]
I mentioned earlier that dependencies are pulled from PyPI. What if you
want to depend on a package that cannot be found on PyPI and won't be
because it is an internal package you don't want to share with anyone?
Just still do as if there was a PyPI entry for it and provide a list of
alternative locations where distribute should look for tarballs::
dependency_links=['http://example.com/yourfiles']
Make sure that page has a directory listing and the links on the page are
pointing to the actual tarballs with their correct filenames as this is
how distribute will find the files. If you have an internal company
server that contains the packages, provide the URL to that server there.
Installing / Developing
-----------------------
To install your application (ideally into a virtualenv) just run the
`setup.py` script with the `install` parameter. It will install your
application into the virtualenv's site-packages folder and also download
and install all dependencies::
$ python setup.py install
If you are developing on the package and also want the requirements to be
installed, you can use the `develop` command instead::
$ python setup.py develop
This has the advantage of just installing a link to the site-packages
folder instead of copying the data over. You can then continue to work on
the code without having to run `install` again after each change.
.. _distribute: http://pypi.python.org/pypi/distribute
.. _pip: http://pypi.python.org/pypi/pip
.. _distribute_setup.py: http://python-distribute.org/distribute_setup.py

77
docs/patterns/errorpages.rst Normal file
View file

@ -0,0 +1,77 @@
Custom Error Pages
==================
Flask comes with a handy :func:`~flask.abort` function that aborts a
request with an HTTP error code early. It will also provide a plain black
and white error page for you with a basic description, but nothing fancy.
Depening on the error code it is less or more likely for the user to
actually see such an error.
Common Error Codes
------------------
The following error codes are some that are often displayed to the user,
even if the application behaves correctly:
*404 Not Found*
The good old "chap, you made a mistake typing that URL" message. So
common that even novices to the internet know that 404 means: damn,
the thing I was looking for is not there. It's a very good idea to
make sure there is actually something useful on a 404 page, at least a
link back to the index.
*403 Forbidden*
If you have some kind of access control on your website, you will have
to send a 403 code for disallowed resources. So make sure the user
is not lost when he tries to access a resource he cannot access.
*410 Gone*
Did you know that there the "404 Not Found" has a brother named "410
Gone"? Few people actually implement that, but the idea is that
resources that previously existed and got deleted answer with 410
instead of 404. If you are not deleting documents permanently from
the database but just mark them as deleted, do the user a favour and
use the 410 code instead and display a message that what he was
looking for was deleted for all ethernity.
*500 Internal Server Error*
Usually happens on programming errors or if the server is overloaded.
A terrible good idea to have a nice page there, because your
application *will* fail sooner or later (see also:
:ref:`application-errors`).
Error Handlers
--------------
An error handler is a function, just like a view function, but it is
called when an error happens and is passed that error. The error is most
likely a :exc:`~werkzeug.exceptions.HTTPException`, but in one case it
can be a different error: a handler for internal server errors will be
passed other exception instances as well if they are uncought.
An error handler is registered with the :meth:`~flask.Flask.errorhandler`
decorator and the error code of the exception. Keep in mind that Flask
will *not* set the error code for you, so make sure to also provide the
HTTP status code when returning a response.
Here an example implementation for a "404 Page Not Found" exception::
from flask import render_template
@app.errorhandler(404)
def page_not_found(e):
return render_template('404.html'), 404
An example template might be this:
.. sourcecode:: html+jinja
{% extends "layout.html" %}
{% block title %}Page Not Found{% endblock %}
{% block body %}
<h1>Page Not Found</h1>
<p>What you were looking for is just not there.
<p><a href="{{ url_for('index') }}">go somewhere nice</a>
{% endblock %}

56
docs/patterns/favicon.rst
View file

@ -1,56 +0,0 @@
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
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
:file:`favicon.ico`.
Now, to get browsers to find your icon, the correct way is to add a link
tag in your HTML. So, for example:
.. sourcecode:: html+jinja
<link rel="shortcut icon" href="{{ url_for('static', filename='favicon.ico') }}">
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 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::
app.add_url_rule(
"/favicon.ico",
endpoint="favicon",
redirect_to=url_for("static", filename="favicon.ico"),
)
If you want to save the extra redirect request you can also write a view
using :func:`~flask.send_from_directory`::
import os
from flask import send_from_directory
@app.route('/favicon.ico')
def favicon():
return send_from_directory(os.path.join(app.root_path, 'static'),
'favicon.ico', mimetype='image/vnd.microsoft.icon')
We can leave out the explicit mimetype and it will be guessed, but we may
as well specify it to avoid the extra guessing, as it will always be the
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
web server's documentation.
See also
--------
* The `Favicon <https://en.wikipedia.org/wiki/Favicon>`_ article on
Wikipedia

144
docs/patterns/fileuploads.rst
View file

@ -1,3 +1,5 @@
.. _uploading-files:
Uploading Files Uploading Files
=============== ===============
@ -8,7 +10,7 @@ uploads is actually quite simple. It basically works like this:
and an ``<input type=file>`` is placed in that form. and an ``<input type=file>`` is placed in that form.
2. The application accesses the file from the :attr:`~flask.request.files` 2. The application accesses the file from the :attr:`~flask.request.files`
dictionary on the request object. dictionary on the request object.
3. use the :meth:`~werkzeug.datastructures.FileStorage.save` method of the file to save 3. use the :meth:`~werkzeug.FileStorage.save` method of the file to save
the file permanently somewhere on the filesystem. the file permanently somewhere on the filesystem.
A Gentle Introduction A Gentle Introduction
@ -19,62 +21,59 @@ specific upload folder and displays a file to the user. Let's look at the
bootstrapping code for our application:: bootstrapping code for our application::
import os import os
from flask import Flask, flash, request, redirect, url_for from flask import Flask, request, redirect, url_for
from werkzeug.utils import secure_filename from werkzeug import secure_filename
UPLOAD_FOLDER = '/path/to/the/uploads' UPLOAD_FOLDER = '/path/to/the/uploads'
ALLOWED_EXTENSIONS = {'txt', 'pdf', 'png', 'jpg', 'jpeg', 'gif'} ALLOWED_EXTENSIONS = set(['txt', 'pdf', 'png', 'jpg', 'jpeg', 'gif'])
app = Flask(__name__) app = Flask(__name__)
app.config['UPLOAD_FOLDER'] = UPLOAD_FOLDER app.add_url_rule('/uploads/<filename>', 'uploaded_file',
build_only=True)
So first we need a couple of imports. Most should be straightforward, the So first we need a couple of imports. Most should be straightforward, the
:func:`werkzeug.secure_filename` is explained a little bit later. The :func:`werkzeug.secure_filename` is explained a little bit later. The
``UPLOAD_FOLDER`` is where we will store the uploaded files and the `UPLOAD_FOLDER` is where we will store the uploaded files and the
``ALLOWED_EXTENSIONS`` is the set of allowed file extensions. `ALLOWED_EXTENSIONS` is the set of allowed file extensions. Then we add a
URL rule by hand to the application. Now usually we're not doing that, so
why here? The reasons is that we want the webserver (or our development
server) to serve these files for us and so we only need a rule to generate
the URL to these files.
Why do we limit the extensions that are allowed? You probably don't want Why do we limit the extensions that are allowed? You probably don't want
your users to be able to upload everything there if the server is directly your users to be able to upload everything there if the server is directly
sending out the data to the client. That way you can make sure that users sending out the data to the client. That way you can make sure that users
are not able to upload HTML files that would cause XSS problems (see are not able to upload HTML files that would cause XSS problems. Also
:ref:`security-xss`). Also make sure to disallow ``.php`` files if the server make sure to disallow `.php` files if the server executes them, but who
executes them, but who has PHP installed on their server, right? :) has PHP installed on his server, right? :)
Next the functions that check if an extension is valid and that uploads Next the functions that check if an extension is valid and that uploads
the file and redirects the user to the URL for the uploaded file:: the file and redirects the user to the URL for the uploaded file::
def allowed_file(filename): def allowed_file(filename):
return '.' in filename and \ return '.' in filename and \
filename.rsplit('.', 1)[1].lower() in ALLOWED_EXTENSIONS filename.rsplit('.', 1)[1] in ALLOWED_EXTENSIONS
@app.route('/', methods=['GET', 'POST']) @app.route('/', methods=['GET', 'POST'])
def upload_file(): def upload_file():
if request.method == 'POST': if request.method == 'POST':
# check if the post request has the file part
if 'file' not in request.files:
flash('No file part')
return redirect(request.url)
file = request.files['file'] file = request.files['file']
# If the user does not select a file, the browser submits an
# empty file without a filename.
if file.filename == '':
flash('No selected file')
return redirect(request.url)
if file and allowed_file(file.filename): if file and allowed_file(file.filename):
filename = secure_filename(file.filename) filename = secure_filename(file.filename)
file.save(os.path.join(app.config['UPLOAD_FOLDER'], filename)) file.save(os.path.join(UPLOAD_FOLDER, filename))
return redirect(url_for('download_file', name=filename)) return redirect(url_for('uploaded_file',
filename=filename))
return ''' return '''
<!doctype html> <!doctype html>
<title>Upload new File</title> <title>Upload new File</title>
<h1>Upload new File</h1> <h1>Upload new File</h1>
<form method=post enctype=multipart/form-data> <form action="" method=post enctype=multipart/form-data>
<input type=file name=file> <p><input type=file name=file>
<input type=submit value=Upload> <input type=submit value=Upload>
</form> </form>
''' '''
So what does that :func:`~werkzeug.utils.secure_filename` function actually do? So what does that :func:`~werkzeug.secure_filename` function actually do?
Now the problem is that there is that principle called "never trust user Now the problem is that there is that principle called "never trust user
input". This is also true for the filename of an uploaded file. All input". This is also true for the filename of an uploaded file. All
submitted form data can be forged, and filenames can be dangerous. For submitted form data can be forged, and filenames can be dangerous. For
@ -83,7 +82,7 @@ before storing it directly on the filesystem.
.. admonition:: Information for the Pros .. admonition:: Information for the Pros
So you're interested in what that :func:`~werkzeug.utils.secure_filename` So you're interested in what that :func:`~werkzeug.secure_filename`
function does and what the problem is if you're not using it? So just function does and what the problem is if you're not using it? So just
imagine someone would send the following information as `filename` to imagine someone would send the following information as `filename` to
your application:: your application::
@ -91,8 +90,8 @@ before storing it directly on the filesystem.
filename = "../../../../home/username/.bashrc" filename = "../../../../home/username/.bashrc"
Assuming the number of ``../`` is correct and you would join this with 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 the server's filesystem he should not modify. This does require some
knowledge about how the application looks like, but trust me, hackers knowledge about how the application looks like, but trust me, hackers
are patient :) are patient :)
@ -101,82 +100,61 @@ before storing it directly on the filesystem.
>>> secure_filename('../../../../home/username/.bashrc') >>> secure_filename('../../../../home/username/.bashrc')
'home_username_.bashrc' 'home_username_.bashrc'
We want to be able to serve the uploaded files so they can be downloaded Now if we run that application, you will notice that uploading works, but
by users. We'll define a ``download_file`` view to serve files in the you won't actually see that uploaded file. Well, you would have to
upload folder by name. ``url_for("download_file", name=name)`` generates configure the server to serve that file for you. This is not handy for
download URLs. development situations or when you are just too lazy to properly set up
the server. Would be nice to have the files still be available in that
situation, and that is really easy to do, just hook in a middleware::
.. code-block:: python from werkzeug import SharedDataMiddleware
app.wsgi_app = SharedDataMiddleware(app.wsgi_app, {
'/uploads': UPLOAD_FOLDER
})
from flask import send_from_directory If you now run the application everything should work as expected.
@app.route('/uploads/<name>')
def download_file(name):
return send_from_directory(app.config["UPLOAD_FOLDER"], name)
If you're using middleware or the HTTP server to serve files, you can
register the ``download_file`` endpoint as ``build_only`` so ``url_for``
will work without a view function.
.. code-block:: python
app.add_url_rule(
"/uploads/<name>", endpoint="download_file", build_only=True
)
Improving Uploads Improving Uploads
----------------- -----------------
.. versionadded:: 0.6
So how exactly does Flask handle uploads? Well it will store them in the So how exactly does Flask handle uploads? Well it will store them in the
webserver's memory if the files are reasonably small, otherwise in a webserver's memory if the files are reasonable small otherwise in a
temporary location (as returned by :func:`tempfile.gettempdir`). But how temporary location (as returned by :func:`tempfile.gettempdir`). But how
do you specify the maximum file size after which an upload is aborted? By do you specify the maximum file size after which an upload is aborted? By
default Flask will happily accept file uploads with an unlimited amount of default Flask will happily accept file uploads to an unlimited amount of
memory, but you can limit that by setting the ``MAX_CONTENT_LENGTH`` memory, but you can limit that by subclassing the request and overriding
config key:: the Werkzeug provided :attr:`~werkzeug.BaseRequest.max_form_memory_size`
attribute::
from flask import Flask, Request from flask import Flask, Request
class LimitedRequest(Request):
max_form_memory_size = 16 * 1024 * 1024
app = Flask(__name__) app = Flask(__name__)
app.config['MAX_CONTENT_LENGTH'] = 16 * 1000 * 1000 app.request_class = LimitedRequest
The code above will limit the maximum allowed payload to 16 megabytes. The code above will limited the maximum allowed payload to 16 megabytes.
If a larger file is transmitted, Flask will raise a If a larger file is transmitted, Flask will raise an
:exc:`~werkzeug.exceptions.RequestEntityTooLarge` exception. :exc:`~werkzeug.exceptions.RequestEntityTooLarge` exception.
.. admonition:: Connection Reset Issue
When using the local development server, you may get a connection
reset error instead of a 413 response. You will get the correct
status response when running the app with a production WSGI server.
This feature was added in Flask 0.6 but can be achieved in older versions
as well by subclassing the request object. For more information on that
consult the Werkzeug documentation on file handling.
Upload Progress Bars Upload Progress Bars
-------------------- --------------------
A while ago many developers had the idea to read the incoming file in A while ago many developers had the idea to read the incoming file in
small chunks and store the upload progress in the database to be able to small chunks and store the upload progress in the database to be able to
poll the progress with JavaScript from the client. The client asks the poll the progress with JavaScript from the client. Long story short: the
server every 5 seconds how much it has transmitted, but this is client asks the server every 5 seconds how much he has transmitted
something it should already know. already. Do you realize the irony? The client is asking for something he
should already know.
An Easier Solution 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:
Now there are better solutions that work faster and are more reliable. There - `Plupload <http://www.plupload.com/>`_ - HTML5, Java, Flash
are JavaScript libraries like jQuery_ that have form plugins to ease the - `SWFUpload <http://www.swfupload.org/>`_ - Flash
construction of progress bar. - `JumpLoader <http://jumploader.com/>`_ - Java
Because the common pattern for file uploads exists almost unchanged in all
applications dealing with uploads, there are also some Flask extensions that
implement a full fledged upload mechanism that allows controlling which
file extensions are allowed to be uploaded.
.. _jQuery: https://jquery.com/

57
docs/patterns/flashing.rst
View file

@ -1,26 +1,22 @@
.. _message-flashing-pattern:
Message Flashing Message Flashing
================ ================
Good applications and user interfaces are all about feedback. If the user Good applications and user interfaces are all about feedback. If the user
does not get enough feedback they will probably end up hating the does not get enough feedback he will probably end up hating the
application. Flask provides a really simple way to give feedback to a application. Flask provides a really simple way to give feedback to a
user with the flashing system. The flashing system basically makes it user with the flashing system. The flashing system basically makes it
possible to record a message at the end of a request and access it next possible to record a message at the end of a request and access it next
request and only next request. This is usually combined with a layout request and only next request. This is usually combined with a layout
template that does this. Note that browsers and sometimes web servers enforce template that does this.
a limit on cookie sizes. This means that flashing messages that are too
large for session cookies causes message flashing to fail silently.
Simple Flashing Simple Flashing
--------------- ---------------
So here is a full example:: So here a full example::
from flask import Flask, flash, redirect, render_template, \ from flask import flash, redirect, url_for, render_template
request, url_for
app = Flask(__name__)
app.secret_key = b'_5#y2L"F4Q8z\n\xec]/'
@app.route('/') @app.route('/')
def index(): def index():
@ -31,14 +27,14 @@ So here is a full example::
error = None error = None
if request.method == 'POST': if request.method == 'POST':
if request.form['username'] != 'admin' or \ if request.form['username'] != 'admin' or \
request.form['password'] != 'secret': request.form['password'] != 'secret':
error = 'Invalid credentials' error = 'Invalid credentials'
else: else:
flash('You were successfully logged in') flash('You were sucessfully logged in')
return redirect(url_for('index')) return redirect(url_for('index'))
return render_template('login.html', error=error) return render_template('login.html', error=error)
And here is the :file:`layout.html` template which does the magic: And here the ``layout.html`` template which does the magic:
.. sourcecode:: html+jinja .. sourcecode:: html+jinja
@ -55,7 +51,7 @@ And here is the :file:`layout.html` template which does the magic:
{% endwith %} {% endwith %}
{% block body %}{% endblock %} {% block body %}{% endblock %}
Here is the :file:`index.html` template which inherits from :file:`layout.html`: And here the index.html template:
.. sourcecode:: html+jinja .. sourcecode:: html+jinja
@ -65,8 +61,7 @@ Here is the :file:`index.html` template which inherits from :file:`layout.html`:
<p>Do you want to <a href="{{ url_for('login') }}">log in?</a> <p>Do you want to <a href="{{ url_for('login') }}">log in?</a>
{% endblock %} {% endblock %}
And here is the :file:`login.html` template which also inherits from And of course the login template:
:file:`layout.html`:
.. sourcecode:: html+jinja .. sourcecode:: html+jinja
@ -76,7 +71,7 @@ And here is the :file:`login.html` template which also inherits from
{% if error %} {% if error %}
<p class=error><strong>Error:</strong> {{ error }} <p class=error><strong>Error:</strong> {{ error }}
{% endif %} {% endif %}
<form method=post> <form action="" method=post>
<dl> <dl>
<dt>Username: <dt>Username:
<dd><input type=text name=username value="{{ <dd><input type=text name=username value="{{
@ -101,11 +96,11 @@ error messages could be displayed with a red background.
To flash a message with a different category, just use the second argument To flash a message with a different category, just use the second argument
to the :func:`~flask.flash` function:: to the :func:`~flask.flash` function::
flash('Invalid password provided', 'error') flash(u'Invalid password provided', 'error')
Inside the template you then have to tell the Inside the template you then have to tell the
:func:`~flask.get_flashed_messages` function to also return the :func:`~flask.get_flashed_messages` function to also return the
categories. The loop looks slightly different in that situation then: categories. The loop looks slighty different in that situation then:
.. sourcecode:: html+jinja .. sourcecode:: html+jinja
@ -122,27 +117,3 @@ categories. The loop looks slightly different in that situation then:
This is just one example of how to render these flashed messages. One This is just one example of how to render these flashed messages. One
might also use the category to add a prefix such as might also use the category to add a prefix such as
``<strong>Error:</strong>`` to the message. ``<strong>Error:</strong>`` to the message.
Filtering Flash Messages
------------------------
.. versionadded:: 0.9
Optionally you can pass a list of categories which filters the results of
:func:`~flask.get_flashed_messages`. This is useful if you wish to
render each category in a separate block.
.. sourcecode:: html+jinja
{% with errors = get_flashed_messages(category_filter=["error"]) %}
{% if errors %}
<div class="alert-message block-message error">
<a class="close" href="#">×</a>
<ul>
{%- for msg in errors %}
<li>{{ msg }}</li>
{% endfor -%}
</ul>
</div>
{% endif %}
{% endwith %}

34
docs/patterns/index.rst
View file

@ -1,24 +1,24 @@
.. _patterns:
Patterns for Flask Patterns for Flask
================== ==================
Certain features and interactions are common enough that you will find Certain things are common enough that the changes are high you will find
them in most web applications. For example, many applications use a them in most web applications. For example quite a lot of applications
relational database and user authentication. They will open a database are using relational databases and user authentication. In that case,
connection at the beginning of the request and get the information for changes are they will open a database connection at the beginning of the
the logged in user. At the end of the request, the database connection request and get the information of the currently logged in user. At the
is closed. end of the request, the database connection is closed again.
These types of patterns may be a bit outside the scope of Flask itself, There are more user contributed snippets and patterns in the `Flask
but Flask makes it easy to implement them. Some common patterns are Snippet Archives <http://flask.pocoo.org/snippets/>`_.
collected in the following pages.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
packages packages
appfactories appfactories
appdispatch distribute
urlprocessors
sqlite3 sqlite3
sqlalchemy sqlalchemy
fileuploads fileuploads
@ -27,14 +27,6 @@ collected in the following pages.
wtforms wtforms
templateinheritance templateinheritance
flashing flashing
javascript jquery
errorpages
lazyloading lazyloading
mongoengine
favicon
streaming
deferredcallbacks
methodoverrides
requestchecksum
celery
subclassing
singlepageapplications

261
docs/patterns/javascript.rst
View file

@ -1,261 +0,0 @@
JavaScript, ``fetch``, and JSON
===============================
You may want to make your HTML page dynamic, by changing data without
reloading the entire page. Instead of submitting an HTML ``<form>`` and
performing a redirect to re-render the template, you can add
`JavaScript`_ that calls |fetch|_ and replaces content on the page.
|fetch|_ is the modern, built-in JavaScript solution to making
requests from a page. You may have heard of other "AJAX" methods and
libraries, such as |XHR|_ or `jQuery`_. These are no longer needed in
modern browsers, although you may choose to use them or another library
depending on your application's requirements. These docs will only focus
on built-in JavaScript features.
.. _JavaScript: https://developer.mozilla.org/Web/JavaScript
.. |fetch| replace:: ``fetch()``
.. _fetch: https://developer.mozilla.org/Web/API/Fetch_API
.. |XHR| replace:: ``XMLHttpRequest()``
.. _XHR: https://developer.mozilla.org/Web/API/XMLHttpRequest
.. _jQuery: https://jquery.com/
Rendering Templates
-------------------
It is important to understand the difference between templates and
JavaScript. Templates are rendered on the server, before the response is
sent to the user's browser. JavaScript runs in the user's browser, after
the template is rendered and sent. Therefore, it is impossible to use
JavaScript to affect how the Jinja template is rendered, but it is
possible to render data into the JavaScript that will run.
To provide data to JavaScript when rendering the template, use the
:func:`~jinja-filters.tojson` filter in a ``<script>`` block. This will
convert the data to a valid JavaScript object, and ensure that any
unsafe HTML characters are rendered safely. If you do not use the
``tojson`` filter, you will get a ``SyntaxError`` in the browser
console.
.. code-block:: python
data = generate_report()
return render_template("report.html", chart_data=data)
.. code-block:: jinja
<script>
const chart_data = {{ chart_data|tojson }}
chartLib.makeChart(chart_data)
</script>
A less common pattern is to add the data to a ``data-`` attribute on an
HTML tag. In this case, you must use single quotes around the value, not
double quotes, otherwise you will produce invalid or unsafe HTML.
.. code-block:: jinja
<div data-chart='{{ chart_data|tojson }}'></div>
Generating URLs
---------------
The other way to get data from the server to JavaScript is to make a
request for it. First, you need to know the URL to request.
The simplest way to generate URLs is to continue to use
:func:`~flask.url_for` when rendering the template. For example:
.. code-block:: javascript
const user_url = {{ url_for("user", id=current_user.id)|tojson }}
fetch(user_url).then(...)
However, you might need to generate a URL based on information you only
know in JavaScript. As discussed above, JavaScript runs in the user's
browser, not as part of the template rendering, so you can't use
``url_for`` at that point.
In this case, you need to know the "root URL" under which your
application is served. In simple setups, this is ``/``, but it might
also be something else, like ``https://example.com/myapp/``.
A simple way to tell your JavaScript code about this root is to set it
as a global variable when rendering the template. Then you can use it
when generating URLs from JavaScript.
.. code-block:: javascript
const SCRIPT_ROOT = {{ request.script_root|tojson }}
let user_id = ... // do something to get a user id from the page
let user_url = `${SCRIPT_ROOT}/user/${user_id}`
fetch(user_url).then(...)
Making a Request with ``fetch``
-------------------------------
|fetch|_ takes two arguments, a URL and an object with other options,
and returns a |Promise|_. We won't cover all the available options, and
will only use ``then()`` on the promise, not other callbacks or
``await`` syntax. Read the linked MDN docs for more information about
those features.
By default, the GET method is used. If the response contains JSON, it
can be used with a ``then()`` callback chain.
.. code-block:: javascript
const room_url = {{ url_for("room_detail", id=room.id)|tojson }}
fetch(room_url)
.then(response => response.json())
.then(data => {
// data is a parsed JSON object
})
To send data, use a data method such as POST, and pass the ``body``
option. The most common types for data are form data or JSON data.
To send form data, pass a populated |FormData|_ object. This uses the
same format as an HTML form, and would be accessed with ``request.form``
in a Flask view.
.. code-block:: javascript
let data = new FormData()
data.append("name", "Flask Room")
data.append("description", "Talk about Flask here.")
fetch(room_url, {
"method": "POST",
"body": data,
}).then(...)
In general, prefer sending request data as form data, as would be used
when submitting an HTML form. JSON can represent more complex data, but
unless you need that it's better to stick with the simpler format. When
sending JSON data, the ``Content-Type: application/json`` header must be
sent as well, otherwise Flask will return a 415 Unsupported Media Type
error.
.. code-block:: javascript
let data = {
"name": "Flask Room",
"description": "Talk about Flask here.",
}
fetch(room_url, {
"method": "POST",
"headers": {"Content-Type": "application/json"},
"body": JSON.stringify(data),
}).then(...)
.. |Promise| replace:: ``Promise``
.. _Promise: https://developer.mozilla.org/Web/JavaScript/Reference/Global_Objects/Promise
.. |FormData| replace:: ``FormData``
.. _FormData: https://developer.mozilla.org/en-US/docs/Web/API/FormData
Following Redirects
-------------------
A response might be a redirect, for example if you logged in with
JavaScript instead of a traditional HTML form, and your view returned
a redirect instead of JSON. JavaScript requests do follow redirects, but
they don't change the page. If you want to make the page change you can
inspect the response and apply the redirect manually.
.. code-block:: javascript
fetch("/login", {"body": ...}).then(
response => {
if (response.redirected) {
window.location = response.url
} else {
showLoginError()
}
}
)
Replacing Content
-----------------
A response might be new HTML, either a new section of the page to add or
replace, or an entirely new page. In general, if you're returning the
entire page, it would be better to handle that with a redirect as shown
in the previous section. The following example shows how to replace a
``<div>`` with the HTML returned by a request.
.. code-block:: html
<div id="geology-fact">
{{ include "geology_fact.html" }}
</div>
<script>
const geology_url = {{ url_for("geology_fact")|tojson }}
const geology_div = getElementById("geology-fact")
fetch(geology_url)
.then(response => response.text)
.then(text => geology_div.innerHTML = text)
</script>
Return JSON from Views
----------------------
To return a JSON object from your API view, you can directly return a
dict from the view. It will be serialized to JSON automatically.
.. code-block:: python
@app.route("/user/<int:id>")
def user_detail(id):
user = User.query.get_or_404(id)
return {
"username": User.username,
"email": User.email,
"picture": url_for("static", filename=f"users/{id}/profile.png"),
}
If you want to return another JSON type, use the
:func:`~flask.json.jsonify` function, which creates a response object
with the given data serialized to JSON.
.. code-block:: python
from flask import jsonify
@app.route("/users")
def user_list():
users = User.query.order_by(User.name).all()
return jsonify([u.to_json() for u in users])
It is usually not a good idea to return file data in a JSON response.
JSON cannot represent binary data directly, so it must be base64
encoded, which can be slow, takes more bandwidth to send, and is not as
easy to cache. Instead, serve files using one view, and generate a URL
to the desired file to include in the JSON. Then the client can make a
separate request to get the linked resource after getting the JSON.
Receiving JSON in Views
-----------------------
Use the :attr:`~flask.Request.json` property of the
:data:`~flask.request` object to decode the request's body as JSON. If
the body is not valid JSON, a 400 Bad Request error will be raised. If
the ``Content-Type`` header is not set to ``application/json``, a 415
Unsupported Media Type error will be raised.
.. code-block:: python
from flask import request
@app.post("/user/<int:id>")
def user_update(id):
user = User.query.get_or_404(id)
user.update_from_json(request.json)
db.session.commit()
return user.to_json()

167
docs/patterns/jquery.rst
View file

@ -1,6 +1,167 @@
:orphan:
AJAX with jQuery AJAX with jQuery
================ ================
Obsolete, see :doc:`/patterns/javascript` instead. `jQuery`_ is a small JavaScript library commonly used to simplify working
with the DOM and JavaScript in general. It is the perfect tool to make
web applications more dynamic by exchanging JSON between server and
client.
JSON itself is a very lightweight transport format, very similar to how
Python primitives (numbers, strings, dicts and lists) look like which is
widely supported and very easy to parse. It became popular a few years
ago and quickly replaced XML as transport format in web applications.
If you have Python 2.6 JSON will work out of the box, in Python 2.5 you
will have to install the `simplejson`_ library from PyPI.
.. _jQuery: http://jquery.com/
.. _simplejson: http://pypi.python.org/pypi/simplejson
Loading jQuery
--------------
In order to use jQuery, you have to download it first and place it in the
static folder of your application and then ensure it's loaded. Ideally
you have a layout template that is used for all pages where you just have
to add a script statement to your `head` to load jQuery:
.. sourcecode:: html
<script type=text/javascript src="{{
url_for('static', filename='jquery.js') }}"></script>
Another method is using Google's `AJAX Libraries API
<http://code.google.com/apis/ajaxlibs/documentation/>`_ to load jQuery:
.. sourcecode:: html
<script type=text/javascript
src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
In this case you don't have to put jQuery into your static folder, it will
instead be loaded from Google directly. This has the advantage that your
website will probably load faster for users if they were to at least one
other website before using the same jQuery version from Google because it
will already be in the browser cache. Downside is that if you don't have
network connectivity during development jQuery will not load.
Where is My Site?
-----------------
Do you know where your application is? If you are developing the answer
is quite simple: it's on localhost port something and directly on the root
of that server. But what if you later decide to move your application to
a different location? For example to ``http://example.com/myapp``? On
the server side this never was a problem because we were using the handy
:func:`~flask.url_for` function that did could answer that question for
us, but if we are using jQuery we should better not hardcode the path to
the application but make that dynamic, so how can we do that?
A simple method would be to add a script tag to our page that sets a
global variable to the prefix to the root of the application. Something
like this:
.. sourcecode:: html+jinja
<script type=text/javascript>
$SCRIPT_ROOT = {{ request.script_root|tojson|safe }};
</script>
The ``|safe`` is necessary so that Jinja does not escape the JSON encoded
string with HTML rules. Usually this would be necessary, but we are
inside a `script` block here where different rules apply.
.. admonition:: Information for Pros
In HTML the `script` tag is declared `CDATA` which means that entities
will not be parsed. Everything until ``</script>`` is handled as script.
This also means that there must never be any ``</`` between the script
tags. ``|tojson`` is kindly enough to do the right thing here and
escape slashes for you (``{{ "</script>"|tojson|safe }}`` is rendered as
``"<\/script>"``).
JSON View Functions
-------------------
Now let's create a server side function that accepts two URL arguments of
numbers which should be added together and then sent back to the
application in a JSON object. This is a really ridiculous example and is
something you usually would do on the client side alone, but a simple
example that shows how you would use jQuery and Flask nonetheless::
from flask import Flask, jsonify, render_template, request
app = Flask(__name__)
@app.route('/_add_numbers')
def add_numbers():
a = request.args.get('a', 0, type=int)
b = request.args.get('b', 0, type=int)
return jsonify(result=a + b)
@app.route('/')
def index():
return render_template('index.html')
As you can see I also added an `index` method here that renders a
template. This template will load jQuery as above and have a little form
we can add two numbers and a link to trigger the function on the server
side.
Note that we are using the :meth:`~werkzeug.MultiDict.get` method here
which will never fail. If the key is missing a default value (here ``0``)
is returned. Furthermore it can convert values to a specific type (like
in our case `int`). This is especially handy for code that is
triggered by a script (APIs, JavaScript etc.) because you don't need
special error reporting in that case.
The HTML
--------
You index.html template either has to extend a `layout.html` template with
jQuery loaded and the `$SCRIPT_ROOT` variable set, or do that on the top.
Here the HTML code needed for our little application (`index.html`).
Notice that we also drop the script directly into the HTML here. It is
usually a better idea to have that in a separate script file:
.. sourcecode:: html
<script type=text/javascript>
$(function() {
$('a#calculate').bind('click', function() {
$.getJSON($SCRIPT_ROOT + '/_add_numbers', {
a: $('input[name="a"]').val(),
b: $('input[name="b"]').val()
}, function(data) {
$("#result").text(data.result);
});
return false;
});
});
</script>
<h1>jQuery Example</h1>
<p><input type=text size=5 name=a> +
<input type=text size=5 name=b> =
<span id=result>?</span>
<p><a href=# id=calculate>calculate server side</a>
I won't got into detail here about how jQuery works, just a very quick
explanation of the little bit of code above:
1. ``$(function() { ... })`` specifies code that should run once the
browser is done loading the basic parts of the page.
2. ``#('selector')`` selects an element and lets you operate on it.
3. ``element.bind('event', func)`` specifies a function that should run
when the user clicked on the element. If that function returns
`false`, the default behaviour will not kick in (in this case, navigate
to the `#` URL).
4. ``$.getJSON(url, data, func)`` sends a `GET` request to `url` and will
send the contents of the `data` object as query parameters. Once the
data arrived, it will call the given function with the return value as
argument. Note that we can use the `$SCRIPT_ROOT` variable here that
we set earlier.
If you don't get the whole picture, download the `sourcecode
for this example
<http://github.com/mitsuhiko/flask/tree/master/examples/jqueryexample>`_
from github.

29
docs/patterns/lazyloading.rst
View file

@ -32,8 +32,8 @@ Imagine the current application looks somewhat like this::
def user(username): def user(username):
pass pass
Then, with the centralized approach you would have one file with the views Then the centralized approach you would have one file with the views
(:file:`views.py`) but without any decorator:: (`views.py`) but without any decorator::
def index(): def index():
pass pass
@ -54,11 +54,11 @@ Loading Late
------------ ------------
So far we only split up the views and the routing, but the module is still So far we only split up the views and the routing, but the module is still
loaded upfront. The trick is to actually load the view function as needed. loaded upfront. The trick to actually load the view function as needed.
This can be accomplished with a helper class that behaves just like a This can be accomplished with a helper class that behaves just like a
function but internally imports the real function on first use:: function but internally imports the real function on first use::
from werkzeug.utils import import_string, cached_property from werkzeug import import_string, cached_property
class LazyView(object): class LazyView(object):
@ -74,7 +74,7 @@ function but internally imports the real function on first use::
return self.view(*args, **kwargs) return self.view(*args, **kwargs)
What's important here is is that `__module__` and `__name__` are properly What's important here is is that `__module__` and `__name__` are properly
set. This is used by Flask internally to figure out how to name the set. This is used by Flask internally to figure out how to do name the
URL rules in case you don't provide a name for the rule yourself. URL rules in case you don't provide a name for the rule yourself.
Then you can define your central place to combine the views like this:: Then you can define your central place to combine the views like this::
@ -90,20 +90,15 @@ Then you can define your central place to combine the views like this::
You can further optimize this in terms of amount of keystrokes needed to You can further optimize this in terms of amount of keystrokes needed to
write this by having a function that calls into write this by having a function that calls into
:meth:`~flask.Flask.add_url_rule` by prefixing a string with the project :meth:`~flask.Flask.add_url_rule` by prefixing a string with the project
name and a dot, and by wrapping `view_func` in a `LazyView` as needed. :: name and a dot, and by wrapping `view_func` in a `LazyView` as needed::
def url(import_name, url_rules=[], **options): def url(url_rule, import_name, **options):
view = LazyView(f"yourapplication.{import_name}") view = LazyView('yourapplication.' + import_name)
for url_rule in url_rules: app.add_url_rule(url_rule, view_func=view, **options)
app.add_url_rule(url_rule, view_func=view, **options)
# add a single route to the index view url('/', 'views.index')
url('views.index', ['/']) url('/user/<username>', 'views.user')
# add two routes to a single function endpoint
url_rules = ['/user/','/user/<username>']
url('views.user', url_rules)
One thing to keep in mind is that before and after request handlers have One thing to keep in mind is that before and after request handlers have
to be in a file that is imported upfront to work properly on the first to be in a file that is imported upfront to work propery on the first
request. The same goes for any kind of remaining decorator. request. The same goes for any kind of remaining decorator.

42
docs/patterns/methodoverrides.rst
View file

@ -1,42 +0,0 @@
Adding HTTP Method Overrides
============================
Some HTTP proxies do not support arbitrary HTTP methods or newer HTTP
methods (such as PATCH). In that case it's possible to "proxy" HTTP
methods through another HTTP method in total violation of the protocol.
The way this works is by letting the client do an HTTP POST request and
set the ``X-HTTP-Method-Override`` header. Then the method is replaced
with the header value before being passed to Flask.
This can be accomplished with an HTTP middleware::
class HTTPMethodOverrideMiddleware(object):
allowed_methods = frozenset([
'GET',
'HEAD',
'POST',
'DELETE',
'PUT',
'PATCH',
'OPTIONS'
])
bodyless_methods = frozenset(['GET', 'HEAD', 'OPTIONS', 'DELETE'])
def __init__(self, app):
self.app = app
def __call__(self, environ, start_response):
method = environ.get('HTTP_X_HTTP_METHOD_OVERRIDE', '').upper()
if method in self.allowed_methods:
environ['REQUEST_METHOD'] = method
if method in self.bodyless_methods:
environ['CONTENT_LENGTH'] = '0'
return self.app(environ, start_response)
To use this with Flask, wrap the app object with the middleware::
from flask import Flask
app = Flask(__name__)
app.wsgi_app = HTTPMethodOverrideMiddleware(app.wsgi_app)

102
docs/patterns/mongoengine.rst
View file

@ -1,102 +0,0 @@
MongoDB with MongoEngine
========================
Using a document database like MongoDB is a common alternative to
relational SQL databases. This pattern shows how to use
`MongoEngine`_, a document mapper library, to integrate with MongoDB.
A running MongoDB server and `Flask-MongoEngine`_ are required. ::
pip install flask-mongoengine
.. _MongoEngine: http://mongoengine.org
.. _Flask-MongoEngine: https://docs.mongoengine.org/projects/flask-mongoengine/en/latest/
Configuration
-------------
Basic setup can be done by defining ``MONGODB_SETTINGS`` on
``app.config`` and creating a ``MongoEngine`` instance. ::
from flask import Flask
from flask_mongoengine import MongoEngine
app = Flask(__name__)
app.config['MONGODB_SETTINGS'] = {
"db": "myapp",
}
db = MongoEngine(app)
Mapping Documents
-----------------
To declare a model that represents a Mongo document, create a class that
inherits from ``Document`` and declare each of the fields. ::
import mongoengine as me
class Movie(me.Document):
title = me.StringField(required=True)
year = me.IntField()
rated = me.StringField()
director = me.StringField()
actors = me.ListField()
If the document has nested fields, use ``EmbeddedDocument`` to
defined the fields of the embedded document and
``EmbeddedDocumentField`` to declare it on the parent document. ::
class Imdb(me.EmbeddedDocument):
imdb_id = me.StringField()
rating = me.DecimalField()
votes = me.IntField()
class Movie(me.Document):
...
imdb = me.EmbeddedDocumentField(Imdb)
Creating Data
-------------
Instantiate your document class with keyword arguments for the fields.
You can also assign values to the field attributes after instantiation.
Then call ``doc.save()``. ::
bttf = Movie(title="Back To The Future", year=1985)
bttf.actors = [
"Michael J. Fox",
"Christopher Lloyd"
]
bttf.imdb = Imdb(imdb_id="tt0088763", rating=8.5)
bttf.save()
Queries
-------
Use the class ``objects`` attribute to make queries. A keyword argument
looks for an equal value on the field. ::
bttf = Movie.objects(title="Back To The Future").get_or_404()
Query operators may be used by concatenating them with the field name
using a double-underscore. ``objects``, and queries returned by
calling it, are iterable. ::
some_theron_movie = Movie.objects(actors__in=["Charlize Theron"]).first()
for recents in Movie.objects(year__gte=2017):
print(recents.title)
Documentation
-------------
There are many more ways to define and query documents with MongoEngine.
For more information, check out the `official documentation
<MongoEngine_>`_.
Flask-MongoEngine adds helpful utilities on top of MongoEngine. Check
out their `documentation <Flask-MongoEngine_>`_ as well.

186
docs/patterns/packages.rst
View file

@ -1,38 +1,37 @@
Large Applications as Packages .. _larger-applications:
==============================
Imagine a simple flask application structure that looks like this:: 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
yourapplication.py /yourapplication.py
/static /static
style.css /style.css
/templates /templates
layout.html layout.html
index.html index.html
login.html login.html
... ...
While this is fine for small applications, for larger applications
it's a good idea to use a package instead of a module.
The :doc:`/tutorial/index` is structured to use the package pattern,
see the :gh:`example code <examples/tutorial>`.
Simple Packages Simple Packages
--------------- ---------------
To convert that into a larger one, just create a new folder To convert that into a larger one, just create a new folder
:file:`yourapplication` inside the existing one and move everything below it. `yourapplication` inside the existing one and move everything below it.
Then rename :file:`yourapplication.py` to :file:`__init__.py`. (Make sure to delete Then rename `yourapplication.py` to `__init__.py`. (Make sure to delete
all ``.pyc`` files first, otherwise things would most likely break) all `.pyc` files first, otherwise things would most likely break)
You should then end up with something like that:: You should then end up with something like that::
/yourapplication /yourapplication
/yourapplication /yourapplication
__init__.py /__init__.py
/static /static
style.css /style.css
/templates /templates
layout.html layout.html
index.html index.html
@ -42,55 +41,32 @@ You should then end up with something like that::
But how do you run your application now? The naive ``python But how do you run your application now? The naive ``python
yourapplication/__init__.py`` will not work. Let's just say that 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 does not want modules in packages to be the startup file. But that is not
a big problem, just add a new file called :file:`pyproject.toml` next to the inner a big problem, just add a new file called `runserver.py` next to the inner
:file:`yourapplication` folder with the following contents: `yourapplication` folder with the following contents::
.. code-block:: toml from yourapplication import app
app.run(debug=True)
[project]
name = "yourapplication"
dependencies = [
"flask",
]
[build-system]
requires = ["flit_core<4"]
build-backend = "flit_core.buildapi"
Install your application so it is importable:
.. code-block:: text
$ pip install -e .
To use the ``flask`` command and run your application you need to set
the ``--app`` option that tells Flask where to find the application
instance:
.. code-block:: text
$ flask --app yourapplication run
What did we gain from this? Now we can restructure the application a bit 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 into multiple modules. The only thing you have to remember is the
following quick checklist: following quick checklist:
1. the `Flask` application object creation has to be in the 1. the `Flask` application object creation has to be in the
:file:`__init__.py` file. That way each module can import it safely and the `__init__.py` file. That way each module can import it safely and the
`__name__` variable will resolve to the correct package. `__name__` variable will resolve to the correct package.
2. all the view functions (the ones with a :meth:`~flask.Flask.route` 2. all the view functions (the ones with a :meth:`~flask.Flask.route`
decorator on top) have to be imported in the :file:`__init__.py` file. decorator on top) have to be imported when in the `__init__.py` file.
Not the object itself, but the module it is in. Import the view module Not the object itself, but the module it is in. Do the importing at
**after the application object is created**. the *bottom* of the file.
Here's an example :file:`__init__.py`:: Here an example `__init__.py`::
from flask import Flask from flask import Flask
app = Flask(__name__) app = Flask(__name__)
import yourapplication.views import yourapplication.views
And this is what :file:`views.py` would look like:: And this is what `views.py` would look like::
from yourapplication import app from yourapplication import app
@ -101,12 +77,11 @@ And this is what :file:`views.py` would look like::
You should then end up with something like that:: You should then end up with something like that::
/yourapplication /yourapplication
pyproject.toml
/yourapplication /yourapplication
__init__.py /__init__.py
views.py /views.py
/static /static
style.css /style.css
/templates /templates
layout.html layout.html
index.html index.html
@ -117,17 +92,108 @@ You should then end up with something like that::
Every Python programmer hates them, and yet we just added some: Every Python programmer hates them, and yet we just added some:
circular imports (That's when two modules depend on each other. In this circular imports (That's when two modules depend on each other. In this
case :file:`views.py` depends on :file:`__init__.py`). Be advised that this is a 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 bad idea in general but here it is actually fine. The reason for this is
that we are not actually using the views in :file:`__init__.py` and just 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 ensuring the module is imported and we are doing that at the bottom of
the file. 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 Blueprints
-----------------------
If you have larger applications it's recommended to divide them into .. _working-with-modules:
smaller groups where each group is implemented with the help of a
blueprint. For a gentle introduction into this topic refer to the Working with Modules
:doc:`/blueprints` chapter of the documentation. --------------------
For larger applications with more than a dozen views it makes sense to
split the views into module. First let's look at the typical struture 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 method,
but most of them are the same.
Long story short, here 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 login():
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 module 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"

Some files were not shown because too many files have changed in this diff Show more