From 94d5ce60c783eed483d2fff49a6470b066430bfb Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Wed, 7 Feb 2024 12:24:11 -0500 Subject: docs: update ZODB wiki tutorial to cookiecutter - Describe 'pyproject.toml' usage (replacing 'setup.py', 'pytest.ini', '.coveragerc'). - Document the new PyPA-blessed build process. --- docs/tutorials/wiki/distributing.rst | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) (limited to 'docs/tutorials/wiki/distributing.rst') diff --git a/docs/tutorials/wiki/distributing.rst b/docs/tutorials/wiki/distributing.rst index c23f79b5a..a423e8b96 100644 --- a/docs/tutorials/wiki/distributing.rst +++ b/docs/tutorials/wiki/distributing.rst @@ -4,33 +4,37 @@ Distributing Your Application ============================= -Once your application works properly, you can create a :term:`distribution` from it by using the ``setup.py sdist`` command. -The following commands assume your current working directory contains the ``tutorial`` package and the ``setup.py`` file. +Once your application works properly, you can create a :term:`distribution` from it by using the PyPA ``build`` command. +The following commands assume your current working directory contains the ``tutorial`` package and its ``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 + %VENV%\Scripts\pip install build + %VENV%\Scripts\python -m build The output of such a command will be something like: .. code-block:: text - running sdist - # more output - creating dist - Creating tar archive - removing 'tutorial-0.0' (and everything under it) + * Creating venv isolated environment... + * Installing packages in isolated environment... (setuptools) + * Getting build dependencies for sdist... + ... + removing build/bdist.linux-x86_64/wheel + Successfully built tutorial-0.0.tar.gz and tutorial-0.0-py3-none-any.whl + This command creates a subdirectory named ``dist``. -Inside that is a tarball named ``tutorial-0.0.tar.gz``, which is the :term:`distribution` of your application. -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. +Inside that is a tarball named ``tutorial-0.0.tar.gz`` (the source :term:`distribution` of your application), as well ass ``tutorial-0.0-py3-none-any.whl`` (the binary :term:`distribution`). +You can send these files to your friends to show them your cool new application. +They should be able to install the app by pointing the ``pip install`` command directly at one of them. +Or you can upload them to `PyPI `_ and share them with the rest of the world, where it can be downloaded via ``pip install`` remotely like any other package people download from PyPI. -- cgit v1.2.3 From d3987fc46c2a52eb7521bb4849c375751ac9ecad Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Wed, 7 Feb 2024 21:01:59 -0500 Subject: docs: fold in 'Distributing' language from the 'wiki2' refresh (PR #3747) --- docs/tutorials/wiki/distributing.rst | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) (limited to 'docs/tutorials/wiki/distributing.rst') diff --git a/docs/tutorials/wiki/distributing.rst b/docs/tutorials/wiki/distributing.rst index a423e8b96..4ad7ffb9f 100644 --- a/docs/tutorials/wiki/distributing.rst +++ b/docs/tutorials/wiki/distributing.rst @@ -4,8 +4,16 @@ Distributing Your Application ============================= -Once your application works properly, you can create a :term:`distribution` from it by using the PyPA ``build`` command. -The following commands assume your current working directory contains the ``tutorial`` package and its ``pyproject.toml`` file. +.. 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 +``pyproject.toml`` file. On Unix: @@ -32,9 +40,14 @@ The output of such a command will be something like: removing build/bdist.linux-x86_64/wheel Successfully built tutorial-0.0.tar.gz and tutorial-0.0-py3-none-any.whl - This command creates a subdirectory named ``dist``. Inside that is a tarball named ``tutorial-0.0.tar.gz`` (the source :term:`distribution` of your application), as well ass ``tutorial-0.0-py3-none-any.whl`` (the binary :term:`distribution`). You can send these files to your friends to show them your cool new application. They should be able to install the app by pointing the ``pip install`` command directly at one of them. -Or you can upload them to `PyPI `_ and share them with the rest of the world, where it can be downloaded via ``pip install`` remotely like any other package people download from PyPI. +These artifacts are also uploadable to `PyPI `_, or another package index, using a tool like ``twine``. + +Note that the config files, such as ``production.ini`` are not part of the distribution. +These files are considered to be defined by the "user" of your application and not part of the application itself. +If you'd like to help a user out, consider defining a new CLI script similar to ``initialize_tutorial_db`` that can render a config file for them! + +Please learn more about distributing an application from the `Python Packaging User Guide `_. -- cgit v1.2.3