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

update docs and examples for pyproject

Browse source 
setup.py -> pyproject.toml
venv -> .venv
This commit is contained in:
David Lord 2023-01-18 10:21:37 -08:00
parent 6d6d986fc5
commit 8f13f5b6d6
No known key found for this signature in database
GPG key ID: 7A1C87E3F5BC42A8
24 changed files with 153 additions and 195 deletions
Download patch file Download diff file Expand all files Collapse all files

6
CONTRIBUTING.rst
View file

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

41
docs/cli.rst
View file

@ -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
setup(
name='flask-my-extension',
...,
entry_points={
'flask.commands': [
'my-command=flask_my_extension.commands:cli'
],
},
)
.. 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:`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(
name='flask-my-extension',
...,
entry_points={
'console_scripts': [
'wiki=wiki:cli'
],
},
)
[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``. ::

4
docs/deploying/eventlet.rst
View file

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

4
docs/deploying/gevent.rst
View file

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

4
docs/deploying/gunicorn.rst
View file

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

6
docs/deploying/mod_wsgi.rst
View file

@ -33,8 +33,8 @@ Create a virtualenv, install your application, then install
.. code-block:: text
$ cd hello-app
$ python -m venv venv
$ . venv/bin/activate
$ python -m venv .venv
$ . .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

4
docs/deploying/uwsgi.rst
View file

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

4
docs/deploying/waitress.rst
View file

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

10
docs/installation.rst
View file

@ -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.

25
docs/patterns/packages.rst
View file

@ -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
:file:`yourapplication` folder with the following contents::
a big problem, just add a new file called :file:`pyproject.toml` next to the inner
:file:`yourapplication` folder with the following contents:
from setuptools import setup
.. code-block:: toml
setup(
name='yourapplication',
packages=['yourapplication'],
include_package_data=True,
install_requires=[
'flask',
],
)
[project]
name = "yourapplication"
dependencies = [
"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

21
docs/tutorial/deploy.rst
View file

@ -14,22 +14,13 @@ application.
Build and Install
-----------------
When you want to deploy your application elsewhere, you build a
distribution file. The current standard for Python distribution is the
*wheel* format, with the ``.whl`` extension. Make sure the wheel library
is installed first:
When you want to deploy your application elsewhere, you build a *wheel*
(``.whl``) file. Install and use the ``build`` tool to do this.
.. code-block:: none
$ pip install 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
$ pip install build
$ python -m build --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'

56
docs/tutorial/install.rst
View file

@ -1,11 +1,10 @@
Make the Project Installable
============================
Making your project installable means that you can build a
*distribution* file and install that in another environment, just like
you installed Flask in your project's environment. This makes deploying
your project the same as installing any other library, so you're using
all the standard Python tools to manage everything.
Making your project installable means that you can build a *wheel* file and install that
in another environment, just like you installed Flask in your project's environment.
This makes deploying your project the same as installing any other library, so you're
using 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
to it.
The ``pyproject.toml`` file describes your project and how to build it.
.. code-block:: python
:caption: ``setup.py``
.. code-block:: toml
:caption: ``pyproject.toml``
from setuptools import find_packages, setup
[project]
name = "flaskr"
version = "1.0.0"
dependencies = [
"flask",
]
setup(
name='flaskr',
version='1.0.0',
packages=find_packages(),
include_package_data=True,
install_requires=[
'flask',
],
)
[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"
``packages`` tells Python what package directories (and the Python files
they contain) to include. ``find_packages()`` finds these directories
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.
The setuptools build backend needs another file named ``MANIFEST.in`` to tell it about
non-Python files to include.
.. 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``
directories, and the ``schema.sql`` file, but to exclude all bytecode
files.
This tells the build to copy everything in the ``static`` and ``templates`` directories,
and the ``schema.sql`` file, but to exclude all bytecode 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
it in *editable* or *development* mode. Editable mode means that as you
make changes to your local code, you'll only need to re-install if you
change the metadata about the project, such as its dependencies.
This tells pip to find ``pyproject.toml`` in the current directory and install the
project in *editable* or *development* mode. Editable mode means that as you make
changes to your local code, you'll only need to re-install if you change the metadata
about the project, such as its dependencies.
You can observe that the project is now installed with ``pip list``.

8
docs/tutorial/layout.rst
View file

@ -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/
├── setup.py
├── .venv/
├── 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__/

22
docs/tutorial/tests.rst
View file

@ -490,20 +490,18 @@ no longer exist in the database.
Running the Tests
-----------------
Some extra configuration, which is not required but makes running
tests with coverage less verbose, can be added to the project's
``setup.cfg`` file.
Some extra configuration, which is not required but makes running tests with coverage
less verbose, can be added to the project's ``pyproject.toml`` file.
.. code-block:: none
:caption: ``setup.cfg``
.. code-block:: toml
:caption: ``pyproject.toml``
[tool:pytest]
testpaths = tests
[tool.pytest.ini_options]
testpaths = ["tests"]
[coverage:run]
branch = True
source =
flaskr
[tool.coverage.run]
branch = true
source = ["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%]

2
examples/javascript/.gitignore vendored
View file

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

4
examples/javascript/README.rst
View file

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

26
examples/javascript/pyproject.toml Normal file
View file

@ -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"]

29
examples/javascript/setup.cfg
View file

@ -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

3
examples/javascript/setup.py
View file

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

2
examples/tutorial/.gitignore vendored
View file

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

8
examples/tutorial/README.rst
View file

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

28
examples/tutorial/pyproject.toml Normal file
View file

@ -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"]

28
examples/tutorial/setup.cfg
View file

@ -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

3
examples/tutorial/setup.py
View file

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