Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

GH-107987: Remove the Distributing Python Modules guide (#108016)

This commit is contained in:
Adam Turner 2023-08-17 11:01:14 +01:00 committed by GitHub
parent f51f0466c0
commit 33e6e3fec0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 16 additions and 170 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Doc/conf.py
View File

@ -354,8 +354,6 @@ _stdauthor = 'Guido van Rossum and the Python development team'
latex_documents = [
('c-api/index', 'c-api.tex',
'The Python/C API', _stdauthor, 'manual'),
('distributing/index', 'distributing.tex',
'Distributing Python Modules', _stdauthor, 'manual'),
('extending/index', 'extending.tex',
'Extending and Embedding Python', _stdauthor, 'manual'),
('installing/index', 'installing.tex',

1
Doc/contents.rst
View File

@ -11,7 +11,6 @@
library/index.rst
extending/index.rst
c-api/index.rst
distributing/index.rst
installing/index.rst
howto/index.rst
faq/index.rst

175
Doc/distributing/index.rst
View File

@ -1,174 +1,19 @@
:orphan:
.. This page is retained solely for existing links to /distributing/index.html.
Direct readers to the PPUG instead.
.. _distributing-index:
###############################
Distributing Python Modules
###############################
:Email: distutils-sig@python.org
As a popular open source development project, Python has an active
supporting community of contributors and users that also make their software
available for other Python developers to use under open source license terms.
This allows Python users to share and collaborate effectively, benefiting
from the solutions others have already created to common (and sometimes
even rare!) problems, as well as potentially contributing their own
solutions to the common pool.
This guide covers the distribution part of the process. For a guide to
installing other Python projects, refer to the
:ref:`installation guide <installing-index>`.
.. note::
For corporate and other institutional users, be aware that many
organisations have their own policies around using and contributing to
open source software. Please take such policies into account when making
use of the distribution and installation tools provided with Python.
Information and guidance on distributing Python modules and packages
has been moved to the `Python Packaging User Guide`_,
and the tutorial on `packaging Python projects`_.
Key terms
=========
* the `Python Package Index <https://pypi.org>`__ is a public
repository of open source licensed packages made available for use by
other Python users
* the `Python Packaging Authority
<https://www.pypa.io/>`__ are the group of
developers and documentation authors responsible for the maintenance and
evolution of the standard packaging tools and the associated metadata and
file format standards. They maintain a variety of tools, documentation
and issue trackers on `GitHub <https://github.com/pypa>`__.
* ``distutils`` is the original build and distribution system first added
to the Python standard library in 1998. While direct use of ``distutils``
is being phased out, it still laid the foundation for the current packaging
and distribution infrastructure, and it not only remains part of the
standard library, but its name lives on in other ways (such as the name
of the mailing list used to coordinate Python packaging standards
development).
* `setuptools`_ is a (largely) drop-in replacement for ``distutils`` first
published in 2004. Its most notable addition over the unmodified
``distutils`` tools was the ability to declare dependencies on other
packages. It is currently recommended as a more regularly updated
alternative to ``distutils`` that offers consistent support for more
recent packaging standards across a wide range of Python versions.
* `wheel`_ (in this context) is a project that adds the ``bdist_wheel``
command to ``distutils``/`setuptools`_. This produces a cross platform
binary packaging format (called "wheels" or "wheel files" and defined in
:pep:`427`) that allows Python libraries, even those including binary
extensions, to be installed on a system without needing to be built
locally.
.. _setuptools: https://setuptools.readthedocs.io/en/latest/
.. _wheel: https://wheel.readthedocs.io/
Open source licensing and collaboration
=======================================
In most parts of the world, software is automatically covered by copyright.
This means that other developers require explicit permission to copy, use,
modify and redistribute the software.
Open source licensing is a way of explicitly granting such permission in a
relatively consistent way, allowing developers to share and collaborate
efficiently by making common solutions to various problems freely available.
This leaves many developers free to spend more time focusing on the problems
that are relatively unique to their specific situation.
The distribution tools provided with Python are designed to make it
reasonably straightforward for developers to make their own contributions
back to that common pool of software if they choose to do so.
The same distribution tools can also be used to distribute software within
an organisation, regardless of whether that software is published as open
source software or not.
Installing the tools
====================
The standard library does not include build tools that support modern
Python packaging standards, as the core development team has found that it
is important to have standard tools that work consistently, even on older
versions of Python.
The currently recommended build and distribution tools can be installed
by invoking the ``pip`` module at the command line::
python -m pip install setuptools wheel twine
.. note::
For POSIX users (including macOS and Linux users), these instructions
assume the use of a :term:`virtual environment`.
For Windows users, these instructions assume that the option to
adjust the system PATH environment variable was selected when installing
Python.
The Python Packaging User Guide includes more details on the `currently
recommended tools`_.
.. _currently recommended tools: https://packaging.python.org/guides/tool-recommendations/#packaging-tool-recommendations
.. index::
single: Python Package Index (PyPI)
single: PyPI; (see Python Package Index (PyPI))
.. _publishing-python-packages:
Reading the Python Packaging User Guide
=======================================
The Python Packaging User Guide covers the various key steps and elements
involved in creating and publishing a project:
* `Project structure`_
* `Building and packaging the project`_
* `Uploading the project to the Python Package Index`_
* `The .pypirc file`_
.. _Project structure: https://packaging.python.org/tutorials/packaging-projects/#packaging-python-projects
.. _Building and packaging the project: https://packaging.python.org/tutorials/packaging-projects/#creating-the-package-files
.. _Uploading the project to the Python Package Index: https://packaging.python.org/tutorials/packaging-projects/#uploading-the-distribution-archives
.. _The .pypirc file: https://packaging.python.org/specifications/pypirc/
How do I...?
============
These are quick answers or links for some common tasks.
... choose a name for my project?
---------------------------------
This isn't an easy topic, but here are a few tips:
* check the Python Package Index to see if the name is already in use
* check popular hosting sites like GitHub, Bitbucket, etc to see if there
is already a project with that name
* check what comes up in a web search for the name you're considering
* avoid particularly common words, especially ones with multiple meanings,
as they can make it difficult for users to find your software when
searching for it
... create and distribute binary extensions?
--------------------------------------------
This is actually quite a complex topic, with a variety of alternatives
available depending on exactly what you're aiming to achieve. See the
Python Packaging User Guide for more information and recommendations.
.. seealso::
`Python Packaging User Guide: Binary Extensions
<https://packaging.python.org/guides/packaging-binary-extensions/>`__
.. other topics:
Once the Development & Deployment part of PPUG is fleshed out, some of
those sections should be linked from new questions here (most notably,
we should have a question about avoiding depending on PyPI that links to
https://packaging.python.org/en/latest/mirrors/)
.. _Python Packaging User Guide: https://packaging.python.org/
.. _packaging Python projects: https://packaging.python.org/en/latest/tutorials/packaging-projects/

4
Doc/installing/index.rst
View File

@ -19,7 +19,9 @@ solutions to the common pool.
This guide covers the installation part of the process. For a guide to
creating and sharing your own Python projects, refer to the
:ref:`distribution guide <distributing-index>`.
`Python packaging user guide`_.
.. _Python Packaging User Guide: https://packaging.python.org/en/latest/tutorials/packaging-projects/
.. note::

4
Doc/tutorial/venv.rst
View File

@ -207,4 +207,6 @@ necessary packages with ``install -r``:
``pip`` has many more options. Consult the :ref:`installing-index`
guide for complete documentation for ``pip``. When you've written
a package and want to make it available on the Python Package Index,
consult the :ref:`distributing-index` guide.
consult the `Python packaging user guide`_.
.. _Python Packaging User Guide: https://packaging.python.org/en/latest/tutorials/packaging-projects/