From 3069052018cc1f1dd6dc2ed702b829a1a7147212 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Sun, 4 Feb 2024 17:16:02 -0700 Subject: update distributing chapter --- docs/tutorials/wiki2/distributing.rst | 41 +++++++++++++++++------------------ 1 file changed, 20 insertions(+), 21 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki2/distributing.rst b/docs/tutorials/wiki2/distributing.rst index 0eff63461..08f7d4d48 100644 --- a/docs/tutorials/wiki2/distributing.rst +++ b/docs/tutorials/wiki2/distributing.rst @@ -4,37 +4,36 @@ Distributing Your Application ============================= -Once your application works properly, you can create a "tarball" from it by -using the ``setup.py sdist`` command. The following commands assume your +.. note:: + + This is an optional step. + It is not required nor expected that every application is built to be distributed to a package index. + However, even when building personal projects, defining it as a distributable artifact can provide many advantages when it comes to optimizing your build for a Docker image or other "production" hardened environments that should not mirror your local development environment exactly. + +Once your application works properly, you can create a "sdist" or "wheel" from +it by using a PEP517-compliant client tool. The following commands assume your current working directory contains the ``tutorial`` package and the -``setup.py`` file. +``pyproject.toml`` file. On Unix: .. code-block:: bash - $VENV/bin/python setup.py sdist + $VENV/bin/pip install build + $VENV/bin/python -m build On Windows: .. code-block:: doscon - %VENV%\Scripts\python setup.py sdist - -The output of such a command will be something like: - -.. code-block:: text + %VENV%\Scripts\pip install build + %VENV%\Scripts\python -m build - running sdist - # more output - creating dist - Creating tar archive - removing 'tutorial-0.0' (and everything under it) +Upon successfull completion, a "sdist" and a "wheel" will be output to the ``dist`` subdirectory. +These artifacts are uploadable to `PyPI `_ using a tool like ``twine``. +You should be able to create a brand new virtualenv and ``pip install`` the sdist or wheel. +Note that the ``production.ini`` is not part of the distribution. +This file is considered to be defined by the "user" of your application, not part of the application itself. +If you'd like to help a user out, consider defining a new CLI script that can render a config file for them! -Note that this command creates a tarball in the ``dist`` subdirectory named -``tutorial-0.0.tar.gz``. You can send this file to your friends to show them -your cool new application. They should be able to install it by pointing the -``pip install`` command directly at it. Or you can upload it to `PyPI -`_ and share it with the rest of the world, where -it can be downloaded via ``pip install`` remotely like any other package people -download from PyPI. +Please learn more about distributing an application from the `Python Packaging User Guide `_. -- cgit v1.2.3