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