From 49cf0e4f3dd5e1e06a5053cdafdfd2ceb7018b53 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Tue, 14 Jun 2022 14:30:22 +0100 Subject: [PATCH 1/4] Move userguide/commands to deprecated/commands --- docs/{userguide => deprecated}/commands.rst | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{userguide => deprecated}/commands.rst (100%) diff --git a/docs/userguide/commands.rst b/docs/deprecated/commands.rst similarity index 100% rename from docs/userguide/commands.rst rename to docs/deprecated/commands.rst From 6850040693db9e3edc4238c1fa4aa458aacaaa9b Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Tue, 14 Jun 2022 15:00:38 +0100 Subject: [PATCH 2/4] Merge docs on deprecated commands Also add a not about modern ways of generating ``sdists`` and ``wheel``. --- docs/conf.py | 1 + docs/deprecated/commands.rst | 43 ++++++++++++++++++++++++++++ docs/deprecated/index.rst | 2 +- docs/deprecated/running_commands.rst | 23 --------------- docs/userguide/index.rst | 1 - 5 files changed, 45 insertions(+), 25 deletions(-) delete mode 100644 docs/deprecated/running_commands.rst diff --git a/docs/conf.py b/docs/conf.py index 159eedcd71..a207c0d129 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -133,6 +133,7 @@ extensions += ['sphinx_reredirects'] redirects = { "userguide/keywords": "/deprecated/changed_keywords.html", + "userguide/commands": "/deprecated/commands.html", } # Add support for inline tabs diff --git a/docs/deprecated/commands.rst b/docs/deprecated/commands.rst index e632e550b3..89acef85ff 100644 --- a/docs/deprecated/commands.rst +++ b/docs/deprecated/commands.rst @@ -1,3 +1,46 @@ +=============================== +Running ``setuptools`` commands +=============================== + +Historically, ``setuptools`` allowed running commands via a ``setup.py`` script +at the root of a Python project, as indicated in the examples below:: + + python setup.py --help + python setup.py --help-commands + python setup.py --version + python setup.py sdist + python setup.py bdist_wheel + +You could also run commands in other circumstances: + +* ``setuptools`` projects without ``setup.py`` (e.g., ``setup.cfg``-only):: + + python -c "import setuptools; setup()" --help + +* ``distutils`` projects (with a ``setup.py`` importing ``distutils``):: + + python -c "import setuptools; with open('setup.py') as f: exec(compile(f.read(), 'setup.py', 'exec'))" develop + +That is, you can simply list the normal setup commands and options following the quoted part. + +.. warning:: + On recent versions of ``setuptools`` running commands via ``python setup.py`` + is considered **deprecated** (and should be avoided). + + If you want to create :term:`sdist ` or :term:`wheel` + distributions the recommendation is to use the command line tool provided by :pypi:`build`:: + + pip install build # needs to be installed first + + python -m build # builds both sdist and wheel + python -m build --sdist + python -m build --wheel + + Build will automatically download ``setuptools`` and build the package in an + isolated environment. You can also specify specific versions of + ``setuptools``, by setting the :doc:`build requirements in pyproject.toml + `. + ----------------- Command Reference ----------------- diff --git a/docs/deprecated/index.rst b/docs/deprecated/index.rst index ea9069ecb2..0ea66cf644 100644 --- a/docs/deprecated/index.rst +++ b/docs/deprecated/index.rst @@ -22,4 +22,4 @@ objectives. distutils/index distutils-legacy functionalities - running_commands + commands diff --git a/docs/deprecated/running_commands.rst b/docs/deprecated/running_commands.rst deleted file mode 100644 index 8d4ca93fc1..0000000000 --- a/docs/deprecated/running_commands.rst +++ /dev/null @@ -1,23 +0,0 @@ -Running ``setuptools`` commands -=============================== - -Historically, ``setuptools`` allowed running commands via a ``setup.py`` script -at the root of a Python project, as indicated in the examples below:: - - python setup.py --help - python setup.py --help-commands - python setup.py --version - python setup.py sdist - python setup.py bdist_wheel - -You could also run commands in other circumstances: - -* ``setuptools`` projects without ``setup.py`` (e.g., ``setup.cfg``-only):: - - python -c "import setuptools; setup()" --help - -* ``distutils`` projects (with a ``setup.py`` importing ``distutils``):: - - python -c "import setuptools; with open('setup.py') as f: exec(compile(f.read(), 'setup.py', 'exec'))" develop - -That is, you can simply list the normal setup commands and options following the quoted part. diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst index d5d150af2e..f8bef0137f 100644 --- a/docs/userguide/index.rst +++ b/docs/userguide/index.rst @@ -34,7 +34,6 @@ Contents extension declarative_config pyproject_config - commands miscellaneous --- From 1b694edd1885488e586b87fb0b4dcca5b5ec2cc6 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Tue, 14 Jun 2022 15:17:35 +0100 Subject: [PATCH 3/4] Add news fragment --- changelog.d/3371.doc.rst | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 changelog.d/3371.doc.rst diff --git a/changelog.d/3371.doc.rst b/changelog.d/3371.doc.rst new file mode 100644 index 0000000000..7e49c13907 --- /dev/null +++ b/changelog.d/3371.doc.rst @@ -0,0 +1,3 @@ +Moved documentation from ``/userguide/commands`` to ``/depracted/commands``. +This change was motived by the fact that running ``python setup.py`` directly is +considered a deprecated practice. From ddcfdfa9db21161af1ce3259ad63a148f3dc3242 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Tue, 14 Jun 2022 15:24:57 +0100 Subject: [PATCH 4/4] Add remark about install command --- docs/deprecated/commands.rst | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/docs/deprecated/commands.rst b/docs/deprecated/commands.rst index 89acef85ff..e287ab8f07 100644 --- a/docs/deprecated/commands.rst +++ b/docs/deprecated/commands.rst @@ -24,8 +24,11 @@ You could also run commands in other circumstances: That is, you can simply list the normal setup commands and options following the quoted part. .. warning:: - On recent versions of ``setuptools`` running commands via ``python setup.py`` - is considered **deprecated** (and should be avoided). + While it is perfectly fine that users write ``setup.py`` files to configure + a package build (e.g. to specify binary extensions or customize commands), + on recent versions of ``setuptools``, running ``python setup.py`` directly + as a script is considered **deprecated**. This also means that users should + avoid running commands directly via ``python setup.py ``. If you want to create :term:`sdist ` or :term:`wheel` distributions the recommendation is to use the command line tool provided by :pypi:`build`:: @@ -41,6 +44,16 @@ That is, you can simply list the normal setup commands and options following the ``setuptools``, by setting the :doc:`build requirements in pyproject.toml `. + If you want to install a package, you can use :pypi:`pip` or :pypi:`installer`:: + + pip install /path/to/wheel/file.whl + pip install /path/to/sdist/file.tar.gz + pip install . # replacement for python setup.py install + pip install --editable . # replacement for python setup.py develop + + pip install installer # nees to be installed first + python -m installer /path/to/wheel/file.whl + ----------------- Command Reference -----------------