Skip to content

Commit 98f80c8

Browse files
encukouencukou
committed
Merge in the main branch
2 parents 44ad014 + 2468aaf commit 98f80c8

13 files changed

Lines changed: 209 additions & 125 deletions

‎Doc/c-api/code.rst‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -211,6 +211,71 @@ bound into a function.
211211
.. versionadded:: 3.12
212212
213213
214+
.. _c_codeobject_flags:
215+
216+
Code Object Flags
217+
-----------------
218+
219+
Code objects contain a bit-field of flags, which can be retrieved as the
220+
:attr:`~codeobject.co_flags` Python attribute (for example using
221+
:c:func:`PyObject_GetAttrString`), and set using a *flags* argument to
222+
:c:func:`PyUnstable_Code_New` and similar functions.
223+
224+
Flags whose names start with ``CO_FUTURE_`` correspond to features normally
225+
selectable by :ref:`future statements <future>`. These flags can be used in
226+
:c:member:`PyCompilerFlags.cf_flags`.
227+
Note that many ``CO_FUTURE_`` flags are mandatory in current versions of
228+
Python, and setting them has no effect.
229+
230+
The following flags are available.
231+
For their meaning, see the linked documentation of their Python equivalents.
232+
233+
234+
.. list-table::
235+
:widths: auto
236+
:header-rows: 1
237+
238+
* * Flag
239+
* Meaning
240+
* * .. c:macro:: CO_OPTIMIZED
241+
* :py:data:`inspect.CO_OPTIMIZED`
242+
* * .. c:macro:: CO_NEWLOCALS
243+
* :py:data:`inspect.CO_NEWLOCALS`
244+
* * .. c:macro:: CO_VARARGS
245+
* :py:data:`inspect.CO_VARARGS`
246+
* * .. c:macro:: CO_VARKEYWORDS
247+
* :py:data:`inspect.CO_VARKEYWORDS`
248+
* * .. c:macro:: CO_NESTED
249+
* :py:data:`inspect.CO_NESTED`
250+
* * .. c:macro:: CO_GENERATOR
251+
* :py:data:`inspect.CO_GENERATOR`
252+
* * .. c:macro:: CO_COROUTINE
253+
* :py:data:`inspect.CO_COROUTINE`
254+
* * .. c:macro:: CO_ITERABLE_COROUTINE
255+
* :py:data:`inspect.CO_ITERABLE_COROUTINE`
256+
* * .. c:macro:: CO_ASYNC_GENERATOR
257+
* :py:data:`inspect.CO_ASYNC_GENERATOR`
258+
* * .. c:macro:: CO_HAS_DOCSTRING
259+
* :py:data:`inspect.CO_HAS_DOCSTRING`
260+
* * .. c:macro:: CO_METHOD
261+
* :py:data:`inspect.CO_METHOD`
262+
263+
* * .. c:macro:: CO_FUTURE_DIVISION
264+
* no effect (:py:data:`__future__.division`)
265+
* * .. c:macro:: CO_FUTURE_ABSOLUTE_IMPORT
266+
* no effect (:py:data:`__future__.absolute_import`)
267+
* * .. c:macro:: CO_FUTURE_WITH_STATEMENT
268+
* no effect (:py:data:`__future__.with_statement`)
269+
* * .. c:macro:: CO_FUTURE_PRINT_FUNCTION
270+
* no effect (:py:data:`__future__.print_function`)
271+
* * .. c:macro:: CO_FUTURE_UNICODE_LITERALS
272+
* no effect (:py:data:`__future__.unicode_literals`)
273+
* * .. c:macro:: CO_FUTURE_GENERATOR_STOP
274+
* no effect (:py:data:`__future__.generator_stop`)
275+
* * .. c:macro:: CO_FUTURE_ANNOTATIONS
276+
* :py:data:`__future__.annotations`
277+
278+
214279
Extra information
215280
-----------------
216281

‎Doc/c-api/veryhigh.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -361,7 +361,7 @@ the same library that the Python runtime is using.
361361
:py:mod:`!ast` Python module, which exports these constants under
362362
the same names.
363363
364-
.. c:var:: int CO_FUTURE_DIVISION
365-
366-
This bit can be set in *flags* to cause division operator ``/`` to be
367-
interpreted as "true division" according to :pep:`238`.
364+
The "``PyCF``" flags above can be combined with "``CO_FUTURE``" flags such
365+
as :c:macro:`CO_FUTURE_ANNOTATIONS` to enable features normally
366+
selectable using :ref:`future statements <future>`.
367+
See :ref:`c_codeobject_flags` for a complete list.

‎Doc/howto/logging-cookbook.rst‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4078,6 +4078,68 @@ lines. With this approach, you get better output:
40784078
WARNING:demo: 1/0
40794079
WARNING:demo:ZeroDivisionError: division by zero
40804080
4081+
How to uniformly handle newlines in logging output
4082+
--------------------------------------------------
4083+
4084+
Usually, messages that are logged (say to console or file) consist of a single
4085+
line of text. However, sometimes there is a need to handle messages with
4086+
multiple lines - whether because a logging format string contains newlines, or
4087+
logged data contains newlines. If you want to handle such messages uniformly, so
4088+
that each line in the logged message appears uniformly formatted as if it was
4089+
logged separately, you can do this using a handler mixin, as in the following
4090+
snippet:
4091+
4092+
.. code-block:: python
4093+
4094+
# Assume this is in a module mymixins.py
4095+
import copy
4096+
4097+
class MultilineMixin:
4098+
def emit(self, record):
4099+
s = record.getMessage()
4100+
if '\n' not in s:
4101+
super().emit(record)
4102+
else:
4103+
lines = s.splitlines()
4104+
rec = copy.copy(record)
4105+
rec.args = None
4106+
for line in lines:
4107+
rec.msg = line
4108+
super().emit(rec)
4109+
4110+
You can use the mixin as in the following script:
4111+
4112+
.. code-block:: python
4113+
4114+
import logging
4115+
4116+
from mymixins import MultilineMixin
4117+
4118+
logger = logging.getLogger(__name__)
4119+
4120+
class StreamHandler(MultilineMixin, logging.StreamHandler):
4121+
pass
4122+
4123+
if __name__ == '__main__':
4124+
logging.basicConfig(level=logging.DEBUG, format='%(asctime)s %(levelname)-9s %(message)s',
4125+
handlers = [StreamHandler()])
4126+
logger.debug('Single line')
4127+
logger.debug('Multiple lines:\nfool me once ...')
4128+
logger.debug('Another single line')
4129+
logger.debug('Multiple lines:\n%s', 'fool me ...\ncan\'t get fooled again')
4130+
4131+
The script, when run, prints something like:
4132+
4133+
.. code-block:: text
4134+
4135+
2025-07-02 13:54:47,234 DEBUG Single line
4136+
2025-07-02 13:54:47,234 DEBUG Multiple lines:
4137+
2025-07-02 13:54:47,234 DEBUG fool me once ...
4138+
2025-07-02 13:54:47,234 DEBUG Another single line
4139+
2025-07-02 13:54:47,234 DEBUG Multiple lines:
4140+
2025-07-02 13:54:47,234 DEBUG fool me ...
4141+
2025-07-02 13:54:47,234 DEBUG can't get fooled again
4142+
40814143
40824144
.. patterns-to-avoid:
40834145

‎Doc/library/__future__.rst‎

Lines changed: 46 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -37,38 +37,52 @@ No feature description will ever be deleted from :mod:`__future__`. Since its
3737
introduction in Python 2.1 the following features have found their way into the
3838
language using this mechanism:
3939

40-
+------------------+-------------+--------------+---------------------------------------------+
41-
| feature | optional in | mandatory in | effect |
42-
+==================+=============+==============+=============================================+
43-
| nested_scopes | 2.1.0b1 | 2.2 | :pep:`227`: |
44-
| | | | *Statically Nested Scopes* |
45-
+------------------+-------------+--------------+---------------------------------------------+
46-
| generators | 2.2.0a1 | 2.3 | :pep:`255`: |
47-
| | | | *Simple Generators* |
48-
+------------------+-------------+--------------+---------------------------------------------+
49-
| division | 2.2.0a2 | 3.0 | :pep:`238`: |
50-
| | | | *Changing the Division Operator* |
51-
+------------------+-------------+--------------+---------------------------------------------+
52-
| absolute_import | 2.5.0a1 | 3.0 | :pep:`328`: |
53-
| | | | *Imports: Multi-Line and Absolute/Relative* |
54-
+------------------+-------------+--------------+---------------------------------------------+
55-
| with_statement | 2.5.0a1 | 2.6 | :pep:`343`: |
56-
| | | | *The "with" Statement* |
57-
+------------------+-------------+--------------+---------------------------------------------+
58-
| print_function | 2.6.0a2 | 3.0 | :pep:`3105`: |
59-
| | | | *Make print a function* |
60-
+------------------+-------------+--------------+---------------------------------------------+
61-
| unicode_literals | 2.6.0a2 | 3.0 | :pep:`3112`: |
62-
| | | | *Bytes literals in Python 3000* |
63-
+------------------+-------------+--------------+---------------------------------------------+
64-
| generator_stop | 3.5.0b1 | 3.7 | :pep:`479`: |
65-
| | | | *StopIteration handling inside generators* |
66-
+------------------+-------------+--------------+---------------------------------------------+
67-
| annotations | 3.7.0b1 | Never [1]_ | :pep:`563`: |
68-
| | | | *Postponed evaluation of annotations*, |
69-
| | | | :pep:`649`: *Deferred evaluation of |
70-
| | | | annotations using descriptors* |
71-
+------------------+-------------+--------------+---------------------------------------------+
40+
41+
.. list-table::
42+
:widths: auto
43+
:header-rows: 1
44+
45+
* * feature
46+
* optional in
47+
* mandatory in
48+
* effect
49+
* * .. data:: nested_scopes
50+
* 2.1.0b1
51+
* 2.2
52+
* :pep:`227`: *Statically Nested Scopes*
53+
* * .. data:: generators
54+
* 2.2.0a1
55+
* 2.3
56+
* :pep:`255`: *Simple Generators*
57+
* * .. data:: division
58+
* 2.2.0a2
59+
* 3.0
60+
* :pep:`238`: *Changing the Division Operator*
61+
* * .. data:: absolute_import
62+
* 2.5.0a1
63+
* 3.0
64+
* :pep:`328`: *Imports: Multi-Line and Absolute/Relative*
65+
* * .. data:: with_statement
66+
* 2.5.0a1
67+
* 2.6
68+
* :pep:`343`: *The “with” Statement*
69+
* * .. data:: print_function
70+
* 2.6.0a2
71+
* 3.0
72+
* :pep:`3105`: *Make print a function*
73+
* * .. data:: unicode_literals
74+
* 2.6.0a2
75+
* 3.0
76+
* :pep:`3112`: *Bytes literals in Python 3000*
77+
* * .. data:: generator_stop
78+
* 3.5.0b1
79+
* 3.7
80+
* :pep:`479`: *StopIteration handling inside generators*
81+
* * .. data:: annotations
82+
* 3.7.0b1
83+
* Never [1]_
84+
* :pep:`563`: *Postponed evaluation of annotations*,
85+
:pep:`649`: *Deferred evaluation of annotations using descriptors*
7286

7387
.. XXX Adding a new entry? Remember to update simple_stmts.rst, too.
7488

‎Doc/library/pyexpat.rst‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,10 @@
1616
references to these attributes should be marked using the :member: role.
1717
1818
19-
.. warning::
19+
.. note::
2020

21-
The :mod:`pyexpat` module is not secure against maliciously
22-
constructed data. If you need to parse untrusted or unauthenticated data see
23-
:ref:`xml-vulnerabilities`.
21+
If you need to parse untrusted or unauthenticated data, see
22+
:ref:`xml-security`.
2423

2524

2625
.. index:: single: Expat

‎Doc/library/security_warnings.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ The following modules have specific security considerations:
2828
<subprocess-security>`
2929
* :mod:`tempfile`: :ref:`mktemp is deprecated due to vulnerability to race
3030
conditions <tempfile-mktemp-deprecated>`
31-
* :mod:`xml`: :ref:`XML vulnerabilities <xml-vulnerabilities>`
31+
* :mod:`xml`: :ref:`XML security <xml-security>`
3232
* :mod:`zipfile`: :ref:`maliciously prepared .zip files can cause disk volume
3333
exhaustion <zipfile-resources-limitations>`
3434

‎Doc/library/xml.dom.minidom.rst‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,10 @@ not already proficient with the DOM should consider using the
1919
:mod:`xml.etree.ElementTree` module for their XML processing instead.
2020

2121

22-
.. warning::
22+
.. note::
2323

24-
The :mod:`xml.dom.minidom` module is not secure against
25-
maliciously constructed data. If you need to parse untrusted or
26-
unauthenticated data see :ref:`xml-vulnerabilities`.
24+
If you need to parse untrusted or unauthenticated data, see
25+
:ref:`xml-security`.
2726

2827

2928
DOM applications typically start by parsing some XML into a DOM. With

‎Doc/library/xml.dom.pulldom.rst‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,10 @@ responsible for explicitly pulling events from the stream, looping over those
1919
events until either processing is finished or an error condition occurs.
2020

2121

22-
.. warning::
22+
.. note::
2323

24-
The :mod:`xml.dom.pulldom` module is not secure against
25-
maliciously constructed data. If you need to parse untrusted or
26-
unauthenticated data see :ref:`xml-vulnerabilities`.
24+
If you need to parse untrusted or unauthenticated data, see
25+
:ref:`xml-security`.
2726

2827
.. versionchanged:: 3.7.1
2928

‎Doc/library/xml.etree.elementtree.rst‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,10 @@ for parsing and creating XML data.
2020
The :mod:`!xml.etree.cElementTree` module is deprecated.
2121

2222

23-
.. warning::
23+
.. note::
2424

25-
The :mod:`xml.etree.ElementTree` module is not secure against
26-
maliciously constructed data. If you need to parse untrusted or
27-
unauthenticated data see :ref:`xml-vulnerabilities`.
25+
If you need to parse untrusted or unauthenticated data, see
26+
:ref:`xml-security`.
2827

2928
Tutorial
3029
--------

0 commit comments

Comments
 (0)