Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit f7614d5

Browse files
ncoghlanncoghlan
committed
Close #19407: New installation & distribution guides
- based on pip and other PyPA tools - includes references to the new Python Packaging User Guide where appropriate (and the relevant section is at least partially filled in) - started new FAQ sections - both guides aim to introduce users to basic open source concepts if they aren't aware of them - existing guides have been relocated (now linked from the distutils docs) rather then removed, since there is some needed material that has yet to be relocated to the distutils docs as a reference for the legacy formats
1 parent 9e06227 commit f7614d5

15 files changed

Lines changed: 459 additions & 32 deletions

File tree

‎Doc/conf.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -120,11 +120,11 @@
120120
latex_documents = [
121121
('c-api/index', 'c-api.tex',
122122
'The Python/C API', _stdauthor, 'manual'),
123-
('distutils/index', 'distutils.tex',
123+
('distributing/index', 'distributing.tex',
124124
'Distributing Python Modules', _stdauthor, 'manual'),
125125
('extending/index', 'extending.tex',
126126
'Extending and Embedding Python', _stdauthor, 'manual'),
127-
('install/index', 'install.tex',
127+
('installing/index', 'installing.tex',
128128
'Installing Python Modules', _stdauthor, 'manual'),
129129
('library/index', 'library.tex',
130130
'The Python Library Reference', _stdauthor, 'manual'),

‎Doc/contents.rst‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@
1111
library/index.rst
1212
extending/index.rst
1313
c-api/index.rst
14-
distutils/index.rst
15-
install/index.rst
14+
distributing/index.rst
15+
installing/index.rst
1616
howto/index.rst
1717
faq/index.rst
1818
glossary.rst
@@ -21,3 +21,11 @@
2121
bugs.rst
2222
copyright.rst
2323
license.rst
24+
25+
.. include legacy packaging docs in build
26+
27+
.. toctree::
28+
:hidden:
29+
30+
distutils/index.rst
31+
install/index.rst

‎Doc/distributing/index.rst‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
.. _distributing-index:
2+
3+
###############################
4+
Distributing Python Modules
5+
###############################
6+
7+
:Email: [email protected]
8+
9+
10+
As a popular open source development project, Python has an active
11+
supporting community of contributors and users that also make their software
12+
available for other Python developers to use under open source license terms.
13+
14+
This allows Python users to share and collaborate effectively, benefiting
15+
from the solutions others have already created to common (and sometimes
16+
even rare!) problems, as well as potentially contributing their own
17+
solutions to the common pool.
18+
19+
This guide covers the distribution part of the process. For a guide to
20+
installing other Python projects, refer to the
21+
:ref:`installation guide <installing-index>`.
22+
23+
.. note::
24+
25+
For corporate and other institutional users, be aware that many
26+
organisations have their own policies around using and contributing to
27+
open source software. Please take such policies into account when making
28+
use of the distribution and installation tools provided with Python.
29+
30+
31+
Key terms
32+
=========
33+
34+
* the `Python Package Index <https://pypi.python.org/pypi>`__ is a public
35+
repository of open source licensed packages made available for use by
36+
other Python users
37+
* the `Python Packaging Authority
38+
<http://packaging.python.org/en/latest/future.html>`__ are the group of
39+
developers and documentation authors responsible for the maintenance and
40+
evolution of the standard packaging tools and the associated metadata and
41+
file format standards. They maintain a variety of tools, documentation
42+
and issue trackers on both `GitHub <https://github.com/pypa>` and
43+
`BitBucket <https://bitbucket.org/pypa/>`__.
44+
* ``distutils`` is the original build and distribution system first added to
45+
the Python standard library in 1998. While direct use of ``distutils`` is
46+
being phased out, it still laid the foundation for the current packaging
47+
and distribution infrastructure, and it not only remains part of the
48+
standard library, but its name lives on in other ways (such as the name
49+
of the mailing list used to coordinate Python packaging standards
50+
development).
51+
52+
53+
Open source licensing and collaboration
54+
=======================================
55+
56+
In most parts of the world, software is automatically covered by copyright.
57+
This means that other developers require explicit permission to copy, use,
58+
modify and redistribute the software.
59+
60+
Open source licensing is a way of explicitly granting such permission in a
61+
relatively consistent way, allowing developers to share and collaborate
62+
efficiently by making common solutions to various problems freely available.
63+
This leaves many developers free to spend more time focusing on the problems
64+
that are relatively unique to their specific situation.
65+
66+
The distribution tools provided with Python are designed to make it
67+
reasonably straightforward for developers to make their own contributions
68+
back to that common pool of software if they choose to do so.
69+
70+
The same distribution tools can also be used to distribute software within
71+
an organisation, regardless of whether that software is published as open
72+
source software or not.
73+
74+
75+
Installing the tools
76+
====================
77+
78+
The standard library does not include build tools that support modern
79+
Python packaging standards, as the core development team has found that it
80+
is important to have standard tools that work consistently, even on older
81+
versions of Python.
82+
83+
The currently recommended build and distribution tools can be installed
84+
using ``pip``::
85+
86+
pip install setuptools wheel twine
87+
88+
89+
Reading the guide
90+
=================
91+
92+
The Python Packaging User Guide covers the various key steps and elements
93+
involved in creating a project
94+
95+
* `Project structure`_
96+
* `Building and packaging the project`_
97+
* `Uploading the project to the Python Package Index`_
98+
99+
.. _Project structure: \
100+
http://packaging.python.org/en/latest/tutorial.html#creating-your-own-project
101+
.. _Building and packaging the project: \
102+
http://packaging.python.org/en/latest/tutorial.html#building-packaging-your-project
103+
.. _Uploading the project to the Python Package Index: \
104+
http://packaging.python.org/en/latest/tutorial.html#building-uploading-your-project-to-pypi
105+
106+
107+
How do I...?
108+
============
109+
110+
These are quick answers or links for some common tasks.
111+
112+
... choose a name for my project?
113+
---------------------------------
114+
115+
This isn't an easy topic, but here are a few tips:
116+
117+
* check the Python Package Index to see if the name is already in use
118+
* check popular hosting sites like GitHub, BitBucket, etc to see if there
119+
is already a project with that name
120+
* check what comes up in a web search for the name you're considering
121+
* avoid particularly common words, especially ones with multiple meanings,
122+
as they can make it difficult for users to find your software when
123+
searching for it
124+
125+
126+
... create and distribute binary extensions?
127+
--------------------------------------------
128+
129+
This is actually quite a complex topic, with a variety of alternatives
130+
available depending on exactly what you're aiming to achieve. See the
131+
Python Packaging User Guide for more information and recommendations.
132+
133+
.. seealso::
134+
135+
`Python Packaging User Guide: Binary Extensions
136+
<http://packaging.python.org/en/latest/extensions.html>`__
137+
138+
.. other topics:
139+
140+
Once the Development & Deployment part of PPUG is fleshed out, some of
141+
those sections should be linked from new questions here (most notably,
142+
we should have a question about avoiding depending on PyPI that links to
143+
http://packaging.python.org/en/latest/deployment.html#pypi-mirrors-and-caches)

‎Doc/distutils/index.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
.. _distutils-index:
22

3-
###############################
4-
Distributing Python Modules
5-
###############################
3+
##############################################
4+
Distributing Python Modules (Legacy version)
5+
##############################################
66

77
:Authors: Greg Ward, Anthony Baxter
88
:Email: [email protected]

‎Doc/extending/index.rst‎

Lines changed: 36 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -21,14 +21,31 @@ Python) that give the language its wide application range.
2121
For a detailed description of the whole Python/C API, see the separate
2222
:ref:`c-api-index`.
2323

24-
.. note::
2524

26-
This guide only covers the basic tools for creating extensions provided
27-
as part of this version of CPython. Third party tools may offer simpler
28-
alternatives. Refer to the `binary extensions section
29-
<https://python-packaging-user-guide.readthedocs.org/en/latest/extensions.html>`__
30-
in the Python Packaging User Guide for more information.
25+
Recommended third party tools
26+
=============================
3127

28+
This guide only covers the basic tools for creating extensions provided
29+
as part of this version of CPython. Third party tools like Cython,
30+
``cffi``, SWIG and Numba offer both simpler and more sophisticated
31+
approaches to creating C and C++ extensions for Python.
32+
33+
.. seealso::
34+
35+
`Python Packaging User Guide: Binary Extensions <https://packaging.python.org/en/latest/extensions.html>`_
36+
The Python Packaging User Guide not only covers several available
37+
tools that simplify the creation of binary extensions, but also
38+
discusses the various reasons why creating an extension module may be
39+
desirable in the first place.
40+
41+
42+
Creating extensions without third party tools
43+
=============================================
44+
45+
This section of the guide covers creating C and C++ extensions without
46+
assistance from third party tools. It is intended primarily for creators
47+
of those tools, rather than being a recommended way to create your own
48+
C extensions.
3249

3350
.. toctree::
3451
:maxdepth: 2
@@ -38,4 +55,17 @@ For a detailed description of the whole Python/C API, see the separate
3855
newtypes.rst
3956
building.rst
4057
windows.rst
58+
59+
Embedding the CPython runtime in a larger application
60+
=====================================================
61+
62+
Sometimes, rather than creating an extension that runs inside the Python
63+
interpreter as the main application, it is desirable to instead embed
64+
the CPython runtime inside a larger application. This section covers
65+
some of the details involved in doing that successfully.
66+
67+
.. toctree::
68+
:maxdepth: 2
69+
:numbered:
70+
4171
embedding.rst

‎Doc/install/index.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22

33
.. _install-index:
44

5-
*****************************
6-
Installing Python Modules
7-
*****************************
5+
********************************************
6+
Installing Python Modules (Legacy version)
7+
********************************************
88

99
:Author: Greg Ward
1010

0 commit comments

Comments
 (0)