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:
parent
0a52d73dde
commit
dae1229729
|
@ -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.
|
|
@ -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
|
||||
======================================================
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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}}
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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:
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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, ::
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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);"
|
||||
|
|
|
|
@ -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.
|
Loading…
Reference in New Issue