Skip to content

Commit 1faf1f0

Browse files
toonarmycaptaintoonarmycaptain
authored
Merge pull request #1 from python/master
Catchup
2 parents e3b2b4b + 3231893 commit 1faf1f0

1,167 files changed

Lines changed: 20138 additions & 8568 deletions

File tree

Some content is hidden

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

‎.github/CODEOWNERS‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ Python/bootstrap_hash.c @python/crypto-team
3535

3636
# Windows
3737
/PC/ @python/windows-team
38-
/PCBuild/ @python/windows-team
38+
/PCbuild/ @python/windows-team
3939

4040
# Windows installer packages
4141
/Tools/msi/ @python/windows-team
@@ -49,3 +49,5 @@ Python/bootstrap_hash.c @python/crypto-team
4949
**/*heapq* @rhettinger
5050
**/*functools* @ncoghlan @rhettinger
5151
**/*decimal* @rhettinger @skrah
52+
53+
**/*idlelib* @terryjreedy

‎.github/CODE_OF_CONDUCT.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
Code of Conduct
2+
===============
3+
4+
Please note that all interactions on
5+
`Python Software Foundation <https://www.python.org/psf-landing/>`__-supported
6+
infrastructure is `covered
7+
<https://www.python.org/psf/records/board/minutes/2014-01-06/#management-of-the-psfs-web-properties>`__
8+
by the `PSF Code of Conduct <https://www.python.org/psf/codeofconduct/>`__,
9+
which includes all infrastructure used in the development of Python itself
10+
(e.g. mailing lists, issue trackers, GitHub, etc.).
11+
12+
In general this means everyone is expected to be open, considerate, and
13+
respectful of others no matter what their position is within the project.
14+

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
!!! If this is a backport PR (PR made against branches other than `master`),
22
please ensure that the PR title is in the following format:
3-
4-
[X.Y] <title from the original PR> GH-NNNN
5-
6-
Where: [X.Y] is the branch name, for example [3.6]
3+
```
4+
[X.Y] <title from the original PR> (GH-NNNN)
5+
```
6+
Where: [X.Y] is the branch name, e.g. [3.6].
77

88
GH-NNNN refers to the PR number from `master`.
99

‎.github/appveyor.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ only_commits:
2828
- Modules/
2929
- Objects/
3030
- PC/
31-
- PCBuild/
31+
- PCbuild/
3232
- Parser/
3333
- Programs/
3434
- Python/

‎.travis.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ matrix:
5656
./venv/bin/python -m test.pythoninfo
5757
script:
5858
# Skip tests that re-run the entire test suite.
59-
- ./venv/bin/python -m coverage run --pylib -m test -uall,-cpu -x test_multiprocessing_fork -x test_multiprocessing_forkserver -x test_multiprocessing_spawn
59+
- ./venv/bin/python -m coverage run --pylib -m test --fail-env-changed -uall,-cpu -x test_multiprocessing_fork -x test_multiprocessing_forkserver -x test_multiprocessing_spawn -x test_concurrent_futures
6060
after_script: # Probably should be after_success once test suite updated to run under coverage.py.
6161
# Make the `coverage` command available to Codecov w/ a version of Python that can parse all source files.
6262
- source ./venv/bin/activate
@@ -91,6 +91,8 @@ script:
9191
- if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then ./python Tools/scripts/patchcheck.py --travis $TRAVIS_PULL_REQUEST; fi
9292
# `-r -w` implicitly provided through `make buildbottest`.
9393
- make buildbottest TESTOPTS="-j4 -uall,-cpu"
94+
# Check that all symbols exported by libpython start with "Py" or "_Py"
95+
- make smelly
9496

9597
notifications:
9698
email: false

‎Doc/c-api/buffer.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -473,7 +473,7 @@ Buffer-related functions
473473
(*order* is ``'A'``). Return ``0`` otherwise.
474474
475475
476-
.. c:function:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char order)
476+
.. c:function:: void PyBuffer_FillContiguousStrides(int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char order)
477477
478478
Fill the *strides* array with byte-strides of a :term:`contiguous` (C-style if
479479
*order* is ``'C'`` or Fortran-style if *order* is ``'F'``) array of the

‎Doc/c-api/init.rst‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1192,3 +1192,160 @@ These functions are only intended to be used by advanced debugging tools.
11921192
Return the next thread state object after *tstate* from the list of all such
11931193
objects belonging to the same :c:type:`PyInterpreterState` object.
11941194
1195+
1196+
.. _thread-local-storage:
1197+
1198+
Thread Local Storage Support
1199+
============================
1200+
1201+
.. sectionauthor:: Masayuki Yamamoto <ma3yuki.8mamo10@gmail.com>
1202+
1203+
The Python interpreter provides low-level support for thread-local storage
1204+
(TLS) which wraps the underlying native TLS implementation to support the
1205+
Python-level thread local storage API (:class:`threading.local`). The
1206+
CPython C level APIs are similar to those offered by pthreads and Windows:
1207+
use a thread key and functions to associate a :c:type:`void\*` value per
1208+
thread.
1209+
1210+
The GIL does *not* need to be held when calling these functions; they supply
1211+
their own locking.
1212+
1213+
Note that :file:`Python.h` does not include the declaration of the TLS APIs,
1214+
you need to include :file:`pythread.h` to use thread-local storage.
1215+
1216+
.. note::
1217+
None of these API functions handle memory management on behalf of the
1218+
:c:type:`void\*` values. You need to allocate and deallocate them yourself.
1219+
If the :c:type:`void\*` values happen to be :c:type:`PyObject\*`, these
1220+
functions don't do refcount operations on them either.
1221+
1222+
.. _thread-specific-storage-api:
1223+
1224+
Thread Specific Storage (TSS) API
1225+
---------------------------------
1226+
1227+
TSS API is introduced to supersede the use of the existing TLS API within the
1228+
CPython interpreter. This API uses a new type :c:type:`Py_tss_t` instead of
1229+
:c:type:`int` to represent thread keys.
1230+
1231+
.. versionadded:: 3.7
1232+
1233+
.. seealso:: "A New C-API for Thread-Local Storage in CPython" (:pep:`539`)
1234+
1235+
1236+
.. c:type:: Py_tss_t
1237+
1238+
This data structure represents the state of a thread key, the definition of
1239+
which may depend on the underlying TLS implementation, and it has an
1240+
internal field representing the key's initialization state. There are no
1241+
public members in this structure.
1242+
1243+
When :ref:`Py_LIMITED_API <stable>` is not defined, static allocation of
1244+
this type by :c:macro:`Py_tss_NEEDS_INIT` is allowed.
1245+
1246+
1247+
.. c:macro:: Py_tss_NEEDS_INIT
1248+
1249+
This macro expands to the initializer for :c:type:`Py_tss_t` variables.
1250+
Note that this macro won't be defined with :ref:`Py_LIMITED_API <stable>`.
1251+
1252+
1253+
Dynamic Allocation
1254+
~~~~~~~~~~~~~~~~~~
1255+
1256+
Dynamic allocation of the :c:type:`Py_tss_t`, required in extension modules
1257+
built with :ref:`Py_LIMITED_API <stable>`, where static allocation of this type
1258+
is not possible due to its implementation being opaque at build time.
1259+
1260+
1261+
.. c:function:: Py_tss_t* PyThread_tss_alloc()
1262+
1263+
Return a value which is the same state as a value initialized with
1264+
:c:macro:`Py_tss_NEEDS_INIT`, or *NULL* in the case of dynamic allocation
1265+
failure.
1266+
1267+
1268+
.. c:function:: void PyThread_tss_free(Py_tss_t *key)
1269+
1270+
Free the given *key* allocated by :c:func:`PyThread_tss_alloc`, after
1271+
first calling :c:func:`PyThread_tss_delete` to ensure any associated
1272+
thread locals have been unassigned. This is a no-op if the *key*
1273+
argument is `NULL`.
1274+
1275+
.. note::
1276+
A freed key becomes a dangling pointer, you should reset the key to
1277+
`NULL`.
1278+
1279+
1280+
Methods
1281+
~~~~~~~
1282+
1283+
The parameter *key* of these functions must not be *NULL*. Moreover, the
1284+
behaviors of :c:func:`PyThread_tss_set` and :c:func:`PyThread_tss_get` are
1285+
undefined if the given :c:type:`Py_tss_t` has not been initialized by
1286+
:c:func:`PyThread_tss_create`.
1287+
1288+
1289+
.. c:function:: int PyThread_tss_is_created(Py_tss_t *key)
1290+
1291+
Return a non-zero value if the given :c:type:`Py_tss_t` has been initialized
1292+
by :c:func:`PyThread_tss_create`.
1293+
1294+
1295+
.. c:function:: int PyThread_tss_create(Py_tss_t *key)
1296+
1297+
Return a zero value on successful initialization of a TSS key. The behavior
1298+
is undefined if the value pointed to by the *key* argument is not
1299+
initialized by :c:macro:`Py_tss_NEEDS_INIT`. This function can be called
1300+
repeatedly on the same key -- calling it on an already initialized key is a
1301+
no-op and immediately returns success.
1302+
1303+
1304+
.. c:function:: void PyThread_tss_delete(Py_tss_t *key)
1305+
1306+
Destroy a TSS key to forget the values associated with the key across all
1307+
threads, and change the key's initialization state to uninitialized. A
1308+
destroyed key is able to be initialized again by
1309+
:c:func:`PyThread_tss_create`. This function can be called repeatedly on
1310+
the same key -- calling it on an already destroyed key is a no-op.
1311+
1312+
1313+
.. c:function:: int PyThread_tss_set(Py_tss_t *key, void *value)
1314+
1315+
Return a zero value to indicate successfully associating a :c:type:`void\*`
1316+
value with a TSS key in the current thread. Each thread has a distinct
1317+
mapping of the key to a :c:type:`void\*` value.
1318+
1319+
1320+
.. c:function:: void* PyThread_tss_get(Py_tss_t *key)
1321+
1322+
Return the :c:type:`void\*` value associated with a TSS key in the current
1323+
thread. This returns *NULL* if no value is associated with the key in the
1324+
current thread.
1325+
1326+
1327+
.. _thread-local-storage-api:
1328+
1329+
Thread Local Storage (TLS) API
1330+
------------------------------
1331+
1332+
.. deprecated:: 3.7
1333+
This API is superseded by
1334+
:ref:`Thread Specific Storage (TSS) API <thread-specific-storage-api>`.
1335+
1336+
.. note::
1337+
This version of the API does not support platforms where the native TLS key
1338+
is defined in a way that cannot be safely cast to ``int``. On such platforms,
1339+
:c:func:`PyThread_create_key` will return immediately with a failure status,
1340+
and the other TLS functions will all be no-ops on such platforms.
1341+
1342+
Due to the compatibility problem noted above, this version of the API should not
1343+
be used in new code.
1344+
1345+
.. c:function:: int PyThread_create_key()
1346+
.. c:function:: void PyThread_delete_key(int key)
1347+
.. c:function:: int PyThread_set_key_value(int key, void *value)
1348+
.. c:function:: void* PyThread_get_key_value(int key)
1349+
.. c:function:: void PyThread_delete_key_value(int key)
1350+
.. c:function:: void PyThread_ReInitTLS()
1351+

‎Doc/c-api/intro.rst‎

Lines changed: 62 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,11 @@ common use. The second reason is to use Python as a component in a larger
1717
application; this technique is generally referred to as :dfn:`embedding` Python
1818
in an application.
1919

20-
Writing an extension module is a relatively well-understood process, where a
21-
"cookbook" approach works well. There are several tools that automate the
22-
process to some extent. While people have embedded Python in other
23-
applications since its early existence, the process of embedding Python is less
24-
straightforward than writing an extension.
20+
Writing an extension module is a relatively well-understood process, where a
21+
"cookbook" approach works well. There are several tools that automate the
22+
process to some extent. While people have embedded Python in other
23+
applications since its early existence, the process of embedding Python is
24+
less straightforward than writing an extension.
2525

2626
Many API functions are useful independent of whether you're embedding or
2727
extending Python; moreover, most applications that embed Python will need to
@@ -30,6 +30,16 @@ familiar with writing an extension before attempting to embed Python in a real
3030
application.
3131

3232

33+
Coding standards
34+
================
35+
36+
If you're writing C code for inclusion in CPython, you **must** follow the
37+
guidelines and standards defined in :PEP:`7`. These guidelines apply
38+
regardless of the version of Python you are contributing to. Following these
39+
conventions is not necessary for your own third party extension modules,
40+
unless you eventually expect to contribute them to Python.
41+
42+
3343
.. _api-includes:
3444

3545
Include Files
@@ -81,6 +91,53 @@ header files do properly declare the entry points to be ``extern "C"``, so there
8191
is no need to do anything special to use the API from C++.
8292

8393

94+
Useful macros
95+
=============
96+
97+
Several useful macros are defined in the Python header files. Many are
98+
defined closer to where they are useful (e.g. :c:macro:`Py_RETURN_NONE`).
99+
Others of a more general utility are defined here. This is not necessarily a
100+
complete listing.
101+
102+
.. c:macro:: Py_UNREACHABLE()
103+
104+
Use this when you have a code path that you do not expect to be reached.
105+
For example, in the ``default:`` clause in a ``switch`` statement for which
106+
all possible values are covered in ``case`` statements. Use this in places
107+
where you might be tempted to put an ``assert(0)`` or ``abort()`` call.
108+
109+
.. c:macro:: Py_ABS(x)
110+
111+
Return the absolute value of ``x``.
112+
113+
.. c:macro:: Py_MIN(x, y)
114+
115+
Return the minimum value between ``x`` and ``y``.
116+
117+
.. c:macro:: Py_MAX(x, y)
118+
119+
Return the maximum value between ``x`` and ``y``.
120+
121+
.. c:macro:: Py_STRINGIFY(x)
122+
123+
Convert ``x`` to a C string. E.g. ``Py_STRINGIFY(123)`` returns
124+
``"123"``.
125+
126+
.. c:macro:: Py_MEMBER_SIZE(type, member)
127+
128+
Return the size of a structure (``type``) ``member`` in bytes.
129+
130+
.. c:macro:: Py_CHARMASK(c)
131+
132+
Argument must be a character or an integer in the range [-128, 127] or [0,
133+
255]. This macro returns ``c`` cast to an ``unsigned char``.
134+
135+
.. c:macro:: Py_GETENV(s)
136+
137+
Like ``getenv(s)``, but returns *NULL* if :option:`-E` was passed on the
138+
command line (i.e. if ``Py_IgnoreEnvironmentFlag`` is set).
139+
140+
84141
.. _api-objects:
85142

86143
Objects, Types and Reference Counts

‎Doc/c-api/mapping.rst‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -50,20 +50,29 @@ Mapping Protocol
5050
5151
.. c:function:: PyObject* PyMapping_Keys(PyObject *o)
5252
53-
On success, return a list or tuple of the keys in object *o*. On failure,
54-
return *NULL*.
53+
On success, return a list of the keys in object *o*. On failure, return
54+
*NULL*.
55+
56+
.. versionchanged:: 3.7
57+
Previously, the function returned a list or a tuple.
5558
5659
5760
.. c:function:: PyObject* PyMapping_Values(PyObject *o)
5861
59-
On success, return a list or tuple of the values in object *o*. On failure,
60-
return *NULL*.
62+
On success, return a list of the values in object *o*. On failure, return
63+
*NULL*.
64+
65+
.. versionchanged:: 3.7
66+
Previously, the function returned a list or a tuple.
6167
6268
6369
.. c:function:: PyObject* PyMapping_Items(PyObject *o)
6470
65-
On success, return a list or tuple of the items in object *o*, where each item
66-
is a tuple containing a key-value pair. On failure, return *NULL*.
71+
On success, return a list of the items in object *o*, where each item is a
72+
tuple containing a key-value pair. On failure, return *NULL*.
73+
74+
.. versionchanged:: 3.7
75+
Previously, the function returned a list or a tuple.
6776
6877
6978
.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key)

‎Doc/c-api/slice.rst‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,22 @@ Slice Objects
5353
5454
Returns ``0`` on success and ``-1`` on error with exception set.
5555
56+
.. note::
57+
This function is considered not safe for resizable sequences.
58+
Its invocation should be replaced by a combination of
59+
:c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices` where ::
60+
61+
if (PySlice_GetIndicesEx(slice, length, &start, &stop, &step, &slicelength) < 0) {
62+
// return error
63+
}
64+
65+
is replaced by ::
66+
67+
if (PySlice_Unpack(slice, &start, &stop, &step) < 0) {
68+
// return error
69+
}
70+
slicelength = PySlice_AdjustIndices(length, &start, &stop, step);
71+
5672
.. versionchanged:: 3.2
5773
The parameter type for the *slice* parameter was ``PySliceObject*``
5874
before.
@@ -61,7 +77,7 @@ Slice Objects
6177
If ``Py_LIMITED_API`` is not set or set to the value between ``0x03050400``
6278
and ``0x03060000`` (not including) or ``0x03060100`` or higher
6379
:c:func:`!PySlice_GetIndicesEx` is implemented as a macro using
64-
:c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices`.
80+
:c:func:`!PySlice_Unpack` and :c:func:`!PySlice_AdjustIndices`.
6581
Arguments *start*, *stop* and *step* are evaluated more than once.
6682
6783
.. deprecated:: 3.6.1

0 commit comments

Comments
 (0)