extensions, to be installed on a system without needing to be built
locally.
-.. _setuptools: https://setuptools.pypa.io/en/latest/setuptools.html
+.. _setuptools: https://setuptools.readthedocs.io/en/latest/
.. _wheel: https://wheel.readthedocs.org
Open source licensing and collaboration
.. _distutils-index:
-###############################
- Distributing Python Modules
-###############################
+##############################################
+ Distributing Python Modules (Legacy version)
+##############################################
:Authors: Greg Ward, Anthony Baxter
:Email: distutils-sig@python.org
+.. seealso::
+
+ :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
.. _install-index:
-*****************************
- Installing Python Modules
-*****************************
+********************************************
+ Installing Python Modules (Legacy version)
+********************************************
:Author: Greg Ward
.. TODO: Fill in XXX comments
+.. 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.
-
:mod:`distutils` --- Building and installing Python modules
===========================================================
.. module:: distutils
- :synopsis: Support for building and installing Python modules into an existing Python
- installation.
+ :synopsis: Support for building and installing Python modules into an
+ existing Python installation.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
100%-pure Python, or may be extension modules written in C, or may be
collections of Python packages which include modules coded in both Python and C.
-This package is discussed in two separate chapters:
-
-
-.. seealso::
-
- :ref:`distutils-index`
- The manual for developers and packagers of Python modules. This describes how
- to prepare :mod:`distutils`\ -based packages so that they may be easily
- installed into an existing Python installation.
-
- :ref:`install-index`
- An "administrators" manual which includes information on installing modules into
- an existing Python installation. You do not need to be a Python programmer to
- read this manual.
-
+Most Python users will *not* want to use this module directly, but instead
+use the cross-version tools maintained by the Python Packaging Authority. In
+particular,
+`setuptools <https://setuptools.readthedocs.io/en/latest/>`__ is an
+enhanced alternative to :mod:`distutils` that provides:
+
+* support for declaring project dependencies
+* additional mechanisms for configuring which files to include in source
+ releases (including plugins for integration with version control systems)
+* the ability to declare project "entry points", which can be used as the
+ basis for application plugin systems
+* the ability to automatically generate Windows command line executables at
+ installation time rather than needing to prebuild them
+* consistent behaviour across all supported Python versions
+
+The recommended `pip <https://pip.pypa.io/>`__ installer runs all
+``setup.py`` scripts with ``setuptools``, even if the script itself only
+imports ``distutils``. Refer to the
+`Python Packaging User Guide <https://packaging.python.org>`_ for more
+information.
+
+For the benefits of packaging tool authors and users seeking a deeper
+understanding of the details of the current packaging and distribution
+system, the legacy :mod:`distutils` based user documentation and API
+reference remain available:
+
+* :ref:`install-index`
+* :ref:`distutils-index`
<p class="biglink"><a class="biglink" href="{{ pathto("howto/index") }}">{% trans %}Python HOWTOs{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}in-depth documents on specific topics{% endtrans %}</span></p>
</td><td width="50%">
+ <p class="biglink"><a class="biglink" href="{{ pathto("installing/index") }}">{% trans %}Installing Python Modules{% endtrans %}</a><br/>
+ <span class="linkdescr">{% trans %}installing from the Python Package Index & other sources{% endtrans %}</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("distributing/index") }}">{% trans %}Distributing Python Modules{% endtrans %}</a><br/>
+ <span class="linkdescr">{% trans %}publishing modules for installation by others{% endtrans %}</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("extending/index") }}">{% trans %}Extending and Embedding{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}tutorial for C/C++ programmers{% endtrans %}</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("c-api/index") }}">{% trans %}Python/C API{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}reference for C/C++ programmers{% endtrans %}</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("install/index") }}">{% trans %}Installing Python Modules{% endtrans %}</a><br/>
- <span class="linkdescr">{% trans %}information for installers & sys-admins{% endtrans %}</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("distutils/index") }}">{% trans %}Distributing Python Modules{% endtrans %}</a><br/>
- <span class="linkdescr">{% trans %}sharing modules with others{% endtrans %}</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("faq/index") }}">{% trans %}FAQs{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}frequently asked questions (with answers!){% endtrans %}</span></p>
</td></tr>
functions together, and add more details such as what underlying Readline
functions and variables are accessed.
+- Issue #26014: Guide users to the newer packaging documentation as was done
+ for Python 3.x. In particular, the top-level 2.7 documentation page now
+ links to the newer installer and distributions pages rather than the
+ legacy install and Distutils pages; these are still linked to in the
+ library/distutils doc page.
+
Tests
-----
projects / python / commitdiff