bpo-36797: Prune more legacy distutils documentation (GH-13092)

Removes more legacy distutils documentation, and more clearly
marks what is left as potentially outdated, with references to
setuptools as a replacement.
This commit is contained in:
Nick Coghlan 2019-05-14 22:04:30 +10:00 committed by GitHub
parent 0a52d73dde
commit dae1229729
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 58 additions and 68 deletions

View File

@ -0,0 +1,5 @@
.. note::
This document is being retained solely until the ``setuptools`` documentation
at https://setuptools.readthedocs.io/en/latest/setuptools.html
independently covers all of the relevant information currently included here.

View File

@ -4,6 +4,16 @@
API Reference
*************
.. seealso::
`New and changed setup.py arguments in setuptools <setuptools-setup-py>`_
The ``setuptools`` project adds new capabilities to the ``setup`` function
and other APIs, makes the API consistent across different Python versions,
and is hence recommended over using ``distutils`` directly.
.. _setuptools-setup-py: https://setuptools.readthedocs.io/en/latest/setuptools.html#new-and-changed-setup-keywords
.. include:: ./_setuptools_disclaimer.rst
:mod:`distutils.core` --- Core Distutils functionality
======================================================

View File

@ -4,6 +4,8 @@
Creating Built Distributions
****************************
.. include:: ./_setuptools_disclaimer.rst
A "built distribution" is what you're probably used to thinking of either as a
"binary package" or an "installer" (depending on your background). It's not
necessarily binary, though, because it might contain only Python source code

View File

@ -4,6 +4,8 @@
Command Reference
*****************
.. include:: ./_setuptools_disclaimer.rst
.. % \section{Building modules: the \protect\command{build} command family}
.. % \label{build-cmds}
.. % \subsubsection{\protect\command{build}}

View File

@ -4,6 +4,8 @@
Writing the Setup Configuration File
************************************
.. include:: ./_setuptools_disclaimer.rst
Often, it's not possible to write down everything needed to build a distribution
*a priori*: you may need to get some information from the user, or from the
user's system, in order to proceed. As long as that information is fairly

View File

@ -4,6 +4,8 @@
Examples
********
.. include:: ./_setuptools_disclaimer.rst
This chapter provides a number of basic examples to help get started with
distutils. Additional information about using distutils can be found in the
Distutils Cookbook.

View File

@ -4,6 +4,8 @@
Extending Distutils
*******************
.. include:: ./_setuptools_disclaimer.rst
Distutils can be extended in various ways. Most extensions take the form of new
commands or replacements for existing commands. New commands may be written to
support new types of platform-specific packaging, for example, while

View File

@ -12,10 +12,7 @@
:ref:`distributing-index`
The up to date module distribution documentations
This document describes the Python Distribution Utilities ("Distutils") from
the module developer's point of view, describing how to use the Distutils to
make Python modules and extensions easily available to a wider audience with
very little overhead for build/release/install mechanics.
.. include:: ./_setuptools_disclaimer.rst
.. note::
@ -25,6 +22,11 @@ very little overhead for build/release/install mechanics.
recommendations section <https://packaging.python.org/guides/tool-recommendations/>`__
in the Python Packaging User Guide for more information.
This document describes the Python Distribution Utilities ("Distutils") from
the module developer's point of view, describing the underlying capabilities
that ``setuptools`` builds on to allow Python developers to make Python modules
and extensions readily available to a wider audience.
.. toctree::
:maxdepth: 2
:numbered:

View File

@ -4,6 +4,8 @@
An Introduction to Distutils
****************************
.. include:: ./_setuptools_disclaimer.rst
This document covers using the Distutils to distribute your Python modules,
concentrating on the role of developer/distributor: if you're looking for
information on installing Python modules, you should refer to the

View File

@ -4,6 +4,8 @@
Writing the Setup Script
************************
.. include:: ./_setuptools_disclaimer.rst
The setup script is the centre of all activity in building, distributing, and
installing modules using the Distutils. The main purpose of the setup script is
to describe your module distribution to the Distutils, so that the various

View File

@ -4,6 +4,8 @@
Creating a Source Distribution
******************************
.. include:: ./_setuptools_disclaimer.rst
As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command
to create a source distribution. In the simplest case, ::

View File

@ -13,23 +13,10 @@
.. seealso::
:ref:`installing-index`
The up to date module installation documentations
.. The audience for this document includes people who don't know anything
about Python and aren't about to learn the language just in order to
install and maintain it for their users, i.e. system administrators.
Thus, I have to be sure to explain the basics at some point:
sys.path and PYTHONPATH at least. Should probably give pointers to
other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc.
Finally, it might be useful to include all the material from my "Care
and Feeding of a Python Installation" talk in here somewhere. Yow!
This document describes the Python Distribution Utilities ("Distutils") from the
end-user's point-of-view, describing how to extend the capabilities of a
standard Python installation by building and installing third-party Python
modules and extensions.
The up to date module installation documentation. For regular Python
usage, you almost certainly want that document rather than this one.
.. include:: ../distutils/_setuptools_disclaimer.rst
.. note::
@ -46,59 +33,26 @@ modules and extensions.
Introduction
============
Although Python's extensive standard library covers many programming needs,
there often comes a time when you need to add some new functionality to your
Python installation in the form of third-party modules. This might be necessary
to support your own programming, or to support an application that you want to
use and that happens to be written in Python.
In Python 2.0, the ``distutils`` API was first added to the standard library.
This provided Linux distro maintainers with a standard way of converting
Python projects into Linux distro packages, and system administrators with a
standard way of installing them directly onto target systems.
In the past, there has been little support for adding third-party modules to an
existing Python installation. With the introduction of the Python Distribution
Utilities (Distutils for short) in Python 2.0, this changed.
In the many years since Python 2.0 was released, tightly coupling the build
system and package installer to the language runtime release cycle has turned
out to be problematic, and it is now recommended that projects use the
``pip`` package installer and the ``setuptools`` build system, rather than
using ``distutils`` directly.
This document is aimed primarily at the people who need to install third-party
Python modules: end-users and system administrators who just need to get some
Python application running, and existing Python programmers who want to add some
new goodies to their toolbox. You don't need to know Python to read this
document; there will be some brief forays into using Python's interactive mode
to explore your installation, but that's it. If you're looking for information
on how to distribute your own Python modules so that others may use them, see
the :ref:`distutils-index` manual. :ref:`debug-setup-script` may also be of
interest.
.. _inst-trivial-install:
Best case: trivial installation
-------------------------------
In the best case, someone will have prepared a special version of the module
distribution you want to install that is targeted specifically at your platform
and is installed just like any other software on your platform. For example,
the module developer might make an executable installer available for Windows
users, an RPM package for users of RPM-based Linux systems (Red Hat, SuSE,
Mandrake, and many others), a Debian package for users of Debian-based Linux
systems, and so forth.
In that case, you would download the installer appropriate to your platform and
do the obvious thing with it: run it if it's an executable installer, ``rpm
--install`` it if it's an RPM, etc. You don't need to run Python or a setup
script, you don't need to compile anything---you might not even need to read any
instructions (although it's always a good idea to do so anyway).
Of course, things will not always be that easy. You might be interested in a
module distribution that doesn't have an easy-to-use installer for your
platform. In that case, you'll have to start with the source distribution
released by the module's author/maintainer. Installing from a source
distribution is not too hard, as long as the modules are packaged in the
standard way. The bulk of this document is about building and installing
modules from standard source distributions.
See :ref:`installing-index` and :ref:`distributing-index` for more details.
This legacy documentation is being retained only until we're confident that the
``setuptools`` documentation covers everything needed.
.. _inst-new-standard:
The new standard: Distutils
---------------------------
Distutils based source distributions
------------------------------------
If you download a module source distribution, you can tell pretty quickly if it
was packaged and distributed in the standard way, i.e. using the Distutils.

View File

@ -4,7 +4,7 @@ c-api/sequence,,:i2,del o[i1:i2]
c-api/sequence,,:i2,o[i1:i2]
c-api/unicode,,:end,str[start:end]
c-api/unicode,,:start,unicode[start:start+length]
distutils/examples,267,`,This is the description of the ``foobar`` package.
distutils/examples,274,`,This is the description of the ``foobar`` package.
distutils/setupscript,,::,
extending/embedding,,:numargs,"if(!PyArg_ParseTuple(args, "":numargs""))"
extending/extending,,:myfunction,"PyArg_ParseTuple(args, ""D:myfunction"", &c);"

1 c-api/arg :ref PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
4 c-api/sequence :i2 o[i1:i2]
5 c-api/unicode :end str[start:end]
6 c-api/unicode :start unicode[start:start+length]
7 distutils/examples 267 274 ` This is the description of the ``foobar`` package.
8 distutils/setupscript ::
9 extending/embedding :numargs if(!PyArg_ParseTuple(args, ":numargs"))
10 extending/extending :myfunction PyArg_ParseTuple(args, "D:myfunction", &c);

View File

@ -0,0 +1,3 @@
More of the legacy distutils documentation has been either pruned, or else
more clearly marked as being retained solely until the setuptools
documentation covers it independently.