Skip to content

Commit 17c8a95

Browse files
gvanrossumgvanrossum
committed
Merge remote-tracking branch 'origin/master' into slotscache
2 parents 4c2eb69 + 64fc105 commit 17c8a95

File tree

156 files changed

+3258
-921
lines changed

Some content is hidden

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

156 files changed

+3258
-921
lines changed

‎.azure-pipelines/docs-steps.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ steps:
1212
inputs:
1313
versionSpec: '>=3.6'
1414

15-
- script: python -m pip install sphinx==3.2.1 blurb python-docs-theme
15+
- script: python -m pip install sphinx==2.2.0 blurb python-docs-theme
1616
displayName: 'Install build dependencies'
1717

1818
- ${{ if ne(parameters.latex, 'true') }}:

‎.github/workflows/build.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ jobs:
6363
# Build Python with the libpython dynamic library
6464
./configure --with-pydebug --enable-shared
6565
make -j4 regen-all
66+
make regen-stdlib-module-names
6667
- name: Check for changes
6768
run: |
6869
changes=$(git status --porcelain)

‎.travis.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,7 @@ before_script:
172172
- eval "$(pyenv init -)"
173173
- pyenv global 3.8
174174
- PYTHON_FOR_REGEN=python3.8 make -j4 regen-all
175+
- make regen-stdlib-module-names
175176
- changes=`git status --porcelain`
176177
- |
177178
# Check for changes in regenerated files

‎Doc/c-api/init.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1192,7 +1192,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
11921192
11931193
.. versionadded:: 3.9
11941194
1195-
.. c:function:: void _PyInterpreterState_SetEvalFrameFunc(PyInterpreterState *interp, _PyFrameEvalFunction eval_frame);
1195+
.. c:function:: void _PyInterpreterState_SetEvalFrameFunc(PyInterpreterState *interp, _PyFrameEvalFunction eval_frame)
11961196
11971197
Set the frame evaluation function.
11981198

‎Doc/c-api/memory.rst‎

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,38 @@ for the I/O buffer escapes completely the Python memory manager.
9292
statistics of the :ref:`pymalloc memory allocator <pymalloc>` every time a
9393
new pymalloc object arena is created, and on shutdown.
9494

95+
Allocator Domains
96+
=================
97+
98+
All allocating functions belong to one of three different "domains" (see also
99+
:c:type`PyMemAllocatorDomain`). These domains represent different allocation
100+
strategies and are optimized for different purposes. The specific details on
101+
how every domain allocates memory or what internal functions each domain calls
102+
is considered an implementation detail, but for debugging purposes a simplified
103+
table can be found at :ref:`here <default-memory-allocators>`. There is no hard
104+
requirement to use the memory returned by the allocation functions belonging to
105+
a given domain for only the purposes hinted by that domain (although this is the
106+
recommended practice). For example, one could use the memory returned by
107+
:c:func:`PyMem_RawMalloc` for allocating Python objects or the memory returned
108+
by :c:func:`PyObject_Malloc` for allocating memory for buffers.
109+
110+
The three allocation domains are:
111+
112+
* Raw domain: intended for allocating memory for general-purpose memory
113+
buffers where the allocation *must* go to the system allocator or where the
114+
allocator can operate without the :term:`GIL`. The memory is requested directly
115+
to the system.
116+
117+
* "Mem" domain: intended for allocating memory for Python buffers and
118+
general-purpose memory buffers where the allocation must be performed with
119+
the :term:`GIL` held. The memory is taken from the Python private heap.
120+
121+
* Object domain: intended for allocating memory belonging to Python objects. The
122+
memory is taken from the Python private heap.
123+
124+
When freeing memory previously allocated by the allocating functions belonging to a
125+
given domain,the matching specific deallocating functions must be used. For example,
126+
:c:func:`PyMem_Free` must be used to free memory allocated using :c:func:`PyMem_Malloc`.
95127

96128
Raw Memory Interface
97129
====================
@@ -272,6 +304,12 @@ The following function sets, modeled after the ANSI C standard, but specifying
272304
behavior when requesting zero bytes, are available for allocating and releasing
273305
memory from the Python heap.
274306
307+
.. note::
308+
There is no guarantee that the memory returned by these allocators can be
309+
succesfully casted to a Python object when intercepting the allocating
310+
functions in this domain by the methods described in
311+
the :ref:`Customize Memory Allocators <customize-memory-allocators>` section.
312+
275313
The :ref:`default object allocator <default-memory-allocators>` uses the
276314
:ref:`pymalloc memory allocator <pymalloc>`.
277315
@@ -353,6 +391,7 @@ Legend:
353391
* ``pymalloc``: :ref:`pymalloc memory allocator <pymalloc>`
354392
* "+ debug": with debug hooks installed by :c:func:`PyMem_SetupDebugHooks`
355393
394+
.. _customize-memory-allocators:
356395
357396
Customize Memory Allocators
358397
===========================
@@ -601,4 +640,3 @@ heap, objects in Python are allocated and released with :c:func:`PyObject_New`,
601640
602641
These will be explained in the next chapter on defining and implementing new
603642
object types in C.
604-

‎Doc/conf.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -237,3 +237,5 @@
237237
# bpo-40204: Disable warnings on Sphinx 2 syntax of the C domain since the
238238
# documentation is built with -W (warnings treated as errors).
239239
c_warn_on_allowed_pre_v3 = False
240+
241+
strip_signature_backslash = True

‎Doc/howto/clinic.rst‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1206,6 +1206,68 @@ type for ``self``, it's best to create your own converter, subclassing
12061206
[clinic start generated code]*/
12071207

12081208

1209+
Using a "defining class" converter
1210+
----------------------------------
1211+
1212+
Argument Clinic facilitates gaining access to the defining class of a method.
1213+
This is useful for :ref:`heap type <heap-types>` methods that need to fetch
1214+
module level state. Use :c:func:`PyType_FromModuleAndSpec` to associate a new
1215+
heap type with a module. You can now use :c:func:`PyType_GetModuleState` on
1216+
the defining class to fetch the module state, for example from a module method.
1217+
1218+
Example from ``Modules/zlibmodule.c``. First, ``defining_class`` is added to
1219+
the clinic input::
1220+
1221+
/*[clinic input]
1222+
zlib.Compress.compress
1223+
1224+
cls: defining_class
1225+
data: Py_buffer
1226+
Binary data to be compressed.
1227+
/
1228+
1229+
1230+
After running the Argument Clinic tool, the following function signature is
1231+
generated::
1232+
1233+
/*[clinic start generated code]*/
1234+
static PyObject *
1235+
zlib_Compress_compress_impl(compobject *self, PyTypeObject *cls,
1236+
Py_buffer *data)
1237+
/*[clinic end generated code: output=6731b3f0ff357ca6 input=04d00f65ab01d260]*/
1238+
1239+
1240+
The following code can now use ``PyType_GetModuleState(cls)`` to fetch the
1241+
module state::
1242+
1243+
zlibstate *state = PyType_GetModuleState(cls);
1244+
1245+
1246+
Each method may only have one argument using this converter, and it must appear
1247+
after ``self``, or, if ``self`` is not used, as the first argument. The argument
1248+
will be of type ``PyTypeObject *``. The argument will not appear in the
1249+
``__text_signature__``.
1250+
1251+
The ``defining_class`` converter is not compatible with ``__init__`` and ``__new__``
1252+
methods, which cannot use the ``METH_METHOD`` convention.
1253+
1254+
It is not possible to use ``defining_class`` with slot methods. In order to
1255+
fetch the module state from such methods, use ``_PyType_GetModuleByDef`` to
1256+
look up the module and then :c:func:`PyModule_GetState` to fetch the module
1257+
state. Example from the ``setattro`` slot method in
1258+
``Modules/_threadmodule.c``::
1259+
1260+
static int
1261+
local_setattro(localobject *self, PyObject *name, PyObject *v)
1262+
{
1263+
PyObject *module = _PyType_GetModuleByDef(Py_TYPE(self), &thread_module);
1264+
thread_module_state *state = get_thread_state(module);
1265+
...
1266+
}
1267+
1268+
1269+
See also :pep:`573`.
1270+
12091271

12101272
Writing a custom converter
12111273
--------------------------

‎Doc/library/asyncio-stream.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -185,7 +185,7 @@ StreamReader
185185
can be read. Use the :attr:`IncompleteReadError.partial`
186186
attribute to get the partially read data.
187187

188-
.. coroutinemethod:: readuntil(separator=b'\n')
188+
.. coroutinemethod:: readuntil(separator=b'\\n')
189189

190190
Read data from the stream until *separator* is found.
191191

‎Doc/library/base64.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -199,7 +199,7 @@ The modern interface provides:
199199
.. versionadded:: 3.4
200200

201201

202-
.. function:: a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\v')
202+
.. function:: a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \\t\\n\\r\\v')
203203

204204
Decode the Ascii85 encoded :term:`bytes-like object` or ASCII string *b* and
205205
return the decoded :class:`bytes`.

‎Doc/library/curses.rst‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -220,11 +220,15 @@ The module :mod:`curses` defines the following functions:
220220
multiple devices, and *x*, *y*, *z* are the event's coordinates. (*z* is
221221
currently unused.) *bstate* is an integer value whose bits will be set to
222222
indicate the type of event, and will be the bitwise OR of one or more of the
223-
following constants, where *n* is the button number from 1 to 4:
223+
following constants, where *n* is the button number from 1 to 5:
224224
:const:`BUTTONn_PRESSED`, :const:`BUTTONn_RELEASED`, :const:`BUTTONn_CLICKED`,
225225
:const:`BUTTONn_DOUBLE_CLICKED`, :const:`BUTTONn_TRIPLE_CLICKED`,
226226
:const:`BUTTON_SHIFT`, :const:`BUTTON_CTRL`, :const:`BUTTON_ALT`.
227227

228+
.. versionchanged:: 3.10
229+
The ``BUTTON5_*`` constants are now exposed if they are provided by the
230+
underlying curses library.
231+
228232

229233
.. function:: getsyx()
230234

0 commit comments

Comments
 (0)