diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index e67cbe13..c81cc3d3 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,11 +1,11 @@
repos:
- repo: https://github.com/asottile/pyupgrade
- rev: v2.1.0
+ rev: v2.4.3
hooks:
- id: pyupgrade
args: ["--py36-plus"]
- repo: https://github.com/asottile/reorder_python_imports
- rev: v2.1.0
+ rev: v2.3.0
hooks:
- id: reorder-python-imports
name: Reorder Python imports (src, tests)
@@ -16,14 +16,14 @@ repos:
hooks:
- id: black
- repo: https://gitlab.com/pycqa/flake8
- rev: 3.7.9
+ rev: 3.8.2
hooks:
- id: flake8
additional_dependencies:
- flake8-bugbear
- flake8-implicit-str-concat
- repo: https://github.com/pre-commit/pre-commit-hooks
- rev: v2.5.0
+ rev: v3.1.0
hooks:
- id: check-byte-order-marker
- id: trailing-whitespace
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index af232107..19069520 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -1,8 +1,8 @@
version: 2
python:
install:
+ - requirements: requirements/docs.txt
- method: pip
path: .
- - requirements: docs/requirements.txt
sphinx:
builder: dirhtml
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 5dbd8fb5..4c6b18a7 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -3,86 +3,107 @@ How to contribute to Flask
Thank you for considering contributing to Flask!
+
Support questions
-----------------
Please, don't use the issue tracker for this. Use one of the following
resources for questions about your own code:
-* The ``#get-help`` channel on our Discord chat: https://discordapp.com/invite/t6rrQZH
+- The ``#get-help`` channel on our Discord chat:
+ https://discord.gg/t6rrQZH
- * The IRC channel ``#pocoo`` on FreeNode is linked to Discord, but
- Discord is preferred.
+ - The IRC channel ``#pocoo`` on FreeNode is linked to Discord, but
+ Discord is preferred.
-* The mailing list flask@python.org for long term discussion or larger issues.
-* Ask on `Stack Overflow`_. Search with Google first using:
- ``site:stackoverflow.com flask {search term, exception message, etc.}``
+- The mailing list flask@python.org for long term discussion or larger
+ issues.
+- Ask on `Stack Overflow`_. Search with Google first using:
+ ``site:stackoverflow.com flask {search term, exception message, etc.}``
.. _Stack Overflow: https://stackoverflow.com/questions/tagged/flask?sort=linked
+
Reporting issues
----------------
-- Describe what you expected to happen.
-- If possible, include a `minimal reproducible example`_ to help us
- identify the issue. This also helps check that the issue is not with
- your own code.
-- Describe what actually happened. Include the full traceback if there was an
- exception.
-- List your Python, Flask, and Werkzeug versions. If possible, check if this
- issue is already fixed in the repository.
+- Describe what you expected to happen.
+- If possible, include a `minimal reproducible example`_ to help us
+ identify the issue. This also helps check that the issue is not with
+ your own code.
+- Describe what actually happened. Include the full traceback if there
+ was an exception.
+- List your Python, Flask, and Werkzeug versions. If possible, check
+ if this issue is already fixed in the repository.
.. _minimal reproducible example: https://stackoverflow.com/help/minimal-reproducible-example
+
Submitting patches
------------------
-- Use `Black`_ to autoformat your code. This should be done for you as a
- git `pre-commit`_ hook, which gets installed when you run ``pip install -e .[dev]``.
- You may also wish to use Black's `Editor integration`_.
-- Include tests if your patch is supposed to solve a bug, and explain
- clearly under which circumstances the bug happens. Make sure the test fails
- without your patch.
-- Include a string like "Fixes #123" in your commit message
- (where 123 is the issue you fixed).
- See `Closing issues using keywords
- `__.
+- Use `Black`_ to autoformat your code. This should be done for you as
+ a Git `pre-commit`_ hook, set up below. You may also wish to use
+ Black's `Editor integration`_.
+- Include tests if your patch is supposed to solve a bug, and explain
+ clearly under which circumstances the bug happens. Make sure the
+ test fails without your patch.
+- Include a string like "Fixes #123" in your commit message (where 123
+ is the issue you fixed). See `Closing issues using keywords
+ `__.
+
First time setup
~~~~~~~~~~~~~~~~
-- Download and install the `latest version of git`_.
-- Configure git with your `username`_ and `email`_::
+- Download and install the `latest version of git`_.
+- Configure git with your `username`_ and `email`_.
- git config --global user.name 'your name'
- git config --global user.email 'your email'
+ .. code-block:: text
-- Make sure you have a `GitHub account`_.
-- Fork Flask to your GitHub account by clicking the `Fork`_ button.
-- `Clone`_ your GitHub fork locally::
+ $ git config --global user.name 'your name'
+ $ git config --global user.email 'your email'
- git clone https://github.com/{username}/flask
- cd flask
+- Make sure you have a `GitHub account`_.
+- Fork Flask to your GitHub account by clicking the `Fork`_ button.
+- `Clone`_ your GitHub fork locally.
-- Add the main repository as a remote to update later::
+ .. code-block:: text
+
+ $ git clone https://github.com/{username}/flask
+ $ cd flask
+
+- Add the main repository as a remote to update later::
+
+ .. code-block:: text
git remote add pallets https://github.com/pallets/flask
git fetch pallets
-- Create a virtualenv::
+- Create a virtualenv.
- python3 -m venv env
- . env/bin/activate
- # or "env\Scripts\activate" on Windows
+ .. code-block:: text
-- Install Flask in editable mode with development dependencies::
+ $ python3 -m venv env
+ $ . env/bin/activate
- pip install -e ".[dev]"
+ On Windows, activating is different.
-- Install the `pre-commit framework`_.
-- Install the pre-commit hooks::
+ .. code-block:: text
- pre-commit install --install-hooks
+ > env\Scripts\activate
+
+- Install Flask in editable mode with development dependencies.
+
+ .. code-block:: text
+
+ $ pip install -e . -r requirements/dev.txt
+
+- Install the pre-commit hooks.
+
+ .. code-block:: text
+
+ $ pre-commit install
.. _GitHub account: https://github.com/join
.. _latest version of git: https://git-scm.com/downloads
@@ -92,28 +113,35 @@ First time setup
.. _Clone: https://help.github.com/en/articles/fork-a-repo#step-2-create-a-local-clone-of-your-fork
.. _pre-commit framework: https://pre-commit.com/#install
+
Start coding
~~~~~~~~~~~~
- Create a branch to identify the issue you would like to work on. If
you're submitting a bug or documentation fix, branch off of the
- latest ".x" branch::
+ latest ".x" branch.
- git checkout -b your-branch-name origin/1.0.x
+ .. code-block:: text
+
+ $ git checkout -b your-branch-name origin/1.0.x
If you're submitting a feature addition or change, branch off of the
- "master" branch::
+ "master" branch.
- git checkout -b your-branch-name origin/master
+ .. code-block:: text
-- Using your favorite editor, make your changes, `committing as you go`_.
-- Include tests that cover any code changes you make. Make sure the test fails
- without your patch. `Run the tests `_.
-- Push your commits to GitHub and `create a pull request`_ by using::
+ $ git checkout -b your-branch-name origin/master
- git push --set-upstream origin your-branch-name
+- Using your favorite editor, make your changes,
+ `committing as you go`_.
+- Include tests that cover any code changes you make. Make sure the
+ test fails without your patch.
+ `Run the tests `_.
+- Push your commits to GitHub and `create a pull request`_.
-- Celebrate 🎉
+ .. code-block:: text
+
+ $ git push --set-upstream origin your-branch-name
.. _committing as you go: https://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html#commit-your-changes
.. _Black: https://black.readthedocs.io
@@ -121,37 +149,43 @@ Start coding
.. _pre-commit: https://pre-commit.com
.. _create a pull request: https://help.github.com/en/articles/creating-a-pull-request
+
.. _contributing-testsuite: #running-the-tests
Running the tests
~~~~~~~~~~~~~~~~~
-Run the basic test suite with::
+Run the basic test suite with pytest.
- pytest
+.. code-block:: text
-This only runs the tests for the current environment. Whether this is relevant
-depends on which part of Flask you're working on. Travis-CI will run the full
-suite when you submit your pull request.
+ $ pytest
+
+This only runs the tests for the current environment. Whether this is
+relevant depends on which part of Flask you're working on. CI will run
+the full suite when you submit your pull request.
The full test suite takes a long time to run because it tests multiple
combinations of Python and dependencies. If you don't have a Python
version installed, it will be skipped with a warning message at the end.
-Run::
- tox
+.. code-block:: text
+
+ $ tox
+
Running test coverage
~~~~~~~~~~~~~~~~~~~~~
Generating a report of lines that do not have test coverage can indicate
-where to start contributing. Run ``pytest`` using ``coverage`` and generate a
-report on the terminal and as an interactive HTML document::
+where to start contributing. Run ``pytest`` using ``coverage`` and
+generate a report on the terminal and as an interactive HTML document.
- coverage run -m pytest
- coverage report
- coverage html
- # then open htmlcov/index.html
+.. code-block:: text
+
+ $ coverage run -m pytest
+ $ coverage report
+ $ coverage html # then open htmlcov/index.html
Read more about `coverage `_.
@@ -162,11 +196,12 @@ from all runs.
Building the docs
~~~~~~~~~~~~~~~~~
-Build the docs in the ``docs`` directory using Sphinx::
+Build the docs in the ``docs`` directory using Sphinx.
- cd docs
- pip install -r requirements.txt
- make html
+.. code-block:: text
+
+ $ cd docs
+ $ make html
Open ``_build/html/index.html`` in your browser to view the docs.
@@ -176,22 +211,23 @@ Read more about `Sphinx `_.
Caution: zero-padded file modes
-------------------------------
-This repository contains several zero-padded file modes that may cause issues
-when pushing this repository to git hosts other than GitHub. Fixing this is
-destructive to the commit history, so we suggest ignoring these warnings. If it
-fails to push and you're using a self-hosted git service like GitLab, you can
-turn off repository checks in the admin panel.
+This repository contains several zero-padded file modes that may cause
+issues when pushing this repository to Git hosts other than GitHub.
+Fixing this is destructive to the commit history, so we suggest ignoring
+these warnings. If it fails to push and you're using a self-hosted Git
+service like GitLab, you can turn off repository checks in the admin
+panel.
-These files can also cause issues while cloning. If you have ::
+These files can also cause issues while cloning if you have
+``fsckObjects`` enabled with either of the following in your git config.
+
+.. code-block::
[fetch]
- fsckobjects = true
-
-or ::
+ fsckObjects = true
[receive]
fsckObjects = true
-set in your git configuration file, cloning this repository will fail. The only
-solution is to set both of the above settings to false while cloning, and then
-setting them back to true after the cloning is finished.
+The only solution is to set both of the above to ``false``, clone, and
+then set them back to ``true`` after.
diff --git a/MANIFEST.in b/MANIFEST.in
index 1743c84b..a63d6ee1 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -2,6 +2,7 @@ include CHANGES.rst
include CONTRIBUTING.rst
include LICENSE.rst
include tox.ini
+include requirements/*.txt
graft artwork
graft docs
prune docs/_build
diff --git a/docs/requirements.txt b/docs/requirements.txt
deleted file mode 100644
index cadd40cd..00000000
--- a/docs/requirements.txt
+++ /dev/null
@@ -1,5 +0,0 @@
-Sphinx~=3.0.0
-Pallets-Sphinx-Themes~=1.2.3
-sphinxcontrib-log-cabinet~=1.0.1
-sphinx-issues~=1.2.0
-packaging~=20.3
diff --git a/requirements/dev.in b/requirements/dev.in
new file mode 100644
index 00000000..c854000e
--- /dev/null
+++ b/requirements/dev.in
@@ -0,0 +1,5 @@
+-r docs.in
+-r tests.in
+pip-tools
+pre-commit
+tox
diff --git a/requirements/dev.txt b/requirements/dev.txt
new file mode 100644
index 00000000..76e5e7bb
--- /dev/null
+++ b/requirements/dev.txt
@@ -0,0 +1,59 @@
+#
+# This file is autogenerated by pip-compile
+# To update, run:
+#
+# pip-compile requirements/dev.in
+#
+alabaster==0.7.12 # via sphinx
+appdirs==1.4.4 # via virtualenv
+attrs==19.3.0 # via pytest
+babel==2.8.0 # via sphinx
+blinker==1.4 # via -r requirements/tests.in
+certifi==2020.4.5.1 # via requests
+cfgv==3.1.0 # via pre-commit
+chardet==3.0.4 # via requests
+click==7.1.2 # via pip-tools
+distlib==0.3.0 # via virtualenv
+docutils==0.16 # via sphinx
+filelock==3.0.12 # via tox, virtualenv
+greenlet==0.4.15 # via -r requirements/tests.in
+identify==1.4.16 # via pre-commit
+idna==2.9 # via requests
+imagesize==1.2.0 # via sphinx
+jinja2==2.11.2 # via sphinx
+markupsafe==1.1.1 # via jinja2
+more-itertools==8.3.0 # via pytest
+nodeenv==1.3.5 # via pre-commit
+packaging==20.4 # via -r requirements/docs.in, pallets-sphinx-themes, pytest, sphinx, tox
+pallets-sphinx-themes==1.2.3 # via -r requirements/docs.in
+pip-tools==5.1.2 # via -r requirements/dev.in
+pluggy==0.13.1 # via pytest, tox
+pre-commit==2.4.0 # via -r requirements/dev.in
+py==1.8.1 # via pytest, tox
+pygments==2.6.1 # via sphinx
+pyparsing==2.4.7 # via packaging
+pytest==5.4.2 # via -r requirements/tests.in
+python-dotenv==0.13.0 # via -r requirements/tests.in
+pytz==2020.1 # via babel
+pyyaml==5.3.1 # via pre-commit
+requests==2.23.0 # via sphinx
+six==1.15.0 # via packaging, pip-tools, tox, virtualenv
+snowballstemmer==2.0.0 # via sphinx
+sphinx-issues==1.2.0 # via -r requirements/docs.in
+sphinx==3.0.3 # via -r requirements/docs.in, pallets-sphinx-themes, sphinx-issues, sphinxcontrib-log-cabinet
+sphinxcontrib-applehelp==1.0.2 # via sphinx
+sphinxcontrib-devhelp==1.0.2 # via sphinx
+sphinxcontrib-htmlhelp==1.0.3 # via sphinx
+sphinxcontrib-jsmath==1.0.1 # via sphinx
+sphinxcontrib-log-cabinet==1.0.1 # via -r requirements/docs.in
+sphinxcontrib-qthelp==1.0.3 # via sphinx
+sphinxcontrib-serializinghtml==1.1.4 # via sphinx
+toml==0.10.1 # via pre-commit, tox
+tox==3.15.1 # via -r requirements/dev.in
+urllib3==1.25.9 # via requests
+virtualenv==20.0.21 # via pre-commit, tox
+wcwidth==0.1.9 # via pytest
+
+# The following packages are considered to be unsafe in a requirements file:
+# pip
+# setuptools
diff --git a/requirements/docs.in b/requirements/docs.in
new file mode 100644
index 00000000..04942a0d
--- /dev/null
+++ b/requirements/docs.in
@@ -0,0 +1,5 @@
+Pallets-Sphinx-Themes
+packaging
+Sphinx
+sphinx-issues
+sphinxcontrib-log-cabinet
diff --git a/requirements/docs.txt b/requirements/docs.txt
new file mode 100644
index 00000000..6e8f4ab3
--- /dev/null
+++ b/requirements/docs.txt
@@ -0,0 +1,36 @@
+#
+# This file is autogenerated by pip-compile
+# To update, run:
+#
+# pip-compile requirements/docs.in
+#
+alabaster==0.7.12 # via sphinx
+babel==2.8.0 # via sphinx
+certifi==2020.4.5.1 # via requests
+chardet==3.0.4 # via requests
+docutils==0.16 # via sphinx
+idna==2.9 # via requests
+imagesize==1.2.0 # via sphinx
+jinja2==2.11.2 # via sphinx
+markupsafe==1.1.1 # via jinja2
+packaging==20.4 # via -r requirements/docs.in, pallets-sphinx-themes, sphinx
+pallets-sphinx-themes==1.2.3 # via -r requirements/docs.in
+pygments==2.6.1 # via sphinx
+pyparsing==2.4.7 # via packaging
+pytz==2020.1 # via babel
+requests==2.23.0 # via sphinx
+six==1.15.0 # via packaging
+snowballstemmer==2.0.0 # via sphinx
+sphinx-issues==1.2.0 # via -r requirements/docs.in
+sphinx==3.0.3 # via -r requirements/docs.in, pallets-sphinx-themes, sphinx-issues, sphinxcontrib-log-cabinet
+sphinxcontrib-applehelp==1.0.2 # via sphinx
+sphinxcontrib-devhelp==1.0.2 # via sphinx
+sphinxcontrib-htmlhelp==1.0.3 # via sphinx
+sphinxcontrib-jsmath==1.0.1 # via sphinx
+sphinxcontrib-log-cabinet==1.0.1 # via -r requirements/docs.in
+sphinxcontrib-qthelp==1.0.3 # via sphinx
+sphinxcontrib-serializinghtml==1.1.4 # via sphinx
+urllib3==1.25.9 # via requests
+
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools
diff --git a/requirements/tests.in b/requirements/tests.in
new file mode 100644
index 00000000..b5f5c912
--- /dev/null
+++ b/requirements/tests.in
@@ -0,0 +1,4 @@
+pytest
+blinker
+greenlet
+python-dotenv
diff --git a/requirements/tests.txt b/requirements/tests.txt
new file mode 100644
index 00000000..d891440f
--- /dev/null
+++ b/requirements/tests.txt
@@ -0,0 +1,18 @@
+#
+# This file is autogenerated by pip-compile
+# To update, run:
+#
+# pip-compile requirements/tests.in
+#
+attrs==19.3.0 # via pytest
+blinker==1.4 # via -r requirements/tests.in
+greenlet==0.4.15 # via -r requirements/tests.in
+more-itertools==8.3.0 # via pytest
+packaging==20.4 # via pytest
+pluggy==0.13.1 # via pytest
+py==1.8.1 # via pytest
+pyparsing==2.4.7 # via packaging
+pytest==5.4.2 # via -r requirements/tests.in
+python-dotenv==0.13.0 # via -r requirements/tests.in
+six==1.15.0 # via packaging
+wcwidth==0.1.9 # via pytest
diff --git a/setup.py b/setup.py
index 37f91346..6218be60 100644
--- a/setup.py
+++ b/setup.py
@@ -15,16 +15,5 @@ setup(
"itsdangerous>=0.24",
"click>=5.1",
],
- extras_require={
- "dotenv": ["python-dotenv"],
- "dev": [
- "pytest",
- "coverage",
- "tox",
- "sphinx",
- "pallets-sphinx-themes",
- "sphinxcontrib-log-cabinet",
- "sphinx-issues",
- ],
- },
+ extras_require={"dotenv": ["python-dotenv"]},
)
diff --git a/tox.ini b/tox.ini
index e276c231..156648ea 100644
--- a/tox.ini
+++ b/tox.ini
@@ -8,10 +8,7 @@ skip_missing_interpreters = true
[testenv]
deps =
- pytest
- greenlet
- blinker
- python-dotenv
+ -r requirements/tests.txt
lowest: Werkzeug==0.15.5
lowest: Jinja2==2.10
@@ -36,5 +33,5 @@ skip_install = true
commands = pre-commit run --all-files --show-diff-on-failure
[testenv:docs]
-deps = -r docs/requirements.txt
+deps = -r requirements/docs.txt
commands = sphinx-build -W -b html -d {envtmpdir}/doctrees docs {envtmpdir}/html