forked from orbit-oss/flask
update docs and examples for pyproject
setup.py -> pyproject.toml venv -> .venv
This commit is contained in:
David Lord
parent
6d6d986fc5
commit
8f13f5b6d6
24 changed files with 153 additions and 195 deletions
41
docs/cli.rst
41
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
|
||||
|
||||
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``. ::
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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'
|
||||
|
||||
|
|
|
|||
|
|
@ -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``.
|
||||
|
||||
|
|
|
|||
|
|
@ -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__/
|
||||
|
|
|
|||
|
|
@ -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%]
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue