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