Skip to content

Commit 3732ed2

Browse files
larryhastingslarryhastings
committed
Merge in all documentation changes since branching 3.4.0rc1.
1 parent b6b6a6d commit 3732ed2

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

93 files changed

+2029
-567
lines changed

‎Doc/c-api/arg.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ in any early abort case).
4545
Unless otherwise stated, buffers are not NUL-terminated.
4646

4747
.. note::
48+
4849
For all ``#`` variants of formats (``s#``, ``y#``, etc.), the type of
4950
the length argument (int or :c:type:`Py_ssize_t`) is controlled by
5051
defining the macro :c:macro:`PY_SSIZE_T_CLEAN` before including

‎Doc/c-api/exceptions.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -525,11 +525,11 @@ Exception Objects
525525
reference, as accessible from Python through :attr:`__cause__`.
526526
527527
528-
.. c:function:: void PyException_SetCause(PyObject *ex, PyObject *ctx)
528+
.. c:function:: void PyException_SetCause(PyObject *ex, PyObject *cause)
529529
530-
Set the cause associated with the exception to *ctx*. Use *NULL* to clear
531-
it. There is no type check to make sure that *ctx* is either an exception
532-
instance or :const:`None`. This steals a reference to *ctx*.
530+
Set the cause associated with the exception to *cause*. Use *NULL* to clear
531+
it. There is no type check to make sure that *cause* is either an exception
532+
instance or :const:`None`. This steals a reference to *cause*.
533533
534534
:attr:`__suppress_context__` is implicitly set to ``True`` by this function.
535535

‎Doc/c-api/init.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -582,6 +582,7 @@ code, or when embedding the Python interpreter:
582582
.. index:: module: _thread
583583
584584
.. note::
585+
585586
When only the main thread exists, no GIL operations are needed. This is a
586587
common situation (most Python programs do not use threads), and the lock
587588
operations slow the interpreter down a bit. Therefore, the lock is not

‎Doc/c-api/module.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ There are only a few functions special to module objects.
120120
121121
Return a pointer to the :c:type:`PyModuleDef` struct from which the module was
122122
created, or *NULL* if the module wasn't created with
123-
:c:func:`PyModule_Create`.i
123+
:c:func:`PyModule_Create`.
124124
125125
.. c:function:: PyObject* PyState_FindModule(PyModuleDef *def)
126126

‎Doc/c-api/object.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -357,9 +357,9 @@ attribute is considered sufficient for this determination.
357357
358358
.. c:function:: Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t default)
359359
360-
Return an estimated length for the object *o*. First trying to return its
361-
actual length, then an estimate using ``__length_hint__``, and finally
362-
returning the default value. On error ``-1`` is returned. This is the
360+
Return an estimated length for the object *o*. First try to return its
361+
actual length, then an estimate using :meth:`~object.__length_hint__`, and
362+
finally return the default value. On error return ``-1``. This is the
363363
equivalent to the Python expression ``operator.length_hint(o, default)``.
364364
365365
.. versionadded:: 3.4

‎Doc/c-api/tuple.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,14 @@ type.
129129
Initializes a struct sequence type *type* from *desc* in place.
130130
131131
132+
.. c:function:: int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)
133+
134+
The same as ``PyStructSequence_InitType``, but returns ``0`` on success and ``-1`` on
135+
failure.
136+
137+
.. versionadded:: 3.4
138+
139+
132140
.. c:type:: PyStructSequence_Desc
133141
134142
Contains the meta information of a struct sequence type to create.

‎Doc/c-api/typeobj.rst‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -205,9 +205,8 @@ type objects) *must* have the :attr:`ob_size` field.
205205
bit currently defined is :const:`Py_PRINT_RAW`. When the :const:`Py_PRINT_RAW`
206206
flag bit is set, the instance should be printed the same way as :c:member:`~PyTypeObject.tp_str`
207207
would format it; when the :const:`Py_PRINT_RAW` flag bit is clear, the instance
208-
should be printed the same was as :c:member:`~PyTypeObject.tp_repr` would format it. It should
209-
return ``-1`` and set an exception condition when an error occurred during the
210-
comparison.
208+
should be printed the same way as :c:member:`~PyTypeObject.tp_repr` would format it. It should
209+
return ``-1`` and set an exception condition when an error occurs.
211210

212211
It is possible that the :c:member:`~PyTypeObject.tp_print` field will be deprecated. In any case,
213212
it is recommended not to define :c:member:`~PyTypeObject.tp_print`, but instead to rely on

‎Doc/conf.py‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,8 @@
6161
# By default, highlight as Python 3.
6262
highlight_language = 'python3'
6363

64+
needs_sphinx = '1.1'
65+
6466

6567
# Options for HTML output
6668
# -----------------------
@@ -118,11 +120,11 @@
118120
latex_documents = [
119121
('c-api/index', 'c-api.tex',
120122
'The Python/C API', _stdauthor, 'manual'),
121-
('distutils/index', 'distutils.tex',
123+
('distributing/index', 'distributing.tex',
122124
'Distributing Python Modules', _stdauthor, 'manual'),
123125
('extending/index', 'extending.tex',
124126
'Extending and Embedding Python', _stdauthor, 'manual'),
125-
('install/index', 'install.tex',
127+
('installing/index', 'installing.tex',
126128
'Installing Python Modules', _stdauthor, 'manual'),
127129
('library/index', 'library.tex',
128130
'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: distutils-sig@python.org
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#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)

0 commit comments

Comments
 (0)