update docs and examples for pyproject

setup.py -> pyproject.toml
venv -> .venv

CONTRIBUTING.rst

@@ -102,14 +102,14 @@ First time setup
 
       .. code-block:: text
 
-         $ python3 -m venv env
+         $ python3 -m venv .venv
-         $ . env/bin/activate
+         $ . .venv/bin/activate
 
     - Windows
 
       .. code-block:: text
 
-         > py -3 -m venv env
+         > py -3 -m venv .venv
          > env\Scripts\activate
 
 -   Upgrade pip and setuptools.

docs/cli.rst

@@ -280,25 +280,25 @@ script. Activating the virtualenv will set the variables.
 
    .. group-tab:: Bash
 
-      Unix Bash, :file:`venv/bin/activate`::
+      Unix Bash, :file:`.venv/bin/activate`::
 
           $ export FLASK_APP=hello
 
    .. group-tab:: Fish
 
-      Fish, :file:`venv/bin/activate.fish`::
+      Fish, :file:`.venv/bin/activate.fish`::
 
           $ set -x FLASK_APP hello
 
    .. group-tab:: CMD
 
-      Windows CMD, :file:`venv\\Scripts\\activate.bat`::
+      Windows CMD, :file:`.venv\\Scripts\\activate.bat`::
 
           > set FLASK_APP=hello
 
    .. group-tab:: Powershell
 
-      Windows Powershell, :file:`venv\\Scripts\\activate.ps1`::
+      Windows Powershell, :file:`.venv\\Scripts\\activate.ps1`::
 
           > $env:FLASK_APP = "hello"
 
@@ -438,24 +438,16 @@ 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:`setup.py` ::
+they are installed. Entry points are specified in :file:`pyproject.toml`:
 
-    from setuptools import setup
+.. code-block:: toml
-
-    setup(
-        name='flask-my-extension',
-        ...,
-        entry_points={
-            'flask.commands': [
-                'my-command=flask_my_extension.commands:cli'
-            ],
-        },
-    )
 
+    [project.entry-points."flask.commands"]
+    my-command = "my_extension.commands:cli"
 
 .. _entry point: https://packaging.python.org/tutorials/packaging-projects/#entry-points
 
-Inside :file:`flask_my_extension/commands.py` you can then export a Click
+Inside :file:`my_extension/commands.py` you can then export a Click
 object::
 
     import click
@@ -493,19 +485,12 @@ Create an instance of :class:`~cli.FlaskGroup` and pass it the factory::
     def cli():
         """Management script for the Wiki application."""
 
-Define the entry point in :file:`setup.py`::
+Define the entry point in :file:`pyproject.toml`:
 
-    from setuptools import setup
+.. code-block:: toml
 
-    setup(
+    [project.scripts]
-        name='flask-my-extension',
+    wiki = "wiki:cli"
-        ...,
-        entry_points={
-            'console_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``. ::

docs/deploying/eventlet.rst

@@ -34,8 +34,8 @@ Create a virtualenv, install your application, then install
 .. code-block:: text
 
     $ cd hello-app
-    $ python -m venv venv
+    $ python -m venv .venv
-    $ . venv/bin/activate
+    $ . .venv/bin/activate
     $ pip install .  # install your application
     $ pip install eventlet
 

docs/deploying/gevent.rst

@@ -33,8 +33,8 @@ Create a virtualenv, install your application, then install ``gevent``.
 .. code-block:: text
 
     $ cd hello-app
-    $ python -m venv venv
+    $ python -m venv .venv
-    $ . venv/bin/activate
+    $ . .venv/bin/activate
     $ pip install .  # install your application
     $ pip install gevent
 

docs/deploying/gunicorn.rst

@@ -30,8 +30,8 @@ Create a virtualenv, install your application, then install
 .. code-block:: text
 
     $ cd hello-app
-    $ python -m venv venv
+    $ python -m venv .venv
-    $ . venv/bin/activate
+    $ . .venv/bin/activate
     $ pip install .  # install your application
     $ pip install gunicorn
 

docs/deploying/mod_wsgi.rst

@@ -33,8 +33,8 @@ Create a virtualenv, install your application, then install
 .. code-block:: text
 
     $ cd hello-app
-    $ python -m venv venv
+    $ python -m venv .venv
-    $ . venv/bin/activate
+    $ . .venv/bin/activate
     $ pip install .  # install your application
     $ pip install mod_wsgi
 
@@ -89,6 +89,6 @@ mod_wsgi to drop to that user after starting.
 
 .. code-block:: text
 
-    $ sudo /home/hello/venv/bin/mod_wsgi-express start-server \
+    $ sudo /home/hello/.venv/bin/mod_wsgi-express start-server \
         /home/hello/wsgi.py \
         --user hello --group hello --port 80 --processes 4

docs/deploying/uwsgi.rst

@@ -29,8 +29,8 @@ Create a virtualenv, install your application, then install ``pyuwsgi``.
 .. code-block:: text
 
     $ cd hello-app
-    $ python -m venv venv
+    $ python -m venv .venv
-    $ . venv/bin/activate
+    $ . .venv/bin/activate
     $ pip install .  # install your application
     $ pip install pyuwsgi
 

docs/deploying/waitress.rst

@@ -27,8 +27,8 @@ Create a virtualenv, install your application, then install
 .. code-block:: text
 
     $ cd hello-app
-    $ python -m venv venv
+    $ python -m venv .venv
-    $ . venv/bin/activate
+    $ . .venv/bin/activate
     $ pip install .  # install your application
     $ pip install waitress
 

docs/installation.rst

@@ -85,7 +85,7 @@ environments.
 Create an environment
 ~~~~~~~~~~~~~~~~~~~~~
 
-Create a project folder and a :file:`venv` folder within:
+Create a project folder and a :file:`.venv` folder within:
 
 .. tabs::
 
@@ -95,7 +95,7 @@ Create a project folder and a :file:`venv` folder within:
 
          $ mkdir myproject
          $ cd myproject
-         $ python3 -m venv venv
+         $ python3 -m venv .venv
 
    .. group-tab:: Windows
 
@@ -103,7 +103,7 @@ Create a project folder and a :file:`venv` folder within:
 
          > mkdir myproject
          > cd myproject
-         > py -3 -m venv venv
+         > py -3 -m venv .venv
 
 
 .. _install-activate-env:
@@ -119,13 +119,13 @@ Before you work on your project, activate the corresponding environment:
 
       .. code-block:: text
 
-         $ . venv/bin/activate
+         $ . .venv/bin/activate
 
    .. group-tab:: Windows
 
       .. code-block:: text
 
-         > venv\Scripts\activate
+         > .venv\Scripts\activate
 
 Your shell prompt will change to show the name of the activated
 environment.

docs/patterns/packages.rst

@@ -42,19 +42,20 @@ You should then end up with something like that::
 But how do you run your application now?  The naive ``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
-a big problem, just add a new file called :file:`setup.py` next to the inner
+a big problem, just add a new file called :file:`pyproject.toml` next to the inner
-:file:`yourapplication` folder with the following contents::
+:file:`yourapplication` folder with the following contents:
 
-    from setuptools import setup
+.. code-block:: toml
 
-    setup(
+    [project]
-        name='yourapplication',
+    name = "yourapplication"
-        packages=['yourapplication'],
+    dependencies = [
-        include_package_data=True,
+        "flask",
-        install_requires=[
+    ]
-            'flask',
+
-        ],
+    [build-system]
-    )
+    requires = ["setuptools"]
+    build-backend = "setuptools.build_meta"
 
 Install your application so it is importable:
 
@@ -98,7 +99,7 @@ And this is what :file:`views.py` would look like::
 You should then end up with something like that::
 
     /yourapplication
-        setup.py
+        pyproject.toml
         /yourapplication
             __init__.py
             views.py

docs/tutorial/deploy.rst

@@ -14,22 +14,13 @@ application.
 Build and Install
 -----------------
 
-When you want to deploy your application elsewhere, you build a
+When you want to deploy your application elsewhere, you build a *wheel*
-distribution file. The current standard for Python distribution is the
+(``.whl``) file. Install and use the ``build`` tool to do this.
-*wheel* format, with the ``.whl`` extension. Make sure the wheel library
-is installed first:
 
 .. code-block:: none
 
-    $ pip install wheel
+    $ pip install build
-
+    $ python -m build --wheel
-Running ``setup.py`` with Python gives you a command line tool to issue
-build-related commands. The ``bdist_wheel`` command will build a wheel
-distribution file.
-
-.. code-block:: none
-
-    $ python setup.py bdist_wheel
 
 You can find the file in ``dist/flaskr-1.0.0-py3-none-any.whl``. The
 file name is in the format of {project name}-{version}-{python tag}
@@ -54,7 +45,7 @@ create the database in the instance folder.
 
 When Flask detects that it's installed (not in editable mode), it uses
 a different directory for the instance folder. You can find it at
-``venv/var/flaskr-instance`` instead.
+``.venv/var/flaskr-instance`` instead.
 
 
 Configure the Secret Key
@@ -77,7 +68,7 @@ Create the ``config.py`` file in the instance folder, which the factory
 will read from if it exists. Copy the generated value into it.
 
 .. code-block:: python
-    :caption: ``venv/var/flaskr-instance/config.py``
+    :caption: ``.venv/var/flaskr-instance/config.py``
 
     SECRET_KEY = '192b9bdd22ab9ed4d12e236c78afcb9a393ec15f71bbf5dc987d54727823bcbf'
 

docs/tutorial/install.rst

@@ -1,11 +1,10 @@
 Make the Project Installable
 ============================
 
-Making your project installable means that you can build a
+Making your project installable means that you can build a *wheel* file and install that
-*distribution* file and install that in another environment, just like
+in another environment, just like you installed Flask in your project's environment.
-you installed Flask in your project's environment. This makes deploying
+This makes deploying your project the same as installing any other library, so you're
-your project the same as installing any other library, so you're using
+using all the standard Python tools to manage everything.
-all the standard Python tools to manage everything.
 
 Installing also comes with other benefits that might not be obvious from
 the tutorial or as a new Python user, including:
@@ -28,31 +27,25 @@ the tutorial or as a new Python user, including:
 Describe the Project
 --------------------
 
-The ``setup.py`` file describes your project and the files that belong
+The ``pyproject.toml`` file describes your project and how to build it.
-to it.
 
-.. code-block:: python
+.. code-block:: toml
-    :caption: ``setup.py``
+    :caption: ``pyproject.toml``
 
-    from setuptools import find_packages, setup
+    [project]
+    name = "flaskr"
+    version = "1.0.0"
+    dependencies = [
+        "flask",
+    ]
 
-    setup(
+    [build-system]
-        name='flaskr',
+    requires = ["setuptools"]
-        version='1.0.0',
+    build-backend = "setuptools.build_meta"
-        packages=find_packages(),
-        include_package_data=True,
-        install_requires=[
-            'flask',
-        ],
-    )
 
 
-``packages`` tells Python what package directories (and the Python files
+The setuptools build backend needs another file named ``MANIFEST.in`` to tell it about
-they contain) to include. ``find_packages()`` finds these directories
+non-Python files to include.
-automatically so you don't have to type them out. To include other
-files, such as the static and templates directories,
-``include_package_data`` is set. Python needs another file named
-``MANIFEST.in`` to tell what this other data is.
 
 .. code-block:: none
     :caption: ``MANIFEST.in``
@@ -62,9 +55,8 @@ files, such as the static and templates directories,
     graft flaskr/templates
     global-exclude *.pyc
 
-This tells Python to copy everything in the ``static`` and ``templates``
+This tells the build to copy everything in the ``static`` and ``templates`` directories,
-directories, and the ``schema.sql`` file, but to exclude all bytecode
+and the ``schema.sql`` file, but to exclude all bytecode files.
-files.
 
 See the official `Packaging tutorial <packaging tutorial_>`_ and
 `detailed guide <packaging guide_>`_ for more explanation of the files
@@ -83,10 +75,10 @@ Use ``pip`` to install your project in the virtual environment.
 
     $ pip install -e .
 
-This tells pip to find ``setup.py`` in the current directory and install
+This tells pip to find ``pyproject.toml`` in the current directory and install the
-it in *editable* or *development* mode. Editable mode means that as you
+project in *editable* or *development* mode. Editable mode means that as you make
-make changes to your local code, you'll only need to re-install if you
+changes to your local code, you'll only need to re-install if you change the metadata
-change the metadata about the project, such as its dependencies.
+about the project, such as its dependencies.
 
 You can observe that the project is now installed with ``pip list``.
 

docs/tutorial/layout.rst

@@ -41,7 +41,7 @@ The project directory will contain:
 * ``flaskr/``, a Python package containing your application code and
   files.
 * ``tests/``, a directory containing test modules.
-* ``venv/``, a Python virtual environment where Flask and other
+* ``.venv/``, a Python virtual environment where Flask and other
   dependencies are installed.
 * Installation files telling Python how to install your project.
 * Version control config, such as `git`_. You should make a habit of
@@ -80,8 +80,8 @@ By the end, your project layout will look like this:
     │   ├── test_db.py
     │   ├── test_auth.py
     │   └── test_blog.py
-    ├── venv/
+    ├── .venv/
-    ├── setup.py
+    ├── pyproject.toml
     └── MANIFEST.in
 
 If you're using version control, the following files that are generated
@@ -92,7 +92,7 @@ write. For example, with git:
 .. code-block:: none
     :caption: ``.gitignore``
 
-    venv/
+    .venv/
 
     *.pyc
     __pycache__/

docs/tutorial/tests.rst

@@ -490,20 +490,18 @@ no longer exist in the database.
 Running the Tests
 -----------------
 
-Some extra configuration, which is not required but makes running
+Some extra configuration, which is not required but makes running tests with coverage
-tests with coverage less verbose, can be added to the project's
+less verbose, can be added to the project's ``pyproject.toml`` file.
-``setup.cfg`` file.
 
-.. code-block:: none
+.. code-block:: toml
-    :caption: ``setup.cfg``
+    :caption: ``pyproject.toml``
 
-    [tool:pytest]
+    [tool.pytest.ini_options]
-    testpaths = tests
+    testpaths = ["tests"]
 
-    [coverage:run]
+    [tool.coverage.run]
-    branch = True
+    branch = true
-    source =
+    source = ["flaskr"]
-        flaskr
 
 To run the tests, use the ``pytest`` command. It will find and run all
 the test functions you've written.
@@ -514,7 +512,7 @@ the test functions you've written.
 
     ========================= test session starts ==========================
     platform linux -- Python 3.6.4, pytest-3.5.0, py-1.5.3, pluggy-0.6.0
-    rootdir: /home/user/Projects/flask-tutorial, inifile: setup.cfg
+    rootdir: /home/user/Projects/flask-tutorial
     collected 23 items
 
     tests/test_auth.py ........                                      [ 34%]

examples/javascript/.gitignore

@@ -1,4 +1,4 @@
-venv/
+.venv/
 *.pyc
 __pycache__/
 instance/

examples/javascript/README.rst

@@ -23,8 +23,8 @@ Install
 
 .. code-block:: text
 
-    $ python3 -m venv venv
+    $ python3 -m venv .venv
-    $ . venv/bin/activate
+    $ . .venv/bin/activate
     $ pip install -e .
 
 

examples/javascript/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "js_example"
+version = "1.1.0"
+description = "Demonstrates making AJAX requests to Flask."
+readme = "README.rst"
+license = {text = "BSD-3-Clause"}
+maintainers = [{name = "Pallets", email = "contact@palletsprojects.com"}]
+dependencies = ["flask"]
+
+[project.urls]
+Documentation = "https://flask.palletsprojects.com/patterns/jquery/"
+
+[project.optional-dependencies]
+test = ["pytest", "blinker"]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+branch = true
+source = ["js_example", "tests"]

examples/javascript/setup.cfg

@@ -1,29 +0,0 @@
-[metadata]
-name = js_example
-version = 1.1.0
-url = https://flask.palletsprojects.com/patterns/jquery/
-license = BSD-3-Clause
-maintainer = Pallets
-maintainer_email = contact@palletsprojects.com
-description = Demonstrates making AJAX requests to Flask.
-long_description = file: README.rst
-long_description_content_type = text/x-rst
-
-[options]
-packages = find:
-include_package_data = true
-install_requires =
-    Flask
-
-[options.extras_require]
-test =
-    pytest
-    blinker
-
-[tool:pytest]
-testpaths = tests
-
-[coverage:run]
-branch = True
-source =
-    js_example

examples/javascript/setup.py

@@ -1,3 +0,0 @@
-from setuptools import setup
-
-setup()

examples/tutorial/.gitignore

@@ -1,4 +1,4 @@
-venv/
+.venv/
 *.pyc
 __pycache__/
 instance/

examples/tutorial/README.rst

@@ -23,13 +23,13 @@ default Git version is the main branch. ::
 
 Create a virtualenv and activate it::
 
-    $ python3 -m venv venv
+    $ python3 -m venv .venv
-    $ . venv/bin/activate
+    $ . .venv/bin/activate
 
 Or on Windows cmd::
 
-    $ py -3 -m venv venv
+    $ py -3 -m venv .venv
-    $ venv\Scripts\activate.bat
+    $ .venv\Scripts\activate.bat
 
 Install Flaskr::
 

examples/tutorial/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "flaskr"
+version = "1.0.0"
+description = "The basic blog app built in the Flask tutorial."
+readme = "README.rst"
+license = {text = "BSD-3-Clause"}
+maintainers = [{name = "Pallets", email = "contact@palletsprojects.com"}]
+dependencies = [
+    "flask",
+]
+
+[project.urls]
+Documentation = "https://flask.palletsprojects.com/tutorial/"
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+branch = true
+source = ["flaskr", "tests"]

examples/tutorial/setup.cfg

@@ -1,28 +0,0 @@
-[metadata]
-name = flaskr
-version = 1.0.0
-url = https://flask.palletsprojects.com/tutorial/
-license = BSD-3-Clause
-maintainer = Pallets
-maintainer_email = contact@palletsprojects.com
-description = The basic blog app built in the Flask tutorial.
-long_description = file: README.rst
-long_description_content_type = text/x-rst
-
-[options]
-packages = find:
-include_package_data = true
-install_requires =
-    Flask
-
-[options.extras_require]
-test =
-    pytest
-
-[tool:pytest]
-testpaths = tests
-
-[coverage:run]
-branch = True
-source =
-    flaskr

examples/tutorial/setup.py

@@ -1,3 +0,0 @@
-from setuptools import setup
-
-setup()