From b0925211f405f6aa353e9e8fd748dca773b9b8aa Mon Sep 17 00:00:00 2001 From: Pablo Galindo Date: Mon, 12 Sep 2022 11:54:49 +0100 Subject: Post 3.11.0rc2 --- Include/patchlevel.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Include/patchlevel.h b/Include/patchlevel.h index f727dc2..a54a2ce 100644 --- a/Include/patchlevel.h +++ b/Include/patchlevel.h @@ -23,7 +23,7 @@ #define PY_RELEASE_SERIAL 2 /* Version as a string */ -#define PY_VERSION "3.11.0rc2" +#define PY_VERSION "3.11.0rc2+" /*--end constants--*/ /* Version as a single 4-byte hex number, e.g. 0x010502B2 == 1.5.2b2. -- cgit v0.12 From c6df6eecd88bc56c8a7e2bf0ae4a65db79fabea3 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sun, 16 Oct 2022 12:41:41 -0700 Subject: GH-91415: Mention alphabetical sort ordering in the Sorting HOWTO (GH-98336) (cherry picked from commit ae192178679c532e2c1b2d3b8c0928b77e0fe90e) Co-authored-by: Raymond Hettinger --- Doc/howto/sorting.rst | 98 ++++++++++++--------------------------------------- 1 file changed, 22 insertions(+), 76 deletions(-) diff --git a/Doc/howto/sorting.rst b/Doc/howto/sorting.rst index 53cbe01..588e895 100644 --- a/Doc/howto/sorting.rst +++ b/Doc/howto/sorting.rst @@ -186,8 +186,8 @@ The `Timsort `_ algorithm used in Python does multiple sorts efficiently because it can take advantage of any ordering already present in a dataset. -The Old Way Using Decorate-Sort-Undecorate -========================================== +Decorate-Sort-Undecorate +======================== This idiom is called Decorate-Sort-Undecorate after its three steps: @@ -226,90 +226,36 @@ after Randal L. Schwartz, who popularized it among Perl programmers. Now that Python sorting provides key-functions, this technique is not often needed. +Comparison Functions +==================== -The Old Way Using the *cmp* Parameter -===================================== - -Many constructs given in this HOWTO assume Python 2.4 or later. Before that, -there was no :func:`sorted` builtin and :meth:`list.sort` took no keyword -arguments. Instead, all of the Py2.x versions supported a *cmp* parameter to -handle user specified comparison functions. - -In Py3.0, the *cmp* parameter was removed entirely (as part of a larger effort to -simplify and unify the language, eliminating the conflict between rich -comparisons and the :meth:`__cmp__` magic method). - -In Py2.x, sort allowed an optional function which can be called for doing the -comparisons. That function should take two arguments to be compared and then -return a negative value for less-than, return zero if they are equal, or return -a positive value for greater-than. For example, we can do: - -.. doctest:: - - >>> def numeric_compare(x, y): - ... return x - y - >>> sorted([5, 2, 4, 1, 3], cmp=numeric_compare) # doctest: +SKIP - [1, 2, 3, 4, 5] - -Or you can reverse the order of comparison with: - -.. doctest:: - - >>> def reverse_numeric(x, y): - ... return y - x - >>> sorted([5, 2, 4, 1, 3], cmp=reverse_numeric) # doctest: +SKIP - [5, 4, 3, 2, 1] - -When porting code from Python 2.x to 3.x, the situation can arise when you have -the user supplying a comparison function and you need to convert that to a key -function. The following wrapper makes that easy to do: - -.. testcode:: - - def cmp_to_key(mycmp): - 'Convert a cmp= function into a key= function' - class K: - def __init__(self, obj, *args): - self.obj = obj - def __lt__(self, other): - return mycmp(self.obj, other.obj) < 0 - def __gt__(self, other): - return mycmp(self.obj, other.obj) > 0 - def __eq__(self, other): - return mycmp(self.obj, other.obj) == 0 - def __le__(self, other): - return mycmp(self.obj, other.obj) <= 0 - def __ge__(self, other): - return mycmp(self.obj, other.obj) >= 0 - def __ne__(self, other): - return mycmp(self.obj, other.obj) != 0 - return K - -.. doctest:: - :hide: +Unlike key functions that return an absolute value for sorting, a comparison +function computes the relative ordering for two inputs. - >>> sorted([5, 2, 4, 1, 3], key=cmp_to_key(reverse_numeric)) - [5, 4, 3, 2, 1] +For example, a `balance scale +`_ +compares two samples giving a relative ordering: lighter, equal, or heavier. +Likewise, a comparison function such as ``cmp(a, b)`` will return a negative +value for less-than, zero if the inputs are equal, or a positive value for +greater-than. -To convert to a key function, just wrap the old comparison function: - -.. testsetup:: - - from functools import cmp_to_key - -.. doctest:: +It is common to encounter comparison functions when translating algorithms from +other languages. Also, some libraries provide comparison functions as part of +their API. For example, :func:`locale.strcoll` is a comparison function. - >>> sorted([5, 2, 4, 1, 3], key=cmp_to_key(reverse_numeric)) - [5, 4, 3, 2, 1] +To accommodate those situations, Python provides +:class:`functools.cmp_to_key` to wrap the comparison function +to make it usable as a key function:: -In Python 3.2, the :func:`functools.cmp_to_key` function was added to the -:mod:`functools` module in the standard library. + sorted(words, key=cmp_to_key(strcoll) Odds and Ends ============= * For locale aware sorting, use :func:`locale.strxfrm` for a key function or - :func:`locale.strcoll` for a comparison function. + :func:`locale.strcoll` for a comparison function. This is necessary + because "alphabetical" sort orderings can vary across cultures even + if the underlying alphabet is the same. * The *reverse* parameter still maintains sort stability (so that records with equal keys retain the original order). Interestingly, that effect can be -- cgit v0.12 From a2820a0ec87d40c1b49c7295963eedc27f2d1284 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sun, 16 Oct 2022 10:16:48 -0700 Subject: gh-85299: Add note warning about entry point guard for asyncio example (GH-93457) (cherry picked from commit 79fd6ccdbe00ec95e4d33fc24fe76076282a334e) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> --- Doc/library/asyncio-eventloop.rst | 8 +++++++- Doc/library/multiprocessing.rst | 2 ++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 555a0f5..c1dddbf 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -1206,7 +1206,13 @@ Executing code in thread or process pools pool, cpu_bound) print('custom process pool', result) - asyncio.run(main()) + if __name__ == '__main__': + asyncio.run(main()) + + Note that the entry point guard (``if __name__ == '__main__'``) + is required for option 3 due to the peculiarities of :mod:`multiprocessing`, + which is used by :class:`~concurrent.futures.ProcessPoolExecutor`. + See :ref:`Safe importing of main module `. This method returns a :class:`asyncio.Future` object. diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index caf24a3..74e3377 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -2955,6 +2955,8 @@ Global variables However, global variables which are just module level constants cause no problems. +.. _multiprocessing-safe-main-import: + Safe importing of main module Make sure that the main module can be safely imported by a new Python -- cgit v0.12 From 77000c82f92072ed8d8a14af734e739e4e989251 Mon Sep 17 00:00:00 2001 From: Vinay Sajip Date: Sat, 15 Oct 2022 21:51:58 +0100 Subject: =?UTF-8?q?[3.11]=20[doc]=20Update=20logging=20cookbook=20with=20a?= =?UTF-8?q?n=20example=20of=20custom=20handli=E2=80=A6=20(GH-98296)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jelle Zijlstra --- Doc/howto/logging-cookbook.rst | 361 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 358 insertions(+), 3 deletions(-) diff --git a/Doc/howto/logging-cookbook.rst b/Doc/howto/logging-cookbook.rst index 16df3b7..10639b1 100644 --- a/Doc/howto/logging-cookbook.rst +++ b/Doc/howto/logging-cookbook.rst @@ -276,6 +276,211 @@ choose a different directory name for the log - just ensure that the directory e and that you have the permissions to create and update files in it. +.. _custom-level-handling: + +Custom handling of levels +------------------------- + +Sometimes, you might want to do something slightly different from the standard +handling of levels in handlers, where all levels above a threshold get +processed by a handler. To do this, you need to use filters. Let's look at a +scenario where you want to arrange things as follows: + +* Send messages of severity ``INFO`` and ``WARNING`` to ``sys.stdout`` +* Send messages of severity ``ERROR`` and above to ``sys.stderr`` +* Send messages of severity ``DEBUG`` and above to file ``app.log`` + +Suppose you configure logging with the following JSON: + +.. code-block:: json + + { + "version": 1, + "disable_existing_loggers": false, + "formatters": { + "simple": { + "format": "%(levelname)-8s - %(message)s" + } + }, + "handlers": { + "stdout": { + "class": "logging.StreamHandler", + "level": "INFO", + "formatter": "simple", + "stream": "ext://sys.stdout", + }, + "stderr": { + "class": "logging.StreamHandler", + "level": "ERROR", + "formatter": "simple", + "stream": "ext://sys.stderr" + }, + "file": { + "class": "logging.FileHandler", + "formatter": "simple", + "filename": "app.log", + "mode": "w" + } + }, + "root": { + "level": "DEBUG", + "handlers": [ + "stderr", + "stdout", + "file" + ] + } + } + +This configuration does *almost* what we want, except that ``sys.stdout`` would +show messages of severity ``ERROR`` and above as well as ``INFO`` and +``WARNING`` messages. To prevent this, we can set up a filter which excludes +those messages and add it to the relevant handler. This can be configured by +adding a ``filters`` section parallel to ``formatters`` and ``handlers``: + +.. code-block:: json + + "filters": { + "warnings_and_below": { + "()" : "__main__.filter_maker", + "level": "WARNING" + } + } + +and changing the section on the ``stdout`` handler to add it: + +.. code-block:: json + + "stdout": { + "class": "logging.StreamHandler", + "level": "INFO", + "formatter": "simple", + "stream": "ext://sys.stdout", + "filters": ["warnings_and_below"] + } + +A filter is just a function, so we can define the ``filter_maker`` (a factory +function) as follows: + +.. code-block:: python + + def filter_maker(level): + level = getattr(logging, level) + + def filter(record): + return record.levelno <= level + + return filter + +This converts the string argument passed in to a numeric level, and returns a +function which only returns ``True`` if the level of the passed in record is +at or below the specified level. Note that in this example I have defined the +``filter_maker`` in a test script ``main.py`` that I run from the command line, +so its module will be ``__main__`` - hence the ``__main__.filter_maker`` in the +filter configuration. You will need to change that if you define it in a +different module. + +With the filter added, we can run ``main.py``, which in full is: + +.. code-block:: python + + import json + import logging + import logging.config + + CONFIG = ''' + { + "version": 1, + "disable_existing_loggers": false, + "formatters": { + "simple": { + "format": "%(levelname)-8s - %(message)s" + } + }, + "filters": { + "warnings_and_below": { + "()" : "__main__.filter_maker", + "level": "WARNING" + } + }, + "handlers": { + "stdout": { + "class": "logging.StreamHandler", + "level": "INFO", + "formatter": "simple", + "stream": "ext://sys.stdout", + "filters": ["warnings_and_below"] + }, + "stderr": { + "class": "logging.StreamHandler", + "level": "ERROR", + "formatter": "simple", + "stream": "ext://sys.stderr" + }, + "file": { + "class": "logging.FileHandler", + "formatter": "simple", + "filename": "app.log", + "mode": "w" + } + }, + "root": { + "level": "DEBUG", + "handlers": [ + "stderr", + "stdout", + "file" + ] + } + } + ''' + + def filter_maker(level): + level = getattr(logging, level) + + def filter(record): + return record.levelno <= level + + return filter + + logging.config.dictConfig(json.loads(CONFIG)) + logging.debug('A DEBUG message') + logging.info('An INFO message') + logging.warning('A WARNING message') + logging.error('An ERROR message') + logging.critical('A CRITICAL message') + +And after running it like this: + +.. code-block:: shell + + python main.py 2>stderr.log >stdout.log + +We can see the results are as expected: + +.. code-block:: shell + + $ more *.log + :::::::::::::: + app.log + :::::::::::::: + DEBUG - A DEBUG message + INFO - An INFO message + WARNING - A WARNING message + ERROR - An ERROR message + CRITICAL - A CRITICAL message + :::::::::::::: + stderr.log + :::::::::::::: + ERROR - An ERROR message + CRITICAL - A CRITICAL message + :::::::::::::: + stdout.log + :::::::::::::: + INFO - An INFO message + WARNING - A WARNING message + + Configuration server example ---------------------------- @@ -3420,6 +3625,159 @@ the above handler, you'd pass structured data using something like this:: i = 1 logger.debug('Message %d', i, extra=extra) +How to treat a logger like an output stream +------------------------------------------- + +Sometimes, you need to interface to a third-party API which expects a file-like +object to write to, but you want to direct the API's output to a logger. You +can do this using a class which wraps a logger with a file-like API. +Here's a short script illustrating such a class: + +.. code-block:: python + + import logging + + class LoggerWriter: + def __init__(self, logger, level): + self.logger = logger + self.level = level + + def write(self, message): + if message != '\n': # avoid printing bare newlines, if you like + self.logger.log(self.level, message) + + def flush(self): + # doesn't actually do anything, but might be expected of a file-like + # object - so optional depending on your situation + pass + + def close(self): + # doesn't actually do anything, but might be expected of a file-like + # object - so optional depending on your situation. You might want + # to set a flag so that later calls to write raise an exception + pass + + def main(): + logging.basicConfig(level=logging.DEBUG) + logger = logging.getLogger('demo') + info_fp = LoggerWriter(logger, logging.INFO) + debug_fp = LoggerWriter(logger, logging.DEBUG) + print('An INFO message', file=info_fp) + print('A DEBUG message', file=debug_fp) + + if __name__ == "__main__": + main() + +When this script is run, it prints + +.. code-block:: text + + INFO:demo:An INFO message + DEBUG:demo:A DEBUG message + +You could also use ``LoggerWriter`` to redirect ``sys.stdout`` and +``sys.stderr`` by doing something like this: + +.. code-block:: python + + import sys + + sys.stdout = LoggerWriter(logger, logging.INFO) + sys.stderr = LoggerWriter(logger, logging.WARNING) + +You should do this *after* configuring logging for your needs. In the above +example, the :func:`~logging.basicConfig` call does this (using the +``sys.stderr`` value *before* it is overwritten by a ``LoggerWriter`` +instance). Then, you'd get this kind of result: + +.. code-block:: pycon + + >>> print('Foo') + INFO:demo:Foo + >>> print('Bar', file=sys.stderr) + WARNING:demo:Bar + >>> + +Of course, these above examples show output according to the format used by +:func:`~logging.basicConfig`, but you can use a different formatter when you +configure logging. +======= +How to treat a logger like an output stream +------------------------------------------- + +Sometimes, you need to interface to a third-party API which expects a file-like +object to write to, but you want to direct the API's output to a logger. You +can do this using a class which wraps a logger with a file-like API. +Here's a short script illustrating such a class: + +.. code-block:: python + + import logging + + class LoggerWriter: + def __init__(self, logger, level): + self.logger = logger + self.level = level + + def write(self, message): + if message != '\n': # avoid printing bare newlines, if you like + self.logger.log(self.level, message) + + def flush(self): + # doesn't actually do anything, but might be expected of a file-like + # object - so optional depending on your situation + pass + + def close(self): + # doesn't actually do anything, but might be expected of a file-like + # object - so optional depending on your situation. You might want + # to set a flag so that later calls to write raise an exception + pass + + def main(): + logging.basicConfig(level=logging.DEBUG) + logger = logging.getLogger('demo') + info_fp = LoggerWriter(logger, logging.INFO) + debug_fp = LoggerWriter(logger, logging.DEBUG) + print('An INFO message', file=info_fp) + print('A DEBUG message', file=debug_fp) + + if __name__ == "__main__": + main() + +When this script is run, it prints + +.. code-block:: text + + INFO:demo:An INFO message + DEBUG:demo:A DEBUG message + +You could also use ``LoggerWriter`` to redirect ``sys.stdout`` and +``sys.stderr`` by doing something like this: + +.. code-block:: python + + import sys + + sys.stdout = LoggerWriter(logger, logging.INFO) + sys.stderr = LoggerWriter(logger, logging.WARNING) + +You should do this *after* configuring logging for your needs. In the above +example, the :func:`~logging.basicConfig` call does this (using the +``sys.stderr`` value *before* it is overwritten by a ``LoggerWriter`` +instance). Then, you'd get this kind of result: + +.. code-block:: pycon + + >>> print('Foo') + INFO:demo:Foo + >>> print('Bar', file=sys.stderr) + WARNING:demo:Bar + >>> + +Of course, the examples above show output according to the format used by +:func:`~logging.basicConfig`, but you can use a different formatter when you +configure logging. .. patterns-to-avoid: @@ -3431,7 +3789,6 @@ need to do or deal with, it is worth mentioning some usage patterns which are *unhelpful*, and which should therefore be avoided in most cases. The following sections are in no particular order. - Opening the same log file multiple times ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -3480,7 +3837,6 @@ that in other languages such as Java and C#, loggers are often static class attributes. However, this pattern doesn't make sense in Python, where the module (and not the class) is the unit of software decomposition. - Adding handlers other than :class:`NullHandler` to a logger in a library ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -3489,7 +3845,6 @@ responsibility of the application developer, not the library developer. If you are maintaining a library, ensure that you don't add handlers to any of your loggers other than a :class:`~logging.NullHandler` instance. - Creating a lot of loggers ^^^^^^^^^^^^^^^^^^^^^^^^^ -- cgit v0.12 From 1a84816c30e35f7d14cf7f6ae378b9201640c4b2 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sat, 15 Oct 2022 12:25:58 -0700 Subject: docs(typing): harmonize "See PEP x for more details" (GH-97927) (cherry picked from commit 02389658a4751a0166e2ed22be112b646378a01b) Co-authored-by: Simon Legner --- Doc/library/typing.rst | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 7639406..38421e5 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -243,7 +243,7 @@ respectively. .. versionchanged:: 3.10 ``Callable`` now supports :class:`ParamSpec` and :data:`Concatenate`. - See :pep:`612` for more information. + See :pep:`612` for more details. .. seealso:: The documentation for :class:`ParamSpec` and :class:`Concatenate` provides @@ -716,7 +716,7 @@ These can be used as types in annotations and do not support ``[]``. of the ``cls`` parameter. - Annotating an :meth:`~object.__enter__` method which returns self. - For more information, see :pep:`673`. + See :pep:`673` for more details. .. versionadded:: 3.11 @@ -847,7 +847,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn .. versionchanged:: 3.10 ``Callable`` now supports :class:`ParamSpec` and :data:`Concatenate`. - See :pep:`612` for more information. + See :pep:`612` for more details. .. seealso:: The documentation for :class:`ParamSpec` and :class:`Concatenate` provide @@ -1033,8 +1033,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn Special typing constructs that mark individual keys of a :class:`TypedDict` as either required or non-required respectively. - For more information, see :class:`TypedDict` and - :pep:`655` ("Marking individual TypedDict items as required or potentially missing"). + See :class:`TypedDict` and :pep:`655` for more details. .. versionadded:: 3.11 @@ -1185,8 +1184,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn is not a subtype of the former, since ``list`` is invariant. The responsibility of writing type-safe type guards is left to the user. - ``TypeGuard`` also works with type variables. For more information, see - :pep:`647` (User-Defined Type Guards). + ``TypeGuard`` also works with type variables. See :pep:`647` for more details. .. versionadded:: 3.10 @@ -1386,7 +1384,7 @@ These are not used in annotations. They are building blocks for creating generic to ``call_soon`` match the types of the (positional) arguments of ``callback``. - For more details on type variable tuples, see :pep:`646`. + See :pep:`646` for more details on type variable tuples. .. versionadded:: 3.11 @@ -1549,7 +1547,7 @@ These are not used in annotations. They are building blocks for creating generic func(C()) # Passes static type check - See :pep:`544` for details. Protocol classes decorated with + See :pep:`544` for more details. Protocol classes decorated with :func:`runtime_checkable` (described later) act as simple-minded runtime protocols that check only the presence of given attributes, ignoring their type signatures. @@ -2619,7 +2617,7 @@ Functions and decorators def process(response): - See :pep:`484` for details and comparison with other typing semantics. + See :pep:`484` for more details and comparison with other typing semantics. .. versionchanged:: 3.11 Overloaded functions can now be introspected at runtime using -- cgit v0.12 From be5de5016637a3a3101c551ca5b162c500a220ce Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sat, 15 Oct 2022 10:52:45 -0700 Subject: Faster sieve() recipe (GH-98287) (cherry picked from commit f4370318d67f1f2f686c1c3a4b217ccc461d31e5) Co-authored-by: Raymond Hettinger --- Doc/library/itertools.rst | 48 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst index da550e6..2b4d7d5 100644 --- a/Doc/library/itertools.rst +++ b/Doc/library/itertools.rst @@ -812,6 +812,26 @@ which incur interpreter overhead. for k in range(len(roots) + 1) ] + def iter_index(seq, value, start=0): + "Return indices where a value occurs in a sequence." + # iter_index('AABCADEAF', 'A') --> 0 1 4 7 + i = start - 1 + try: + while True: + yield (i := seq.index(value, i+1)) + except ValueError: + pass + + def sieve(n): + "Primes less than n" + # sieve(30) --> 2 3 5 7 11 13 17 19 23 29 + data = bytearray([1]) * n + data[:2] = 0, 0 + limit = math.isqrt(n) + 1 + for p in compress(range(limit), data): + data[p*p : n : p] = bytearray(len(range(p*p, n, p))) + return iter_index(data, 1) + def flatten(list_of_lists): "Flatten one level of nesting" return chain.from_iterable(list_of_lists) @@ -1156,6 +1176,34 @@ which incur interpreter overhead. >>> all(factored(x) == expanded(x) for x in range(-10, 11)) True + >>> list(iter_index('AABCADEAF', 'A')) + [0, 1, 4, 7] + >>> list(iter_index('AABCADEAF', 'B')) + [2] + >>> list(iter_index('AABCADEAF', 'X')) + [] + >>> list(iter_index('', 'X')) + [] + + >>> list(sieve(30)) + [2, 3, 5, 7, 11, 13, 17, 19, 23, 29] + >>> small_primes = [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73, 79, 83, 89, 97] + >>> all(list(sieve(n)) == [p for p in small_primes if p < n] for n in range(101)) + True + >>> len(list(sieve(100))) + 25 + >>> len(list(sieve(1_000))) + 168 + >>> len(list(sieve(10_000))) + 1229 + >>> len(list(sieve(100_000))) + 9592 + >>> len(list(sieve(1_000_000))) + 78498 + >>> carmichael = {561, 1105, 1729, 2465, 2821, 6601, 8911} # https://oeis.org/A002997 + >>> set(sieve(10_000)).isdisjoint(carmichael) + True + >>> list(flatten([('a', 'b'), (), ('c', 'd', 'e'), ('f',), ('g', 'h', 'i')])) ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i'] -- cgit v0.12 From f96dbab7d8f87525bfd2ce10a8d960535334b637 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sat, 15 Oct 2022 09:12:18 -0700 Subject: gh-98227: executionmodel.rst: except* can also bind names (GH-98256) Co-authored-by: Jelle Zijlstra (cherry picked from commit 146f168fbf5b239158922f4defd494088c381525) Co-authored-by: BiscuitCandy <70342294+BiscuitCandy@users.noreply.github.com> --- Doc/reference/executionmodel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/executionmodel.rst b/Doc/reference/executionmodel.rst index d918356..3f01180 100644 --- a/Doc/reference/executionmodel.rst +++ b/Doc/reference/executionmodel.rst @@ -67,7 +67,7 @@ The following constructs bind names: + :keyword:`for` loop header, + after :keyword:`!as` in a :keyword:`with` statement, :keyword:`except` - clause or in the as-pattern in structural pattern matching, + clause, :keyword:`except* ` clause, or in the as-pattern in structural pattern matching, + in a capture pattern in structural pattern matching * :keyword:`import` statements. -- cgit v0.12 From 3737a0e3ab96823064b77ff9635b4640b9be4256 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sat, 15 Oct 2022 07:32:37 -0700 Subject: gh-91485: Doc: Using Python syntax to document builtin Python functions. (GH-96579) (cherry picked from commit 3c4cbd177f36777a04e78eb07ce20367560a66d3) Co-authored-by: Julien Palard --- Doc/library/functions.rst | 149 ++++++++++++++++++++++++++-------------------- 1 file changed, 84 insertions(+), 65 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 1ba22b2..4986d0a 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -54,14 +54,14 @@ are always available. They are listed here in alphabetical order. .. |func-bytearray| replace:: ``bytearray()`` .. |func-bytes| replace:: ``bytes()`` -.. function:: abs(x) +.. function:: abs(x, /) Return the absolute value of a number. The argument may be an integer, a floating point number, or an object implementing :meth:`__abs__`. If the argument is a complex number, its magnitude is returned. -.. function:: aiter(async_iterable) +.. function:: aiter(async_iterable, /) Return an :term:`asynchronous iterator` for an :term:`asynchronous iterable`. Equivalent to calling ``x.__aiter__()``. @@ -70,7 +70,7 @@ are always available. They are listed here in alphabetical order. .. versionadded:: 3.10 -.. function:: all(iterable) +.. function:: all(iterable, /) Return ``True`` if all elements of the *iterable* are true (or if the iterable is empty). Equivalent to:: @@ -82,7 +82,8 @@ are always available. They are listed here in alphabetical order. return True -.. awaitablefunction:: anext(async_iterator[, default]) +.. awaitablefunction:: anext(async_iterator, /) + anext(async_iterator, default, /) When awaited, return the next item from the given :term:`asynchronous iterator`, or *default* if given and the iterator is exhausted. @@ -97,7 +98,7 @@ are always available. They are listed here in alphabetical order. .. versionadded:: 3.10 -.. function:: any(iterable) +.. function:: any(iterable, /) Return ``True`` if any element of the *iterable* is true. If the iterable is empty, return ``False``. Equivalent to:: @@ -109,7 +110,7 @@ are always available. They are listed here in alphabetical order. return False -.. function:: ascii(object) +.. function:: ascii(object, /) As :func:`repr`, return a string containing a printable representation of an object, but escape the non-ASCII characters in the string returned by @@ -117,7 +118,7 @@ are always available. They are listed here in alphabetical order. similar to that returned by :func:`repr` in Python 2. -.. function:: bin(x) +.. function:: bin(x, /) Convert an integer number to a binary string prefixed with "0b". The result is a valid Python expression. If *x* is not a Python :class:`int` object, it @@ -139,7 +140,7 @@ are always available. They are listed here in alphabetical order. See also :func:`format` for more information. -.. class:: bool([x]) +.. class:: bool(x=False, /) Return a Boolean value, i.e. one of ``True`` or ``False``. *x* is converted using the standard :ref:`truth testing procedure `. If *x* is false @@ -172,7 +173,9 @@ are always available. They are listed here in alphabetical order. .. versionadded:: 3.7 .. _func-bytearray: -.. class:: bytearray([source[, encoding[, errors]]]) +.. class:: bytearray(source=b'') + bytearray(source, encoding) + bytearray(source, encoding, errors) :noindex: Return a new array of bytes. The :class:`bytearray` class is a mutable @@ -202,7 +205,9 @@ are always available. They are listed here in alphabetical order. .. _func-bytes: -.. class:: bytes([source[, encoding[, errors]]]) +.. class:: bytes(source=b'') + bytes(source, encoding) + bytes(source, encoding, errors) :noindex: Return a new "bytes" object which is an immutable sequence of integers in @@ -217,7 +222,7 @@ are always available. They are listed here in alphabetical order. See also :ref:`binaryseq`, :ref:`typebytes`, and :ref:`bytes-methods`. -.. function:: callable(object) +.. function:: callable(object, /) Return :const:`True` if the *object* argument appears callable, :const:`False` if not. If this returns ``True``, it is still possible that a @@ -230,7 +235,7 @@ are always available. They are listed here in alphabetical order. in Python 3.2. -.. function:: chr(i) +.. function:: chr(i, /) Return the string representing a character whose Unicode code point is the integer *i*. For example, ``chr(97)`` returns the string ``'a'``, while @@ -358,7 +363,8 @@ are always available. They are listed here in alphabetical order. support for top-level ``await``, ``async for``, and ``async with``. -.. class:: complex([real[, imag]]) +.. class:: complex(real=0, imag=0) + complex(string, /) Return a complex number with the value *real* + *imag*\*1j or convert a string or number to a complex number. If the first parameter is a string, it will @@ -391,7 +397,7 @@ are always available. They are listed here in alphabetical order. :meth:`__float__` are not defined. -.. function:: delattr(object, name) +.. function:: delattr(object, name, /) This is a relative of :func:`setattr`. The arguments are an object and a string. The string must be the name of one of the object's attributes. The @@ -401,8 +407,8 @@ are always available. They are listed here in alphabetical order. .. _func-dict: .. class:: dict(**kwarg) - dict(mapping, **kwarg) - dict(iterable, **kwarg) + dict(mapping, /, **kwarg) + dict(iterable, /, **kwarg) :noindex: Create a new dictionary. The :class:`dict` object is the dictionary class. @@ -412,7 +418,8 @@ are always available. They are listed here in alphabetical order. :class:`tuple` classes, as well as the :mod:`collections` module. -.. function:: dir([object]) +.. function:: dir() + dir(object, /) Without arguments, return the list of names in the current local scope. With an argument, attempt to return a list of valid attributes for that object. @@ -468,7 +475,7 @@ are always available. They are listed here in alphabetical order. class. -.. function:: divmod(a, b) +.. function:: divmod(a, b, /) Take two (non-complex) numbers as arguments and return a pair of numbers consisting of their quotient and remainder when using integer division. With @@ -504,7 +511,7 @@ are always available. They are listed here in alphabetical order. .. _func-eval: -.. function:: eval(expression[, globals[, locals]]) +.. function:: eval(expression, /, globals=None, locals=None) The arguments are a string and optional globals and locals. If provided, *globals* must be a dictionary. If provided, *locals* can be any mapping @@ -555,7 +562,7 @@ are always available. They are listed here in alphabetical order. .. index:: builtin: exec -.. function:: exec(object[, globals[, locals]], *, closure=None) +.. function:: exec(object, globals=None, locals=None, /, *, closure=None) This function supports dynamic execution of Python code. *object* must be either a string or a code object. If it is a string, the string is parsed as @@ -611,7 +618,7 @@ are always available. They are listed here in alphabetical order. Added the *closure* parameter. -.. function:: filter(function, iterable) +.. function:: filter(function, iterable, /) Construct an iterator from those elements of *iterable* for which *function* returns true. *iterable* may be either a sequence, a container which @@ -628,7 +635,7 @@ are always available. They are listed here in alphabetical order. elements of *iterable* for which *function* returns false. -.. class:: float([x]) +.. class:: float(x=0.0, /) .. index:: single: NaN @@ -696,7 +703,7 @@ are always available. They are listed here in alphabetical order. single: __format__ single: string; format() (built-in function) -.. function:: format(value[, format_spec]) +.. function:: format(value, format_spec="", /) Convert a *value* to a "formatted" representation, as controlled by *format_spec*. The interpretation of *format_spec* will depend on the type @@ -719,7 +726,7 @@ are always available. They are listed here in alphabetical order. .. _func-frozenset: -.. class:: frozenset([iterable]) +.. class:: frozenset(iterable=set(), /) :noindex: Return a new :class:`frozenset` object, optionally with elements taken from @@ -731,7 +738,8 @@ are always available. They are listed here in alphabetical order. module. -.. function:: getattr(object, name[, default]) +.. function:: getattr(object, name, /) + getattr(object, name, default, /) Return the value of the named attribute of *object*. *name* must be a string. If the string is the name of one of the object's attributes, the result is the @@ -754,7 +762,7 @@ are always available. They are listed here in alphabetical order. regardless of where the function is called. -.. function:: hasattr(object, name) +.. function:: hasattr(object, name, /) The arguments are an object and a string. The result is ``True`` if the string is the name of one of the object's attributes, ``False`` if not. (This @@ -762,7 +770,7 @@ are always available. They are listed here in alphabetical order. raises an :exc:`AttributeError` or not.) -.. function:: hash(object) +.. function:: hash(object, /) Return the hash value of the object (if it has one). Hash values are integers. They are used to quickly compare dictionary keys during a @@ -775,7 +783,8 @@ are always available. They are listed here in alphabetical order. truncates the return value based on the bit width of the host machine. See :meth:`__hash__` for details. -.. function:: help([object]) +.. function:: help() + help(request) Invoke the built-in help system. (This function is intended for interactive use.) If no argument is given, the interactive help system starts on the @@ -796,7 +805,7 @@ are always available. They are listed here in alphabetical order. signatures for callables are now more comprehensive and consistent. -.. function:: hex(x) +.. function:: hex(x, /) Convert an integer number to a lowercase hexadecimal string prefixed with "0x". If *x* is not a Python :class:`int` object, it has to define an @@ -828,7 +837,7 @@ are always available. They are listed here in alphabetical order. :meth:`float.hex` method. -.. function:: id(object) +.. function:: id(object, /) Return the "identity" of an object. This is an integer which is guaranteed to be unique and constant for this object during its lifetime. @@ -840,7 +849,8 @@ are always available. They are listed here in alphabetical order. .. audit-event:: builtins.id id id -.. function:: input([prompt]) +.. function:: input() + input(prompt, /) If the *prompt* argument is present, it is written to standard output without a trailing newline. The function then reads a line from input, converts it @@ -866,8 +876,8 @@ are always available. They are listed here in alphabetical order. with the result after successfully reading input. -.. class:: int([x]) - int(x, base=10) +.. class:: int(x=0, /) + int(x, /, base=10) Return an integer object constructed from a number or string *x*, or return ``0`` if no arguments are given. If *x* defines :meth:`__int__`, @@ -918,7 +928,7 @@ are always available. They are listed here in alphabetical order. See the :ref:`integer string conversion length limitation ` documentation. -.. function:: isinstance(object, classinfo) +.. function:: isinstance(object, classinfo, /) Return ``True`` if the *object* argument is an instance of the *classinfo* argument, or of a (direct, indirect, or :term:`virtual `) of *classinfo*. A @@ -949,7 +959,8 @@ are always available. They are listed here in alphabetical order. *classinfo* can be a :ref:`types-union`. -.. function:: iter(object[, sentinel]) +.. function:: iter(object, /) + iter(object, sentinel, /) Return an :term:`iterator` object. The first argument is interpreted very differently depending on the presence of the second argument. Without a @@ -976,7 +987,7 @@ are always available. They are listed here in alphabetical order. process_block(block) -.. function:: len(s) +.. function:: len(s, /) Return the length (the number of items) of an object. The argument may be a sequence (such as a string, bytes, tuple, list, or range) or a collection @@ -989,7 +1000,8 @@ are always available. They are listed here in alphabetical order. .. _func-list: -.. class:: list([iterable]) +.. class:: list() + list(iterable, /) :noindex: Rather than being a function, :class:`list` is actually a mutable @@ -1007,18 +1019,19 @@ are always available. They are listed here in alphabetical order. The contents of this dictionary should not be modified; changes may not affect the values of local and free variables used by the interpreter. -.. function:: map(function, iterable, ...) +.. function:: map(function, iterable, /, *iterables) Return an iterator that applies *function* to every item of *iterable*, - yielding the results. If additional *iterable* arguments are passed, + yielding the results. If additional *iterables* arguments are passed, *function* must take that many arguments and is applied to the items from all iterables in parallel. With multiple iterables, the iterator stops when the shortest iterable is exhausted. For cases where the function inputs are already arranged into argument tuples, see :func:`itertools.starmap`\. -.. function:: max(iterable, *[, key, default]) - max(arg1, arg2, *args[, key]) +.. function:: max(iterable, /, *, key=None) + max(iterable, /, *, default, key=None) + max(arg1, arg2, /, *args, key=None) Return the largest item in an iterable or the largest of two or more arguments. @@ -1054,8 +1067,9 @@ are always available. They are listed here in alphabetical order. :ref:`typememoryview` for more information. -.. function:: min(iterable, *[, key, default]) - min(arg1, arg2, *args[, key]) +.. function:: min(iterable, /, *, key=None) + min(iterable, /, *, default, key=None) + min(arg1, arg2, /, *args, key=None) Return the smallest item in an iterable or the smallest of two or more arguments. @@ -1083,7 +1097,8 @@ are always available. They are listed here in alphabetical order. The *key* can be ``None``. -.. function:: next(iterator[, default]) +.. function:: next(iterator, /) + next(iterator, default, /) Retrieve the next item from the :term:`iterator` by calling its :meth:`~iterator.__next__` method. If *default* is given, it is returned @@ -1102,7 +1117,7 @@ are always available. They are listed here in alphabetical order. assign arbitrary attributes to an instance of the :class:`object` class. -.. function:: oct(x) +.. function:: oct(x, /) Convert an integer number to an octal string prefixed with "0o". The result is a valid Python expression. If *x* is not a Python :class:`int` object, it @@ -1354,7 +1369,7 @@ are always available. They are listed here in alphabetical order. .. versionchanged:: 3.11 The ``'U'`` mode has been removed. -.. function:: ord(c) +.. function:: ord(c, /) Given a string representing one Unicode character, return an integer representing the Unicode code point of that character. For example, @@ -1362,7 +1377,7 @@ are always available. They are listed here in alphabetical order. returns ``8364``. This is the inverse of :func:`chr`. -.. function:: pow(base, exp[, mod]) +.. function:: pow(base, exp, mod=None) Return *base* to the power *exp*; if *mod* is present, return *base* to the power *exp*, modulo *mod* (computed more efficiently than @@ -1505,15 +1520,15 @@ are always available. They are listed here in alphabetical order. .. _func-range: -.. class:: range(stop) - range(start, stop[, step]) +.. class:: range(stop, /) + range(start, stop, step=1, /) :noindex: Rather than being a function, :class:`range` is actually an immutable sequence type, as documented in :ref:`typesseq-range` and :ref:`typesseq`. -.. function:: repr(object) +.. function:: repr(object, /) Return a string containing a printable representation of an object. For many types, this function makes an attempt to return a string that would yield an @@ -1526,7 +1541,7 @@ are always available. They are listed here in alphabetical order. :exc:`RuntimeError`. -.. function:: reversed(seq) +.. function:: reversed(seq, /) Return a reverse :term:`iterator`. *seq* must be an object which has a :meth:`__reversed__` method or supports the sequence protocol (the @@ -1534,7 +1549,7 @@ are always available. They are listed here in alphabetical order. arguments starting at ``0``). -.. function:: round(number[, ndigits]) +.. function:: round(number, ndigits=None) Return *number* rounded to *ndigits* precision after the decimal point. If *ndigits* is omitted or is ``None``, it returns the @@ -1562,7 +1577,8 @@ are always available. They are listed here in alphabetical order. .. _func-set: -.. class:: set([iterable]) +.. class:: set() + set(iterable, /) :noindex: Return a new :class:`set` object, optionally with elements taken from @@ -1574,7 +1590,7 @@ are always available. They are listed here in alphabetical order. module. -.. function:: setattr(object, name, value) +.. function:: setattr(object, name, value, /) This is the counterpart of :func:`getattr`. The arguments are an object, a string, and an arbitrary value. The string may name an existing attribute or a @@ -1590,8 +1606,8 @@ are always available. They are listed here in alphabetical order. :func:`setattr`. -.. class:: slice(stop) - slice(start, stop[, step]) +.. class:: slice(stop, /) + slice(start, stop, step=1, /) Return a :term:`slice` object representing the set of indices specified by ``range(start, stop, step)``. The *start* and *step* arguments default to @@ -1708,21 +1724,22 @@ are always available. They are listed here in alphabetical order. .. versionchanged:: 3.8 The *start* parameter can be specified as a keyword argument. -.. class:: super([type[, object-or-type]]) +.. class:: super() + super(type, object_or_type=None, /) Return a proxy object that delegates method calls to a parent or sibling class of *type*. This is useful for accessing inherited methods that have been overridden in a class. - The *object-or-type* determines the :term:`method resolution order` + The *object_or_type* determines the :term:`method resolution order` to be searched. The search starts from the class right after the *type*. - For example, if :attr:`~class.__mro__` of *object-or-type* is + For example, if :attr:`~class.__mro__` of *object_or_type* is ``D -> B -> C -> A -> object`` and the value of *type* is ``B``, then :func:`super` searches ``C -> A -> object``. - The :attr:`~class.__mro__` attribute of the *object-or-type* lists the method + The :attr:`~class.__mro__` attribute of the *object_or_type* lists the method resolution search order used by both :func:`getattr` and :func:`super`. The attribute is dynamic and can change whenever the inheritance hierarchy is updated. @@ -1778,15 +1795,16 @@ are always available. They are listed here in alphabetical order. .. _func-tuple: -.. class:: tuple([iterable]) +.. class:: tuple() + tuple(iterable, /) :noindex: Rather than being a function, :class:`tuple` is actually an immutable sequence type, as documented in :ref:`typesseq-tuple` and :ref:`typesseq`. -.. class:: type(object) - type(name, bases, dict, **kwds) +.. class:: type(object, /) + type(name, bases, dict, /, **kwds) .. index:: object: type @@ -1826,7 +1844,8 @@ are always available. They are listed here in alphabetical order. Subclasses of :class:`type` which don't override ``type.__new__`` may no longer use the one-argument form to get the type of an object. -.. function:: vars([object]) +.. function:: vars() + vars(object, /) Return the :attr:`~object.__dict__` attribute for a module, class, instance, or any other object with a :attr:`~object.__dict__` attribute. -- cgit v0.12 From 0f3c5ab0397ba35d6c705f70e2cfe9ff2422fd13 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 12 Oct 2022 09:13:24 -0700 Subject: gh-96265: Formatting changes for faq/general (GH-98129) * Some formatting changes for general faq * Use list for Python versioning Co-authored-by: Ezio Melotti * New line for list, list for a/b/rc * Line wrap for 80 chars * More line wrap * Remove PythonWin mention. Co-authored-by: C.A.M. Gerlach Co-authored-by: Ezio Melotti Co-authored-by: C.A.M. Gerlach (cherry picked from commit e9569ec43e2376aa77240cd630db4be07e8720f3) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> --- Doc/faq/general.rst | 30 ++++++++++++++++++------------ 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/Doc/faq/general.rst b/Doc/faq/general.rst index 6c7e4fc..2fb68f6 100644 --- a/Doc/faq/general.rst +++ b/Doc/faq/general.rst @@ -125,11 +125,15 @@ find packages of interest to you. How does the Python version numbering scheme work? -------------------------------------------------- -Python versions are numbered A.B.C or A.B. A is the major version number -- it -is only incremented for really major changes in the language. B is the minor -version number, incremented for less earth-shattering changes. C is the -micro-level -- it is incremented for each bugfix release. See :pep:`6` for more -information about bugfix releases. +Python versions are numbered "A.B.C" or "A.B": + +* *A* is the major version number -- it is only incremented for really major + changes in the language. +* *B* is the minor version number -- it is incremented for less earth-shattering + changes. +* *C* is the micro version number -- it is incremented for each bugfix release. + +See :pep:`6` for more information about bugfix releases. Not all releases are bugfix releases. In the run-up to a new major release, a series of development releases are made, denoted as alpha, beta, or release @@ -139,12 +143,14 @@ Betas are more stable, preserving existing interfaces but possibly adding new modules, and release candidates are frozen, making no changes except as needed to fix critical bugs. -Alpha, beta and release candidate versions have an additional suffix. The -suffix for an alpha version is "aN" for some small number N, the suffix for a -beta version is "bN" for some small number N, and the suffix for a release -candidate version is "rcN" for some small number N. In other words, all versions -labeled 2.0aN precede the versions labeled 2.0bN, which precede versions labeled -2.0rcN, and *those* precede 2.0. +Alpha, beta and release candidate versions have an additional suffix: + +* The suffix for an alpha version is "aN" for some small number *N*. +* The suffix for a beta version is "bN" for some small number *N*. +* The suffix for a release candidate version is "rcN" for some small number *N*. + +In other words, all versions labeled *2.0aN* precede the versions labeled +*2.0bN*, which precede versions labeled *2.0rcN*, and *those* precede 2.0. You may also find version numbers with a "+" suffix, e.g. "2.2+". These are unreleased versions, built directly from the CPython development repository. In @@ -429,7 +435,7 @@ With the interpreter, documentation is never far from the student as they are programming. There are also good IDEs for Python. IDLE is a cross-platform IDE for Python -that is written in Python using Tkinter. PythonWin is a Windows-specific IDE. +that is written in Python using Tkinter. Emacs users will be happy to know that there is a very good Python mode for Emacs. All of these programming environments provide syntax highlighting, auto-indenting, and access to the interactive interpreter while coding. Consult -- cgit v0.12 From b63602303e334e454d3f54e8b304599a4cc6f2e9 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 12 Oct 2022 09:08:56 -0700 Subject: tutorial: remove "with single quotes" (GH-98204) Closes GH-91856. On Windows double quotes are sometimes better, on Unix usually single quotes. It's not our place to explain that, so just don't. (cherry picked from commit 5f8ca1b7969f34ee09adb7b28337ebd920e6215a) Co-authored-by: Jelle Zijlstra --- Doc/tutorial/interpreter.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tutorial/interpreter.rst b/Doc/tutorial/interpreter.rst index d7f300d..08851cb 100644 --- a/Doc/tutorial/interpreter.rst +++ b/Doc/tutorial/interpreter.rst @@ -52,7 +52,7 @@ A second way of starting the interpreter is ``python -c command [arg] ...``, which executes the statement(s) in *command*, analogous to the shell's :option:`-c` option. Since Python statements often contain spaces or other characters that are special to the shell, it is usually advised to quote -*command* in its entirety with single quotes. +*command* in its entirety. Some Python modules are also useful as scripts. These can be invoked using ``python -m module [arg] ...``, which executes the source file for *module* as -- cgit v0.12 From 168ec080e8c537cc1e7c93237afcb3c44d393358 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 11 Oct 2022 21:51:13 -0700 Subject: gh-65046: Link to logging cookbook from asyncio docs (GH-98207) (cherry picked from commit c39a0c335486fa8eac0f3030930f9e8769118a4f) Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com> --- Doc/howto/logging-cookbook.rst | 2 ++ Doc/library/asyncio-dev.rst | 5 +++++ 2 files changed, 7 insertions(+) diff --git a/Doc/howto/logging-cookbook.rst b/Doc/howto/logging-cookbook.rst index 10639b1..25ea37f 100644 --- a/Doc/howto/logging-cookbook.rst +++ b/Doc/howto/logging-cookbook.rst @@ -537,6 +537,8 @@ configuration:: print('complete') +.. _blocking-handlers: + Dealing with handlers that block -------------------------------- diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst index 77f1128..29d69b9 100644 --- a/Doc/library/asyncio-dev.rst +++ b/Doc/library/asyncio-dev.rst @@ -148,6 +148,11 @@ adjusted:: logging.getLogger("asyncio").setLevel(logging.WARNING) +Network logging can block the event loop. It is recommended to use +a separate thread for handling logs or use non-blocking IO. For example, +see :ref:`blocking-handlers`. + + .. _asyncio-coroutine-not-scheduled: Detect never-awaited coroutines -- cgit v0.12 From 61e24f3abd2eeb71633a66383f13118e3771fa67 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 11 Oct 2022 21:05:12 -0700 Subject: Formatting fixes in contextlib docs (GH-98111) (cherry picked from commit 3b33c2010aa00ef5877bc35b02ae658e3c9f27af) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> --- Doc/library/contextlib.rst | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index 2d28fb3..1b55868 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -66,6 +66,8 @@ Functions and classes provided: # Code to release resource, e.g.: release_resource(resource) + The function can then be used like this:: + >>> with managed_resource(timeout=3600) as resource: ... # Resource is released at the end of this block, ... # even if code in the block raises an exception @@ -140,9 +142,9 @@ Functions and classes provided: finally: print(f'it took {time.monotonic() - now}s to run') - @timeit() - async def main(): - # ... async code ... + @timeit() + async def main(): + # ... async code ... When used as a decorator, a new generator instance is implicitly created on each function call. This allows the otherwise "one-shot" context managers @@ -249,15 +251,15 @@ Functions and classes provided: :ref:`asynchronous context managers `:: async def send_http(session=None): - if not session: - # If no http session, create it with aiohttp - cm = aiohttp.ClientSession() - else: - # Caller is responsible for closing the session - cm = nullcontext(session) + if not session: + # If no http session, create it with aiohttp + cm = aiohttp.ClientSession() + else: + # Caller is responsible for closing the session + cm = nullcontext(session) - async with cm as session: - # Send http requests with session + async with cm as session: + # Send http requests with session .. versionadded:: 3.7 @@ -396,6 +398,8 @@ Functions and classes provided: print('Finishing') return False + The class can then be used like this:: + >>> @mycontext() ... def function(): ... print('The bit in the middle') @@ -466,6 +470,8 @@ Functions and classes provided: print('Finishing') return False + The class can then be used like this:: + >>> @mycontext() ... async def function(): ... print('The bit in the middle') -- cgit v0.12 From 37d165904d34aea0921c6a46568bb04e02f1b156 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 11 Oct 2022 19:50:25 -0700 Subject: gh-95276: Add callable entry to the glossary (GH-95738) (cherry picked from commit e3bf125c81d5da0734429c1cb6ae75e6086e35ae) Co-authored-by: MonadChains --- Doc/glossary.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index e0dd4fc..9550b98 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -203,6 +203,16 @@ Glossary A list of bytecode instructions can be found in the documentation for :ref:`the dis module `. + callable + A callable is an object that can be called, possibly with a set + of arguments (see :term:`argument`), with the following syntax:: + + callable(argument1, argument2, ...) + + A :term:`function`, and by extension a :term:`method`, is a callable. + An instance of a class that implements the :meth:`~object.__call__` + method is also a callable. + callback A subroutine function which is passed as an argument to be executed at some point in the future. -- cgit v0.12 From 7b1be2ac81615fc89583faa69139b5def5125093 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 11 Oct 2022 19:45:44 -0700 Subject: gh-96130: Rephrase use of "typecheck" verb for clarity (GH-98144) I'm sympathetic to the issue report, especially in case this helps clarify to new users that Python itself does not do type checking at runtime (cherry picked from commit ed6344eed043eaaa41d11c1176c25aa79de64ef4) Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com> --- Doc/library/typing.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 38421e5..11f0543 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -100,7 +100,7 @@ A type alias is defined by assigning the type to the alias. In this example, def scale(scalar: float, vector: Vector) -> Vector: return [scalar * num for num in vector] - # typechecks; a list of floats qualifies as a Vector. + # passes type checking; a list of floats qualifies as a Vector. new_vector = scale(2.0, [1.0, -4.2, 5.4]) Type aliases are useful for simplifying complex type signatures. For example:: @@ -142,10 +142,10 @@ of the original type. This is useful in helping catch logical errors:: def get_user_name(user_id: UserId) -> str: ... - # typechecks + # passes type checking user_a = get_user_name(UserId(42351)) - # does not typecheck; an int is not a UserId + # fails type checking; an int is not a UserId user_b = get_user_name(-1) You may still perform all ``int`` operations on a variable of type ``UserId``, @@ -171,7 +171,7 @@ It is invalid to create a subtype of ``Derived``:: UserId = NewType('UserId', int) - # Fails at runtime and does not typecheck + # Fails at runtime and does not pass type checking class AdminUserId(UserId): pass However, it is possible to create a :class:`NewType` based on a 'derived' ``NewType``:: @@ -458,12 +458,12 @@ value of type :data:`Any` and assign it to any variable:: s = a # OK def foo(item: Any) -> int: - # Typechecks; 'item' could be any type, + # Passes type checking; 'item' could be any type, # and that type might have a 'bar' method item.bar() ... -Notice that no typechecking is performed when assigning a value of type +Notice that no type checking is performed when assigning a value of type :data:`Any` to a more precise type. For example, the static type checker did not report an error when assigning ``a`` to ``s`` even though ``s`` was declared to be of type :class:`str` and receives an :class:`int` value at @@ -495,20 +495,20 @@ reject almost all operations on it, and assigning it to a variable (or using it as a return value) of a more specialized type is a type error. For example:: def hash_a(item: object) -> int: - # Fails; an object does not have a 'magic' method. + # Fails type checking; an object does not have a 'magic' method. item.magic() ... def hash_b(item: Any) -> int: - # Typechecks + # Passes type checking item.magic() ... - # Typechecks, since ints and strs are subclasses of object + # Passes type checking, since ints and strs are subclasses of object hash_a(42) hash_a("foo") - # Typechecks, since Any is compatible with all types + # Passes type checking, since Any is compatible with all types hash_b(42) hash_b("foo") -- cgit v0.12 From e0260d03f78b2db31f056e49d601739e036055b6 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 11 Oct 2022 09:22:04 -0700 Subject: gh-98172: Fix formatting in `except*` docs (GH-98173) (cherry picked from commit 5ecf961640192a2192383aa20e1e93dcdf23c9b6) Co-authored-by: Jelle Zijlstra --- Doc/reference/compound_stmts.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 751c7c2..6a176b7 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -340,17 +340,17 @@ one except* clause, the first that matches it. :: +-+---------------- 1 ---------------- | ValueError: 1 +------------------------------------ - >>> - Any remaining exceptions that were not handled by any except* clause - are re-raised at the end, combined into an exception group along with - all exceptions that were raised from within except* clauses. +Any remaining exceptions that were not handled by any :keyword:`!except*` +clause are re-raised at the end, combined into an exception group along with +all exceptions that were raised from within :keyword:`!except*` clauses. - An except* clause must have a matching type, and this type cannot be a - subclass of :exc:`BaseExceptionGroup`. It is not possible to mix except - and except* in the same :keyword:`try`. :keyword:`break`, - :keyword:`continue` and :keyword:`return` cannot appear in an except* - clause. +An :keyword:`!except*` clause must have a matching type, +and this type cannot be a subclass of :exc:`BaseExceptionGroup`. +It is not possible to mix :keyword:`except` and :keyword:`!except*` +in the same :keyword:`try`. +:keyword:`break`, :keyword:`continue` and :keyword:`return` +cannot appear in an :keyword:`!except*` clause. .. index:: -- cgit v0.12 From e69136baffa315191b3261a8def214b8d1c3858b Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 10 Oct 2022 13:10:04 -0700 Subject: [3.11] gh-88452: Add a warning about non-portability of environments. (GH-98155) (GH-98157) --- Doc/library/venv.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 3fa1046..3bed256 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -85,6 +85,19 @@ Creating virtual environments without there needing to be any reference to its virtual environment in ``PATH``. +.. warning:: Because scripts installed in environments should not expect the + environment to be activated, their shebang lines contain the absolute paths + to their environment's interpreters. Because of this, environments are + inherently non-portable, in the general case. You should always have a + simple means of recreating an environment (for example, if you have a + requirements file ``requirements.txt``, you can invoke ``pip install -r + requirements.txt`` using the environment's ``pip`` to install all of the + packages needed by the environment). If for any reason you need to move the + environment to a new location, you should recreate it at the desired + location and delete the one at the old location. If you move an environment + because you moved a parent directory of it, you should recreate the + environment in its new location. Otherwise, software installed into the + environment may not work as expected. .. _venv-api: -- cgit v0.12 From 1f58d8ce78913774ebb33f9f1f29f4acc2c004f2 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 10 Oct 2022 07:01:05 -0700 Subject: gh-83940: os docs: Improve wording for getenv/getenvb (GH-98113) (cherry picked from commit 187e853690908ca2af19a0701ca7529b43d05df9) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> --- Doc/library/os.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 27b74f9..c667592 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -299,8 +299,8 @@ process and user. .. function:: getenv(key, default=None) - Return the value of the environment variable *key* if it exists, or - *default* if it doesn't. *key*, *default* and the result are str. Note that + Return the value of the environment variable *key* as a string if it exists, or + *default* if it doesn't. *key* is a string. Note that since :func:`getenv` uses :data:`os.environ`, the mapping of :func:`getenv` is similarly also captured on import, and the function may not reflect future environment changes. @@ -314,8 +314,8 @@ process and user. .. function:: getenvb(key, default=None) - Return the value of the environment variable *key* if it exists, or - *default* if it doesn't. *key*, *default* and the result are bytes. Note that + Return the value of the environment variable *key* as bytes if it exists, or + *default* if it doesn't. *key* must be bytes. Note that since :func:`getenvb` uses :data:`os.environb`, the mapping of :func:`getenvb` is similarly also captured on import, and the function may not reflect future environment changes. -- cgit v0.12 From 7b803ec34405f4fba5114d728df223bfd4db5b83 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 10 Oct 2022 01:50:26 -0700 Subject: doc: remove a misleading statement. (GH-98093) (cherry picked from commit 571e23d99157ed7ad67ca2334a396fc9ddbe07ec) Co-authored-by: Julien Palard --- Doc/tutorial/introduction.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst index 33678f5..a64a92f 100644 --- a/Doc/tutorial/introduction.rst +++ b/Doc/tutorial/introduction.rst @@ -70,8 +70,8 @@ the ones with a fractional part (e.g. ``5.0``, ``1.6``) have type :class:`float`. We will see more about numeric types later in the tutorial. Division (``/``) always returns a float. To do :term:`floor division` and -get an integer result (discarding any fractional result) you can use the ``//`` -operator; to calculate the remainder you can use ``%``:: +get an integer result you can use the ``//`` operator; to calculate +the remainder you can use ``%``:: >>> 17 / 3 # classic division returns a float 5.666666666666667 -- cgit v0.12 From 979440e96f0eb434ae4e2df3913ee34e5c9feffd Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sun, 9 Oct 2022 18:03:53 -0700 Subject: Fix types in buffer/memoryview docs (GH-98118) The definition of obj in the `Py_buffer` struct is as a PyObject* https://github.com/python/cpython/blob/ec091bd47e2f968b0d1631b9a8104283a7beeb1b/Include/pybuffer.hGH-L22 PyMemoryView_GET_BASE returns `.obj` - thus its return type should be a PyObject* (or at least a void*). It definitely doesn't return `Py_buffer` (cherry picked from commit c459fedf7cfd5dadf72e088d789c7375b3a6e093) Co-authored-by: da-woods --- Doc/c-api/buffer.rst | 2 +- Doc/c-api/memoryview.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index 05e131d..a04062f 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -99,7 +99,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`. For :term:`contiguous` arrays, the value points to the beginning of the memory block. - .. c:member:: void *obj + .. c:member:: PyObject *obj A new reference to the exporting object. The reference is owned by the consumer and automatically decremented and set to ``NULL`` by diff --git a/Doc/c-api/memoryview.rst b/Doc/c-api/memoryview.rst index 4d94b3f..ebd5c77 100644 --- a/Doc/c-api/memoryview.rst +++ b/Doc/c-api/memoryview.rst @@ -55,7 +55,7 @@ any other object. *mview* **must** be a memoryview instance; this macro doesn't check its type, you must do it yourself or you will risk crashes. -.. c:function:: Py_buffer *PyMemoryView_GET_BASE(PyObject *mview) +.. c:function:: PyObject *PyMemoryView_GET_BASE(PyObject *mview) Return either a pointer to the exporting object that the memoryview is based on or ``NULL`` if the memoryview has been created by one of the functions -- cgit v0.12 From 9f3aaef8544ec4852841c38c4af8616743b8f361 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sun, 9 Oct 2022 18:02:00 -0700 Subject: gh-56133: copyreg docs: Clarify function/constructor parameter (GH-95497) (cherry picked from commit 281a3f18cc2afac0fa92c75e807775971e531711) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> --- Doc/library/copyreg.rst | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/Doc/library/copyreg.rst b/Doc/library/copyreg.rst index dc35965..866b180 100644 --- a/Doc/library/copyreg.rst +++ b/Doc/library/copyreg.rst @@ -25,20 +25,17 @@ Such constructors may be factory functions or class instances. hence not valid as a constructor), raises :exc:`TypeError`. -.. function:: pickle(type, function, constructor=None) +.. function:: pickle(type, function, constructor_ob=None) Declares that *function* should be used as a "reduction" function for objects of type *type*. *function* should return either a string or a tuple - containing two or three elements. + containing two or three elements. See the :attr:`~pickle.Pickler.dispatch_table` + for more details on the interface of *function*. - The optional *constructor* parameter, if provided, is a callable object which - can be used to reconstruct the object when called with the tuple of arguments - returned by *function* at pickling time. A :exc:`TypeError` is raised if the - *constructor* is not callable. + The *constructor_ob* parameter is a legacy feature and is now ignored, but if + passed it must be a callable. - See the :mod:`pickle` module for more details on the interface - expected of *function* and *constructor*. Note that the - :attr:`~pickle.Pickler.dispatch_table` attribute of a pickler + Note that the :attr:`~pickle.Pickler.dispatch_table` attribute of a pickler object or subclass of :class:`pickle.Pickler` can also be used for declaring reduction functions. -- cgit v0.12 From 7460cf43ba25aca63f23d6c4cceec102aa9a271b Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sat, 8 Oct 2022 19:03:25 -0700 Subject: Minor edits to the Descriptor HowTo Guide (GH-24901) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Raymond Hettinger (cherry picked from commit 2d2e01aa4cb72db8dabcd04e87f1e60b3597267e) Co-authored-by: Géry Ogam --- Doc/howto/descriptor.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/Doc/howto/descriptor.rst b/Doc/howto/descriptor.rst index 91a6c31..74710d9 100644 --- a/Doc/howto/descriptor.rst +++ b/Doc/howto/descriptor.rst @@ -847,7 +847,7 @@ afterwards, :meth:`__set_name__` will need to be called manually. ORM example ----------- -The following code is simplified skeleton showing how data descriptors could +The following code is a simplified skeleton showing how data descriptors could be used to implement an `object relational mapping `_. @@ -1535,6 +1535,8 @@ by member descriptors: def __get__(self, obj, objtype=None): 'Emulate member_get() in Objects/descrobject.c' # Also see PyMember_GetOne() in Python/structmember.c + if obj is None: + return self value = obj._slotvalues[self.offset] if value is null: raise AttributeError(self.name) @@ -1563,13 +1565,13 @@ variables: class Type(type): 'Simulate how the type metaclass adds member objects for slots' - def __new__(mcls, clsname, bases, mapping): + def __new__(mcls, clsname, bases, mapping, **kwargs): 'Emulate type_new() in Objects/typeobject.c' # type_new() calls PyTypeReady() which calls add_methods() slot_names = mapping.get('slot_names', []) for offset, name in enumerate(slot_names): mapping[name] = Member(name, clsname, offset) - return type.__new__(mcls, clsname, bases, mapping) + return type.__new__(mcls, clsname, bases, mapping, **kwargs) The :meth:`object.__new__` method takes care of creating instances that have slots instead of an instance dictionary. Here is a rough simulation in pure @@ -1580,7 +1582,7 @@ Python: class Object: 'Simulate how object.__new__() allocates memory for __slots__' - def __new__(cls, *args): + def __new__(cls, *args, **kwargs): 'Emulate object_new() in Objects/typeobject.c' inst = super().__new__(cls) if hasattr(cls, 'slot_names'): @@ -1593,7 +1595,7 @@ Python: cls = type(self) if hasattr(cls, 'slot_names') and name not in cls.slot_names: raise AttributeError( - f'{type(self).__name__!r} object has no attribute {name!r}' + f'{cls.__name__!r} object has no attribute {name!r}' ) super().__setattr__(name, value) @@ -1602,7 +1604,7 @@ Python: cls = type(self) if hasattr(cls, 'slot_names') and name not in cls.slot_names: raise AttributeError( - f'{type(self).__name__!r} object has no attribute {name!r}' + f'{cls.__name__!r} object has no attribute {name!r}' ) super().__delattr__(name) -- cgit v0.12 From 9b6afbee2e8b3eea80d7b73497cfc8ef6dc276dc Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sat, 8 Oct 2022 00:01:27 -0700 Subject: gh-97913 Docs: Add walrus operator to the index (GH-97921) * Add walrus operator to the index * Add named expression to the index Co-authored-by: Mariatta Wijaya * Fix indentation and add missing newline Co-authored-by: Ezio Melotti Co-authored-by: Mariatta Wijaya Co-authored-by: Ezio Melotti (cherry picked from commit 296313002fde56f52d6c81f17d7ba5c2eb57d098) Co-authored-by: Hugo van Kemenade --- Doc/reference/expressions.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 6bf21a7..8ed520d 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -1720,6 +1720,12 @@ returns a boolean value regardless of the type of its argument (for example, ``not 'foo'`` produces ``False`` rather than ``''``.) +.. index:: + single: := (colon equals) + single: assignment expression + single: walrus operator + single: named expression + Assignment expressions ====================== -- cgit v0.12 From dfae46c6652b33861a24fcadb20a1d4ff881d652 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Fri, 7 Oct 2022 22:07:06 -0700 Subject: gh-97822: Fix http.server documentation reference to test() function (GH-98027) Co-authored-by: Jelle Zijlstra (cherry picked from commit 6b485629d2e3e232460db7da3f8b18b67d4f4da8) Co-authored-by: JasonYZ --- Doc/library/http.server.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index 48f952d..81b6bf5 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -392,8 +392,8 @@ provides three different variants: contents of the file are output. If the file's MIME type starts with ``text/`` the file is opened in text mode; otherwise binary mode is used. - For example usage, see the implementation of the :func:`test` function - invocation in the :mod:`http.server` module. + For example usage, see the implementation of the ``test`` function + in :source:`Lib/http/server.py`. .. versionchanged:: 3.7 Support of the ``'If-Modified-Since'`` header. -- cgit v0.12 From e32c7364c6a390a21944697d4a042f5716cf656e Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Fri, 7 Oct 2022 16:05:52 -0700 Subject: gh-61105: Add default param, note on using cookiejar subclass (GH-95427) (cherry picked from commit 5eaf4d610147a3b9adc91a55790096d05bbe01d4) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> --- Doc/library/http.cookiejar.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Doc/library/http.cookiejar.rst b/Doc/library/http.cookiejar.rst index 53b3087..e6c5981 100644 --- a/Doc/library/http.cookiejar.rst +++ b/Doc/library/http.cookiejar.rst @@ -61,7 +61,7 @@ The following classes are provided: responsible for storing and retrieving cookies from a file or database. -.. class:: FileCookieJar(filename, delayload=None, policy=None) +.. class:: FileCookieJar(filename=None, delayload=None, policy=None) *policy* is an object implementing the :class:`CookiePolicy` interface. For the other arguments, see the documentation for the corresponding attributes. @@ -71,6 +71,8 @@ The following classes are provided: :meth:`load` or :meth:`revert` method is called. Subclasses of this class are documented in section :ref:`file-cookie-jar-classes`. + This should not be initialized directly – use its subclasses below instead. + .. versionchanged:: 3.8 The filename parameter supports a :term:`path-like object`. @@ -317,7 +319,7 @@ FileCookieJar subclasses and co-operation with web browsers The following :class:`CookieJar` subclasses are provided for reading and writing. -.. class:: MozillaCookieJar(filename, delayload=None, policy=None) +.. class:: MozillaCookieJar(filename=None, delayload=None, policy=None) A :class:`FileCookieJar` that can load from and save cookies to disk in the Mozilla ``cookies.txt`` file format (which is also used by the Lynx and Netscape @@ -338,7 +340,7 @@ writing. Mozilla. -.. class:: LWPCookieJar(filename, delayload=None, policy=None) +.. class:: LWPCookieJar(filename=None, delayload=None, policy=None) A :class:`FileCookieJar` that can load from and save cookies to disk in format compatible with the libwww-perl library's ``Set-Cookie3`` file format. This is -- cgit v0.12 From c634cd2d8c5e8035734f2e04904e218f17a84c74 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Fri, 7 Oct 2022 13:53:15 -0700 Subject: [3.11] gh-91708: Revert params note in urllib.parse.urlparse table (GH-96699) (#98052) Revert params note in urllib.parse.urlparse table (cherry picked from commit eed80458e8e776d15fa862da71dcce58c47e2ca7) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> --- Doc/library/urllib.parse.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/urllib.parse.rst b/Doc/library/urllib.parse.rst index 1478b34..96b3965 100644 --- a/Doc/library/urllib.parse.rst +++ b/Doc/library/urllib.parse.rst @@ -113,7 +113,8 @@ or on combining URL components into a URL string. +------------------+-------+-------------------------+------------------------+ | :attr:`path` | 2 | Hierarchical path | empty string | +------------------+-------+-------------------------+------------------------+ - | :attr:`params` | 3 | No longer used | always an empty string | + | :attr:`params` | 3 | Parameters for last | empty string | + | | | path element | | +------------------+-------+-------------------------+------------------------+ | :attr:`query` | 4 | Query component | empty string | +------------------+-------+-------------------------+------------------------+ -- cgit v0.12 From 517ffe0a29f765a7dcd670f1afc493b999c8c13a Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Fri, 7 Oct 2022 12:02:51 -0700 Subject: [3.11] gh-96959: Update HTTP links which are redirected to HTTPS (GH-98039) (#98049) (cherry picked from commit c81c64ca58822156beba79dfd3035bf2a5b7354e) Co-authored-by: 180909 <734461790@qq.com> --- Doc/faq/library.rst | 2 +- Doc/includes/tzinfo_examples.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst index 8167bf2..8c4baec 100644 --- a/Doc/faq/library.rst +++ b/Doc/faq/library.rst @@ -609,7 +609,7 @@ use ``p.read(n)``. substituted for standard input and output. You will have to use pseudo ttys ("ptys") instead of pipes. Or you can use a Python interface to Don Libes' "expect" library. A Python extension that interfaces to expect is called - "expy" and available from http://expectpy.sourceforge.net. A pure Python + "expy" and available from https://expectpy.sourceforge.net. A pure Python solution that works like expect is `pexpect `_. diff --git a/Doc/includes/tzinfo_examples.py b/Doc/includes/tzinfo_examples.py index 9b9e32a..1fa6e61 100644 --- a/Doc/includes/tzinfo_examples.py +++ b/Doc/includes/tzinfo_examples.py @@ -71,7 +71,7 @@ def first_sunday_on_or_after(dt): # DST start and end times. For a complete and up-to-date set of DST rules # and timezone definitions, visit the Olson Database (or try pytz): # http://www.twinsun.com/tz/tz-link.htm -# http://sourceforge.net/projects/pytz/ (might not be up-to-date) +# https://sourceforge.net/projects/pytz/ (might not be up-to-date) # # In the US, since 2007, DST starts at 2am (standard time) on the second # Sunday in March, which is the first Sunday on or after Mar 8. -- cgit v0.12 From 40527c2b1918b7045f9b8b235b4b9e54f9cce91a Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Fri, 7 Oct 2022 11:21:01 -0700 Subject: gh-64921: Clarify wording for open()'s newline arg (GH-96171) (cherry picked from commit 4a74e6ab3885e7906cc5e0b15addc7779bc76249) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> --- Doc/library/functions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 4986d0a..635cffd 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1267,8 +1267,8 @@ are always available. They are listed here in alphabetical order. .. _open-newline-parameter: - *newline* controls how :term:`universal newlines` mode works (it only - applies to text mode). It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and + *newline* determines how to parse newline characters from the stream. + It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``. It works as follows: * When reading input from the stream, if *newline* is ``None``, universal -- cgit v0.12 From a8a33e16e3e2ee52a46c787971c830a9e036816a Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Fri, 7 Oct 2022 07:10:46 -0700 Subject: gh-71316: Update dis documentation to include changes to jump arguments (GH-95798) (cherry picked from commit 6592a62ec2939323b895c85780da7fd73a640da3) Co-authored-by: Christopher Chianelli --- Doc/library/dis.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index f7989ea..d292592 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -30,6 +30,10 @@ interpreter. Use 2 bytes for each instruction. Previously the number of bytes varied by instruction. + .. versionchanged:: 3.10 + The argument of jump, exception handling and loop instructions is now + the instruction offset rather than the byte offset. + .. versionchanged:: 3.11 Some instructions are accompanied by one or more inline cache entries, which take the form of :opcode:`CACHE` instructions. These instructions -- cgit v0.12 From 3652b26ba165122c75a305e0c4e1a2d340cb51eb Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Fri, 7 Oct 2022 01:46:31 -0700 Subject: Misc updates to the itertools recipes and tests (GH-98018) (cherry picked from commit e500cc04517bd65668f2e203c1e37b0cc5b1cf1b) Co-authored-by: Raymond Hettinger --- Doc/library/itertools.rst | 42 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 38 insertions(+), 4 deletions(-) diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst index 2b4d7d5..9de09ed 100644 --- a/Doc/library/itertools.rst +++ b/Doc/library/itertools.rst @@ -775,10 +775,7 @@ which incur interpreter overhead. return sum(map(pred, iterable)) def pad_none(iterable): - """Returns the sequence elements and then returns None indefinitely. - - Useful for emulating the behavior of the built-in map() function. - """ + "Returns the sequence elements and then returns None indefinitely." return chain(iterable, repeat(None)) def ncycles(iterable, n): @@ -860,6 +857,13 @@ which incur interpreter overhead. else: raise ValueError('Expected fill, strict, or ignore') + def batched(iterable, n): + "Batch data into lists of length n. The last batch may be shorter." + # batched('ABCDEFG', 3) --> ABC DEF G + it = iter(iterable) + while (batch := list(islice(it, n))): + yield batch + def triplewise(iterable): "Return overlapping triplets from an iterable" # triplewise('ABCDEFG') -> ABC BCD CDE DEF EFG @@ -1232,6 +1236,36 @@ which incur interpreter overhead. >>> list(grouper('abcdefg', n=3, incomplete='ignore')) [('a', 'b', 'c'), ('d', 'e', 'f')] + >>> list(batched('ABCDEFG', 3)) + [['A', 'B', 'C'], ['D', 'E', 'F'], ['G']] + >>> list(batched('ABCDEF', 3)) + [['A', 'B', 'C'], ['D', 'E', 'F']] + >>> list(batched('ABCDE', 3)) + [['A', 'B', 'C'], ['D', 'E']] + >>> list(batched('ABCD', 3)) + [['A', 'B', 'C'], ['D']] + >>> list(batched('ABC', 3)) + [['A', 'B', 'C']] + >>> list(batched('AB', 3)) + [['A', 'B']] + >>> list(batched('A', 3)) + [['A']] + >>> list(batched('', 3)) + [] + >>> list(batched('ABCDEFG', 2)) + [['A', 'B'], ['C', 'D'], ['E', 'F'], ['G']] + >>> list(batched('ABCDEFG', 1)) + [['A'], ['B'], ['C'], ['D'], ['E'], ['F'], ['G']] + >>> list(batched('ABCDEFG', 0)) + [] + >>> list(batched('ABCDEFG', -1)) + Traceback (most recent call last): + ... + ValueError: Stop argument for islice() must be None or an integer: 0 <= x <= sys.maxsize. + >>> s = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' + >>> all(list(flatten(batched(s[:n], 5))) == list(s[:n]) for n in range(len(s))) + True + >>> list(triplewise('ABCDEFG')) [('A', 'B', 'C'), ('B', 'C', 'D'), ('C', 'D', 'E'), ('D', 'E', 'F'), ('E', 'F', 'G')] -- cgit v0.12 From 47e920d9c00cca73c0fca7b644dc5be1e91462a5 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 6 Oct 2022 17:56:24 -0700 Subject: [3.11] Remove extra spaces in custom openSSL documentation. (GH-93568) (#98007) Remove extra spaces in custom openSSL documentation. (GH-93568) (cherry picked from commit 4875433682ffec2694647ac43f1b21f5ad73fd25) Co-authored-by: Xiao Chen Co-authored-by: Xiao Chen --- Doc/using/unix.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Doc/using/unix.rst b/Doc/using/unix.rst index 3f9f136..061cfa5 100644 --- a/Doc/using/unix.rst +++ b/Doc/using/unix.rst @@ -158,16 +158,16 @@ Custom OpenSSL .. code-block:: shell-session $ curl -O https://www.openssl.org/source/openssl-VERSION.tar.gz - $ tar xzf openssl-VERSION - $ pushd openssl-VERSION - $ ./config \ - --prefix=/usr/local/custom-openssl \ - --libdir=lib \ - --openssldir=/etc/ssl - $ make -j1 depend - $ make -j8 - $ make install_sw - $ popd + $ tar xzf openssl-VERSION + $ pushd openssl-VERSION + $ ./config \ + --prefix=/usr/local/custom-openssl \ + --libdir=lib \ + --openssldir=/etc/ssl + $ make -j1 depend + $ make -j8 + $ make install_sw + $ popd 3. Build Python with custom OpenSSL (see the configure `--with-openssl` and `--with-openssl-rpath` options) -- cgit v0.12 From d994584d6f91ec5e64f6dbfb28c9379f7ca5db44 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 6 Oct 2022 14:10:06 -0700 Subject: [3.11] gh-97850: Remove the open issues section from the import reference (GH-97935) (GH-97994) Remove the open issues section from the import reference Tracking in https://github.com/python/cpython/issues/97850 instead. (cherry picked from commit f8edc6ff531bb98858185857513371f14519ed1d) Co-authored-by: Brett Cannon Automerge-Triggered-By: GH:brettcannon --- Doc/reference/import.rst | 19 ------------------- 1 file changed, 19 deletions(-) diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index 1e6b08f..0d8c029 100644 --- a/Doc/reference/import.rst +++ b/Doc/reference/import.rst @@ -1019,25 +1019,6 @@ and ``__main__.__spec__`` is set accordingly, they're still considered to populate the ``__main__`` namespace, and not during normal import. -Open issues -=========== - -XXX It would be really nice to have a diagram. - -XXX * (import_machinery.rst) how about a section devoted just to the -attributes of modules and packages, perhaps expanding upon or supplanting the -related entries in the data model reference page? - -XXX runpy, pkgutil, et al in the library manual should all get "See Also" -links at the top pointing to the new import system section. - -XXX Add more explanation regarding the different ways in which -``__main__`` is initialized? - -XXX Add more info on ``__main__`` quirks/pitfalls (i.e. copy from -:pep:`395`). - - References ========== -- cgit v0.12 From 35b94b7ce2ffa9c82a7c8a14b0b9a65927670279 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 6 Oct 2022 14:01:27 -0700 Subject: [3.11] Docs: pin sphinx-lint (GH-97992) (GH-97993) --- Doc/requirements.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Doc/requirements.txt b/Doc/requirements.txt index f8a7f9d..960ac54 100644 --- a/Doc/requirements.txt +++ b/Doc/requirements.txt @@ -7,7 +7,10 @@ sphinx==4.5.0 blurb -sphinx-lint<1 +# sphinx-lint 0.6.2 yields many default role errors due to the new regular +# expression used for default role detection, so we don't use the version +# until the errors are fixed. +sphinx-lint==0.6.1 # The theme used by the documentation is stored separately, so we need # to install that as well. -- cgit v0.12 From a3df8d714125f262c2dbe422c09fe914aa8bcfc1 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Thu, 6 Oct 2022 13:47:33 -0700 Subject: [3.11] Backport effc25f 3.11 (#97991) * Add Pynche's move to the What's new in 3.11 (#97974) * Add Pynche's move to the What's new in 3.11 * Update Doc/whatsnew/3.11.rst Co-authored-by: Ezio Melotti Co-authored-by: Ezio Melotti (cherry picked from commit effc25f7f25ae1ac053415addc584b050c022dcb) * [3.11] Add Pynche's move to the What's new in 3.11 (GH-97974) * Add Pynche's move to the What's new in 3.11 * Update Doc/whatsnew/3.11.rst Co-authored-by: Ezio Melotti Co-authored-by: Ezio Melotti . (cherry picked from commit effc25f7f25ae1ac053415addc584b050c022dcb) Co-authored-by: Barry Warsaw --- Doc/whatsnew/3.11.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 9353446..a13cbe6 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -1596,6 +1596,9 @@ Removed (and corresponding ``EXPERIMENTAL_ISOLATED_SUBINTERPRETERS``) have been removed. +* Pynche --- The Pythonically Natural Color and Hue Editor --- has been moved out + of ``Tools/scripts`` and is `being developed independently + `_ from the Python source tree. Porting to Python 3.11 ====================== -- cgit v0.12 From cc10a8e81c55bf54affe561475473de53e05f007 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 6 Oct 2022 12:32:39 -0700 Subject: gh-86482: Document assignment expression need for ()s (GH-23291) Co-authored-by: Jelle Zijlstra (cherry picked from commit 2b5f1360ead9aa72ae00de59edfd6c229d13933f) Co-authored-by: Terry Jan Reedy --- Doc/reference/expressions.rst | 7 +++++++ .../Core and Builtins/2020-11-15-02-08-43.bpo-42316.LqdkWK.rst | 1 + 2 files changed, 8 insertions(+) create mode 100644 Misc/NEWS.d/next/Core and Builtins/2020-11-15-02-08-43.bpo-42316.LqdkWK.rst diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 8ed520d..60136cd 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -1751,6 +1751,13 @@ Or, when processing a file stream in chunks: while chunk := file.read(9000): process(chunk) +Assignment expressions must be surrounded by parentheses when used +as sub-expressions in slicing, conditional, lambda, +keyword-argument, and comprehension-if expressions +and in ``assert`` and ``with`` statements. +In all other places where they can be used, parentheses are not required, +including in ``if`` and ``while`` statements. + .. versionadded:: 3.8 See :pep:`572` for more details about assignment expressions. diff --git a/Misc/NEWS.d/next/Core and Builtins/2020-11-15-02-08-43.bpo-42316.LqdkWK.rst b/Misc/NEWS.d/next/Core and Builtins/2020-11-15-02-08-43.bpo-42316.LqdkWK.rst new file mode 100644 index 0000000..ea99780 --- /dev/null +++ b/Misc/NEWS.d/next/Core and Builtins/2020-11-15-02-08-43.bpo-42316.LqdkWK.rst @@ -0,0 +1 @@ +Document some places where an assignment expression needs parentheses. -- cgit v0.12 From bf1de26199e55c5320d512372f77654101937e0f Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 6 Oct 2022 10:49:29 -0700 Subject: [3.11] gh-93738: Disallow pre-v3 syntax in the C domain (GH-97962) (#97976) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Also, disable using invalid sphinx-lint 0.6.2. (cherry picked from commit f612565bd32d4ab0945798da775eea070f08b6fe) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Łukasz Langa --- Doc/c-api/unicode.rst | 12 ++++++------ Doc/conf.py | 10 ---------- Doc/extending/newtypes.rst | 14 +++++++------- Doc/extending/newtypes_tutorial.rst | 2 +- Doc/howto/isolating-extensions.rst | 2 +- Doc/requirements.txt | 2 +- Doc/whatsnew/2.2.rst | 2 +- Doc/whatsnew/2.5.rst | 2 +- 8 files changed, 18 insertions(+), 28 deletions(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index eb99013..eda0132 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -17,8 +17,8 @@ of Unicode characters while staying memory efficient. There are special cases for strings where all code points are below 128, 256, or 65536; otherwise, code points must be below 1114112 (which is the full Unicode range). -:c:type:`Py_UNICODE*` and UTF-8 representations are created on demand and cached -in the Unicode object. The :c:type:`Py_UNICODE*` representation is deprecated +:c:expr:`Py_UNICODE*` and UTF-8 representations are created on demand and cached +in the Unicode object. The :c:expr:`Py_UNICODE*` representation is deprecated and inefficient. Due to the transition between the old APIs and the new APIs, Unicode objects @@ -30,7 +30,7 @@ can internally be in two states depending on how they were created: * "legacy" Unicode objects have been created through one of the deprecated APIs (typically :c:func:`PyUnicode_FromUnicode`) and only bear the - :c:type:`Py_UNICODE*` representation; you will have to call + :c:expr:`Py_UNICODE*` representation; you will have to call :c:func:`PyUnicode_READY` on them before calling any other API. .. note:: @@ -236,7 +236,7 @@ access to internal read-only data of Unicode objects: returned buffer is always terminated with an extra null code point. It may also contain embedded null code points, which would cause the string to be truncated when used in most C functions. The ``AS_DATA`` form - casts the pointer to :c:type:`const char *`. The *o* argument has to be + casts the pointer to :c:expr:`const char *`. The *o* argument has to be a Unicode object (not checked). .. versionchanged:: 3.3 @@ -714,7 +714,7 @@ Extension modules can continue using them, as they will not be removed in Python Return a read-only pointer to the Unicode object's internal :c:type:`Py_UNICODE` buffer, or ``NULL`` on error. This will create the - :c:type:`Py_UNICODE*` representation of the object if it is not yet + :c:expr:`Py_UNICODE*` representation of the object if it is not yet available. The buffer is always terminated with an extra null code point. Note that the resulting :c:type:`Py_UNICODE` string may also contain embedded null code points, which would cause the string to be truncated when @@ -730,7 +730,7 @@ Extension modules can continue using them, as they will not be removed in Python Like :c:func:`PyUnicode_AsUnicode`, but also saves the :c:func:`Py_UNICODE` array length (excluding the extra null terminator) in *size*. - Note that the resulting :c:type:`Py_UNICODE*` string + Note that the resulting :c:expr:`Py_UNICODE*` string may contain embedded null code points, which would cause the string to be truncated when used in most C functions. diff --git a/Doc/conf.py b/Doc/conf.py index 2e670e5..fd4ee2d 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -234,13 +234,3 @@ linkcheck_ignore = [r'https://bugs.python.org/(issue)?\d+'] # Relative filename of the data files refcount_file = 'data/refcounts.dat' stable_abi_file = 'data/stable_abi.dat' - -# Sphinx 2 and Sphinx 3 compatibility -# ----------------------------------- - -# bpo-40204: Allow Sphinx 2 syntax in the C domain -c_allow_pre_v3 = True - -# bpo-40204: Disable warnings on Sphinx 2 syntax of the C domain since the -# documentation is built with -W (warnings treated as errors). -c_warn_on_allowed_pre_v3 = False diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst index c7c434e..5ba6383 100644 --- a/Doc/extending/newtypes.rst +++ b/Doc/extending/newtypes.rst @@ -207,8 +207,8 @@ a special case, for which the new value passed to the handler is ``NULL``. Python supports two pairs of attribute handlers; a type that supports attributes only needs to implement the functions for one pair. The difference is that one -pair takes the name of the attribute as a :c:type:`char\*`, while the other -accepts a :c:type:`PyObject\*`. Each type can use whichever pair makes more +pair takes the name of the attribute as a :c:expr:`char\*`, while the other +accepts a :c:expr:`PyObject*`. Each type can use whichever pair makes more sense for the implementation's convenience. :: getattrfunc tp_getattr; /* char * version */ @@ -219,7 +219,7 @@ sense for the implementation's convenience. :: If accessing attributes of an object is always a simple operation (this will be explained shortly), there are generic implementations which can be used to -provide the :c:type:`PyObject\*` version of the attribute management functions. +provide the :c:expr:`PyObject*` version of the attribute management functions. The actual need for type-specific attribute handlers almost completely disappeared starting with Python 2.2, though there are many examples which have not been updated to use some of the new generic mechanism that is available. @@ -339,9 +339,9 @@ of ``NULL`` is required. Type-specific Attribute Management ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -For simplicity, only the :c:type:`char\*` version will be demonstrated here; the -type of the name parameter is the only difference between the :c:type:`char\*` -and :c:type:`PyObject\*` flavors of the interface. This example effectively does +For simplicity, only the :c:expr:`char\*` version will be demonstrated here; the +type of the name parameter is the only difference between the :c:expr:`char\*` +and :c:expr:`PyObject*` flavors of the interface. This example effectively does the same thing as the generic example above, but does not use the generic support added in Python 2.2. It explains how the handler functions are called, so that if you do need to extend their functionality, you'll understand @@ -572,7 +572,7 @@ performance-critical objects (such as numbers). For an object to be weakly referencable, the extension type must do two things: -#. Include a :c:type:`PyObject\*` field in the C object structure dedicated to +#. Include a :c:expr:`PyObject*` field in the C object structure dedicated to the weak reference mechanism. The object's constructor should leave it ``NULL`` (which is automatic when using the default :c:member:`~PyTypeObject.tp_alloc`). diff --git a/Doc/extending/newtypes_tutorial.rst b/Doc/extending/newtypes_tutorial.rst index 34c25d1..5d4a3f0 100644 --- a/Doc/extending/newtypes_tutorial.rst +++ b/Doc/extending/newtypes_tutorial.rst @@ -24,7 +24,7 @@ The Basics ========== The :term:`CPython` runtime sees all Python objects as variables of type -:c:type:`PyObject\*`, which serves as a "base type" for all Python objects. +:c:expr:`PyObject*`, which serves as a "base type" for all Python objects. The :c:type:`PyObject` structure itself only contains the object's :term:`reference count` and a pointer to the object's "type object". This is where the action is; the type object determines which (C) functions diff --git a/Doc/howto/isolating-extensions.rst b/Doc/howto/isolating-extensions.rst index 8ee7e5e..2657b4e 100644 --- a/Doc/howto/isolating-extensions.rst +++ b/Doc/howto/isolating-extensions.rst @@ -411,7 +411,7 @@ that subclass, which may be defined in different module than yours. pass For a method to get its "defining class", it must use the -:c:data:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS` +:data:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS` :c:type:`calling convention ` and the corresponding :c:type:`PyCMethod` signature:: diff --git a/Doc/requirements.txt b/Doc/requirements.txt index 960ac54..be05873 100644 --- a/Doc/requirements.txt +++ b/Doc/requirements.txt @@ -10,7 +10,7 @@ blurb # sphinx-lint 0.6.2 yields many default role errors due to the new regular # expression used for default role detection, so we don't use the version # until the errors are fixed. -sphinx-lint==0.6.1 +sphinx-lint<1,!=0.6.2 # The theme used by the documentation is stored separately, so we need # to install that as well. diff --git a/Doc/whatsnew/2.2.rst b/Doc/whatsnew/2.2.rst index 9355c1b..b3d6ff6 100644 --- a/Doc/whatsnew/2.2.rst +++ b/Doc/whatsnew/2.2.rst @@ -1102,7 +1102,7 @@ code, none of the changes described here will affect you very much. * A different argument parsing function, :c:func:`PyArg_UnpackTuple`, has been added that's simpler and presumably faster. Instead of specifying a format string, the caller simply gives the minimum and maximum number of arguments - expected, and a set of pointers to :c:type:`PyObject\*` variables that will be + expected, and a set of pointers to :c:expr:`PyObject*` variables that will be filled in with argument values. * Two new flags :const:`METH_NOARGS` and :const:`METH_O` are available in method diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst index 6c21682..880fbaa 100644 --- a/Doc/whatsnew/2.5.rst +++ b/Doc/whatsnew/2.5.rst @@ -1725,7 +1725,7 @@ attribute of the function object to change this:: ``ctypes.pythonapi`` object. This object does *not* release the global interpreter lock before calling a function, because the lock must be held when calling into the interpreter's code. There's a :class:`py_object()` type -constructor that will create a :c:type:`PyObject \*` pointer. A simple usage:: +constructor that will create a :c:expr:`PyObject *` pointer. A simple usage:: import ctypes -- cgit v0.12 From 508ef0f343e556e7d1edb2efd4de962a76a5336a Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 5 Oct 2022 17:21:55 -0700 Subject: [3.11] gh-95691: Doc BufferedWriter and BufferedReader (GH-95703) (#97947) gh-95691: Doc BufferedWriter and BufferedReader (GH-95703) (cherry picked from commit 0d68879104dfb392d31e52e25dcb0661801a0249) Co-authored-by: 180909 <734461790@qq.com> Co-authored-by: 180909 <734461790@qq.com> --- Doc/library/io.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 97a7064..03c90ad 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -270,7 +270,7 @@ to provide an interface to files in the machine's file system. The :class:`BufferedIOBase` ABC extends :class:`IOBase`. It deals with buffering on a raw binary stream (:class:`RawIOBase`). Its subclasses, :class:`BufferedWriter`, :class:`BufferedReader`, and :class:`BufferedRWPair` -buffer raw binary streams that are readable, writable, and both readable and writable, +buffer raw binary streams that are writable, readable, and both readable and writable, respectively. :class:`BufferedRandom` provides a buffered interface to seekable streams. Another :class:`BufferedIOBase` subclass, :class:`BytesIO`, is a stream of in-memory bytes. -- cgit v0.12 From bf50f10a6dc1f82de10ce4105e30300d7028fa7e Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 5 Oct 2022 16:54:21 -0700 Subject: GH-88968: Add notes about socket ownership transfers (GH-97936) (cherry picked from commit 74ea204634f8eb4745afd5cb75c3fe7749cf38b5) Co-authored-by: Guido van Rossum --- Doc/library/asyncio-eventloop.rst | 24 ++++++++++++++++++++++++ Doc/library/asyncio-stream.rst | 24 ++++++++++++++++++++++++ 2 files changed, 48 insertions(+) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index c1dddbf..de2ecdc 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -456,6 +456,12 @@ Opening network connections *happy_eyeballs_delay*, *interleave* and *local_addr* should be specified. + .. note:: + + The *sock* argument transfers ownership of the socket to the + transport created. To close the socket, call the transport's + :meth:`~asyncio.BaseTransport.close` method. + * *local_addr*, if given, is a ``(local_host, local_port)`` tuple used to bind the socket locally. The *local_host* and *local_port* are looked up using ``getaddrinfo()``, similarly to *host* and *port*. @@ -554,6 +560,12 @@ Opening network connections transport. If specified, *local_addr* and *remote_addr* should be omitted (must be :const:`None`). + .. note:: + + The *sock* argument transfers ownership of the socket to the + transport created. To close the socket, call the transport's + :meth:`~asyncio.BaseTransport.close` method. + See :ref:`UDP echo client protocol ` and :ref:`UDP echo server protocol ` examples. @@ -665,6 +677,12 @@ Creating network servers * *sock* can optionally be specified in order to use a preexisting socket object. If specified, *host* and *port* must not be specified. + .. note:: + + The *sock* argument transfers ownership of the socket to the + server created. To close the socket, call the server's + :meth:`~asyncio.Server.close` method. + * *backlog* is the maximum number of queued connections passed to :meth:`~socket.socket.listen` (defaults to 100). @@ -766,6 +784,12 @@ Creating network servers * *sock* is a preexisting socket object returned from :meth:`socket.accept `. + .. note:: + + The *sock* argument transfers ownership of the socket to the + transport created. To close the socket, call the transport's + :meth:`~asyncio.BaseTransport.close` method. + * *ssl* can be set to an :class:`~ssl.SSLContext` to enable SSL over the accepted connections. diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index 9b46867..ce88d70 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -67,6 +67,12 @@ and work with streams: The rest of the arguments are passed directly to :meth:`loop.create_connection`. + .. note:: + + The *sock* argument transfers ownership of the socket to the + :class:`StreamWriter` created. To close the socket, call its + :meth:`~asyncio.StreamWriter.close` method. + .. versionchanged:: 3.7 Added the *ssl_handshake_timeout* parameter. @@ -103,6 +109,12 @@ and work with streams: The rest of the arguments are passed directly to :meth:`loop.create_server`. + .. note:: + + The *sock* argument transfers ownership of the socket to the + server created. To close the socket, call the server's + :meth:`~asyncio.Server.close` method. + .. versionchanged:: 3.7 Added the *ssl_handshake_timeout* and *start_serving* parameters. @@ -123,6 +135,12 @@ and work with streams: See also the documentation of :meth:`loop.create_unix_connection`. + .. note:: + + The *sock* argument transfers ownership of the socket to the + :class:`StreamWriter` created. To close the socket, call its + :meth:`~asyncio.StreamWriter.close` method. + .. availability:: Unix. .. versionchanged:: 3.7 @@ -143,6 +161,12 @@ and work with streams: See also the documentation of :meth:`loop.create_unix_server`. + .. note:: + + The *sock* argument transfers ownership of the socket to the + server created. To close the socket, call the server's + :meth:`~asyncio.Server.close` method. + .. availability:: Unix. .. versionchanged:: 3.7 -- cgit v0.12 From 2af22d220576124951997dfa0039be4c4b6b9cbe Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 5 Oct 2022 15:03:18 -0700 Subject: [3.11] gh-96197: Fix expression when :func:`sys.breakpointhook is missing (gh-96293) (#96294) (cherry picked from commit 47d406ffc4946b023e38322c5235bec25f068481) Co-authored-by: Dong-hee Na --- Doc/library/functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 635cffd..2393698 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -165,7 +165,7 @@ are always available. They are listed here in alphabetical order. :func:`sys.breakpointhook` can be set to some other function and :func:`breakpoint` will automatically call that, allowing you to drop into the debugger of choice. - If :func:`sys.breakpointhook` is not available to be called, this function will + If :func:`sys.breakpointhook` is not accessible, this function will raise :exc:`RuntimeError`. .. audit-event:: builtins.breakpoint breakpointhook breakpoint -- cgit v0.12 From 82f663b7f096cdfbb2c6e3293794852546912f6c Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 5 Oct 2022 14:50:46 -0700 Subject: [3.11] gh-97654: Add auto exception chaining example to tutorial (GH-97703) (#97885) gh-97654: Add auto exception chaining example to tutorial (GH-97703) Add auto exception chaining example to tutorial (cherry picked from commit 395b66a0ae5237eec195ca97daaaf8563706ed34) Co-authored-by: Shahriar Heidrich --- Doc/tutorial/errors.rst | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst index 57919e3..67bb195 100644 --- a/Doc/tutorial/errors.rst +++ b/Doc/tutorial/errors.rst @@ -284,8 +284,27 @@ re-raise the exception:: Exception Chaining ================== -The :keyword:`raise` statement allows an optional :keyword:`from` which enables -chaining exceptions. For example:: +If an unhandled exception occurs inside an :keyword:`except` section, it will +have the exception being handled attached to it and included in the error +message:: + + >>> try: + ... open("database.sqlite") + ... except OSError: + ... raise RuntimeError("unable to handle error") + ... + Traceback (most recent call last): + File "", line 2, in + FileNotFoundError: [Errno 2] No such file or directory: 'database.sqlite' + + During handling of the above exception, another exception occurred: + + Traceback (most recent call last): + File "", line 4, in + RuntimeError: unable to handle error + +To indicate that an exception is a direct consequence of another, the +:keyword:`raise` statement allows an optional :keyword:`from` clause:: # exc must be exception instance or None. raise RuntimeError from exc @@ -311,9 +330,8 @@ This can be useful when you are transforming exceptions. For example:: File "", line 4, in RuntimeError: Failed to open database -Exception chaining happens automatically when an exception is raised inside an -:keyword:`except` or :keyword:`finally` section. This can be -disabled by using ``from None`` idiom: +It also allows disabling automatic exception chaining using the ``from None`` +idiom:: >>> try: ... open('database.sqlite') -- cgit v0.12 From e48d6dfbcd8eadf4fe21b286d413aae1aaeb4df6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Langa?= Date: Wed, 5 Oct 2022 14:11:12 -0700 Subject: [3.11] gh-93738: Documentation C syntax (:c:type: -> :c:expr:) (GH-97768) (#97924) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit :c:type:`` -> :c:expr:`` Co-authored-by: Łukasz Langa (cherry picked from commit 0031e62973801d34a9e19ab7bb199e9668e32d7b) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/c-api/arg.rst | 72 +++++++++++++------------- Doc/c-api/capsule.rst | 2 +- Doc/c-api/complex.rst | 4 +- Doc/c-api/conversion.rst | 4 +- Doc/c-api/dict.rst | 4 +- Doc/c-api/file.rst | 2 +- Doc/c-api/float.rst | 16 +++--- Doc/c-api/init.rst | 28 +++++------ Doc/c-api/intro.rst | 4 +- Doc/c-api/long.rst | 42 ++++++++-------- Doc/c-api/marshal.rst | 12 ++--- Doc/c-api/memory.rst | 12 ++--- Doc/c-api/sys.rst | 6 +-- Doc/c-api/unicode.rst | 24 ++++----- Doc/extending/extending.rst | 8 +-- Doc/extending/newtypes.rst | 4 +- Doc/library/ctypes.rst | 120 ++++++++++++++++++++++---------------------- Doc/library/posix.rst | 4 +- Doc/library/socket.rst | 2 +- Doc/library/stdtypes.rst | 2 +- Doc/library/struct.rst | 42 ++++++++-------- Doc/reference/datamodel.rst | 2 +- Doc/whatsnew/2.2.rst | 2 +- Doc/whatsnew/2.3.rst | 4 +- Doc/whatsnew/2.4.rst | 8 +-- Doc/whatsnew/2.5.rst | 20 ++++---- Doc/whatsnew/2.6.rst | 2 +- Doc/whatsnew/2.7.rst | 4 +- Doc/whatsnew/3.3.rst | 2 +- Doc/whatsnew/3.7.rst | 14 +++--- Doc/whatsnew/3.9.rst | 2 +- Misc/NEWS.d/3.5.0a1.rst | 2 +- Misc/NEWS.d/3.9.0a1.rst | 2 +- Misc/NEWS.d/3.9.0b1.rst | 2 +- 34 files changed, 240 insertions(+), 240 deletions(-) diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index 926e524..b4c48aa 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -194,10 +194,10 @@ which disallows mutable objects such as :class:`bytearray`. It only works for encoded data without embedded NUL bytes. This format requires two arguments. The first is only used as input, and - must be a :c:type:`const char*` which points to the name of an encoding as a + must be a :c:expr:`const char*` which points to the name of an encoding as a NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used. An exception is raised if the named encoding is not known to Python. The - second argument must be a :c:type:`char**`; the value of the pointer it + second argument must be a :c:expr:`char**`; the value of the pointer it references will be set to a buffer with the contents of the argument text. The text will be encoded in the encoding specified by the first argument. @@ -217,10 +217,10 @@ which disallows mutable objects such as :class:`bytearray`. characters. It requires three arguments. The first is only used as input, and must be a - :c:type:`const char*` which points to the name of an encoding as a + :c:expr:`const char*` which points to the name of an encoding as a NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used. An exception is raised if the named encoding is not known to Python. The - second argument must be a :c:type:`char**`; the value of the pointer it + second argument must be a :c:expr:`char**`; the value of the pointer it references will be set to a buffer with the contents of the argument text. The text will be encoded in the encoding specified by the first argument. The third argument must be a pointer to an integer; the referenced integer @@ -252,38 +252,38 @@ Numbers ``b`` (:class:`int`) [unsigned char] Convert a nonnegative Python integer to an unsigned tiny int, stored in a C - :c:type:`unsigned char`. + :c:expr:`unsigned char`. ``B`` (:class:`int`) [unsigned char] Convert a Python integer to a tiny int without overflow checking, stored in a C - :c:type:`unsigned char`. + :c:expr:`unsigned char`. ``h`` (:class:`int`) [short int] - Convert a Python integer to a C :c:type:`short int`. + Convert a Python integer to a C :c:expr:`short int`. ``H`` (:class:`int`) [unsigned short int] - Convert a Python integer to a C :c:type:`unsigned short int`, without overflow + Convert a Python integer to a C :c:expr:`unsigned short int`, without overflow checking. ``i`` (:class:`int`) [int] - Convert a Python integer to a plain C :c:type:`int`. + Convert a Python integer to a plain C :c:expr:`int`. ``I`` (:class:`int`) [unsigned int] - Convert a Python integer to a C :c:type:`unsigned int`, without overflow + Convert a Python integer to a C :c:expr:`unsigned int`, without overflow checking. ``l`` (:class:`int`) [long int] - Convert a Python integer to a C :c:type:`long int`. + Convert a Python integer to a C :c:expr:`long int`. ``k`` (:class:`int`) [unsigned long] - Convert a Python integer to a C :c:type:`unsigned long` without + Convert a Python integer to a C :c:expr:`unsigned long` without overflow checking. ``L`` (:class:`int`) [long long] - Convert a Python integer to a C :c:type:`long long`. + Convert a Python integer to a C :c:expr:`long long`. ``K`` (:class:`int`) [unsigned long long] - Convert a Python integer to a C :c:type:`unsigned long long` + Convert a Python integer to a C :c:expr:`unsigned long long` without overflow checking. ``n`` (:class:`int`) [:c:type:`Py_ssize_t`] @@ -291,20 +291,20 @@ Numbers ``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char] Convert a Python byte, represented as a :class:`bytes` or - :class:`bytearray` object of length 1, to a C :c:type:`char`. + :class:`bytearray` object of length 1, to a C :c:expr:`char`. .. versionchanged:: 3.3 Allow :class:`bytearray` objects. ``C`` (:class:`str` of length 1) [int] Convert a Python character, represented as a :class:`str` object of - length 1, to a C :c:type:`int`. + length 1, to a C :c:expr:`int`. ``f`` (:class:`float`) [float] - Convert a Python floating point number to a C :c:type:`float`. + Convert a Python floating point number to a C :c:expr:`float`. ``d`` (:class:`float`) [double] - Convert a Python floating point number to a C :c:type:`double`. + Convert a Python floating point number to a C :c:expr:`double`. ``D`` (:class:`complex`) [Py_complex] Convert a Python complex number to a C :c:type:`Py_complex` structure. @@ -329,13 +329,13 @@ Other objects ``O&`` (object) [*converter*, *anything*] Convert a Python object to a C variable through a *converter* function. This takes two arguments: the first is a function, the second is the address of a C - variable (of arbitrary type), converted to :c:type:`void *`. The *converter* + variable (of arbitrary type), converted to :c:expr:`void *`. The *converter* function in turn is called as follows:: status = converter(object, address); where *object* is the Python object to be converted and *address* is the - :c:type:`void*` argument that was passed to the :c:func:`PyArg_Parse\*` function. + :c:expr:`void*` argument that was passed to the ``PyArg_Parse*`` function. The returned *status* should be ``1`` for a successful conversion and ``0`` if the conversion has failed. When the conversion fails, the *converter* function should raise an exception and leave the content of *address* unmodified. @@ -568,7 +568,7 @@ Building values Same as ``s#``. ``u`` (:class:`str`) [const wchar_t \*] - Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or UCS-4) + Convert a null-terminated :c:expr:`wchar_t` buffer of Unicode (UTF-16 or UCS-4) data to a Python Unicode object. If the Unicode buffer pointer is ``NULL``, ``None`` is returned. @@ -584,51 +584,51 @@ Building values Same as ``s#``. ``i`` (:class:`int`) [int] - Convert a plain C :c:type:`int` to a Python integer object. + Convert a plain C :c:expr:`int` to a Python integer object. ``b`` (:class:`int`) [char] - Convert a plain C :c:type:`char` to a Python integer object. + Convert a plain C :c:expr:`char` to a Python integer object. ``h`` (:class:`int`) [short int] - Convert a plain C :c:type:`short int` to a Python integer object. + Convert a plain C :c:expr:`short int` to a Python integer object. ``l`` (:class:`int`) [long int] - Convert a C :c:type:`long int` to a Python integer object. + Convert a C :c:expr:`long int` to a Python integer object. ``B`` (:class:`int`) [unsigned char] - Convert a C :c:type:`unsigned char` to a Python integer object. + Convert a C :c:expr:`unsigned char` to a Python integer object. ``H`` (:class:`int`) [unsigned short int] - Convert a C :c:type:`unsigned short int` to a Python integer object. + Convert a C :c:expr:`unsigned short int` to a Python integer object. ``I`` (:class:`int`) [unsigned int] - Convert a C :c:type:`unsigned int` to a Python integer object. + Convert a C :c:expr:`unsigned int` to a Python integer object. ``k`` (:class:`int`) [unsigned long] - Convert a C :c:type:`unsigned long` to a Python integer object. + Convert a C :c:expr:`unsigned long` to a Python integer object. ``L`` (:class:`int`) [long long] - Convert a C :c:type:`long long` to a Python integer object. + Convert a C :c:expr:`long long` to a Python integer object. ``K`` (:class:`int`) [unsigned long long] - Convert a C :c:type:`unsigned long long` to a Python integer object. + Convert a C :c:expr:`unsigned long long` to a Python integer object. ``n`` (:class:`int`) [:c:type:`Py_ssize_t`] Convert a C :c:type:`Py_ssize_t` to a Python integer. ``c`` (:class:`bytes` of length 1) [char] - Convert a C :c:type:`int` representing a byte to a Python :class:`bytes` object of + Convert a C :c:expr:`int` representing a byte to a Python :class:`bytes` object of length 1. ``C`` (:class:`str` of length 1) [int] - Convert a C :c:type:`int` representing a character to Python :class:`str` + Convert a C :c:expr:`int` representing a character to Python :class:`str` object of length 1. ``d`` (:class:`float`) [double] - Convert a C :c:type:`double` to a Python floating point number. + Convert a C :c:expr:`double` to a Python floating point number. ``f`` (:class:`float`) [float] - Convert a C :c:type:`float` to a Python floating point number. + Convert a C :c:expr:`float` to a Python floating point number. ``D`` (:class:`complex`) [Py_complex \*] Convert a C :c:type:`Py_complex` structure to a Python complex number. @@ -651,7 +651,7 @@ Building values ``O&`` (object) [*converter*, *anything*] Convert *anything* to a Python object through a *converter* function. The - function is called with *anything* (which should be compatible with :c:type:`void*`) + function is called with *anything* (which should be compatible with :c:expr:`void*`) as its argument and should return a "new" Python object, or ``NULL`` if an error occurred. diff --git a/Doc/c-api/capsule.rst b/Doc/c-api/capsule.rst index 2c4cfc4..1c8f432 100644 --- a/Doc/c-api/capsule.rst +++ b/Doc/c-api/capsule.rst @@ -15,7 +15,7 @@ Refer to :ref:`using-capsules` for more information on using these objects. .. c:type:: PyCapsule This subtype of :c:type:`PyObject` represents an opaque value, useful for C - extension modules who need to pass an opaque value (as a :c:type:`void*` + extension modules who need to pass an opaque value (as a :c:expr:`void*` pointer) through Python code to other C code. It is often used to make a C function pointer defined in one module available to other modules, so the regular import mechanism can be used to access C APIs defined in dynamically diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst index c258946..9228ce8 100644 --- a/Doc/c-api/complex.rst +++ b/Doc/c-api/complex.rst @@ -115,12 +115,12 @@ Complex Numbers as Python Objects .. c:function:: double PyComplex_RealAsDouble(PyObject *op) - Return the real part of *op* as a C :c:type:`double`. + Return the real part of *op* as a C :c:expr:`double`. .. c:function:: double PyComplex_ImagAsDouble(PyObject *op) - Return the imaginary part of *op* as a C :c:type:`double`. + Return the imaginary part of *op* as a C :c:expr:`double`. .. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op) diff --git a/Doc/c-api/conversion.rst b/Doc/c-api/conversion.rst index 7b4cc1c..9b9c4ff 100644 --- a/Doc/c-api/conversion.rst +++ b/Doc/c-api/conversion.rst @@ -49,7 +49,7 @@ The following functions provide locale-independent string to number conversions. .. c:function:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception) - Convert a string ``s`` to a :c:type:`double`, raising a Python + Convert a string ``s`` to a :c:expr:`double`, raising a Python exception on failure. The set of accepted strings corresponds to the set of strings accepted by Python's :func:`float` constructor, except that ``s`` must not have leading or trailing whitespace. @@ -83,7 +83,7 @@ The following functions provide locale-independent string to number conversions. .. c:function:: char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype) - Convert a :c:type:`double` *val* to a string using supplied + Convert a :c:expr:`double` *val* to a string using supplied *format_code*, *precision*, and *flags*. *format_code* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``, diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index d257c9b..5b0cd93 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -73,7 +73,7 @@ Dictionary Objects .. index:: single: PyUnicode_FromString() Insert *val* into the dictionary *p* using *key* as a key. *key* should - be a :c:type:`const char*`. The key object is created using + be a :c:expr:`const char*`. The key object is created using ``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on failure. This function *does not* steal a reference to *val*. @@ -118,7 +118,7 @@ Dictionary Objects .. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key) This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a - :c:type:`const char*`, rather than a :c:type:`PyObject*`. + :c:expr:`const char*`, rather than a :c:expr:`PyObject*`. Note that exceptions which occur while calling :meth:`__hash__` and :meth:`__eq__` methods and creating a temporary string object diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst index ed3735a..0d42177 100644 --- a/Doc/c-api/file.rst +++ b/Doc/c-api/file.rst @@ -38,7 +38,7 @@ the :mod:`io` APIs instead. .. c:function:: int PyObject_AsFileDescriptor(PyObject *p) - Return the file descriptor associated with *p* as an :c:type:`int`. If the + Return the file descriptor associated with *p* as an :c:expr:`int`. If the object is an integer, its value is returned. If not, the object's :meth:`~io.IOBase.fileno` method is called if it exists; the method must return an integer, which is returned as the file descriptor diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst index b306caf..023b12c 100644 --- a/Doc/c-api/float.rst +++ b/Doc/c-api/float.rst @@ -44,7 +44,7 @@ Floating Point Objects .. c:function:: double PyFloat_AsDouble(PyObject *pyfloat) - Return a C :c:type:`double` representation of the contents of *pyfloat*. If + Return a C :c:expr:`double` representation of the contents of *pyfloat*. If *pyfloat* is not a Python floating point object but has a :meth:`__float__` method, this method will first be called to convert *pyfloat* into a float. If ``__float__()`` is not defined then it falls back to :meth:`__index__`. @@ -57,7 +57,7 @@ Floating Point Objects .. c:function:: double PyFloat_AS_DOUBLE(PyObject *pyfloat) - Return a C :c:type:`double` representation of the contents of *pyfloat*, but + Return a C :c:expr:`double` representation of the contents of *pyfloat*, but without error checking. @@ -70,12 +70,12 @@ Floating Point Objects .. c:function:: double PyFloat_GetMax() - Return the maximum representable finite float *DBL_MAX* as C :c:type:`double`. + Return the maximum representable finite float *DBL_MAX* as C :c:expr:`double`. .. c:function:: double PyFloat_GetMin() - Return the minimum normalized positive float *DBL_MIN* as C :c:type:`double`. + Return the minimum normalized positive float *DBL_MIN* as C :c:expr:`double`. Pack and Unpack functions @@ -83,8 +83,8 @@ Pack and Unpack functions The pack and unpack functions provide an efficient platform-independent way to store floating-point values as byte strings. The Pack routines produce a bytes -string from a C :c:type:`double`, and the Unpack routines produce a C -:c:type:`double` from such a bytes string. The suffix (2, 4 or 8) specifies the +string from a C :c:expr:`double`, and the Unpack routines produce a C +:c:expr:`double` from such a bytes string. The suffix (2, 4 or 8) specifies the number of bytes in the bytes string. On platforms that appear to use IEEE 754 formats these functions work by @@ -107,7 +107,7 @@ Pack functions -------------- The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an -:c:type:`int` argument, non-zero if you want the bytes string in little-endian +:c:expr:`int` argument, non-zero if you want the bytes string in little-endian format (exponent last, at ``p+1``, ``p+3``, or ``p+6`` ``p+7``), zero if you want big-endian format (exponent first, at *p*). The :c:data:`PY_BIG_ENDIAN` constant can be used to use the native endian: it is equal to ``1`` on big @@ -138,7 +138,7 @@ Unpack functions ---------------- The unpack routines read 2, 4 or 8 bytes, starting at *p*. *le* is an -:c:type:`int` argument, non-zero if the bytes string is in little-endian format +:c:expr:`int` argument, non-zero if the bytes string is in little-endian format (exponent last, at ``p+1``, ``p+3`` or ``p+6`` and ``p+7``), zero if big-endian (exponent first, at *p*). The :c:data:`PY_BIG_ENDIAN` constant can be used to use the native endian: it is equal to ``1`` on big endian processor, or ``0`` diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index d495495..8573826 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -376,7 +376,7 @@ Process-wide parameters interpreter will change the contents of this storage. Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a - :c:type:`wchar_*` string. + :c:expr:`wchar_*` string. .. deprecated:: 3.11 @@ -527,7 +527,7 @@ Process-wide parameters if required after calling :c:func:`Py_Initialize`. Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a - :c:type:`wchar_*` string. + :c:expr:`wchar_*` string. The path argument is copied internally, so the caller may free it after the call completes. @@ -642,7 +642,7 @@ Process-wide parameters directory (``"."``). Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a - :c:type:`wchar_*` string. + :c:expr:`wchar_*` string. See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv` members of the :ref:`Python Initialization Configuration `. @@ -678,7 +678,7 @@ Process-wide parameters :option:`-I`. Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a - :c:type:`wchar_*` string. + :c:expr:`wchar_*` string. See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv` members of the :ref:`Python Initialization Configuration `. @@ -704,7 +704,7 @@ Process-wide parameters this storage. Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a - :c:type:`wchar_*` string. + :c:expr:`wchar_*` string. .. deprecated:: 3.11 @@ -1291,8 +1291,8 @@ All of the following functions must be called after :c:func:`Py_Initialize`. exception (if any) for the thread is cleared. This raises no exceptions. .. versionchanged:: 3.7 - The type of the *id* parameter changed from :c:type:`long` to - :c:type:`unsigned long`. + The type of the *id* parameter changed from :c:expr:`long` to + :c:expr:`unsigned long`. .. c:function:: void PyEval_AcquireThread(PyThreadState *tstate) @@ -1730,7 +1730,7 @@ The Python interpreter provides low-level support for thread-local storage (TLS) which wraps the underlying native TLS implementation to support the Python-level thread local storage API (:class:`threading.local`). The CPython C level APIs are similar to those offered by pthreads and Windows: -use a thread key and functions to associate a :c:type:`void*` value per +use a thread key and functions to associate a :c:expr:`void*` value per thread. The GIL does *not* need to be held when calling these functions; they supply @@ -1741,8 +1741,8 @@ you need to include :file:`pythread.h` to use thread-local storage. .. note:: None of these API functions handle memory management on behalf of the - :c:type:`void*` values. You need to allocate and deallocate them yourself. - If the :c:type:`void*` values happen to be :c:type:`PyObject*`, these + :c:expr:`void*` values. You need to allocate and deallocate them yourself. + If the :c:expr:`void*` values happen to be :c:expr:`PyObject*`, these functions don't do refcount operations on them either. .. _thread-specific-storage-api: @@ -1752,7 +1752,7 @@ Thread Specific Storage (TSS) API TSS API is introduced to supersede the use of the existing TLS API within the CPython interpreter. This API uses a new type :c:type:`Py_tss_t` instead of -:c:type:`int` to represent thread keys. +:c:expr:`int` to represent thread keys. .. versionadded:: 3.7 @@ -1838,14 +1838,14 @@ undefined if the given :c:type:`Py_tss_t` has not been initialized by .. c:function:: int PyThread_tss_set(Py_tss_t *key, void *value) - Return a zero value to indicate successfully associating a :c:type:`void*` + Return a zero value to indicate successfully associating a :c:expr:`void*` value with a TSS key in the current thread. Each thread has a distinct - mapping of the key to a :c:type:`void*` value. + mapping of the key to a :c:expr:`void*` value. .. c:function:: void* PyThread_tss_get(Py_tss_t *key) - Return the :c:type:`void*` value associated with a TSS key in the current + Return the :c:expr:`void*` value associated with a TSS key in the current thread. This returns ``NULL`` if no value is associated with the key in the current thread. diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index d9fcd0d..63069f4 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -530,8 +530,8 @@ Types ----- There are few other data types that play a significant role in the Python/C -API; most are simple C types such as :c:type:`int`, :c:type:`long`, -:c:type:`double` and :c:type:`char*`. A few structure types are used to +API; most are simple C types such as :c:expr:`int`, :c:expr:`long`, +:c:expr:`double` and :c:expr:`char*`. A few structure types are used to describe static tables used to list the functions exported by a module or the data attributes of a new object type, and another is used to describe the value of a complex number. These will be discussed together with the functions that diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index 620344e..bd3d731 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -47,7 +47,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. .. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v) - Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long`, or + Return a new :c:type:`PyLongObject` object from a C :c:expr:`unsigned long`, or ``NULL`` on failure. @@ -65,13 +65,13 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. .. c:function:: PyObject* PyLong_FromLongLong(long long v) - Return a new :c:type:`PyLongObject` object from a C :c:type:`long long`, or ``NULL`` + Return a new :c:type:`PyLongObject` object from a C :c:expr:`long long`, or ``NULL`` on failure. .. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned long long v) - Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long long`, + Return a new :c:type:`PyLongObject` object from a C :c:expr:`unsigned long long`, or ``NULL`` on failure. @@ -115,12 +115,12 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. single: LONG_MAX single: OverflowError (built-in exception) - Return a C :c:type:`long` representation of *obj*. If *obj* is not an + Return a C :c:expr:`long` representation of *obj*. If *obj* is not an instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method (if present) to convert it to a :c:type:`PyLongObject`. Raise :exc:`OverflowError` if the value of *obj* is out of range for a - :c:type:`long`. + :c:expr:`long`. Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. @@ -133,7 +133,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. .. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow) - Return a C :c:type:`long` representation of *obj*. If *obj* is not an + Return a C :c:expr:`long` representation of *obj*. If *obj* is not an instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method (if present) to convert it to a :c:type:`PyLongObject`. @@ -156,12 +156,12 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. .. index:: single: OverflowError (built-in exception) - Return a C :c:type:`long long` representation of *obj*. If *obj* is not an + Return a C :c:expr:`long long` representation of *obj*. If *obj* is not an instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method (if present) to convert it to a :c:type:`PyLongObject`. Raise :exc:`OverflowError` if the value of *obj* is out of range for a - :c:type:`long long`. + :c:expr:`long long`. Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. @@ -174,7 +174,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. .. c:function:: long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow) - Return a C :c:type:`long long` representation of *obj*. If *obj* is not an + Return a C :c:expr:`long long` representation of *obj*. If *obj* is not an instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method (if present) to convert it to a :c:type:`PyLongObject`. @@ -215,11 +215,11 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. single: ULONG_MAX single: OverflowError (built-in exception) - Return a C :c:type:`unsigned long` representation of *pylong*. *pylong* + Return a C :c:expr:`unsigned long` representation of *pylong*. *pylong* must be an instance of :c:type:`PyLongObject`. Raise :exc:`OverflowError` if the value of *pylong* is out of range for a - :c:type:`unsigned long`. + :c:expr:`unsigned long`. Returns ``(unsigned long)-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. @@ -246,11 +246,11 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. .. index:: single: OverflowError (built-in exception) - Return a C :c:type:`unsigned long long` representation of *pylong*. *pylong* + Return a C :c:expr:`unsigned long long` representation of *pylong*. *pylong* must be an instance of :c:type:`PyLongObject`. Raise :exc:`OverflowError` if the value of *pylong* is out of range for an - :c:type:`unsigned long long`. + :c:expr:`unsigned long long`. Returns ``(unsigned long long)-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. @@ -261,11 +261,11 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. .. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *obj) - Return a C :c:type:`unsigned long` representation of *obj*. If *obj* is not + Return a C :c:expr:`unsigned long` representation of *obj*. If *obj* is not an instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method (if present) to convert it to a :c:type:`PyLongObject`. - If the value of *obj* is out of range for an :c:type:`unsigned long`, + If the value of *obj* is out of range for an :c:expr:`unsigned long`, return the reduction of that value modulo ``ULONG_MAX + 1``. Returns ``(unsigned long)-1`` on error. Use :c:func:`PyErr_Occurred` to @@ -280,12 +280,12 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. .. c:function:: unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj) - Return a C :c:type:`unsigned long long` representation of *obj*. If *obj* + Return a C :c:expr:`unsigned long long` representation of *obj*. If *obj* is not an instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method (if present) to convert it to a :c:type:`PyLongObject`. - If the value of *obj* is out of range for an :c:type:`unsigned long long`, + If the value of *obj* is out of range for an :c:expr:`unsigned long long`, return the reduction of that value modulo ``ULLONG_MAX + 1``. Returns ``(unsigned long long)-1`` on error. Use :c:func:`PyErr_Occurred` @@ -300,20 +300,20 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. .. c:function:: double PyLong_AsDouble(PyObject *pylong) - Return a C :c:type:`double` representation of *pylong*. *pylong* must be + Return a C :c:expr:`double` representation of *pylong*. *pylong* must be an instance of :c:type:`PyLongObject`. Raise :exc:`OverflowError` if the value of *pylong* is out of range for a - :c:type:`double`. + :c:expr:`double`. Returns ``-1.0`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. .. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong) - Convert a Python integer *pylong* to a C :c:type:`void` pointer. + Convert a Python integer *pylong* to a C :c:expr:`void` pointer. If *pylong* cannot be converted, an :exc:`OverflowError` will be raised. This - is only assured to produce a usable :c:type:`void` pointer for values created + is only assured to produce a usable :c:expr:`void` pointer for values created with :c:func:`PyLong_FromVoidPtr`. Returns ``NULL`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. diff --git a/Doc/c-api/marshal.rst b/Doc/c-api/marshal.rst index 7bb0dad..bf8373a 100644 --- a/Doc/c-api/marshal.rst +++ b/Doc/c-api/marshal.rst @@ -21,9 +21,9 @@ unmarshalling. Version 2 uses a binary format for floating point numbers. .. c:function:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version) - Marshal a :c:type:`long` integer, *value*, to *file*. This will only write + Marshal a :c:expr:`long` integer, *value*, to *file*. This will only write the least-significant 32 bits of *value*; regardless of the size of the - native :c:type:`long` type. *version* indicates the file format. + native :c:expr:`long` type. *version* indicates the file format. .. c:function:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version) @@ -43,9 +43,9 @@ The following functions allow marshalled values to be read back in. .. c:function:: long PyMarshal_ReadLongFromFile(FILE *file) - Return a C :c:type:`long` from the data stream in a :c:type:`FILE*` opened + Return a C :c:expr:`long` from the data stream in a :c:expr:`FILE*` opened for reading. Only a 32-bit value can be read in using this function, - regardless of the native size of :c:type:`long`. + regardless of the native size of :c:expr:`long`. On error, sets the appropriate exception (:exc:`EOFError`) and returns ``-1``. @@ -53,9 +53,9 @@ The following functions allow marshalled values to be read back in. .. c:function:: int PyMarshal_ReadShortFromFile(FILE *file) - Return a C :c:type:`short` from the data stream in a :c:type:`FILE*` opened + Return a C :c:expr:`short` from the data stream in a :c:expr:`FILE*` opened for reading. Only a 16-bit value can be read in using this function, - regardless of the native size of :c:type:`short`. + regardless of the native size of :c:expr:`short`. On error, sets the appropriate exception (:exc:`EOFError`) and returns ``-1``. diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst index 335ea00..f314563 100644 --- a/Doc/c-api/memory.rst +++ b/Doc/c-api/memory.rst @@ -141,7 +141,7 @@ zero bytes. .. c:function:: void* PyMem_RawMalloc(size_t n) - Allocates *n* bytes and returns a pointer of type :c:type:`void*` to the + Allocates *n* bytes and returns a pointer of type :c:expr:`void*` to the allocated memory, or ``NULL`` if the request fails. Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as @@ -152,7 +152,7 @@ zero bytes. .. c:function:: void* PyMem_RawCalloc(size_t nelem, size_t elsize) Allocates *nelem* elements each whose size in bytes is *elsize* and returns - a pointer of type :c:type:`void*` to the allocated memory, or ``NULL`` if the + a pointer of type :c:expr:`void*` to the allocated memory, or ``NULL`` if the request fails. The memory is initialized to zeros. Requesting zero elements or elements of size zero bytes returns a distinct @@ -212,7 +212,7 @@ The :ref:`default memory allocator ` uses the .. c:function:: void* PyMem_Malloc(size_t n) - Allocates *n* bytes and returns a pointer of type :c:type:`void*` to the + Allocates *n* bytes and returns a pointer of type :c:expr:`void*` to the allocated memory, or ``NULL`` if the request fails. Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as @@ -223,7 +223,7 @@ The :ref:`default memory allocator ` uses the .. c:function:: void* PyMem_Calloc(size_t nelem, size_t elsize) Allocates *nelem* elements each whose size in bytes is *elsize* and returns - a pointer of type :c:type:`void*` to the allocated memory, or ``NULL`` if the + a pointer of type :c:expr:`void*` to the allocated memory, or ``NULL`` if the request fails. The memory is initialized to zeros. Requesting zero elements or elements of size zero bytes returns a distinct @@ -320,7 +320,7 @@ The :ref:`default object allocator ` uses the .. c:function:: void* PyObject_Malloc(size_t n) - Allocates *n* bytes and returns a pointer of type :c:type:`void*` to the + Allocates *n* bytes and returns a pointer of type :c:expr:`void*` to the allocated memory, or ``NULL`` if the request fails. Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as @@ -331,7 +331,7 @@ The :ref:`default object allocator ` uses the .. c:function:: void* PyObject_Calloc(size_t nelem, size_t elsize) Allocates *nelem* elements each whose size in bytes is *elsize* and returns - a pointer of type :c:type:`void*` to the allocated memory, or ``NULL`` if the + a pointer of type :c:expr:`void*` to the allocated memory, or ``NULL`` if the request fails. The memory is initialized to zeros. Requesting zero elements or elements of size zero bytes returns a distinct diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst index 7b71467..517b57b 100644 --- a/Doc/c-api/sys.rst +++ b/Doc/c-api/sys.rst @@ -105,7 +105,7 @@ Operating System Utilities Return the current signal handler for signal *i*. This is a thin wrapper around either :c:func:`sigaction` or :c:func:`signal`. Do not call those functions - directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:type:`void + directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:expr:`void (\*)(int)`. @@ -114,7 +114,7 @@ Operating System Utilities Set the signal handler for signal *i* to be *h*; return the old signal handler. This is a thin wrapper around either :c:func:`sigaction` or :c:func:`signal`. Do not call those functions directly! :c:type:`PyOS_sighandler_t` is a typedef - alias for :c:type:`void (\*)(int)`. + alias for :c:expr:`void (\*)(int)`. .. c:function:: wchar_t* Py_DecodeLocale(const char* arg, size_t *size) @@ -377,7 +377,7 @@ accessible to C code. They all work with the current interpreter thread's silently abort the operation by raising an error subclassed from :class:`Exception` (other errors will not be silenced). - The hook function is of type :c:type:`int (*)(const char *event, PyObject + The hook function is of type :c:expr:`int (*)(const char *event, PyObject *args, void *userData)`, where *args* is guaranteed to be a :c:type:`PyTupleObject`. The hook function is always called with the GIL held by the Python interpreter that raised the event. diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index eda0132..e1c1e06 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -58,7 +58,7 @@ Python: .. c:type:: Py_UNICODE - This is a typedef of :c:type:`wchar_t`, which is a 16-bit type or 32-bit type + This is a typedef of :c:expr:`wchar_t`, which is a 16-bit type or 32-bit type depending on the platform. .. versionchanged:: 3.3 @@ -935,11 +935,11 @@ conversion function: wchar_t Support """"""""""""""" -:c:type:`wchar_t` support for platforms which support it: +:c:expr:`wchar_t` support for platforms which support it: .. c:function:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size) - Create a Unicode object from the :c:type:`wchar_t` buffer *w* of the given *size*. + Create a Unicode object from the :c:expr:`wchar_t` buffer *w* of the given *size*. Passing ``-1`` as the *size* indicates that the function must itself compute the length, using wcslen. Return ``NULL`` on failure. @@ -947,13 +947,13 @@ wchar_t Support .. c:function:: Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *w, Py_ssize_t size) - Copy the Unicode object contents into the :c:type:`wchar_t` buffer *w*. At most - *size* :c:type:`wchar_t` characters are copied (excluding a possibly trailing - null termination character). Return the number of :c:type:`wchar_t` characters - copied or ``-1`` in case of an error. Note that the resulting :c:type:`wchar_t*` + Copy the Unicode object contents into the :c:expr:`wchar_t` buffer *w*. At most + *size* :c:expr:`wchar_t` characters are copied (excluding a possibly trailing + null termination character). Return the number of :c:expr:`wchar_t` characters + copied or ``-1`` in case of an error. Note that the resulting :c:expr:`wchar_t*` string may or may not be null-terminated. It is the responsibility of the caller - to make sure that the :c:type:`wchar_t*` string is null-terminated in case this is - required by the application. Also, note that the :c:type:`wchar_t*` string + to make sure that the :c:expr:`wchar_t*` string is null-terminated in case this is + required by the application. Also, note that the :c:expr:`wchar_t*` string might contain null characters, which would cause the string to be truncated when used with most C functions. @@ -963,9 +963,9 @@ wchar_t Support Convert the Unicode object to a wide character string. The output string always ends with a null character. If *size* is not ``NULL``, write the number of wide characters (excluding the trailing null termination character) into - *\*size*. Note that the resulting :c:type:`wchar_t` string might contain + *\*size*. Note that the resulting :c:expr:`wchar_t` string might contain null characters, which would cause the string to be truncated when used with - most C functions. If *size* is ``NULL`` and the :c:type:`wchar_t*` string + most C functions. If *size* is ``NULL`` and the :c:expr:`wchar_t*` string contains null characters a :exc:`ValueError` is raised. Returns a buffer allocated by :c:func:`PyMem_Alloc` (use @@ -976,7 +976,7 @@ wchar_t Support .. versionadded:: 3.2 .. versionchanged:: 3.7 - Raises a :exc:`ValueError` if *size* is ``NULL`` and the :c:type:`wchar_t*` + Raises a :exc:`ValueError` if *size* is ``NULL`` and the :c:expr:`wchar_t*` string contains null characters. diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index 2e3362b..890b19a 100644 --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -298,7 +298,7 @@ In this case, it will return an integer object. (Yes, even integers are objects on the heap in Python!) If you have a C function that returns no useful argument (a function returning -:c:type:`void`), the corresponding Python function must return ``None``. You +:c:expr:`void`), the corresponding Python function must return ``None``. You need this idiom to do so (which is implemented by the :c:macro:`Py_RETURN_NONE` macro):: @@ -1171,7 +1171,7 @@ other extension modules must be exported in a different way. Python provides a special mechanism to pass C-level information (pointers) from one extension module to another one: Capsules. A Capsule is a Python data type -which stores a pointer (:c:type:`void \*`). Capsules can only be created and +which stores a pointer (:c:expr:`void \*`). Capsules can only be created and accessed via their C API, but they can be passed around like any other Python object. In particular, they can be assigned to a name in an extension module's namespace. Other extension modules can then import this module, retrieve the @@ -1185,7 +1185,7 @@ different ways between the module providing the code and the client modules. Whichever method you choose, it's important to name your Capsules properly. The function :c:func:`PyCapsule_New` takes a name parameter -(:c:type:`const char \*`); you're permitted to pass in a ``NULL`` name, but +(:c:expr:`const char \*`); you're permitted to pass in a ``NULL`` name, but we strongly encourage you to specify a name. Properly named Capsules provide a degree of runtime type-safety; there is no feasible way to tell one unnamed Capsule from another. @@ -1203,7 +1203,7 @@ of certainty that the Capsule they load contains the correct C API. The following example demonstrates an approach that puts most of the burden on the writer of the exporting module, which is appropriate for commonly used library modules. It stores all C API pointers (just one in the example!) in an -array of :c:type:`void` pointers which becomes the value of a Capsule. The header +array of :c:expr:`void` pointers which becomes the value of a Capsule. The header file corresponding to the module provides a macro that takes care of importing the module and retrieving its C API pointers; client modules only have to call this macro before accessing the C API. diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst index 5ba6383..21ef1f0 100644 --- a/Doc/extending/newtypes.rst +++ b/Doc/extending/newtypes.rst @@ -208,7 +208,7 @@ a special case, for which the new value passed to the handler is ``NULL``. Python supports two pairs of attribute handlers; a type that supports attributes only needs to implement the functions for one pair. The difference is that one pair takes the name of the attribute as a :c:expr:`char\*`, while the other -accepts a :c:expr:`PyObject*`. Each type can use whichever pair makes more +accepts a :c:type:`PyObject\*`. Each type can use whichever pair makes more sense for the implementation's convenience. :: getattrfunc tp_getattr; /* char * version */ @@ -341,7 +341,7 @@ Type-specific Attribute Management For simplicity, only the :c:expr:`char\*` version will be demonstrated here; the type of the name parameter is the only difference between the :c:expr:`char\*` -and :c:expr:`PyObject*` flavors of the interface. This example effectively does +and :c:type:`PyObject\*` flavors of the interface. This example effectively does the same thing as the generic example above, but does not use the generic support added in Python 2.2. It explains how the handler functions are called, so that if you do need to extend their functionality, you'll understand diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 52950b5..f501375 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -197,9 +197,9 @@ calls). ``None``, integers, bytes objects and (unicode) strings are the only native Python objects that can directly be used as parameters in these function calls. ``None`` is passed as a C ``NULL`` pointer, bytes objects and strings are passed -as pointer to the memory block that contains their data (:c:type:`char *` or -:c:type:`wchar_t *`). Python integers are passed as the platforms default C -:c:type:`int` type, their value is masked to fit into the C type. +as pointer to the memory block that contains their data (:c:expr:`char *` or +:c:expr:`wchar_t *`). Python integers are passed as the platforms default C +:c:expr:`int` type, their value is masked to fit into the C type. Before we move on calling functions with other parameter types, we have to learn more about :mod:`ctypes` data types. @@ -215,49 +215,49 @@ Fundamental data types +----------------------+------------------------------------------+----------------------------+ | ctypes type | C type | Python type | +======================+==========================================+============================+ -| :class:`c_bool` | :c:type:`_Bool` | bool (1) | +| :class:`c_bool` | :c:expr:`_Bool` | bool (1) | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_char` | :c:type:`char` | 1-character bytes object | +| :class:`c_char` | :c:expr:`char` | 1-character bytes object | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_wchar` | :c:type:`wchar_t` | 1-character string | +| :class:`c_wchar` | :c:expr:`wchar_t` | 1-character string | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_byte` | :c:type:`char` | int | +| :class:`c_byte` | :c:expr:`char` | int | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_ubyte` | :c:type:`unsigned char` | int | +| :class:`c_ubyte` | :c:expr:`unsigned char` | int | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_short` | :c:type:`short` | int | +| :class:`c_short` | :c:expr:`short` | int | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_ushort` | :c:type:`unsigned short` | int | +| :class:`c_ushort` | :c:expr:`unsigned short` | int | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_int` | :c:type:`int` | int | +| :class:`c_int` | :c:expr:`int` | int | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_uint` | :c:type:`unsigned int` | int | +| :class:`c_uint` | :c:expr:`unsigned int` | int | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_long` | :c:type:`long` | int | +| :class:`c_long` | :c:expr:`long` | int | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_ulong` | :c:type:`unsigned long` | int | +| :class:`c_ulong` | :c:expr:`unsigned long` | int | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_longlong` | :c:type:`__int64` or :c:type:`long long` | int | +| :class:`c_longlong` | :c:expr:`__int64` or :c:expr:`long long` | int | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_ulonglong` | :c:type:`unsigned __int64` or | int | -| | :c:type:`unsigned long long` | | +| :class:`c_ulonglong` | :c:expr:`unsigned __int64` or | int | +| | :c:expr:`unsigned long long` | | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_size_t` | :c:type:`size_t` | int | +| :class:`c_size_t` | :c:expr:`size_t` | int | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_ssize_t` | :c:type:`ssize_t` or | int | -| | :c:type:`Py_ssize_t` | | +| :class:`c_ssize_t` | :c:expr:`ssize_t` or | int | +| | :c:expr:`Py_ssize_t` | | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_float` | :c:type:`float` | float | +| :class:`c_float` | :c:expr:`float` | float | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_double` | :c:type:`double` | float | +| :class:`c_double` | :c:expr:`double` | float | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_longdouble`| :c:type:`long double` | float | +| :class:`c_longdouble`| :c:expr:`long double` | float | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_char_p` | :c:type:`char *` (NUL terminated) | bytes object or ``None`` | +| :class:`c_char_p` | :c:expr:`char *` (NUL terminated) | bytes object or ``None`` | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_wchar_p` | :c:type:`wchar_t *` (NUL terminated) | string or ``None`` | +| :class:`c_wchar_p` | :c:expr:`wchar_t *` (NUL terminated) | string or ``None`` | +----------------------+------------------------------------------+----------------------------+ -| :class:`c_void_p` | :c:type:`void *` | int or ``None`` | +| :class:`c_void_p` | :c:expr:`void *` | int or ``None`` | +----------------------+------------------------------------------+----------------------------+ (1) @@ -332,7 +332,7 @@ property:: The :func:`create_string_buffer` function replaces the old :func:`c_buffer` function (which is still available as an alias). To create a mutable memory -block containing unicode characters of the C type :c:type:`wchar_t`, use the +block containing unicode characters of the C type :c:expr:`wchar_t`, use the :func:`create_unicode_buffer` function. @@ -443,7 +443,7 @@ integer, string, bytes, a :mod:`ctypes` instance, or an object with an Return types ^^^^^^^^^^^^ -By default functions are assumed to return the C :c:type:`int` type. Other +By default functions are assumed to return the C :c:expr:`int` type. Other return types can be specified by setting the :attr:`restype` attribute of the function object. @@ -1323,7 +1323,7 @@ way is to instantiate one of the following classes: Instances of this class represent loaded shared libraries. Functions in these libraries use the standard C calling convention, and are assumed to return - :c:type:`int`. + :c:expr:`int`. On Windows creating a :class:`CDLL` instance may fail even if the DLL name exists. When a dependent DLL of the loaded DLL is not found, a @@ -1358,7 +1358,7 @@ way is to instantiate one of the following classes: Windows only: Instances of this class represent loaded shared libraries, functions in these libraries use the ``stdcall`` calling convention, and are - assumed to return :c:type:`int` by default. + assumed to return :c:expr:`int` by default. The Python :term:`global interpreter lock` is released before calling any function exported by these libraries, and reacquired afterwards. @@ -1514,7 +1514,7 @@ object is available: An instance of :class:`PyDLL` that exposes Python C API functions as attributes. Note that all these functions are assumed to return C - :c:type:`int`, which is of course not always the truth, so you have to assign + :c:expr:`int`, which is of course not always the truth, so you have to assign the correct :attr:`restype` attribute to use these functions. .. audit-event:: ctypes.dlopen name ctypes.LibraryLoader @@ -1560,10 +1560,10 @@ They are instances of a private class: .. attribute:: restype Assign a ctypes type to specify the result type of the foreign function. - Use ``None`` for :c:type:`void`, a function not returning anything. + Use ``None`` for :c:expr:`void`, a function not returning anything. It is possible to assign a callable Python object that is not a ctypes - type, in this case the function is assumed to return a C :c:type:`int`, and + type, in this case the function is assumed to return a C :c:expr:`int`, and the callable will be called with this integer, allowing further processing or error checking. Using this is deprecated, for more flexible post processing or error checking use a ctypes data type as @@ -2176,21 +2176,21 @@ These are the fundamental ctypes data types: .. class:: c_byte - Represents the C :c:type:`signed char` datatype, and interprets the value as + Represents the C :c:expr:`signed char` datatype, and interprets the value as small integer. The constructor accepts an optional integer initializer; no overflow checking is done. .. class:: c_char - Represents the C :c:type:`char` datatype, and interprets the value as a single + Represents the C :c:expr:`char` datatype, and interprets the value as a single character. The constructor accepts an optional string initializer, the length of the string must be exactly one character. .. class:: c_char_p - Represents the C :c:type:`char *` datatype when it points to a zero-terminated + Represents the C :c:expr:`char *` datatype when it points to a zero-terminated string. For a general character pointer that may also point to binary data, ``POINTER(c_char)`` must be used. The constructor accepts an integer address, or a bytes object. @@ -2198,68 +2198,68 @@ These are the fundamental ctypes data types: .. class:: c_double - Represents the C :c:type:`double` datatype. The constructor accepts an + Represents the C :c:expr:`double` datatype. The constructor accepts an optional float initializer. .. class:: c_longdouble - Represents the C :c:type:`long double` datatype. The constructor accepts an + Represents the C :c:expr:`long double` datatype. The constructor accepts an optional float initializer. On platforms where ``sizeof(long double) == sizeof(double)`` it is an alias to :class:`c_double`. .. class:: c_float - Represents the C :c:type:`float` datatype. The constructor accepts an + Represents the C :c:expr:`float` datatype. The constructor accepts an optional float initializer. .. class:: c_int - Represents the C :c:type:`signed int` datatype. The constructor accepts an + Represents the C :c:expr:`signed int` datatype. The constructor accepts an optional integer initializer; no overflow checking is done. On platforms where ``sizeof(int) == sizeof(long)`` it is an alias to :class:`c_long`. .. class:: c_int8 - Represents the C 8-bit :c:type:`signed int` datatype. Usually an alias for + Represents the C 8-bit :c:expr:`signed int` datatype. Usually an alias for :class:`c_byte`. .. class:: c_int16 - Represents the C 16-bit :c:type:`signed int` datatype. Usually an alias for + Represents the C 16-bit :c:expr:`signed int` datatype. Usually an alias for :class:`c_short`. .. class:: c_int32 - Represents the C 32-bit :c:type:`signed int` datatype. Usually an alias for + Represents the C 32-bit :c:expr:`signed int` datatype. Usually an alias for :class:`c_int`. .. class:: c_int64 - Represents the C 64-bit :c:type:`signed int` datatype. Usually an alias for + Represents the C 64-bit :c:expr:`signed int` datatype. Usually an alias for :class:`c_longlong`. .. class:: c_long - Represents the C :c:type:`signed long` datatype. The constructor accepts an + Represents the C :c:expr:`signed long` datatype. The constructor accepts an optional integer initializer; no overflow checking is done. .. class:: c_longlong - Represents the C :c:type:`signed long long` datatype. The constructor accepts + Represents the C :c:expr:`signed long long` datatype. The constructor accepts an optional integer initializer; no overflow checking is done. .. class:: c_short - Represents the C :c:type:`signed short` datatype. The constructor accepts an + Represents the C :c:expr:`signed short` datatype. The constructor accepts an optional integer initializer; no overflow checking is done. @@ -2277,83 +2277,83 @@ These are the fundamental ctypes data types: .. class:: c_ubyte - Represents the C :c:type:`unsigned char` datatype, it interprets the value as + Represents the C :c:expr:`unsigned char` datatype, it interprets the value as small integer. The constructor accepts an optional integer initializer; no overflow checking is done. .. class:: c_uint - Represents the C :c:type:`unsigned int` datatype. The constructor accepts an + Represents the C :c:expr:`unsigned int` datatype. The constructor accepts an optional integer initializer; no overflow checking is done. On platforms where ``sizeof(int) == sizeof(long)`` it is an alias for :class:`c_ulong`. .. class:: c_uint8 - Represents the C 8-bit :c:type:`unsigned int` datatype. Usually an alias for + Represents the C 8-bit :c:expr:`unsigned int` datatype. Usually an alias for :class:`c_ubyte`. .. class:: c_uint16 - Represents the C 16-bit :c:type:`unsigned int` datatype. Usually an alias for + Represents the C 16-bit :c:expr:`unsigned int` datatype. Usually an alias for :class:`c_ushort`. .. class:: c_uint32 - Represents the C 32-bit :c:type:`unsigned int` datatype. Usually an alias for + Represents the C 32-bit :c:expr:`unsigned int` datatype. Usually an alias for :class:`c_uint`. .. class:: c_uint64 - Represents the C 64-bit :c:type:`unsigned int` datatype. Usually an alias for + Represents the C 64-bit :c:expr:`unsigned int` datatype. Usually an alias for :class:`c_ulonglong`. .. class:: c_ulong - Represents the C :c:type:`unsigned long` datatype. The constructor accepts an + Represents the C :c:expr:`unsigned long` datatype. The constructor accepts an optional integer initializer; no overflow checking is done. .. class:: c_ulonglong - Represents the C :c:type:`unsigned long long` datatype. The constructor + Represents the C :c:expr:`unsigned long long` datatype. The constructor accepts an optional integer initializer; no overflow checking is done. .. class:: c_ushort - Represents the C :c:type:`unsigned short` datatype. The constructor accepts + Represents the C :c:expr:`unsigned short` datatype. The constructor accepts an optional integer initializer; no overflow checking is done. .. class:: c_void_p - Represents the C :c:type:`void *` type. The value is represented as integer. + Represents the C :c:expr:`void *` type. The value is represented as integer. The constructor accepts an optional integer initializer. .. class:: c_wchar - Represents the C :c:type:`wchar_t` datatype, and interprets the value as a + Represents the C :c:expr:`wchar_t` datatype, and interprets the value as a single character unicode string. The constructor accepts an optional string initializer, the length of the string must be exactly one character. .. class:: c_wchar_p - Represents the C :c:type:`wchar_t *` datatype, which must be a pointer to a + Represents the C :c:expr:`wchar_t *` datatype, which must be a pointer to a zero-terminated wide character string. The constructor accepts an integer address, or a string. .. class:: c_bool - Represent the C :c:type:`bool` datatype (more accurately, :c:type:`_Bool` from + Represent the C :c:expr:`bool` datatype (more accurately, :c:expr:`_Bool` from C99). Its value can be ``True`` or ``False``, and the constructor accepts any object that has a truth value. diff --git a/Doc/library/posix.rst b/Doc/library/posix.rst index 90be191..ec04b0d 100644 --- a/Doc/library/posix.rst +++ b/Doc/library/posix.rst @@ -39,12 +39,12 @@ Large File Support Several operating systems (including AIX and Solaris) provide support for files that are larger than 2 GiB from a C programming model where -:c:type:`int` and :c:type:`long` are 32-bit values. This is typically accomplished +:c:expr:`int` and :c:expr:`long` are 32-bit values. This is typically accomplished by defining the relevant size and offset types as 64-bit values. Such files are sometimes referred to as :dfn:`large files`. Large file support is enabled in Python when the size of an :c:type:`off_t` is -larger than a :c:type:`long` and the :c:type:`long long` is at least as large +larger than a :c:expr:`long` and the :c:expr:`long long` is at least as large as an :c:type:`off_t`. It may be necessary to configure and compile Python with certain compiler flags to enable this mode. For example, with Solaris 2.6 and 2.7 you need to do diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 9d1cfb5..33fed1c 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -1565,7 +1565,7 @@ to sockets. ancillary data, items of the form ``(socket.SOL_SOCKET, socket.SCM_RIGHTS, fds)``, where *fds* is a :class:`bytes` object representing the new file descriptors as a binary array of the - native C :c:type:`int` type. If :meth:`recvmsg` raises an + native C :c:expr:`int` type. If :meth:`recvmsg` raises an exception after the system call returns, it will first attempt to close any file descriptors received via this mechanism. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index af41dbb..84bca3a 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -215,7 +215,7 @@ Numeric Types --- :class:`int`, :class:`float`, :class:`complex` There are three distinct numeric types: :dfn:`integers`, :dfn:`floating point numbers`, and :dfn:`complex numbers`. In addition, Booleans are a subtype of integers. Integers have unlimited precision. Floating point -numbers are usually implemented using :c:type:`double` in C; information +numbers are usually implemented using :c:expr:`double` in C; information about the precision and internal representation of floating point numbers for the machine on which your program is running is available in :data:`sys.float_info`. Complex numbers have a real and imaginary diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst index c1888d4..d12a573 100644 --- a/Doc/library/struct.rst +++ b/Doc/library/struct.rst @@ -196,46 +196,46 @@ platform-dependent. +========+==========================+====================+================+============+ | ``x`` | pad byte | no value | | | +--------+--------------------------+--------------------+----------------+------------+ -| ``c`` | :c:type:`char` | bytes of length 1 | 1 | | +| ``c`` | :c:expr:`char` | bytes of length 1 | 1 | | +--------+--------------------------+--------------------+----------------+------------+ -| ``b`` | :c:type:`signed char` | integer | 1 | \(1), \(2) | +| ``b`` | :c:expr:`signed char` | integer | 1 | \(1), \(2) | +--------+--------------------------+--------------------+----------------+------------+ -| ``B`` | :c:type:`unsigned char` | integer | 1 | \(2) | +| ``B`` | :c:expr:`unsigned char` | integer | 1 | \(2) | +--------+--------------------------+--------------------+----------------+------------+ -| ``?`` | :c:type:`_Bool` | bool | 1 | \(1) | +| ``?`` | :c:expr:`_Bool` | bool | 1 | \(1) | +--------+--------------------------+--------------------+----------------+------------+ -| ``h`` | :c:type:`short` | integer | 2 | \(2) | +| ``h`` | :c:expr:`short` | integer | 2 | \(2) | +--------+--------------------------+--------------------+----------------+------------+ -| ``H`` | :c:type:`unsigned short` | integer | 2 | \(2) | +| ``H`` | :c:expr:`unsigned short` | integer | 2 | \(2) | +--------+--------------------------+--------------------+----------------+------------+ -| ``i`` | :c:type:`int` | integer | 4 | \(2) | +| ``i`` | :c:expr:`int` | integer | 4 | \(2) | +--------+--------------------------+--------------------+----------------+------------+ -| ``I`` | :c:type:`unsigned int` | integer | 4 | \(2) | +| ``I`` | :c:expr:`unsigned int` | integer | 4 | \(2) | +--------+--------------------------+--------------------+----------------+------------+ -| ``l`` | :c:type:`long` | integer | 4 | \(2) | +| ``l`` | :c:expr:`long` | integer | 4 | \(2) | +--------+--------------------------+--------------------+----------------+------------+ -| ``L`` | :c:type:`unsigned long` | integer | 4 | \(2) | +| ``L`` | :c:expr:`unsigned long` | integer | 4 | \(2) | +--------+--------------------------+--------------------+----------------+------------+ -| ``q`` | :c:type:`long long` | integer | 8 | \(2) | +| ``q`` | :c:expr:`long long` | integer | 8 | \(2) | +--------+--------------------------+--------------------+----------------+------------+ -| ``Q`` | :c:type:`unsigned long | integer | 8 | \(2) | +| ``Q`` | :c:expr:`unsigned long | integer | 8 | \(2) | | | long` | | | | +--------+--------------------------+--------------------+----------------+------------+ -| ``n`` | :c:type:`ssize_t` | integer | | \(3) | +| ``n`` | :c:expr:`ssize_t` | integer | | \(3) | +--------+--------------------------+--------------------+----------------+------------+ -| ``N`` | :c:type:`size_t` | integer | | \(3) | +| ``N`` | :c:expr:`size_t` | integer | | \(3) | +--------+--------------------------+--------------------+----------------+------------+ | ``e`` | \(6) | float | 2 | \(4) | +--------+--------------------------+--------------------+----------------+------------+ -| ``f`` | :c:type:`float` | float | 4 | \(4) | +| ``f`` | :c:expr:`float` | float | 4 | \(4) | +--------+--------------------------+--------------------+----------------+------------+ -| ``d`` | :c:type:`double` | float | 8 | \(4) | +| ``d`` | :c:expr:`double` | float | 8 | \(4) | +--------+--------------------------+--------------------+----------------+------------+ -| ``s`` | :c:type:`char[]` | bytes | | | +| ``s`` | :c:expr:`char[]` | bytes | | | +--------+--------------------------+--------------------+----------------+------------+ -| ``p`` | :c:type:`char[]` | bytes | | | +| ``p`` | :c:expr:`char[]` | bytes | | | +--------+--------------------------+--------------------+----------------+------------+ -| ``P`` | :c:type:`void \*` | integer | | \(5) | +| ``P`` | :c:expr:`void \*` | integer | | \(5) | +--------+--------------------------+--------------------+----------------+------------+ .. versionchanged:: 3.3 @@ -250,8 +250,8 @@ Notes: (1) .. index:: single: ? (question mark); in struct format strings - The ``'?'`` conversion code corresponds to the :c:type:`_Bool` type defined by - C99. If this type is not available, it is simulated using a :c:type:`char`. In + The ``'?'`` conversion code corresponds to the :c:expr:`_Bool` type defined by + C99. If this type is not available, it is simulated using a :c:expr:`char`. In standard mode, it is always represented by one byte. (2) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 758f3ae..f2465cd 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -316,7 +316,7 @@ Sequences A string is a sequence of values that represent Unicode code points. All the code points in the range ``U+0000 - U+10FFFF`` can be - represented in a string. Python doesn't have a :c:type:`char` type; + represented in a string. Python doesn't have a :c:expr:`char` type; instead, every code point in the string is represented as a string object with length ``1``. The built-in function :func:`ord` converts a code point from its string form to an integer in the diff --git a/Doc/whatsnew/2.2.rst b/Doc/whatsnew/2.2.rst index b3d6ff6..3999766 100644 --- a/Doc/whatsnew/2.2.rst +++ b/Doc/whatsnew/2.2.rst @@ -983,7 +983,7 @@ New and Improved Modules Jun-ichiro "itojun" Hagino.) * Two new format characters were added to the :mod:`struct` module for 64-bit - integers on platforms that support the C :c:type:`long long` type. ``q`` is for + integers on platforms that support the C :c:expr:`long long` type. ``q`` is for a signed 64-bit integer, and ``Q`` is for an unsigned one. The value is returned in Python's long integer type. (Contributed by Tim Peters.) diff --git a/Doc/whatsnew/2.3.rst b/Doc/whatsnew/2.3.rst index 55061d2..4b9f7a2 100644 --- a/Doc/whatsnew/2.3.rst +++ b/Doc/whatsnew/2.3.rst @@ -1905,8 +1905,8 @@ Changes to Python's build process and to the C API include: "")`` instead, but this will be slower than using :const:`METH_NOARGS`. * :c:func:`PyArg_ParseTuple` accepts new format characters for various sizes of - unsigned integers: ``B`` for :c:type:`unsigned char`, ``H`` for :c:type:`unsigned - short int`, ``I`` for :c:type:`unsigned int`, and ``K`` for :c:type:`unsigned + unsigned integers: ``B`` for :c:expr:`unsigned char`, ``H`` for :c:expr:`unsigned + short int`, ``I`` for :c:expr:`unsigned int`, and ``K`` for :c:expr:`unsigned long long`. * A new function, ``PyObject_DelItemString(mapping, char *key)`` was added diff --git a/Doc/whatsnew/2.4.rst b/Doc/whatsnew/2.4.rst index ddfac1a..eac6f0f 100644 --- a/Doc/whatsnew/2.4.rst +++ b/Doc/whatsnew/2.4.rst @@ -472,7 +472,7 @@ PEP 327: Decimal Data Type ========================== Python has always supported floating-point (FP) numbers, based on the underlying -C :c:type:`double` type, as a data type. However, while most programming +C :c:expr:`double` type, as a data type. However, while most programming languages provide a floating-point type, many people (even programmers) are unaware that floating-point numbers don't represent certain decimal fractions accurately. The new :class:`Decimal` type can represent these fractions @@ -501,7 +501,7 @@ mantissa is multiplied by 4 (2 to the power of the exponent 2); 1.25 \* 4 equals 5. Modern systems usually provide floating-point support that conforms to a -standard called IEEE 754. C's :c:type:`double` type is usually implemented as a +standard called IEEE 754. C's :c:expr:`double` type is usually implemented as a 64-bit IEEE 754 number, which uses 52 bits of space for the mantissa. This means that numbers can only be specified to 52 bits of precision. If you're trying to represent numbers whose expansion repeats endlessly, the expansion is @@ -750,10 +750,10 @@ The solution described in the PEP is to add three new functions to the Python API that perform ASCII-only conversions, ignoring the locale setting: * ``PyOS_ascii_strtod(str, ptr)`` and ``PyOS_ascii_atof(str, ptr)`` - both convert a string to a C :c:type:`double`. + both convert a string to a C :c:expr:`double`. * ``PyOS_ascii_formatd(buffer, buf_len, format, d)`` converts a - :c:type:`double` to an ASCII string. + :c:expr:`double` to an ASCII string. The code for these functions came from the GLib library (https://developer.gnome.org/glib/stable/), whose developers kindly diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst index 880fbaa..0d3ab3b 100644 --- a/Doc/whatsnew/2.5.rst +++ b/Doc/whatsnew/2.5.rst @@ -872,18 +872,18 @@ PEP 353: Using ssize_t as the index type ======================================== A wide-ranging change to Python's C API, using a new :c:type:`Py_ssize_t` type -definition instead of :c:type:`int`, will permit the interpreter to handle more +definition instead of :c:expr:`int`, will permit the interpreter to handle more data on 64-bit platforms. This change doesn't affect Python's capacity on 32-bit platforms. -Various pieces of the Python interpreter used C's :c:type:`int` type to store +Various pieces of the Python interpreter used C's :c:expr:`int` type to store sizes or counts; for example, the number of items in a list or tuple were stored -in an :c:type:`int`. The C compilers for most 64-bit platforms still define -:c:type:`int` as a 32-bit type, so that meant that lists could only hold up to +in an :c:expr:`int`. The C compilers for most 64-bit platforms still define +:c:expr:`int` as a 32-bit type, so that meant that lists could only hold up to ``2**31 - 1`` = 2147483647 items. (There are actually a few different programming models that 64-bit C compilers can use -- see https://unix.org/version2/whatsnew/lp64_wp.html for a discussion -- but the -most commonly available model leaves :c:type:`int` as 32 bits.) +most commonly available model leaves :c:expr:`int` as 32 bits.) A limit of 2147483647 items doesn't really matter on a 32-bit platform because you'll run out of memory before hitting the length limit. Each list item @@ -895,7 +895,7 @@ It's possible to address that much memory on a 64-bit platform, however. The pointers for a list that size would only require 16 GiB of space, so it's not unreasonable that Python programmers might construct lists that large. Therefore, the Python interpreter had to be changed to use some type other than -:c:type:`int`, and this will be a 64-bit type on 64-bit platforms. The change +:c:expr:`int`, and this will be a 64-bit type on 64-bit platforms. The change will cause incompatibilities on 64-bit machines, so it was deemed worth making the transition now, while the number of 64-bit users is still relatively small. (In 5 or 10 years, we may *all* be on 64-bit machines, and the transition would @@ -909,7 +909,7 @@ may therefore need to have some variables changed to :c:type:`Py_ssize_t`. The :c:func:`PyArg_ParseTuple` and :c:func:`Py_BuildValue` functions have a new conversion code, ``n``, for :c:type:`Py_ssize_t`. :c:func:`PyArg_ParseTuple`'s -``s#`` and ``t#`` still output :c:type:`int` by default, but you can define the +``s#`` and ``t#`` still output :c:expr:`int` by default, but you can define the macro :c:macro:`PY_SSIZE_T_CLEAN` before including :file:`Python.h` to make them return :c:type:`Py_ssize_t`. @@ -1695,7 +1695,7 @@ attributes of the :class:`CDLL` object. :: result = libc.printf("Line of output\n") Type constructors for the various C types are provided: :func:`c_int`, -:func:`c_float`, :func:`c_double`, :func:`c_char_p` (equivalent to :c:type:`char +:func:`c_float`, :func:`c_double`, :func:`c_char_p` (equivalent to :c:expr:`char \*`), and so forth. Unlike Python's types, the C versions are all mutable; you can assign to their :attr:`value` attribute to change the wrapped value. Python integers and strings will be automatically converted to the corresponding C @@ -2093,7 +2093,7 @@ Changes to Python's build process and to the C API include: * The largest change to the C API came from :pep:`353`, which modifies the interpreter to use a :c:type:`Py_ssize_t` type definition instead of - :c:type:`int`. See the earlier section :ref:`pep-353` for a discussion of this + :c:expr:`int`. See the earlier section :ref:`pep-353` for a discussion of this change. * The design of the bytecode compiler has changed a great deal, no longer @@ -2264,7 +2264,7 @@ code: Setting :attr:`rpc_paths` to ``None`` or an empty tuple disables this path checking. -* C API: Many functions now use :c:type:`Py_ssize_t` instead of :c:type:`int` to +* C API: Many functions now use :c:type:`Py_ssize_t` instead of :c:expr:`int` to allow processing more data on 64-bit machines. Extension code may need to make the same change to avoid warnings and to support 64-bit machines. See the earlier section :ref:`pep-353` for a discussion of this change. diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst index 3d0d187..6dddf37 100644 --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -2389,7 +2389,7 @@ changes, or look through the Subversion logs for all the details. has been updated from version 2.3.2 in Python 2.5 to version 2.4.1. -* The :mod:`struct` module now supports the C99 :c:type:`_Bool` type, +* The :mod:`struct` module now supports the C99 :c:expr:`_Bool` type, using the format character ``'?'``. (Contributed by David Remahl.) diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst index d48a9f7..3df9f8a 100644 --- a/Doc/whatsnew/2.7.rst +++ b/Doc/whatsnew/2.7.rst @@ -2144,7 +2144,7 @@ Changes to Python's build process and to the C API include: * New functions: :c:func:`PyLong_AsLongAndOverflow` and :c:func:`PyLong_AsLongLongAndOverflow` approximates a Python long - integer as a C :c:type:`long` or :c:type:`long long`. + integer as a C :c:expr:`long` or :c:expr:`long long`. If the number is too large to fit into the output type, an *overflow* flag is set and returned to the caller. (Contributed by Case Van Horsen; :issue:`7528` and :issue:`7767`.) @@ -2202,7 +2202,7 @@ Changes to Python's build process and to the C API include: * New format codes: the :c:func:`PyFormat_FromString`, :c:func:`PyFormat_FromStringV`, and :c:func:`PyErr_Format` functions now accept ``%lld`` and ``%llu`` format codes for displaying - C's :c:type:`long long` types. + C's :c:expr:`long long` types. (Contributed by Mark Dickinson; :issue:`7228`.) * The complicated interaction between threads and process forking has diff --git a/Doc/whatsnew/3.3.rst b/Doc/whatsnew/3.3.rst index 1b5b683..695621b 100644 --- a/Doc/whatsnew/3.3.rst +++ b/Doc/whatsnew/3.3.rst @@ -932,7 +932,7 @@ it can now be used as a class decorator (:issue:`10868`). array ----- -The :mod:`array` module supports the :c:type:`long long` type using ``q`` and +The :mod:`array` module supports the :c:expr:`long long` type using ``q`` and ``Q`` type codes. (Contributed by Oren Tirosh and Hirokazu Yamamoto in :issue:`1172711`.) diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst index 545b7c7..e56d428 100644 --- a/Doc/whatsnew/3.7.rst +++ b/Doc/whatsnew/3.7.rst @@ -290,21 +290,21 @@ PEP 539: New C API for Thread-Local Storage While Python provides a C API for thread-local storage support; the existing :ref:`Thread Local Storage (TLS) API ` has used -:c:type:`int` to represent TLS keys across all platforms. This has not +:c:expr:`int` to represent TLS keys across all platforms. This has not generally been a problem for officially support platforms, but that is neither POSIX-compliant, nor portable in any practical sense. :pep:`539` changes this by providing a new :ref:`Thread Specific Storage (TSS) API ` to CPython which supersedes use of the existing TLS API within the CPython interpreter, while deprecating the existing -API. The TSS API uses a new type :c:type:`Py_tss_t` instead of :c:type:`int` +API. The TSS API uses a new type :c:type:`Py_tss_t` instead of :c:expr:`int` to represent TSS keys--an opaque type the definition of which may depend on the underlying TLS implementation. Therefore, this will allow to build CPython on platforms where the native TLS key is defined in a way that cannot be safely -cast to :c:type:`int`. +cast to :c:expr:`int`. Note that on platforms where the native TLS key is defined in a way that cannot -be safely cast to :c:type:`int`, all functions of the existing TLS API will be +be safely cast to :c:expr:`int`, all functions of the existing TLS API will be no-op and immediately return failure. This indicates clearly that the old API is not supported on platforms where it cannot be used reliably, and that no effort will be made to add such support. @@ -1708,12 +1708,12 @@ Contributed by Paul Ganssle in :issue:`10381`. The type of results of :c:func:`PyThread_start_new_thread` and :c:func:`PyThread_get_thread_ident`, and the *id* parameter of -:c:func:`PyThreadState_SetAsyncExc` changed from :c:type:`long` to -:c:type:`unsigned long`. +:c:func:`PyThreadState_SetAsyncExc` changed from :c:expr:`long` to +:c:expr:`unsigned long`. (Contributed by Serhiy Storchaka in :issue:`6532`.) :c:func:`PyUnicode_AsWideCharString` now raises a :exc:`ValueError` if the -second argument is ``NULL`` and the :c:type:`wchar_t*` string contains null +second argument is ``NULL`` and the :c:expr:`wchar_t*` string contains null characters. (Contributed by Serhiy Storchaka in :issue:`30708`.) Changes to the startup sequence and the management of dynamic memory diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst index 6deaede..ff01a65 100644 --- a/Doc/whatsnew/3.9.rst +++ b/Doc/whatsnew/3.9.rst @@ -773,7 +773,7 @@ Optimizations Stinner in :issue:`38061`.) * :c:func:`PyLong_FromDouble` is now up to 1.87x faster for values that - fit into :c:type:`long`. + fit into :c:expr:`long`. (Contributed by Sergey Fedoseev in :issue:`37986`.) * A number of Python builtins (:class:`range`, :class:`tuple`, :class:`set`, diff --git a/Misc/NEWS.d/3.5.0a1.rst b/Misc/NEWS.d/3.5.0a1.rst index 97bdef6..96e5920 100644 --- a/Misc/NEWS.d/3.5.0a1.rst +++ b/Misc/NEWS.d/3.5.0a1.rst @@ -3034,7 +3034,7 @@ by Phil Elson. .. nonce: LK_5S1 .. section: Library -os.read() now uses a :c:func:`Py_ssize_t` type instead of :c:type:`int` for +os.read() now uses a :c:func:`Py_ssize_t` type instead of :c:expr:`int` for the size to support reading more than 2 GB at once. On Windows, the size is truncated to INT_MAX. As any call to os.read(), the OS may read less bytes than the number of requested bytes. diff --git a/Misc/NEWS.d/3.9.0a1.rst b/Misc/NEWS.d/3.9.0a1.rst index 45f232f..63d77fd 100644 --- a/Misc/NEWS.d/3.9.0a1.rst +++ b/Misc/NEWS.d/3.9.0a1.rst @@ -1510,7 +1510,7 @@ asynchronous magic methods on a MagicMock now return an AsyncMock. .. section: Library Update the *length* parameter of :func:`os.pread` to accept -:c:type:`Py_ssize_t` instead of :c:type:`int`. +:c:type:`Py_ssize_t` instead of :c:expr:`int`. .. diff --git a/Misc/NEWS.d/3.9.0b1.rst b/Misc/NEWS.d/3.9.0b1.rst index 529be0e..a7f52f8 100644 --- a/Misc/NEWS.d/3.9.0b1.rst +++ b/Misc/NEWS.d/3.9.0b1.rst @@ -191,7 +191,7 @@ internal subinterpreters module. .. section: Core and Builtins Improve performance of :c:func:`PyLong_FromDouble` for values that fit into -:c:type:`long`. +:c:expr:`long`. .. -- cgit v0.12 From 28f97dc9d272b517f10882997d20dd1b59e17ff9 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 5 Oct 2022 13:16:12 -0700 Subject: docs(typing): add "see PEP 675" to LiteralString (GH-97926) (cherry picked from commit 2016bc54a22b83d0ca9174b64257cc7bb67a0916) Co-authored-by: Simon Legner --- Doc/library/typing.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 11f0543..b75753f 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -626,6 +626,8 @@ These can be used as types in annotations and do not support ``[]``. that generate type checker errors could be vulnerable to an SQL injection attack. + See :pep:`675` for more details. + .. versionadded:: 3.11 .. data:: Never -- cgit v0.12 From c5d6009c41a2d31f65904d9193c588ba82c6eb71 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 5 Oct 2022 11:01:17 -0700 Subject: GH-95172 Make the same version `versionadded` oneline (GH-95172) * Make the same version versionadded oneline * Format versionadded for enum.rst * Format versionadded A single line versionadded was reading better. Co-authored-by: Senthil Kumaran (cherry picked from commit d6062d1170199c4f02acf6de8fcbf5d748a03db2) Co-authored-by: 180909 <734461790@qq.com> --- Doc/library/enum.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index b1333c7..241d19d 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -134,8 +134,7 @@ Module Contents .. versionadded:: 3.6 ``Flag``, ``IntFlag``, ``auto`` -.. versionadded:: 3.11 ``StrEnum``, ``EnumCheck``, ``FlagBoundary``, ``property`` -.. versionadded:: 3.11 ``member``, ``nonmember`` +.. versionadded:: 3.11 ``StrEnum``, ``EnumCheck``, ``FlagBoundary``, ``property``, ``member``, ``nonmember`` --------------- -- cgit v0.12 From 6ff98f7b45aed3f46aa1d4115b31730ea3a1df54 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 5 Oct 2022 11:00:29 -0700 Subject: [3.11] gh-93738: Documentation C syntax (Function glob patterns -> literal markup) (GH-97774) (#97910) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit (cherry picked from commit 0e72606dd4cf3023a4f8c2fe3c58082592b253f7) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Łukasz Langa --- Doc/c-api/arg.rst | 8 ++++---- Doc/c-api/exceptions.rst | 4 ++-- Doc/c-api/init.rst | 6 +++--- Doc/c-api/module.rst | 4 ++-- Doc/c-api/typeobj.rst | 8 ++++---- Doc/extending/extending.rst | 6 +++--- Doc/whatsnew/2.5.rst | 6 +++--- 7 files changed, 21 insertions(+), 21 deletions(-) diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index b4c48aa..9df026a 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -335,7 +335,7 @@ Other objects status = converter(object, address); where *object* is the Python object to be converted and *address* is the - :c:expr:`void*` argument that was passed to the ``PyArg_Parse*`` function. + :c:type:`void*` argument that was passed to the ``PyArg_Parse*`` function. The returned *status* should be ``1`` for a successful conversion and ``0`` if the conversion has failed. When the conversion fails, the *converter* function should raise an exception and leave the content of *address* unmodified. @@ -409,9 +409,9 @@ what is specified for the corresponding format unit in that case. For the conversion to succeed, the *arg* object must match the format and the format must be exhausted. On success, the -:c:func:`PyArg_Parse\*` functions return true, otherwise they return +``PyArg_Parse*`` functions return true, otherwise they return false and raise an appropriate exception. When the -:c:func:`PyArg_Parse\*` functions fail due to conversion failure in one +``PyArg_Parse*`` functions fail due to conversion failure in one of the format units, the variables at the addresses corresponding to that and the following format units are left untouched. @@ -518,7 +518,7 @@ Building values .. c:function:: PyObject* Py_BuildValue(const char *format, ...) Create a new value based on a format string similar to those accepted by the - :c:func:`PyArg_Parse\*` family of functions and a sequence of values. Returns + ``PyArg_Parse*`` family of functions and a sequence of values. Returns the value or ``NULL`` in the case of an error; an exception will be raised if ``NULL`` is returned. diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 02ec1da..e5112f7 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -14,7 +14,7 @@ there is a global indicator (per thread) of the last error that occurred. Most C API functions don't clear this on success, but will set it to indicate the cause of the error on failure. Most C API functions also return an error indicator, usually ``NULL`` if they are supposed to return a pointer, or ``-1`` -if they return an integer (exception: the :c:func:`PyArg_\*` functions +if they return an integer (exception: the ``PyArg_*`` functions return ``1`` for success and ``0`` for failure). Concretely, the error indicator consists of three object pointers: the @@ -370,7 +370,7 @@ Querying the error indicator .. c:function:: PyObject* PyErr_Occurred() Test whether the error indicator is set. If set, return the exception *type* - (the first argument to the last call to one of the :c:func:`PyErr_Set\*` + (the first argument to the last call to one of the ``PyErr_Set*`` functions or to :c:func:`PyErr_Restore`). If not set, return ``NULL``. You do not own a reference to the return value, so you do not need to :c:func:`Py_DECREF` it. diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 8573826..a9c1941 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -847,11 +847,11 @@ from a C thread is:: /* Release the thread. No Python API allowed beyond this point. */ PyGILState_Release(gstate); -Note that the :c:func:`PyGILState_\*` functions assume there is only one global +Note that the ``PyGILState_*`` functions assume there is only one global interpreter (created automatically by :c:func:`Py_Initialize`). Python supports the creation of additional interpreters (using :c:func:`Py_NewInterpreter`), but mixing multiple interpreters and the -:c:func:`PyGILState_\*` API is unsupported. +``PyGILState_*`` API is unsupported. .. _fork-and-threads: @@ -1478,7 +1478,7 @@ operations executed by such objects may affect the wrong (sub-)interpreter's dictionary of loaded modules. It is equally important to avoid sharing objects from which the above are reachable. -Also note that combining this functionality with :c:func:`PyGILState_\*` APIs +Also note that combining this functionality with ``PyGILState_*`` APIs is delicate, because these APIs assume a bijection between Python thread states and OS-level threads, an assumption broken by the presence of sub-interpreters. It is highly recommended that you don't switch sub-interpreters between a pair diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst index 94c8d9f..e2ba157 100644 --- a/Doc/c-api/module.rst +++ b/Doc/c-api/module.rst @@ -64,8 +64,8 @@ Module Objects If *module* is not a module object (or a subtype of a module object), :exc:`SystemError` is raised and ``NULL`` is returned. - It is recommended extensions use other :c:func:`PyModule_\*` and - :c:func:`PyObject_\*` functions rather than directly manipulate a module's + It is recommended extensions use other ``PyModule_*`` and + ``PyObject_*`` functions rather than directly manipulate a module's :attr:`~object.__dict__`. diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 8be489a..2219f68 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -7,8 +7,8 @@ Type Objects Perhaps one of the most important structures of the Python object system is the structure that defines a new type: the :c:type:`PyTypeObject` structure. Type -objects can be handled using any of the :c:func:`PyObject_\*` or -:c:func:`PyType_\*` functions, but do not offer much that's interesting to most +objects can be handled using any of the ``PyObject_*`` or +``PyType_*`` functions, but do not offer much that's interesting to most Python applications. These objects are fundamental to how objects behave, so they are very important to the interpreter itself and to any extension module that implements new types. @@ -1484,8 +1484,8 @@ and :c:type:`PyType_Type` effectively act as defaults.) If the instances of this type are weakly referenceable, this field is greater than zero and contains the offset in the instance structure of the weak reference list head (ignoring the GC header, if present); this offset is used by - :c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The - instance structure needs to include a field of type :c:type:`PyObject*` which is + :c:func:`PyObject_ClearWeakRefs` and the ``PyWeakref_*`` functions. The + instance structure needs to include a field of type :c:expr:`PyObject*` which is initialized to ``NULL``. Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that is the list head for diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index 890b19a..d9bf4fd 100644 --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -157,16 +157,16 @@ since you should be able to tell from the return value. When a function *f* that calls another function *g* detects that the latter fails, *f* should itself return an error value (usually ``NULL`` or ``-1``). It -should *not* call one of the :c:func:`PyErr_\*` functions --- one has already +should *not* call one of the ``PyErr_*`` functions --- one has already been called by *g*. *f*'s caller is then supposed to also return an error -indication to *its* caller, again *without* calling :c:func:`PyErr_\*`, and so on +indication to *its* caller, again *without* calling ``PyErr_*``, and so on --- the most detailed cause of the error was already reported by the function that first detected it. Once the error reaches the Python interpreter's main loop, this aborts the currently executing Python code and tries to find an exception handler specified by the Python programmer. (There are situations where a module can actually give a more detailed error -message by calling another :c:func:`PyErr_\*` function, and in such cases it is +message by calling another ``PyErr_*`` function, and in such cases it is fine to do so. As a general rule, however, this is not necessary, and can cause information about the cause of the error to be lost: most operations can fail for a variety of reasons.) diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst index 0d3ab3b..dcfaef6 100644 --- a/Doc/whatsnew/2.5.rst +++ b/Doc/whatsnew/2.5.rst @@ -2270,9 +2270,9 @@ code: earlier section :ref:`pep-353` for a discussion of this change. * C API: The obmalloc changes mean that you must be careful to not mix usage - of the :c:func:`PyMem_\*` and :c:func:`PyObject_\*` families of functions. Memory - allocated with one family's :c:func:`\*_Malloc` must be freed with the - corresponding family's :c:func:`\*_Free` function. + of the ``PyMem_*`` and ``PyObject_*`` families of functions. Memory + allocated with one family's ``*_Malloc`` must be freed with the + corresponding family's ``*_Free`` function. .. ====================================================================== -- cgit v0.12 From 2af31cf7de3d07072fe81d3b10345a191c5c8cd4 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 5 Oct 2022 08:21:32 -0700 Subject: [3.11] gh-93738: Documentation C syntax (:c:type:`PyTypeObject*` -> :c:expr:`PyTypeObject*`) (GH-97778) (#97892) Co-authored-by: Ezio Melotti (cherry picked from commit c70c8b69762f720377adaf22f2e5ec6496a7be53) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/c-api/object.rst | 2 +- Doc/c-api/typehints.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index fb03366..5a25a2b 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -310,7 +310,7 @@ Object Protocol is equivalent to the Python expression ``type(o)``. This function increments the reference count of the return value. There's really no reason to use this function instead of the :c:func:`Py_TYPE()` function, which returns a - pointer of type :c:type:`PyTypeObject*`, except when the incremented reference + pointer of type :c:expr:`PyTypeObject*`, except when the incremented reference count is needed. diff --git a/Doc/c-api/typehints.rst b/Doc/c-api/typehints.rst index 8b0b9b6..4c1957a 100644 --- a/Doc/c-api/typehints.rst +++ b/Doc/c-api/typehints.rst @@ -15,8 +15,8 @@ two types exist -- :ref:`GenericAlias ` and Equivalent to calling the Python class :class:`types.GenericAlias`. The *origin* and *args* arguments set the ``GenericAlias``\ 's ``__origin__`` and ``__args__`` attributes respectively. - *origin* should be a :c:type:`PyTypeObject*`, and *args* can be a - :c:type:`PyTupleObject*` or any ``PyObject*``. If *args* passed is + *origin* should be a :c:expr:`PyTypeObject*`, and *args* can be a + :c:expr:`PyTupleObject*` or any ``PyObject*``. If *args* passed is not a tuple, a 1-tuple is automatically constructed and ``__args__`` is set to ``(args,)``. Minimal checking is done for the arguments, so the function will succeed even -- cgit v0.12 From 33e4537975b271570476af7c2db9226dce133da7 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 5 Oct 2022 08:20:03 -0700 Subject: [3.11] gh-93738: Documentation C syntax (Use `c:struct`) (GH-97772) (#97869) Use `c:struct` (cherry picked from commit a0f5599aac2037da715d09733e0a83a9cba7c37a) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/c-api/import.rst | 6 +++--- Doc/c-api/veryhigh.rst | 4 ++-- Doc/library/ctypes.rst | 4 ++-- Doc/library/socket.rst | 12 ++++++------ Doc/whatsnew/3.11.rst | 2 +- Doc/whatsnew/3.8.rst | 2 +- 6 files changed, 15 insertions(+), 15 deletions(-) diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst index 5e2333a..0922956 100644 --- a/Doc/c-api/import.rst +++ b/Doc/c-api/import.rst @@ -243,7 +243,7 @@ Importing Modules UTF-8 encoded string instead of a Unicode object. -.. c:type:: struct _frozen +.. c:struct:: _frozen .. index:: single: freeze utility @@ -265,7 +265,7 @@ Importing Modules .. c:var:: const struct _frozen* PyImport_FrozenModules - This pointer is initialized to point to an array of :c:type:`struct _frozen` + This pointer is initialized to point to an array of :c:struct:`_frozen` records, terminated by one whose members are all ``NULL`` or zero. When a frozen module is imported, it is searched in this table. Third-party code could play tricks with this to provide a dynamically created collection of frozen modules. @@ -281,7 +281,7 @@ Importing Modules :c:func:`Py_Initialize`. -.. c:type:: struct _inittab +.. c:struct:: _inittab Structure describing a single entry in the list of built-in modules. Each of these structures gives the name and initialization function for a module built diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index 7bd47bb..365a2b5 100644 --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -82,7 +82,7 @@ the same library that the Python runtime is using. .. c:function:: int PyRun_SimpleString(const char *command) This is a simplified interface to :c:func:`PyRun_SimpleStringFlags` below, - leaving the :c:type:`PyCompilerFlags`\* argument set to ``NULL``. + leaving the :c:struct:`PyCompilerFlags`\* argument set to ``NULL``. .. c:function:: int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags) @@ -338,7 +338,7 @@ the same library that the Python runtime is using. interpreter loop. -.. c:type:: struct PyCompilerFlags +.. c:struct:: PyCompilerFlags This is the structure used to hold compiler flags. In cases where code is only being compiled, it is passed as ``int flags``, and in cases where code is being diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index f501375..62e8fd3 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1074,7 +1074,7 @@ An extended example which also demonstrates the use of pointers accesses the Quoting the docs for that value: - This pointer is initialized to point to an array of :c:type:`struct _frozen` + This pointer is initialized to point to an array of :c:struct:`_frozen` records, terminated by one whose members are all ``NULL`` or zero. When a frozen module is imported, it is searched in this table. Third-party code could play tricks with this to provide a dynamically created collection of frozen modules. @@ -1093,7 +1093,7 @@ size, we show only how this table can be read with :mod:`ctypes`:: ... >>> -We have defined the :c:type:`struct _frozen` data type, so we can get the pointer +We have defined the :c:struct:`_frozen` data type, so we can get the pointer to the table:: >>> FrozenTable = POINTER(struct_frozen) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 33fed1c..b1c2ab0 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -1012,7 +1012,7 @@ The :mod:`socket` module also offers various network-related services: Convert an IPv4 address from dotted-quad string format (for example, '123.45.67.89') to 32-bit packed binary format, as a bytes object four characters in length. This is useful when conversing with a program that uses the standard C - library and needs objects of type :c:type:`struct in_addr`, which is the C type + library and needs objects of type :c:struct:`in_addr`, which is the C type for the 32-bit packed binary this function returns. :func:`inet_aton` also accepts strings with less than three dots; see the @@ -1031,7 +1031,7 @@ The :mod:`socket` module also offers various network-related services: Convert a 32-bit packed IPv4 address (a :term:`bytes-like object` four bytes in length) to its standard dotted-quad string representation (for example, '123.45.67.89'). This is useful when conversing with a program that uses the - standard C library and needs objects of type :c:type:`struct in_addr`, which + standard C library and needs objects of type :c:struct:`in_addr`, which is the C type for the 32-bit packed binary data this function takes as an argument. @@ -1048,8 +1048,8 @@ The :mod:`socket` module also offers various network-related services: Convert an IP address from its family-specific string format to a packed, binary format. :func:`inet_pton` is useful when a library or network protocol - calls for an object of type :c:type:`struct in_addr` (similar to - :func:`inet_aton`) or :c:type:`struct in6_addr`. + calls for an object of type :c:struct:`in_addr` (similar to + :func:`inet_aton`) or :c:struct:`in6_addr`. Supported values for *address_family* are currently :const:`AF_INET` and :const:`AF_INET6`. If the IP address string *ip_string* is invalid, @@ -1069,8 +1069,8 @@ The :mod:`socket` module also offers various network-related services: bytes) to its standard, family-specific string representation (for example, ``'7.10.0.5'`` or ``'5aef:2b::8'``). :func:`inet_ntop` is useful when a library or network protocol returns an - object of type :c:type:`struct in_addr` (similar to :func:`inet_ntoa`) or - :c:type:`struct in6_addr`. + object of type :c:struct:`in_addr` (similar to :func:`inet_ntoa`) or + :c:struct:`in6_addr`. Supported values for *address_family* are currently :const:`AF_INET` and :const:`AF_INET6`. If the bytes object *packed_ip* is not the correct diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index a13cbe6..00068a4 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -1823,7 +1823,7 @@ Porting to Python 3.11 fields of the result from the exception instance (the ``value`` field). (Contributed by Irit Katriel in :issue:`45711`.) -* :c:type:`_frozen` has a new ``is_package`` field to indicate whether +* :c:struct:`_frozen` has a new ``is_package`` field to indicate whether or not the frozen module is a package. Previously, a negative value in the ``size`` field was the indicator. Now only non-negative values be used for ``size``. diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst index 51e1f9a..9426ea7 100644 --- a/Doc/whatsnew/3.8.rst +++ b/Doc/whatsnew/3.8.rst @@ -2011,7 +2011,7 @@ Changes in the Python API Changes in the C API -------------------- -* The :c:type:`PyCompilerFlags` structure got a new *cf_feature_version* +* The :c:struct:`PyCompilerFlags` structure got a new *cf_feature_version* field. It should be initialized to ``PY_MINOR_VERSION``. The field is ignored by default, and is used if and only if ``PyCF_ONLY_AST`` flag is set in *cf_flags*. -- cgit v0.12 From e2f7642b982e01bab7b59e59c542f5597e4bc1f0 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 5 Oct 2022 08:18:55 -0700 Subject: [3.11] gh-93738: Documentation C syntax (:c:type: to :c:expr:, misc. cases) (GH-97775) (#97873) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/c-api/file.rst | 2 +- Doc/c-api/structures.rst | 6 +++--- Doc/whatsnew/2.4.rst | 4 ++-- Misc/NEWS.d/3.8.0a4.rst | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst index 0d42177..3e5c9ea 100644 --- a/Doc/c-api/file.rst +++ b/Doc/c-api/file.rst @@ -65,7 +65,7 @@ the :mod:`io` APIs instead. Overrides the normal behavior of :func:`io.open_code` to pass its parameter through the provided handler. - The handler is a function of type :c:type:`PyObject *(\*)(PyObject *path, + The handler is a function of type :c:expr:`PyObject *(\*)(PyObject *path, void *userData)`, where *path* is guaranteed to be :c:type:`PyUnicodeObject`. The *userData* pointer is passed into the hook function. Since hook diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 86d4536..3f6f2c6 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -103,7 +103,7 @@ the definition of all other Python objects. .. versionchanged:: 3.11 :c:func:`Py_TYPE()` is changed to an inline static function. - The parameter type is no longer :c:type:`const PyObject*`. + The parameter type is no longer :c:expr:`const PyObject*`. .. c:function:: int Py_IS_TYPE(PyObject *o, PyTypeObject *type) @@ -128,7 +128,7 @@ the definition of all other Python objects. Use the :c:func:`Py_SET_REFCNT()` function to set an object reference count. .. versionchanged:: 3.11 - The parameter type is no longer :c:type:`const PyObject*`. + The parameter type is no longer :c:expr:`const PyObject*`. .. versionchanged:: 3.10 :c:func:`Py_REFCNT()` is changed to the inline static function. @@ -149,7 +149,7 @@ the definition of all other Python objects. .. versionchanged:: 3.11 :c:func:`Py_SIZE()` is changed to an inline static function. - The parameter type is no longer :c:type:`const PyVarObject*`. + The parameter type is no longer :c:expr:`const PyVarObject*`. .. c:function:: void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size) diff --git a/Doc/whatsnew/2.4.rst b/Doc/whatsnew/2.4.rst index eac6f0f..63e8198 100644 --- a/Doc/whatsnew/2.4.rst +++ b/Doc/whatsnew/2.4.rst @@ -1453,7 +1453,7 @@ Some of the changes to Python's build process and to the C API are: extension functions: :c:macro:`Py_RETURN_NONE`, :c:macro:`Py_RETURN_TRUE`, and :c:macro:`Py_RETURN_FALSE`. (Contributed by Brett Cannon.) -* Another new macro, :c:macro:`Py_CLEAR(obj)`, decreases the reference count of +* Another new macro, :c:macro:`Py_CLEAR`, decreases the reference count of *obj* and sets *obj* to the null pointer. (Contributed by Jim Fulton.) * A new function, ``PyTuple_Pack(N, obj1, obj2, ..., objN)``, constructs @@ -1464,7 +1464,7 @@ Some of the changes to Python's build process and to the C API are: lookups without masking exceptions raised during the look-up process. (Contributed by Raymond Hettinger.) -* The :c:macro:`Py_IS_NAN(X)` macro returns 1 if its float or double argument +* The :c:expr:`Py_IS_NAN(X)` macro returns 1 if its float or double argument *X* is a NaN. (Contributed by Tim Peters.) * C code can avoid unnecessary locking by using the new diff --git a/Misc/NEWS.d/3.8.0a4.rst b/Misc/NEWS.d/3.8.0a4.rst index fc952fa..5250d82 100644 --- a/Misc/NEWS.d/3.8.0a4.rst +++ b/Misc/NEWS.d/3.8.0a4.rst @@ -1354,7 +1354,7 @@ the function is called twice. .. nonce: pz-DIR .. section: C API -:c:macro:`PyDoc_VAR(name)` and :c:macro:`PyDoc_STRVAR(name,str)` now create +:c:expr:`PyDoc_VAR(name)` and :c:expr:`PyDoc_STRVAR(name,str)` now create ``static const char name[]`` instead of ``static char name[]``. Patch by Inada Naoki. -- cgit v0.12 From 800c9c06107462c7be3a5302b3645b158e76dd2e Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 5 Oct 2022 08:18:27 -0700 Subject: [3.11] gh-93738: Documentation C syntax (:c:type:`PyObject` -> :c:expr:`PyObject`) (GH-97776) (#97889) :c:type:`PyObject` -> :c:expr:`PyObject` (cherry picked from commit 0bf6a617ed1832bc4803e532c8d6b3427cf48b13) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/c-api/arg.rst | 10 +++++----- Doc/c-api/call.rst | 8 ++++---- Doc/c-api/dict.rst | 4 ++-- Doc/c-api/exceptions.rst | 4 ++-- Doc/c-api/init.rst | 4 ++-- Doc/c-api/intro.rst | 4 ++-- Doc/c-api/structures.rst | 20 ++++++++++---------- Doc/c-api/tuple.rst | 2 +- Doc/c-api/typeobj.rst | 2 +- Doc/library/ctypes.rst | 4 ++-- 10 files changed, 31 insertions(+), 31 deletions(-) diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index 9df026a..0c15045 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -129,12 +129,12 @@ which disallows mutable objects such as :class:`bytearray`. ``S`` (:class:`bytes`) [PyBytesObject \*] Requires that the Python object is a :class:`bytes` object, without attempting any conversion. Raises :exc:`TypeError` if the object is not - a bytes object. The C variable may also be declared as :c:type:`PyObject*`. + a bytes object. The C variable may also be declared as :c:expr:`PyObject*`. ``Y`` (:class:`bytearray`) [PyByteArrayObject \*] Requires that the Python object is a :class:`bytearray` object, without attempting any conversion. Raises :exc:`TypeError` if the object is not - a :class:`bytearray` object. The C variable may also be declared as :c:type:`PyObject*`. + a :class:`bytearray` object. The C variable may also be declared as :c:expr:`PyObject*`. ``u`` (:class:`str`) [const Py_UNICODE \*] Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of @@ -181,7 +181,7 @@ which disallows mutable objects such as :class:`bytearray`. ``U`` (:class:`str`) [PyObject \*] Requires that the Python object is a Unicode object, without attempting any conversion. Raises :exc:`TypeError` if the object is not a Unicode - object. The C variable may also be declared as :c:type:`PyObject*`. + object. The C variable may also be declared as :c:expr:`PyObject*`. ``w*`` (read-write :term:`bytes-like object`) [Py_buffer] This format accepts any object which implements the read-write buffer @@ -320,7 +320,7 @@ Other objects ``O!`` (object) [*typeobject*, PyObject \*] Store a Python object in a C object pointer. This is similar to ``O``, but takes two C arguments: the first is the address of a Python type object, the - second is the address of the C variable (of type :c:type:`PyObject*`) into which + second is the address of the C variable (of type :c:expr:`PyObject*`) into which the object pointer is stored. If the Python object does not have the required type, :exc:`TypeError` is raised. @@ -481,7 +481,7 @@ API Functions *args*; it must actually be a tuple. The length of the tuple must be at least *min* and no more than *max*; *min* and *max* may be equal. Additional arguments must be passed to the function, each of which should be a pointer to a - :c:type:`PyObject*` variable; these will be filled in with the values from + :c:expr:`PyObject*` variable; these will be filled in with the values from *args*; they will contain :term:`borrowed references `. The variables which correspond to optional parameters not given by *args* will not be filled in; these should diff --git a/Doc/c-api/call.rst b/Doc/c-api/call.rst index 13ef8b2..36149f1 100644 --- a/Doc/c-api/call.rst +++ b/Doc/c-api/call.rst @@ -275,7 +275,7 @@ please see individual documentation for details. This is the equivalent of the Python expression: ``callable(*args)``. - Note that if you only pass :c:type:`PyObject *` args, + Note that if you only pass :c:expr:`PyObject *` args, :c:func:`PyObject_CallFunctionObjArgs` is a faster alternative. .. versionchanged:: 3.4 @@ -296,7 +296,7 @@ please see individual documentation for details. This is the equivalent of the Python expression: ``obj.name(arg1, arg2, ...)``. - Note that if you only pass :c:type:`PyObject *` args, + Note that if you only pass :c:expr:`PyObject *` args, :c:func:`PyObject_CallMethodObjArgs` is a faster alternative. .. versionchanged:: 3.4 @@ -306,7 +306,7 @@ please see individual documentation for details. .. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ...) Call a callable Python object *callable*, with a variable number of - :c:type:`PyObject *` arguments. The arguments are provided as a variable number + :c:expr:`PyObject *` arguments. The arguments are provided as a variable number of parameters followed by *NULL*. Return the result of the call on success, or raise an exception and return @@ -320,7 +320,7 @@ please see individual documentation for details. Call a method of the Python object *obj*, where the name of the method is given as a Python string object in *name*. It is called with a variable number of - :c:type:`PyObject *` arguments. The arguments are provided as a variable number + :c:expr:`PyObject *` arguments. The arguments are provided as a variable number of parameters followed by *NULL*. Return the result of the call on success, or raise an exception and return diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 5b0cd93..041afed 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -118,7 +118,7 @@ Dictionary Objects .. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key) This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a - :c:expr:`const char*`, rather than a :c:expr:`PyObject*`. + :c:type:`const char*`, rather than a :c:expr:`PyObject*`. Note that exceptions which occur while calling :meth:`__hash__` and :meth:`__eq__` methods and creating a temporary string object @@ -167,7 +167,7 @@ Dictionary Objects prior to the first call to this function to start the iteration; the function returns true for each pair in the dictionary, and false once all pairs have been reported. The parameters *pkey* and *pvalue* should either - point to :c:type:`PyObject*` variables that will be filled in with each key + point to :c:expr:`PyObject*` variables that will be filled in with each key and value, respectively, or may be ``NULL``. Any references returned through them are borrowed. *ppos* should not be altered during iteration. Its value represents offsets within the internal dictionary structure, and diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index e5112f7..6c89488 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -848,7 +848,7 @@ Standard Exceptions All standard Python exceptions are available as global variables whose names are ``PyExc_`` followed by the Python exception name. These have the type -:c:type:`PyObject*`; they are all class objects. For completeness, here are all +:c:expr:`PyObject*`; they are all class objects. For completeness, here are all the variables: .. index:: @@ -1068,7 +1068,7 @@ Standard Warning Categories All standard Python warning categories are available as global variables whose names are ``PyExc_`` followed by the Python exception name. These have the type -:c:type:`PyObject*`; they are all class objects. For completeness, here are all +:c:expr:`PyObject*`; they are all class objects. For completeness, here are all the variables: .. index:: diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index a9c1941..f2473bb 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1741,8 +1741,8 @@ you need to include :file:`pythread.h` to use thread-local storage. .. note:: None of these API functions handle memory management on behalf of the - :c:expr:`void*` values. You need to allocate and deallocate them yourself. - If the :c:expr:`void*` values happen to be :c:expr:`PyObject*`, these + :c:type:`void*` values. You need to allocate and deallocate them yourself. + If the :c:type:`void*` values happen to be :c:expr:`PyObject*`, these functions don't do refcount operations on them either. .. _thread-specific-storage-api: diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 63069f4..ac2afa1 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -264,13 +264,13 @@ Objects, Types and Reference Counts .. index:: object: type Most Python/C API functions have one or more arguments as well as a return value -of type :c:type:`PyObject*`. This type is a pointer to an opaque data type +of type :c:expr:`PyObject*`. This type is a pointer to an opaque data type representing an arbitrary Python object. Since all Python object types are treated the same way by the Python language in most situations (e.g., assignments, scope rules, and argument passing), it is only fitting that they should be represented by a single C type. Almost all Python objects live on the heap: you never declare an automatic or static variable of type -:c:type:`PyObject`, only pointer variables of type :c:type:`PyObject*` can be +:c:type:`PyObject`, only pointer variables of type :c:expr:`PyObject*` can be declared. The sole exception are the type objects; since these must never be deallocated, they are typically static :c:type:`PyTypeObject` objects. diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 3f6f2c6..2b5d9a8 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -27,7 +27,7 @@ the definition of all other Python objects. object. In a normal "release" build, it contains only the object's reference count and a pointer to the corresponding type object. Nothing is actually declared to be a :c:type:`PyObject`, but every pointer - to a Python object can be cast to a :c:type:`PyObject*`. Access to the + to a Python object can be cast to a :c:expr:`PyObject*`. Access to the members must be done by using the macros :c:macro:`Py_REFCNT` and :c:macro:`Py_TYPE`. @@ -184,7 +184,7 @@ Implementing functions and methods .. c:type:: PyCFunction Type of the functions used to implement most Python callables in C. - Functions of this type take two :c:type:`PyObject*` parameters and return + Functions of this type take two :c:expr:`PyObject*` parameters and return one such value. If the return value is ``NULL``, an exception shall have been set. If not ``NULL``, the return value is interpreted as the return value of the function as exposed in Python. The function must return a new @@ -263,10 +263,10 @@ Implementing functions and methods +------------------+---------------+-------------------------------+ The :attr:`ml_meth` is a C function pointer. The functions may be of different -types, but they always return :c:type:`PyObject*`. If the function is not of +types, but they always return :c:expr:`PyObject*`. If the function is not of the :c:type:`PyCFunction`, the compiler will require a cast in the method table. Even though :c:type:`PyCFunction` defines the first parameter as -:c:type:`PyObject*`, it is common that the method implementation uses the +:c:expr:`PyObject*`, it is common that the method implementation uses the specific C type of the *self* object. The :attr:`ml_flags` field is a bitfield which can include the following flags. @@ -278,7 +278,7 @@ There are these calling conventions: .. data:: METH_VARARGS This is the typical calling convention, where the methods have the type - :c:type:`PyCFunction`. The function expects two :c:type:`PyObject*` values. + :c:type:`PyCFunction`. The function expects two :c:expr:`PyObject*` values. The first one is the *self* object for methods; for module functions, it is the module object. The second parameter (often called *args*) is a tuple object representing all arguments. This parameter is typically processed @@ -299,7 +299,7 @@ There are these calling conventions: Fast calling convention supporting only positional arguments. The methods have the type :c:type:`_PyCFunctionFast`. The first parameter is *self*, the second parameter is a C array - of :c:type:`PyObject*` values indicating the arguments and the third + of :c:expr:`PyObject*` values indicating the arguments and the third parameter is the number of arguments (the length of the array). .. versionadded:: 3.7 @@ -315,7 +315,7 @@ There are these calling conventions: with methods of type :c:type:`_PyCFunctionFastWithKeywords`. Keyword arguments are passed the same way as in the :ref:`vectorcall protocol `: - there is an additional fourth :c:type:`PyObject*` parameter + there is an additional fourth :c:expr:`PyObject*` parameter which is a tuple representing the names of the keyword arguments (which are guaranteed to be strings) or possibly ``NULL`` if there are no keywords. The values of the keyword @@ -354,7 +354,7 @@ There are these calling conventions: Methods with a single object argument can be listed with the :const:`METH_O` flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument. They have the type :c:type:`PyCFunction`, with the *self* parameter, and a - :c:type:`PyObject*` parameter representing the single argument. + :c:expr:`PyObject*` parameter representing the single argument. These two constants are not used to indicate the calling convention but the @@ -520,7 +520,7 @@ Accessing attributes of extension types | | | getter and setter | +-------------+------------------+-----------------------------------+ - The ``get`` function takes one :c:type:`PyObject*` parameter (the + The ``get`` function takes one :c:expr:`PyObject*` parameter (the instance) and a function pointer (the associated ``closure``):: typedef PyObject *(*getter)(PyObject *, void *); @@ -528,7 +528,7 @@ Accessing attributes of extension types It should return a new reference on success or ``NULL`` with a set exception on failure. - ``set`` functions take two :c:type:`PyObject*` parameters (the instance and + ``set`` functions take two :c:expr:`PyObject*` parameters (the instance and the value to be set) and a function pointer (the associated ``closure``):: typedef int (*setter)(PyObject *, PyObject *, void *); diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst index 9b85522..0bfd4b3 100644 --- a/Doc/c-api/tuple.rst +++ b/Doc/c-api/tuple.rst @@ -161,7 +161,7 @@ type. .. c:type:: PyStructSequence_Field Describes a field of a struct sequence. As a struct sequence is modeled as a - tuple, all fields are typed as :c:type:`PyObject*`. The index in the + tuple, all fields are typed as :c:expr:`PyObject*`. The index in the :attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which field of the struct sequence is described. diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 2219f68..2d57a98 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -1484,7 +1484,7 @@ and :c:type:`PyType_Type` effectively act as defaults.) If the instances of this type are weakly referenceable, this field is greater than zero and contains the offset in the instance structure of the weak reference list head (ignoring the GC header, if present); this offset is used by - :c:func:`PyObject_ClearWeakRefs` and the ``PyWeakref_*`` functions. The + :c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The instance structure needs to include a field of type :c:expr:`PyObject*` which is initialized to ``NULL``. diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 62e8fd3..99c35a8 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -2366,8 +2366,8 @@ These are the fundamental ctypes data types: .. class:: py_object - Represents the C :c:type:`PyObject *` datatype. Calling this without an - argument creates a ``NULL`` :c:type:`PyObject *` pointer. + Represents the C :c:expr:`PyObject *` datatype. Calling this without an + argument creates a ``NULL`` :c:expr:`PyObject *` pointer. The :mod:`ctypes.wintypes` module provides quite some other Windows specific data types, for example :c:type:`HWND`, :c:type:`WPARAM`, or :c:type:`DWORD`. Some -- cgit v0.12 From 5f430976162804272f4f684fea186a04d48b559f Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 5 Oct 2022 01:57:30 -0700 Subject: gh-97661: Improve accuracy of sqlite3.Cursor.fetchone docs (GH-97662) Co-authored-by: C.A.M. Gerlach (cherry picked from commit 4b83cd0b22428fbfccf1f0e85c0fc36be6ab7edf) Co-authored-by: Jia Junjie <62194633+jiajunjie@users.noreply.github.com> --- Doc/library/sqlite3.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index a9d20a1..110d262 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1413,7 +1413,9 @@ Cursor objects .. method:: fetchone() - Return the next row of a query result set as a :class:`tuple`. + If :attr:`~Connection.row_factory` is ``None``, + return the next row query result set as a :class:`tuple`. + Else, pass it to the row factory and return its result. Return ``None`` if no more data is available. -- cgit v0.12 From 12bd7e9258423aac3a35e599323ada82121ae2b4 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 18:29:54 -0700 Subject: Add re.VERBOSE flag documentation example (GH-97678) The current re.VERBOSE documentation example leaves space for ambiguous interpretation. One may read that spaces within the `(?:` token are spaces inside the non-capturing group (such as `(?: )`). This patch removes the ambiguity by including examples after the statement. (cherry picked from commit 0ceafa7fa408b64377ea31dd5386152da19ef38a) Co-authored-by: Athos Ribeiro --- Doc/library/re.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/re.rst b/Doc/library/re.rst index 2392785..3a6e2e7 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -781,7 +781,8 @@ Flags more readable by allowing you to visually separate logical sections of the pattern and add comments. Whitespace within the pattern is ignored, except when in a character class, or when preceded by an unescaped backslash, - or within tokens like ``*?``, ``(?:`` or ``(?P<...>``. + or within tokens like ``*?``, ``(?:`` or ``(?P<...>``. For example, ``(? :`` + and ``* ?`` are not allowed. When a line contains a ``#`` that is not in a character class and is not preceded by an unescaped backslash, all characters from the leftmost such ``#`` through the end of the line are ignored. -- cgit v0.12 From 65b25911e319933e36bec4b773bc78c60cb9014d Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 18:08:59 -0700 Subject: gh-95913: Copyedit/improve Implementation Changes What's New section (GH-97720) * Add and refine reST/Sphinx syntax for implementation changes section * Clarify and refine wording in the Implementation Changes section * Elide unnecessary comma Co-authored-by: Ezio Melotti Co-authored-by: Ezio Melotti (cherry picked from commit 4e731814d781dae3419e981c0acc3ef833e26e8a) Co-authored-by: C.A.M. Gerlach --- Doc/whatsnew/3.11.rst | 44 +++++++++++++++++++++++++++----------------- 1 file changed, 27 insertions(+), 17 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 00068a4..aef8b8c 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -439,17 +439,24 @@ Other Language Changes there is a mixture of strings and bytes keys. (Contributed by Thomas Grainger in :gh:`91181`.) + +.. _whatsnew311-other-implementation-changes: + Other CPython Implementation Changes ==================================== -* Special methods :meth:`complex.__complex__` and :meth:`bytes.__bytes__` are implemented to - support :class:`typing.SupportsComplex` and :class:`typing.SupportsBytes` protocols. +* The special methods :meth:`~object.__complex__` for :class:`complex` + and :meth:`~object.__bytes__` for :class:`bytes` are implemented to support + the :class:`typing.SupportsComplex` and :class:`typing.SupportsBytes` protocols. (Contributed by Mark Dickinson and Dong-hee Na in :issue:`24234`.) -* ``siphash13`` is added as a new internal hashing algorithms. It has similar security - properties as ``siphash24`` but it is slightly faster for long inputs. ``str``, ``bytes``, - and some other types now use it as default algorithm for :func:`hash`. :pep:`552` - hash-based pyc files now use ``siphash13``, too. +* ``siphash13`` is added as a new internal hashing algorithm. + It has similar security properties as ``siphash24``, + but it is slightly faster for long inputs. + :class:`str`, :class:`bytes`, and some other types + now use it as the default algorithm for :func:`hash`. + :pep:`552` :ref:`hash-based .pyc files ` + now use ``siphash13`` too. (Contributed by Inada Naoki in :issue:`29410`.) * When an active exception is re-raised by a :keyword:`raise` statement with no parameters, @@ -458,25 +465,28 @@ Other CPython Implementation Changes reflected in the re-raised exception. (Contributed by Irit Katriel in :issue:`45711`.) -* The interpreter state's representation of handled exceptions (a.k.a exc_info, or - _PyErr_StackItem) now has only the ``exc_value`` field, ``exc_type`` and ``exc_traceback`` - have been removed as their values can be derived from ``exc_value``. +* The interpreter state's representation of handled exceptions + (aka ``exc_info`` or ``_PyErr_StackItem``) + now only has the ``exc_value`` field; ``exc_type`` and ``exc_traceback`` + have been removed, as they can be derived from ``exc_value``. (Contributed by Irit Katriel in :issue:`45711`.) -* A new command line option for the Windows installer ``AppendPath`` has been added. - It behaves similiar to ``PrependPath`` but appends the install and scripts directories - instead of prepending them. +* A new :ref:`command line option `, ``AppendPath``, + has been added for the Windows installer. + It behaves similarly to ``PrependPath``, + but appends the install and scripts directories instead of prepending them. (Contributed by Bastian Neuburger in :issue:`44934`.) -* The :c:member:`PyConfig.module_search_paths_set` field must now be set to 1 for +* The :c:member:`PyConfig.module_search_paths_set` field must now be set to ``1`` for initialization to use :c:member:`PyConfig.module_search_paths` to initialize :data:`sys.path`. Otherwise, initialization will recalculate the path and replace any values added to ``module_search_paths``. -* The output of the :option:`--help` option is changed to fit inside 50 lines and 80 - columns. Information about :ref:`Python environment variables ` - and :option:`-X options <-X>` is available with the new :option:`--help-env` or - :option:`--help-xoptions` flags, and with :option:`--help-all`. +* The output of the :option:`--help` option now fits in 50 lines/80 columns. + Information about :ref:`Python environment variables ` + and :option:`-X` options is now available using the respective + :option:`--help-env` and :option:`--help-xoptions` flags, + and with the new :option:`--help-all`. (Contributed by Éric Araujo in :issue:`46142`.) * Converting between :class:`int` and :class:`str` in bases other than 2 -- cgit v0.12 From 5137002179030ffd202e595ee416899a3baf524a Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 17:55:17 -0700 Subject: [3.11] gh-93738: Documentation C syntax (:c:data:`view->obj` -> :c:expr:`view->obj`) (GH-97773) (#97867) :c:data:`view->obj` -> :c:expr:`view->obj` (cherry picked from commit fa59bda8d30ea0b6c19007205b57c800c944304c) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/c-api/typeobj.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 2d57a98..4f4e239 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -2321,13 +2321,13 @@ Buffer Object Structures steps: (1) Check if the request can be met. If not, raise :c:data:`PyExc_BufferError`, - set :c:data:`view->obj` to ``NULL`` and return ``-1``. + set :c:expr:`view->obj` to ``NULL`` and return ``-1``. (2) Fill in the requested fields. (3) Increment an internal counter for the number of exports. - (4) Set :c:data:`view->obj` to *exporter* and increment :c:data:`view->obj`. + (4) Set :c:expr:`view->obj` to *exporter* and increment :c:expr:`view->obj`. (5) Return ``0``. @@ -2335,10 +2335,10 @@ Buffer Object Structures schemes can be used: * Re-export: Each member of the tree acts as the exporting object and - sets :c:data:`view->obj` to a new reference to itself. + sets :c:expr:`view->obj` to a new reference to itself. * Redirect: The buffer request is redirected to the root object of the - tree. Here, :c:data:`view->obj` will be a new reference to the root + tree. Here, :c:expr:`view->obj` will be a new reference to the root object. The individual fields of *view* are described in section @@ -2380,7 +2380,7 @@ Buffer Object Structures *view* argument. - This function MUST NOT decrement :c:data:`view->obj`, since that is + This function MUST NOT decrement :c:expr:`view->obj`, since that is done automatically in :c:func:`PyBuffer_Release` (this scheme is useful for breaking reference cycles). -- cgit v0.12 From aa7893bbaf69e6c1a1a9f6e6d58696993c85c6c3 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 17:53:48 -0700 Subject: [3.11] gh-93738: Documentation C syntax (:c:type:`PyInterpreterState *` -> :c:expr:`PyInterpreterState *`) (GH-97777) (#97865) :c:type:`PyInterpreterState *` -> :c:expr:`PyInterpreterState *` (cherry picked from commit 4ebb0250314b57637d213cd5bc5f5ce5dd911d94) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/c-api/init.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index f2473bb..4c0731e 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -914,7 +914,7 @@ code, or when embedding the Python interpreter: .. c:type:: PyThreadState This data structure represents the state of a single thread. The only public - data member is :attr:`interp` (:c:type:`PyInterpreterState *`), which points to + data member is :attr:`interp` (:c:expr:`PyInterpreterState *`), which points to this thread's interpreter state. -- cgit v0.12 From 56aaff4631499c5baa514b51ac45e843d6daf3dc Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 17:48:24 -0700 Subject: [3.11] gh-93738: Documentation C syntax (:c:type:`TYPE` -> :c:expr:`TYPE`) (GH-97770) (#97874) :c:type:`TYPE` -> :c:expr:`TYPE` (cherry picked from commit 8b211b4cdbcddecfcc4d1682864795b5f1438c59) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/c-api/memory.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst index f314563..f726cd4 100644 --- a/Doc/c-api/memory.rst +++ b/Doc/c-api/memory.rst @@ -265,14 +265,14 @@ The following type-oriented macros are provided for convenience. Note that .. c:function:: TYPE* PyMem_New(TYPE, size_t n) Same as :c:func:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes of - memory. Returns a pointer cast to :c:type:`TYPE*`. The memory will not have + memory. Returns a pointer cast to :c:expr:`TYPE*`. The memory will not have been initialized in any way. .. c:function:: TYPE* PyMem_Resize(void *p, TYPE, size_t n) Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n * - sizeof(TYPE))`` bytes. Returns a pointer cast to :c:type:`TYPE*`. On return, + sizeof(TYPE))`` bytes. Returns a pointer cast to :c:expr:`TYPE*`. On return, *p* will be a pointer to the new memory area, or ``NULL`` in the event of failure. -- cgit v0.12 From 9b73bd434584c71ddb86fc5445289bee60812edf Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 17:47:02 -0700 Subject: [3.11] gh-93738: Documentation C syntax (:c:type:`FILE` -> :c:expr:`FILE`) (GH-97769) (#97871) :c:type:`FILE` -> :c:expr:`FILE` (cherry picked from commit 192d401ba53224020f5f9ca6e1ff2c9f89511ac4) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/c-api/file.rst | 2 +- Doc/c-api/marshal.rst | 8 ++++---- Doc/c-api/veryhigh.rst | 6 +++--- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst index 3e5c9ea..58ed58e 100644 --- a/Doc/c-api/file.rst +++ b/Doc/c-api/file.rst @@ -8,7 +8,7 @@ File Objects .. index:: object: file These APIs are a minimal emulation of the Python 2 C API for built-in file -objects, which used to rely on the buffered I/O (:c:type:`FILE*`) support +objects, which used to rely on the buffered I/O (:c:expr:`FILE*`) support from the C standard library. In Python 3, files and streams use the new :mod:`io` module, which defines several layers over the low-level unbuffered I/O of the operating system. The functions described below are diff --git a/Doc/c-api/marshal.rst b/Doc/c-api/marshal.rst index bf8373a..571d68c 100644 --- a/Doc/c-api/marshal.rst +++ b/Doc/c-api/marshal.rst @@ -43,7 +43,7 @@ The following functions allow marshalled values to be read back in. .. c:function:: long PyMarshal_ReadLongFromFile(FILE *file) - Return a C :c:expr:`long` from the data stream in a :c:expr:`FILE*` opened + Return a C :c:type:`long` from the data stream in a :c:expr:`FILE*` opened for reading. Only a 32-bit value can be read in using this function, regardless of the native size of :c:expr:`long`. @@ -53,7 +53,7 @@ The following functions allow marshalled values to be read back in. .. c:function:: int PyMarshal_ReadShortFromFile(FILE *file) - Return a C :c:expr:`short` from the data stream in a :c:expr:`FILE*` opened + Return a C :c:type:`short` from the data stream in a :c:expr:`FILE*` opened for reading. Only a 16-bit value can be read in using this function, regardless of the native size of :c:expr:`short`. @@ -63,7 +63,7 @@ The following functions allow marshalled values to be read back in. .. c:function:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file) - Return a Python object from the data stream in a :c:type:`FILE*` opened for + Return a Python object from the data stream in a :c:expr:`FILE*` opened for reading. On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError` @@ -72,7 +72,7 @@ The following functions allow marshalled values to be read back in. .. c:function:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file) - Return a Python object from the data stream in a :c:type:`FILE*` opened for + Return a Python object from the data stream in a :c:expr:`FILE*` opened for reading. Unlike :c:func:`PyMarshal_ReadObjectFromFile`, this function assumes that no further objects will be read from the file, allowing it to aggressively load file data into memory so that the de-serialization can diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index 365a2b5..bfb14ac 100644 --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -16,11 +16,11 @@ parameter. The available start symbols are :const:`Py_eval_input`, :const:`Py_file_input`, and :const:`Py_single_input`. These are described following the functions which accept them as parameters. -Note also that several of these functions take :c:type:`FILE*` parameters. One -particular issue which needs to be handled carefully is that the :c:type:`FILE` +Note also that several of these functions take :c:expr:`FILE*` parameters. One +particular issue which needs to be handled carefully is that the :c:expr:`FILE` structure for different C libraries can be different and incompatible. Under Windows (at least), it is possible for dynamically linked extensions to actually -use different libraries, so care should be taken that :c:type:`FILE*` parameters +use different libraries, so care should be taken that :c:expr:`FILE*` parameters are only passed to these functions if it is certain that they were created by the same library that the Python runtime is using. -- cgit v0.12 From ab665d9b6770ecda35e8ce8050a0b7d423f782d1 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 16:46:13 -0700 Subject: [3.11] gh-93738: Documentation C syntax (:c:type:`PyTupleObject*` -> :c:expr:`PyTupleObject*`) (GH-97780) (#97863) :c:type:`PyTupleObject*` -> :c:expr:`PyTupleObject*` (cherry picked from commit 510baa429affb832d7b4ed68182e59daa2815d2e) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/c-api/typehints.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/typehints.rst b/Doc/c-api/typehints.rst index 4c1957a..88554a3 100644 --- a/Doc/c-api/typehints.rst +++ b/Doc/c-api/typehints.rst @@ -15,7 +15,7 @@ two types exist -- :ref:`GenericAlias ` and Equivalent to calling the Python class :class:`types.GenericAlias`. The *origin* and *args* arguments set the ``GenericAlias``\ 's ``__origin__`` and ``__args__`` attributes respectively. - *origin* should be a :c:expr:`PyTypeObject*`, and *args* can be a + *origin* should be a :c:type:`PyTypeObject*`, and *args* can be a :c:expr:`PyTupleObject*` or any ``PyObject*``. If *args* passed is not a tuple, a 1-tuple is automatically constructed and ``__args__`` is set to ``(args,)``. -- cgit v0.12 From 0679066d940691e91989d55e885d54824bd88cd8 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 16:40:47 -0700 Subject: [3.11] gh-93738: Documentation C syntax (:c:type:`PyBytesObject*` -> :c:expr:`PyBytesObject*`) (GH-97782) (#97861) :c:type:`PyBytesObject*` -> :c:expr:`PyBytesObject*` (cherry picked from commit 9ebc50866b58a0ee2985c6540a67fee8a4a49e4d) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/c-api/unicode.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index e1c1e06..1fb6d4d 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -849,7 +849,7 @@ argument parsing, the ``"O&"`` converter should be used, passing ParseTuple converter: encode :class:`str` objects -- obtained directly or through the :class:`os.PathLike` interface -- to :class:`bytes` using :c:func:`PyUnicode_EncodeFSDefault`; :class:`bytes` objects are output as-is. - *result* must be a :c:type:`PyBytesObject*` which must be released when it is + *result* must be a :c:expr:`PyBytesObject*` which must be released when it is no longer used. .. versionadded:: 3.1 -- cgit v0.12 From 264b615d9b899894880c01b7ffb22c8e1a33bf4d Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 16:38:58 -0700 Subject: [3.11] gh-93738: Documentation C syntax (:c:type:`PyUnicodeObject*` -> :c:expr:`PyUnicodeObject*`) (GH-97783) (#97859) :c:type:`PyUnicodeObject*` -> :c:expr:`PyUnicodeObject*` (cherry picked from commit 898834e27b82bd1f3532b6448a862a7a9cdeff66) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/c-api/unicode.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 1fb6d4d..e72f151 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -866,7 +866,7 @@ conversion function: ParseTuple converter: decode :class:`bytes` objects -- obtained either directly or indirectly through the :class:`os.PathLike` interface -- to :class:`str` using :c:func:`PyUnicode_DecodeFSDefaultAndSize`; :class:`str` - objects are output as-is. *result* must be a :c:type:`PyUnicodeObject*` which + objects are output as-is. *result* must be a :c:expr:`PyUnicodeObject*` which must be released when it is no longer used. .. versionadded:: 3.2 -- cgit v0.12 From 232a40206ae1914b53d124888381da69d4d55cd0 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 16:38:24 -0700 Subject: [3.11] gh-93738: Documentation C syntax (:c:type:`Py_UNICODE*` -> :c:expr:`Py_UNICODE*`) (GH-97784) (#97857) :c:type:`Py_UNICODE*` -> :c:expr:`Py_UNICODE*` (cherry picked from commit a081cae2a2cd1248ad067c3f7dc218ea7e3d203a) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/whatsnew/3.3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/whatsnew/3.3.rst b/Doc/whatsnew/3.3.rst index 695621b..237e457 100644 --- a/Doc/whatsnew/3.3.rst +++ b/Doc/whatsnew/3.3.rst @@ -2267,7 +2267,7 @@ The :c:type:`Py_UNICODE` has been deprecated by :pep:`393` and will be removed in Python 4. All functions using this type are deprecated: Unicode functions and methods using :c:type:`Py_UNICODE` and -:c:type:`Py_UNICODE*` types: +:c:expr:`Py_UNICODE*` types: * :c:macro:`PyUnicode_FromUnicode`: use :c:func:`PyUnicode_FromWideChar` or :c:func:`PyUnicode_FromKindAndData` -- cgit v0.12 From 52709b20998330108b50406df7b16133c37fb5e1 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 16:24:50 -0700 Subject: gh-95913: Copyedit/improve Other Language Changes What's New section (GH-97719) * Add/refine cross references to items in other lang changes section * Unify context manager exception changes into single non-repetitive item * More clearly describe the intent and consequences of the -P option * Apply minor clarifications & copyedits to rest of section * Tweak the formatting of module references Co-authored-by: Ezio Melotti Co-authored-by: Ezio Melotti (cherry picked from commit a77d9dedcd0d52c2663e9de4417dec9d1c5199f4) Co-authored-by: C.A.M. Gerlach --- Doc/whatsnew/3.11.rst | 67 +++++++++++++++++++++++++++------------------------ 1 file changed, 36 insertions(+), 31 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index aef8b8c..1e2bec0 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -391,52 +391,57 @@ detected by checking its tag for a ``-32`` suffix. All releases of Python since 3.5 have included this in their 32-bit builds. +.. _whatsnew311-other-lang-changes: + Other Language Changes ====================== -* Starred expressions can be used in :ref:`for statements`. (See - :issue:`46725` for more details.) - -* Asynchronous comprehensions are now allowed inside comprehensions in - asynchronous functions. Outer comprehensions implicitly become - asynchronous. (Contributed by Serhiy Storchaka in :issue:`33346`.) +* Starred unpacking expressions can now be used in :keyword:`for` statements. + (See :issue:`46725` for more details.) -* A :exc:`TypeError` is now raised instead of an :exc:`AttributeError` in - :meth:`contextlib.ExitStack.enter_context` and - :meth:`contextlib.AsyncExitStack.enter_async_context` for objects which do not - support the :term:`context manager` or :term:`asynchronous context manager` - protocols correspondingly. - (Contributed by Serhiy Storchaka in :issue:`44471`.) +* Asynchronous :ref:`comprehensions ` are now allowed + inside comprehensions in :ref:`asynchronous functions `. + Outer comprehensions implicitly become asynchronous in this case. + (Contributed by Serhiy Storchaka in :issue:`33346`.) * A :exc:`TypeError` is now raised instead of an :exc:`AttributeError` in - :keyword:`with` and :keyword:`async with` statements for objects which do not - support the :term:`context manager` or :term:`asynchronous context manager` - protocols correspondingly. - (Contributed by Serhiy Storchaka in :issue:`12022`.) - -* Added :meth:`object.__getstate__` which provides the default - implementation of the ``__getstate__()`` method. :mod:`Copying ` - and :mod:`pickling ` instances of subclasses of builtin types + :keyword:`with` statements and :meth:`contextlib.ExitStack.enter_context` + for objects that do not support the :term:`context manager` protocol, + and in :keyword:`async with` statements and + :meth:`contextlib.AsyncExitStack.enter_async_context` + for objects not supporting the :term:`asynchronous context manager` protocol. + (Contributed by Serhiy Storchaka in :issue:`12022` and :issue:`44471`.) + +* Added :meth:`object.__getstate__`, which provides the default + implementation of the :meth:`!__getstate__` method. :mod:`copy`\ing + and :mod:`pickle`\ing instances of subclasses of builtin types :class:`bytearray`, :class:`set`, :class:`frozenset`, :class:`collections.OrderedDict`, :class:`collections.deque`, :class:`weakref.WeakSet`, and :class:`datetime.tzinfo` now copies and pickles instance attributes implemented as :term:`slots <__slots__>`. (Contributed by Serhiy Storchaka in :issue:`26579`.) -* Add :option:`-P` command line option and :envvar:`PYTHONSAFEPATH` environment - variable to not prepend a potentially unsafe path to :data:`sys.path` such as - the current directory, the script's directory or an empty string. +* Added a :option:`-P` command line option + and a :envvar:`PYTHONSAFEPATH` environment variable, + which disable the automatic prepending to :data:`sys.path` + of the script's directory when running a script, + or the current directory when using :option:`-c` and :option:`-m`. + This ensures only stdlib and installed modules + are picked up by :keyword:`import`, + and avoids unintentionally or maliciously shadowing modules + with those in a local (and typically user-writable) directory. (Contributed by Victor Stinner in :gh:`57684`.) -* A ``"z"`` option was added to the format specification mini-language that - coerces negative zero to zero after rounding to the format precision. See - :pep:`682` for more details. (Contributed by John Belmonte in :gh:`90153`.) +* A ``"z"`` option was added to the :ref:`formatspec` that + coerces negative to positive zero after rounding to the format precision. + See :pep:`682` for more details. + (Contributed by John Belmonte in :gh:`90153`.) -* Bytes are no longer accepted on :attr:`sys.path`. Support broke sometime - between Python 3.2 and 3.6 with no one noticing until after Python 3.10.0 - was released. Bringing back support would also be problematic due to - interactions between :option:`-b` and :attr:`sys.path_importer_cache` when - there is a mixture of strings and bytes keys. +* Bytes are no longer accepted on :data:`sys.path`. Support broke sometime + between Python 3.2 and 3.6, with no one noticing until after Python 3.10.0 + was released. In addition, bringing back support would be problematic due to + interactions between :option:`-b` and :data:`sys.path_importer_cache` when + there is a mixture of :class:`str` and :class:`bytes` keys. (Contributed by Thomas Grainger in :gh:`91181`.) -- cgit v0.12 From 028e7d47cdca63ac544cc2aa54df18d1b39811cf Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 15:58:59 -0700 Subject: gh-95913: Move py.exe to appropriate What's New section & refine text (GH-97718) * Move Windows py.exe improvements from Typing section to New Features * Add ref target label and use literal for py.exe * Be clearer/explict about what legacy version arg components reprisent * Apply other minor clarity and textual fixes to py.exe launcher text * Refine phrasing of legacy sentence of py.exe desc Co-authored-by: Ezio Melotti Co-authored-by: Ezio Melotti (cherry picked from commit 985958187d578cfa311e404588950b29fda95db7) Co-authored-by: C.A.M. Gerlach --- Doc/whatsnew/3.11.rst | 50 ++++++++++++++++++++++++++------------------------ 1 file changed, 26 insertions(+), 24 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 1e2bec0..9d24d42 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -202,6 +202,32 @@ default traceback. See :pep:`678` for more details. (Contributed by Irit Katriel in :issue:`45607`.) +.. _whatsnew311-windows-launcher: + +Windows ``py.exe`` launcher improvements +---------------------------------------- + +The copy of the :ref:`launcher` included with Python 3.11 has been significantly +updated. It now supports company/tag syntax as defined in :pep:`514` using the +``-V:/`` argument instead of the limited ``-.``. +This allows launching distributions other than ``PythonCore``, +the one hosted on `python.org `_. + +When using ``-V:`` selectors, either company or tag can be omitted, but all +installs will be searched. For example, ``-V:OtherPython/`` will select the +"best" tag registered for ``OtherPython``, while ``-V:3.11`` or ``-V:/3.11`` +will select the "best" distribution with tag ``3.11``. + +When using the legacy ``-``, ``-.``, +``--`` or ``-.-`` arguments, +all existing behaviour should be preserved from past versions, +and only releases from ``PythonCore`` will be selected. +However, the ``-64`` suffix now implies "not 32-bit" (not necessarily x86-64), +as there are multiple supported 64-bit platforms. +32-bit runtimes are detected by checking the runtime's tag for a ``-32`` suffix. +All releases of Python since 3.5 have included this in their 32-bit builds. + + .. _new-feat-related-type-hints-311: New Features Related to Type Hints @@ -369,30 +395,6 @@ PEP 563 May Not Be the Future that was planned for this release has been indefinitely postponed. See `this message `_ for more information. -Windows py.exe launcher improvements ------------------------------------- - -The copy of :ref:`launcher` included with Python 3.11 has been significantly -updated. It now supports company/tag syntax as defined in :pep:`514` using the -``-V:/`` argument instead of the limited ``-x.y`` argument. This -allows launching distributions other than ``PythonCore``, which is the one -obtained from `python.org `_. - -When using ``-V:`` selectors, either company or tag can be omitted, but all -installs will be searched. For example, ``-V:OtherPython/`` will select the -"best" tag registered for ``OtherPython``, while ``-V:3.11`` or ``-V:/3.11`` -will select the "best" distribution with tag ``3.11``. - -When using legacy ``-x``, ``-x.y``, ``-x-ZZ`` or ``-x.y-ZZ`` arguments, all -existing behaviour should be preserved from past versions. Only releases from -``PythonCore`` will be selected. However, the ``-64`` suffix now implies "not -32-bit", as there are multiple supported 64-bit platforms. 32-bit runtimes are -detected by checking its tag for a ``-32`` suffix. All releases of Python -since 3.5 have included this in their 32-bit builds. - - -.. _whatsnew311-other-lang-changes: - Other Language Changes ====================== -- cgit v0.12 From 95f7ed8b079b5e5159633f00a8bd05058aef1eb4 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 15:55:34 -0700 Subject: [3.11] gh-88355: Fix backslashes in AF_PIPE (GH-96543) (#97854) gh-88355: Fix backslashes in AF_PIPE (GH-96543) Fix backslashes in AF_PIPE (GH-88355) The correct syntax for AF_PIPE addresses is `\\.\pipe\blahblah`, not `\.\pipe{blahblah}`, but the syntax markup messed up the backslashes. (cherry picked from commit ff28d8926de92d809e3b7f71d3e44672178ed11e) Co-authored-by: cousteau Co-authored-by: cousteau --- Doc/library/multiprocessing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 74e3377..a51fc85 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -2630,9 +2630,9 @@ Address Formats filesystem. * An ``'AF_PIPE'`` address is a string of the form - :samp:`r'\\\\.\\pipe\\{PipeName}'`. To use :func:`Client` to connect to a named + :samp:`r'\\\\\\.\\pipe\\\\{PipeName}'`. To use :func:`Client` to connect to a named pipe on a remote computer called *ServerName* one should use an address of the - form :samp:`r'\\\\{ServerName}\\pipe\\{PipeName}'` instead. + form :samp:`r'\\\\\\\\{ServerName}\\pipe\\\\{PipeName}'` instead. Note that any string beginning with two backslashes is assumed by default to be an ``'AF_PIPE'`` address rather than an ``'AF_UNIX'`` address. -- cgit v0.12 From ed772a817ed8dce41b2bd20700e08f1475e49163 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 15:21:28 -0700 Subject: [3.11] gh-96448: fix documentation for _thread.lock.acquire (GH-96449) (#97851) gh-96448: fix documentation for _thread.lock.acquire (GH-96449) * fix documentation for _thread.lock.acquire * update formatting of _thread.lock.acquire() doc (cherry picked from commit 7acb93f0d44c6fb971fdb09b86f68896e3b1e2f8) Co-authored-by: Daniel Giger Co-authored-by: Daniel Giger --- Doc/library/_thread.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/_thread.rst b/Doc/library/_thread.rst index ea4aa30..ecd7a68 100644 --- a/Doc/library/_thread.rst +++ b/Doc/library/_thread.rst @@ -157,21 +157,21 @@ This module defines the following constants and functions: Lock objects have the following methods: -.. method:: lock.acquire(waitflag=1, timeout=-1) +.. method:: lock.acquire(blocking=True, timeout=-1) Without any optional argument, this method acquires the lock unconditionally, if necessary waiting until it is released by another thread (only one thread at a time can acquire a lock --- that's their reason for existence). - If the integer *waitflag* argument is present, the action depends on its - value: if it is zero, the lock is only acquired if it can be acquired - immediately without waiting, while if it is nonzero, the lock is acquired + If the *blocking* argument is present, the action depends on its + value: if it is False, the lock is only acquired if it can be acquired + immediately without waiting, while if it is True, the lock is acquired unconditionally as above. If the floating-point *timeout* argument is present and positive, it specifies the maximum wait time in seconds before returning. A negative *timeout* argument specifies an unbounded wait. You cannot specify - a *timeout* if *waitflag* is zero. + a *timeout* if *blocking* is False. The return value is ``True`` if the lock is acquired successfully, ``False`` if not. -- cgit v0.12 From 7ddd0d3194c411fb3db7e86b30dc8209a9ccda0c Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 15:14:52 -0700 Subject: gh-90301: Doc: Add references to PEP 686 (GH-96816) Doc: Add references to PEP 686. (cherry picked from commit 87679a6e607eec1134d77222a3a92d0d11f768ad) Co-authored-by: Inada Naoki --- Doc/library/io.rst | 16 +++++++++------- Doc/library/os.rst | 5 +++++ 2 files changed, 14 insertions(+), 7 deletions(-) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 03c90ad..8fd6b35 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -123,17 +123,19 @@ encoding is not UTF-8 for most Windows users. For example:: with open("README.md") as f: long_description = f.read() -Additionally, while there is no concrete plan as of yet, Python may change -the default text file encoding to UTF-8 in the future. - Accordingly, it is highly recommended that you specify the encoding explicitly when opening text files. If you want to use UTF-8, pass ``encoding="utf-8"``. To use the current locale encoding, -``encoding="locale"`` is supported in Python 3.10. +``encoding="locale"`` is supported since Python 3.10. + +.. seealso:: + + :ref:`utf8-mode` + Python UTF-8 Mode can be used to change the default encoding to + UTF-8 from locale-specific encoding. -When you need to run existing code on Windows that attempts to open -UTF-8 files using the default locale encoding, you can enable the UTF-8 -mode. See :ref:`UTF-8 mode on Windows `. + :pep:`686` + Python 3.15 will make :ref:`utf8-mode` default. .. _io-encoding-warning: diff --git a/Doc/library/os.rst b/Doc/library/os.rst index c667592..7185016 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -159,6 +159,11 @@ can be read from :data:`sys.flags.utf8_mode `. See also the :ref:`UTF-8 mode on Windows ` and the :term:`filesystem encoding and error handler`. +.. seealso:: + + :pep:`686` + Python 3.15 will make :ref:`utf8-mode` default. + .. _os-procinfo: -- cgit v0.12 From 9d49bd4773cc2018cbe0af9e370a60f592c3a1bf Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 11:45:02 -0700 Subject: GH-95913: Update what's new in 3.11 for asyncio (GH-97806) Co-authored-by: Kumar Aditya <59607654+kumaraditya303@users.noreply.github.com> Co-authored-by: C.A.M. Gerlach Co-authored-by: Jelle Zijlstra (cherry picked from commit 9fbfa42ece3e0256657ce2594c7c3eb8b3ac8ff3) Co-authored-by: Guido van Rossum --- Doc/whatsnew/3.11.rst | 56 ++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 40 insertions(+), 16 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 9d24d42..1b25a9e 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -522,27 +522,51 @@ New Modules Improved Modules ================ +.. _whatsnew311-asyncio: + asyncio ------- -* Add raw datagram socket functions to the event loop: - :meth:`~asyncio.AbstractEventLoop.sock_sendto`, - :meth:`~asyncio.AbstractEventLoop.sock_recvfrom` and - :meth:`~asyncio.AbstractEventLoop.sock_recvfrom_into`. - (Contributed by Alex Grönholm in :issue:`46805`.) - -* Add :meth:`~asyncio.streams.StreamWriter.start_tls` method for upgrading - existing stream-based connections to TLS. (Contributed by Ian Good in - :issue:`34975`.) - -* Add :class:`~asyncio.Barrier` class to the synchronization primitives of - the asyncio library. (Contributed by Yves Duprat and Andrew Svetlov in - :gh:`87518`.) - -* Add :class:`~asyncio.TaskGroup` class, +* Added the :class:`~asyncio.TaskGroup` class, an :ref:`asynchronous context manager ` holding a group of tasks that will wait for all of them upon exit. - (Contributed by Yury Seliganov and others.) + For new code this is recommended over using + :func:`~asyncio.create_task` and :func:`~asyncio.gather` directly. + (Contributed by Yury Selivanov and others in :gh:`90908`.) + +* Added :func:`~asyncio.timeout`, an asynchronous context manager for + setting a timeout on asynchronous operations. For new code this is + recommended over using :func:`~asyncio.wait_for` directly. + (Contributed by Andrew Svetlov in :gh:`90927`.) + +* Added the :class:`~asyncio.Runner` class, which exposes the machinery + used by :func:`~asyncio.run`. + (Contributed by Andrew Svetlov in :gh:`91218`.) + +* Added the :class:`~asyncio.Barrier` class to the synchronization + primitives in the asyncio library, and the related + :exc:`~asyncio.BrokenBarrierError` exception. + (Contributed by Yves Duprat and Andrew Svetlov in :gh:`87518`.) + +* Added keyword argument *all_errors* to :meth:`asyncio.loop.create_connection` + so that multiple connection errors can be raised as an :exc:`ExceptionGroup`. + +* Added the :meth:`asyncio.StreamWriter.start_tls` method for + upgrading existing stream-based connections to TLS. + (Contributed by Ian Good in :issue:`34975`.) + +* Added raw datagram socket functions to the event loop: + :meth:`~asyncio.loop.sock_sendto`, + :meth:`~asyncio.loop.sock_recvfrom` and + :meth:`~asyncio.loop.sock_recvfrom_into`. + These have implementations in :class:`~asyncio.SelectorEventLoop` and + :class:`~asyncio.ProactorEventLoop`. + (Contributed by Alex Grönholm in :issue:`46805`.) + +* Added :meth:`~asyncio.Task.cancelling` and + :meth:`~asyncio.Task.uncancel` methods to :class:`~asyncio.Task`. + These are primarily intended for internal use, + notably by :class:`~asyncio.TaskGroup`. contextlib ---------- -- cgit v0.12 From c6bf822a894d32f24d42ebbe65ec0172ab4ee4f6 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 09:52:28 -0700 Subject: GH-82604: fix docs about configuring selector (GH-97755) (cherry picked from commit 53503ff60e9a4727af0d9a1096418675e72a0fae) Co-authored-by: Kumar Aditya <59607654+kumaraditya303@users.noreply.github.com> --- Doc/library/asyncio-eventloop.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index de2ecdc..41ebc04 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -1638,9 +1638,12 @@ on Unix and :class:`ProactorEventLoop` on Windows. import asyncio import selectors - selector = selectors.SelectSelector() - loop = asyncio.SelectorEventLoop(selector) - asyncio.set_event_loop(loop) + class MyPolicy(asyncio.DefaultEventLoopPolicy): + def new_event_loop(self): + selector = selectors.SelectSelector() + return asyncio.SelectorEventLoop(selector) + + asyncio.set_event_loop_policy(MyPolicy()) .. availability:: Unix, Windows. -- cgit v0.12 From e232e49e867b3ba692277d33a08ac3c5149db805 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 09:13:37 -0700 Subject: gh-97754: Update doc for default location of per-user installs on Windows (GH-97756) (cherry picked from commit a120b9f25d037a1c794df731f8cc6a2898a9165e) Co-authored-by: Ben Faulhaber <111227622+faulhaberben@users.noreply.github.com> --- Doc/using/windows.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst index 210920d..84441a5 100644 --- a/Doc/using/windows.rst +++ b/Doc/using/windows.rst @@ -150,11 +150,14 @@ of available options is shown below. | | | Python X.Y` | +---------------------------+--------------------------------------+--------------------------+ | DefaultJustForMeTargetDir | The default install directory for | :file:`%LocalAppData%\\\ | -| | just-for-me installs | Programs\\PythonXY` or | +| | just-for-me installs | Programs\\Python\\\ | +| | | PythonXY` or | | | | :file:`%LocalAppData%\\\ | -| | | Programs\\PythonXY-32` or| +| | | Programs\\Python\\\ | +| | | PythonXY-32` or | | | | :file:`%LocalAppData%\\\ | -| | | Programs\\PythonXY-64` | +| | | Programs\\Python\\\ | +| | | PythonXY-64` | +---------------------------+--------------------------------------+--------------------------+ | DefaultCustomTargetDir | The default custom install directory | (empty) | | | displayed in the UI | | -- cgit v0.12 From 746fb3c91d11c70a8ed8b80c3027f511f24cf7a8 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 4 Oct 2022 06:15:46 -0700 Subject: Adjust stable ABI internal documentation (GH-96896) I was perusing this file, and noticed that this part of the documentation is slightly out of date: the `struct` items in this TOML file currently contain `struct_abi_kind` members, which distinguish between the different types of ABI compatibility described in the comment. I've updated the comment to reflect this. (cherry picked from commit 6e533088290b909df324615df24286489603989f) Co-authored-by: William Woodruff --- Misc/stable_abi.toml | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/Misc/stable_abi.toml b/Misc/stable_abi.toml index e34bfcd..50dbb0c 100644 --- a/Misc/stable_abi.toml +++ b/Misc/stable_abi.toml @@ -13,13 +13,8 @@ # The current format is TOML. # There are these kinds of top-level "items": -# - struct: A C struct. Currently this file does not distinguish between: -# - opaque structs, which the Limited API only handles via pointers -# (so these can change at any time) -# - structs where only certain members are part of the stable ABI (e.g. -# PyObject) -# - structs which must not be changed at all (e.g. PyType_Slot, which is -# fully defined and used in arrays) +# - struct: A C struct. See `struct_abi_kind` for how much of the struct is +# exposed. # - function: A function that must be kept available (and exported, i.e. not # converted to a macro). # - const: A simple value, defined with `#define`. @@ -42,6 +37,18 @@ # of the stable ABI. # - a combination of the above (functions that were called by macros that # were public in the past) +# - struct_abi_kind: for `struct`, defines how much of the struct is exposed: +# - 'full-abi': All of the struct is part of the ABI, including the size +# (users may define arrays of these structs). +# Typically used for initalization, rather than at runtime. +# - 'opaque': No members are part of the ABI, nor is the size. The Limited +# API only handles these via pointers. The C definition should be +# incomplete (opaque). +# - 'members': Only specific members are part of the stable ABI. +# The struct's size may change, so it can't be used in arrays. +# Do not add new structs of this kind without an extremely good reason. +# - members: For `struct` with struct_abi_kind = 'members', a list of the +# exposed members. # - doc: for `feature_macro`, the blurb added in documentation # - windows: for `feature_macro`, this macro is defined on Windows. # (This info is used to generate the DLL manifest and needs to be available -- cgit v0.12 From 4dda0c817391ed7bdd5ebf5f4aa3e389a1f735f1 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 3 Oct 2022 22:43:00 -0700 Subject: gh-97709: Included newline separator in Mandelbrot set (GH-97737) Included newline separator in Mandelbrot set Now the Mandelbrot set one-liner example on separates the lines with a '\n' character. (cherry picked from commit 49802605f8e47c5c7ddc8a6cecdf4afe44765586) Co-authored-by: matheusja --- Doc/faq/programming.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index 6514c00..c056446 100644 --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -735,7 +735,7 @@ Is it possible to write obfuscated one-liners in Python? -------------------------------------------------------- Yes. Usually this is done by nesting :keyword:`lambda` within -:keyword:`!lambda`. See the following three examples, due to Ulf Bartelt:: +:keyword:`!lambda`. See the following three examples, slightly adapted from Ulf Bartelt:: from functools import reduce @@ -748,7 +748,7 @@ Yes. Usually this is done by nesting :keyword:`lambda` within f(x,f), range(10)))) # Mandelbrot set - print((lambda Ru,Ro,Iu,Io,IM,Sx,Sy:reduce(lambda x,y:x+y,map(lambda y, + print((lambda Ru,Ro,Iu,Io,IM,Sx,Sy:reduce(lambda x,y:x+'\n'+y,map(lambda y, Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,Sy=Sy,L=lambda yc,Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,i=IM, Sx=Sx,Sy=Sy:reduce(lambda x,y:x+y,map(lambda x,xc=Ru,yc=yc,Ru=Ru,Ro=Ro, i=i,Sx=Sx,F=lambda xc,yc,x,y,k,f=lambda xc,yc,x,y,k,f:(k<=0)or (x*x+y*y -- cgit v0.12 From d21bef549bedf58a2b33deb2dacc563c0f9a7a86 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 3 Oct 2022 18:55:04 -0700 Subject: gh-93738: Documentation C syntax (:c:data:`0` -> ``0``) (GH-97771) :c:data:`0` -> ``0`` (cherry picked from commit 5e997cff3e1dea24241726338457611beb8882ec) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/c-api/exceptions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 6c89488..087e0a6 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -189,7 +189,7 @@ For convenience, some of these functions will always return a .. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr) This is a convenience function to raise :exc:`WindowsError`. If called with - *ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastError` + *ierr* of ``0``, the error code returned by a call to :c:func:`GetLastError` is used instead. It calls the Win32 function :c:func:`FormatMessage` to retrieve the Windows description of error code given by *ierr* or :c:func:`GetLastError`, then it constructs a tuple object whose first item is the *ierr* value and whose -- cgit v0.12 From fb0d9316efe00481ceb2c7f437d09da11e917651 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 3 Oct 2022 16:35:10 -0700 Subject: Update http.client.rst (GH-24803) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Update http.client.rst * Apply suggestions from code review Co-authored-by: Éric * Update http.client.rst Co-authored-by: Éric Co-authored-by: Senthil Kumaran (cherry picked from commit 0c91a125116b21e91d0d1cca457da830348f0806) Co-authored-by: Géry Ogam --- Doc/library/http.client.rst | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst index 16823ec..b7c94c9 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -61,7 +61,7 @@ The module provides the following classes: .. versionchanged:: 3.4 The *strict* parameter was removed. HTTP 0.9-style "Simple Responses" are - not longer supported. + no longer supported. .. versionchanged:: 3.7 *blocksize* parameter was added. @@ -474,7 +474,7 @@ statement. Return the value of the header *name*, or *default* if there is no header matching *name*. If there is more than one header with the name *name*, - return all of the values joined by ', '. If 'default' is any iterable other + return all of the values joined by ', '. If *default* is any iterable other than a single string, its elements are similarly returned joined by commas. .. method:: HTTPResponse.getheaders() @@ -578,7 +578,7 @@ Here is an example session that uses the ``HEAD`` method. Note that the >>> data == b'' True -Here is an example session that shows how to ``POST`` requests:: +Here is an example session that uses the ``POST`` method:: >>> import http.client, urllib.parse >>> params = urllib.parse.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'}) @@ -594,14 +594,13 @@ Here is an example session that shows how to ``POST`` requests:: b'Redirecting to https://bugs.python.org/issue12524' >>> conn.close() -Client side ``HTTP PUT`` requests are very similar to ``POST`` requests. The -difference lies only the server side where HTTP server will allow resources to -be created via ``PUT`` request. It should be noted that custom HTTP methods +Client side HTTP ``PUT`` requests are very similar to ``POST`` requests. The +difference lies only on the server side where HTTP servers will allow resources to +be created via ``PUT`` requests. It should be noted that custom HTTP methods are also handled in :class:`urllib.request.Request` by setting the appropriate -method attribute. Here is an example session that shows how to send a ``PUT`` -request using http.client:: +method attribute. Here is an example session that uses the ``PUT`` method:: - >>> # This creates an HTTP message + >>> # This creates an HTTP request >>> # with the content of BODY as the enclosed representation >>> # for the resource http://localhost:8080/file ... -- cgit v0.12 From 4f254f61205ac6cce47eac4dd32a40d33093fd14 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 3 Oct 2022 16:30:07 -0700 Subject: Minor grammar changes to http.client docs (GH-96221) Minor grammar changes (cherry picked from commit d053c47bfde1b3d8779546b980849708662f2660) Co-authored-by: Rohan Shah <57906961+rshah713@users.noreply.github.com> --- Doc/library/http.client.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst index b7c94c9..06f9251 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -14,7 +14,7 @@ -------------- -This module defines classes which implement the client side of the HTTP and +This module defines classes that implement the client side of the HTTP and HTTPS protocols. It is normally not used directly --- the module :mod:`urllib.request` uses it to handle URLs that use HTTP and HTTPS. @@ -37,7 +37,7 @@ The module provides the following classes: blocksize=8192) An :class:`HTTPConnection` instance represents one transaction with an HTTP - server. It should be instantiated passing it a host and optional port + server. It should be instantiated by passing it a host and optional port number. If no port number is passed, the port is extracted from the host string if it has the form ``host:port``, else the default HTTP port (80) is used. If the optional *timeout* parameter is given, blocking -- cgit v0.12 From 208701e037b061131d38a062e6009e232d71646c Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 3 Oct 2022 15:48:00 -0700 Subject: multiprocessing docs: Remove extra option ELLIPSIS from section with code (GH-96625) (cherry picked from commit d78aa4e11a80653588229cc97119afae693d1c06) Co-authored-by: Ivan Kapeykin <5349983@gmail.com> --- Doc/library/multiprocessing.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index a51fc85..7358ca1 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -674,7 +674,6 @@ The :mod:`multiprocessing` package mostly replicates the API of the Example usage of some of the methods of :class:`Process`: .. doctest:: - :options: +ELLIPSIS >>> import multiprocessing, time, signal >>> p = multiprocessing.Process(target=time.sleep, args=(1000,)) -- cgit v0.12 From ce01c59b2544e8a552e34a07484060a5270911d6 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 3 Oct 2022 06:43:31 -0700 Subject: Fix typo in unittest docs (GH-97742) (cherry picked from commit e6f9ec5c031bd996fcd5f463c407beef0b743b49) Co-authored-by: annonm --- Doc/library/unittest.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index 87571d8..42d17db 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -1797,7 +1797,7 @@ Loading and running tests A list of the non-fatal errors encountered while loading tests. Not reset by the loader at any point. Fatal errors are signalled by the relevant - a method raising an exception to the caller. Non-fatal errors are also + method raising an exception to the caller. Non-fatal errors are also indicated by a synthetic test that will raise the original error when run. -- cgit v0.12 From 1729bec2b5ec71a9e543cc88b26592eb71a5fb95 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sun, 2 Oct 2022 21:21:46 -0700 Subject: gh-95913: Fix PEP number in PEP 678 What's New ref label (GH-97739) What's New: Fix PEP number in PEP 678 ref target label (cherry picked from commit e738b5190bfa63086b5e8169189e9b05302873c8) Co-authored-by: C.A.M. Gerlach --- Doc/whatsnew/3.11.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 1b25a9e..62fea4e 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -192,6 +192,8 @@ See :pep:`654` for more details. Irit Katriel, Yury Selivanov and Guido van Rossum.) +.. _whatsnew311-pep678: + PEP 678: Exceptions can be enriched with notes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v0.12 From 5e99363a74f89a9f7924003936f2b55b66c43890 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sun, 2 Oct 2022 21:11:05 -0700 Subject: gh-95913: Copyedit/improve New Modules What's New section (GH-97721) * Link TOML & WSGI in New Modules section, refine text & add ref label * Further reformat new modules & add PEP link to tomllib (cherry picked from commit bd00112a99af44c6ef82ee45b4072ec3bbc82fef) Co-authored-by: C.A.M. Gerlach --- Doc/whatsnew/3.11.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 62fea4e..d241cd5 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -510,14 +510,17 @@ Other CPython Implementation Changes is 4300 digits in string form. +.. _whatsnew311-new-modules: + New Modules =========== -* A new module, :mod:`tomllib`, was added for parsing TOML. +* :mod:`tomllib`: For parsing `TOML `_. + See :pep:`680` for more details. (Contributed by Taneli Hukkinen in :issue:`40059`.) -* :mod:`wsgiref.types`, containing WSGI-specific types for static type - checking, was added. +* :mod:`wsgiref.types`: + :pep:`WSGI <3333>`-specific types for static type checking. (Contributed by Sebastian Rittau in :issue:`42012`.) -- cgit v0.12 From 10818aa83302b30e79eeb4ffb1bbafa1c4e0d066 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sun, 2 Oct 2022 21:02:46 -0700 Subject: gh-97740: Fix bang in Sphinx C domain ref target syntax (GH-97741) * gh-97740: Fix bang in Sphinx C domain ref target syntax Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> * Add NEWS entry for C domain bang fix Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> (cherry picked from commit 9148c0d893c7807331fd7be0997261e289074bc5) Co-authored-by: C.A.M. Gerlach --- Doc/conf.py | 25 ++++++++++++++++++++++ .../2022-10-02-10-58-52.gh-issue-97741.39l023.rst | 2 ++ 2 files changed, 27 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2022-10-02-10-58-52.gh-issue-97741.39l023.rst diff --git a/Doc/conf.py b/Doc/conf.py index fd4ee2d..e5c989d 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -234,3 +234,28 @@ linkcheck_ignore = [r'https://bugs.python.org/(issue)?\d+'] # Relative filename of the data files refcount_file = 'data/refcounts.dat' stable_abi_file = 'data/stable_abi.dat' + +# Sphinx 2 and Sphinx 3 compatibility +# ----------------------------------- + +# bpo-40204: Allow Sphinx 2 syntax in the C domain +c_allow_pre_v3 = True + +# bpo-40204: Disable warnings on Sphinx 2 syntax of the C domain since the +# documentation is built with -W (warnings treated as errors). +c_warn_on_allowed_pre_v3 = False + +# Fix '!' not working with C domain when pre_v3 is enabled +import sphinx + +if sphinx.version_info[:2] < (5, 3): + from sphinx.domains.c import CXRefRole + + original_run = CXRefRole.run + + def new_run(self): + if self.disabled: + return super(CXRefRole, self).run() + return original_run(self) + + CXRefRole.run = new_run diff --git a/Misc/NEWS.d/next/Documentation/2022-10-02-10-58-52.gh-issue-97741.39l023.rst b/Misc/NEWS.d/next/Documentation/2022-10-02-10-58-52.gh-issue-97741.39l023.rst new file mode 100644 index 0000000..8da9c92 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2022-10-02-10-58-52.gh-issue-97741.39l023.rst @@ -0,0 +1,2 @@ +Fix ``!`` in c domain ref target syntax via a ``conf.py`` patch, so it works +as intended to disable ref target resolution. -- cgit v0.12 From c8bdf339d7a000ac6fec0dbb04b4852ce6ad9041 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sun, 2 Oct 2022 15:27:17 -0700 Subject: GH-85447: Clarify docs about awaiting future multiple times (GH-97738) (cherry picked from commit 9151bbefea3fb932eb6aa6ddb22d64b83f8149c7) Co-authored-by: Kumar Aditya <59607654+kumaraditya303@users.noreply.github.com> --- Doc/library/asyncio-future.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/asyncio-future.rst b/Doc/library/asyncio-future.rst index 99a5d3a..8e60877 100644 --- a/Doc/library/asyncio-future.rst +++ b/Doc/library/asyncio-future.rst @@ -85,7 +85,8 @@ Future Object Future is an :term:`awaitable` object. Coroutines can await on Future objects until they either have a result or an exception - set, or until they are cancelled. + set, or until they are cancelled. A Future can be awaited multiple + times and the result is same. Typically Futures are used to enable low-level callback-based code (e.g. in protocols implemented using asyncio -- cgit v0.12 From 1067baf54be97f907ffc73b94780c19eea1199ef Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sun, 2 Oct 2022 09:44:42 -0700 Subject: =?UTF-8?q?[3.11]=20[docs]=20Update=20logging=20cookbook=20with=20?= =?UTF-8?q?recipe=20for=20using=20a=20logger=20like=20an=20output=E2=80=A6?= =?UTF-8?q?=20(GH-97730)=20(GH-97735)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Doc/howto/logging-cookbook.rst | 77 ------------------------------------------ 1 file changed, 77 deletions(-) diff --git a/Doc/howto/logging-cookbook.rst b/Doc/howto/logging-cookbook.rst index 25ea37f..d1c3534 100644 --- a/Doc/howto/logging-cookbook.rst +++ b/Doc/howto/logging-cookbook.rst @@ -3703,83 +3703,6 @@ instance). Then, you'd get this kind of result: Of course, these above examples show output according to the format used by :func:`~logging.basicConfig`, but you can use a different formatter when you configure logging. -======= -How to treat a logger like an output stream -------------------------------------------- - -Sometimes, you need to interface to a third-party API which expects a file-like -object to write to, but you want to direct the API's output to a logger. You -can do this using a class which wraps a logger with a file-like API. -Here's a short script illustrating such a class: - -.. code-block:: python - - import logging - - class LoggerWriter: - def __init__(self, logger, level): - self.logger = logger - self.level = level - - def write(self, message): - if message != '\n': # avoid printing bare newlines, if you like - self.logger.log(self.level, message) - - def flush(self): - # doesn't actually do anything, but might be expected of a file-like - # object - so optional depending on your situation - pass - - def close(self): - # doesn't actually do anything, but might be expected of a file-like - # object - so optional depending on your situation. You might want - # to set a flag so that later calls to write raise an exception - pass - - def main(): - logging.basicConfig(level=logging.DEBUG) - logger = logging.getLogger('demo') - info_fp = LoggerWriter(logger, logging.INFO) - debug_fp = LoggerWriter(logger, logging.DEBUG) - print('An INFO message', file=info_fp) - print('A DEBUG message', file=debug_fp) - - if __name__ == "__main__": - main() - -When this script is run, it prints - -.. code-block:: text - - INFO:demo:An INFO message - DEBUG:demo:A DEBUG message - -You could also use ``LoggerWriter`` to redirect ``sys.stdout`` and -``sys.stderr`` by doing something like this: - -.. code-block:: python - - import sys - - sys.stdout = LoggerWriter(logger, logging.INFO) - sys.stderr = LoggerWriter(logger, logging.WARNING) - -You should do this *after* configuring logging for your needs. In the above -example, the :func:`~logging.basicConfig` call does this (using the -``sys.stderr`` value *before* it is overwritten by a ``LoggerWriter`` -instance). Then, you'd get this kind of result: - -.. code-block:: pycon - - >>> print('Foo') - INFO:demo:Foo - >>> print('Bar', file=sys.stderr) - WARNING:demo:Bar - >>> - -Of course, the examples above show output according to the format used by -:func:`~logging.basicConfig`, but you can use a different formatter when you -configure logging. .. patterns-to-avoid: -- cgit v0.12 From eb5cdf6246b14f7e322b4c1fb5f91971e3082939 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sat, 1 Oct 2022 22:28:54 -0700 Subject: gh-97607: Fix content parsing in the impl-detail reST directive (GH-97652) * Don't parse content as arg in the impl-detail directive This does not change the (untranslated) output, but ensures that the doctree node metadata is correct. which fixes gh-97607 with the text not being translated. It also simplifies the code and logic and makes it consistant with the docutils built-in directives. * Remove unused branch from impl-detail directive handling no-content case This is not used anywhere in the docs and lacks a clear use case, and is more likely a mistake which is now flagged at build time. This simplifies the logic from two code paths to one, and makes the behavior consistant with similar built-in directives (e.g. the various admonition types). * Further simplify impl-detail reST directive code (cherry picked from commit e8165d47b852e933c176209ddc0b5836a9b0d5f4) Co-authored-by: C.A.M. Gerlach --- Doc/tools/extensions/pyspecific.py | 23 +++++++---------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py index f326e77..647554d 100644 --- a/Doc/tools/extensions/pyspecific.py +++ b/Doc/tools/extensions/pyspecific.py @@ -101,33 +101,24 @@ def source_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): class ImplementationDetail(Directive): has_content = True - required_arguments = 0 - optional_arguments = 1 final_argument_whitespace = True # This text is copied to templates/dummy.html label_text = 'CPython implementation detail:' def run(self): + self.assert_has_content() pnode = nodes.compound(classes=['impl-detail']) label = translators['sphinx'].gettext(self.label_text) content = self.content add_text = nodes.strong(label, label) - if self.arguments: - n, m = self.state.inline_text(self.arguments[0], self.lineno) - pnode.append(nodes.paragraph('', '', *(n + m))) self.state.nested_parse(content, self.content_offset, pnode) - if pnode.children and isinstance(pnode[0], nodes.paragraph): - content = nodes.inline(pnode[0].rawsource, translatable=True) - content.source = pnode[0].source - content.line = pnode[0].line - content += pnode[0].children - pnode[0].replace_self(nodes.paragraph('', '', content, - translatable=False)) - pnode[0].insert(0, add_text) - pnode[0].insert(1, nodes.Text(' ')) - else: - pnode.insert(0, nodes.paragraph('', '', add_text)) + content = nodes.inline(pnode[0].rawsource, translatable=True) + content.source = pnode[0].source + content.line = pnode[0].line + content += pnode[0].children + pnode[0].replace_self(nodes.paragraph( + '', '', add_text, nodes.Text(' '), content, translatable=False)) return [pnode] -- cgit v0.12 From d79a412598a923dbbabc78ea4f91518128b9a553 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sat, 1 Oct 2022 22:20:43 -0700 Subject: gh-95975: Move except/*/finally ref labels to more precise locations (GH-95976) * gh-95975: Move except/*/finally ref labels to more precise locations * Add section headers to fix :keyword: role and aid navigation * Move see also to the introduction rather than a particular subsection * Fix other minor Sphinx syntax issues with except Co-authored-by: Ezio Melotti * Suppress redundant link to same section for except too * Don't link try/except/else/finally keywords if in the same section * Format try/except/finally as keywords in modified sections Co-authored-by: Ezio Melotti (cherry picked from commit dcc82331c8f05a6a149ac15c519d4fbae72692b2) Co-authored-by: C.A.M. Gerlach --- Doc/reference/compound_stmts.rst | 122 ++++++++++++++++++++++++--------------- 1 file changed, 76 insertions(+), 46 deletions(-) diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 6a176b7..9acad50 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -199,10 +199,8 @@ returns the list ``[0, 1, 2]``. .. versionchanged:: 3.11 Starred elements are now allowed in the expression list. + .. _try: -.. _except: -.. _except_star: -.. _finally: The :keyword:`!try` statement ============================= @@ -215,7 +213,7 @@ The :keyword:`!try` statement keyword: as single: : (colon); compound statement -The :keyword:`try` statement specifies exception handlers and/or cleanup code +The :keyword:`!try` statement specifies exception handlers and/or cleanup code for a group of statements: .. productionlist:: python-grammar @@ -231,40 +229,56 @@ for a group of statements: try3_stmt: "try" ":" `suite` : "finally" ":" `suite` +Additional information on exceptions can be found in section :ref:`exceptions`, +and information on using the :keyword:`raise` statement to generate exceptions +may be found in section :ref:`raise`. -The :keyword:`except` clause(s) specify one or more exception handlers. When no + +.. _except: + +:keyword:`!except` clause +------------------------- + +The :keyword:`!except` clause(s) specify one or more exception handlers. When no exception occurs in the :keyword:`try` clause, no exception handler is executed. When an exception occurs in the :keyword:`!try` suite, a search for an exception -handler is started. This search inspects the except clauses in turn until one -is found that matches the exception. An expression-less except clause, if -present, must be last; it matches any exception. For an except clause with an -expression, that expression is evaluated, and the clause matches the exception +handler is started. This search inspects the :keyword:`!except` clauses in turn +until one is found that matches the exception. +An expression-less :keyword:`!except` clause, if present, must be last; +it matches any exception. +For an :keyword:`!except` clause with an expression, +that expression is evaluated, and the clause matches the exception if the resulting object is "compatible" with the exception. An object is compatible with an exception if the object is the class or a :term:`non-virtual base class ` of the exception object, or a tuple containing an item that is the class or a non-virtual base class of the exception object. -If no except clause matches the exception, the search for an exception handler +If no :keyword:`!except` clause matches the exception, +the search for an exception handler continues in the surrounding code and on the invocation stack. [#]_ -If the evaluation of an expression in the header of an except clause raises an -exception, the original search for a handler is canceled and a search starts for +If the evaluation of an expression +in the header of an :keyword:`!except` clause raises an exception, +the original search for a handler is canceled and a search starts for the new exception in the surrounding code and on the call stack (it is treated as if the entire :keyword:`try` statement raised the exception). .. index:: single: as; except clause -When a matching except clause is found, the exception is assigned to the target -specified after the :keyword:`!as` keyword in that except clause, if present, and -the except clause's suite is executed. All except clauses must have an -executable block. When the end of this block is reached, execution continues -normally after the entire try statement. (This means that if two nested -handlers exist for the same exception, and the exception occurs in the try -clause of the inner handler, the outer handler will not handle the exception.) +When a matching :keyword:`!except` clause is found, +the exception is assigned to the target +specified after the :keyword:`!as` keyword in that :keyword:`!except` clause, +if present, and the :keyword:`!except` clause's suite is executed. +All :keyword:`!except` clauses must have an executable block. +When the end of this block is reached, execution continues +normally after the entire :keyword:`try` statement. +(This means that if two nested handlers exist for the same exception, +and the exception occurs in the :keyword:`!try` clause of the inner handler, +the outer handler will not handle the exception.) When an exception has been assigned using ``as target``, it is cleared at the -end of the except clause. This is as if :: +end of the :keyword:`!except` clause. This is as if :: except E as N: foo @@ -278,7 +292,8 @@ was translated to :: del N This means the exception must be assigned to a different name to be able to -refer to it after the except clause. Exceptions are cleared because with the +refer to it after the :keyword:`!except` clause. +Exceptions are cleared because with the traceback attached to them, they form a reference cycle with the stack frame, keeping all locals in that frame alive until the next garbage collection occurs. @@ -286,7 +301,8 @@ keeping all locals in that frame alive until the next garbage collection occurs. module: sys object: traceback -Before an except clause's suite is executed, details about the exception are +Before an :keyword:`!except` clause's suite is executed, +details about the exception are stored in the :mod:`sys` module and can be accessed via :func:`sys.exc_info`. :func:`sys.exc_info` returns a 3-tuple consisting of the exception class, the exception instance and a traceback object (see section :ref:`types`) identifying @@ -312,17 +328,24 @@ when leaving an exception handler:: >>> print(sys.exc_info()) (None, None, None) + .. index:: keyword: except_star -The :keyword:`except*` clause(s) are used for handling -:exc:`ExceptionGroup`\ s. The exception type for matching is interpreted as in +.. _except_star: + +:keyword:`!except*` clause +-------------------------- + +The :keyword:`!except*` clause(s) are used for handling +:exc:`ExceptionGroup`\s. The exception type for matching is interpreted as in the case of :keyword:`except`, but in the case of exception groups we can have partial matches when the type matches some of the exceptions in the group. -This means that multiple except* clauses can execute, each handling part of -the exception group. Each clause executes once and handles an exception group +This means that multiple :keyword:`!except*` clauses can execute, +each handling part of the exception group. +Each clause executes once and handles an exception group of all matching exceptions. Each exception in the group is handled by at most -one except* clause, the first that matches it. :: +one :keyword:`!except*` clause, the first that matches it. :: >>> try: ... raise ExceptionGroup("eg", @@ -341,16 +364,16 @@ one except* clause, the first that matches it. :: | ValueError: 1 +------------------------------------ -Any remaining exceptions that were not handled by any :keyword:`!except*` -clause are re-raised at the end, combined into an exception group along with -all exceptions that were raised from within :keyword:`!except*` clauses. + Any remaining exceptions that were not handled by any :keyword:`!except*` + clause are re-raised at the end, combined into an exception group along with + all exceptions that were raised from within :keyword:`!except*` clauses. -An :keyword:`!except*` clause must have a matching type, -and this type cannot be a subclass of :exc:`BaseExceptionGroup`. -It is not possible to mix :keyword:`except` and :keyword:`!except*` -in the same :keyword:`try`. -:keyword:`break`, :keyword:`continue` and :keyword:`return` -cannot appear in an :keyword:`!except*` clause. + An :keyword:`!except*` clause must have a matching type, + and this type cannot be a subclass of :exc:`BaseExceptionGroup`. + It is not possible to mix :keyword:`except` and :keyword:`!except*` + in the same :keyword:`try`. + :keyword:`break`, :keyword:`continue` and :keyword:`return` + cannot appear in an :keyword:`!except*` clause. .. index:: @@ -359,17 +382,28 @@ cannot appear in an :keyword:`!except*` clause. statement: break statement: continue +.. _except_else: + +:keyword:`!else` clause +----------------------- + The optional :keyword:`!else` clause is executed if the control flow leaves the :keyword:`try` suite, no exception was raised, and no :keyword:`return`, :keyword:`continue`, or :keyword:`break` statement was executed. Exceptions in the :keyword:`!else` clause are not handled by the preceding :keyword:`except` clauses. + .. index:: keyword: finally -If :keyword:`finally` is present, it specifies a 'cleanup' handler. The +.. _finally: + +:keyword:`!finally` clause +-------------------------- + +If :keyword:`!finally` is present, it specifies a 'cleanup' handler. The :keyword:`try` clause is executed, including any :keyword:`except` and -:keyword:`!else` clauses. If an exception occurs in any of the clauses and is +:keyword:`else` clauses. If an exception occurs in any of the clauses and is not handled, the exception is temporarily saved. The :keyword:`!finally` clause is executed. If there is a saved exception it is re-raised at the end of the :keyword:`!finally` clause. If the :keyword:`!finally` clause raises another @@ -387,7 +421,7 @@ or :keyword:`continue` statement, the saved exception is discarded:: 42 The exception information is not available to the program during execution of -the :keyword:`finally` clause. +the :keyword:`!finally` clause. .. index:: statement: return @@ -396,10 +430,10 @@ the :keyword:`finally` clause. When a :keyword:`return`, :keyword:`break` or :keyword:`continue` statement is executed in the :keyword:`try` suite of a :keyword:`!try`...\ :keyword:`!finally` -statement, the :keyword:`finally` clause is also executed 'on the way out.' +statement, the :keyword:`!finally` clause is also executed 'on the way out.' The return value of a function is determined by the last :keyword:`return` -statement executed. Since the :keyword:`finally` clause always executes, a +statement executed. Since the :keyword:`!finally` clause always executes, a :keyword:`!return` statement executed in the :keyword:`!finally` clause will always be the last one executed:: @@ -412,13 +446,9 @@ always be the last one executed:: >>> foo() 'finally' -Additional information on exceptions can be found in section :ref:`exceptions`, -and information on using the :keyword:`raise` statement to generate exceptions -may be found in section :ref:`raise`. - .. versionchanged:: 3.8 Prior to Python 3.8, a :keyword:`continue` statement was illegal in the - :keyword:`finally` clause due to a problem with the implementation. + :keyword:`!finally` clause due to a problem with the implementation. .. _with: -- cgit v0.12 From b8afd5ffd3e7f03627bacc82dbd2d7e340f901a1 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sat, 1 Oct 2022 16:51:34 -0700 Subject: Fix capitalization of Unix in documentation (GH-96913) (cherry picked from commit bd7d0e875e6955dd69cde18a034e59a75b8b4d00) Co-authored-by: Will Hawkins <8715530+hawkinsw@users.noreply.github.com> --- Doc/library/email.compat32-message.rst | 4 ++-- Doc/library/email.generator.rst | 4 ++-- Doc/library/multiprocessing.rst | 4 ++-- Doc/library/os.path.rst | 2 +- Doc/library/test.rst | 2 +- Doc/whatsnew/3.3.rst | 2 +- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/Doc/library/email.compat32-message.rst b/Doc/library/email.compat32-message.rst index c68e773..4eaa9d5 100644 --- a/Doc/library/email.compat32-message.rst +++ b/Doc/library/email.compat32-message.rst @@ -83,7 +83,7 @@ Here are the methods of the :class:`Message` class: Note that this method is provided as a convenience and may not always format the message the way you want. For example, by default it does not do the mangling of lines that begin with ``From`` that is - required by the unix mbox format. For more flexibility, instantiate a + required by the Unix mbox format. For more flexibility, instantiate a :class:`~email.generator.Generator` instance and use its :meth:`~email.generator.Generator.flatten` method directly. For example:: @@ -125,7 +125,7 @@ Here are the methods of the :class:`Message` class: Note that this method is provided as a convenience and may not always format the message the way you want. For example, by default it does not do the mangling of lines that begin with ``From`` that is - required by the unix mbox format. For more flexibility, instantiate a + required by the Unix mbox format. For more flexibility, instantiate a :class:`~email.generator.BytesGenerator` instance and use its :meth:`~email.generator.BytesGenerator.flatten` method directly. For example:: diff --git a/Doc/library/email.generator.rst b/Doc/library/email.generator.rst index 2d9bae6..34ad7b7 100644 --- a/Doc/library/email.generator.rst +++ b/Doc/library/email.generator.rst @@ -55,7 +55,7 @@ To accommodate reproducible processing of SMIME-signed messages defaults to the value of the :attr:`~email.policy.Policy.mangle_from_` setting of the *policy* (which is ``True`` for the :data:`~email.policy.compat32` policy and ``False`` for all others). - *mangle_from_* is intended for use when messages are stored in unix mbox + *mangle_from_* is intended for use when messages are stored in Unix mbox format (see :mod:`mailbox` and `WHY THE CONTENT-LENGTH FORMAT IS BAD `_). @@ -156,7 +156,7 @@ to be using :class:`BytesGenerator`, and not :class:`Generator`. defaults to the value of the :attr:`~email.policy.Policy.mangle_from_` setting of the *policy* (which is ``True`` for the :data:`~email.policy.compat32` policy and ``False`` for all others). - *mangle_from_* is intended for use when messages are stored in unix mbox + *mangle_from_* is intended for use when messages are stored in Unix mbox format (see :mod:`mailbox` and `WHY THE CONTENT-LENGTH FORMAT IS BAD `_). diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 7358ca1..5516084 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -144,8 +144,8 @@ to start a process. These *start methods* are subprocess. See :issue:`33725`. .. versionchanged:: 3.4 - *spawn* added on all unix platforms, and *forkserver* added for - some unix platforms. + *spawn* added on all Unix platforms, and *forkserver* added for + some Unix platforms. Child processes no longer inherit all of the parents inheritable handles on Windows. diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index f02877e..0becb59 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -16,7 +16,7 @@ files see :func:`open`, and for accessing the filesystem see the :mod:`os` module. The path parameters can be passed as strings, or bytes, or any object implementing the :class:`os.PathLike` protocol. -Unlike a unix shell, Python does not do any *automatic* path expansions. +Unlike a Unix shell, Python does not do any *automatic* path expansions. Functions such as :func:`expanduser` and :func:`expandvars` can be invoked explicitly when an application desires shell-like path expansion. (See also the :mod:`glob` module.) diff --git a/Doc/library/test.rst b/Doc/library/test.rst index 4336258..8e05ff3 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -1075,7 +1075,7 @@ The :mod:`test.support.socket_helper` module provides support for socket tests. .. function:: bind_unix_socket(sock, addr) - Bind a unix socket, raising :exc:`unittest.SkipTest` if + Bind a Unix socket, raising :exc:`unittest.SkipTest` if :exc:`PermissionError` is raised. diff --git a/Doc/whatsnew/3.3.rst b/Doc/whatsnew/3.3.rst index 237e457..fef1a8a 100644 --- a/Doc/whatsnew/3.3.rst +++ b/Doc/whatsnew/3.3.rst @@ -1898,7 +1898,7 @@ socket family on OS X. (Contributed by Michael Goderbauer in :issue:`13777`.) * New function :func:`~socket.sethostname` allows the hostname to be set - on unix systems if the calling process has sufficient privileges. + on Unix systems if the calling process has sufficient privileges. (Contributed by Ross Lagerwall in :issue:`10866`.) -- cgit v0.12 From c12c993aa11a9aa660b34f3aecbdf4dbcbc91dfb Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Fri, 30 Sep 2022 10:54:12 -0700 Subject: gh-87597: Document TimeoutExpired.stdout & .stderr types (GH-97685) This documents the behavior that has always been the case since timeout support was introduced in Python 3.3. (cherry picked from commit b05dd796492160c37c9e15e3882f699f411b3461) Co-authored-by: Gregory P. Smith --- Doc/library/subprocess.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 43d6ffc..dee5bd8 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -193,7 +193,10 @@ underlying :class:`Popen` interface can be used directly. .. attribute:: output Output of the child process if it was captured by :func:`run` or - :func:`check_output`. Otherwise, ``None``. + :func:`check_output`. Otherwise, ``None``. This is always + :class:`bytes` when any output was captured regardless of the + ``text=True`` setting. It may remain ``None`` instead of ``b''`` + when no output was observed. .. attribute:: stdout @@ -202,7 +205,9 @@ underlying :class:`Popen` interface can be used directly. .. attribute:: stderr Stderr output of the child process if it was captured by :func:`run`. - Otherwise, ``None``. + Otherwise, ``None``. This is always :class:`bytes` when stderr output + was captured regardless of the ``text=True`` setting. It may remain + ``None`` instead of ``b''`` when no stderr output was observed. .. versionadded:: 3.3 -- cgit v0.12 From 815ad02586390439f1fd51a1d2ada56df1b65892 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Fri, 30 Sep 2022 02:12:22 -0700 Subject: [3.11] Use SyntaxError invalid range in tutorial introduction example (GH-93031) (GH-97666) Use SyntaxError invalid range in tutorial introduction example (GH-93031) Use output from a 3.10+ REPL, showing invalid range, for the SyntaxError examples in the tutorial introduction page. Co-authored-by: Eddie Hebert --- Doc/tutorial/introduction.rst | 4 ++-- .../next/Documentation/2022-05-20-18-42-10.gh-issue-93031.c2RdJe.rst | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2022-05-20-18-42-10.gh-issue-93031.c2RdJe.rst diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst index a64a92f..558b1c3 100644 --- a/Doc/tutorial/introduction.rst +++ b/Doc/tutorial/introduction.rst @@ -234,12 +234,12 @@ This only works with two literals though, not with variables or expressions:: >>> prefix 'thon' # can't concatenate a variable and a string literal File "", line 1 prefix 'thon' - ^ + ^^^^^^ SyntaxError: invalid syntax >>> ('un' * 3) 'ium' File "", line 1 ('un' * 3) 'ium' - ^ + ^^^^^ SyntaxError: invalid syntax If you want to concatenate variables or a variable and a literal, use ``+``:: diff --git a/Misc/NEWS.d/next/Documentation/2022-05-20-18-42-10.gh-issue-93031.c2RdJe.rst b/Misc/NEWS.d/next/Documentation/2022-05-20-18-42-10.gh-issue-93031.c2RdJe.rst new file mode 100644 index 0000000..c46b45d --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2022-05-20-18-42-10.gh-issue-93031.c2RdJe.rst @@ -0,0 +1 @@ +Update tutorial introduction output to use 3.10+ SyntaxError invalid range. -- cgit v0.12 From f20ad5ef4521cefc6d9004a3d8b44a25d72ba821 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 29 Sep 2022 16:25:10 -0700 Subject: gh-96397: Document that attributes need not be identifiers (GH-96454) Co-authored-by: C.A.M. Gerlach (cherry picked from commit 9a11ed8e50492d327e4de0a8f3a473e788b14a6f) Co-authored-by: Jeff Allen --- Doc/glossary.rst | 11 +++++++++-- Doc/library/functions.rst | 8 ++++++++ 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 9550b98..59f9426 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -136,10 +136,17 @@ Glossary :exc:`StopAsyncIteration` exception. Introduced by :pep:`492`. attribute - A value associated with an object which is referenced by name using - dotted expressions. For example, if an object *o* has an attribute + A value associated with an object which is usually referenced by name + using dotted expressions. + For example, if an object *o* has an attribute *a* it would be referenced as *o.a*. + It is possible to give an object an attribute whose name is not an + identifier as defined by :ref:`identifiers`, for example using + :func:`setattr`, if the object allows it. + Such an attribute will not be accessible using a dotted expression, + and would instead need to be retrieved with :func:`getattr`. + awaitable An object that can be used in an :keyword:`await` expression. Can be a :term:`coroutine` or an object with an :meth:`__await__` method. diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 2393698..8108c98 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -403,6 +403,7 @@ are always available. They are listed here in alphabetical order. string. The string must be the name of one of the object's attributes. The function deletes the named attribute, provided the object allows it. For example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``. + *name* need not be a Python identifier (see :func:`setattr`). .. _func-dict: @@ -746,6 +747,7 @@ are always available. They are listed here in alphabetical order. value of that attribute. For example, ``getattr(x, 'foobar')`` is equivalent to ``x.foobar``. If the named attribute does not exist, *default* is returned if provided, otherwise :exc:`AttributeError` is raised. + *name* need not be a Python identifier (see :func:`setattr`). .. note:: @@ -1598,6 +1600,12 @@ are always available. They are listed here in alphabetical order. object allows it. For example, ``setattr(x, 'foobar', 123)`` is equivalent to ``x.foobar = 123``. + *name* need not be a Python identifier as defined in :ref:`identifiers` + unless the object chooses to enforce that, for example in a custom + :meth:`~object.__getattribute__` or via :attr:`~object.__slots__`. + An attribute whose name is not an identifier will not be accessible using + the dot notation, but is accessible through :func:`getattr` etc.. + .. note:: Since :ref:`private name mangling ` happens at -- cgit v0.12 From 807d14baae2ff4f787bee1d47010963a2a36d58d Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 29 Sep 2022 16:00:33 -0700 Subject: closes gh-97650: correct sphinx executable (gh-97651) (cherry picked from commit 0179a82caa05a322d1dbab05155be6f919c281ff) Co-authored-by: NoSuck --- Doc/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/README.rst b/Doc/README.rst index 4326086..d67cad7 100644 --- a/Doc/README.rst +++ b/Doc/README.rst @@ -40,7 +40,7 @@ If you'd like to create the virtual environment in a different location, you can specify it using the ``VENVDIR`` variable. You can also skip creating the virtual environment altogether, in which case -the Makefile will look for instances of ``sphinxbuild`` and ``blurb`` +the Makefile will look for instances of ``sphinx-build`` and ``blurb`` installed on your process ``PATH`` (configurable with the ``SPHINXBUILD`` and ``BLURB`` variables). -- cgit v0.12 From 68b7a6ab991a9964372bc2019bf857a0b382e9fb Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 29 Sep 2022 06:51:39 -0700 Subject: gh-52597: Add position-only markers for os functions (GH-94735) (cherry picked from commit c759944f16ed9887a77d5ebd738f17f3892c2476) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> --- Doc/library/os.rst | 134 ++++++++++++++++++++++++++--------------------------- 1 file changed, 67 insertions(+), 67 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 7185016..9a4e2f8 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -374,7 +374,7 @@ process and user. :ref:`wasm-availability` for more information. -.. function:: getgrouplist(user, group) +.. function:: getgrouplist(user, group, /) Return list of group ids that *user* belongs to. If *group* is not in the list, it is included; typically, *group* is specified as the group ID @@ -520,7 +520,7 @@ process and user. :ref:`wasm-availability` for more information. -.. function:: initgroups(username, gid) +.. function:: initgroups(username, gid, /) Call the system initgroups() to initialize the group access list with all of the groups of which the specified username is a member, plus the specified @@ -531,7 +531,7 @@ process and user. .. versionadded:: 3.2 -.. function:: putenv(key, value) +.. function:: putenv(key, value, /) .. index:: single: environment variables; setting @@ -556,28 +556,28 @@ process and user. The function is now always available. -.. function:: setegid(egid) +.. function:: setegid(egid, /) Set the current process's effective group id. .. availability:: Unix, not Emscripten, not WASI. -.. function:: seteuid(euid) +.. function:: seteuid(euid, /) Set the current process's effective user id. .. availability:: Unix, not Emscripten, not WASI. -.. function:: setgid(gid) +.. function:: setgid(gid, /) Set the current process' group id. .. availability:: Unix, not Emscripten, not WASI. -.. function:: setgroups(groups) +.. function:: setgroups(groups, /) Set the list of supplemental group ids associated with the current process to *groups*. *groups* must be a sequence, and each element must be an integer @@ -598,7 +598,7 @@ process and user. .. availability:: Unix, not Emscripten, not WASI. -.. function:: setpgid(pid, pgrp) +.. function:: setpgid(pid, pgrp, /) Call the system call :c:func:`setpgid` to set the process group id of the process with id *pid* to the process group with id *pgrp*. See the Unix manual @@ -626,14 +626,14 @@ process and user. .. versionadded:: 3.3 -.. function:: setregid(rgid, egid) +.. function:: setregid(rgid, egid, /) Set the current process's real and effective group ids. .. availability:: Unix, not Emscripten, not WASI. -.. function:: setresgid(rgid, egid, sgid) +.. function:: setresgid(rgid, egid, sgid, /) Set the current process's real, effective, and saved group ids. @@ -642,7 +642,7 @@ process and user. .. versionadded:: 3.2 -.. function:: setresuid(ruid, euid, suid) +.. function:: setresuid(ruid, euid, suid, /) Set the current process's real, effective, and saved user ids. @@ -651,14 +651,14 @@ process and user. .. versionadded:: 3.2 -.. function:: setreuid(ruid, euid) +.. function:: setreuid(ruid, euid, /) Set the current process's real and effective user ids. .. availability:: Unix, not Emscripten, not WASI. -.. function:: getsid(pid) +.. function:: getsid(pid, /) Call the system call :c:func:`getsid`. See the Unix manual for the semantics. @@ -672,7 +672,7 @@ process and user. .. availability:: Unix, not Emscripten, not WASI. -.. function:: setuid(uid) +.. function:: setuid(uid, /) .. index:: single: user; id, setting @@ -682,7 +682,7 @@ process and user. .. placed in this section since it relates to errno.... a little weak -.. function:: strerror(code) +.. function:: strerror(code, /) Return the error message corresponding to the error code in *code*. On platforms where :c:func:`strerror` returns ``NULL`` when given an unknown @@ -697,7 +697,7 @@ process and user. .. versionadded:: 3.2 -.. function:: umask(mask) +.. function:: umask(mask, /) Set the current numeric umask and return the previous umask. @@ -737,7 +737,7 @@ process and user. with named attributes. -.. function:: unsetenv(key) +.. function:: unsetenv(key, /) .. index:: single: environment variables; deleting @@ -805,7 +805,7 @@ as internal buffering of data. :func:`fdopen`, use its :meth:`~io.IOBase.close` method. -.. function:: closerange(fd_low, fd_high) +.. function:: closerange(fd_low, fd_high, /) Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive), ignoring errors. Equivalent to (but much faster than):: @@ -851,7 +851,7 @@ as internal buffering of data. On Unix, the function now implements the Python UTF-8 Mode. -.. function:: dup(fd) +.. function:: dup(fd, /) Return a duplicate of file descriptor *fd*. The new file descriptor is :ref:`non-inheritable `. @@ -922,7 +922,7 @@ as internal buffering of data. This function is not available on MacOS. -.. function:: fpathconf(fd, name) +.. function:: fpathconf(fd, name, /) Return system configuration information relevant to an open file. *name* specifies the configuration value to retrieve; it may be a string which is the @@ -954,7 +954,7 @@ as internal buffering of data. The :func:`.stat` function. -.. function:: fstatvfs(fd) +.. function:: fstatvfs(fd, /) Return information about the filesystem containing the file associated with file descriptor *fd*, like :func:`statvfs`. As of Python 3.3, this is @@ -975,7 +975,7 @@ as internal buffering of data. .. availability:: Unix, Windows. -.. function:: ftruncate(fd, length) +.. function:: ftruncate(fd, length, /) Truncate the file corresponding to file descriptor *fd*, so that it is at most *length* bytes in size. As of Python 3.3, this is equivalent to @@ -989,7 +989,7 @@ as internal buffering of data. Added support for Windows -.. function:: get_blocking(fd) +.. function:: get_blocking(fd, /) Get the blocking mode of the file descriptor: ``False`` if the :data:`O_NONBLOCK` flag is set, ``True`` if the flag is cleared. @@ -1004,13 +1004,13 @@ as internal buffering of data. .. versionadded:: 3.5 -.. function:: isatty(fd) +.. function:: isatty(fd, /) Return ``True`` if the file descriptor *fd* is open and connected to a tty(-like) device, else ``False``. -.. function:: lockf(fd, cmd, len) +.. function:: lockf(fd, cmd, len, /) Apply, test or remove a POSIX lock on an open file descriptor. *fd* is an open file descriptor. @@ -1037,7 +1037,7 @@ as internal buffering of data. .. versionadded:: 3.3 -.. function:: login_tty(fd) +.. function:: login_tty(fd, /) Prepare the tty of which fd is a file descriptor for a new login session. Make the calling process a session leader; make the tty the controlling tty, @@ -1048,7 +1048,7 @@ as internal buffering of data. .. versionadded:: 3.11 -.. function:: lseek(fd, pos, how) +.. function:: lseek(fd, pos, how, /) Set the current position of file descriptor *fd* to position *pos*, modified by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the @@ -1205,7 +1205,7 @@ or `the MSDN `_ on Windo The new file descriptors are now non-inheritable. -.. function:: pipe2(flags) +.. function:: pipe2(flags, /) Create a pipe with *flags* set atomically. *flags* can be constructed by ORing together one or more of these values: @@ -1218,7 +1218,7 @@ or `the MSDN `_ on Windo .. versionadded:: 3.3 -.. function:: posix_fallocate(fd, offset, len) +.. function:: posix_fallocate(fd, offset, len, /) Ensures that enough disk space is allocated for the file specified by *fd* starting from *offset* and continuing for *len* bytes. @@ -1228,7 +1228,7 @@ or `the MSDN `_ on Windo .. versionadded:: 3.3 -.. function:: posix_fadvise(fd, offset, len, advice) +.. function:: posix_fadvise(fd, offset, len, advice, /) Announces an intention to access data in a specific pattern thus allowing the kernel to make optimizations. @@ -1258,7 +1258,7 @@ or `the MSDN `_ on Windo .. versionadded:: 3.3 -.. function:: pread(fd, n, offset) +.. function:: pread(fd, n, offset, /) Read at most *n* bytes from file descriptor *fd* at a position of *offset*, leaving the file offset unchanged. @@ -1271,7 +1271,7 @@ or `the MSDN `_ on Windo .. versionadded:: 3.3 -.. function:: preadv(fd, buffers, offset, flags=0) +.. function:: preadv(fd, buffers, offset, flags=0, /) Read from a file descriptor *fd* at a position of *offset* into mutable :term:`bytes-like objects ` *buffers*, leaving the file @@ -1328,7 +1328,7 @@ or `the MSDN `_ on Windo .. versionadded:: 3.7 -.. function:: pwrite(fd, str, offset) +.. function:: pwrite(fd, str, offset, /) Write the bytestring in *str* to file descriptor *fd* at position of *offset*, leaving the file offset unchanged. @@ -1340,7 +1340,7 @@ or `the MSDN `_ on Windo .. versionadded:: 3.3 -.. function:: pwritev(fd, buffers, offset, flags=0) +.. function:: pwritev(fd, buffers, offset, flags=0, /) Write the *buffers* contents to file descriptor *fd* at a offset *offset*, leaving the file offset unchanged. *buffers* must be a sequence of @@ -1403,7 +1403,7 @@ or `the MSDN `_ on Windo .. versionadded:: 3.10 -.. function:: read(fd, n) +.. function:: read(fd, n, /) Read at most *n* bytes from file descriptor *fd*. @@ -1463,7 +1463,7 @@ or `the MSDN `_ on Windo Parameters *out* and *in* was renamed to *out_fd* and *in_fd*. -.. function:: set_blocking(fd, blocking) +.. function:: set_blocking(fd, blocking, /) Set the blocking mode of the specified file descriptor. Set the :data:`O_NONBLOCK` flag if blocking is ``False``, clear the flag otherwise. @@ -1532,7 +1532,7 @@ or `the MSDN `_ on Windo .. versionadded:: 3.10 -.. function:: readv(fd, buffers) +.. function:: readv(fd, buffers, /) Read from a file descriptor *fd* into a number of mutable :term:`bytes-like objects ` *buffers*. Transfer data into each buffer until @@ -1550,7 +1550,7 @@ or `the MSDN `_ on Windo .. versionadded:: 3.3 -.. function:: tcgetpgrp(fd) +.. function:: tcgetpgrp(fd, /) Return the process group associated with the terminal given by *fd* (an open file descriptor as returned by :func:`os.open`). @@ -1558,7 +1558,7 @@ or `the MSDN `_ on Windo .. availability:: Unix, not WASI. -.. function:: tcsetpgrp(fd, pg) +.. function:: tcsetpgrp(fd, pg, /) Set the process group associated with the terminal given by *fd* (an open file descriptor as returned by :func:`os.open`) to *pg*. @@ -1566,7 +1566,7 @@ or `the MSDN `_ on Windo .. availability:: Unix, not WASI. -.. function:: ttyname(fd) +.. function:: ttyname(fd, /) Return a string which specifies the terminal device associated with file descriptor *fd*. If *fd* is not associated with a terminal device, an @@ -1575,7 +1575,7 @@ or `the MSDN `_ on Windo .. availability:: Unix. -.. function:: write(fd, str) +.. function:: write(fd, str, /) Write the bytestring in *str* to file descriptor *fd*. @@ -1595,7 +1595,7 @@ or `the MSDN `_ on Windo :exc:`InterruptedError` exception (see :pep:`475` for the rationale). -.. function:: writev(fd, buffers) +.. function:: writev(fd, buffers, /) Write the contents of *buffers* to file descriptor *fd*. *buffers* must be a sequence of :term:`bytes-like objects `. Buffers are @@ -1619,7 +1619,7 @@ Querying the size of a terminal .. versionadded:: 3.3 -.. function:: get_terminal_size(fd=STDOUT_FILENO) +.. function:: get_terminal_size(fd=STDOUT_FILENO, /) Return the size of the terminal window as ``(columns, lines)``, tuple of type :class:`terminal_size`. @@ -1674,21 +1674,21 @@ streams are closed, and inheritable handles are only inherited if the On WebAssembly platforms ``wasm32-emscripten`` and ``wasm32-wasi``, the file descriptor cannot be modified. -.. function:: get_inheritable(fd) +.. function:: get_inheritable(fd, /) Get the "inheritable" flag of the specified file descriptor (a boolean). -.. function:: set_inheritable(fd, inheritable) +.. function:: set_inheritable(fd, inheritable, /) Set the "inheritable" flag of the specified file descriptor. -.. function:: get_handle_inheritable(handle) +.. function:: get_handle_inheritable(handle, /) Get the "inheritable" flag of the specified handle (a boolean). .. availability:: Windows. -.. function:: set_handle_inheritable(handle, inheritable) +.. function:: set_handle_inheritable(handle, inheritable, /) Set the "inheritable" flag of the specified handle. @@ -2235,19 +2235,19 @@ features: Accepts a :term:`path-like object`. -.. function:: major(device) +.. function:: major(device, /) Extract the device major number from a raw device number (usually the :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`). -.. function:: minor(device) +.. function:: minor(device, /) Extract the device minor number from a raw device number (usually the :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`). -.. function:: makedev(major, minor) +.. function:: makedev(major, minor, /) Compose a raw device number from the major and minor device numbers. @@ -3903,7 +3903,7 @@ written in Python, such as a mail server's external command delivery program. .. availability:: Unix, not Emscripten, not WASI. -.. function:: kill(pid, sig) +.. function:: kill(pid, sig, /) .. index:: single: process; killing @@ -3930,7 +3930,7 @@ written in Python, such as a mail server's external command delivery program. Windows support. -.. function:: killpg(pgid, sig) +.. function:: killpg(pgid, sig, /) .. index:: single: process; killing @@ -3943,7 +3943,7 @@ written in Python, such as a mail server's external command delivery program. .. availability:: Unix, not Emscripten, not WASI. -.. function:: nice(increment) +.. function:: nice(increment, /) Add *increment* to the process's "niceness". Return the new niceness. @@ -3963,7 +3963,7 @@ written in Python, such as a mail server's external command delivery program. .. versionadded:: 3.9 -.. function:: plock(op) +.. function:: plock(op, /) Lock program segments into memory. The value of *op* (defined in ````) determines which segments are locked. @@ -4385,7 +4385,7 @@ written in Python, such as a mail server's external command delivery program. :func:`waitpid` can be used to wait for the completion of a specific child process and has more options. -.. function:: waitid(idtype, id, options) +.. function:: waitid(idtype, id, options, /) Wait for the completion of one or more child processes. *idtype* can be :data:`P_PID`, :data:`P_PGID`, :data:`P_ALL`, or @@ -4453,7 +4453,7 @@ written in Python, such as a mail server's external command delivery program. Added :data:`CLD_KILLED` and :data:`CLD_STOPPED` values. -.. function:: waitpid(pid, options) +.. function:: waitpid(pid, options, /) The details of this function differ on Unix and Windows. @@ -4582,7 +4582,7 @@ The following functions take a process status code as returned by :func:`system`, :func:`wait`, or :func:`waitpid` as a parameter. They may be used to determine the disposition of a process. -.. function:: WCOREDUMP(status) +.. function:: WCOREDUMP(status, /) Return ``True`` if a core dump was generated for the process, otherwise return ``False``. @@ -4727,33 +4727,33 @@ operating system. scheduling policy constants above. -.. function:: sched_setscheduler(pid, policy, param) +.. function:: sched_setscheduler(pid, policy, param, /) Set the scheduling policy for the process with PID *pid*. A *pid* of 0 means the calling process. *policy* is one of the scheduling policy constants above. *param* is a :class:`sched_param` instance. -.. function:: sched_getscheduler(pid) +.. function:: sched_getscheduler(pid, /) Return the scheduling policy for the process with PID *pid*. A *pid* of 0 means the calling process. The result is one of the scheduling policy constants above. -.. function:: sched_setparam(pid, param) +.. function:: sched_setparam(pid, param, /) Set the scheduling parameters for the process with PID *pid*. A *pid* of 0 means the calling process. *param* is a :class:`sched_param` instance. -.. function:: sched_getparam(pid) +.. function:: sched_getparam(pid, /) Return the scheduling parameters as a :class:`sched_param` instance for the process with PID *pid*. A *pid* of 0 means the calling process. -.. function:: sched_rr_get_interval(pid) +.. function:: sched_rr_get_interval(pid, /) Return the round-robin quantum in seconds for the process with PID *pid*. A *pid* of 0 means the calling process. @@ -4764,14 +4764,14 @@ operating system. Voluntarily relinquish the CPU. -.. function:: sched_setaffinity(pid, mask) +.. function:: sched_setaffinity(pid, mask, /) Restrict the process with PID *pid* (or the current process if zero) to a set of CPUs. *mask* is an iterable of integers representing the set of CPUs to which the process should be restricted. -.. function:: sched_getaffinity(pid) +.. function:: sched_getaffinity(pid, /) Return the set of CPUs the process with PID *pid* (or the current process if zero) is restricted to. @@ -4783,7 +4783,7 @@ Miscellaneous System Information -------------------------------- -.. function:: confstr(name) +.. function:: confstr(name, /) Return string-valued system configuration values. *name* specifies the configuration value to retrieve; it may be a string which is the name of a @@ -4834,7 +4834,7 @@ Miscellaneous System Information .. availability:: Unix. -.. function:: sysconf(name) +.. function:: sysconf(name, /) Return integer-valued system configuration values. If the configuration value specified by *name* isn't defined, ``-1`` is returned. The comments regarding @@ -4977,7 +4977,7 @@ Random numbers .. versionadded:: 3.6 -.. function:: urandom(size) +.. function:: urandom(size, /) Return a bytestring of *size* random bytes suitable for cryptographic use. -- cgit v0.12 From f0cbc6c18ea5c072b629df4aa300cfb0c862b111 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 28 Sep 2022 10:42:28 -0700 Subject: fixup policy docs (GH-97618) (cherry picked from commit 9a404b173e57ce171a867cfc3776cdf88d6c553f) Co-authored-by: Kumar Aditya <59607654+kumaraditya303@users.noreply.github.com> --- Doc/library/asyncio-policy.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/Doc/library/asyncio-policy.rst b/Doc/library/asyncio-policy.rst index ef6a058..d528db7 100644 --- a/Doc/library/asyncio-policy.rst +++ b/Doc/library/asyncio-policy.rst @@ -7,9 +7,14 @@ Policies ======== -An event loop policy is a global per-process object that controls -the management of the event loop. Each event loop has a default -policy, which can be changed and customized using the policy API. +An event loop policy is a global object +used to get and set the current :ref:`event loop `, +as well as create new event loops. +The default policy can be :ref:`replaced ` with +:ref:`built-in alternatives ` +to use different event loop implementations, +or substituted by a :ref:`custom policy ` +that can override these behaviors. A policy defines the notion of *context* and manages a separate event loop per context. The default policy -- cgit v0.12 From edc3356277ded2fbef14192bc34c4c133a53b8d7 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 28 Sep 2022 06:45:48 -0700 Subject: Fix docs on conditional expression grouping (GH-96447) (GH-97606) --- Doc/reference/expressions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 60136cd..4b8ceab 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -1892,7 +1892,7 @@ The following table summarizes the operator precedence in Python, from highest precedence (most binding) to lowest precedence (least binding). Operators in the same box have the same precedence. Unless the syntax is explicitly given, operators are binary. Operators in the same box group left to right (except for -exponentiation, which groups from right to left). +exponentiation and conditional expressions, which group from right to left). Note that comparisons, membership tests, and identity tests, all have the same precedence and have a left-to-right chaining feature as described in the -- cgit v0.12 From 8de353323ff36039a3bf24d16c619712615a05a7 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 27 Sep 2022 21:32:01 -0700 Subject: [3.11] gh-65046: Add note about logging from async code. (GH-97602) (GH-97608) --- Doc/howto/logging-cookbook.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Doc/howto/logging-cookbook.rst b/Doc/howto/logging-cookbook.rst index d1c3534..b49b00d 100644 --- a/Doc/howto/logging-cookbook.rst +++ b/Doc/howto/logging-cookbook.rst @@ -604,6 +604,14 @@ which, when run, will produce: MainThread: Look out! +.. note:: Although the earlier discussion wasn't specifically talking about + async code, but rather about slow logging handlers, it should be noted that + when logging from async code, network and even file handlers could lead to + problems (blocking the event loop) because some logging is done from + :mod:`asyncio` internals. It might be best, if any async code is used in an + application, to use the above approach for logging, so that any blocking code + runs only in the ``QueueListener`` thread. + .. versionchanged:: 3.5 Prior to Python 3.5, the :class:`QueueListener` always passed every message received from the queue to every handler it was initialized with. (This was -- cgit v0.12 From 2b0b01768352f3d7a4c7c146128a1ac89eac4809 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 27 Sep 2022 17:33:32 -0700 Subject: gh-96377: Update asyncio policy doc intro paras to be clear and accurate (GH-97603) Also fix up some cross-references in the asyncio docs. (cherry picked from commit cc0f3a10f0ee507d9044ef9036cf3e711c5338a9) Co-authored-by: C.A.M. Gerlach --- Doc/library/asyncio-dev.rst | 2 +- Doc/library/asyncio-eventloop.rst | 7 +++++-- Doc/library/asyncio-llapi-index.rst | 2 +- Doc/library/asyncio-policy.rst | 23 ++++++++++++++++------- 4 files changed, 23 insertions(+), 11 deletions(-) diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst index 29d69b9..921a394 100644 --- a/Doc/library/asyncio-dev.rst +++ b/Doc/library/asyncio-dev.rst @@ -109,7 +109,7 @@ that the event loop runs in. There is currently no way to schedule coroutines or callbacks directly from a different process (such as one started with -:mod:`multiprocessing`). The :ref:`Event Loop Methods ` +:mod:`multiprocessing`). The :ref:`asyncio-event-loop-methods` section lists APIs that can read from pipes and watch file descriptors without blocking the event loop. In addition, asyncio's :ref:`Subprocess ` APIs provide a way to start a diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 41ebc04..15f4f04 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -1,6 +1,8 @@ .. currentmodule:: asyncio +.. _asyncio-event-loop: + ========== Event Loop ========== @@ -92,7 +94,7 @@ This documentation page contains the following sections: loop APIs. -.. _asyncio-event-loop: +.. _asyncio-event-loop-methods: Event Loop Methods ================== @@ -1616,6 +1618,7 @@ Do not instantiate the class directly. .. _asyncio-event-loops: +.. _asyncio-event-loop-implementations: Event Loop Implementations ========================== @@ -1665,7 +1668,7 @@ on Unix and :class:`ProactorEventLoop` on Windows. Abstract base class for asyncio-compliant event loops. - The :ref:`Event Loop Methods ` section lists all + The :ref:`asyncio-event-loop-methods` section lists all methods that an alternative implementation of ``AbstractEventLoop`` should have defined. diff --git a/Doc/library/asyncio-llapi-index.rst b/Doc/library/asyncio-llapi-index.rst index cdadb79..c787cb9 100644 --- a/Doc/library/asyncio-llapi-index.rst +++ b/Doc/library/asyncio-llapi-index.rst @@ -37,7 +37,7 @@ Event Loop Methods ================== See also the main documentation section about the -:ref:`event loop methods `. +:ref:`asyncio-event-loop-methods`. .. rubric:: Lifecycle .. list-table:: diff --git a/Doc/library/asyncio-policy.rst b/Doc/library/asyncio-policy.rst index d528db7..a73e995 100644 --- a/Doc/library/asyncio-policy.rst +++ b/Doc/library/asyncio-policy.rst @@ -7,7 +7,7 @@ Policies ======== -An event loop policy is a global object +An event loop policy is a global (per-interpreter) object used to get and set the current :ref:`event loop `, as well as create new event loops. The default policy can be :ref:`replaced ` with @@ -16,18 +16,20 @@ to use different event loop implementations, or substituted by a :ref:`custom policy ` that can override these behaviors. -A policy defines the notion of *context* and manages a -separate event loop per context. The default policy -defines *context* to be the current thread. +The :ref:`policy object ` +gets and sets a separate event loop per *context*. +This is per-thread by default, +though custom policies could define *context* differently. -By using a custom event loop policy, the behavior of -:func:`get_event_loop`, :func:`set_event_loop`, and -:func:`new_event_loop` functions can be customized. +Custom event loop policies can control the behavior of +:func:`get_event_loop`, :func:`set_event_loop`, and :func:`new_event_loop`. Policy objects should implement the APIs defined in the :class:`AbstractEventLoopPolicy` abstract base class. +.. _asyncio-policy-get-set: + Getting and Setting the Policy ============================== @@ -45,6 +47,8 @@ for the current process: If *policy* is set to ``None``, the default policy is restored. +.. _asyncio-policy-objects: + Policy Objects ============== @@ -91,6 +95,8 @@ The abstract event loop policy base class is defined as follows: This function is Unix specific. +.. _asyncio-policy-builtin: + asyncio ships with the following built-in policies: @@ -122,6 +128,7 @@ asyncio ships with the following built-in policies: .. availability:: Windows. + .. _asyncio-watchers: Process Watchers @@ -275,6 +282,8 @@ implementation used by the asyncio event loop: .. versionadded:: 3.9 +.. _asyncio-custom-policies: + Custom Policies =============== -- cgit v0.12 From 50da78af68579ebc4d2efb0decb825ec6d859728 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 27 Sep 2022 04:16:37 -0700 Subject: gh-96959: Update more HTTP links (GH-97536) Use HTTPS for documents which are available by both HTTP and HTTPS links, but there is no redirection from HTTP to HTTPS or vice versa. (cherry picked from commit dd53b79de0ea98af6a11481217a961daef4e9774) Co-authored-by: Serhiy Storchaka --- Doc/faq/extending.rst | 2 +- Doc/faq/general.rst | 2 +- Doc/faq/gui.rst | 2 +- Doc/faq/library.rst | 4 +- Doc/faq/programming.rst | 4 +- Doc/library/ast.rst | 2 +- Doc/library/json.rst | 2 +- Doc/library/mailbox.rst | 2 +- Doc/library/random.rst | 6 +- Doc/library/tkinter.rst | 2 +- Doc/library/tkinter.tix.rst | 150 +++++++++++++++++++++--------------------- Doc/library/tkinter.ttk.rst | 4 +- Doc/library/xmlrpc.client.rst | 2 +- Doc/using/windows.rst | 2 +- Doc/whatsnew/2.0.rst | 2 +- Doc/whatsnew/2.3.rst | 2 +- Doc/whatsnew/3.2.rst | 6 +- Doc/whatsnew/3.4.rst | 2 +- Doc/whatsnew/3.5.rst | 2 +- Doc/whatsnew/3.6.rst | 2 +- Doc/whatsnew/3.7.rst | 2 +- Doc/whatsnew/3.8.rst | 2 +- 22 files changed, 103 insertions(+), 103 deletions(-) diff --git a/Doc/faq/extending.rst b/Doc/faq/extending.rst index 318e355..0728263 100644 --- a/Doc/faq/extending.rst +++ b/Doc/faq/extending.rst @@ -51,7 +51,7 @@ If you need to interface to some C or C++ library for which no Python extension currently exists, you can try wrapping the library's data types and functions with a tool such as `SWIG `_. `SIP `__, `CXX -`_ `Boost +`_ `Boost `_, or `Weave `_ are also alternatives for wrapping C++ libraries. diff --git a/Doc/faq/general.rst b/Doc/faq/general.rst index 2fb68f6..ad4e38a 100644 --- a/Doc/faq/general.rst +++ b/Doc/faq/general.rst @@ -335,7 +335,7 @@ Consulting the proceedings for `past Python conferences different companies and organizations. High-profile Python projects include `the Mailman mailing list manager -`_ and `the Zope application server +`_ and `the Zope application server `_. Several Linux distributions, most notably `Red Hat `_, have written part or all of their installer and system administration software in Python. Companies that use Python internally diff --git a/Doc/faq/gui.rst b/Doc/faq/gui.rst index 86c56d9..023ffdf 100644 --- a/Doc/faq/gui.rst +++ b/Doc/faq/gui.rst @@ -49,7 +49,7 @@ environment variables. To get truly stand-alone applications, the Tcl scripts that form the library have to be integrated into the application as well. One tool supporting that is SAM (stand-alone modules), which is part of the Tix distribution -(http://tix.sourceforge.net/). +(https://tix.sourceforge.net/). Build Tix with SAM enabled, perform the appropriate call to :c:func:`Tclsam_init`, etc. inside Python's diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst index 8c4baec..a9cde45 100644 --- a/Doc/faq/library.rst +++ b/Doc/faq/library.rst @@ -180,8 +180,8 @@ How do I create documentation from doc strings? The :mod:`pydoc` module can create HTML from the doc strings in your Python source code. An alternative for creating API documentation purely from -docstrings is `epydoc `_. `Sphinx -`_ can also include docstring content. +docstrings is `epydoc `_. `Sphinx +`_ can also include docstring content. How do I get a single keypress at a time? diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index c056446..676dfae 100644 --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -35,7 +35,7 @@ debugging non-PythonWin programs. PythonWin is available as part of as a part of the `ActivePython `_ distribution. -`Eric `_ is an IDE built on PyQt +`Eric `_ is an IDE built on PyQt and the Scintilla editing component. `trepan3k `_ is a gdb-like debugger. @@ -99,7 +99,7 @@ executables: * `PyOxidizer `_ (Cross-platform) * `cx_Freeze `_ (Cross-platform) * `py2app `_ (macOS only) -* `py2exe `_ (Windows only) +* `py2exe `_ (Windows only) Are there coding standards or a style guide for Python programs? ---------------------------------------------------------------- diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index b3c59c7..da0fe8c 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -2268,7 +2268,7 @@ to stdout. Otherwise, the content is read from stdin. code that generated them. This is helpful for tools that make source code transformations. - `leoAst.py `_ unifies the + `leoAst.py `_ unifies the token-based and parse-tree-based views of python programs by inserting two-way links between tokens and ast nodes. diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 3f74359..5383614 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -120,7 +120,7 @@ See :ref:`json-commandline` for detailed documentation. .. note:: - JSON is a subset of `YAML `_ 1.2. The JSON produced by + JSON is a subset of `YAML `_ 1.2. The JSON produced by this module's default settings (in particular, the default *separators* value) is also a subset of YAML 1.0 and 1.1. This module can thus also be used as a YAML serializer. diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index d74fc80..ff3da41 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -426,7 +426,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. .. seealso:: - `maildir man page from Courier `_ + `maildir man page from Courier `_ A specification of the format. Describes a common extension for supporting folders. diff --git a/Doc/library/random.rst b/Doc/library/random.rst index cf9f04d..661f7c9 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -550,13 +550,13 @@ Simulation of arrival times and service deliveries for a multiserver queue:: `Economics Simulation `_ a simulation of a marketplace by - `Peter Norvig `_ that shows effective + `Peter Norvig `_ that shows effective use of many of the tools and distributions provided by this module (gauss, uniform, sample, betavariate, choice, triangular, and randrange). `A Concrete Introduction to Probability (using Python) - `_ - a tutorial by `Peter Norvig `_ covering + `_ + a tutorial by `Peter Norvig `_ covering the basics of probability theory, how to write simulations, and how to perform data analysis using Python. diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 0d2b344..c8e4317 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -38,7 +38,7 @@ details that are unchanged. .. seealso:: - * `TkDocs `_ + * `TkDocs `_ Extensive tutorial on creating user interfaces with Tkinter. Explains key concepts, and illustrates recommended approaches using the modern API. diff --git a/Doc/library/tkinter.tix.rst b/Doc/library/tkinter.tix.rst index 88b936c..c86fcfa 100644 --- a/Doc/library/tkinter.tix.rst +++ b/Doc/library/tkinter.tix.rst @@ -33,17 +33,17 @@ special needs of your application and users. .. seealso:: - `Tix Homepage `_ + `Tix Homepage `_ The home page for :mod:`Tix`. This includes links to additional documentation and downloads. - `Tix Man Pages `_ + `Tix Man Pages `_ On-line version of the man pages and reference material. - `Tix Programming Guide `_ + `Tix Programming Guide `_ On-line version of the programmer's reference material. - `Tix Development Applications `_ + `Tix Development Applications `_ Tix applications for development of Tix and Tkinter programs. Tide applications work under Tk or Tkinter, and include :program:`TixInspect`, an inspector to remotely modify and debug Tix/Tk/Tkinter applications. @@ -80,7 +80,7 @@ the following:: Tix Widgets ----------- -`Tix `_ +`Tix `_ introduces over 40 widget classes to the :mod:`tkinter` repertoire. @@ -91,125 +91,125 @@ Basic Widgets .. class:: Balloon() A `Balloon - `_ that + `_ that pops up over a widget to provide help. When the user moves the cursor inside a widget to which a Balloon widget has been bound, a small pop-up window with a descriptive message will be shown on the screen. .. Python Demo of: -.. \ulink{Balloon}{http://tix.sourceforge.net/dist/current/demos/samples/Balloon.tcl} +.. \ulink{Balloon}{https://tix.sourceforge.net/dist/current/demos/samples/Balloon.tcl} .. class:: ButtonBox() The `ButtonBox - `_ + `_ widget creates a box of buttons, such as is commonly used for ``Ok Cancel``. .. Python Demo of: -.. \ulink{ButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/BtnBox.tcl} +.. \ulink{ButtonBox}{https://tix.sourceforge.net/dist/current/demos/samples/BtnBox.tcl} .. class:: ComboBox() The `ComboBox - `_ + `_ widget is similar to the combo box control in MS Windows. The user can select a choice by either typing in the entry subwidget or selecting from the listbox subwidget. .. Python Demo of: -.. \ulink{ComboBox}{http://tix.sourceforge.net/dist/current/demos/samples/ComboBox.tcl} +.. \ulink{ComboBox}{https://tix.sourceforge.net/dist/current/demos/samples/ComboBox.tcl} .. class:: Control() The `Control - `_ + `_ widget is also known as the :class:`SpinBox` widget. The user can adjust the value by pressing the two arrow buttons or by entering the value directly into the entry. The new value will be checked against the user-defined upper and lower limits. .. Python Demo of: -.. \ulink{Control}{http://tix.sourceforge.net/dist/current/demos/samples/Control.tcl} +.. \ulink{Control}{https://tix.sourceforge.net/dist/current/demos/samples/Control.tcl} .. class:: LabelEntry() The `LabelEntry - `_ + `_ widget packages an entry widget and a label into one mega widget. It can be used to simplify the creation of "entry-form" type of interface. .. Python Demo of: -.. \ulink{LabelEntry}{http://tix.sourceforge.net/dist/current/demos/samples/LabEntry.tcl} +.. \ulink{LabelEntry}{https://tix.sourceforge.net/dist/current/demos/samples/LabEntry.tcl} .. class:: LabelFrame() The `LabelFrame - `_ + `_ widget packages a frame widget and a label into one mega widget. To create widgets inside a LabelFrame widget, one creates the new widgets relative to the :attr:`frame` subwidget and manage them inside the :attr:`frame` subwidget. .. Python Demo of: -.. \ulink{LabelFrame}{http://tix.sourceforge.net/dist/current/demos/samples/LabFrame.tcl} +.. \ulink{LabelFrame}{https://tix.sourceforge.net/dist/current/demos/samples/LabFrame.tcl} .. class:: Meter() The `Meter - `_ widget + `_ widget can be used to show the progress of a background job which may take a long time to execute. .. Python Demo of: -.. \ulink{Meter}{http://tix.sourceforge.net/dist/current/demos/samples/Meter.tcl} +.. \ulink{Meter}{https://tix.sourceforge.net/dist/current/demos/samples/Meter.tcl} .. class:: OptionMenu() The `OptionMenu - `_ + `_ creates a menu button of options. .. Python Demo of: -.. \ulink{OptionMenu}{http://tix.sourceforge.net/dist/current/demos/samples/OptMenu.tcl} +.. \ulink{OptionMenu}{https://tix.sourceforge.net/dist/current/demos/samples/OptMenu.tcl} .. class:: PopupMenu() The `PopupMenu - `_ + `_ widget can be used as a replacement of the ``tk_popup`` command. The advantage of the :mod:`Tix` :class:`PopupMenu` widget is it requires less application code to manipulate. .. Python Demo of: -.. \ulink{PopupMenu}{http://tix.sourceforge.net/dist/current/demos/samples/PopMenu.tcl} +.. \ulink{PopupMenu}{https://tix.sourceforge.net/dist/current/demos/samples/PopMenu.tcl} .. class:: Select() The `Select - `_ widget + `_ widget is a container of button subwidgets. It can be used to provide radio-box or check-box style of selection options for the user. .. Python Demo of: -.. \ulink{Select}{http://tix.sourceforge.net/dist/current/demos/samples/Select.tcl} +.. \ulink{Select}{https://tix.sourceforge.net/dist/current/demos/samples/Select.tcl} .. class:: StdButtonBox() The `StdButtonBox - `_ + `_ widget is a group of standard buttons for Motif-like dialog boxes. .. Python Demo of: -.. \ulink{StdButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/StdBBox.tcl} +.. \ulink{StdButtonBox}{https://tix.sourceforge.net/dist/current/demos/samples/StdBBox.tcl} File Selectors @@ -219,37 +219,37 @@ File Selectors .. class:: DirList() The `DirList - `_ + `_ widget displays a list view of a directory, its previous directories and its sub-directories. The user can choose one of the directories displayed in the list or change to another directory. .. Python Demo of: -.. \ulink{DirList}{http://tix.sourceforge.net/dist/current/demos/samples/DirList.tcl} +.. \ulink{DirList}{https://tix.sourceforge.net/dist/current/demos/samples/DirList.tcl} .. class:: DirTree() The `DirTree - `_ + `_ widget displays a tree view of a directory, its previous directories and its sub-directories. The user can choose one of the directories displayed in the list or change to another directory. .. Python Demo of: -.. \ulink{DirTree}{http://tix.sourceforge.net/dist/current/demos/samples/DirTree.tcl} +.. \ulink{DirTree}{https://tix.sourceforge.net/dist/current/demos/samples/DirTree.tcl} .. class:: DirSelectDialog() The `DirSelectDialog - `_ + `_ widget presents the directories in the file system in a dialog window. The user can use this dialog window to navigate through the file system to select the desired directory. .. Python Demo of: -.. \ulink{DirSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/DirDlg.tcl} +.. \ulink{DirSelectDialog}{https://tix.sourceforge.net/dist/current/demos/samples/DirDlg.tcl} .. class:: DirSelectBox() @@ -263,39 +263,39 @@ File Selectors .. class:: ExFileSelectBox() The `ExFileSelectBox - `_ + `_ widget is usually embedded in a tixExFileSelectDialog widget. It provides a convenient method for the user to select files. The style of the :class:`ExFileSelectBox` widget is very similar to the standard file dialog on MS Windows 3.1. .. Python Demo of: -.. \ulink{ExFileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/EFileDlg.tcl} +.. \ulink{ExFileSelectDialog}{https://tix.sourceforge.net/dist/current/demos/samples/EFileDlg.tcl} .. class:: FileSelectBox() The `FileSelectBox - `_ + `_ is similar to the standard Motif(TM) file-selection box. It is generally used for the user to choose a file. FileSelectBox stores the files mostly recently selected into a :class:`ComboBox` widget so that they can be quickly selected again. .. Python Demo of: -.. \ulink{FileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/FileDlg.tcl} +.. \ulink{FileSelectDialog}{https://tix.sourceforge.net/dist/current/demos/samples/FileDlg.tcl} .. class:: FileEntry() The `FileEntry - `_ + `_ widget can be used to input a filename. The user can type in the filename manually. Alternatively, the user can press the button widget that sits next to the entry, which will bring up a file selection dialog. .. Python Demo of: -.. \ulink{FileEntry}{http://tix.sourceforge.net/dist/current/demos/samples/FileEnt.tcl} +.. \ulink{FileEntry}{https://tix.sourceforge.net/dist/current/demos/samples/FileEnt.tcl} Hierarchical ListBox @@ -305,42 +305,42 @@ Hierarchical ListBox .. class:: HList() The `HList - `_ widget + `_ widget can be used to display any data that have a hierarchical structure, for example, file system directory trees. The list entries are indented and connected by branch lines according to their places in the hierarchy. .. Python Demo of: -.. \ulink{HList}{http://tix.sourceforge.net/dist/current/demos/samples/HList1.tcl} +.. \ulink{HList}{https://tix.sourceforge.net/dist/current/demos/samples/HList1.tcl} .. class:: CheckList() The `CheckList - `_ + `_ widget displays a list of items to be selected by the user. CheckList acts similarly to the Tk checkbutton or radiobutton widgets, except it is capable of handling many more items than checkbuttons or radiobuttons. .. Python Demo of: -.. \ulink{ CheckList}{http://tix.sourceforge.net/dist/current/demos/samples/ChkList.tcl} +.. \ulink{ CheckList}{https://tix.sourceforge.net/dist/current/demos/samples/ChkList.tcl} .. Python Demo of: -.. \ulink{ScrolledHList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList.tcl} +.. \ulink{ScrolledHList (1)}{https://tix.sourceforge.net/dist/current/demos/samples/SHList.tcl} .. Python Demo of: -.. \ulink{ScrolledHList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList2.tcl} +.. \ulink{ScrolledHList (2)}{https://tix.sourceforge.net/dist/current/demos/samples/SHList2.tcl} .. class:: Tree() The `Tree - `_ widget + `_ widget can be used to display hierarchical data in a tree form. The user can adjust the view of the tree by opening or closing parts of the tree. .. Python Demo of: -.. \ulink{Tree}{http://tix.sourceforge.net/dist/current/demos/samples/Tree.tcl} +.. \ulink{Tree}{https://tix.sourceforge.net/dist/current/demos/samples/Tree.tcl} .. Python Demo of: -.. \ulink{Tree (Dynamic)}{http://tix.sourceforge.net/dist/current/demos/samples/DynTree.tcl} +.. \ulink{Tree (Dynamic)}{https://tix.sourceforge.net/dist/current/demos/samples/DynTree.tcl} Tabular ListBox @@ -350,7 +350,7 @@ Tabular ListBox .. class:: TList() The `TList - `_ widget + `_ widget can be used to display data in a tabular format. The list entries of a :class:`TList` widget are similar to the entries in the Tk listbox widget. The main differences are (1) the :class:`TList` widget can display the list entries @@ -358,17 +358,17 @@ Tabular ListBox multiple colors and fonts for the list entries. .. Python Demo of: -.. \ulink{ScrolledTList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/STList1.tcl} +.. \ulink{ScrolledTList (1)}{https://tix.sourceforge.net/dist/current/demos/samples/STList1.tcl} .. Python Demo of: -.. \ulink{ScrolledTList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/STList2.tcl} +.. \ulink{ScrolledTList (2)}{https://tix.sourceforge.net/dist/current/demos/samples/STList2.tcl} .. Grid has yet to be added to Python .. \subsubsection{Grid Widget} .. Python Demo of: -.. \ulink{Simple Grid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid0.tcl} +.. \ulink{Simple Grid}{https://tix.sourceforge.net/dist/current/demos/samples/SGrid0.tcl} .. Python Demo of: -.. \ulink{ScrolledGrid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid1.tcl} +.. \ulink{ScrolledGrid}{https://tix.sourceforge.net/dist/current/demos/samples/SGrid1.tcl} .. Python Demo of: -.. \ulink{Editable Grid}{http://tix.sourceforge.net/dist/current/demos/samples/EditGrid.tcl} +.. \ulink{Editable Grid}{https://tix.sourceforge.net/dist/current/demos/samples/EditGrid.tcl} Manager Widgets @@ -378,19 +378,19 @@ Manager Widgets .. class:: PanedWindow() The `PanedWindow - `_ + `_ widget allows the user to interactively manipulate the sizes of several panes. The panes can be arranged either vertically or horizontally. The user changes the sizes of the panes by dragging the resize handle between two panes. .. Python Demo of: -.. \ulink{PanedWindow}{http://tix.sourceforge.net/dist/current/demos/samples/PanedWin.tcl} +.. \ulink{PanedWindow}{https://tix.sourceforge.net/dist/current/demos/samples/PanedWin.tcl} .. class:: ListNoteBook() The `ListNoteBook - `_ + `_ widget is very similar to the :class:`TixNoteBook` widget: it can be used to display many windows in a limited space using a notebook metaphor. The notebook is divided into a stack of pages (windows). At one time only one of these pages @@ -398,30 +398,30 @@ Manager Widgets the desired page in the :attr:`hlist` subwidget. .. Python Demo of: -.. \ulink{ListNoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/ListNBK.tcl} +.. \ulink{ListNoteBook}{https://tix.sourceforge.net/dist/current/demos/samples/ListNBK.tcl} .. class:: NoteBook() The `NoteBook - `_ + `_ widget can be used to display many windows in a limited space using a notebook metaphor. The notebook is divided into a stack of pages. At one time only one of these pages can be shown. The user can navigate through these pages by choosing the visual "tabs" at the top of the NoteBook widget. .. Python Demo of: -.. \ulink{NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/NoteBook.tcl} +.. \ulink{NoteBook}{https://tix.sourceforge.net/dist/current/demos/samples/NoteBook.tcl} .. \subsubsection{Scrolled Widgets} .. Python Demo of: -.. \ulink{ScrolledListBox}{http://tix.sourceforge.net/dist/current/demos/samples/SListBox.tcl} +.. \ulink{ScrolledListBox}{https://tix.sourceforge.net/dist/current/demos/samples/SListBox.tcl} .. Python Demo of: -.. \ulink{ScrolledText}{http://tix.sourceforge.net/dist/current/demos/samples/SText.tcl} +.. \ulink{ScrolledText}{https://tix.sourceforge.net/dist/current/demos/samples/SText.tcl} .. Python Demo of: -.. \ulink{ScrolledWindow}{http://tix.sourceforge.net/dist/current/demos/samples/SWindow.tcl} +.. \ulink{ScrolledWindow}{https://tix.sourceforge.net/dist/current/demos/samples/SWindow.tcl} .. Python Demo of: -.. \ulink{Canvas Object View}{http://tix.sourceforge.net/dist/current/demos/samples/CObjView.tcl} +.. \ulink{Canvas Object View}{https://tix.sourceforge.net/dist/current/demos/samples/CObjView.tcl} Image Types @@ -429,17 +429,17 @@ Image Types The :mod:`tkinter.tix` module adds: -* `pixmap `_ +* `pixmap `_ capabilities to all :mod:`tkinter.tix` and :mod:`tkinter` widgets to create color images from XPM files. .. Python Demo of: - .. \ulink{XPM Image In Button}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl} + .. \ulink{XPM Image In Button}{https://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl} .. Python Demo of: - .. \ulink{XPM Image In Menu}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm1.tcl} + .. \ulink{XPM Image In Menu}{https://tix.sourceforge.net/dist/current/demos/samples/Xpm1.tcl} * `Compound - `_ image + `_ image types can be used to create images that consists of multiple horizontal lines; each line is composed of a series of items (texts, bitmaps, images or spaces) arranged from left to right. For example, a compound image can be used to @@ -447,13 +447,13 @@ The :mod:`tkinter.tix` module adds: widget. .. Python Demo of: - .. \ulink{Compound Image In Buttons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg.tcl} + .. \ulink{Compound Image In Buttons}{https://tix.sourceforge.net/dist/current/demos/samples/CmpImg.tcl} .. Python Demo of: - .. \ulink{Compound Image In NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg2.tcl} + .. \ulink{Compound Image In NoteBook}{https://tix.sourceforge.net/dist/current/demos/samples/CmpImg2.tcl} .. Python Demo of: - .. \ulink{Compound Image Notebook Color Tabs}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg4.tcl} + .. \ulink{Compound Image Notebook Color Tabs}{https://tix.sourceforge.net/dist/current/demos/samples/CmpImg4.tcl} .. Python Demo of: - .. \ulink{Compound Image Icons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg3.tcl} + .. \ulink{Compound Image Icons}{https://tix.sourceforge.net/dist/current/demos/samples/CmpImg3.tcl} Miscellaneous Widgets @@ -463,7 +463,7 @@ Miscellaneous Widgets .. class:: InputOnly() The `InputOnly - `_ + `_ widgets are to accept inputs from the user, which can be done with the ``bind`` command (Unix only). @@ -477,7 +477,7 @@ In addition, :mod:`tkinter.tix` augments :mod:`tkinter` by providing: .. class:: Form() The `Form - `_ geometry + `_ geometry manager based on attachment rules for all Tk widgets. @@ -488,7 +488,7 @@ Tix Commands .. class:: tixCommand() The `tix commands - `_ provide + `_ provide access to miscellaneous elements of :mod:`Tix`'s internal state and the :mod:`Tix` application context. Most of the information manipulated by these methods pertains to the application as a whole, or to a screen or display, diff --git a/Doc/library/tkinter.ttk.rst b/Doc/library/tkinter.ttk.rst index b05799e..4ff2b21 100644 --- a/Doc/library/tkinter.ttk.rst +++ b/Doc/library/tkinter.ttk.rst @@ -56,7 +56,7 @@ for improved styling effects. .. seealso:: - `Converting existing applications to use Tile widgets `_ + `Converting existing applications to use Tile widgets `_ A monograph (using Tcl terminology) about differences typically encountered when moving applications to use the new widgets. @@ -1272,7 +1272,7 @@ option. If you don't know the class name of a widget, use the method .. seealso:: - `Tcl'2004 conference presentation `_ + `Tcl'2004 conference presentation `_ This document explains how the theme engine works diff --git a/Doc/library/xmlrpc.client.rst b/Doc/library/xmlrpc.client.rst index 2dcf398..8b09acd 100644 --- a/Doc/library/xmlrpc.client.rst +++ b/Doc/library/xmlrpc.client.rst @@ -165,7 +165,7 @@ between conformable Python objects and XML on the wire. A good description of XML-RPC operation and client software in several languages. Contains pretty much everything an XML-RPC client developer needs to know. - `XML-RPC Introspection `_ + `XML-RPC Introspection `_ Describes the XML-RPC protocol extension for introspection. `XML-RPC Specification `_ diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst index 84441a5..e338b11 100644 --- a/Doc/using/windows.rst +++ b/Doc/using/windows.rst @@ -1217,7 +1217,7 @@ With ongoing development of Python, some platforms that used to be supported earlier are no longer supported (due to the lack of users or developers). Check :pep:`11` for details on all unsupported platforms. -* `Windows CE `_ is +* `Windows CE `_ is `no longer supported `__ since Python 3 (if it ever was). * The `Cygwin `_ installer offers to install the diff --git a/Doc/whatsnew/2.0.rst b/Doc/whatsnew/2.0.rst index 24fc39b..6b16dfd 100644 --- a/Doc/whatsnew/2.0.rst +++ b/Doc/whatsnew/2.0.rst @@ -572,7 +572,7 @@ Work has been done on porting Python to 64-bit Windows on the Itanium processor, mostly by Trent Mick of ActiveState. (Confusingly, ``sys.platform`` is still ``'win32'`` on Win64 because it seems that for ease of porting, MS Visual C++ treats code as 32 bit on Itanium.) PythonWin also supports Windows CE; see the -Python CE page at http://pythonce.sourceforge.net/ for more information. +Python CE page at https://pythonce.sourceforge.net/ for more information. Another new platform is Darwin/MacOS X; initial support for it is in Python 2.0. Dynamic loading works, if you specify "configure --with-dyld --with-suffix=.x". diff --git a/Doc/whatsnew/2.3.rst b/Doc/whatsnew/2.3.rst index 4b9f7a2..c6e2003 100644 --- a/Doc/whatsnew/2.3.rst +++ b/Doc/whatsnew/2.3.rst @@ -1231,7 +1231,7 @@ complete list of changes, or look through the CVS logs for all the details. repeat an array. (Contributed by Jason Orendorff.) * The :mod:`bsddb` module has been replaced by version 4.1.6 of the `PyBSDDB - `_ package, providing a more complete interface + `_ package, providing a more complete interface to the transactional features of the BerkeleyDB library. The old version of the module has been renamed to :mod:`bsddb185` and is no diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst index 8a2159d..7b12e63 100644 --- a/Doc/whatsnew/3.2.rst +++ b/Doc/whatsnew/3.2.rst @@ -973,7 +973,7 @@ sites do not finish before midnight, the barrier times-out and the ballots are sealed and deposited in a queue for later handling. See `Barrier Synchronization Patterns -`_ +`_ for more examples of how barriers can be used in parallel computing. Also, there is a simple but thorough explanation of barriers in `The Little Book of Semaphores `_, *section 3.6*. @@ -2419,7 +2419,7 @@ Unicode ======= Python has been updated to `Unicode 6.0.0 -`_. The update to the standard adds +`_. The update to the standard adds over 2,000 new characters including `emoji `_ symbols which are important for mobile phones. @@ -2427,7 +2427,7 @@ In addition, the updated standard has altered the character properties for two Kannada characters (U+0CF1, U+0CF2) and one New Tai Lue numeric character (U+19DA), making the former eligible for use in identifiers while disqualifying the latter. For more information, see `Unicode Character Database Changes -`_. +`_. Codecs diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst index a09b60f..9f894b4 100644 --- a/Doc/whatsnew/3.4.rst +++ b/Doc/whatsnew/3.4.rst @@ -1963,7 +1963,7 @@ Other Improvements `_ will build python, run the test suite, and generate an HTML coverage report for the C codebase using ``gcov`` and `lcov - `_. + `_. * The ``-R`` option to the :ref:`python regression test suite ` now also checks for memory allocation leaks, using diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst index 89b8eef..625373d 100644 --- a/Doc/whatsnew/3.5.rst +++ b/Doc/whatsnew/3.5.rst @@ -1977,7 +1977,7 @@ unicodedata ----------- The :mod:`unicodedata` module now uses data from `Unicode 8.0.0 -`_. +`_. unittest diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst index e54475f..bcca28d 100644 --- a/Doc/whatsnew/3.6.rst +++ b/Doc/whatsnew/3.6.rst @@ -1644,7 +1644,7 @@ unicodedata ----------- The :mod:`unicodedata` module now uses data from `Unicode 9.0.0 -`_. +`_. (Contributed by Benjamin Peterson.) diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst index e56d428..5bb3d2a 100644 --- a/Doc/whatsnew/3.7.rst +++ b/Doc/whatsnew/3.7.rst @@ -1507,7 +1507,7 @@ unicodedata ----------- The internal :mod:`unicodedata` database has been upgraded to use `Unicode 11 -`_. (Contributed by Benjamin +`_. (Contributed by Benjamin Peterson.) diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst index 9426ea7..7f3083b 100644 --- a/Doc/whatsnew/3.8.rst +++ b/Doc/whatsnew/3.8.rst @@ -1347,7 +1347,7 @@ unicodedata ----------- The :mod:`unicodedata` module has been upgraded to use the `Unicode 12.1.0 -`_ release. +`_ release. New function :func:`~unicodedata.is_normalized` can be used to verify a string is in a specific normal form, often much faster than by actually normalizing -- cgit v0.12 From e65e6de0fbfdb1e030b3ba067913e953dff2257f Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 26 Sep 2022 15:45:58 -0700 Subject: GH-65046: Fix docs about logging in `asyncio` (GH-97559) Explain that logging should not use network I/O. (cherry picked from commit d68c37c0d08542a346a13b150a204208bb0408f5) Co-authored-by: Kumar Aditya <59607654+kumaraditya303@users.noreply.github.com> --- Doc/library/asyncio-dev.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst index 921a394..14f2c35 100644 --- a/Doc/library/asyncio-dev.rst +++ b/Doc/library/asyncio-dev.rst @@ -149,8 +149,7 @@ adjusted:: Network logging can block the event loop. It is recommended to use -a separate thread for handling logs or use non-blocking IO. For example, -see :ref:`blocking-handlers`. +a separate thread for handling logs or use non-blocking IO. .. _asyncio-coroutine-not-scheduled: -- cgit v0.12 From 1281d35a8a4f0678c2f67095de08bee94b3fe670 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sun, 25 Sep 2022 21:15:52 -0700 Subject: gh-82530: Create blank function instead of invalid import for email example (GH-97529) Co-authored-by: Terry Jan Reedy (cherry picked from commit 2b428a1faed88f148ede131e3b86ab6227c6c3f0) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> --- Doc/includes/email-read-alternative.py | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/Doc/includes/email-read-alternative.py b/Doc/includes/email-read-alternative.py index 5ea84e6..8d0b4e6 100644 --- a/Doc/includes/email-read-alternative.py +++ b/Doc/includes/email-read-alternative.py @@ -8,8 +8,15 @@ import webbrowser from email import policy from email.parser import BytesParser -# An imaginary module that would make this work and be safe. -from imaginary import magic_html_parser + +def magic_html_parser(html_text, partfiles): + """Return safety-sanitized html linked to partfiles. + + Rewrite the href="cid:...." attributes to point to the filenames in partfiles. + Though not trivial, this should be possible using html.parser. + """ + raise NotImplementedError("Add the magic needed") + # In a real program you'd get the filename from the arguments. with open('outgoing.msg', 'rb') as fp: @@ -62,9 +69,6 @@ else: print("Don't know how to display {}".format(richest.get_content_type())) sys.exit() with tempfile.NamedTemporaryFile(mode='w', delete=False) as f: - # The magic_html_parser has to rewrite the href="cid:...." attributes to - # point to the filenames in partfiles. It also has to do a safety-sanitize - # of the html. It could be written using html.parser. f.write(magic_html_parser(body.get_content(), partfiles)) webbrowser.open(f.name) os.remove(f.name) -- cgit v0.12 From 00e8a27dee50707ce53c19b8a7150fac80ae3648 Mon Sep 17 00:00:00 2001 From: Steve Dower Date: Fri, 23 Sep 2022 13:55:06 +0100 Subject: gh-77171: Document that wave only supports simple PCM files (GH-97510) --- Doc/library/wave.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/wave.rst b/Doc/library/wave.rst index f63e0d3..d50aabd 100644 --- a/Doc/library/wave.rst +++ b/Doc/library/wave.rst @@ -12,7 +12,8 @@ -------------- The :mod:`wave` module provides a convenient interface to the WAV sound format. -It does not support compression/decompression, but it does support mono/stereo. +Only files using ``WAVE_FORMAT_PCM`` are supported. Note that this does not +include files using ``WAVE_FORMAT_EXTENSIBLE`` even if the subformat is PCM. The :mod:`wave` module defines the following function and exception: -- cgit v0.12 From c10f8c824783ac4e0f6405808937e4680e683ebd Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Fri, 23 Sep 2022 03:54:53 -0700 Subject: gh-75608: Add Windows FAQ entry for missing UCRT (GH-92765) (cherry picked from commit 80bc7d7c0a3f777da244ec79429baf382523b8da) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> --- Doc/faq/windows.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Doc/faq/windows.rst b/Doc/faq/windows.rst index df7ab71..7768aaf 100644 --- a/Doc/faq/windows.rst +++ b/Doc/faq/windows.rst @@ -276,3 +276,11 @@ How do I check for a keypress without blocking? Use the :mod:`msvcrt` module. This is a standard Windows-specific extension module. It defines a function ``kbhit()`` which checks whether a keyboard hit is present, and ``getch()`` which gets one character without echoing it. + +How do I solve the missing api-ms-win-crt-runtime-l1-1-0.dll error? +------------------------------------------------------------------- + +This can occur on Python 3.5 and later when using Windows 8.1 or earlier without all updates having been installed. +First ensure your operating system is supported and is up to date, and if that does not resolve the issue, +visit the `Microsoft support page `_ +for guidance on manually installing the C Runtime update. -- cgit v0.12 From 50c0a22bc36deb0d667f9e1506b921a791d93e48 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 22 Sep 2022 11:18:02 -0700 Subject: gh-96397: Document that keywords in calls need not be identifiers (GH-96393) This represents the official SC stance, see https://github.com/python/steering-council/issues/142GH-issuecomment-1252172695 (cherry picked from commit 9d432b4a181cd42017699de4354e7b36c5b87d88) Co-authored-by: Jeff Allen --- Doc/reference/expressions.rst | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 4b8ceab..6b5e0e1 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -1054,10 +1054,20 @@ used in the same call, so in practice this confusion does not often arise. If the syntax ``**expression`` appears in the function call, ``expression`` must evaluate to a :term:`mapping`, the contents of which are treated as -additional keyword arguments. If a keyword is already present -(as an explicit keyword argument, or from another unpacking), +additional keyword arguments. If a parameter matching a key has already been +given a value (by an explicit keyword argument, or from another unpacking), a :exc:`TypeError` exception is raised. +When ``**expression`` is used, each key in this mapping must be +a string. +Each value from the mapping is assigned to the first formal parameter +eligible for keyword assignment whose name is equal to the key. +A key need not be a Python identifier (e.g. ``"max-temp °F"`` is acceptable, +although it will not match any formal parameter that could be declared). +If there is no match to a formal parameter +the key-value pair is collected by the ``**`` parameter, if there is one, +or if there is not, a :exc:`TypeError` exception is raised. + Formal parameters using the syntax ``*identifier`` or ``**identifier`` cannot be used as positional argument slots or as keyword argument names. -- cgit v0.12 From a592f84f50d4cf9b3621f76259c0e10981b27195 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 21 Sep 2022 06:11:48 -0700 Subject: gh-81039: Add small example of f-string's "=}" to tutorial (gh-92291) (gh-96989) (cherry picked from commit 4b81139aac3fa11779f6eedb6e621bde29e64b30) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com> --- Doc/tutorial/inputoutput.rst | 12 +++++++++++- Doc/whatsnew/3.8.rst | 1 + 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/Doc/tutorial/inputoutput.rst b/Doc/tutorial/inputoutput.rst index d341400..de84ab7 100644 --- a/Doc/tutorial/inputoutput.rst +++ b/Doc/tutorial/inputoutput.rst @@ -133,7 +133,17 @@ applies :func:`repr`:: >>> print(f'My hovercraft is full of {animals!r}.') My hovercraft is full of 'eels'. -For a reference on these format specifications, see +The ``=`` specifier can be used to expand an expression to the text of the +expression, an equal sign, then the representation of the evaluated expression: + + >>> bugs = 'roaches' + >>> count = 13 + >>> area = 'living room' + >>> print(f'Debugging {bugs=} {count=} {area=}') + Debugging bugs='roaches' count=13 area='living room' + +See :ref:`self-documenting expressions ` for more information +on the ``=`` specifier. For a reference on these format specifications, see the reference guide for the :ref:`formatspec`. .. _tut-string-format: diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst index 7f3083b..7f85ff3 100644 --- a/Doc/whatsnew/3.8.rst +++ b/Doc/whatsnew/3.8.rst @@ -250,6 +250,7 @@ Android and Cygwin, whose cases are handled by the script); this change is backward incompatible on purpose. (Contributed by Victor Stinner in :issue:`36721`.) +.. _bpo-36817-whatsnew: f-strings support ``=`` for self-documenting expressions and debugging ---------------------------------------------------------------------- -- cgit v0.12 From 64640964002bef23df8666a5dcd08c7118ab2659 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 20 Sep 2022 01:52:09 -0700 Subject: [3.11] gh-96727: Document restrictions on Handler.emit() with respect to locking. (GH-96948) (GH-96950) (cherry picked from commit 6ad47b41a650a13b4a9214309c10239726331eb8) --- Doc/library/logging.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index eacba56..9390f06 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -522,6 +522,22 @@ subclasses. However, the :meth:`__init__` method in subclasses needs to call is intended to be implemented by subclasses and so raises a :exc:`NotImplementedError`. + .. warning:: This method is called after a handler-level lock is acquired, which + is released after this method returns. When you override this method, note + that you should be careful when calling anything that invokes other parts of + the logging API which might do locking, because that might result in a + deadlock. Specifically: + + * Logging configuration APIs acquire the module-level lock, and then + individual handler-level locks as those handlers are configured. + + * Many logging APIs lock the module-level lock. If such an API is called + from this method, it could cause a deadlock if a configuration call is + made on another thread, because that thread will try to acquire the + module-level lock *before* the handler-level lock, whereas this thread + tries to acquire the module-level lock *after* the handler-level lock + (because in this method, the handler-level lock has already been acquired). + For a list of handlers included as standard, see :mod:`logging.handlers`. .. _formatter-objects: -- cgit v0.12 From 2a1e9b01d166d43d8c261f788545ded839eb52c9 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 19 Sep 2022 12:19:18 -0700 Subject: gh-96917: link to typing.readthedocs.io from typing.rst (GH-96921) See the discussion at https://github.com/python/cpython/issues/91533 (cherry picked from commit 5b3a2569f4b4dfb58a8f90a241f9dac1a7ea4bf6) Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com> --- Doc/library/typing.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index b75753f..04f63f6 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -39,6 +39,11 @@ provides backports of these new features to older versions of Python. For a summary of deprecated features and a deprecation timeline, please see `Deprecation Timeline of Major Features`_. +.. seealso:: + + The documentation at https://typing.readthedocs.io/ serves as useful reference + for type system features, useful typing related tools and typing best practices. + .. _relevant-peps: -- cgit v0.12 From 837c1206b28f71b9bfca30225bbc5f4f24e2b84d Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 19 Sep 2022 06:51:08 -0700 Subject: gh-95913: Copyedit, link & format Typing Features section in 3.11 What's New (GH-96097) Co-authored-by: Ezio Melotti Co-authored-by: Alex Waygood (cherry picked from commit 558768ff22e47582ae95ad7c3f8955407934916e) Co-authored-by: C.A.M. Gerlach --- Doc/whatsnew/3.11.rst | 73 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 50 insertions(+), 23 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index d241cd5..203c536 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -231,6 +231,7 @@ All releases of Python since 3.5 have included this in their 32-bit builds. .. _new-feat-related-type-hints-311: +.. _whatsnew311-typing-features: New Features Related to Type Hints ================================== @@ -238,15 +239,20 @@ New Features Related to Type Hints This section covers major changes affecting :pep:`484` type hints and the :mod:`typing` module. + +.. _whatsnew311-pep646: + PEP 646: Variadic generics -------------------------- -:pep:`484` introduced :data:`~typing.TypeVar`, enabling creation -of generics parameterised with a single type. :pep:`646` introduces +:pep:`484` previously introduced :data:`~typing.TypeVar`, enabling creation +of generics parameterised with a single type. :pep:`646` adds :data:`~typing.TypeVarTuple`, enabling parameterisation with an *arbitrary* number of types. In other words, a :data:`~typing.TypeVarTuple` is a *variadic* type variable, -enabling *variadic* generics. This enables a wide variety of use cases. +enabling *variadic* generics. + +This enables a wide variety of use cases. In particular, it allows the type of array-like structures in numerical computing libraries such as NumPy and TensorFlow to be parameterised with the array *shape*. Static type checkers will now @@ -258,26 +264,30 @@ See :pep:`646` for more details. Serhiy Storchaka and Jelle Zijlstra. PEP written by Mark Mendoza, Matthew Rahtz, Pradeep Kumar Srinivasan, and Vincent Siles.) + +.. _whatsnew311-pep655: + PEP 655: Marking individual ``TypedDict`` items as required or not-required --------------------------------------------------------------------------- :data:`~typing.Required` and :data:`~typing.NotRequired` provide a straightforward way to mark whether individual items in a -:data:`~typing.TypedDict` must be present. Previously this was only possible +:class:`~typing.TypedDict` must be present. Previously, this was only possible using inheritance. -Fields are still required by default, unless the ``total=False`` -parameter is set. -For example, the following specifies a dictionary with one required and -one not-required key:: +All fields are still required by default, +unless the *total* parameter is set to ``False``, +in which case all fields are still not-required by default. +For example, the following specifies a :class:`!TypedDict` +with one required and one not-required key:: class Movie(TypedDict): title: str year: NotRequired[int] - m1: Movie = {"title": "Black Panther", "year": 2018} # ok - m2: Movie = {"title": "Star Wars"} # ok (year is not required) - m3: Movie = {"year": 2022} # error (missing required field title) + m1: Movie = {"title": "Black Panther", "year": 2018} # OK + m2: Movie = {"title": "Star Wars"} # OK (year is not required) + m3: Movie = {"year": 2022} # ERROR (missing required field title) The following definition is equivalent:: @@ -290,15 +300,20 @@ See :pep:`655` for more details. (Contributed by David Foster and Jelle Zijlstra in :issue:`47087`. PEP written by David Foster.) + +.. _whatsnew311-pep673: + PEP 673: ``Self`` type ---------------------- The new :data:`~typing.Self` annotation provides a simple and intuitive way to annotate methods that return an instance of their class. This -behaves the same as the :data:`~typing.TypeVar`-based approach specified -in :pep:`484` but is more concise and easier to follow. +behaves the same as the :class:`~typing.TypeVar`-based approach +:pep:`specified in PEP 484 <484#annotating-instance-and-class-methods>`, +but is more concise and easier to follow. -Common use cases include alternative constructors provided as classmethods +Common use cases include alternative constructors provided as +:func:`classmethod `\s, and :meth:`~object.__enter__` methods that return ``self``:: class MyLock: @@ -323,6 +338,9 @@ See :pep:`673` for more details. (Contributed by James Hilton-Balfe in :issue:`46534`. PEP written by Pradeep Kumar Srinivasan and James Hilton-Balfe.) + +.. _whatsnew311-pep675: + PEP 675: Arbitrary literal string type -------------------------------------- @@ -357,14 +375,17 @@ See :pep:`675` for more details. (Contributed by Jelle Zijlstra in :issue:`47088`. PEP written by Pradeep Kumar Srinivasan and Graham Bleaney.) + +.. _whatsnew311-pep681: + PEP 681: Data Class Transforms ------------------------------ :data:`~typing.dataclass_transform` may be used to decorate a class, metaclass, or a function that is itself a decorator. The presence of ``@dataclass_transform()`` tells a static type checker that the -decorated object performs runtime "magic" that -transforms a class, giving it :func:`dataclasses.dataclass`-like behaviors. +decorated object performs runtime "magic" that transforms a class, +giving it :func:`dataclass `-like behaviors. For example:: @@ -376,26 +397,32 @@ For example:: cls.__ne__ = ... return cls - # The create_model decorator can now be used to create new model - # classes, like this: + # The create_model decorator can now be used to create new model classes: @create_model class CustomerModel: id: int name: str - c = CustomerModel(id=327, name="John Smith") + c = CustomerModel(id=327, name="Eric Idle") See :pep:`681` for more details. (Contributed by Jelle Zijlstra in :gh:`91860`. PEP written by Erik De Bonte and Eric Traut.) -PEP 563 May Not Be the Future + +.. _whatsnew311-pep563-deferred: + +PEP 563 may not be the future ----------------------------- -* :pep:`563` Postponed Evaluation of Annotations, ``__future__.annotations`` - that was planned for this release has been indefinitely postponed. - See `this message `_ for more information. +:pep:`563` Postponed Evaluation of Annotations +(the ``from __future__ import annotations`` :ref:`future statement `) +that was originally planned for release in Python 3.10 +has been put on hold indefinitely. +See `this message from the Steering Council `__ +for more information. + Other Language Changes ====================== -- cgit v0.12 From 365f9b7b3581c13a705897502d72ae91adfa4e1e Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 19 Sep 2022 06:45:35 -0700 Subject: gh-95913: Fix and copyedit New Features section of 3.11 What's New (GH-95915) (cherry picked from commit 8ee27e33182e6d9040e79f6ccc9219afa049d40e) Co-authored-by: C.A.M. Gerlach --- Doc/c-api/code.rst | 4 +-- Doc/whatsnew/3.11.rst | 71 +++++++++++++++++++++++++++------------------------ 2 files changed, 39 insertions(+), 36 deletions(-) diff --git a/Doc/c-api/code.rst b/Doc/c-api/code.rst index d4a3c4a..9054e7e 100644 --- a/Doc/c-api/code.rst +++ b/Doc/c-api/code.rst @@ -1,9 +1,9 @@ .. highlight:: c -.. _codeobjects: - .. index:: object; code, code object +.. _codeobjects: + Code Objects ------------ diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 203c536..98eab50 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -50,6 +50,8 @@ This article explains the new features in Python 3.11, compared to 3.10. For full details, see the :ref:`changelog `. +.. _whatsnew311-summary: + Summary -- Release highlights ============================= @@ -96,16 +98,18 @@ Important deprecations, removals or restrictions: * :pep:`670`: Convert macros to functions in the Python C API. +.. _whatsnew311-features: + New Features ============ .. _whatsnew311-pep657: -Enhanced error locations in tracebacks --------------------------------------- +PEP 657: Enhanced error locations in tracebacks +----------------------------------------------- When printing tracebacks, the interpreter will now point to the exact expression -that caused the error instead of just the line. For example: +that caused the error, instead of just the line. For example: .. code-block:: python @@ -118,9 +122,9 @@ that caused the error instead of just the line. For example: ^^^^^^^^^ AttributeError: 'NoneType' object has no attribute 'x' -Previous versions of the interpreter would point to just the line making it +Previous versions of the interpreter would point to just the line, making it ambiguous which object was ``None``. These enhanced errors can also be helpful -when dealing with deeply nested dictionary objects and multiple function calls, +when dealing with deeply nested :class:`dict` objects and multiple function calls: .. code-block:: python @@ -138,7 +142,7 @@ when dealing with deeply nested dictionary objects and multiple function calls, ~~~~~~~~~~~~~~~~~~^^^^^ TypeError: 'NoneType' object is not subscriptable -as well as complex arithmetic expressions: +As well as complex arithmetic expressions: .. code-block:: python @@ -148,33 +152,28 @@ as well as complex arithmetic expressions: ~~~~~~^~~ ZeroDivisionError: division by zero -See :pep:`657` for more details. (Contributed by Pablo Galindo, Batuhan Taskaya -and Ammar Askar in :issue:`43950`.) - -.. note:: - This feature requires storing column positions in code objects which may - result in a small increase of disk usage of compiled Python files or - interpreter memory usage. To avoid storing the extra information and/or - deactivate printing the extra traceback information, the - :option:`-X` ``no_debug_ranges`` command line flag or the :envvar:`PYTHONNODEBUGRANGES` - environment variable can be used. - -Column information for code objects -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The information used by the enhanced traceback feature is made available as a -general API that can be used to correlate bytecode instructions with source -code. This information can be retrieved using: +Additionally, the information used by the enhanced traceback feature +is made available via a general API, that can be used to correlate +:term:`bytecode` :ref:`instructions ` with source code location. +This information can be retrieved using: - The :meth:`codeobject.co_positions` method in Python. -- The :c:func:`PyCode_Addr2Location` function in the C-API. - -The :option:`-X` ``no_debug_ranges`` option and the environment variable -:envvar:`PYTHONNODEBUGRANGES` can be used to disable this feature. +- The :c:func:`PyCode_Addr2Location` function in the C API. See :pep:`657` for more details. (Contributed by Pablo Galindo, Batuhan Taskaya and Ammar Askar in :issue:`43950`.) +.. note:: + This feature requires storing column positions in :ref:`codeobjects`, + which may result in a small increase in interpreter memory usage + and disk usage for compiled Python files. + To avoid storing the extra information + and deactivate printing the extra traceback information, + use the :option:`-X no_debug_ranges <-X>` command line option + or the :envvar:`PYTHONNODEBUGRANGES` environment variable. + + +.. _whatsnew311-pep654: PEP 654: Exception Groups and ``except*`` ----------------------------------------- @@ -192,16 +191,20 @@ See :pep:`654` for more details. Irit Katriel, Yury Selivanov and Guido van Rossum.) -.. _whatsnew311-pep678: +.. _whatsnew311-pep670: PEP 678: Exceptions can be enriched with notes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------------------------- + +The :meth:`~BaseException.add_note` method is added to :exc:`BaseException`. +It can be used to enrich exceptions with context information +that is not available at the time when the exception is raised. +The added notes appear in the default traceback. + +See :pep:`678` for more details. -The :meth:`add_note` method was added to :exc:`BaseException`. It can be -used to enrich exceptions with context information which is not available -at the time when the exception is raised. The notes added appear in the -default traceback. See :pep:`678` for more details. (Contributed by -Irit Katriel in :issue:`45607`.) +(Contributed by Irit Katriel in :issue:`45607`. +PEP written by Zac Hatfield-Dodds.) .. _whatsnew311-windows-launcher: -- cgit v0.12 From 1c345fa01264dae0270b0b93e9b36d7519ab9e59 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sun, 18 Sep 2022 15:53:31 -0700 Subject: GH-96851: Add link to FAQ entry for caching method calls. (GH-96902) (cherry picked from commit bbc24b2bd569108b957ed24c5a95ffeaf8cde0db) Co-authored-by: Raymond Hettinger --- Doc/faq/programming.rst | 2 ++ Doc/library/functools.rst | 3 +++ 2 files changed, 5 insertions(+) diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index 676dfae..76bd153 100644 --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -1897,6 +1897,8 @@ The classes can be used like this: 'blog-why-python-rocks' +.. _faq-cache-method-calls: + How do I cache method calls? ---------------------------- diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 00aca09..d6792ed 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -191,6 +191,9 @@ The :mod:`functools` module defines the following functions: The cache keeps references to the arguments and return values until they age out of the cache or until the cache is cleared. + If a method is cached, the `self` instance argument is included in the + cache. See :ref:`faq-cache-method-calls` + An `LRU (least recently used) cache `_ works best when the most recent calls are the best predictors of upcoming -- cgit v0.12 From 122a07c869952c188bd229b89df33b0248e355b8 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sat, 17 Sep 2022 20:11:29 -0700 Subject: Simplify sieve() recipe. Add edge case tests. (GH-96892) (cherry picked from commit 78359b1d45608439f8e03b8e86174fe7b04d3e08) Co-authored-by: Raymond Hettinger --- Doc/library/itertools.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst index 9de09ed..3c8e8db 100644 --- a/Doc/library/itertools.rst +++ b/Doc/library/itertools.rst @@ -820,14 +820,14 @@ which incur interpreter overhead. pass def sieve(n): - "Primes less than n" - # sieve(30) --> 2 3 5 7 11 13 17 19 23 29 - data = bytearray([1]) * n - data[:2] = 0, 0 - limit = math.isqrt(n) + 1 - for p in compress(range(limit), data): - data[p*p : n : p] = bytearray(len(range(p*p, n, p))) - return iter_index(data, 1) + "Primes less than n" + # sieve(30) --> 2 3 5 7 11 13 17 19 23 29 + data = bytearray([1]) * n + data[:2] = 0, 0 + limit = math.isqrt(n) + 1 + for p in compress(range(limit), data): + data[p+p : n : p] = bytearray(len(range(p+p, n, p))) + return compress(count(), data) def flatten(list_of_lists): "Flatten one level of nesting" @@ -1191,8 +1191,8 @@ which incur interpreter overhead. >>> list(sieve(30)) [2, 3, 5, 7, 11, 13, 17, 19, 23, 29] - >>> small_primes = [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73, 79, 83, 89, 97] - >>> all(list(sieve(n)) == [p for p in small_primes if p < n] for n in range(101)) + >>> small_primes = [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59] + >>> all(list(sieve(n)) == [p for p in small_primes if p < n] for n in range(60)) True >>> len(list(sieve(100))) 25 -- cgit v0.12 From a955cccf7ac78231ca3766f7ca0cfcbb5768a413 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sat, 17 Sep 2022 20:01:12 -0700 Subject: Clarify that the expression is regular math notation, not Python. (GH-96903) (GH-96908) --- Doc/library/math.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/math.rst b/Doc/library/math.rst index 6d9a992..8d48656 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -45,8 +45,8 @@ Number-theoretic and representation functions to zero when ``k > n``. Also called the binomial coefficient because it is equivalent - to the coefficient of k-th term in polynomial expansion of the - expression ``(1 + x) ** n``. + to the coefficient of k-th term in polynomial expansion of + ``(1 + x)ⁿ``. Raises :exc:`TypeError` if either of the arguments are not integers. Raises :exc:`ValueError` if either of the arguments are negative. -- cgit v0.12 From 746dad4eaba4937b18c0c457abf8a9933c8e261d Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 15 Sep 2022 14:21:08 -0700 Subject: gh-96810: Clarify for which statements sqlite3 implicitly opens transactions (GH-96832) (cherry picked from commit 16c33a9676e2f3ef330d09f2ab515c56636fa09f) Co-authored-by: Erlend E. Aasland --- Doc/library/sqlite3.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 110d262..99a413f 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -2239,7 +2239,8 @@ If the connection attribute :attr:`~Connection.isolation_level` is not ``None``, new transactions are implicitly opened before :meth:`~Cursor.execute` and :meth:`~Cursor.executemany` executes -``INSERT``, ``UPDATE``, ``DELETE``, or ``REPLACE`` statements. +``INSERT``, ``UPDATE``, ``DELETE``, or ``REPLACE`` statements; +for other statements, no implicit transaction handling is performed. Use the :meth:`~Connection.commit` and :meth:`~Connection.rollback` methods to respectively commit and roll back pending transactions. You can choose the underlying `SQLite transaction behaviour`_ — -- cgit v0.12 From 99f55684988e44abd15cb708137bfafac8eef499 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 14 Sep 2022 12:56:14 -0700 Subject: gh-96702: Order methods before attrs in sqlite3.Connection docs (GH-96703) (#96788) (cherry picked from commit 49cceeb5c998a51bb12b7dbde17b53647bb52113) Co-authored-by: Erlend E. Aasland Co-authored-by: Erlend E. Aasland --- Doc/library/sqlite3.rst | 193 ++++++++++++++++++++++++------------------------ 1 file changed, 96 insertions(+), 97 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 99a413f..8fdb753 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -557,103 +557,6 @@ Connection objects An SQLite database connection has the following attributes and methods: - .. attribute:: isolation_level - - This attribute controls the :ref:`transaction handling - ` performed by :mod:`!sqlite3`. - If set to ``None``, transactions are never implicitly opened. - If set to one of ``"DEFERRED"``, ``"IMMEDIATE"``, or ``"EXCLUSIVE"``, - corresponding to the underlying `SQLite transaction behaviour`_, - implicit :ref:`transaction management - ` is performed. - - If not overridden by the *isolation_level* parameter of :func:`connect`, - the default is ``""``, which is an alias for ``"DEFERRED"``. - - .. attribute:: in_transaction - - This read-only attribute corresponds to the low-level SQLite - `autocommit mode`_. - - ``True`` if a transaction is active (there are uncommitted changes), - ``False`` otherwise. - - .. versionadded:: 3.2 - - .. attribute:: row_factory - - A callable that accepts two arguments, - a :class:`Cursor` object and the raw row results as a :class:`tuple`, - and returns a custom object representing an SQLite row. - - Example: - - .. doctest:: - - >>> def dict_factory(cursor, row): - ... col_names = [col[0] for col in cursor.description] - ... return {key: value for key, value in zip(col_names, row)} - >>> con = sqlite3.connect(":memory:") - >>> con.row_factory = dict_factory - >>> for row in con.execute("SELECT 1 AS a, 2 AS b"): - ... print(row) - {'a': 1, 'b': 2} - - If returning a tuple doesn't suffice and you want name-based access to - columns, you should consider setting :attr:`row_factory` to the - highly optimized :class:`sqlite3.Row` type. :class:`Row` provides both - index-based and case-insensitive name-based access to columns with almost no - memory overhead. It will probably be better than your own custom - dictionary-based approach or even a db_row based solution. - - .. XXX what's a db_row-based solution? - - .. attribute:: text_factory - - A callable that accepts a :class:`bytes` parameter and returns a text - representation of it. - The callable is invoked for SQLite values with the ``TEXT`` data type. - By default, this attribute is set to :class:`str`. - If you want to return ``bytes`` instead, set *text_factory* to ``bytes``. - - Example: - - .. testcode:: - - con = sqlite3.connect(":memory:") - cur = con.cursor() - - AUSTRIA = "Österreich" - - # by default, rows are returned as str - cur.execute("SELECT ?", (AUSTRIA,)) - row = cur.fetchone() - assert row[0] == AUSTRIA - - # but we can make sqlite3 always return bytestrings ... - con.text_factory = bytes - cur.execute("SELECT ?", (AUSTRIA,)) - row = cur.fetchone() - assert type(row[0]) is bytes - # the bytestrings will be encoded in UTF-8, unless you stored garbage in the - # database ... - assert row[0] == AUSTRIA.encode("utf-8") - - # we can also implement a custom text_factory ... - # here we implement one that appends "foo" to all strings - con.text_factory = lambda x: x.decode("utf-8") + "foo" - cur.execute("SELECT ?", ("bar",)) - row = cur.fetchone() - assert row[0] == "barfoo" - - con.close() - - .. attribute:: total_changes - - Return the total number of database rows that have been modified, inserted, or - deleted since the database connection was opened. - - .. method:: cursor(factory=Cursor) Create and return a :class:`Cursor` object. @@ -1307,6 +1210,102 @@ Connection objects .. versionadded:: 3.11 + .. attribute:: in_transaction + + This read-only attribute corresponds to the low-level SQLite + `autocommit mode`_. + + ``True`` if a transaction is active (there are uncommitted changes), + ``False`` otherwise. + + .. versionadded:: 3.2 + + .. attribute:: isolation_level + + This attribute controls the :ref:`transaction handling + ` performed by :mod:`!sqlite3`. + If set to ``None``, transactions are never implicitly opened. + If set to one of ``"DEFERRED"``, ``"IMMEDIATE"``, or ``"EXCLUSIVE"``, + corresponding to the underlying `SQLite transaction behaviour`_, + implicit :ref:`transaction management + ` is performed. + + If not overridden by the *isolation_level* parameter of :func:`connect`, + the default is ``""``, which is an alias for ``"DEFERRED"``. + + .. attribute:: row_factory + + A callable that accepts two arguments, + a :class:`Cursor` object and the raw row results as a :class:`tuple`, + and returns a custom object representing an SQLite row. + + Example: + + .. doctest:: + + >>> def dict_factory(cursor, row): + ... col_names = [col[0] for col in cursor.description] + ... return {key: value for key, value in zip(col_names, row)} + >>> con = sqlite3.connect(":memory:") + >>> con.row_factory = dict_factory + >>> for row in con.execute("SELECT 1 AS a, 2 AS b"): + ... print(row) + {'a': 1, 'b': 2} + + If returning a tuple doesn't suffice and you want name-based access to + columns, you should consider setting :attr:`row_factory` to the + highly optimized :class:`sqlite3.Row` type. :class:`Row` provides both + index-based and case-insensitive name-based access to columns with almost no + memory overhead. It will probably be better than your own custom + dictionary-based approach or even a db_row based solution. + + .. XXX what's a db_row-based solution? + + .. attribute:: text_factory + + A callable that accepts a :class:`bytes` parameter and returns a text + representation of it. + The callable is invoked for SQLite values with the ``TEXT`` data type. + By default, this attribute is set to :class:`str`. + If you want to return ``bytes`` instead, set *text_factory* to ``bytes``. + + Example: + + .. testcode:: + + con = sqlite3.connect(":memory:") + cur = con.cursor() + + AUSTRIA = "Österreich" + + # by default, rows are returned as str + cur.execute("SELECT ?", (AUSTRIA,)) + row = cur.fetchone() + assert row[0] == AUSTRIA + + # but we can make sqlite3 always return bytestrings ... + con.text_factory = bytes + cur.execute("SELECT ?", (AUSTRIA,)) + row = cur.fetchone() + assert type(row[0]) is bytes + # the bytestrings will be encoded in UTF-8, unless you stored garbage in the + # database ... + assert row[0] == AUSTRIA.encode("utf-8") + + # we can also implement a custom text_factory ... + # here we implement one that appends "foo" to all strings + con.text_factory = lambda x: x.decode("utf-8") + "foo" + cur.execute("SELECT ?", ("bar",)) + row = cur.fetchone() + assert row[0] == "barfoo" + + con.close() + + .. attribute:: total_changes + + Return the total number of database rows that have been modified, inserted, or + deleted since the database connection was opened. + .. _sqlite3-cursor-objects: -- cgit v0.12 From 6cce942bd30e41924be0b5f199f8d84971ad67b2 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 13 Sep 2022 19:23:30 -0700 Subject: Itertools sieve() recipe (GH-96813) (GH-96814) --- Doc/library/itertools.rst | 38 ++++++-------------------------------- 1 file changed, 6 insertions(+), 32 deletions(-) diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst index 3c8e8db..16b1204 100644 --- a/Doc/library/itertools.rst +++ b/Doc/library/itertools.rst @@ -314,7 +314,7 @@ loops that truncate the stream. def count(start=0, step=1): # count(10) --> 10 11 12 13 14 ... - # count(2.5, 0.5) -> 2.5 3.0 3.5 ... + # count(2.5, 0.5) --> 2.5 3.0 3.5 ... n = start while True: yield n @@ -739,7 +739,7 @@ which incur interpreter overhead. def prepend(value, iterator): "Prepend a single value in front of an iterator" - # prepend(1, [2, 3, 4]) -> 1 2 3 4 + # prepend(1, [2, 3, 4]) --> 1 2 3 4 return chain([value], iterator) def tabulate(function, start=0): @@ -809,23 +809,13 @@ which incur interpreter overhead. for k in range(len(roots) + 1) ] - def iter_index(seq, value, start=0): - "Return indices where a value occurs in a sequence." - # iter_index('AABCADEAF', 'A') --> 0 1 4 7 - i = start - 1 - try: - while True: - yield (i := seq.index(value, i+1)) - except ValueError: - pass - def sieve(n): "Primes less than n" # sieve(30) --> 2 3 5 7 11 13 17 19 23 29 data = bytearray([1]) * n data[:2] = 0, 0 limit = math.isqrt(n) + 1 - for p in compress(range(limit), data): + for p in compress(count(), islice(data, limit)): data[p+p : n : p] = bytearray(len(range(p+p, n, p))) return compress(count(), data) @@ -866,12 +856,12 @@ which incur interpreter overhead. def triplewise(iterable): "Return overlapping triplets from an iterable" - # triplewise('ABCDEFG') -> ABC BCD CDE DEF EFG + # triplewise('ABCDEFG') --> ABC BCD CDE DEF EFG for (a, _), (b, c) in pairwise(pairwise(iterable)): yield a, b, c def sliding_window(iterable, n): - # sliding_window('ABCDEFG', 4) -> ABCD BCDE CDEF DEFG + # sliding_window('ABCDEFG', 4) --> ABCD BCDE CDEF DEFG it = iter(iterable) window = collections.deque(islice(it, n), maxlen=n) if len(window) == n: @@ -1103,6 +1093,7 @@ which incur interpreter overhead. >>> import operator >>> import collections >>> import math + >>> import random >>> take(10, count()) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] @@ -1152,7 +1143,6 @@ which incur interpreter overhead. >>> list(repeatfunc(pow, 5, 2, 3)) [8, 8, 8, 8, 8] - >>> import random >>> take(5, map(int, repeatfunc(random.random))) [0, 0, 0, 0, 0] @@ -1180,20 +1170,8 @@ which incur interpreter overhead. >>> all(factored(x) == expanded(x) for x in range(-10, 11)) True - >>> list(iter_index('AABCADEAF', 'A')) - [0, 1, 4, 7] - >>> list(iter_index('AABCADEAF', 'B')) - [2] - >>> list(iter_index('AABCADEAF', 'X')) - [] - >>> list(iter_index('', 'X')) - [] - >>> list(sieve(30)) [2, 3, 5, 7, 11, 13, 17, 19, 23, 29] - >>> small_primes = [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59] - >>> all(list(sieve(n)) == [p for p in small_primes if p < n] for n in range(60)) - True >>> len(list(sieve(100))) 25 >>> len(list(sieve(1_000))) @@ -1204,14 +1182,10 @@ which incur interpreter overhead. 9592 >>> len(list(sieve(1_000_000))) 78498 - >>> carmichael = {561, 1105, 1729, 2465, 2821, 6601, 8911} # https://oeis.org/A002997 - >>> set(sieve(10_000)).isdisjoint(carmichael) - True >>> list(flatten([('a', 'b'), (), ('c', 'd', 'e'), ('f',), ('g', 'h', 'i')])) ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i'] - >>> import random >>> random.seed(85753098575309) >>> list(repeatfunc(random.random, 3)) [0.16370491282496968, 0.45889608687313455, 0.3747076837820118] -- cgit v0.12 From 3e6f19b91608c52c7c58fea2a55ad305659e3376 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 13 Sep 2022 13:53:11 -0700 Subject: Add dataclass field default change to 3.11 what's new (GH-96790) Co-authored-by: Hugo van Kemenade (cherry picked from commit 4995f5f9a07921c5b90066a22285a538551b36d8) Co-authored-by: Laurie O --- Doc/whatsnew/3.11.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 98eab50..2747eaeb 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -610,6 +610,14 @@ Added non parallel-safe :func:`~contextlib.chdir` context manager to change the current working directory and then restore it on exit. Simple wrapper around :func:`~os.chdir`. (Contributed by Filipe Laíns in :issue:`25625`) +dataclasses +----------- + +* Change field default mutability check, allowing only defaults which are + :term:`hashable` instead of any object which is not an instance of + :class:`dict`, :class:`list` or :class:`set`. (Contributed by Eric V. Smith in + :issue:`44674`.) + datetime -------- -- cgit v0.12 From 040bbd2ec6d1675c718565824144d71caa88d383 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 13 Sep 2022 09:44:56 -0700 Subject: gh-95778: Fix `sys.set_int_max_str_digits()` parameter name (GH-96798) Discovered in https://github.com/python/typeshed/pull/8733 (cherry picked from commit bf5fd492524f1b630a60c98eff8fe5fa66603b54) Co-authored-by: Alex Waygood --- Doc/library/sys.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 4d6db2c..aab3f6a 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -1331,7 +1331,7 @@ always available. .. availability:: Unix. -.. function:: set_int_max_str_digits(n) +.. function:: set_int_max_str_digits(maxdigits) Set the :ref:`integer string conversion length limitation ` used by this interpreter. See also -- cgit v0.12 From 886fd3938bb911250ce114b6f6ea2a0edf917a1f Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 13 Sep 2022 08:57:02 -0700 Subject: gh-96706: [doc] Don't recomment deprecated use of get_event_loop() in examples (GH-96707) (cherry picked from commit 53a54b781d1f05f2d0b40ce88b3da92d5d23e9d2) Co-authored-by: zhanpon --- Doc/library/asyncio-eventloop.rst | 6 +++--- Doc/library/asyncio-llapi-index.rst | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 15f4f04..93bca96 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -1699,7 +1699,7 @@ event loop:: print('Hello World') loop.stop() - loop = asyncio.get_event_loop() + loop = asyncio.new_event_loop() # Schedule a call to hello_world() loop.call_soon(hello_world, loop) @@ -1735,7 +1735,7 @@ after 5 seconds, and then stops the event loop:: else: loop.stop() - loop = asyncio.get_event_loop() + loop = asyncio.new_event_loop() # Schedule the first call to display_date() end_time = loop.time() + 5.0 @@ -1767,7 +1767,7 @@ Wait until a file descriptor received some data using the # Create a pair of connected file descriptors rsock, wsock = socketpair() - loop = asyncio.get_event_loop() + loop = asyncio.new_event_loop() def reader(): data = rsock.recv(100) diff --git a/Doc/library/asyncio-llapi-index.rst b/Doc/library/asyncio-llapi-index.rst index c787cb9..b7ad888 100644 --- a/Doc/library/asyncio-llapi-index.rst +++ b/Doc/library/asyncio-llapi-index.rst @@ -267,7 +267,7 @@ See also the main documentation section about the .. rubric:: Examples -* :ref:`Using asyncio.get_event_loop() and loop.run_forever() +* :ref:`Using asyncio.new_event_loop() and loop.run_forever() `. * :ref:`Using loop.call_later() `. -- cgit v0.12 From 154b3cd751642b6f21a090ad548785bfa1cbc686 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 22 Sep 2022 10:17:53 -0700 Subject: GH-96975: Skip incomplete frames in PyEval_GetFrame (GH-97018) (cherry picked from commit 8fd2c3b75b90c4ee391894aa5094615bbdb6242f) Co-authored-by: Brandt Bucher --- Lib/test/test_embed.py | 3 + .../2022-09-21-16-06-37.gh-issue-96975.BmE0XY.rst | 2 + Programs/_testembed.c | 68 ++++++++++++++++++++++ Python/ceval.c | 9 ++- 4 files changed, 79 insertions(+), 3 deletions(-) create mode 100644 Misc/NEWS.d/next/Core and Builtins/2022-09-21-16-06-37.gh-issue-96975.BmE0XY.rst diff --git a/Lib/test/test_embed.py b/Lib/test/test_embed.py index 90022db..b8e3c37 100644 --- a/Lib/test/test_embed.py +++ b/Lib/test/test_embed.py @@ -1709,6 +1709,9 @@ class AuditingTests(EmbeddingTestsMixin, unittest.TestCase): timeout=support.SHORT_TIMEOUT, returncode=1) + def test_get_incomplete_frame(self): + self.run_embedded_interpreter("test_get_incomplete_frame") + class MiscTests(EmbeddingTestsMixin, unittest.TestCase): def test_unicode_id_init(self): diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-09-21-16-06-37.gh-issue-96975.BmE0XY.rst b/Misc/NEWS.d/next/Core and Builtins/2022-09-21-16-06-37.gh-issue-96975.BmE0XY.rst new file mode 100644 index 0000000..e6fcb84 --- /dev/null +++ b/Misc/NEWS.d/next/Core and Builtins/2022-09-21-16-06-37.gh-issue-96975.BmE0XY.rst @@ -0,0 +1,2 @@ +Fix a crash occurring when :c:func:`PyEval_GetFrame` is called while the +topmost Python frame is in a partially-initialized state. diff --git a/Programs/_testembed.c b/Programs/_testembed.c index f844456..d3d6588 100644 --- a/Programs/_testembed.c +++ b/Programs/_testembed.c @@ -1950,6 +1950,73 @@ static int test_repeated_init_and_inittab(void) return 0; } +static void wrap_allocator(PyMemAllocatorEx *allocator); +static void unwrap_allocator(PyMemAllocatorEx *allocator); + +static void * +malloc_wrapper(void *ctx, size_t size) +{ + PyMemAllocatorEx *allocator = (PyMemAllocatorEx *)ctx; + unwrap_allocator(allocator); + PyEval_GetFrame(); // BOOM! + wrap_allocator(allocator); + return allocator->malloc(allocator->ctx, size); +} + +static void * +calloc_wrapper(void *ctx, size_t nelem, size_t elsize) +{ + PyMemAllocatorEx *allocator = (PyMemAllocatorEx *)ctx; + return allocator->calloc(allocator->ctx, nelem, elsize); +} + +static void * +realloc_wrapper(void *ctx, void *ptr, size_t new_size) +{ + PyMemAllocatorEx *allocator = (PyMemAllocatorEx *)ctx; + return allocator->realloc(allocator->ctx, ptr, new_size); +} + +static void +free_wrapper(void *ctx, void *ptr) +{ + PyMemAllocatorEx *allocator = (PyMemAllocatorEx *)ctx; + allocator->free(allocator->ctx, ptr); +} + +static void +wrap_allocator(PyMemAllocatorEx *allocator) +{ + PyMem_GetAllocator(PYMEM_DOMAIN_OBJ, allocator); + PyMemAllocatorEx wrapper = { + .malloc = &malloc_wrapper, + .calloc = &calloc_wrapper, + .realloc = &realloc_wrapper, + .free = &free_wrapper, + .ctx = allocator, + }; + PyMem_SetAllocator(PYMEM_DOMAIN_OBJ, &wrapper); +} + +static void +unwrap_allocator(PyMemAllocatorEx *allocator) +{ + PyMem_SetAllocator(PYMEM_DOMAIN_OBJ, allocator); +} + +static int +test_get_incomplete_frame(void) +{ + _testembed_Py_Initialize(); + PyMemAllocatorEx allocator; + wrap_allocator(&allocator); + // Force an allocation with an incomplete (generator) frame: + int result = PyRun_SimpleString("(_ for _ in ())"); + unwrap_allocator(&allocator); + Py_Finalize(); + return result; +} + /* ********************************************************* * List of test cases and the function that implements it. @@ -2032,6 +2099,7 @@ static struct TestCase TestCases[] = { #ifndef MS_WINDOWS {"test_frozenmain", test_frozenmain}, #endif + {"test_get_incomplete_frame", test_get_incomplete_frame}, {NULL, NULL} }; diff --git a/Python/ceval.c b/Python/ceval.c index 66fa2ea..478ecd8 100644 --- a/Python/ceval.c +++ b/Python/ceval.c @@ -7115,11 +7115,14 @@ _PyEval_GetFrame(void) PyFrameObject * PyEval_GetFrame(void) { - PyThreadState *tstate = _PyThreadState_GET(); - if (tstate->cframe->current_frame == NULL) { + _PyInterpreterFrame *frame = _PyEval_GetFrame(); + while (frame && _PyFrame_IsIncomplete(frame)) { + frame = frame->previous; + } + if (frame == NULL) { return NULL; } - PyFrameObject *f = _PyFrame_GetFrameObject(tstate->cframe->current_frame); + PyFrameObject *f = _PyFrame_GetFrameObject(frame); if (f == NULL) { PyErr_Clear(); } -- cgit v0.12 From d0ab10f6f0163c397af4412175fe9ca0b2d96b4b Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 6 Oct 2022 17:36:39 -0700 Subject: [3.11] GH-97002: Prevent _PyInterpreterFrames from backing more than one PyFrameObject (GH-98002) (cherry picked from commit 21a2d9ff550977f2668e2cf1cc15793bf27fa109) --- Lib/test/test_frame.py | 65 ++++++++++++++++++++++ .../2022-10-06-02-11-34.gh-issue-97002.Zvsk71.rst | 3 + Python/frame.c | 29 ++++++++-- 3 files changed, 91 insertions(+), 6 deletions(-) create mode 100644 Misc/NEWS.d/next/Core and Builtins/2022-10-06-02-11-34.gh-issue-97002.Zvsk71.rst diff --git a/Lib/test/test_frame.py b/Lib/test/test_frame.py index 9fab176..e153bc5 100644 --- a/Lib/test/test_frame.py +++ b/Lib/test/test_frame.py @@ -1,3 +1,4 @@ +import gc import re import sys import types @@ -258,5 +259,69 @@ class TestIncompleteFrameAreInvisible(unittest.TestCase): gen() + @support.cpython_only + def test_sneaky_frame_object(self): + + def trace(frame, event, arg): + """ + Don't actually do anything, just force a frame object to be created. + """ + + def callback(phase, info): + """ + Yo dawg, I heard you like frames, so I'm allocating a frame while + you're allocating a frame, so you can have a frame while you have a + frame! + """ + nonlocal sneaky_frame_object + sneaky_frame_object = sys._getframe().f_back + # We're done here: + gc.callbacks.remove(callback) + + def f(): + while True: + yield + + old_threshold = gc.get_threshold() + old_callbacks = gc.callbacks[:] + old_enabled = gc.isenabled() + old_trace = sys.gettrace() + try: + # Stop the GC for a second while we set things up: + gc.disable() + # Create a paused generator: + g = f() + next(g) + # Move all objects to the oldest generation, and tell the GC to run + # on the *very next* allocation: + gc.collect() + gc.set_threshold(1, 0, 0) + # Okay, so here's the nightmare scenario: + # - We're tracing the resumption of a generator, which creates a new + # frame object. + # - The allocation of this frame object triggers a collection + # *before* the frame object is actually created. + # - During the collection, we request the exact same frame object. + # This test does it with a GC callback, but in real code it would + # likely be a trace function, weakref callback, or finalizer. + # - The collection finishes, and the original frame object is + # created. We now have two frame objects fighting over ownership + # of the same interpreter frame! + sys.settrace(trace) + gc.callbacks.append(callback) + sneaky_frame_object = None + gc.enable() + next(g) + # g.gi_frame should be the the frame object from the callback (the + # one that was *requested* second, but *created* first): + self.assertIs(g.gi_frame, sneaky_frame_object) + finally: + gc.set_threshold(*old_threshold) + gc.callbacks[:] = old_callbacks + sys.settrace(old_trace) + if old_enabled: + gc.enable() + + if __name__ == "__main__": unittest.main() diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-10-06-02-11-34.gh-issue-97002.Zvsk71.rst b/Misc/NEWS.d/next/Core and Builtins/2022-10-06-02-11-34.gh-issue-97002.Zvsk71.rst new file mode 100644 index 0000000..1f577e0 --- /dev/null +++ b/Misc/NEWS.d/next/Core and Builtins/2022-10-06-02-11-34.gh-issue-97002.Zvsk71.rst @@ -0,0 +1,3 @@ +Fix an issue where several frame objects could be backed by the same +interpreter frame, possibly leading to corrupted memory and hard crashes of +the interpreter. diff --git a/Python/frame.c b/Python/frame.c index c4e9349..ef88481 100644 --- a/Python/frame.c +++ b/Python/frame.c @@ -35,14 +35,31 @@ _PyFrame_MakeAndSetFrameObject(_PyInterpreterFrame *frame) Py_XDECREF(error_type); Py_XDECREF(error_value); Py_XDECREF(error_traceback); + return NULL; } - else { - assert(frame->owner != FRAME_OWNED_BY_FRAME_OBJECT); - assert(frame->owner != FRAME_CLEARED); - f->f_frame = frame; - frame->frame_obj = f; - PyErr_Restore(error_type, error_value, error_traceback); + PyErr_Restore(error_type, error_value, error_traceback); + if (frame->frame_obj) { + // GH-97002: How did we get into this horrible situation? Most likely, + // allocating f triggered a GC collection, which ran some code that + // *also* created the same frame... while we were in the middle of + // creating it! See test_sneaky_frame_object in test_frame.py for a + // concrete example. + // + // Regardless, just throw f away and use that frame instead, since it's + // already been exposed to user code. It's actually a bit tricky to do + // this, since we aren't backed by a real _PyInterpreterFrame anymore. + // Just pretend that we have an owned, cleared frame so frame_dealloc + // doesn't make the situation worse: + f->f_frame = (_PyInterpreterFrame *)f->_f_frame_data; + f->f_frame->owner = FRAME_CLEARED; + f->f_frame->frame_obj = f; + Py_DECREF(f); + return frame->frame_obj; } + assert(frame->owner != FRAME_OWNED_BY_FRAME_OBJECT); + assert(frame->owner != FRAME_CLEARED); + f->f_frame = frame; + frame->frame_obj = f; return f; } -- cgit v0.12 From 4c0c1e201a896ee5141df9a698e8a94aad2d5e6d Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 20 Oct 2022 16:55:37 -0700 Subject: [3.11] gh-97514: Don't use Linux abstract sockets for multiprocessing (GH-98501) (GH-98502) Linux abstract sockets are insecure as they lack any form of filesystem permissions so their use allows anyone on the system to inject code into the process. This removes the default preference for abstract sockets in multiprocessing introduced in Python 3.9+ via https://github.com/python/cpython/pull/18866 while fixing https://github.com/python/cpython/issues/84031. Explicit use of an abstract socket by a user now generates a RuntimeWarning. If we choose to keep this warning, it should be backported to the 3.7 and 3.8 branches. (cherry picked from commit 49f61068f49747164988ffc5a442d2a63874fc17) Co-authored-by: Gregory P. Smith Automerge-Triggered-By: GH:gpshead --- Lib/multiprocessing/connection.py | 5 ----- .../2022-09-07-10-42-00.gh-issue-97514.Yggdsl.rst | 15 +++++++++++++++ 2 files changed, 15 insertions(+), 5 deletions(-) create mode 100644 Misc/NEWS.d/next/Security/2022-09-07-10-42-00.gh-issue-97514.Yggdsl.rst diff --git a/Lib/multiprocessing/connection.py b/Lib/multiprocessing/connection.py index 65303d2..b08144f 100644 --- a/Lib/multiprocessing/connection.py +++ b/Lib/multiprocessing/connection.py @@ -73,11 +73,6 @@ def arbitrary_address(family): if family == 'AF_INET': return ('localhost', 0) elif family == 'AF_UNIX': - # Prefer abstract sockets if possible to avoid problems with the address - # size. When coding portable applications, some implementations have - # sun_path as short as 92 bytes in the sockaddr_un struct. - if util.abstract_sockets_supported: - return f"\0listener-{os.getpid()}-{next(_mmap_counter)}" return tempfile.mktemp(prefix='listener-', dir=util.get_temp_dir()) elif family == 'AF_PIPE': return tempfile.mktemp(prefix=r'\\.\pipe\pyc-%d-%d-' % diff --git a/Misc/NEWS.d/next/Security/2022-09-07-10-42-00.gh-issue-97514.Yggdsl.rst b/Misc/NEWS.d/next/Security/2022-09-07-10-42-00.gh-issue-97514.Yggdsl.rst new file mode 100644 index 0000000..02d95b5 --- /dev/null +++ b/Misc/NEWS.d/next/Security/2022-09-07-10-42-00.gh-issue-97514.Yggdsl.rst @@ -0,0 +1,15 @@ +On Linux the :mod:`multiprocessing` module returns to using filesystem backed +unix domain sockets for communication with the *forkserver* process instead of +the Linux abstract socket namespace. Only code that chooses to use the +:ref:`"forkserver" start method ` is affected. + +Abstract sockets have no permissions and could allow any user on the system in +the same `network namespace +`_ (often the +whole system) to inject code into the multiprocessing *forkserver* process. +This was a potential privilege escalation. Filesystem based socket permissions +restrict this to the *forkserver* process user as was the default in Python 3.8 +and earlier. + +This prevents Linux `CVE-2022-42919 +`_. -- cgit v0.12 From 4e0fda59f1f9f79e64b66f0320a46de93df310ba Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 20 Oct 2022 07:33:12 -0700 Subject: gh-98360: multiprocessing now spawns children on Windows with correct argv[0] in virtual environments (GH-98462) (cherry picked from commit e48f9b2b7e73f4a89a9b9c287f3b93dc13a60460) Co-authored-by: Steve Dower --- Lib/multiprocessing/popen_spawn_win32.py | 5 +-- Lib/test/_test_venv_multiprocessing.py | 40 ++++++++++++++++++++++ Lib/test/test_venv.py | 16 ++++++++- .../2022-10-19-20-00-28.gh-issue-98360.O2m6YG.rst | 4 +++ 4 files changed, 62 insertions(+), 3 deletions(-) create mode 100644 Lib/test/_test_venv_multiprocessing.py create mode 100644 Misc/NEWS.d/next/Windows/2022-10-19-20-00-28.gh-issue-98360.O2m6YG.rst diff --git a/Lib/multiprocessing/popen_spawn_win32.py b/Lib/multiprocessing/popen_spawn_win32.py index 9c4098d..4d60ffc 100644 --- a/Lib/multiprocessing/popen_spawn_win32.py +++ b/Lib/multiprocessing/popen_spawn_win32.py @@ -54,19 +54,20 @@ class Popen(object): wfd = msvcrt.open_osfhandle(whandle, 0) cmd = spawn.get_command_line(parent_pid=os.getpid(), pipe_handle=rhandle) - cmd = ' '.join('"%s"' % x for x in cmd) python_exe = spawn.get_executable() # bpo-35797: When running in a venv, we bypass the redirect # executor and launch our base Python. if WINENV and _path_eq(python_exe, sys.executable): - python_exe = sys._base_executable + cmd[0] = python_exe = sys._base_executable env = os.environ.copy() env["__PYVENV_LAUNCHER__"] = sys.executable else: env = None + cmd = ' '.join('"%s"' % x for x in cmd) + with open(wfd, 'wb', closefd=True) as to_child: # start process try: diff --git a/Lib/test/_test_venv_multiprocessing.py b/Lib/test/_test_venv_multiprocessing.py new file mode 100644 index 0000000..af72e91 --- /dev/null +++ b/Lib/test/_test_venv_multiprocessing.py @@ -0,0 +1,40 @@ +import multiprocessing +import random +import sys +import time + +def fill_queue(queue, code): + queue.put(code) + + +def drain_queue(queue, code): + if code != queue.get(): + sys.exit(1) + + +def test_func(): + code = random.randrange(0, 1000) + queue = multiprocessing.Queue() + fill_pool = multiprocessing.Process( + target=fill_queue, + args=(queue, code) + ) + drain_pool = multiprocessing.Process( + target=drain_queue, + args=(queue, code) + ) + drain_pool.start() + fill_pool.start() + fill_pool.join() + drain_pool.join() + + +def main(): + test_pool = multiprocessing.Process(target=test_func) + test_pool.start() + test_pool.join() + sys.exit(test_pool.exitcode) + + +if __name__ == "__main__": + main() diff --git a/Lib/test/test_venv.py b/Lib/test/test_venv.py index 74039f5..decf021 100644 --- a/Lib/test/test_venv.py +++ b/Lib/test/test_venv.py @@ -20,7 +20,7 @@ import tempfile from test.support import (captured_stdout, captured_stderr, requires_zlib, skip_if_broken_multiprocessing_synchronize, verbose, requires_subprocess, is_emscripten, is_wasi, - requires_venv_with_pip) + requires_venv_with_pip, TEST_HOME_DIR) from test.support.os_helper import (can_symlink, EnvironmentVarGuard, rmtree) import unittest import venv @@ -482,6 +482,20 @@ class BasicTest(BaseTest): 'pool.terminate()']) self.assertEqual(out.strip(), "python".encode()) + @requireVenvCreate + def test_multiprocessing_recursion(self): + """ + Test that the multiprocessing is able to spawn itself + """ + skip_if_broken_multiprocessing_synchronize() + + rmtree(self.env_dir) + self.run_with_capture(venv.create, self.env_dir) + envpy = os.path.join(os.path.realpath(self.env_dir), + self.bindir, self.exe) + script = os.path.join(TEST_HOME_DIR, '_test_venv_multiprocessing.py') + subprocess.check_call([envpy, script]) + @unittest.skipIf(os.name == 'nt', 'not relevant on Windows') def test_deactivate_with_strict_bash_opts(self): bash = shutil.which("bash") diff --git a/Misc/NEWS.d/next/Windows/2022-10-19-20-00-28.gh-issue-98360.O2m6YG.rst b/Misc/NEWS.d/next/Windows/2022-10-19-20-00-28.gh-issue-98360.O2m6YG.rst new file mode 100644 index 0000000..61c1e5e --- /dev/null +++ b/Misc/NEWS.d/next/Windows/2022-10-19-20-00-28.gh-issue-98360.O2m6YG.rst @@ -0,0 +1,4 @@ +Fixes :mod:`multiprocessing` spawning child processes on Windows from a +virtual environment to ensure that child processes that also use +:mod:`multiprocessing` to spawn more children will recognize that they are +in a virtual environment. -- cgit v0.12 From 585c95df95780c3a66db8b458713b172d7874b64 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 3 Oct 2022 21:03:26 -0700 Subject: [3.11] GH-97752: Clear the previous member of newly-created generator/coroutine frames (GH-97812) (cherry picked from commit 93fcc1f4133e177882850177c2c047d46019b812) --- Lib/test/test_generators.py | 19 +++++++++++++++++++ .../2022-10-03-13-35-48.gh-issue-97752.0xTjJY.rst | 2 ++ Python/frame.c | 3 +++ 3 files changed, 24 insertions(+) create mode 100644 Misc/NEWS.d/next/Core and Builtins/2022-10-03-13-35-48.gh-issue-97752.0xTjJY.rst diff --git a/Lib/test/test_generators.py b/Lib/test/test_generators.py index e5aa7da..353073d 100644 --- a/Lib/test/test_generators.py +++ b/Lib/test/test_generators.py @@ -206,6 +206,25 @@ class GeneratorTest(unittest.TestCase): finally: gc.set_threshold(*thresholds) + def test_ag_frame_f_back(self): + async def f(): + yield + ag = f() + self.assertIsNone(ag.ag_frame.f_back) + + def test_cr_frame_f_back(self): + async def f(): + pass + cr = f() + self.assertIsNone(cr.cr_frame.f_back) + cr.close() # Suppress RuntimeWarning. + + def test_gi_frame_f_back(self): + def f(): + yield + gi = f() + self.assertIsNone(gi.gi_frame.f_back) + class ExceptionTest(unittest.TestCase): diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-10-03-13-35-48.gh-issue-97752.0xTjJY.rst b/Misc/NEWS.d/next/Core and Builtins/2022-10-03-13-35-48.gh-issue-97752.0xTjJY.rst new file mode 100644 index 0000000..c656350 --- /dev/null +++ b/Misc/NEWS.d/next/Core and Builtins/2022-10-03-13-35-48.gh-issue-97752.0xTjJY.rst @@ -0,0 +1,2 @@ +Fix possible data corruption or crashes when accessing the ``f_back`` member +of newly-created generator or coroutine frames. diff --git a/Python/frame.c b/Python/frame.c index ef88481..9d5cab9 100644 --- a/Python/frame.c +++ b/Python/frame.c @@ -69,6 +69,9 @@ _PyFrame_Copy(_PyInterpreterFrame *src, _PyInterpreterFrame *dest) assert(src->stacktop >= src->f_code->co_nlocalsplus); Py_ssize_t size = ((char*)&src->localsplus[src->stacktop]) - (char *)src; memcpy(dest, src, size); + // Don't leave a dangling pointer to the old frame when creating generators + // and coroutines: + dest->previous = NULL; } -- cgit v0.12 From fc127628d581d8b64c602cd16573a84ff06f035d Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 19 Oct 2022 15:41:28 -0700 Subject: gh-98414: py.exe launcher does not use defaults for -V:company/ option (GH-98460) (cherry picked from commit 4bd63f66cd4f6e8d549f88ae0f4b0106d522b6bb) Co-authored-by: Steve Dower --- Lib/test/test_launcher.py | 7 +++++++ .../next/Windows/2022-10-19-19-35-37.gh-issue-98414.FbHZuS.rst | 3 +++ PC/launcher2.c | 1 + 3 files changed, 11 insertions(+) create mode 100644 Misc/NEWS.d/next/Windows/2022-10-19-19-35-37.gh-issue-98414.FbHZuS.rst diff --git a/Lib/test/test_launcher.py b/Lib/test/test_launcher.py index 97686e6..ba6856b 100644 --- a/Lib/test/test_launcher.py +++ b/Lib/test/test_launcher.py @@ -370,6 +370,13 @@ class TestLauncher(unittest.TestCase, RunPyMixin): self.assertEqual(company, data["env.company"]) self.assertEqual("3.100", data["env.tag"]) + def test_filter_to_company_with_default(self): + company = "PythonTestSuite" + data = self.run_py([f"-V:{company}/"], env=dict(PY_PYTHON="3.0")) + self.assertEqual("X.Y.exe", data["LaunchCommand"]) + self.assertEqual(company, data["env.company"]) + self.assertEqual("3.100", data["env.tag"]) + def test_filter_to_tag(self): company = "PythonTestSuite" data = self.run_py([f"-V:3.100"]) diff --git a/Misc/NEWS.d/next/Windows/2022-10-19-19-35-37.gh-issue-98414.FbHZuS.rst b/Misc/NEWS.d/next/Windows/2022-10-19-19-35-37.gh-issue-98414.FbHZuS.rst new file mode 100644 index 0000000..df07b7f --- /dev/null +++ b/Misc/NEWS.d/next/Windows/2022-10-19-19-35-37.gh-issue-98414.FbHZuS.rst @@ -0,0 +1,3 @@ +Fix :file:`py.exe` launcher handling of ``-V:/`` option when +default preferences have been set in environment variables or configuration +files. diff --git a/PC/launcher2.c b/PC/launcher2.c index 23eaa19..1f6f97b 100644 --- a/PC/launcher2.c +++ b/PC/launcher2.c @@ -653,6 +653,7 @@ parseCommandLine(SearchInfo *search) search->tag = argStart; } search->tagLength = (int)(tail - search->tag); + search->allowDefaults = false; search->restOfCmdLine = tail; } else if (MATCHES(L"0") || MATCHES(L"-list")) { search->list = true; -- cgit v0.12 From 715b67782eeace45f0250e2291488185ca21fbeb Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 17 Oct 2022 12:25:18 -0700 Subject: gh-95914: Add What's New item describing PEP 670 changes (GH-98315) (cherry picked from commit aafc53c0a6d1450dcfbc3f994318025ffb49ce73) Co-authored-by: C.A.M. Gerlach --- Doc/whatsnew/3.11.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 2747eaeb..8e99e94 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -1897,6 +1897,17 @@ New Features Porting to Python 3.11 ---------------------- +* Some macros have been converted to static inline functions to avoid + `macro pitfalls `_. + The change should be mostly transparent to users, + as the replacement functions will cast their arguments to the expected types + to avoid compiler warnings due to static type checks. + However, when the limited C API is set to >=3.11, + these casts are not done, + and callers will need to cast arguments to their expected types. + See :pep:`670` for more details. + (Contributed by Victor Stinner and Erlend E. Aasland in :gh:`89653`.) + * :c:func:`PyErr_SetExcInfo()` no longer uses the ``type`` and ``traceback`` arguments, the interpreter now derives those values from the exception instance (the ``value`` argument). The function still steals references -- cgit v0.12 From c95433573ac889f1e9f3a749200d314cc6bbb83a Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 18 Oct 2022 08:36:42 -0700 Subject: [3.11] gh-98331: Update bundled pip to 22.3 (GH-98332) (gh-98400) --- Lib/ensurepip/__init__.py | 4 ++-- Lib/ensurepip/_bundled/pip-22.2.2-py3-none-any.whl | Bin 2044706 -> 0 bytes Lib/ensurepip/_bundled/pip-22.3-py3-none-any.whl | Bin 0 -> 2051507 bytes .../_bundled/setuptools-63.2.0-py3-none-any.whl | Bin 1228000 -> 0 bytes .../_bundled/setuptools-65.5.0-py3-none-any.whl | Bin 0 -> 1232695 bytes .../2022-10-16-15-31-50.gh-issue-98331.Y5kPOX.rst | 1 + 6 files changed, 3 insertions(+), 2 deletions(-) delete mode 100644 Lib/ensurepip/_bundled/pip-22.2.2-py3-none-any.whl create mode 100644 Lib/ensurepip/_bundled/pip-22.3-py3-none-any.whl delete mode 100644 Lib/ensurepip/_bundled/setuptools-63.2.0-py3-none-any.whl create mode 100644 Lib/ensurepip/_bundled/setuptools-65.5.0-py3-none-any.whl create mode 100644 Misc/NEWS.d/next/Library/2022-10-16-15-31-50.gh-issue-98331.Y5kPOX.rst diff --git a/Lib/ensurepip/__init__.py b/Lib/ensurepip/__init__.py index 33c9180..4a6ba9c 100644 --- a/Lib/ensurepip/__init__.py +++ b/Lib/ensurepip/__init__.py @@ -10,8 +10,8 @@ from importlib import resources __all__ = ["version", "bootstrap"] _PACKAGE_NAMES = ('setuptools', 'pip') -_SETUPTOOLS_VERSION = "63.2.0" -_PIP_VERSION = "22.2.2" +_SETUPTOOLS_VERSION = "65.5.0" +_PIP_VERSION = "22.3" _PROJECTS = [ ("setuptools", _SETUPTOOLS_VERSION, "py3"), ("pip", _PIP_VERSION, "py3"), diff --git a/Lib/ensurepip/_bundled/pip-22.2.2-py3-none-any.whl b/Lib/ensurepip/_bundled/pip-22.2.2-py3-none-any.whl deleted file mode 100644 index 0309971..0000000 Binary files a/Lib/ensurepip/_bundled/pip-22.2.2-py3-none-any.whl and /dev/null differ diff --git a/Lib/ensurepip/_bundled/pip-22.3-py3-none-any.whl b/Lib/ensurepip/_bundled/pip-22.3-py3-none-any.whl new file mode 100644 index 0000000..d6fccd9 Binary files /dev/null and b/Lib/ensurepip/_bundled/pip-22.3-py3-none-any.whl differ diff --git a/Lib/ensurepip/_bundled/setuptools-63.2.0-py3-none-any.whl b/Lib/ensurepip/_bundled/setuptools-63.2.0-py3-none-any.whl deleted file mode 100644 index e3b5446..0000000 Binary files a/Lib/ensurepip/_bundled/setuptools-63.2.0-py3-none-any.whl and /dev/null differ diff --git a/Lib/ensurepip/_bundled/setuptools-65.5.0-py3-none-any.whl b/Lib/ensurepip/_bundled/setuptools-65.5.0-py3-none-any.whl new file mode 100644 index 0000000..123a13e Binary files /dev/null and b/Lib/ensurepip/_bundled/setuptools-65.5.0-py3-none-any.whl differ diff --git a/Misc/NEWS.d/next/Library/2022-10-16-15-31-50.gh-issue-98331.Y5kPOX.rst b/Misc/NEWS.d/next/Library/2022-10-16-15-31-50.gh-issue-98331.Y5kPOX.rst new file mode 100644 index 0000000..b4cf943 --- /dev/null +++ b/Misc/NEWS.d/next/Library/2022-10-16-15-31-50.gh-issue-98331.Y5kPOX.rst @@ -0,0 +1 @@ +Update the bundled copies of pip and setuptools to versions 22.3 and 65.5.0 respectively. -- cgit v0.12 From 92dc6aba83c66ebd12f666881bf8b2d57638c67e Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sat, 22 Oct 2022 12:18:57 -0700 Subject: [3.11] gh-95913: Edit & expand Optimizations in 3.11 WhatsNew (GH-98426) (#98554) gh-95913: Edit & expand Optimizations in 3.11 WhatsNew (GH-98426) (cherry picked from commit f58631be1148ee5436bb71d175d3993e3e6b4e1e) Co-authored-by: C.A.M. Gerlach Co-authored-by: C.A.M. Gerlach --- Doc/whatsnew/3.11.rst | 59 ++++++++++++++++++++++++++++++++++----------------- 1 file changed, 39 insertions(+), 20 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 8e99e94..95949f0 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -1089,33 +1089,52 @@ fcntl Optimizations ============= -* Compiler now optimizes simple C-style formatting with literal format - containing only format codes ``%s``, ``%r`` and ``%a`` and makes it as - fast as corresponding f-string expression. +This section covers specific optimizations independent of the +:ref:`whatsnew311-faster-cpython` project, which is covered in its own section. + +* The compiler now optimizes simple + :ref:`printf-style % formatting ` on string literals + containing only the format codes ``%s``, ``%r`` and ``%a`` and makes it as + fast as a corresponding :term:`f-string` expression. (Contributed by Serhiy Storchaka in :issue:`28307`.) -* "Zero-cost" exceptions are implemented. The cost of ``try`` statements is - almost eliminated when no exception is raised. - (Contributed by Mark Shannon in :issue:`40222`.) +* Integer division (``//``) is better tuned for optimization by compilers. + It is now around 20% faster on x86-64 when dividing an :class:`int` + by a value smaller than ``2**30``. + (Contributed by Gregory P. Smith and Tim Peters in :gh:`90564`.) -* Pure ASCII strings are now normalized in constant time by :func:`unicodedata.normalize`. - (Contributed by Dong-hee Na in :issue:`44987`.) +* :func:`sum` is now nearly 30% faster for integers smaller than ``2**30``. + (Contributed by Stefan Behnel in :gh:`68264`.) -* :mod:`math` functions :func:`~math.comb` and :func:`~math.perm` are now up - to 10 times or more faster for large arguments (the speed up is larger for - larger *k*). - (Contributed by Serhiy Storchaka in :issue:`37295`.) +* Resizing lists is streamlined for the common case, + speeding up :meth:`list.append` by ≈15% + and simple :term:`list comprehension`\s by up to 20-30% + (Contributed by Dennis Sweeney in :gh:`91165`.) -* Dict don't store hash value when all inserted keys are Unicode objects. - This reduces dict size. For example, ``sys.getsizeof(dict.fromkeys("abcdefg"))`` - becomes 272 bytes from 352 bytes on 64bit platform. +* Dictionaries don't store hash values when all keys are Unicode objects, + decreasing :class:`dict` size. + For example, ``sys.getsizeof(dict.fromkeys("abcdefg"))`` + is reduced from 352 bytes to 272 bytes (23% smaller) on 64-bit platforms. (Contributed by Inada Naoki in :issue:`46845`.) -* :mod:`re`'s regular expression matching engine has been partially refactored, - and now uses computed gotos (or "threaded code") on supported platforms. As a - result, Python 3.11 executes the `pyperformance regular expression benchmarks - `_ up to 10% - faster than Python 3.10. +* Using :class:`asyncio.DatagramProtocol` is now orders of magnitude faster + when transferring large files over UDP, + with speeds over 100 times higher for a ≈60 MiB file. + (Contributed by msoxzw in :gh:`91487`.) + +* :mod:`math` functions :func:`~math.comb` and :func:`~math.perm` are now + ≈10 times faster for large arguments (with a larger speedup for larger *k*). + (Contributed by Serhiy Storchaka in :issue:`37295`.) + +* The :mod:`statistics` functions :func:`~statistics.mean`, + :func:`~statistics.variance` and :func:`~statistics.stdev` now consume + iterators in one pass rather than converting them to a :class:`list` first. + This is twice as fast and can save substantial memory. + (Contributed by Raymond Hettinger in :gh:`90415`.) + +* :func:`unicodedata.normalize` + now normalizes pure-ASCII strings in constant time. + (Contributed by Dong-hee Na in :issue:`44987`.) Faster CPython -- cgit v0.12 From 25ebe354aafa0b56f2413ccd48cff8023b6d2e81 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 18 Oct 2022 16:20:19 -0700 Subject: gh-95914: Add links to 3.11 WhatsNew Summary items (GH-98416) Add links to Summary items to where readers can learn more (cherry picked from commit fcae1954a2ad009d23fc4170b40dcfb2d0e1a153) Co-authored-by: C.A.M. Gerlach --- Doc/whatsnew/3.11.rst | 64 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 38 insertions(+), 26 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 95949f0..2fbb2bd 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -58,44 +58,49 @@ Summary -- Release highlights .. This section singles out the most important changes in Python 3.11. Brevity is key. -- Python 3.11 is between 10-60% faster than Python 3.10. On average, we measured a - 1.25x speedup on the standard benchmark suite. See `Faster CPython`_ for details. +* Python 3.11 is between 10-60% faster than Python 3.10. + On average, we measured a 1.25x speedup on the standard benchmark suite. + See :ref:`whatsnew311-faster-cpython` for details. .. PEP-sized items next. New syntax features: -* :pep:`654`: Exception Groups and ``except*``. +* :ref:`whatsnew311-pep654` New built-in features: -* :pep:`678`: Enriching Exceptions with Notes. +* :ref:`whatsnew311-pep678` New standard library modules: -* :pep:`680`: ``tomllib`` — Support for Parsing TOML in the Standard Library. +* :pep:`680`: :mod:`tomllib` — + Support for parsing `TOML `_ in the Standard Library Interpreter improvements: -* :pep:`657`: Include Fine Grained Error Locations in Tracebacks. +* :ref:`whatsnew311-pep657` * New :option:`-P` command line option and :envvar:`PYTHONSAFEPATH` environment - variable to disable automatically prepending a potentially unsafe path - (the working dir or script directory, depending on invocation) - to :data:`sys.path`. + variable to :ref:`disable automatically prepending potentially unsafe paths + ` to :data:`sys.path` New typing features: -* :pep:`646`: Variadic generics. -* :pep:`655`: Marking individual TypedDict items as required or potentially missing. -* :pep:`673`: ``Self`` type. -* :pep:`675`: Arbitrary literal string type. -* :pep:`681`: Data Class Transforms. +* :ref:`whatsnew311-pep646` +* :ref:`whatsnew311-pep655` +* :ref:`whatsnew311-pep673` +* :ref:`whatsnew311-pep675` +* :ref:`whatsnew311-pep681` -Important deprecations, removals or restrictions: +Important deprecations, removals and restrictions: -* :pep:`594`: Removing dead batteries from the standard library. -* :pep:`624`: Remove ``Py_UNICODE`` encoder APIs. -* :pep:`670`: Convert macros to functions in the Python C API. +* :pep:`594`: + :ref:`Many legacy standard library modules have been deprecated + ` and will be removed in Python 3.13 +* :pep:`624`: + :ref:`Py_UNICODE encoder APIs have been removed ` +* :pep:`670`: + :ref:`Macros converted to static inline functions ` .. _whatsnew311-features: @@ -105,8 +110,8 @@ New Features .. _whatsnew311-pep657: -PEP 657: Enhanced error locations in tracebacks ------------------------------------------------ +PEP 657: Fine-grained error locations in tracebacks +--------------------------------------------------- When printing tracebacks, the interpreter will now point to the exact expression that caused the error, instead of just the line. For example: @@ -381,7 +386,7 @@ Kumar Srinivasan and Graham Bleaney.) .. _whatsnew311-pep681: -PEP 681: Data Class Transforms +PEP 681: Data class transforms ------------------------------ :data:`~typing.dataclass_transform` may be used to @@ -455,6 +460,8 @@ Other Language Changes pickles instance attributes implemented as :term:`slots <__slots__>`. (Contributed by Serhiy Storchaka in :issue:`26579`.) +.. _whatsnew311-pythonsafepath: + * Added a :option:`-P` command line option and a :envvar:`PYTHONSAFEPATH` environment variable, which disable the automatic prepending to :data:`sys.path` @@ -1497,11 +1504,7 @@ Deprecated removed in Python 3.13. Use ``locale.setlocale(locale.LC_ALL, "")`` instead. (Contributed by Victor Stinner in :gh:`90817`.) -* The :mod:`asynchat`, :mod:`asyncore` and :mod:`smtpd` modules have been - deprecated since at least Python 3.6. Their documentation and deprecation - warnings have now been updated to note they will removed in Python 3.12 - (:pep:`594`). - (Contributed by Hugo van Kemenade in :issue:`47022`.) +.. _whatsnew311-pep594: * :pep:`594` led to the deprecations of the following modules which are slated for removal in Python 3.13: @@ -1529,6 +1532,11 @@ Deprecated (Contributed by Brett Cannon in :issue:`47061` and Victor Stinner in :gh:`68966`.) +* The :mod:`asynchat`, :mod:`asyncore` and :mod:`smtpd` modules have been + deprecated since at least Python 3.6. Their documentation and deprecation + warnings have now been updated to note they will removed in Python 3.12. + (Contributed by Hugo van Kemenade in :issue:`47022`.) + * More strict rules will be applied now applied for numerical group references and group names in regular expressions in future Python versions. Only sequence of ASCII digits will be now accepted as a numerical reference. @@ -1916,6 +1924,8 @@ New Features Porting to Python 3.11 ---------------------- +.. _whatsnew311-pep670: + * Some macros have been converted to static inline functions to avoid `macro pitfalls `_. The change should be mostly transparent to users, @@ -2292,6 +2302,8 @@ Removed API). (Contributed by Victor Stinner in :issue:`45412`.) +.. _whatsnew311-pep624: + * Remove the :c:type:`Py_UNICODE` encoder APIs, as they have been deprecated since Python 3.3, are little used -- cgit v0.12 From 98eef50f0d83de5234fb6c432c67f5f3716114d4 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Tue, 18 Oct 2022 03:41:57 -0500 Subject: gh-95913: Prepare remaining Whatsnew sections for editing (#98342) * Add line breaks & ref targets to Whatsnew to prepare for future changes * Use standard heading underbar symbols for H4 sections * Flatten Porting subsection; clarify scope of/link Python->CAPI sections * Move C API pending deprecations to C API section, to match the others --- Doc/whatsnew/3.11.rst | 133 +++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 105 insertions(+), 28 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 2fbb2bd..fe2a3bd 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -561,6 +561,8 @@ New Modules (Contributed by Sebastian Rittau in :issue:`42012`.) +.. _whatsnew311-improved-modules: + Improved Modules ================ @@ -1093,6 +1095,8 @@ fcntl the ``FD_CLOEXEC`` flag in addition. +.. _whatsnew311-optimizations: + Optimizations ============= @@ -1144,6 +1148,8 @@ This section covers specific optimizations independent of the (Contributed by Dong-hee Na in :issue:`44987`.) +.. _whatsnew311-faster-cpython: + Faster CPython ============== @@ -1156,11 +1162,16 @@ could be up to 10-60% faster. This project focuses on two major areas in Python: faster startup and faster runtime. Other optimizations not under this project are listed in `Optimizations`_. + +.. _whatsnew311-faster-startup: + Faster Startup -------------- +.. _whatsnew311-faster-imports: + Frozen imports / Static code objects -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Python caches bytecode in the :ref:`__pycache__` directory to speed up module loading. @@ -1185,11 +1196,16 @@ impact for short-running programs using Python. (Contributed by Eric Snow, Guido van Rossum and Kumar Aditya in numerous issues.) +.. _whatsnew311-faster-runtime: + Faster Runtime -------------- +.. _whatsnew311-lazy-python-frames: + Cheaper, lazy Python frames -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Python frames are created whenever Python calls a Python function. This frame holds execution information. The following are new frame optimizations: @@ -1206,10 +1222,13 @@ up significantly. We measured a 3-7% speedup in pyperformance. (Contributed by Mark Shannon in :issue:`44590`.) + .. _inline-calls: +.. _whatsnew311-inline-calls: Inlined Python function calls -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + During a Python function call, Python will call an evaluating C function to interpret that function's code. This effectively limits pure Python recursion to what's safe for the C stack. @@ -1226,8 +1245,12 @@ We measured a 1-3% improvement in pyperformance. (Contributed by Pablo Galindo and Mark Shannon in :issue:`45256`.) + +.. _whatsnew311-pep659: + PEP 659: Specializing Adaptive Interpreter -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + :pep:`659` is one of the key parts of the faster CPython project. The general idea is that while Python is a dynamic language, most code has regions where objects and types rarely change. This concept is known as *type stability*. @@ -1309,6 +1332,8 @@ Bucher, with additional help from Irit Katriel and Dennis Sweeney.) be sped up by :issue:`45947`. +.. _whatsnew311-faster-cpython-misc: + Misc ---- @@ -1320,6 +1345,9 @@ Misc time required for catching an exception by about 10%. (Contributed by Irit Katriel in :issue:`45711`.) + +.. _whatsnew311-faster-cpython-faq: + FAQ --- @@ -1354,6 +1382,8 @@ FAQ | A: No. We're still exploring other optimizations. +.. _whatsnew311-faster-cpython-about: + About ----- @@ -1363,6 +1393,8 @@ funded by Bloomberg LP to work on the project part-time. Finally, many contributors are volunteers from the community. +.. _whatsnew311-bytecode-changes: + CPython bytecode changes ======================== @@ -1419,9 +1451,17 @@ CPython bytecode changes * :opcode:`RESUME` has been added. It is a no-op. Performs internal tracing, debugging and optimization checks. + +.. _whatsnew311-deprecated: +.. _whatsnew311-python-api-deprecated: + Deprecated ========== +This section lists Python APIs that have been deprecated in Python 3.11. + +Deprecated C APIs are :ref:`listed separately `. + * Chaining :class:`classmethod` descriptors (introduced in :issue:`19072`) is now deprecated. It can no longer be used to wrap other descriptors such as :class:`property`. The core design of this feature was flawed @@ -1561,13 +1601,17 @@ Deprecated (Contributed by Serhiy Storchaka and Miro Hrončok in :gh:`92728`.) +.. _whatsnew311-pending-removal: +.. _whatsnew311-python-api-pending-removal: + Pending Removal in Python 3.12 ============================== -The following APIs have been deprecated in earlier Python releases, +The following Python APIs have been deprecated in earlier Python releases, and will be removed in Python 3.12. -Python API: +C APIs pending removal are +:ref:`listed separately `. * :class:`pkgutil.ImpImporter` * :class:`pkgutil.ImpLoader` @@ -1596,29 +1640,17 @@ Python API: * :func:`sqlite3.OptimizedUnicode` * :func:`sqlite3.enable_shared_cache` -C API: - -* :c:func:`PyUnicode_AS_DATA` -* :c:func:`PyUnicode_AS_UNICODE` -* :c:func:`PyUnicode_AsUnicodeAndSize` -* :c:func:`PyUnicode_AsUnicode` -* :c:func:`PyUnicode_FromUnicode` -* :c:func:`PyUnicode_GET_DATA_SIZE` -* :c:func:`PyUnicode_GET_SIZE` -* :c:func:`PyUnicode_GetSize` -* :c:func:`PyUnicode_IS_COMPACT` -* :c:func:`PyUnicode_IS_READY` -* :c:func:`PyUnicode_READY` -* :c:func:`Py_UNICODE_WSTR_LENGTH` -* :c:func:`_PyUnicode_AsUnicode` -* :c:macro:`PyUnicode_WCHAR_KIND` -* :c:type:`PyUnicodeObject` -* :c:func:`PyUnicode_InternImmortal()` +.. _whatsnew311-removed: +.. _whatsnew311-python-api-removed: Removed ======= +This section lists Python APIs that have been removed in Python 3.12. + +Removed C APIs are :ref:`listed separately `. + * :class:`smtpd.MailmanProxy` is now removed as it is unusable without an external module, ``mailman``. (Contributed by Dong-hee Na in :issue:`35800`.) @@ -1711,15 +1743,18 @@ Removed of ``Tools/scripts`` and is `being developed independently `_ from the Python source tree. + +.. _whatsnew311-porting: +.. _whatsnew311-python-api-porting: + Porting to Python 3.11 ====================== This section lists previously described changes and other bugfixes -that may require changes to your code. +in the Python API that may require changes to your Python code. - -Changes in the Python API -------------------------- +Porting notes for the C API are +:ref:`listed separately `. * Prohibited passing non-:class:`concurrent.futures.ThreadPoolExecutor` executors to :meth:`loop.set_default_executor` following a deprecation in @@ -1768,6 +1803,9 @@ Changes in the Python API as meaningless when read. To get the pointer to the object's dictionary call :c:func:`PyObject_GenericGetDict` instead. + +.. _whatsnew311-build-changes: + Build Changes ============= @@ -1855,9 +1893,13 @@ Build Changes (Contributed by Serhiy Storchaka in :issue:`46996`.) +.. _whatsnew311-c-api: + C API Changes ============= +.. _whatsnew311-c-api-new-features: + New Features ------------ @@ -1921,6 +1963,9 @@ New Features * Added the :c:member:`PyConfig.safe_path` member. (Contributed by Victor Stinner in :gh:`57684`.) + +.. _whatsnew311-c-api-porting: + Porting to Python 3.11 ---------------------- @@ -2220,6 +2265,9 @@ Porting to Python 3.11 paths and then modify them, finish initialization and use :c:func:`PySys_GetObject` to retrieve :data:`sys.path` as a Python list object and modify it directly. + +.. _whatsnew311-c-api-deprecated: + Deprecated ---------- @@ -2245,6 +2293,35 @@ Deprecated * Deprecate the ``ob_shash`` member of the :c:type:`PyBytesObject`. Use :c:func:`PyObject_Hash` instead. (Contributed by Inada Naoki in :issue:`46864`.) + +.. _whatsnew311-c-api-pending-removal: + +Pending Removal in Python 3.12 +------------------------------ + +The following C APIs have been deprecated in earlier Python releases, +and will be removed in Python 3.12. + +* :c:func:`PyUnicode_AS_DATA` +* :c:func:`PyUnicode_AS_UNICODE` +* :c:func:`PyUnicode_AsUnicodeAndSize` +* :c:func:`PyUnicode_AsUnicode` +* :c:func:`PyUnicode_FromUnicode` +* :c:func:`PyUnicode_GET_DATA_SIZE` +* :c:func:`PyUnicode_GET_SIZE` +* :c:func:`PyUnicode_GetSize` +* :c:func:`PyUnicode_IS_COMPACT` +* :c:func:`PyUnicode_IS_READY` +* :c:func:`PyUnicode_READY` +* :c:func:`Py_UNICODE_WSTR_LENGTH` +* :c:func:`_PyUnicode_AsUnicode` +* :c:macro:`PyUnicode_WCHAR_KIND` +* :c:type:`PyUnicodeObject` +* :c:func:`PyUnicode_InternImmortal()` + + +.. _whatsnew311-c-api-removed: + Removed ------- -- cgit v0.12 From a1e59b76a7eaaa49af4b9c9f7cf07adbc77030d7 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 19 Sep 2022 06:51:08 -0700 Subject: gh-95913: Copyedit, link & format Typing Features section in 3.11 What's New (GH-96097) Co-authored-by: Ezio Melotti Co-authored-by: Alex Waygood (cherry picked from commit 558768ff22e47582ae95ad7c3f8955407934916e) Co-authored-by: C.A.M. Gerlach --- Doc/whatsnew/3.11.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index fe2a3bd..b8c1b3a 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -383,10 +383,9 @@ See :pep:`675` for more details. (Contributed by Jelle Zijlstra in :issue:`47088`. PEP written by Pradeep Kumar Srinivasan and Graham Bleaney.) - .. _whatsnew311-pep681: -PEP 681: Data class transforms +PEP 681: Data Class Transforms ------------------------------ :data:`~typing.dataclass_transform` may be used to -- cgit v0.12 From f8f0386bb768c6b71373bb423e9c6234eb78da58 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sat, 22 Oct 2022 12:21:01 -0700 Subject: gh-95913: Copyedit & xref FrameInfo in Whatsnew inspect section (GH-98304) (cherry picked from commit 8f30267ab49e1ef3ac3165a102b2196336547c8a) Co-authored-by: C.A.M. Gerlach --- Doc/library/inspect.rst | 22 +++++++++++++++------- Doc/whatsnew/3.11.rst | 29 ++++++++++++++++++++--------- 2 files changed, 35 insertions(+), 16 deletions(-) diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 700cd91..44f1ae0 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -434,8 +434,10 @@ attributes: Return ``True`` if the type of object is a :class:`~types.MethodWrapperType`. - These are instances of :class:`~types.MethodWrapperType`, such as :meth:`~object().__str__`, - :meth:`~object().__eq__` and :meth:`~object().__repr__` + These are instances of :class:`~types.MethodWrapperType`, such as :meth:`~object.__str__`, + :meth:`~object.__eq__` and :meth:`~object.__repr__`. + + .. versionadded:: 3.11 .. function:: isroutine(object) @@ -1206,12 +1208,13 @@ is considered deprecated and may be removed in the future. number, start column offset, and end column offset associated with the instruction being executed by the frame this record corresponds to. -.. versionchanged:: 3.5 - Return a named tuple instead of a tuple. + .. versionchanged:: 3.5 + Return a :term:`named tuple` instead of a :class:`tuple`. + + .. versionchanged:: 3.11 + :class:`!FrameInfo` is now a class instance + (that is backwards compatible with the previous :term:`named tuple`). -.. versionchanged:: 3.11 - Changed the return object from a named tuple to a regular object (that is - backwards compatible with the previous named tuple). .. class:: Traceback @@ -1245,6 +1248,11 @@ is considered deprecated and may be removed in the future. the instruction being executed by the frame this traceback corresponds to. + .. versionchanged:: 3.11 + :class:`!Traceback` is now a class instance + (that is backwards compatible with the previous :term:`named tuple`). + + .. note:: Keeping references to frame objects, as found in the first element of the frame diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index b8c1b3a..b5ca28e 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -746,22 +746,33 @@ IDLE and idlelib * Include prompts when saving Shell with inputs and outputs. (Contributed by Terry Jan Reedy in :gh:`95191`.) + +.. _whatsnew311-inspect: + inspect ------- -* Add :func:`inspect.getmembers_static`: return all members without + +* Add :func:`~inspect.getmembers_static` to return all members without triggering dynamic lookup via the descriptor protocol. (Contributed by Weipeng Hong in :issue:`30533`.) -* Add :func:`inspect.ismethodwrapper` for checking if the type of an object is a - :class:`~types.MethodWrapperType`. (Contributed by Hakan Çelik in :issue:`29418`.) +* Add :func:`~inspect.ismethodwrapper` + for checking if the type of an object is a :class:`~types.MethodWrapperType`. + (Contributed by Hakan Çelik in :issue:`29418`.) -* Change the frame-related functions in the :mod:`inspect` module to return a - regular object (that is backwards compatible with the old tuple-like - interface) that include the extended :pep:`657` position information (end +* Change the frame-related functions in the :mod:`inspect` module to return new + :class:`~inspect.FrameInfo` and :class:`~inspect.Traceback` class instances + (backwards compatible with the previous :term:`named tuple`-like interfaces) + that includes the extended :pep:`657` position information (end line number, column and end column). The affected functions are: - :func:`inspect.getframeinfo`, :func:`inspect.getouterframes`, :func:`inspect.getinnerframes`, - :func:`inspect.stack` and :func:`inspect.trace`. (Contributed by Pablo Galindo in - :gh:`88116`.) + + * :func:`inspect.getframeinfo` + * :func:`inspect.getouterframes` + * :func:`inspect.getinnerframes`, + * :func:`inspect.stack` + * :func:`inspect.trace` + + (Contributed by Pablo Galindo in :gh:`88116`.) locale ------ -- cgit v0.12 From f1ca2f6a41ea032d411777a17a42308ce33e6309 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Mon, 17 Oct 2022 18:49:38 -0500 Subject: [3.11] Docs: Fix backtick errors found by sphinx-lint (GH-97998) (#98371) Co-authored-by: Ezio Melotti . (cherry picked from commit fa2d43e5184f5eaf3391844ec2400342a1b2ead4) Co-authored-by: Hugo van Kemenade Co-authored-by: Hugo van Kemenade --- Doc/c-api/init.rst | 2 +- Doc/c-api/type.rst | 2 +- Doc/faq/design.rst | 2 +- Doc/howto/enum.rst | 2 +- Doc/howto/logging-cookbook.rst | 4 ++-- Doc/howto/logging.rst | 10 +++++----- Doc/install/index.rst | 2 +- Doc/library/asyncio-protocol.rst | 2 +- Doc/library/asyncio-task.rst | 10 +++++----- Doc/library/bdb.rst | 2 +- Doc/library/bz2.rst | 4 ++-- Doc/library/concurrent.futures.rst | 6 +++--- Doc/library/ctypes.rst | 2 +- Doc/library/curses.rst | 2 +- Doc/library/datetime.rst | 4 ++-- Doc/library/decimal.rst | 8 ++++---- Doc/library/dis.rst | 2 +- Doc/library/email.compat32-message.rst | 2 +- Doc/library/email.headerregistry.rst | 2 +- Doc/library/functools.rst | 4 ++-- Doc/library/hashlib.rst | 2 +- Doc/library/io.rst | 6 +++--- Doc/library/lzma.rst | 2 +- Doc/library/os.rst | 4 ++-- Doc/library/select.rst | 2 +- Doc/library/socket.rst | 2 +- Doc/library/statistics.rst | 2 +- Doc/library/sys.rst | 6 +++--- Doc/library/unittest.mock-examples.rst | 2 +- Doc/library/xml.dom.minidom.rst | 4 ++-- Doc/library/xmlrpc.client.rst | 2 +- Doc/library/xmlrpc.server.rst | 2 +- Doc/reference/expressions.rst | 2 +- Doc/reference/import.rst | 2 +- Doc/reference/simple_stmts.rst | 8 -------- Doc/requirements.txt | 2 +- Doc/using/configure.rst | 14 +++++++------- Doc/using/unix.rst | 2 +- Doc/using/windows.rst | 2 +- Doc/whatsnew/2.6.rst | 6 +++--- Doc/whatsnew/2.7.rst | 4 ++-- Doc/whatsnew/3.10.rst | 2 +- Doc/whatsnew/3.11.rst | 2 +- Doc/whatsnew/3.2.rst | 4 ++-- Doc/whatsnew/3.3.rst | 4 ++-- Doc/whatsnew/3.5.rst | 4 ++-- Doc/whatsnew/3.6.rst | 6 +++--- Doc/whatsnew/3.7.rst | 2 +- Doc/whatsnew/3.9.rst | 2 +- 49 files changed, 85 insertions(+), 93 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 4c0731e..aecc3b8 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1796,7 +1796,7 @@ is not possible due to its implementation being opaque at build time. Free the given *key* allocated by :c:func:`PyThread_tss_alloc`, after first calling :c:func:`PyThread_tss_delete` to ensure any associated thread locals have been unassigned. This is a no-op if the *key* - argument is `NULL`. + argument is ``NULL``. .. note:: A freed key becomes a dangling pointer. You should reset the key to diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst index d740e4e..ac35204 100644 --- a/Doc/c-api/type.rst +++ b/Doc/c-api/type.rst @@ -40,7 +40,7 @@ Type Objects .. c:function:: unsigned long PyType_GetFlags(PyTypeObject* type) Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This function is primarily - meant for use with `Py_LIMITED_API`; the individual flag bits are + meant for use with ``Py_LIMITED_API``; the individual flag bits are guaranteed to be stable across Python releases, but access to :c:member:`~PyTypeObject.tp_flags` itself is not part of the limited API. diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst index 9da1d01..9dbfacd 100644 --- a/Doc/faq/design.rst +++ b/Doc/faq/design.rst @@ -155,7 +155,7 @@ Why can't I use an assignment in an expression? Starting in Python 3.8, you can! -Assignment expressions using the walrus operator `:=` assign a variable in an +Assignment expressions using the walrus operator ``:=`` assign a variable in an expression:: while chunk := fp.read(200): diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst index 7b1cf75..bad5e50 100644 --- a/Doc/howto/enum.rst +++ b/Doc/howto/enum.rst @@ -1120,7 +1120,7 @@ Enum Classes The :class:`EnumType` metaclass is responsible for providing the :meth:`__contains__`, :meth:`__dir__`, :meth:`__iter__` and other methods that allow one to do things with an :class:`Enum` class that fail on a typical -class, such as `list(Color)` or `some_enum_var in Color`. :class:`EnumType` is +class, such as ``list(Color)`` or ``some_enum_var in Color``. :class:`EnumType` is responsible for ensuring that various other methods on the final :class:`Enum` class are correct (such as :meth:`__new__`, :meth:`__getnewargs__`, :meth:`__str__` and :meth:`__repr__`). diff --git a/Doc/howto/logging-cookbook.rst b/Doc/howto/logging-cookbook.rst index b49b00d..c510718 100644 --- a/Doc/howto/logging-cookbook.rst +++ b/Doc/howto/logging-cookbook.rst @@ -769,7 +769,7 @@ To run a logging listener in production, you may need to use a process-managemen such as `Supervisor `_. `Here `_ is a Gist which provides the bare-bones files to run the above functionality using Supervisor: you -will need to change the `/path/to/` parts in the Gist to reflect the actual paths you +will need to change the ``/path/to/`` parts in the Gist to reflect the actual paths you want to use. @@ -2981,7 +2981,7 @@ Formatting times using UTC (GMT) via configuration -------------------------------------------------- Sometimes you want to format times using UTC, which can be done using a class -such as `UTCFormatter`, shown below:: +such as ``UTCFormatter``, shown below:: import logging import time diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst index f98876a..8706527 100644 --- a/Doc/howto/logging.rst +++ b/Doc/howto/logging.rst @@ -552,14 +552,14 @@ raw message. If there is no date format string, the default date format is: %Y-%m-%d %H:%M:%S -with the milliseconds tacked on at the end. The ``style`` is one of `%`, '{' -or '$'. If one of these is not specified, then '%' will be used. +with the milliseconds tacked on at the end. The ``style`` is one of ``'%'``, +``'{'``, or ``'$'``. If one of these is not specified, then ``'%'`` will be used. -If the ``style`` is '%', the message format string uses +If the ``style`` is ``'%'``, the message format string uses ``%()s`` styled string substitution; the possible keys are -documented in :ref:`logrecord-attributes`. If the style is '{', the message +documented in :ref:`logrecord-attributes`. If the style is ``'{'``, the message format string is assumed to be compatible with :meth:`str.format` (using -keyword arguments), while if the style is '$' then the message format string +keyword arguments), while if the style is ``'$'`` then the message format string should conform to what is expected by :meth:`string.Template.substitute`. .. versionchanged:: 3.2 diff --git a/Doc/install/index.rst b/Doc/install/index.rst index 84df5e7..d2d8e56 100644 --- a/Doc/install/index.rst +++ b/Doc/install/index.rst @@ -761,7 +761,7 @@ And on Windows, the configuration files are: +--------------+-------------------------------------------------+-------+ On all platforms, the "personal" file can be temporarily disabled by -passing the `--no-user-cfg` option. +passing the ``--no-user-cfg`` option. Notes: diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst index 8b67f4b..969354c 100644 --- a/Doc/library/asyncio-protocol.rst +++ b/Doc/library/asyncio-protocol.rst @@ -553,7 +553,7 @@ accept factories that return streaming protocols. a connection is open. However, :meth:`protocol.eof_received() ` - is called at most once. Once `eof_received()` is called, + is called at most once. Once ``eof_received()`` is called, ``data_received()`` is not called anymore. .. method:: Protocol.eof_received() diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 221197e..27054d7 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -629,7 +629,7 @@ Timeouts Change the time the timeout will trigger. - If *when* is `None`, any current deadline will be removed, and the + If *when* is ``None``, any current deadline will be removed, and the context manager will wait indefinitely. If *when* is a float, it is set as the new deadline. @@ -865,17 +865,17 @@ Running in Threads # blocking_io complete at 19:50:54 # finished main at 19:50:54 - Directly calling `blocking_io()` in any coroutine would block the event loop + Directly calling ``blocking_io()`` in any coroutine would block the event loop for its duration, resulting in an additional 1 second of run time. Instead, - by using `asyncio.to_thread()`, we can run it in a separate thread without + by using ``asyncio.to_thread()``, we can run it in a separate thread without blocking the event loop. .. note:: - Due to the :term:`GIL`, `asyncio.to_thread()` can typically only be used + Due to the :term:`GIL`, ``asyncio.to_thread()`` can typically only be used to make IO-bound functions non-blocking. However, for extension modules that release the GIL or alternative Python implementations that don't - have one, `asyncio.to_thread()` can also be used for CPU-bound functions. + have one, ``asyncio.to_thread()`` can also be used for CPU-bound functions. .. versionadded:: 3.9 diff --git a/Doc/library/bdb.rst b/Doc/library/bdb.rst index 7b74bbd..d201dc9 100644 --- a/Doc/library/bdb.rst +++ b/Doc/library/bdb.rst @@ -143,7 +143,7 @@ The :mod:`bdb` module also defines two classes: For real file names, the canonical form is an operating-system-dependent, :func:`case-normalized ` :func:`absolute path - `. A *filename* with angle brackets, such as `""` + `. A *filename* with angle brackets, such as ``""`` generated in interactive mode, is returned unchanged. .. method:: reset() diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst index 999892e..ae5a159 100644 --- a/Doc/library/bz2.rst +++ b/Doc/library/bz2.rst @@ -206,7 +206,7 @@ Incremental (de)compression will be set to ``True``. Attempting to decompress data after the end of stream is reached - raises an `EOFError`. Any data found after the end of the + raises an :exc:`EOFError`. Any data found after the end of the stream is ignored and saved in the :attr:`~.unused_data` attribute. .. versionchanged:: 3.5 @@ -303,7 +303,7 @@ Using :class:`BZ2Compressor` for incremental compression: >>> out = out + comp.flush() The example above uses a very "nonrandom" stream of data -(a stream of `b"z"` chunks). Random data tends to compress poorly, +(a stream of ``b"z"`` chunks). Random data tends to compress poorly, while ordered, repetitive data usually yields a high compression ratio. Writing and reading a bzip2-compressed file in binary mode: diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst index 95c9e50..8106cc2 100644 --- a/Doc/library/concurrent.futures.rst +++ b/Doc/library/concurrent.futures.rst @@ -152,7 +152,7 @@ And:: All threads enqueued to ``ThreadPoolExecutor`` will be joined before the interpreter can exit. Note that the exit handler which does this is - executed *before* any exit handlers added using `atexit`. This means + executed *before* any exit handlers added using ``atexit``. This means exceptions in the main thread must be caught and handled in order to signal threads to exit gracefully. For this reason, it is recommended that ``ThreadPoolExecutor`` not be used for long-running tasks. @@ -411,13 +411,13 @@ The :class:`Future` class encapsulates the asynchronous execution of a callable. tests. If the method returns ``False`` then the :class:`Future` was cancelled, - i.e. :meth:`Future.cancel` was called and returned `True`. Any threads + i.e. :meth:`Future.cancel` was called and returned ``True``. Any threads waiting on the :class:`Future` completing (i.e. through :func:`as_completed` or :func:`wait`) will be woken up. If the method returns ``True`` then the :class:`Future` was not cancelled and has been put in the running state, i.e. calls to - :meth:`Future.running` will return `True`. + :meth:`Future.running` will return ``True``. This method can only be called once and cannot be called after :meth:`Future.set_result` or :meth:`Future.set_exception` have been diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 99c35a8..2900f77 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1934,7 +1934,7 @@ Utility functions .. function:: GetLastError() Windows only: Returns the last error code set by Windows in the calling thread. - This function calls the Windows `GetLastError()` function directly, + This function calls the Windows ``GetLastError()`` function directly, it does not return the ctypes-private copy of the error code. .. function:: get_errno() diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst index a7cc495..83e19fa 100644 --- a/Doc/library/curses.rst +++ b/Doc/library/curses.rst @@ -278,7 +278,7 @@ The module :mod:`curses` defines the following functions: Change the definition of a color, taking the number of the color to be changed followed by three RGB values (for the amounts of red, green, and blue components). The value of *color_number* must be between ``0`` and - `COLORS - 1`. Each of *r*, *g*, *b*, must be a value between ``0`` and + ``COLORS - 1``. Each of *r*, *g*, *b*, must be a value between ``0`` and ``1000``. When :func:`init_color` is used, all occurrences of that color on the screen immediately change to the new definition. This function is a no-op on most terminals; it is active only if :func:`can_change_color` returns ``True``. diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index b4580d1..8a7d999 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -1769,7 +1769,7 @@ Other constructor: ISO 8601 format, with the following exceptions: 1. Time zone offsets may have fractional seconds. - 2. The leading `T`, normally required in cases where there may be ambiguity between + 2. The leading ``T``, normally required in cases where there may be ambiguity between a date and a time, is not required. 3. Fractional seconds may have any number of digits (anything beyond 6 will be truncated). @@ -2265,7 +2265,7 @@ where historical changes have been made to civil time. two digits of ``offset.hours`` and ``offset.minutes`` respectively. .. versionchanged:: 3.6 - Name generated from ``offset=timedelta(0)`` is now plain `'UTC'`, not + Name generated from ``offset=timedelta(0)`` is now plain ``'UTC'``, not ``'UTC+00:00'``. diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index e7d3950..6bce940 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -576,11 +576,11 @@ Decimal objects Alternative constructor that only accepts instances of :class:`float` or :class:`int`. - Note `Decimal.from_float(0.1)` is not the same as `Decimal('0.1')`. + Note ``Decimal.from_float(0.1)`` is not the same as ``Decimal('0.1')``. Since 0.1 is not exactly representable in binary floating point, the value is stored as the nearest representable value which is - `0x1.999999999999ap-4`. That equivalent value in decimal is - `0.1000000000000000055511151231257827021181583404541015625`. + ``0x1.999999999999ap-4``. That equivalent value in decimal is + ``0.1000000000000000055511151231257827021181583404541015625``. .. note:: From Python 3.2 onwards, a :class:`Decimal` instance can also be constructed directly from a :class:`float`. @@ -1209,7 +1209,7 @@ In addition to the three supplied contexts, new contexts can be created with the .. method:: exp(x) - Returns `e ** x`. + Returns ``e ** x``. .. method:: fma(x, y, z) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index d292592..98866b7 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -373,7 +373,7 @@ details of bytecode instructions as :class:`Instruction` instances: .. class:: Positions - In case the information is not available, some fields might be `None`. + In case the information is not available, some fields might be ``None``. .. data:: lineno .. data:: end_lineno diff --git a/Doc/library/email.compat32-message.rst b/Doc/library/email.compat32-message.rst index 4eaa9d5..5bef155 100644 --- a/Doc/library/email.compat32-message.rst +++ b/Doc/library/email.compat32-message.rst @@ -298,7 +298,7 @@ Here are the methods of the :class:`Message` class: In a model generated from bytes, any header values that (in contravention of the RFCs) contain non-ASCII bytes will, when retrieved through this interface, be represented as :class:`~email.header.Header` objects with - a charset of `unknown-8bit`. + a charset of ``unknown-8bit``. .. method:: __len__() diff --git a/Doc/library/email.headerregistry.rst b/Doc/library/email.headerregistry.rst index 98527ce..00a954e 100644 --- a/Doc/library/email.headerregistry.rst +++ b/Doc/library/email.headerregistry.rst @@ -153,7 +153,7 @@ headers. specified as ``-0000`` (indicating it is in UTC but contains no information about the source timezone), then :attr:`.datetime` will be a naive :class:`~datetime.datetime`. If a specific timezone offset is - found (including `+0000`), then :attr:`.datetime` will contain an aware + found (including ``+0000``), then :attr:`.datetime` will contain an aware ``datetime`` that uses :class:`datetime.timezone` to record the timezone offset. diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index d6792ed..9beebd2 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -144,7 +144,7 @@ The :mod:`functools` module defines the following functions: arguments to the function must be hashable. Distinct argument patterns may be considered to be distinct calls with - separate cache entries. For example, `f(a=1, b=2)` and `f(b=2, a=1)` + separate cache entries. For example, ``f(a=1, b=2)`` and ``f(b=2, a=1)`` differ in their keyword argument order and may have two separate cache entries. @@ -191,7 +191,7 @@ The :mod:`functools` module defines the following functions: The cache keeps references to the arguments and return values until they age out of the cache or until the cache is cleared. - If a method is cached, the `self` instance argument is included in the + If a method is cached, the ``self`` instance argument is included in the cache. See :ref:`faq-cache-method-calls` An `LRU (least recently used) cache diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst index 0906ce7..a96fc8b 100644 --- a/Doc/library/hashlib.rst +++ b/Doc/library/hashlib.rst @@ -432,7 +432,7 @@ Constructor functions also accept the following tree hashing parameters: BLAKE2s, 0 in sequential mode). * *last_node*: boolean indicating whether the processed node is the last - one (`False` for sequential mode). + one (``False`` for sequential mode). .. figure:: hashlib-blake2-tree.png :alt: Explanation of tree mode parameters. diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 8fd6b35..0968509 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -1055,10 +1055,10 @@ Text I/O The initial value of the buffer can be set by providing *initial_value*. If newline translation is enabled, newlines will be encoded as if by :meth:`~TextIOBase.write`. The stream is positioned at the start of the - buffer which emulates opening an existing file in a `w+` mode, making it + buffer which emulates opening an existing file in a ``w+`` mode, making it ready for an immediate write from the beginning or for a write that - would overwrite the initial value. To emulate opening a file in an `a+` - mode ready for appending, use `f.seek(0, io.SEEK_END)` to reposition the + would overwrite the initial value. To emulate opening a file in an ``a+`` + mode ready for appending, use ``f.seek(0, io.SEEK_END)`` to reposition the stream at the end of the buffer. The *newline* argument works like that of :class:`TextIOWrapper`, diff --git a/Doc/library/lzma.rst b/Doc/library/lzma.rst index 2109264..868d4dc 100644 --- a/Doc/library/lzma.rst +++ b/Doc/library/lzma.rst @@ -258,7 +258,7 @@ Compressing and decompressing data in memory will be set to ``True``. Attempting to decompress data after the end of stream is reached - raises an `EOFError`. Any data found after the end of the + raises an :exc:`EOFError`. Any data found after the end of the stream is ignored and saved in the :attr:`~.unused_data` attribute. .. versionchanged:: 3.5 diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 9a4e2f8..633cd08 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -3180,7 +3180,7 @@ features: system records access and modification times; see :func:`~os.stat`. The best way to preserve exact times is to use the *st_atime_ns* and *st_mtime_ns* fields from the :func:`os.stat` result object with the *ns* parameter to - `utime`. + :func:`utime`. This function can support :ref:`specifying a file descriptor `, :ref:`paths relative to directory descriptors ` and :ref:`not @@ -4071,7 +4071,7 @@ written in Python, such as a mail server's external command delivery program. library :c:data:`POSIX_SPAWN_RESETIDS` flag. If the *setsid* argument is ``True``, it will create a new session ID - for `posix_spawn`. *setsid* requires :c:data:`POSIX_SPAWN_SETSID` + for ``posix_spawn``. *setsid* requires :c:data:`POSIX_SPAWN_SETSID` or :c:data:`POSIX_SPAWN_SETSID_NP` flag. Otherwise, :exc:`NotImplementedError` is raised. diff --git a/Doc/library/select.rst b/Doc/library/select.rst index a8df81f..2890706 100644 --- a/Doc/library/select.rst +++ b/Doc/library/select.rst @@ -61,7 +61,7 @@ The module defines the following: events. *sizehint* informs epoll about the expected number of events to be - registered. It must be positive, or `-1` to use the default. It is only + registered. It must be positive, or ``-1`` to use the default. It is only used on older systems where :c:func:`epoll_create1` is not available; otherwise it has no effect (though its value is still checked). diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index b1c2ab0..8c26089 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -642,7 +642,7 @@ The following functions all create :ref:`socket objects `. When :const:`SOCK_NONBLOCK` or :const:`SOCK_CLOEXEC` bit flags are applied to *type* they are cleared, and :attr:`socket.type` will not reflect them. They are still passed - to the underlying system `socket()` call. Therefore, + to the underlying system ``socket()`` call. Therefore, :: diff --git a/Doc/library/statistics.rst b/Doc/library/statistics.rst index bf86990..78c4bc5 100644 --- a/Doc/library/statistics.rst +++ b/Doc/library/statistics.rst @@ -813,7 +813,7 @@ of applications in statistics. The relative likelihood is computed as the probability of a sample occurring in a narrow range divided by the width of the range (hence the word "density"). Since the likelihood is relative to other points, - its value can be greater than `1.0`. + its value can be greater than ``1.0``. .. method:: NormalDist.cdf(x) diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index aab3f6a..542b08b 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -250,7 +250,7 @@ always available. Print low-level information to stderr about the state of CPython's memory allocator. - If Python is `built in debug mode ` (:option:`configure + If Python is :ref:`built in debug mode ` (:option:`configure --with-pydebug option <--with-pydebug>`), it also performs some expensive internal consistency checks. @@ -349,7 +349,7 @@ always available. files to (and read them from) a parallel directory tree rooted at this directory, rather than from ``__pycache__`` directories in the source code tree. Any ``__pycache__`` directories in the source code tree will be ignored - and new `.pyc` files written within the pycache prefix. Thus if you use + and new ``.pyc`` files written within the pycache prefix. Thus if you use :mod:`compileall` as a pre-build step, you must ensure you run it with the same pycache prefix (if any) that you will use at runtime. @@ -874,7 +874,7 @@ always available. .. function:: get_asyncgen_hooks() Returns an *asyncgen_hooks* object, which is similar to a - :class:`~collections.namedtuple` of the form `(firstiter, finalizer)`, + :class:`~collections.namedtuple` of the form ``(firstiter, finalizer)``, where *firstiter* and *finalizer* are expected to be either ``None`` or functions which take an :term:`asynchronous generator iterator` as an argument, and are used to schedule finalization of an asynchronous diff --git a/Doc/library/unittest.mock-examples.rst b/Doc/library/unittest.mock-examples.rst index 054efa8..f9a207b 100644 --- a/Doc/library/unittest.mock-examples.rst +++ b/Doc/library/unittest.mock-examples.rst @@ -1116,7 +1116,7 @@ on first use). That aside there is a way to use ``mock`` to affect the results of an import. Importing fetches an *object* from the :data:`sys.modules` dictionary. Note that it fetches an *object*, which need not be a module. Importing a module for the -first time results in a module object being put in `sys.modules`, so usually +first time results in a module object being put in ``sys.modules``, so usually when you import something you get a module back. This need not be the case however. diff --git a/Doc/library/xml.dom.minidom.rst b/Doc/library/xml.dom.minidom.rst index 82e5d6a..72a7a98 100644 --- a/Doc/library/xml.dom.minidom.rst +++ b/Doc/library/xml.dom.minidom.rst @@ -148,8 +148,8 @@ module documentation. This section lists the differences between the API and Similarly, explicitly stating the *standalone* argument causes the standalone document declarations to be added to the prologue of the XML document. - If the value is set to `True`, `standalone="yes"` is added, - otherwise it is set to `"no"`. + If the value is set to ``True``, ``standalone="yes"`` is added, + otherwise it is set to ``"no"``. Not stating the argument will omit the declaration from the document. .. versionchanged:: 3.8 diff --git a/Doc/library/xmlrpc.client.rst b/Doc/library/xmlrpc.client.rst index 8b09acd..bd2c49a 100644 --- a/Doc/library/xmlrpc.client.rst +++ b/Doc/library/xmlrpc.client.rst @@ -60,7 +60,7 @@ between conformable Python objects and XML on the wire. may be passed to calls. The *headers* parameter is an optional sequence of HTTP headers to send with each request, expressed as a sequence of 2-tuples representing the header - name and value. (e.g. `[('Header-Name', 'value')]`). + name and value. (e.g. ``[('Header-Name', 'value')]``). The obsolete *use_datetime* flag is similar to *use_builtin_types* but it applies only to date/time values. diff --git a/Doc/library/xmlrpc.server.rst b/Doc/library/xmlrpc.server.rst index 9778a85..016369d 100644 --- a/Doc/library/xmlrpc.server.rst +++ b/Doc/library/xmlrpc.server.rst @@ -263,7 +263,7 @@ This ExampleService demo can be invoked from the command line:: The client that interacts with the above server is included in -`Lib/xmlrpc/client.py`:: +``Lib/xmlrpc/client.py``:: server = ServerProxy("http://localhost:8000") diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 6b5e0e1..cc96975 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -1551,7 +1551,7 @@ built-in types. true). * Mappings (instances of :class:`dict`) compare equal if and only if they have - equal `(key, value)` pairs. Equality comparison of the keys and values + equal ``(key, value)`` pairs. Equality comparison of the keys and values enforces reflexivity. Order comparisons (``<``, ``>``, ``<=``, and ``>=``) raise :exc:`TypeError`. diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index 0d8c029..70d946a 100644 --- a/Doc/reference/import.rst +++ b/Doc/reference/import.rst @@ -816,7 +816,7 @@ The path based finder iterates over every entry in the search path, and for each of these, looks for an appropriate :term:`path entry finder` (:class:`~importlib.abc.PathEntryFinder`) for the path entry. Because this can be an expensive operation (e.g. there may be -`stat()` call overheads for this search), the path based finder maintains +``stat()`` call overheads for this search), the path based finder maintains a cache mapping path entries to path entry finders. This cache is maintained in :data:`sys.path_importer_cache` (despite the name, this cache actually stores finder objects rather than being limited to :term:`importer` objects). diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index 8311de0..5c9937f 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -994,20 +994,12 @@ The :keyword:`!nonlocal` statement .. productionlist:: python-grammar nonlocal_stmt: "nonlocal" `identifier` ("," `identifier`)* -.. XXX add when implemented - : ["=" (`target_list` "=")+ starred_expression] - : | "nonlocal" identifier augop expression_list - The :keyword:`nonlocal` statement causes the listed identifiers to refer to previously bound variables in the nearest enclosing scope excluding globals. This is important because the default behavior for binding is to search the local namespace first. The statement allows encapsulated code to rebind variables outside of the local scope besides the global (module) scope. -.. XXX not implemented - The :keyword:`nonlocal` statement may prepend an assignment or augmented - assignment, but not an expression. - Names listed in a :keyword:`nonlocal` statement, unlike those listed in a :keyword:`global` statement, must refer to pre-existing bindings in an enclosing scope (the scope in which a new binding should be created cannot diff --git a/Doc/requirements.txt b/Doc/requirements.txt index be05873..7f82dc3 100644 --- a/Doc/requirements.txt +++ b/Doc/requirements.txt @@ -10,7 +10,7 @@ blurb # sphinx-lint 0.6.2 yields many default role errors due to the new regular # expression used for default role detection, so we don't use the version # until the errors are fixed. -sphinx-lint<1,!=0.6.2 +sphinx-lint==0.6.4 # The theme used by the documentation is stored separately, so we need # to install that as well. diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 8ce9884..c387528 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -750,12 +750,12 @@ Compiler flags In particular, :envvar:`CFLAGS` should not contain: - * the compiler flag `-I` (for setting the search path for include files). - The `-I` flags are processed from left to right, and any flags in - :envvar:`CFLAGS` would take precedence over user- and package-supplied `-I` + * the compiler flag ``-I`` (for setting the search path for include files). + The ``-I`` flags are processed from left to right, and any flags in + :envvar:`CFLAGS` would take precedence over user- and package-supplied ``-I`` flags. - * hardening flags such as `-Werror` because distributions cannot control + * hardening flags such as ``-Werror`` because distributions cannot control whether packages installed by users conform to such heightened standards. @@ -873,9 +873,9 @@ Linker flags In particular, :envvar:`LDFLAGS` should not contain: - * the compiler flag `-L` (for setting the search path for libraries). - The `-L` flags are processed from left to right, and any flags in - :envvar:`LDFLAGS` would take precedence over user- and package-supplied `-L` + * the compiler flag ``-L`` (for setting the search path for libraries). + The ``-L`` flags are processed from left to right, and any flags in + :envvar:`LDFLAGS` would take precedence over user- and package-supplied ``-L`` flags. .. envvar:: CONFIGURE_LDFLAGS_NODIST diff --git a/Doc/using/unix.rst b/Doc/using/unix.rst index 061cfa5..24c02c9 100644 --- a/Doc/using/unix.rst +++ b/Doc/using/unix.rst @@ -170,7 +170,7 @@ Custom OpenSSL $ popd 3. Build Python with custom OpenSSL - (see the configure `--with-openssl` and `--with-openssl-rpath` options) + (see the configure ``--with-openssl`` and ``--with-openssl-rpath`` options) .. code-block:: shell-session diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst index e338b11..4ab68e1 100644 --- a/Doc/using/windows.rst +++ b/Doc/using/windows.rst @@ -203,7 +203,7 @@ of available options is shown below. +---------------------------+--------------------------------------+--------------------------+ | Include_pip | Install bundled pip and setuptools | 1 | +---------------------------+--------------------------------------+--------------------------+ -| Include_symbols | Install debugging symbols (`*`.pdb) | 0 | +| Include_symbols | Install debugging symbols (``*.pdb``)| 0 | +---------------------------+--------------------------------------+--------------------------+ | Include_tcltk | Install Tcl/Tk support and IDLE | 1 | +---------------------------+--------------------------------------+--------------------------+ diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst index 6dddf37..b96dfe9 100644 --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -717,13 +717,13 @@ This will produce the output:: PEP 3101: Advanced String Formatting ===================================================== -In Python 3.0, the `%` operator is supplemented by a more powerful string +In Python 3.0, the ``%`` operator is supplemented by a more powerful string formatting method, :meth:`format`. Support for the :meth:`str.format` method has been backported to Python 2.6. -In 2.6, both 8-bit and Unicode strings have a `.format()` method that +In 2.6, both 8-bit and Unicode strings have a ``.format()`` method that treats the string as a template and takes the arguments to be formatted. -The formatting template uses curly brackets (`{`, `}`) as special characters:: +The formatting template uses curly brackets (``{``, ``}``) as special characters:: >>> # Substitute positional argument 0 into the string. >>> "User ID: {0}".format("root") diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst index 3df9f8a..82f5ea3 100644 --- a/Doc/whatsnew/2.7.rst +++ b/Doc/whatsnew/2.7.rst @@ -2485,8 +2485,8 @@ In the standard library: * The ElementTree library, :mod:`xml.etree`, no longer escapes ampersands and angle brackets when outputting an XML processing - instruction (which looks like ``) - or comment (which looks like ``). + instruction (which looks like ````) + or comment (which looks like ````). (Patch by Neil Muller; :issue:`2746`.) * The :meth:`~StringIO.StringIO.readline` method of :class:`~StringIO.StringIO` objects now does diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst index db8d928..24d5bba 100644 --- a/Doc/whatsnew/3.10.rst +++ b/Doc/whatsnew/3.10.rst @@ -1183,7 +1183,7 @@ and will be incorrect in some rare cases, including some ``_``-s in New in 3.10 maintenance releases. -Apply syntax highlighting to `.pyi` files. (Contributed by Alex +Apply syntax highlighting to ``.pyi`` files. (Contributed by Alex Waygood and Terry Jan Reedy in :issue:`45447`.) Include prompts when saving Shell with inputs and outputs. diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index b5ca28e..10534b1 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -740,7 +740,7 @@ hashlib IDLE and idlelib ---------------- -* Apply syntax highlighting to `.pyi` files. (Contributed by Alex +* Apply syntax highlighting to ``.pyi`` files. (Contributed by Alex Waygood and Terry Jan Reedy in :issue:`45447`.) * Include prompts when saving Shell with inputs and outputs. diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst index 7b12e63..3becd3f 100644 --- a/Doc/whatsnew/3.2.rst +++ b/Doc/whatsnew/3.2.rst @@ -1746,7 +1746,7 @@ names. instead of module names for running specific tests (:issue:`10620`). The new test discovery can find tests within packages, locating any test importable from the top-level directory. The top-level directory can be specified with - the `-t` option, a pattern for matching files with ``-p``, and a directory to + the ``-t`` option, a pattern for matching files with ``-p``, and a directory to start discovery with ``-s``: .. code-block:: shell-session @@ -1858,7 +1858,7 @@ asyncore :class:`asyncore.dispatcher` now provides a :meth:`~asyncore.dispatcher.handle_accepted()` method -returning a `(sock, addr)` pair which is called when a connection has actually +returning a ``(sock, addr)`` pair which is called when a connection has actually been established with a new remote endpoint. This is supposed to be used as a replacement for old :meth:`~asyncore.dispatcher.handle_accept()` and avoids the user to call :meth:`~asyncore.dispatcher.accept()` directly. diff --git a/Doc/whatsnew/3.3.rst b/Doc/whatsnew/3.3.rst index fef1a8a..96a6325 100644 --- a/Doc/whatsnew/3.3.rst +++ b/Doc/whatsnew/3.3.rst @@ -2389,10 +2389,10 @@ Porting Python code :attr:`sys.path_importer_cache` where it represents the use of implicit finders, but semantically it should not change anything. -* :class:`importlib.abc.Finder` no longer specifies a `find_module()` abstract +* :class:`importlib.abc.Finder` no longer specifies a ``find_module()`` abstract method that must be implemented. If you were relying on subclasses to implement that method, make sure to check for the method's existence first. - You will probably want to check for `find_loader()` first, though, in the + You will probably want to check for ``find_loader()`` first, though, in the case of working with :term:`path entry finders `. * :mod:`pkgutil` has been converted to use :mod:`importlib` internally. This diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst index 625373d..f9cceec 100644 --- a/Doc/whatsnew/3.5.rst +++ b/Doc/whatsnew/3.5.rst @@ -2469,11 +2469,11 @@ Changes in the Python API ``opt-`` tag in ``.pyc`` file names. The :func:`importlib.util.cache_from_source` has gained an *optimization* parameter to help control the ``opt-`` tag. Because of this, the - *debug_override* parameter of the function is now deprecated. `.pyo` files + *debug_override* parameter of the function is now deprecated. ``.pyo`` files are also no longer supported as a file argument to the Python interpreter and thus serve no purpose when distributed on their own (i.e. sourceless code distribution). Due to the fact that the magic number for bytecode has changed - in Python 3.5, all old `.pyo` files from previous versions of Python are + in Python 3.5, all old ``.pyo`` files from previous versions of Python are invalid regardless of this PEP. * The :mod:`socket` module now exports the :data:`~socket.CAN_RAW_FD_FRAMES` diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst index bcca28d..70e4525 100644 --- a/Doc/whatsnew/3.6.rst +++ b/Doc/whatsnew/3.6.rst @@ -960,8 +960,8 @@ contextlib The :class:`contextlib.AbstractContextManager` class has been added to provide an abstract base class for context managers. It provides a -sensible default implementation for `__enter__()` which returns -``self`` and leaves `__exit__()` an abstract method. A matching +sensible default implementation for ``__enter__()`` which returns +``self`` and leaves ``__exit__()`` an abstract method. A matching class has been added to the :mod:`typing` module as :class:`typing.ContextManager`. (Contributed by Brett Cannon in :issue:`25609`.) @@ -1388,7 +1388,7 @@ are treated as punctuation. site ---- -When specifying paths to add to :attr:`sys.path` in a `.pth` file, +When specifying paths to add to :attr:`sys.path` in a ``.pth`` file, you may now specify file paths on top of directories (e.g. zip files). (Contributed by Wolfgang Langner in :issue:`26587`). diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst index 5bb3d2a..de03e5b 100644 --- a/Doc/whatsnew/3.7.rst +++ b/Doc/whatsnew/3.7.rst @@ -2497,7 +2497,7 @@ number of other issues). Some known details affected: * :c:func:`PySys_AddWarnOptionUnicode` is not currently usable by embedding applications due to the requirement to create a Unicode object prior to - calling `Py_Initialize`. Use :c:func:`PySys_AddWarnOption` instead. + calling ``Py_Initialize``. Use :c:func:`PySys_AddWarnOption` instead. * warnings filters added by an embedding application with :c:func:`PySys_AddWarnOption` should now more consistently take precedence diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst index ff01a65..624e71f 100644 --- a/Doc/whatsnew/3.9.rst +++ b/Doc/whatsnew/3.9.rst @@ -500,7 +500,7 @@ Reedy in :issue:`40468`.) Move the indent space setting from the Font tab to the new Windows tab. (Contributed by Mark Roseman and Terry Jan Reedy in :issue:`33962`.) -Apply syntax highlighting to `.pyi` files. (Contributed by Alex +Apply syntax highlighting to ``.pyi`` files. (Contributed by Alex Waygood and Terry Jan Reedy in :issue:`45447`.) imaplib -- cgit v0.12 From b0e3eaae580389b0f97547fabe200451032ec4c9 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 18 Oct 2022 21:34:40 -0700 Subject: gh-95913: Add WhatsNew section for new logging APIs (GH-98320) * Add entry for new logging.getLevelNamesMapping function * Add entry for SysLogHandler.createSocket to whatsnew * Add missing line break between logging bullet list items (cherry picked from commit 251b8ccd2a4354840ed2d3aeb9b643a999ba792f) Co-authored-by: C.A.M. Gerlach --- Doc/whatsnew/3.11.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 10534b1..cd78b14 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -781,6 +781,26 @@ locale ``locale.getpreferredencoding(False)`` but ignores the :ref:`Python UTF-8 Mode `. + +.. _whatsnew311-logging: + +logging +------- + +* Added :func:`~logging.getLevelNamesMapping` + to return a mapping from logging level names (e.g. ``'CRITICAL'``) + to the values of their corresponding :ref:`levels` (e.g. ``50``, by default). + (Contributed by Andrei Kulakovin in :gh:`88024`.) + +* Added a :meth:`~logging.handlers.SysLogHandler.createSocket` method + to :class:`~logging.handlers.SysLogHandler`, to match + :meth:`SocketHandler.createSocket() + `. + It is called automatically during handler initialization + and when emitting an event, if there is no active socket. + (Contributed by Kirill Pinchuk in :gh:`88457`.) + + math ---- -- cgit v0.12 From 425bec30021e6b2dcad8f6411725991a096d286a Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 18 Oct 2022 21:40:47 -0700 Subject: gh-95913: Edit zipfile Whatsnew section & add new APIs (GH-98314) * Link ZipFile in What's New entry discussing it * Add entry for new ZipFile.mkdir method * Add entry for new zipfile.Path.stem/suffix/suffixes methods * Add missing line breaks between zipfile bullet list items (cherry picked from commit ed827d560831b054d262818b1777f7879e8fbd3e) Co-authored-by: C.A.M. Gerlach --- Doc/whatsnew/3.11.rst | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index cd78b14..642a129 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -1110,13 +1110,25 @@ warnings providing a more concise way to locally ignore warnings or convert them to errors. (Contributed by Zac Hatfield-Dodds in :issue:`47074`.) + +.. _whatsnew311-zipfile: + zipfile ------- -* Added support for specifying member name encoding for reading - metadata in the zipfile's directory and file headers. +* Added support for specifying member name encoding for reading metadata + in a :class:`~zipfile.ZipFile`'s directory and file headers. (Contributed by Stephen J. Turnbull and Serhiy Storchaka in :issue:`28080`.) +* Added :meth:`ZipFile.mkdir() ` + for creating new directories inside ZIP archives. + (Contributed by Sam Ezeh in :gh:`49083`.) + +* Added :attr:`~zipfile.Path.stem`, :attr:`~zipfile.Path.suffix` + and :attr:`~zipfile.Path.suffixes` to :class:`zipfile.Path`. + (Contributed by Miguel Brito in :gh:`88261`.) + + fcntl ----- -- cgit v0.12 From 1f192c3bcdc052871200722e2d561686e6245094 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 18 Oct 2022 02:34:47 -0700 Subject: gh-95913: Copyedit, xref and organize enum section (GH-98295) * Whatsnew: Convert literals in enum section to actual x-references * Whatsnew: Rewrite enum section for clear and consistant phrasing * Whatsnew: Combine directly related enum items instead of seperating them * gh-98250: Describe __str__/__format__ changes more clearly/accurately * Tweak enum section language per feedback from Ethan (cherry picked from commit 73e5180faf37e2d362e13f4ef12955a8b8535d7b) Co-authored-by: C.A.M. Gerlach --- Doc/whatsnew/3.11.rst | 102 +++++++++++++++++++++++++++++++------------------- 1 file changed, 64 insertions(+), 38 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 642a129..21c48f7 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -636,48 +636,74 @@ datetime formats (barring only those that support fractional hours and minutes). (Contributed by Paul Ganssle in :gh:`80010`.) -enum ----- - -* ``EnumMeta`` renamed to ``EnumType`` (``EnumMeta`` kept as alias). - -* ``StrEnum`` added -- enum members are and must be strings. - -* ``ReprEnum`` added -- causes only the ``__repr__`` to be modified, not the - ``__str__`` nor the ``__format__``. - -* ``FlagBoundary`` added -- controls behavior when invalid values are given to - a flag. - -* ``EnumCheck`` added -- used by ``verify`` to ensure various constraints. -* ``verify`` added -- function to ensure given ``EnumCheck`` constraints. +.. _whatsnew311-enum: -* ``member`` added -- decorator to ensure given object is converted to an enum - member. - -* ``nonmember`` added -- decorator to ensure given object is not converted to - an enum member. - -* ``property`` added -- use instead of ``types.DynamicClassAttribute``. - -* ``global_enum`` added -- enum decorator to adjust ``__repr__`` and ``__str__`` - to show members in the global context -- see ``re.RegexFlag`` for an example. - -* ``Flag`` enhancements: members support length, iteration, and containment - checks. - -* ``Enum``/``Flag`` fixes: members are now defined before ``__init_subclass__`` - is called; ``dir()`` now includes methods, etc., from mixed-in data types. +enum +---- -* ``Flag`` fixes: only primary values (power of two) are considered canonical - while composite values (3, 6, 10, etc.) are considered aliases; inverted - flags are coerced to their positive equivalent. +* Renamed :class:`!EnumMeta` to :class:`~enum.EnumType` + (:class:`!EnumMeta` kept as an alias). + +* Added :class:`~enum.StrEnum`, + with members that can be used as (and must be) strings. + +* Added :class:`~enum.ReprEnum`, + which only modifies the :meth:`~object.__repr__` of members + while returning their literal values (rather than names) + for :meth:`~object.__str__` and :meth:`~object.__format__` + (used by :func:`str`, :func:`format` and :term:`f-string`\s). + +* Changed :class:`~enum.IntEnum`, :class:`~enum.IntFlag` and :class:`~enum.StrEnum` + to now inherit from :class:`ReprEnum`, + so their :func:`str` output now matches :func:`format` + (both ``str(AnIntEnum.ONE)`` and ``format(AnIntEnum.ONE)`` return ``'1'``, + whereas before ``str(AnIntEnum.ONE)`` returned ``'AnIntEnum.ONE'``. + +* Changed :meth:`Enum.__format__() ` + (the default for :func:`format`, :meth:`str.format` and :term:`f-string`\s) + of enums with mixed-in types (e.g. :class:`int`, :class:`str`) + to also include the class name in the output, not just the member's key. + This matches the existing behavior of :meth:`enum.Enum.__str__`, + returning e.g. ``'AnEnum.MEMBER'`` for an enum ``AnEnum(str, Enum)`` + instead of just ``'MEMBER'``. + +* Added a new *boundary* class parameter to :class:`~enum.Flag` enums + and the :class:`~enum.FlagBoundary` enum with its options, + to control how to handle out-of-range flag values. + +* Added the :func:`~enum.verify` enum decorator + and the :class:`~enum.EnumCheck` enum with its options, + to check enum classes against several specific constraints. + +* Added the :func:`~enum.member` and :func:`~enum.nonmember` decorators, + to ensure the decorated object is/is not converted to an enum member. + +* Added the :func:`~enum.property` decorator, + which works like :func:`property` except for enums. + Use this instead of :func:`types.DynamicClassAttribute`. + +* Added the :func:`~enum.global_enum` enum decorator, + which adjusts :meth:`~object.__repr__` and :meth:`~object.__str__` + to show values as members of their module rather than the enum class. + For example, ``'re.ASCII'`` for the :data:`~re.ASCII` member + of :class:`re.RegexFlag` rather than ``'RegexFlag.ASCII'``. + +* Enhanced :class:`~enum.Flag` to support + :func:`len`, iteration and :keyword:`in`/:keyword:`not in` on its members. + For example, the following now works: + ``len(AFlag(3)) == 2 and list(AFlag(3)) == (AFlag.ONE, AFlag.TWO)`` + +* Changed :class:`~enum.Enum` and :class:`~enum.Flag` + so that members are now defined + before :meth:`~object.__init_subclass__` is called; + :func:`dir` now includes methods, etc., from mixed-in data types. + +* Changed :class:`~enum.Flag` + to only consider primary values (power of two) canonical + while composite values (``3``, ``6``, ``10``, etc.) are considered aliases; + inverted flags are coerced to their positive equivalent. -* ``IntEnum`` / ``IntFlag`` / ``StrEnum`` fixes: these now inherit from - ``ReprEnum`` so the ``str()`` output now matches ``format()`` output, - which is the data types' (so both ``str(AnIntEnum.ONE)`` and - ``format(AnIntEnum.ONE)`` is equal to ``'1'``). fractions --------- -- cgit v0.12 From a969af4eaa7d111b52832cb1d310c0ae46cc6402 Mon Sep 17 00:00:00 2001 From: Pablo Galindo Date: Sat, 22 Oct 2022 20:45:19 +0100 Subject: Sync What's new for the current 3.11.0rc2+ branch with the 3.11.0 release branch --- Doc/whatsnew/3.11.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 21c48f7..c143a41 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -196,7 +196,7 @@ See :pep:`654` for more details. Irit Katriel, Yury Selivanov and Guido van Rossum.) -.. _whatsnew311-pep670: +.. _whatsnew311-pep678: PEP 678: Exceptions can be enriched with notes ---------------------------------------------- @@ -383,9 +383,10 @@ See :pep:`675` for more details. (Contributed by Jelle Zijlstra in :issue:`47088`. PEP written by Pradeep Kumar Srinivasan and Graham Bleaney.) + .. _whatsnew311-pep681: -PEP 681: Data Class Transforms +PEP 681: Data class transforms ------------------------------ :data:`~typing.dataclass_transform` may be used to @@ -431,6 +432,8 @@ See `this message from the Steering Council Date: Wed, 5 Oct 2022 16:32:16 -0700 Subject: gh-96865: [Enum] fix Flag to use CONFORM boundary (GH-97528) (cherry picked from commit b44372e03c5461b6ad3d89763a9eb6cb82df07a4) Co-authored-by: Ethan Furman --- Lib/enum.py | 2 +- Lib/test/test_enum.py | 2 +- .../next/Library/2022-09-24-18-56-23.gh-issue-96865.o9WUkW.rst | 9 +++++++++ 3 files changed, 11 insertions(+), 2 deletions(-) create mode 100644 Misc/NEWS.d/next/Library/2022-09-24-18-56-23.gh-issue-96865.o9WUkW.rst diff --git a/Lib/enum.py b/Lib/enum.py index 28b638c..ff8f5cc 100644 --- a/Lib/enum.py +++ b/Lib/enum.py @@ -1292,7 +1292,7 @@ class FlagBoundary(StrEnum): STRICT, CONFORM, EJECT, KEEP = FlagBoundary -class Flag(Enum, boundary=STRICT): +class Flag(Enum, boundary=CONFORM): """ Support for flags """ diff --git a/Lib/test/test_enum.py b/Lib/test/test_enum.py index 7964d3e..8cd1fe1 100644 --- a/Lib/test/test_enum.py +++ b/Lib/test/test_enum.py @@ -2878,7 +2878,7 @@ class OldTestFlag(unittest.TestCase): self.assertEqual(bool(f.value), bool(f)) def test_boundary(self): - self.assertIs(enum.Flag._boundary_, STRICT) + self.assertIs(enum.Flag._boundary_, CONFORM) class Iron(Flag, boundary=STRICT): ONE = 1 TWO = 2 diff --git a/Misc/NEWS.d/next/Library/2022-09-24-18-56-23.gh-issue-96865.o9WUkW.rst b/Misc/NEWS.d/next/Library/2022-09-24-18-56-23.gh-issue-96865.o9WUkW.rst new file mode 100644 index 0000000..b054fde --- /dev/null +++ b/Misc/NEWS.d/next/Library/2022-09-24-18-56-23.gh-issue-96865.o9WUkW.rst @@ -0,0 +1,9 @@ +fix Flag to use boundary CONFORM + +This restores previous Flag behavior of allowing flags with non-sequential values to be combined; e.g. + + class Skip(Flag): + TWO = 2 + EIGHT = 8 + + Skip.TWO | Skip.EIGHT -> -- cgit v0.12 From 84fd4a54a61097ae2f80344f4dbd5b33cc2b7768 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 6 Oct 2022 12:13:46 -0700 Subject: [3.11] gh-97897: Prevent os.mkfifo and os.mknod segfaults with macOS 13 SDK (GH-97944) (#97969) The macOS 13 SDK includes support for the `mkfifoat` and `mknodat` system calls. Using the `dir_fd` option with either `os.mkfifo` or `os.mknod` could result in a segfault if cpython is built with the macOS 13 SDK but run on an earlier version of macOS. Prevent this by adding runtime support for detection of these system calls ("weaklinking") as is done for other newer syscalls on macOS. (cherry picked from commit 6d0a0191a4e5477bd843e62c24d7f3bcad4fd5fc) Co-authored-by: Ned Deily --- Lib/test/test_posix.py | 22 ++++++++ .../2022-10-05-15-26-58.gh-issue-97897.Rf-C6u.rst | 6 +++ Modules/posixmodule.c | 60 +++++++++++++++++++--- 3 files changed, 80 insertions(+), 8 deletions(-) create mode 100644 Misc/NEWS.d/next/macOS/2022-10-05-15-26-58.gh-issue-97897.Rf-C6u.rst diff --git a/Lib/test/test_posix.py b/Lib/test/test_posix.py index ae25ef5..e643d8e 100644 --- a/Lib/test/test_posix.py +++ b/Lib/test/test_posix.py @@ -2090,6 +2090,28 @@ class TestPosixWeaklinking(unittest.TestCase): with self.assertRaisesRegex(NotImplementedError, "dir_fd unavailable"): os.mkdir("dir", dir_fd=0) + def test_mkfifo(self): + self._verify_available("HAVE_MKFIFOAT") + if self.mac_ver >= (13, 0): + self.assertIn("HAVE_MKFIFOAT", posix._have_functions) + + else: + self.assertNotIn("HAVE_MKFIFOAT", posix._have_functions) + + with self.assertRaisesRegex(NotImplementedError, "dir_fd unavailable"): + os.mkfifo("path", dir_fd=0) + + def test_mknod(self): + self._verify_available("HAVE_MKNODAT") + if self.mac_ver >= (13, 0): + self.assertIn("HAVE_MKNODAT", posix._have_functions) + + else: + self.assertNotIn("HAVE_MKNODAT", posix._have_functions) + + with self.assertRaisesRegex(NotImplementedError, "dir_fd unavailable"): + os.mknod("path", dir_fd=0) + def test_rename_replace(self): self._verify_available("HAVE_RENAMEAT") if self.mac_ver >= (10, 10): diff --git a/Misc/NEWS.d/next/macOS/2022-10-05-15-26-58.gh-issue-97897.Rf-C6u.rst b/Misc/NEWS.d/next/macOS/2022-10-05-15-26-58.gh-issue-97897.Rf-C6u.rst new file mode 100644 index 0000000..0d21e98 --- /dev/null +++ b/Misc/NEWS.d/next/macOS/2022-10-05-15-26-58.gh-issue-97897.Rf-C6u.rst @@ -0,0 +1,6 @@ +The macOS 13 SDK includes support for the ``mkfifoat`` and ``mknodat`` system calls. +Using the ``dir_fd`` option with either :func:`os.mkfifo` or :func:`os.mknod` could result in a +segfault if cpython is built with the macOS 13 SDK but run on an earlier +version of macOS. Prevent this by adding runtime support for detection of +these system calls ("weaklinking") as is done for other newer syscalls on +macOS. diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c index 3780325..309982a 100644 --- a/Modules/posixmodule.c +++ b/Modules/posixmodule.c @@ -91,6 +91,8 @@ # define HAVE_FUTIMENS_RUNTIME __builtin_available(macOS 10.13, iOS 11.0, tvOS 11.0, watchOS 4.0, *) # define HAVE_UTIMENSAT_RUNTIME __builtin_available(macOS 10.13, iOS 11.0, tvOS 11.0, watchOS 4.0, *) # define HAVE_PWRITEV_RUNTIME __builtin_available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) +# define HAVE_MKFIFOAT_RUNTIME __builtin_available(macOS 13.0, iOS 16.0, tvOS 16.0, watchOS 9.0, *) +# define HAVE_MKNODAT_RUNTIME __builtin_available(macOS 13.0, iOS 16.0, tvOS 16.0, watchOS 9.0, *) # define HAVE_POSIX_SPAWN_SETSID_RUNTIME __builtin_available(macOS 10.15, *) @@ -175,6 +177,8 @@ # define HAVE_FUTIMENS_RUNTIME 1 # define HAVE_UTIMENSAT_RUNTIME 1 # define HAVE_PWRITEV_RUNTIME 1 +# define HAVE_MKFIFOAT_RUNTIME 1 +# define HAVE_MKNODAT_RUNTIME 1 #endif @@ -10644,18 +10648,35 @@ os_mkfifo_impl(PyObject *module, path_t *path, int mode, int dir_fd) { int result; int async_err = 0; +#ifdef HAVE_MKFIFOAT + int mkfifoat_unavailable = 0; +#endif do { Py_BEGIN_ALLOW_THREADS #ifdef HAVE_MKFIFOAT - if (dir_fd != DEFAULT_DIR_FD) - result = mkfifoat(dir_fd, path->narrow, mode); - else + if (dir_fd != DEFAULT_DIR_FD) { + if (HAVE_MKFIFOAT_RUNTIME) { + result = mkfifoat(dir_fd, path->narrow, mode); + + } else { + mkfifoat_unavailable = 1; + result = 0; + } + } else #endif result = mkfifo(path->narrow, mode); Py_END_ALLOW_THREADS } while (result != 0 && errno == EINTR && !(async_err = PyErr_CheckSignals())); + +#ifdef HAVE_MKFIFOAT + if (mkfifoat_unavailable) { + argument_unavailable_error(NULL, "dir_fd"); + return NULL; + } +#endif + if (result != 0) return (!async_err) ? posix_error() : NULL; @@ -10696,18 +10717,33 @@ os_mknod_impl(PyObject *module, path_t *path, int mode, dev_t device, { int result; int async_err = 0; +#ifdef HAVE_MKNODAT + int mknodat_unavailable = 0; +#endif do { Py_BEGIN_ALLOW_THREADS #ifdef HAVE_MKNODAT - if (dir_fd != DEFAULT_DIR_FD) - result = mknodat(dir_fd, path->narrow, mode, device); - else + if (dir_fd != DEFAULT_DIR_FD) { + if (HAVE_MKNODAT_RUNTIME) { + result = mknodat(dir_fd, path->narrow, mode, device); + + } else { + mknodat_unavailable = 1; + result = 0; + } + } else #endif result = mknod(path->narrow, mode, device); Py_END_ALLOW_THREADS } while (result != 0 && errno == EINTR && !(async_err = PyErr_CheckSignals())); +#ifdef HAVE_MKNODAT + if (mknodat_unavailable) { + argument_unavailable_error(NULL, "dir_fd"); + return NULL; + } +#endif if (result != 0) return (!async_err) ? posix_error() : NULL; @@ -15576,6 +15612,14 @@ PROBE(probe_fdopendir, HAVE_FDOPENDIR_RUNTIME) PROBE(probe_mkdirat, HAVE_MKDIRAT_RUNTIME) #endif +#ifdef HAVE_MKFIFOAT +PROBE(probe_mkfifoat, HAVE_MKFIFOAT_RUNTIME) +#endif + +#ifdef HAVE_MKNODAT +PROBE(probe_mknodat, HAVE_MKNODAT_RUNTIME) +#endif + #ifdef HAVE_RENAMEAT PROBE(probe_renameat, HAVE_RENAMEAT_RUNTIME) #endif @@ -15709,11 +15753,11 @@ static const struct have_function { #endif #ifdef HAVE_MKFIFOAT - { "HAVE_MKFIFOAT", NULL }, + { "HAVE_MKFIFOAT", probe_mkfifoat }, #endif #ifdef HAVE_MKNODAT - { "HAVE_MKNODAT", NULL }, + { "HAVE_MKNODAT", probe_mknodat }, #endif #ifdef HAVE_OPENAT -- cgit v0.12 From 9cb7324e8fc37350879fc6004ebbbb1cf5f9dd02 Mon Sep 17 00:00:00 2001 From: Nikita Sobolev Date: Thu, 6 Oct 2022 01:00:13 +0300 Subject: [3.11] gh-96587: Raise `SyntaxError` for PEP654 on older `feature_version` (GH-96588) (#96591) (cherry picked from commit 2c7d2e8d46164efb6e27a64081d8e949f6876515) Co-authored-by: Nikita Sobolev --- Grammar/python.gram | 4 +++- Lib/test/test_ast.py | 9 +++++++++ .../2022-09-05-19-20-44.gh-issue-96587.bVxhX2.rst | 2 ++ Parser/parser.c | 2 +- 4 files changed, 15 insertions(+), 2 deletions(-) create mode 100644 Misc/NEWS.d/next/Core and Builtins/2022-09-05-19-20-44.gh-issue-96587.bVxhX2.rst diff --git a/Grammar/python.gram b/Grammar/python.gram index d4df78b..51f846a 100644 --- a/Grammar/python.gram +++ b/Grammar/python.gram @@ -412,7 +412,9 @@ try_stmt[stmt_ty]: | invalid_try_stmt | 'try' &&':' b=block f=finally_block { _PyAST_Try(b, NULL, NULL, f, EXTRA) } | 'try' &&':' b=block ex[asdl_excepthandler_seq*]=except_block+ el=[else_block] f=[finally_block] { _PyAST_Try(b, ex, el, f, EXTRA) } - | 'try' &&':' b=block ex[asdl_excepthandler_seq*]=except_star_block+ el=[else_block] f=[finally_block] { _PyAST_TryStar(b, ex, el, f, EXTRA) } + | 'try' &&':' b=block ex[asdl_excepthandler_seq*]=except_star_block+ el=[else_block] f=[finally_block] { + CHECK_VERSION(stmt_ty, 11, "Exception groups are", + _PyAST_TryStar(b, ex, el, f, EXTRA)) } # Except statement diff --git a/Lib/test/test_ast.py b/Lib/test/test_ast.py index 7275e15..90ad6af 100644 --- a/Lib/test/test_ast.py +++ b/Lib/test/test_ast.py @@ -771,6 +771,15 @@ class AST_Tests(unittest.TestCase): with self.assertRaises(SyntaxError): ast.parse('(x := 0)', feature_version=(3, 7)) + def test_exception_groups_feature_version(self): + code = dedent(''' + try: ... + except* Exception: ... + ''') + ast.parse(code) + with self.assertRaises(SyntaxError): + ast.parse(code, feature_version=(3, 10)) + def test_constant_as_name(self): for constant in "True", "False", "None": expr = ast.Expression(ast.Name(constant, ast.Load())) diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-09-05-19-20-44.gh-issue-96587.bVxhX2.rst b/Misc/NEWS.d/next/Core and Builtins/2022-09-05-19-20-44.gh-issue-96587.bVxhX2.rst new file mode 100644 index 0000000..37e9dcb --- /dev/null +++ b/Misc/NEWS.d/next/Core and Builtins/2022-09-05-19-20-44.gh-issue-96587.bVxhX2.rst @@ -0,0 +1,2 @@ +Correctly raise ``SyntaxError`` on exception groups (:pep:`654`) on python +versions prior to 3.11 diff --git a/Parser/parser.c b/Parser/parser.c index e13dbe0..3fc12e5 100644 --- a/Parser/parser.c +++ b/Parser/parser.c @@ -6970,7 +6970,7 @@ try_stmt_rule(Parser *p) UNUSED(_end_lineno); // Only used by EXTRA macro int _end_col_offset = _token->end_col_offset; UNUSED(_end_col_offset); // Only used by EXTRA macro - _res = _PyAST_TryStar ( b , ex , el , f , EXTRA ); + _res = CHECK_VERSION ( stmt_ty , 11 , "Exception groups are" , _PyAST_TryStar ( b , ex , el , f , EXTRA ) ); if (_res == NULL && PyErr_Occurred()) { p->error_indicator = 1; p->level--; -- cgit v0.12 From 3ce43a2c85bad4947fec11ab51352fa3caaa294b Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 14 Sep 2022 08:59:34 -0700 Subject: gh-96729: Ensure installers built with Tools/msi/buildrelease.bat have matching UUIDs with official releases (GH-96755) (cherry picked from commit 662782e95f97d26bd57b3edc6aaf674e30899f44) Co-authored-by: adang1345 --- Misc/NEWS.d/next/Build/2022-09-11-14-23-49.gh-issue-96729.W4uBWL.rst | 2 ++ Tools/msi/buildrelease.bat | 4 +++- 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 Misc/NEWS.d/next/Build/2022-09-11-14-23-49.gh-issue-96729.W4uBWL.rst diff --git a/Misc/NEWS.d/next/Build/2022-09-11-14-23-49.gh-issue-96729.W4uBWL.rst b/Misc/NEWS.d/next/Build/2022-09-11-14-23-49.gh-issue-96729.W4uBWL.rst new file mode 100644 index 0000000..b67cd20 --- /dev/null +++ b/Misc/NEWS.d/next/Build/2022-09-11-14-23-49.gh-issue-96729.W4uBWL.rst @@ -0,0 +1,2 @@ +Ensure that Windows releases built with ``Tools\msi\buildrelease.bat`` are +upgradable to and from official Python releases. diff --git a/Tools/msi/buildrelease.bat b/Tools/msi/buildrelease.bat index ccec4da..839f620 100644 --- a/Tools/msi/buildrelease.bat +++ b/Tools/msi/buildrelease.bat @@ -12,7 +12,9 @@ rem rem The following substitutions will be applied to the release URI: rem Variable Description Example rem {arch} architecture amd64, win32 -set RELEASE_URI=https://www.python.org/{arch} +rem Do not change the scheme to https. Otherwise, releases built with this +rem script will not be upgradable to/from official releases of Python. +set RELEASE_URI=http://www.python.org/{arch} rem This is the URL that will be used to download installation files. rem The files available from the default URL *will* conflict with your -- cgit v0.12 From bac61bc5b132221dde406f0700e238c302029698 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Fri, 16 Sep 2022 11:33:27 -0700 Subject: gh-95778: Mention sys.set_int_max_str_digits() in error message (GH-96874) When ValueError is raised if an integer is larger than the limit, mention sys.set_int_max_str_digits() in the error message. (cherry picked from commit e841ffc915e82e5ea6e3b473205417d63494808d) Co-authored-by: Victor Stinner --- Doc/library/stdtypes.rst | 4 ++-- .../Core and Builtins/2022-09-16-19-02-40.gh-issue-95778.cJmnst.rst | 3 +++ Objects/longobject.c | 4 ++-- 3 files changed, 7 insertions(+), 4 deletions(-) create mode 100644 Misc/NEWS.d/next/Core and Builtins/2022-09-16-19-02-40.gh-issue-95778.cJmnst.rst diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 84bca3a..14d2a27 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5489,7 +5489,7 @@ When an operation would exceed the limit, a :exc:`ValueError` is raised: >>> _ = int('2' * 5432) Traceback (most recent call last): ... - ValueError: Exceeds the limit (4300) for integer string conversion: value has 5432 digits. + ValueError: Exceeds the limit (4300) for integer string conversion: value has 5432 digits; use sys.set_int_max_str_digits() to increase the limit. >>> i = int('2' * 4300) >>> len(str(i)) 4300 @@ -5497,7 +5497,7 @@ When an operation would exceed the limit, a :exc:`ValueError` is raised: >>> len(str(i_squared)) Traceback (most recent call last): ... - ValueError: Exceeds the limit (4300) for integer string conversion: value has 8599 digits. + ValueError: Exceeds the limit (4300) for integer string conversion: value has 8599 digits; use sys.set_int_max_str_digits() to increase the limit. >>> len(hex(i_squared)) 7144 >>> assert int(hex(i_squared), base=16) == i*i # Hexadecimal is unlimited. diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-09-16-19-02-40.gh-issue-95778.cJmnst.rst b/Misc/NEWS.d/next/Core and Builtins/2022-09-16-19-02-40.gh-issue-95778.cJmnst.rst new file mode 100644 index 0000000..ebf6377 --- /dev/null +++ b/Misc/NEWS.d/next/Core and Builtins/2022-09-16-19-02-40.gh-issue-95778.cJmnst.rst @@ -0,0 +1,3 @@ +When :exc:`ValueError` is raised if an integer is larger than the limit, +mention the :func:`sys.set_int_max_str_digits` function in the error message. +Patch by Victor Stinner. diff --git a/Objects/longobject.c b/Objects/longobject.c index 17274d0..e93461a 100644 --- a/Objects/longobject.c +++ b/Objects/longobject.c @@ -36,8 +36,8 @@ medium_value(PyLongObject *x) #define IS_SMALL_INT(ival) (-_PY_NSMALLNEGINTS <= (ival) && (ival) < _PY_NSMALLPOSINTS) #define IS_SMALL_UINT(ival) ((ival) < _PY_NSMALLPOSINTS) -#define _MAX_STR_DIGITS_ERROR_FMT_TO_INT "Exceeds the limit (%d) for integer string conversion: value has %zd digits" -#define _MAX_STR_DIGITS_ERROR_FMT_TO_STR "Exceeds the limit (%d) for integer string conversion" +#define _MAX_STR_DIGITS_ERROR_FMT_TO_INT "Exceeds the limit (%d) for integer string conversion: value has %zd digits; use sys.set_int_max_str_digits() to increase the limit" +#define _MAX_STR_DIGITS_ERROR_FMT_TO_STR "Exceeds the limit (%d) for integer string conversion; use sys.set_int_max_str_digits() to increase the limit" static inline void _Py_DECREF_INT(PyLongObject *op) -- cgit v0.12 From 9e008fe3519b6c08edc2f2363bc2eb4a4e044698 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 19 Sep 2022 04:48:58 -0700 Subject: gh-96821: Fix undefined behaviour in `_testcapimodule.c` (GH-96915) (GH-96927) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * gh-96821: Assert for demonstrating undefined behaviour * Fix UB (cherry picked from commit cbdeda8ce7a3543cb3376d70e4cd46fcf24f42a7) Co-authored-by: C.A.M. Gerlach Co-authored-by: Matthias Görgens --- .../Core and Builtins/2022-09-18-08-47-40.gh-issue-96821.Co2iOq.rst | 1 + Modules/_testcapimodule.c | 4 +++- 2 files changed, 4 insertions(+), 1 deletion(-) create mode 100644 Misc/NEWS.d/next/Core and Builtins/2022-09-18-08-47-40.gh-issue-96821.Co2iOq.rst diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-09-18-08-47-40.gh-issue-96821.Co2iOq.rst b/Misc/NEWS.d/next/Core and Builtins/2022-09-18-08-47-40.gh-issue-96821.Co2iOq.rst new file mode 100644 index 0000000..4fd0532 --- /dev/null +++ b/Misc/NEWS.d/next/Core and Builtins/2022-09-18-08-47-40.gh-issue-96821.Co2iOq.rst @@ -0,0 +1 @@ +Fix undefined behaviour in ``_testcapimodule.c``. diff --git a/Modules/_testcapimodule.c b/Modules/_testcapimodule.c index 1a3cbe0..43fec81 100644 --- a/Modules/_testcapimodule.c +++ b/Modules/_testcapimodule.c @@ -5576,8 +5576,10 @@ meth_fastcall_keywords(PyObject* self, PyObject* const* args, if (pyargs == NULL) { return NULL; } + assert(args != NULL || nargs == 0); + PyObject* const* args_offset = args == NULL ? NULL : args + nargs; PyObject *pykwargs = PyObject_Vectorcall((PyObject*)&PyDict_Type, - args + nargs, 0, kwargs); + args_offset, 0, kwargs); return Py_BuildValue("NNN", _null_to_none(self), pyargs, pykwargs); } -- cgit v0.12 From 67f5d24e44cd53f23b814a735718cfca36f553c5 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 26 Sep 2022 08:43:26 -0700 Subject: gh-96848: Fix -X int_max_str_digits option parsing (GH-96988) Fix command line parsing: reject "-X int_max_str_digits" option with no value (invalid) when the PYTHONINTMAXSTRDIGITS environment variable is set to a valid limit. (cherry picked from commit 41351662bcd21672d8ccfa62fe44d72027e6bcf8) Co-authored-by: Victor Stinner --- Lib/test/test_cmd_line.py | 2 ++ .../Core and Builtins/2022-09-21-14-38-31.gh-issue-96848.WuoLzU.rst | 3 +++ Python/initconfig.c | 3 ++- 3 files changed, 7 insertions(+), 1 deletion(-) create mode 100644 Misc/NEWS.d/next/Core and Builtins/2022-09-21-14-38-31.gh-issue-96848.WuoLzU.rst diff --git a/Lib/test/test_cmd_line.py b/Lib/test/test_cmd_line.py index 78edd52..1c33be2 100644 --- a/Lib/test/test_cmd_line.py +++ b/Lib/test/test_cmd_line.py @@ -874,6 +874,8 @@ class CmdLineTest(unittest.TestCase): assert_python_failure('-X', 'int_max_str_digits', '-c', code) assert_python_failure('-X', 'int_max_str_digits=foo', '-c', code) assert_python_failure('-X', 'int_max_str_digits=100', '-c', code) + assert_python_failure('-X', 'int_max_str_digits', '-c', code, + PYTHONINTMAXSTRDIGITS='4000') assert_python_failure('-c', code, PYTHONINTMAXSTRDIGITS='foo') assert_python_failure('-c', code, PYTHONINTMAXSTRDIGITS='100') diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-09-21-14-38-31.gh-issue-96848.WuoLzU.rst b/Misc/NEWS.d/next/Core and Builtins/2022-09-21-14-38-31.gh-issue-96848.WuoLzU.rst new file mode 100644 index 0000000..a9b04ce --- /dev/null +++ b/Misc/NEWS.d/next/Core and Builtins/2022-09-21-14-38-31.gh-issue-96848.WuoLzU.rst @@ -0,0 +1,3 @@ +Fix command line parsing: reject :option:`-X int_max_str_digits <-X>` option +with no value (invalid) when the :envvar:`PYTHONINTMAXSTRDIGITS` environment +variable is set to a valid limit. Patch by Victor Stinner. diff --git a/Python/initconfig.c b/Python/initconfig.c index 0ce22e0..0ccca26 100644 --- a/Python/initconfig.c +++ b/Python/initconfig.c @@ -1734,10 +1734,10 @@ static PyStatus config_init_int_max_str_digits(PyConfig *config) { int maxdigits; - int valid = 0; const char *env = config_get_env(config, "PYTHONINTMAXSTRDIGITS"); if (env) { + int valid = 0; if (!_Py_str_to_int(env, &maxdigits)) { valid = ((maxdigits == 0) || (maxdigits >= _PY_LONG_MAX_STR_DIGITS_THRESHOLD)); } @@ -1755,6 +1755,7 @@ config_init_int_max_str_digits(PyConfig *config) const wchar_t *xoption = config_get_xoption(config, L"int_max_str_digits"); if (xoption) { const wchar_t *sep = wcschr(xoption, L'='); + int valid = 0; if (sep) { if (!config_wstr_to_int(sep + 1, &maxdigits)) { valid = ((maxdigits == 0) || (maxdigits >= _PY_LONG_MAX_STR_DIGITS_THRESHOLD)); -- cgit v0.12 From 56145c696323d6fa5c346d6bcf3a7b7ff4410cef Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 22 Sep 2022 09:58:35 -0700 Subject: gh-90155: Fix bug in asyncio.Semaphore and strengthen FIFO guarantee (GH-93222) The main problem was that an unluckily timed task cancellation could cause the semaphore to be stuck. There were also doubts about strict FIFO ordering of tasks allowed to pass. The Semaphore implementation was rewritten to be more similar to Lock. Many tests for edge cases (including cancellation) were added. (cherry picked from commit 24e03796248ab8c7f62d715c28156abe2f1c0d20) Co-authored-by: Cyker Way --- Lib/asyncio/locks.py | 64 ++++++++----- Lib/test/test_asyncio/test_locks.py | 100 +++++++++++++++++++++ .../2022-05-25-15-57-39.gh-issue-90155.YMstB5.rst | 1 + 3 files changed, 143 insertions(+), 22 deletions(-) create mode 100644 Misc/NEWS.d/next/Library/2022-05-25-15-57-39.gh-issue-90155.YMstB5.rst diff --git a/Lib/asyncio/locks.py b/Lib/asyncio/locks.py index e711302..f8f5903 100644 --- a/Lib/asyncio/locks.py +++ b/Lib/asyncio/locks.py @@ -346,9 +346,8 @@ class Semaphore(_ContextManagerMixin, mixins._LoopBoundMixin): def __init__(self, value=1): if value < 0: raise ValueError("Semaphore initial value must be >= 0") + self._waiters = None self._value = value - self._waiters = collections.deque() - self._wakeup_scheduled = False def __repr__(self): res = super().__repr__() @@ -357,16 +356,8 @@ class Semaphore(_ContextManagerMixin, mixins._LoopBoundMixin): extra = f'{extra}, waiters:{len(self._waiters)}' return f'<{res[1:-1]} [{extra}]>' - def _wake_up_next(self): - while self._waiters: - waiter = self._waiters.popleft() - if not waiter.done(): - waiter.set_result(None) - self._wakeup_scheduled = True - return - def locked(self): - """Returns True if semaphore can not be acquired immediately.""" + """Returns True if semaphore counter is zero.""" return self._value == 0 async def acquire(self): @@ -378,28 +369,57 @@ class Semaphore(_ContextManagerMixin, mixins._LoopBoundMixin): called release() to make it larger than 0, and then return True. """ - # _wakeup_scheduled is set if *another* task is scheduled to wakeup - # but its acquire() is not resumed yet - while self._wakeup_scheduled or self._value <= 0: - fut = self._get_loop().create_future() - self._waiters.append(fut) + if (not self.locked() and (self._waiters is None or + all(w.cancelled() for w in self._waiters))): + self._value -= 1 + return True + + if self._waiters is None: + self._waiters = collections.deque() + fut = self._get_loop().create_future() + self._waiters.append(fut) + + # Finally block should be called before the CancelledError + # handling as we don't want CancelledError to call + # _wake_up_first() and attempt to wake up itself. + try: try: await fut - # reset _wakeup_scheduled *after* waiting for a future - self._wakeup_scheduled = False - except exceptions.CancelledError: - self._wake_up_next() - raise + finally: + self._waiters.remove(fut) + except exceptions.CancelledError: + if not self.locked(): + self._wake_up_first() + raise + self._value -= 1 + if not self.locked(): + self._wake_up_first() return True def release(self): """Release a semaphore, incrementing the internal counter by one. + When it was zero on entry and another coroutine is waiting for it to become larger than zero again, wake up that coroutine. """ self._value += 1 - self._wake_up_next() + self._wake_up_first() + + def _wake_up_first(self): + """Wake up the first waiter if it isn't done.""" + if not self._waiters: + return + try: + fut = next(iter(self._waiters)) + except StopIteration: + return + + # .done() necessarily means that a waiter will wake up later on and + # either take the lock, or, if it was cancelled and lock wasn't + # taken already, will hit this again and wake up a new waiter. + if not fut.done(): + fut.set_result(True) class BoundedSemaphore(Semaphore): diff --git a/Lib/test/test_asyncio/test_locks.py b/Lib/test/test_asyncio/test_locks.py index 541b490..4b9d166 100644 --- a/Lib/test/test_asyncio/test_locks.py +++ b/Lib/test/test_asyncio/test_locks.py @@ -5,6 +5,7 @@ from unittest import mock import re import asyncio +import collections STR_RGX_REPR = ( r'^<(?P.*?) object at (?P
.*?)' @@ -774,6 +775,9 @@ class SemaphoreTests(unittest.IsolatedAsyncioTestCase): self.assertTrue('waiters' not in repr(sem)) self.assertTrue(RGX_REPR.match(repr(sem))) + if sem._waiters is None: + sem._waiters = collections.deque() + sem._waiters.append(mock.Mock()) self.assertTrue('waiters:1' in repr(sem)) self.assertTrue(RGX_REPR.match(repr(sem))) @@ -843,6 +847,7 @@ class SemaphoreTests(unittest.IsolatedAsyncioTestCase): self.assertEqual(2, sem._value) await asyncio.sleep(0) + await asyncio.sleep(0) self.assertEqual(0, sem._value) self.assertEqual(3, len(result)) self.assertTrue(sem.locked()) @@ -885,6 +890,7 @@ class SemaphoreTests(unittest.IsolatedAsyncioTestCase): sem.release() await asyncio.sleep(0) + await asyncio.sleep(0) num_done = sum(t.done() for t in [t3, t4]) self.assertEqual(num_done, 1) self.assertTrue(t3.done()) @@ -904,9 +910,32 @@ class SemaphoreTests(unittest.IsolatedAsyncioTestCase): t1.cancel() sem.release() await asyncio.sleep(0) + await asyncio.sleep(0) self.assertTrue(sem.locked()) self.assertTrue(t2.done()) + async def test_acquire_no_hang(self): + + sem = asyncio.Semaphore(1) + + async def c1(): + async with sem: + await asyncio.sleep(0) + t2.cancel() + + async def c2(): + async with sem: + self.assertFalse(True) + + t1 = asyncio.create_task(c1()) + t2 = asyncio.create_task(c2()) + + r1, r2 = await asyncio.gather(t1, t2, return_exceptions=True) + self.assertTrue(r1 is None) + self.assertTrue(isinstance(r2, asyncio.CancelledError)) + + await asyncio.wait_for(sem.acquire(), timeout=1.0) + def test_release_not_acquired(self): sem = asyncio.BoundedSemaphore() @@ -945,6 +974,77 @@ class SemaphoreTests(unittest.IsolatedAsyncioTestCase): result ) + async def test_acquire_fifo_order_2(self): + sem = asyncio.Semaphore(1) + result = [] + + async def c1(result): + await sem.acquire() + result.append(1) + return True + + async def c2(result): + await sem.acquire() + result.append(2) + sem.release() + await sem.acquire() + result.append(4) + return True + + async def c3(result): + await sem.acquire() + result.append(3) + return True + + t1 = asyncio.create_task(c1(result)) + t2 = asyncio.create_task(c2(result)) + t3 = asyncio.create_task(c3(result)) + + await asyncio.sleep(0) + + sem.release() + sem.release() + + tasks = [t1, t2, t3] + await asyncio.gather(*tasks) + self.assertEqual([1, 2, 3, 4], result) + + async def test_acquire_fifo_order_3(self): + sem = asyncio.Semaphore(0) + result = [] + + async def c1(result): + await sem.acquire() + result.append(1) + return True + + async def c2(result): + await sem.acquire() + result.append(2) + return True + + async def c3(result): + await sem.acquire() + result.append(3) + return True + + t1 = asyncio.create_task(c1(result)) + t2 = asyncio.create_task(c2(result)) + t3 = asyncio.create_task(c3(result)) + + await asyncio.sleep(0) + + t1.cancel() + + await asyncio.sleep(0) + + sem.release() + sem.release() + + tasks = [t1, t2, t3] + await asyncio.gather(*tasks, return_exceptions=True) + self.assertEqual([2, 3], result) + class BarrierTests(unittest.IsolatedAsyncioTestCase): diff --git a/Misc/NEWS.d/next/Library/2022-05-25-15-57-39.gh-issue-90155.YMstB5.rst b/Misc/NEWS.d/next/Library/2022-05-25-15-57-39.gh-issue-90155.YMstB5.rst new file mode 100644 index 0000000..8def769 --- /dev/null +++ b/Misc/NEWS.d/next/Library/2022-05-25-15-57-39.gh-issue-90155.YMstB5.rst @@ -0,0 +1 @@ +Fix broken :class:`asyncio.Semaphore` when acquire is cancelled. -- cgit v0.12 From 9c80b55ad69f67e3507c0185e07b98af35dc7239 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 26 Sep 2022 17:00:53 -0700 Subject: gh-97545: Make Semaphore run faster. (GH-97549) (cherry picked from commit 68c46ae68b6e0c36a12e37285fff9ce0782ed01e) Co-authored-by: Cyker Way --- Lib/asyncio/locks.py | 38 ++++++++++------------ Lib/test/test_asyncio/test_locks.py | 3 +- .../2022-09-25-23-24-52.gh-issue-97545.HZLSNt.rst | 1 + 3 files changed, 19 insertions(+), 23 deletions(-) create mode 100644 Misc/NEWS.d/next/Library/2022-09-25-23-24-52.gh-issue-97545.HZLSNt.rst diff --git a/Lib/asyncio/locks.py b/Lib/asyncio/locks.py index f8f5903..fd41dfd 100644 --- a/Lib/asyncio/locks.py +++ b/Lib/asyncio/locks.py @@ -357,8 +357,9 @@ class Semaphore(_ContextManagerMixin, mixins._LoopBoundMixin): return f'<{res[1:-1]} [{extra}]>' def locked(self): - """Returns True if semaphore counter is zero.""" - return self._value == 0 + """Returns True if semaphore cannot be acquired immediately.""" + return self._value == 0 or ( + any(not w.cancelled() for w in (self._waiters or ()))) async def acquire(self): """Acquire a semaphore. @@ -369,8 +370,7 @@ class Semaphore(_ContextManagerMixin, mixins._LoopBoundMixin): called release() to make it larger than 0, and then return True. """ - if (not self.locked() and (self._waiters is None or - all(w.cancelled() for w in self._waiters))): + if not self.locked(): self._value -= 1 return True @@ -388,13 +388,13 @@ class Semaphore(_ContextManagerMixin, mixins._LoopBoundMixin): finally: self._waiters.remove(fut) except exceptions.CancelledError: - if not self.locked(): - self._wake_up_first() + if not fut.cancelled(): + self._value += 1 + self._wake_up_next() raise - self._value -= 1 - if not self.locked(): - self._wake_up_first() + if self._value > 0: + self._wake_up_next() return True def release(self): @@ -404,22 +404,18 @@ class Semaphore(_ContextManagerMixin, mixins._LoopBoundMixin): become larger than zero again, wake up that coroutine. """ self._value += 1 - self._wake_up_first() + self._wake_up_next() - def _wake_up_first(self): - """Wake up the first waiter if it isn't done.""" + def _wake_up_next(self): + """Wake up the first waiter that isn't done.""" if not self._waiters: return - try: - fut = next(iter(self._waiters)) - except StopIteration: - return - # .done() necessarily means that a waiter will wake up later on and - # either take the lock, or, if it was cancelled and lock wasn't - # taken already, will hit this again and wake up a new waiter. - if not fut.done(): - fut.set_result(True) + for fut in self._waiters: + if not fut.done(): + self._value -= 1 + fut.set_result(True) + return class BoundedSemaphore(Semaphore): diff --git a/Lib/test/test_asyncio/test_locks.py b/Lib/test/test_asyncio/test_locks.py index 4b9d166..c20ec94 100644 --- a/Lib/test/test_asyncio/test_locks.py +++ b/Lib/test/test_asyncio/test_locks.py @@ -844,10 +844,9 @@ class SemaphoreTests(unittest.IsolatedAsyncioTestCase): sem.release() sem.release() - self.assertEqual(2, sem._value) + self.assertEqual(0, sem._value) await asyncio.sleep(0) - await asyncio.sleep(0) self.assertEqual(0, sem._value) self.assertEqual(3, len(result)) self.assertTrue(sem.locked()) diff --git a/Misc/NEWS.d/next/Library/2022-09-25-23-24-52.gh-issue-97545.HZLSNt.rst b/Misc/NEWS.d/next/Library/2022-09-25-23-24-52.gh-issue-97545.HZLSNt.rst new file mode 100644 index 0000000..a53902e --- /dev/null +++ b/Misc/NEWS.d/next/Library/2022-09-25-23-24-52.gh-issue-97545.HZLSNt.rst @@ -0,0 +1 @@ +Make Semaphore run faster. -- cgit v0.12 From 38ade0d2aca25748207189b17323874cad183f78 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Wed, 28 Sep 2022 15:28:38 -0700 Subject: gh-97616: list_resize() checks for integer overflow (GH-97617) Fix multiplying a list by an integer (list *= int): detect the integer overflow when the new allocated length is close to the maximum size. Issue reported by Jordan Limor. list_resize() now checks for integer overflow before multiplying the new allocated length by the list item size (sizeof(PyObject*)). (cherry picked from commit a5f092f3c469b674b8d9ccbd4e4377230c9ac7cf) Co-authored-by: Victor Stinner --- Lib/test/test_list.py | 13 +++++++++++++ .../Security/2022-09-28-17-09-37.gh-issue-97616.K1e3Xs.rst | 3 +++ Objects/listobject.c | 10 ++++++++-- 3 files changed, 24 insertions(+), 2 deletions(-) create mode 100644 Misc/NEWS.d/next/Security/2022-09-28-17-09-37.gh-issue-97616.K1e3Xs.rst diff --git a/Lib/test/test_list.py b/Lib/test/test_list.py index d3da05b..9aa6dd1 100644 --- a/Lib/test/test_list.py +++ b/Lib/test/test_list.py @@ -96,6 +96,19 @@ class ListTest(list_tests.CommonTest): self.assertRaises((MemoryError, OverflowError), mul, lst, n) self.assertRaises((MemoryError, OverflowError), imul, lst, n) + def test_list_resize_overflow(self): + # gh-97616: test new_allocated * sizeof(PyObject*) overflow + # check in list_resize() + lst = [0] * 65 + del lst[1:] + self.assertEqual(len(lst), 1) + + size = ((2 ** (tuple.__itemsize__ * 8) - 1) // 2) + with self.assertRaises((MemoryError, OverflowError)): + lst * size + with self.assertRaises((MemoryError, OverflowError)): + lst *= size + def test_repr_large(self): # Check the repr of large list objects def check(n): diff --git a/Misc/NEWS.d/next/Security/2022-09-28-17-09-37.gh-issue-97616.K1e3Xs.rst b/Misc/NEWS.d/next/Security/2022-09-28-17-09-37.gh-issue-97616.K1e3Xs.rst new file mode 100644 index 0000000..721427f --- /dev/null +++ b/Misc/NEWS.d/next/Security/2022-09-28-17-09-37.gh-issue-97616.K1e3Xs.rst @@ -0,0 +1,3 @@ +Fix multiplying a list by an integer (``list *= int``): detect the integer +overflow when the new allocated length is close to the maximum size. Issue +reported by Jordan Limor. Patch by Victor Stinner. diff --git a/Objects/listobject.c b/Objects/listobject.c index 8e3d02a..1900913 100644 --- a/Objects/listobject.c +++ b/Objects/listobject.c @@ -76,8 +76,14 @@ list_resize(PyListObject *self, Py_ssize_t newsize) if (newsize == 0) new_allocated = 0; - num_allocated_bytes = new_allocated * sizeof(PyObject *); - items = (PyObject **)PyMem_Realloc(self->ob_item, num_allocated_bytes); + if (new_allocated <= (size_t)PY_SSIZE_T_MAX / sizeof(PyObject *)) { + num_allocated_bytes = new_allocated * sizeof(PyObject *); + items = (PyObject **)PyMem_Realloc(self->ob_item, num_allocated_bytes); + } + else { + // integer overflow + items = NULL; + } if (items == NULL) { PyErr_NoMemory(); return -1; -- cgit v0.12 From a1f4e42619e3dede9f465d8ee691e04e5eb30026 Mon Sep 17 00:00:00 2001 From: Steve Dower Date: Fri, 30 Sep 2022 13:48:19 +0100 Subject: gh-90989: Clarify some installer text (GH-97668) --- .../Windows/2022-09-29-23-08-49.gh-issue-90989.no89Q2.rst | 1 + Tools/msi/bundle/Default.wxl | 12 ++++++------ 2 files changed, 7 insertions(+), 6 deletions(-) create mode 100644 Misc/NEWS.d/next/Windows/2022-09-29-23-08-49.gh-issue-90989.no89Q2.rst diff --git a/Misc/NEWS.d/next/Windows/2022-09-29-23-08-49.gh-issue-90989.no89Q2.rst b/Misc/NEWS.d/next/Windows/2022-09-29-23-08-49.gh-issue-90989.no89Q2.rst new file mode 100644 index 0000000..34fffdf --- /dev/null +++ b/Misc/NEWS.d/next/Windows/2022-09-29-23-08-49.gh-issue-90989.no89Q2.rst @@ -0,0 +1 @@ +Clarify some text in the Windows installer. diff --git a/Tools/msi/bundle/Default.wxl b/Tools/msi/bundle/Default.wxl index 2eddd1f..d65dd83 100644 --- a/Tools/msi/bundle/Default.wxl +++ b/Tools/msi/bundle/Default.wxl @@ -79,15 +79,15 @@ Select Customize to review current options. Use Programs and Features to remove the 'py' launcher. Upgrades the global 'py' launcher from the previous version. - Associate &files with Python (requires the py launcher) + Associate &files with Python (requires the 'py' launcher) Create shortcuts for installed applications Add Python to &environment variables - Add &Python [ShortVersion] to PATH + Add &python.exe to PATH Append Python to &environment variables - Append &Python [ShortVersion] to PATH - Install for &all users - for &all users (requires elevation) - Install &launcher for all users (recommended) + Append &python.exe to PATH + Install Python [ShortVersion] for &all users + for &all users (requires admin privileges) + Use admin privi&leges when installing py.exe &Precompile standard library Download debugging &symbols Download debu&g binaries (requires VS 2017 or later) -- cgit v0.12 From 965ce0d8f103364b9e8a9e22314b9316b961e3a0 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Fri, 21 Oct 2022 07:52:17 -0700 Subject: gh-95027: Fix regrtest stdout encoding on Windows (GH-98492) On Windows, when the Python test suite is run with the -jN option, the ANSI code page is now used as the encoding for the stdout temporary file, rather than using UTF-8 which can lead to decoding errors. (cherry picked from commit ec1f6f5f139868dc2c1116a7c7c878c38c668d53) Co-authored-by: Victor Stinner --- Lib/test/libregrtest/runtest_mp.py | 14 +++++++++++--- .../Tests/2022-10-20-17-49-50.gh-issue-95027.viRpJB.rst | 4 ++++ 2 files changed, 15 insertions(+), 3 deletions(-) create mode 100644 Misc/NEWS.d/next/Tests/2022-10-20-17-49-50.gh-issue-95027.viRpJB.rst diff --git a/Lib/test/libregrtest/runtest_mp.py b/Lib/test/libregrtest/runtest_mp.py index 13649ce..c6a4dae 100644 --- a/Lib/test/libregrtest/runtest_mp.py +++ b/Lib/test/libregrtest/runtest_mp.py @@ -21,6 +21,9 @@ from test.libregrtest.runtest import ( from test.libregrtest.setup import setup_tests from test.libregrtest.utils import format_duration, print_warning +if sys.platform == 'win32': + import locale + # Display the running tests if nothing happened last N seconds PROGRESS_UPDATE = 30.0 # seconds @@ -259,11 +262,16 @@ class TestWorkerProcess(threading.Thread): self.current_test_name = None def _runtest(self, test_name: str) -> MultiprocessResult: + if sys.platform == 'win32': + # gh-95027: When stdout is not a TTY, Python uses the ANSI code + # page for the sys.stdout encoding. If the main process runs in a + # terminal, sys.stdout uses WindowsConsoleIO with UTF-8 encoding. + encoding = locale.getencoding() + else: + encoding = sys.stdout.encoding # gh-94026: Write stdout+stderr to a tempfile as workaround for # non-blocking pipes on Emscripten with NodeJS. - with tempfile.TemporaryFile( - 'w+', encoding=sys.stdout.encoding - ) as stdout_fh: + with tempfile.TemporaryFile('w+', encoding=encoding) as stdout_fh: # gh-93353: Check for leaked temporary files in the parent process, # since the deletion of temporary files can happen late during # Python finalization: too late for libregrtest. diff --git a/Misc/NEWS.d/next/Tests/2022-10-20-17-49-50.gh-issue-95027.viRpJB.rst b/Misc/NEWS.d/next/Tests/2022-10-20-17-49-50.gh-issue-95027.viRpJB.rst new file mode 100644 index 0000000..8bf1a9d --- /dev/null +++ b/Misc/NEWS.d/next/Tests/2022-10-20-17-49-50.gh-issue-95027.viRpJB.rst @@ -0,0 +1,4 @@ +On Windows, when the Python test suite is run with the ``-jN`` option, the +ANSI code page is now used as the encoding for the stdout temporary file, +rather than using UTF-8 which can lead to decoding errors. Patch by Victor +Stinner. -- cgit v0.12 From c2cb04ed9df08cd21d22867ba6a14cdd54765d6d Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 24 Oct 2022 05:41:42 -0700 Subject: gh-95913 Add string section to Whatsnew with new Template methods (GH-98311) (cherry picked from commit e2dc223004a4230a9f820d2ff617770719a42cc6) Co-authored-by: C.A.M. Gerlach --- Doc/whatsnew/3.11.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index c143a41..710b6c8 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -949,6 +949,18 @@ sqlite3 (Contributed by Aviv Palivoda and Erlend E. Aasland in :issue:`24905`.) +.. _whatsnew311-string: + +string +------ + +* Add :meth:`~string.Template.get_identifiers` + and :meth:`~string.Template.is_valid` to :class:`string.Template`, + which respectively return all valid placeholders, + and whether any invalid placeholders are present. + (Contributed by Ben Kehoe in :gh:`90465`.) + + sys --- -- cgit v0.12 From 7cdea80d3bbf3f9bdff6724859c0ffb142d30b9b Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 24 Oct 2022 05:41:07 -0700 Subject: gh-95913: Edit, xref & sort 3.11 WhatsNew Removed section (GH-98584) (cherry picked from commit 8dbec4dbe57df30ec930c3035f86f8896764bc99) Co-authored-by: C.A.M. Gerlach --- Doc/whatsnew/3.11.rst | 119 ++++++++++++++++++++++++++------------------------ 1 file changed, 61 insertions(+), 58 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 710b6c8..a0622d3 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -1734,95 +1734,98 @@ This section lists Python APIs that have been removed in Python 3.12. Removed C APIs are :ref:`listed separately `. -* :class:`smtpd.MailmanProxy` is now removed as it is unusable without - an external module, ``mailman``. (Contributed by Dong-hee Na in :issue:`35800`.) +* Removed the :func:`!@asyncio.coroutine` :term:`decorator` + enabling legacy generator-based coroutines to be compatible with + :keyword:`async` / :keyword:`await` code. + The function has been deprecated since Python 3.8 and the removal was + initially scheduled for Python 3.10. Use :keyword:`async def` instead. + (Contributed by Illia Volochii in :issue:`43216`.) + +* Removed :class:`!asyncio.coroutines.CoroWrapper` used for wrapping legacy + generator-based coroutine objects in the debug mode. + (Contributed by Illia Volochii in :issue:`43216`.) + +* Due to significant security concerns, the *reuse_address* parameter of + :meth:`asyncio.loop.create_datagram_endpoint`, disabled in Python 3.9, is + now entirely removed. This is because of the behavior of the socket option + ``SO_REUSEADDR`` in UDP. + (Contributed by Hugo van Kemenade in :issue:`45129`.) -* The ``binhex`` module, deprecated in Python 3.9, is now removed. - The following :mod:`binascii` functions, deprecated in Python 3.9, are now - also removed: +* Removed the :mod:`!binhex` module, deprecated in Python 3.9. + Also removed the related, similarly-deprecated :mod:`binascii` functions: - * ``a2b_hqx()``, ``b2a_hqx()``; - * ``rlecode_hqx()``, ``rledecode_hqx()``. + * :func:`!binascii.a2b_hqx` + * :func:`!binascii.b2a_hqx` + * :func:`!binascii.rlecode_hqx` + * :func:`!binascii.rldecode_hqx` The :func:`binascii.crc_hqx` function remains available. (Contributed by Victor Stinner in :issue:`45085`.) -* The distutils ``bdist_msi`` command, deprecated in Python 3.9, is now removed. +* Removed the :mod:`distutils` ``bdist_msi`` command deprecated in Python 3.9. Use ``bdist_wheel`` (wheel packages) instead. (Contributed by Hugo van Kemenade in :issue:`45124`.) -* Due to significant security concerns, the *reuse_address* parameter of - :meth:`asyncio.loop.create_datagram_endpoint`, disabled in Python 3.9, is - now entirely removed. This is because of the behavior of the socket option - ``SO_REUSEADDR`` in UDP. - (Contributed by Hugo van Kemenade in :issue:`45129`.) - -* Removed :meth:`__getitem__` methods of +* Removed the :meth:`~object.__getitem__` methods of :class:`xml.dom.pulldom.DOMEventStream`, :class:`wsgiref.util.FileWrapper` and :class:`fileinput.FileInput`, deprecated since Python 3.9. (Contributed by Hugo van Kemenade in :issue:`45132`.) -* The following deprecated functions and methods are removed in the :mod:`gettext` - module: :func:`~gettext.lgettext`, :func:`~gettext.ldgettext`, - :func:`~gettext.lngettext` and :func:`~gettext.ldngettext`. - - Function :func:`~gettext.bind_textdomain_codeset`, methods - :meth:`~gettext.NullTranslations.output_charset` and - :meth:`~gettext.NullTranslations.set_output_charset`, and the *codeset* - parameter of functions :func:`~gettext.translation` and - :func:`~gettext.install` are also removed, since they are only used for - the ``l*gettext()`` functions. +* Removed the deprecated :mod:`gettext` functions + :func:`!lgettext`, :func:`!ldgettext`, + :func:`!lngettext` and :func:`!ldngettext`. + Also removed the :func:`!bind_textdomain_codeset` function, + the :meth:`!NullTranslations.output_charset` and + :meth:`!NullTranslations.set_output_charset` methods, + and the *codeset* parameter of :func:`!translation` and :func:`!install`, + since they are only used for the :func:`!l*gettext` functions. (Contributed by Dong-hee Na and Serhiy Storchaka in :issue:`44235`.) -* The :func:`@asyncio.coroutine ` :term:`decorator` enabling - legacy generator-based coroutines to be compatible with async/await code. - The function has been deprecated since Python 3.8 and the removal was - initially scheduled for Python 3.10. Use :keyword:`async def` instead. - (Contributed by Illia Volochii in :issue:`43216`.) - -* :class:`asyncio.coroutines.CoroWrapper` used for wrapping legacy - generator-based coroutine objects in the debug mode. - (Contributed by Illia Volochii in :issue:`43216`.) - -* Removed the deprecated ``split()`` method of :class:`_tkinter.TkappType`. - (Contributed by Erlend E. Aasland in :issue:`38371`.) - * Removed from the :mod:`inspect` module: - * the ``getargspec`` function, deprecated since Python 3.0; + * The :func:`!getargspec` function, deprecated since Python 3.0; use :func:`inspect.signature` or :func:`inspect.getfullargspec` instead. - * the ``formatargspec`` function, deprecated since Python 3.5; - use the :func:`inspect.signature` function and :class:`Signature` object - directly. + * The :func:`!formatargspec` function, deprecated since Python 3.5; + use the :func:`inspect.signature` function + or the :class:`inspect.Signature` object directly. - * the undocumented ``Signature.from_builtin`` and ``Signature.from_function`` - functions, deprecated since Python 3.5; use the - :meth:`Signature.from_callable() ` method - instead. + * The undocumented :meth:`!Signature.from_builtin` + and :meth:`!Signature.from_function` methods, deprecated since Python 3.5; + use the :meth:`Signature.from_callable() ` + method instead. (Contributed by Hugo van Kemenade in :issue:`45320`.) -* Remove namespace package support from unittest discovery. It was introduced in - Python 3.4 but has been broken since Python 3.7. - (Contributed by Inada Naoki in :issue:`23882`.) - -* Remove ``__class_getitem__`` method from :class:`pathlib.PurePath`, +* Removed the :meth:`~object.__class_getitem__` method + from :class:`pathlib.PurePath`, because it was not used and added by mistake in previous versions. (Contributed by Nikita Sobolev in :issue:`46483`.) -* Remove the undocumented private ``float.__set_format__()`` method, previously - known as ``float.__setformat__()`` in Python 3.7. Its docstring said: "You - probably don't want to use this function. It exists mainly to be used in - Python's test suite." +* Removed the :class:`!MailmanProxy` class in the :mod:`smtpd` module, + as it is unusable without the external :mod:`!mailman` package. + (Contributed by Dong-hee Na in :issue:`35800`.) + +* Removed the deprecated :meth:`!split` method of :class:`!_tkinter.TkappType`. + (Contributed by Erlend E. Aasland in :issue:`38371`.) + +* Removed namespace package support from :mod:`unittest` discovery. + It was introduced in Python 3.4 but has been broken since Python 3.7. + (Contributed by Inada Naoki in :issue:`23882`.) + +* Removed the undocumented private :meth:`!float.__set_format__()` method, + previously known as :meth:`!float.__setformat__()` in Python 3.7. + Its docstring said: "You probably don't want to use this function. + It exists mainly to be used in Python's test suite." (Contributed by Victor Stinner in :issue:`46852`.) -* The ``--experimental-isolated-subinterpreters`` configure flag - (and corresponding ``EXPERIMENTAL_ISOLATED_SUBINTERPRETERS``) +* The :option:`!--experimental-isolated-subinterpreters` configure flag + (and corresponding :c:macro:`!EXPERIMENTAL_ISOLATED_SUBINTERPRETERS` macro) have been removed. -* Pynche --- The Pythonically Natural Color and Hue Editor --- has been moved out +* `Pynche `_ + --- The Pythonically Natural Color and Hue Editor --- has been moved out of ``Tools/scripts`` and is `being developed independently `_ from the Python source tree. -- cgit v0.12 From cde4cf9de4143f3797d540ade64b08768458917a Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 24 Oct 2022 05:41:00 -0700 Subject: gh-95913: Edit, sort & expand 3.11 WhatsNew Porting section (GH-98585) (cherry picked from commit 43bef54a32feef1eb6a4d63f00f89e2c5a39abd1) Co-authored-by: C.A.M. Gerlach --- Doc/whatsnew/3.11.rst | 61 ++++++++++++++++++++++++++------------------------- 1 file changed, 31 insertions(+), 30 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index a0622d3..d8e8764 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -1842,22 +1842,23 @@ in the Python API that may require changes to your Python code. Porting notes for the C API are :ref:`listed separately `. -* Prohibited passing non-:class:`concurrent.futures.ThreadPoolExecutor` - executors to :meth:`loop.set_default_executor` following a deprecation in - Python 3.8. - (Contributed by Illia Volochii in :issue:`43234`.) - * :func:`open`, :func:`io.open`, :func:`codecs.open` and :class:`fileinput.FileInput` no longer accept ``'U'`` ("universal newline") - in the file mode. This flag was deprecated since Python 3.3. In Python 3, the - "universal newline" is used by default when a file is open in text mode. The - :ref:`newline parameter ` of :func:`open` controls - how universal newlines works. + in the file mode. In Python 3, "universal newline" mode is used by default + whenever a file is opened in text mode, + and the ``'U'`` flag has been deprecated since Python 3.3. + The :ref:`newline parameter ` + to these functions controls how universal newlines work. (Contributed by Victor Stinner in :issue:`37330`.) -* The :mod:`pdb` module now reads the :file:`.pdbrc` configuration file with - the ``'utf-8'`` encoding. - (Contributed by Srinivas Reddy Thatiparthy (శ్రీనివాస్ రెడ్డి తాటిపర్తి) in :issue:`41137`.) +* :class:`ast.AST` node positions are now validated when provided to + :func:`compile` and other related functions. If invalid positions are detected, + a :exc:`ValueError` will be raised. (Contributed by Pablo Galindo in :gh:`93351`) + +* Prohibited passing non-:class:`concurrent.futures.ThreadPoolExecutor` + executors to :meth:`asyncio.loop.set_default_executor` + following a deprecation in Python 3.8. + (Contributed by Illia Volochii in :issue:`43234`.) * :mod:`calendar`: The :class:`calendar.LocaleTextCalendar` and :class:`calendar.LocaleHTMLCalendar` classes now use @@ -1865,29 +1866,29 @@ Porting notes for the C API are if no locale is specified. (Contributed by Victor Stinner in :issue:`46659`.) -* Global inline flags (e.g. ``(?i)``) can now only be used at the start of - the regular expressions. Using them not at the start of expression was - deprecated since Python 3.6. - (Contributed by Serhiy Storchaka in :issue:`47066`.) - -* :mod:`re` module: Fix a few long-standing bugs where, in rare cases, - capturing group could get wrong result. So the result may be different than - before. - (Contributed by Ma Lin in :issue:`35859`.) +* The :mod:`pdb` module now reads the :file:`.pdbrc` configuration file with + the ``'UTF-8'`` encoding. + (Contributed by Srinivas Reddy Thatiparthy (శ్రీనివాస్ రెడ్డి తాటిపర్తి) in :issue:`41137`.) -* The *population* parameter of :func:`random.sample` must be a sequence. - Automatic conversion of sets to lists is no longer supported. If the sample size +* The *population* parameter of :func:`random.sample` must be a sequence, + and automatic conversion of :class:`set`\s to :class:`list`\s + is no longer supported. Also, if the sample size is larger than the population size, a :exc:`ValueError` is raised. (Contributed by Raymond Hettinger in :issue:`40465`.) -* :class:`ast.AST` node positions are now validated when provided to - :func:`compile` and other related functions. If invalid positions are detected, - a :exc:`ValueError` will be raised. (Contributed by Pablo Galindo in :gh:`93351`) +* The *random* optional parameter of :func:`random.shuffle` was removed. + It was previously an arbitrary random function to use for the shuffle; + now, :func:`random.random` (its previous default) will always be used. -* :c:member:`~PyTypeObject.tp_dictoffset` should be treated as write-only. - It can be set to describe C extension clases to the VM, but should be regarded - as meaningless when read. To get the pointer to the object's dictionary call - :c:func:`PyObject_GenericGetDict` instead. +* In :mod:`re` :ref:`re-syntax`, global inline flags (e.g. ``(?i)``) + can now only be used at the start of regular expressions. + Using them elsewhere has been deprecated since Python 3.6. + (Contributed by Serhiy Storchaka in :issue:`47066`.) + +* In the :mod:`re` module, several long-standing bugs where fixed that, + in rare cases, could cause capture groups to get the wrong result. + Therefore, this could change the captured output in these cases. + (Contributed by Ma Lin in :issue:`35859`.) .. _whatsnew311-build-changes: -- cgit v0.12 From c184c6750e40ca4ffa4f62a5d145b892cbd066bc Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 24 Oct 2022 05:41:47 -0700 Subject: gh-95913: Edit, link and sort 3.11 WhatsNew Build section (GH-98588) (cherry picked from commit e81fad6b8a2334903fac5799b43997623a2ed904) Co-authored-by: C.A.M. Gerlach --- Doc/whatsnew/3.11.rst | 124 +++++++++++++++++++++++++++----------------------- 1 file changed, 67 insertions(+), 57 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index d8e8764..8f3ef3f 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -1896,31 +1896,66 @@ Porting notes for the C API are Build Changes ============= -* Building Python now requires a C11 compiler. Optional C11 features are not - required. - (Contributed by Victor Stinner in :issue:`46656`.) - -* Building Python now requires support of IEEE 754 floating point numbers. - (Contributed by Victor Stinner in :issue:`46917`.) +* CPython now has :pep:`11` :pep:`Tier 3 support <11#tier-3>` for + cross compiling to the `WebAssembly `_ platforms + `Emscripten `_ + (``wasm32-unknown-emscripten``, i.e. Python in the browser) + and `WebAssembly System Interface (WASI) `_ + (``wasm32-unknown-wasi``). + The effort is inspired by previous work like `Pyodide `_. + These platforms provide a limited subset of POSIX APIs; Python standard + libraries features and modules related to networking, processes, threading, + signals, mmap, and users/groups are not available or don't work. + (Emscripten contributed by Christian Heimes and Ethan Smith in :gh:`84461` + and WASI contributed by Christian Heimes in :gh:`90473`; + platforms promoted in :gh:`95085`) + +* Building Python now requires: + + * A `C11 `_ compiler. + `Optional C11 features + `_ + are not required. + (Contributed by Victor Stinner in :issue:`46656`.) + + * Support for `IEEE 754 `_ + floating point numbers. + (Contributed by Victor Stinner in :issue:`46917`.) + + * Support for `floating point Not-a-Number (NaN) + `_, + as the :c:macro:`!Py_NO_NAN` macro has been removed. + (Contributed by Victor Stinner in :issue:`46656`.) + + * A `C99 `_ + ```` header file providing the + :c:func:`!copysign`, :c:func:`!hypot`, :c:func:`!isfinite`, + :c:func:`!isinf`, :c:func:`!isnan`, and :c:func:`!round` functions + (contributed by Victor Stinner in :issue:`45440`); + and a :c:data:`!NAN` constant or the :c:func:`!__builtin_nan` function + (Contributed by Victor Stinner in :issue:`46640`). + +* The :mod:`tkinter` package now requires `Tcl/Tk `_ + version 8.5.12 or newer. + (Contributed by Serhiy Storchaka in :issue:`46996`.) -* CPython can now be built with the ThinLTO option via ``--with-lto=thin``. - (Contributed by Dong-hee Na and Brett Holman in :issue:`44340`.) +* Build dependencies, compiler flags, and linker flags for most stdlib + extension modules are now detected by :program:`configure`. libffi, libnsl, + libsqlite3, zlib, bzip2, liblzma, libcrypt, Tcl/Tk, and uuid flags + are detected by `pkg-config + `_ (when available). + :mod:`tkinter` now requires a pkg-config command + to detect development settings for `Tcl/Tk`_ headers and libraries. + (Contributed by Christian Heimes and Erlend Egeberg Aasland in + :issue:`45847`, :issue:`45747`, and :issue:`45763`.) * libpython is no longer linked against libcrypt. (Contributed by Mike Gilbert in :issue:`45433`.) -* Building Python now requires a C99 ```` header file providing - the following functions: ``copysign()``, ``hypot()``, ``isfinite()``, - ``isinf()``, ``isnan()``, ``round()``. - (Contributed by Victor Stinner in :issue:`45440`.) - -* Building Python now requires a C99 ```` header file providing - a ``NAN`` constant, or the ``__builtin_nan()`` built-in function. - (Contributed by Victor Stinner in :issue:`46640`.) - -* Building Python now requires support for floating point Not-a-Number (NaN): - remove the ``Py_NO_NAN`` macro. - (Contributed by Victor Stinner in :issue:`46656`.) +* CPython can now be built with the + `ThinLTO `_ option + via passing ``thin`` to :option:`--with-lto`, i.e. ``--with-lto=thin``. + (Contributed by Dong-hee Na and Brett Holman in :issue:`44340`.) * Freelists for object structs can now be disabled. A new :program:`configure` option :option:`!--without-freelists` can be used to disable all freelists @@ -1929,55 +1964,30 @@ Build Changes * ``Modules/Setup`` and ``Modules/makesetup`` have been improved and tied up. Extension modules can now be built through ``makesetup``. All except some - test modules can be linked statically into main binary or library. + test modules can be linked statically into a main binary or library. (Contributed by Brett Cannon and Christian Heimes in :issue:`45548`, :issue:`45570`, :issue:`45571`, and :issue:`43974`.) -* Build dependencies, compiler flags, and linker flags for most stdlib - extension modules are now detected by :program:`configure`. libffi, libnsl, - libsqlite3, zlib, bzip2, liblzma, libcrypt, Tcl/Tk, and uuid flags - are detected by ``pkg-config`` (when available). :mod:`tkinter` now - requires ``pkg-config`` command to detect development settings for Tcl/Tk - headers and libraries. - (Contributed by Christian Heimes and Erlend Egeberg Aasland in - :issue:`45847`, :issue:`45747`, and :issue:`45763`.) - .. note:: - Use the environment variables :envvar:`TCLTK_CFLAGS` and - :envvar:`TCLTK_LIBS` to manually specify the location of Tcl/Tk headers - and libraries. The :program:`configure` options ``--with-tcltk-includes`` - and ``--with-tcltk-libs`` have been removed. + Use the environment variables :envvar:`!TCLTK_CFLAGS` and + :envvar:`!TCLTK_LIBS` to manually specify the location of Tcl/Tk headers + and libraries. The :program:`configure` options + :option:`!--with-tcltk-includes` and :option:`!--with-tcltk-libs` + have been removed. On RHEL 7 and CentOS 7 the development packages do not provide ``tcl.pc`` - and ``tk.pc``, use :envvar:`TCLTK_LIBS="-ltk8.5 -ltkstub8.5 -ltcl8.5"`. + and ``tk.pc``; use ``TCLTK_LIBS="-ltk8.5 -ltkstub8.5 -ltcl8.5"``. The directory ``Misc/rhel7`` contains ``.pc`` files and instructions - how to build Python with RHEL 7's and CentOS 7's Tcl/Tk and OpenSSL. - -* CPython now has :pep:`11` tier 3 support for cross compiling to WebAssembly - platform ``wasm32-unknown-emscripten`` (Python in the browser). The effort - is inspired by previous work like `Pyodide `_. - Emscripten provides a limited subset of POSIX APIs. Python standard - libraries features and modules related to networking, processes, threading, - signals, mmap, and users/groups are not available or don't work. - (Contributed by Christian Heimes and Ethan Smith in :gh:`84461`, - promoted in :gh:`95085`) - -* CPython now has :pep:`11` tier 3 support for cross compiling to WebAssembly - platform ``wasm32-unknown-wasi`` (WebAssembly System Interface). Like on - Emscripten, only a subset of Python's standard library is available on WASI. - (Contributed by Christian Heimes in :gh:`90473`, promoted in :gh:`95085`) + on how to build Python with RHEL 7's and CentOS 7's Tcl/Tk and OpenSSL. * CPython will now use 30-bit digits by default for the Python :class:`int` implementation. Previously, the default was to use 30-bit digits on platforms with ``SIZEOF_VOID_P >= 8``, and 15-bit digits otherwise. It's still possible to explicitly request use of 15-bit digits via either the - ``--enable-big-digits`` option to the configure script or (for Windows) the - ``PYLONG_BITS_IN_DIGIT`` variable in ``PC/pyconfig.h``, but this option may - be removed at some point in the future. (Contributed by Mark Dickinson in - :issue:`45569`.) - -* The :mod:`tkinter` package now requires Tcl/Tk version 8.5.12 or newer. - (Contributed by Serhiy Storchaka in :issue:`46996`.) + :option:`--enable-big-digits` option to the configure script + or (for Windows) the ``PYLONG_BITS_IN_DIGIT`` variable in ``PC/pyconfig.h``, + but this option may be removed at some point in the future. + (Contributed by Mark Dickinson in :issue:`45569`.) .. _whatsnew311-c-api: -- cgit v0.12 From f0083923faa1759e4770cf03bd45312fea6df729 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sat, 1 Oct 2022 11:10:04 -0700 Subject: gh-90908: Document asyncio.Task.cancelling() and asyncio.Task.uncancel() (GH-95253) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Thomas Grainger (cherry picked from commit f00645d5dbf4cfa0b8f382c8977724578dff191d) Co-authored-by: Łukasz Langa --- Doc/library/asyncio-task.rst | 202 +++++++++++++++++++++++------------- Lib/asyncio/tasks.py | 4 +- Lib/test/test_asyncio/test_tasks.py | 128 ++++++++++++++++++++++- 3 files changed, 254 insertions(+), 80 deletions(-) diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 27054d7..eb42301 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -294,11 +294,13 @@ perform clean-up logic. In case :exc:`asyncio.CancelledError` is explicitly caught, it should generally be propagated when clean-up is complete. Most code can safely ignore :exc:`asyncio.CancelledError`. -Important asyncio components, like :class:`asyncio.TaskGroup` and the -:func:`asyncio.timeout` context manager, are implemented using cancellation -internally and might misbehave if a coroutine swallows -:exc:`asyncio.CancelledError`. +The asyncio components that enable structured concurrency, like +:class:`asyncio.TaskGroup` and :func:`asyncio.timeout`, +are implemented using cancellation internally and might misbehave if +a coroutine swallows :exc:`asyncio.CancelledError`. Similarly, user code +should not call :meth:`uncancel `. +.. _taskgroups: Task Groups =========== @@ -1003,76 +1005,6 @@ Task Object Deprecation warning is emitted if *loop* is not specified and there is no running event loop. - .. method:: cancel(msg=None) - - Request the Task to be cancelled. - - This arranges for a :exc:`CancelledError` exception to be thrown - into the wrapped coroutine on the next cycle of the event loop. - - The coroutine then has a chance to clean up or even deny the - request by suppressing the exception with a :keyword:`try` ... - ... ``except CancelledError`` ... :keyword:`finally` block. - Therefore, unlike :meth:`Future.cancel`, :meth:`Task.cancel` does - not guarantee that the Task will be cancelled, although - suppressing cancellation completely is not common and is actively - discouraged. - - .. versionchanged:: 3.9 - Added the *msg* parameter. - - .. deprecated-removed:: 3.11 3.14 - *msg* parameter is ambiguous when multiple :meth:`cancel` - are called with different cancellation messages. - The argument will be removed. - - .. _asyncio_example_task_cancel: - - The following example illustrates how coroutines can intercept - the cancellation request:: - - async def cancel_me(): - print('cancel_me(): before sleep') - - try: - # Wait for 1 hour - await asyncio.sleep(3600) - except asyncio.CancelledError: - print('cancel_me(): cancel sleep') - raise - finally: - print('cancel_me(): after sleep') - - async def main(): - # Create a "cancel_me" Task - task = asyncio.create_task(cancel_me()) - - # Wait for 1 second - await asyncio.sleep(1) - - task.cancel() - try: - await task - except asyncio.CancelledError: - print("main(): cancel_me is cancelled now") - - asyncio.run(main()) - - # Expected output: - # - # cancel_me(): before sleep - # cancel_me(): cancel sleep - # cancel_me(): after sleep - # main(): cancel_me is cancelled now - - .. method:: cancelled() - - Return ``True`` if the Task is *cancelled*. - - The Task is *cancelled* when the cancellation was requested with - :meth:`cancel` and the wrapped coroutine propagated the - :exc:`CancelledError` exception thrown into it. - .. method:: done() Return ``True`` if the Task is *done*. @@ -1186,3 +1118,125 @@ Task Object in the :func:`repr` output of a task object. .. versionadded:: 3.8 + + .. method:: cancel(msg=None) + + Request the Task to be cancelled. + + This arranges for a :exc:`CancelledError` exception to be thrown + into the wrapped coroutine on the next cycle of the event loop. + + The coroutine then has a chance to clean up or even deny the + request by suppressing the exception with a :keyword:`try` ... + ... ``except CancelledError`` ... :keyword:`finally` block. + Therefore, unlike :meth:`Future.cancel`, :meth:`Task.cancel` does + not guarantee that the Task will be cancelled, although + suppressing cancellation completely is not common and is actively + discouraged. + + .. versionchanged:: 3.9 + Added the *msg* parameter. + + .. deprecated-removed:: 3.11 3.14 + *msg* parameter is ambiguous when multiple :meth:`cancel` + are called with different cancellation messages. + The argument will be removed. + + .. _asyncio_example_task_cancel: + + The following example illustrates how coroutines can intercept + the cancellation request:: + + async def cancel_me(): + print('cancel_me(): before sleep') + + try: + # Wait for 1 hour + await asyncio.sleep(3600) + except asyncio.CancelledError: + print('cancel_me(): cancel sleep') + raise + finally: + print('cancel_me(): after sleep') + + async def main(): + # Create a "cancel_me" Task + task = asyncio.create_task(cancel_me()) + + # Wait for 1 second + await asyncio.sleep(1) + + task.cancel() + try: + await task + except asyncio.CancelledError: + print("main(): cancel_me is cancelled now") + + asyncio.run(main()) + + # Expected output: + # + # cancel_me(): before sleep + # cancel_me(): cancel sleep + # cancel_me(): after sleep + # main(): cancel_me is cancelled now + + .. method:: cancelled() + + Return ``True`` if the Task is *cancelled*. + + The Task is *cancelled* when the cancellation was requested with + :meth:`cancel` and the wrapped coroutine propagated the + :exc:`CancelledError` exception thrown into it. + + .. method:: uncancel() + + Decrement the count of cancellation requests to this Task. + + Returns the remaining number of cancellation requests. + + Note that once execution of a cancelled task completed, further + calls to :meth:`uncancel` are ineffective. + + .. versionadded:: 3.11 + + This method is used by asyncio's internals and isn't expected to be + used by end-user code. In particular, if a Task gets successfully + uncancelled, this allows for elements of structured concurrency like + :ref:`taskgroups` and :func:`asyncio.timeout` to continue running, + isolating cancellation to the respective structured block. + For example:: + + async def make_request_with_timeout(): + try: + async with asyncio.timeout(1): + # Structured block affected by the timeout: + await make_request() + await make_another_request() + except TimeoutError: + log("There was a timeout") + # Outer code not affected by the timeout: + await unrelated_code() + + While the block with ``make_request()`` and ``make_another_request()`` + might get cancelled due to the timeout, ``unrelated_code()`` should + continue running even in case of the timeout. This is implemented + with :meth:`uncancel`. :class:`TaskGroup` context managers use + :func:`uncancel` in a similar fashion. + + .. method:: cancelling() + + Return the number of pending cancellation requests to this Task, i.e., + the number of calls to :meth:`cancel` less the number of + :meth:`uncancel` calls. + + Note that if this number is greater than zero but the Task is + still executing, :meth:`cancelled` will still return ``False``. + This is because this number can be lowered by calling :meth:`uncancel`, + which can lead to the task not being cancelled after all if the + cancellation requests go down to zero. + + This method is used by asyncio's internals and isn't expected to be + used by end-user code. See :meth:`uncancel` for more details. + + .. versionadded:: 3.11 diff --git a/Lib/asyncio/tasks.py b/Lib/asyncio/tasks.py index 56a355c..e48da0f 100644 --- a/Lib/asyncio/tasks.py +++ b/Lib/asyncio/tasks.py @@ -243,8 +243,8 @@ class Task(futures._PyFuture): # Inherit Python Task implementation def uncancel(self): """Decrement the task's count of cancellation requests. - This should be used by tasks that catch CancelledError - and wish to continue indefinitely until they are cancelled again. + This should be called by the party that called `cancel()` on the task + beforehand. Returns the remaining number of cancellation requests. """ diff --git a/Lib/test/test_asyncio/test_tasks.py b/Lib/test/test_asyncio/test_tasks.py index 427034a..1cc2060 100644 --- a/Lib/test/test_asyncio/test_tasks.py +++ b/Lib/test/test_asyncio/test_tasks.py @@ -525,7 +525,7 @@ class BaseTaskTests: finally: loop.close() - def test_uncancel(self): + def test_uncancel_basic(self): loop = asyncio.new_event_loop() async def task(): @@ -538,17 +538,137 @@ class BaseTaskTests: try: t = self.new_task(loop, task()) loop.run_until_complete(asyncio.sleep(0.01)) - self.assertTrue(t.cancel()) # Cancel first sleep + + # Cancel first sleep + self.assertTrue(t.cancel()) self.assertIn(" cancelling ", repr(t)) + self.assertEqual(t.cancelling(), 1) + self.assertFalse(t.cancelled()) # Task is still not complete loop.run_until_complete(asyncio.sleep(0.01)) - self.assertNotIn(" cancelling ", repr(t)) # after .uncancel() - self.assertTrue(t.cancel()) # Cancel second sleep + # after .uncancel() + self.assertNotIn(" cancelling ", repr(t)) + self.assertEqual(t.cancelling(), 0) + self.assertFalse(t.cancelled()) # Task is still not complete + + # Cancel second sleep + self.assertTrue(t.cancel()) + self.assertEqual(t.cancelling(), 1) + self.assertFalse(t.cancelled()) # Task is still not complete with self.assertRaises(asyncio.CancelledError): loop.run_until_complete(t) + self.assertTrue(t.cancelled()) # Finally, task complete + self.assertTrue(t.done()) + + # uncancel is no longer effective after the task is complete + t.uncancel() + self.assertTrue(t.cancelled()) + self.assertTrue(t.done()) finally: loop.close() + def test_uncancel_structured_blocks(self): + # This test recreates the following high-level structure using uncancel():: + # + # async def make_request_with_timeout(): + # try: + # async with asyncio.timeout(1): + # # Structured block affected by the timeout: + # await make_request() + # await make_another_request() + # except TimeoutError: + # pass # There was a timeout + # # Outer code not affected by the timeout: + # await unrelated_code() + + loop = asyncio.new_event_loop() + + async def make_request_with_timeout(*, sleep: float, timeout: float): + task = asyncio.current_task() + loop = task.get_loop() + + timed_out = False + structured_block_finished = False + outer_code_reached = False + + def on_timeout(): + nonlocal timed_out + timed_out = True + task.cancel() + + timeout_handle = loop.call_later(timeout, on_timeout) + try: + try: + # Structured block affected by the timeout + await asyncio.sleep(sleep) + structured_block_finished = True + finally: + timeout_handle.cancel() + if ( + timed_out + and task.uncancel() == 0 + and sys.exc_info()[0] is asyncio.CancelledError + ): + # Note the five rules that are needed here to satisfy proper + # uncancellation: + # + # 1. handle uncancellation in a `finally:` block to allow for + # plain returns; + # 2. our `timed_out` flag is set, meaning that it was our event + # that triggered the need to uncancel the task, regardless of + # what exception is raised; + # 3. we can call `uncancel()` because *we* called `cancel()` + # before; + # 4. we call `uncancel()` but we only continue converting the + # CancelledError to TimeoutError if `uncancel()` caused the + # cancellation request count go down to 0. We need to look + # at the counter vs having a simple boolean flag because our + # code might have been nested (think multiple timeouts). See + # commit 7fce1063b6e5a366f8504e039a8ccdd6944625cd for + # details. + # 5. we only convert CancelledError to TimeoutError; for other + # exceptions raised due to the cancellation (like + # a ConnectionLostError from a database client), simply + # propagate them. + # + # Those checks need to take place in this exact order to make + # sure the `cancelling()` counter always stays in sync. + # + # Additionally, the original stimulus to `cancel()` the task + # needs to be unscheduled to avoid re-cancelling the task later. + # Here we do it by cancelling `timeout_handle` in the `finally:` + # block. + raise TimeoutError + except TimeoutError: + self.assertTrue(timed_out) + + # Outer code not affected by the timeout: + outer_code_reached = True + await asyncio.sleep(0) + return timed_out, structured_block_finished, outer_code_reached + + # Test which timed out. + t1 = self.new_task(loop, make_request_with_timeout(sleep=10.0, timeout=0.1)) + timed_out, structured_block_finished, outer_code_reached = ( + loop.run_until_complete(t1) + ) + self.assertTrue(timed_out) + self.assertFalse(structured_block_finished) # it was cancelled + self.assertTrue(outer_code_reached) # task got uncancelled after leaving + # the structured block and continued until + # completion + self.assertEqual(t1.cancelling(), 0) # no pending cancellation of the outer task + + # Test which did not time out. + t2 = self.new_task(loop, make_request_with_timeout(sleep=0, timeout=10.0)) + timed_out, structured_block_finished, outer_code_reached = ( + loop.run_until_complete(t2) + ) + self.assertFalse(timed_out) + self.assertTrue(structured_block_finished) + self.assertTrue(outer_code_reached) + self.assertEqual(t2.cancelling(), 0) + def test_cancel(self): def gen(): -- cgit v0.12 From 981b509784c733c54d47bd4d1ceea34fc7ebcac3 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Thu, 6 Oct 2022 18:50:25 -0700 Subject: GH-90985: Revert "Deprecate passing a message into cancel()" (GH-97999) Reason: we were too hasty in deprecating this. We shouldn't deprecate it before we have a replacement. (cherry picked from commit 09de8d7aafece264720afbca3052a63eee413b73) Co-authored-by: Guido van Rossum --- Doc/library/asyncio-future.rst | 10 ---- Doc/library/asyncio-task.rst | 6 +-- Lib/asyncio/futures.py | 6 --- Lib/asyncio/tasks.py | 5 -- Lib/test/test_asyncio/test_futures.py | 12 +---- Lib/test/test_asyncio/test_tasks.py | 54 +++------------------- .../2022-10-06-23-42-00.gh-issue-90985.s280JY.rst | 1 + Modules/_asynciomodule.c | 20 -------- 8 files changed, 12 insertions(+), 102 deletions(-) create mode 100644 Misc/NEWS.d/next/Library/2022-10-06-23-42-00.gh-issue-90985.s280JY.rst diff --git a/Doc/library/asyncio-future.rst b/Doc/library/asyncio-future.rst index 8e60877..70cec9b 100644 --- a/Doc/library/asyncio-future.rst +++ b/Doc/library/asyncio-future.rst @@ -197,11 +197,6 @@ Future Object .. versionchanged:: 3.9 Added the *msg* parameter. - .. deprecated-removed:: 3.11 3.14 - *msg* parameter is ambiguous when multiple :meth:`cancel` - are called with different cancellation messages. - The argument will be removed. - .. method:: exception() Return the exception that was set on this Future. @@ -282,8 +277,3 @@ the Future has a result:: - :meth:`asyncio.Future.cancel` accepts an optional ``msg`` argument, but :func:`concurrent.futures.cancel` does not. - - .. deprecated-removed:: 3.11 3.14 - *msg* parameter is ambiguous when multiple :meth:`cancel` - are called with different cancellation messages. - The argument will be removed. diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index eb42301..f795f25 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -1137,10 +1137,8 @@ Task Object .. versionchanged:: 3.9 Added the *msg* parameter. - .. deprecated-removed:: 3.11 3.14 - *msg* parameter is ambiguous when multiple :meth:`cancel` - are called with different cancellation messages. - The argument will be removed. + .. versionchanged:: 3.11 + The ``msg`` parameter is propagated from cancelled task to its awaiter. .. _asyncio_example_task_cancel: diff --git a/Lib/asyncio/futures.py b/Lib/asyncio/futures.py index 4bd9629..be2458a 100644 --- a/Lib/asyncio/futures.py +++ b/Lib/asyncio/futures.py @@ -8,7 +8,6 @@ import concurrent.futures import contextvars import logging import sys -import warnings from types import GenericAlias from . import base_futures @@ -151,11 +150,6 @@ class Future: change the future's state to cancelled, schedule the callbacks and return True. """ - if msg is not None: - warnings.warn("Passing 'msg' argument to Future.cancel() " - "is deprecated since Python 3.11, and " - "scheduled for removal in Python 3.14.", - DeprecationWarning, stacklevel=2) self.__log_traceback = False if self._state != _PENDING: return False diff --git a/Lib/asyncio/tasks.py b/Lib/asyncio/tasks.py index e48da0f..3e07ce5 100644 --- a/Lib/asyncio/tasks.py +++ b/Lib/asyncio/tasks.py @@ -207,11 +207,6 @@ class Task(futures._PyFuture): # Inherit Python Task implementation This also increases the task's count of cancellation requests. """ - if msg is not None: - warnings.warn("Passing 'msg' argument to Task.cancel() " - "is deprecated since Python 3.11, and " - "scheduled for removal in Python 3.14.", - DeprecationWarning, stacklevel=2) self._log_traceback = False if self.done(): return False diff --git a/Lib/test/test_asyncio/test_futures.py b/Lib/test/test_asyncio/test_futures.py index f4a46ec..d71af8c 100644 --- a/Lib/test/test_asyncio/test_futures.py +++ b/Lib/test/test_asyncio/test_futures.py @@ -228,22 +228,14 @@ class BaseFutureTests: self.assertTrue(hasattr(f, '_cancel_message')) self.assertEqual(f._cancel_message, None) - with self.assertWarnsRegex( - DeprecationWarning, - "Passing 'msg' argument" - ): - f.cancel('my message') + f.cancel('my message') with self.assertRaises(asyncio.CancelledError): self.loop.run_until_complete(f) self.assertEqual(f._cancel_message, 'my message') def test_future_cancel_message_setter(self): f = self._new_future(loop=self.loop) - with self.assertWarnsRegex( - DeprecationWarning, - "Passing 'msg' argument" - ): - f.cancel('my message') + f.cancel('my message') f._cancel_message = 'my new message' self.assertEqual(f._cancel_message, 'my new message') diff --git a/Lib/test/test_asyncio/test_tasks.py b/Lib/test/test_asyncio/test_tasks.py index 1cc2060..7585768 100644 --- a/Lib/test/test_asyncio/test_tasks.py +++ b/Lib/test/test_asyncio/test_tasks.py @@ -113,11 +113,7 @@ class BaseTaskTests: self.assertTrue(hasattr(t, '_cancel_message')) self.assertEqual(t._cancel_message, None) - with self.assertWarnsRegex( - DeprecationWarning, - "Passing 'msg' argument" - ): - t.cancel('my message') + t.cancel('my message') self.assertEqual(t._cancel_message, 'my message') with self.assertRaises(asyncio.CancelledError) as cm: @@ -129,11 +125,7 @@ class BaseTaskTests: async def coro(): pass t = self.new_task(self.loop, coro()) - with self.assertWarnsRegex( - DeprecationWarning, - "Passing 'msg' argument" - ): - t.cancel('my message') + t.cancel('my message') t._cancel_message = 'my new message' self.assertEqual(t._cancel_message, 'my new message') @@ -710,14 +702,7 @@ class BaseTaskTests: async def coro(): task = self.new_task(loop, sleep()) await asyncio.sleep(0) - if cancel_args not in ((), (None,)): - with self.assertWarnsRegex( - DeprecationWarning, - "Passing 'msg' argument" - ): - task.cancel(*cancel_args) - else: - task.cancel(*cancel_args) + task.cancel(*cancel_args) done, pending = await asyncio.wait([task]) task.result() @@ -751,14 +736,7 @@ class BaseTaskTests: async def coro(): task = self.new_task(loop, sleep()) await asyncio.sleep(0) - if cancel_args not in ((), (None,)): - with self.assertWarnsRegex( - DeprecationWarning, - "Passing 'msg' argument" - ): - task.cancel(*cancel_args) - else: - task.cancel(*cancel_args) + task.cancel(*cancel_args) done, pending = await asyncio.wait([task]) task.exception() @@ -781,17 +759,10 @@ class BaseTaskTests: fut.set_result(None) await asyncio.sleep(10) - def cancel(task, msg): - with self.assertWarnsRegex( - DeprecationWarning, - "Passing 'msg' argument" - ): - task.cancel(msg) - async def coro(): inner_task = self.new_task(loop, sleep()) await fut - loop.call_soon(cancel, inner_task, 'msg') + loop.call_soon(inner_task.cancel, 'msg') try: await inner_task except asyncio.CancelledError as ex: @@ -817,11 +788,7 @@ class BaseTaskTests: async def coro(): task = self.new_task(loop, sleep()) # We deliberately leave out the sleep here. - with self.assertWarnsRegex( - DeprecationWarning, - "Passing 'msg' argument" - ): - task.cancel('my message') + task.cancel('my message') done, pending = await asyncio.wait([task]) task.exception() @@ -2183,14 +2150,7 @@ class BaseTaskTests: async def main(): qwe = self.new_task(loop, test()) await asyncio.sleep(0.2) - if cancel_args not in ((), (None,)): - with self.assertWarnsRegex( - DeprecationWarning, - "Passing 'msg' argument" - ): - qwe.cancel(*cancel_args) - else: - qwe.cancel(*cancel_args) + qwe.cancel(*cancel_args) await qwe try: diff --git a/Misc/NEWS.d/next/Library/2022-10-06-23-42-00.gh-issue-90985.s280JY.rst b/Misc/NEWS.d/next/Library/2022-10-06-23-42-00.gh-issue-90985.s280JY.rst new file mode 100644 index 0000000..964aa39 --- /dev/null +++ b/Misc/NEWS.d/next/Library/2022-10-06-23-42-00.gh-issue-90985.s280JY.rst @@ -0,0 +1 @@ +Earlier in 3.11 we deprecated ``asyncio.Task.cancel("message")``. We realized we were too harsh, and have undeprecated it. diff --git a/Modules/_asynciomodule.c b/Modules/_asynciomodule.c index 10679be..e51f97f 100644 --- a/Modules/_asynciomodule.c +++ b/Modules/_asynciomodule.c @@ -1111,16 +1111,6 @@ static PyObject * _asyncio_Future_cancel_impl(FutureObj *self, PyObject *msg) /*[clinic end generated code: output=3edebbc668e5aba3 input=925eb545251f2c5a]*/ { - if (msg != Py_None) { - if (PyErr_WarnEx(PyExc_DeprecationWarning, - "Passing 'msg' argument to Future.cancel() " - "is deprecated since Python 3.11, and " - "scheduled for removal in Python 3.14.", - 2)) - { - return NULL; - } - } ENSURE_FUTURE_ALIVE(self) return future_cancel(self, msg); } @@ -2201,16 +2191,6 @@ static PyObject * _asyncio_Task_cancel_impl(TaskObj *self, PyObject *msg) /*[clinic end generated code: output=c66b60d41c74f9f1 input=7bb51bf25974c783]*/ { - if (msg != Py_None) { - if (PyErr_WarnEx(PyExc_DeprecationWarning, - "Passing 'msg' argument to Task.cancel() " - "is deprecated since Python 3.11, and " - "scheduled for removal in Python 3.14.", - 2)) - { - return NULL; - } - } self->task_log_tb = 0; if (self->task_state != STATE_PENDING) { -- cgit v0.12 From deaf509e8fc6e0363bd6f26d52ad42f976ec42f2 Mon Sep 17 00:00:00 2001 From: Pablo Galindo Date: Mon, 24 Oct 2022 18:34:46 +0100 Subject: Python 3.11.0 --- Include/patchlevel.h | 6 +- Lib/pydoc_data/topics.py | 304 ++++++++++++--------- Misc/NEWS.d/3.11.0.rst | 255 +++++++++++++++++ .../2022-09-11-14-23-49.gh-issue-96729.W4uBWL.rst | 2 - .../2020-11-15-02-08-43.bpo-42316.LqdkWK.rst | 1 - .../2022-09-05-19-20-44.gh-issue-96587.bVxhX2.rst | 2 - .../2022-09-16-19-02-40.gh-issue-95778.cJmnst.rst | 3 - .../2022-09-18-08-47-40.gh-issue-96821.Co2iOq.rst | 1 - .../2022-09-21-14-38-31.gh-issue-96848.WuoLzU.rst | 3 - .../2022-09-21-16-06-37.gh-issue-96975.BmE0XY.rst | 2 - .../2022-10-03-13-35-48.gh-issue-97752.0xTjJY.rst | 2 - .../2022-10-06-02-11-34.gh-issue-97002.Zvsk71.rst | 3 - .../2022-05-20-18-42-10.gh-issue-93031.c2RdJe.rst | 1 - .../2022-10-02-10-58-52.gh-issue-97741.39l023.rst | 2 - .../2022-05-25-15-57-39.gh-issue-90155.YMstB5.rst | 1 - .../2022-09-24-18-56-23.gh-issue-96865.o9WUkW.rst | 9 - .../2022-09-25-23-24-52.gh-issue-97545.HZLSNt.rst | 1 - .../2022-10-06-23-42-00.gh-issue-90985.s280JY.rst | 1 - .../2022-10-16-15-31-50.gh-issue-98331.Y5kPOX.rst | 1 - .../2022-09-07-10-42-00.gh-issue-97514.Yggdsl.rst | 15 - .../2022-09-28-17-09-37.gh-issue-97616.K1e3Xs.rst | 3 - .../2022-10-20-17-49-50.gh-issue-95027.viRpJB.rst | 4 - .../2022-09-29-23-08-49.gh-issue-90989.no89Q2.rst | 1 - .../2022-10-19-19-35-37.gh-issue-98414.FbHZuS.rst | 3 - .../2022-10-19-20-00-28.gh-issue-98360.O2m6YG.rst | 4 - .../2022-10-05-15-26-58.gh-issue-97897.Rf-C6u.rst | 6 - README.rst | 4 +- 27 files changed, 436 insertions(+), 204 deletions(-) create mode 100644 Misc/NEWS.d/3.11.0.rst delete mode 100644 Misc/NEWS.d/next/Build/2022-09-11-14-23-49.gh-issue-96729.W4uBWL.rst delete mode 100644 Misc/NEWS.d/next/Core and Builtins/2020-11-15-02-08-43.bpo-42316.LqdkWK.rst delete mode 100644 Misc/NEWS.d/next/Core and Builtins/2022-09-05-19-20-44.gh-issue-96587.bVxhX2.rst delete mode 100644 Misc/NEWS.d/next/Core and Builtins/2022-09-16-19-02-40.gh-issue-95778.cJmnst.rst delete mode 100644 Misc/NEWS.d/next/Core and Builtins/2022-09-18-08-47-40.gh-issue-96821.Co2iOq.rst delete mode 100644 Misc/NEWS.d/next/Core and Builtins/2022-09-21-14-38-31.gh-issue-96848.WuoLzU.rst delete mode 100644 Misc/NEWS.d/next/Core and Builtins/2022-09-21-16-06-37.gh-issue-96975.BmE0XY.rst delete mode 100644 Misc/NEWS.d/next/Core and Builtins/2022-10-03-13-35-48.gh-issue-97752.0xTjJY.rst delete mode 100644 Misc/NEWS.d/next/Core and Builtins/2022-10-06-02-11-34.gh-issue-97002.Zvsk71.rst delete mode 100644 Misc/NEWS.d/next/Documentation/2022-05-20-18-42-10.gh-issue-93031.c2RdJe.rst delete mode 100644 Misc/NEWS.d/next/Documentation/2022-10-02-10-58-52.gh-issue-97741.39l023.rst delete mode 100644 Misc/NEWS.d/next/Library/2022-05-25-15-57-39.gh-issue-90155.YMstB5.rst delete mode 100644 Misc/NEWS.d/next/Library/2022-09-24-18-56-23.gh-issue-96865.o9WUkW.rst delete mode 100644 Misc/NEWS.d/next/Library/2022-09-25-23-24-52.gh-issue-97545.HZLSNt.rst delete mode 100644 Misc/NEWS.d/next/Library/2022-10-06-23-42-00.gh-issue-90985.s280JY.rst delete mode 100644 Misc/NEWS.d/next/Library/2022-10-16-15-31-50.gh-issue-98331.Y5kPOX.rst delete mode 100644 Misc/NEWS.d/next/Security/2022-09-07-10-42-00.gh-issue-97514.Yggdsl.rst delete mode 100644 Misc/NEWS.d/next/Security/2022-09-28-17-09-37.gh-issue-97616.K1e3Xs.rst delete mode 100644 Misc/NEWS.d/next/Tests/2022-10-20-17-49-50.gh-issue-95027.viRpJB.rst delete mode 100644 Misc/NEWS.d/next/Windows/2022-09-29-23-08-49.gh-issue-90989.no89Q2.rst delete mode 100644 Misc/NEWS.d/next/Windows/2022-10-19-19-35-37.gh-issue-98414.FbHZuS.rst delete mode 100644 Misc/NEWS.d/next/Windows/2022-10-19-20-00-28.gh-issue-98360.O2m6YG.rst delete mode 100644 Misc/NEWS.d/next/macOS/2022-10-05-15-26-58.gh-issue-97897.Rf-C6u.rst diff --git a/Include/patchlevel.h b/Include/patchlevel.h index a54a2ce..6274014 100644 --- a/Include/patchlevel.h +++ b/Include/patchlevel.h @@ -19,11 +19,11 @@ #define PY_MAJOR_VERSION 3 #define PY_MINOR_VERSION 11 #define PY_MICRO_VERSION 0 -#define PY_RELEASE_LEVEL PY_RELEASE_LEVEL_GAMMA -#define PY_RELEASE_SERIAL 2 +#define PY_RELEASE_LEVEL PY_RELEASE_LEVEL_FINAL +#define PY_RELEASE_SERIAL 0 /* Version as a string */ -#define PY_VERSION "3.11.0rc2+" +#define PY_VERSION "3.11.0" /*--end constants--*/ /* Version as a single 4-byte hex number, e.g. 0x010502B2 == 1.5.2b2. diff --git a/Lib/pydoc_data/topics.py b/Lib/pydoc_data/topics.py index 14c6dc2..7bba5cb 100644 --- a/Lib/pydoc_data/topics.py +++ b/Lib/pydoc_data/topics.py @@ -1,5 +1,5 @@ # -*- coding: utf-8 -*- -# Autogenerated by Sphinx on Sun Sep 11 20:22:13 2022 +# Autogenerated by Sphinx on Mon Oct 24 18:35:07 2022 topics = {'assert': 'The "assert" statement\n' '**********************\n' '\n' @@ -1671,10 +1671,26 @@ topics = {'assert': 'The "assert" statement\n' 'If the syntax "**expression" appears in the function call,\n' '"expression" must evaluate to a *mapping*, the contents of which ' 'are\n' - 'treated as additional keyword arguments. If a keyword is already\n' - 'present (as an explicit keyword argument, or from another ' - 'unpacking),\n' - 'a "TypeError" exception is raised.\n' + 'treated as additional keyword arguments. If a parameter matching a ' + 'key\n' + 'has already been given a value (by an explicit keyword argument, ' + 'or\n' + 'from another unpacking), a "TypeError" exception is raised.\n' + '\n' + 'When "**expression" is used, each key in this mapping must be a\n' + 'string. Each value from the mapping is assigned to the first ' + 'formal\n' + 'parameter eligible for keyword assignment whose name is equal to ' + 'the\n' + 'key. A key need not be a Python identifier (e.g. ""max-temp °F"" ' + 'is\n' + 'acceptable, although it will not match any formal parameter that ' + 'could\n' + 'be declared). If there is no match to a formal parameter the ' + 'key-value\n' + 'pair is collected by the "**" parameter, if there is one, or if ' + 'there\n' + 'is not, a "TypeError" exception is raised.\n' '\n' 'Formal parameters using the syntax "*identifier" or "**identifier"\n' 'cannot be used as positional argument slots or as keyword argument\n' @@ -2022,7 +2038,7 @@ topics = {'assert': 'The "assert" statement\n' '\n' '* Mappings (instances of "dict") compare equal if and only if ' 'they\n' - ' have equal *(key, value)* pairs. Equality comparison of the ' + ' have equal "(key, value)" pairs. Equality comparison of the ' 'keys and\n' ' values enforces reflexivity.\n' '\n' @@ -2398,35 +2414,43 @@ topics = {'assert': 'The "assert" statement\n' ' try3_stmt ::= "try" ":" suite\n' ' "finally" ":" suite\n' '\n' + 'Additional information on exceptions can be found in section\n' + 'Exceptions, and information on using the "raise" statement to ' + 'generate\n' + 'exceptions may be found in section The raise statement.\n' + '\n' + '\n' + '"except" clause\n' + '---------------\n' + '\n' 'The "except" clause(s) specify one or more exception handlers. ' 'When no\n' 'exception occurs in the "try" clause, no exception handler is\n' 'executed. When an exception occurs in the "try" suite, a search ' 'for an\n' - 'exception handler is started. This search inspects the except ' - 'clauses\n' - 'in turn until one is found that matches the exception. An ' - 'expression-\n' - 'less except clause, if present, must be last; it matches any\n' - 'exception. For an except clause with an expression, that ' - 'expression\n' - 'is evaluated, and the clause matches the exception if the ' - 'resulting\n' - 'object is “compatible” with the exception. An object is ' - 'compatible\n' - 'with an exception if the object is the class or a *non-virtual ' - 'base\n' - 'class* of the exception object, or a tuple containing an item ' - 'that is\n' - 'the class or a non-virtual base class of the exception object.\n' - '\n' - 'If no except clause matches the exception, the search for an ' + 'exception handler is started. This search inspects the "except"\n' + 'clauses in turn until one is found that matches the exception. ' + 'An\n' + 'expression-less "except" clause, if present, must be last; it ' + 'matches\n' + 'any exception. For an "except" clause with an expression, that\n' + 'expression is evaluated, and the clause matches the exception if ' + 'the\n' + 'resulting object is “compatible” with the exception. An object ' + 'is\n' + 'compatible with an exception if the object is the class or a ' + '*non-\n' + 'virtual base class* of the exception object, or a tuple ' + 'containing an\n' + 'item that is the class or a non-virtual base class of the ' 'exception\n' - 'handler continues in the surrounding code and on the invocation ' - 'stack.\n' - '[1]\n' + 'object.\n' + '\n' + 'If no "except" clause matches the exception, the search for an\n' + 'exception handler continues in the surrounding code and on the\n' + 'invocation stack. [1]\n' '\n' - 'If the evaluation of an expression in the header of an except ' + 'If the evaluation of an expression in the header of an "except" ' 'clause\n' 'raises an exception, the original search for a handler is ' 'canceled and\n' @@ -2436,24 +2460,24 @@ topics = {'assert': 'The "assert" statement\n' 'raised\n' 'the exception).\n' '\n' - 'When a matching except clause is found, the exception is ' + 'When a matching "except" clause is found, the exception is ' 'assigned to\n' - 'the target specified after the "as" keyword in that except ' - 'clause, if\n' - 'present, and the except clause’s suite is executed. All except\n' - 'clauses must have an executable block. When the end of this ' + 'the target specified after the "as" keyword in that "except" ' + 'clause,\n' + 'if present, and the "except" clause’s suite is executed. All ' + '"except"\n' + 'clauses must have an executable block. When the end of this ' 'block is\n' - 'reached, execution continues normally after the entire try ' - 'statement.\n' - '(This means that if two nested handlers exist for the same ' - 'exception,\n' - 'and the exception occurs in the try clause of the inner handler, ' - 'the\n' - 'outer handler will not handle the exception.)\n' + 'reached, execution continues normally after the entire "try"\n' + 'statement. (This means that if two nested handlers exist for the ' + 'same\n' + 'exception, and the exception occurs in the "try" clause of the ' + 'inner\n' + 'handler, the outer handler will not handle the exception.)\n' '\n' 'When an exception has been assigned using "as target", it is ' 'cleared\n' - 'at the end of the except clause. This is as if\n' + 'at the end of the "except" clause. This is as if\n' '\n' ' except E as N:\n' ' foo\n' @@ -2468,7 +2492,7 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'This means the exception must be assigned to a different name to ' 'be\n' - 'able to refer to it after the except clause. Exceptions are ' + 'able to refer to it after the "except" clause. Exceptions are ' 'cleared\n' 'because with the traceback attached to them, they form a ' 'reference\n' @@ -2476,7 +2500,8 @@ topics = {'assert': 'The "assert" statement\n' 'alive\n' 'until the next garbage collection occurs.\n' '\n' - 'Before an except clause’s suite is executed, details about the\n' + 'Before an "except" clause’s suite is executed, details about ' + 'the\n' 'exception are stored in the "sys" module and can be accessed ' 'via\n' '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting ' @@ -2512,6 +2537,10 @@ topics = {'assert': 'The "assert" statement\n' ' >>> print(sys.exc_info())\n' ' (None, None, None)\n' '\n' + '\n' + '"except*" clause\n' + '----------------\n' + '\n' 'The "except*" clause(s) are used for handling "ExceptionGroup"s. ' 'The\n' 'exception type for matching is interpreted as in the case of ' @@ -2520,12 +2549,13 @@ topics = {'assert': 'The "assert" statement\n' 'when\n' 'the type matches some of the exceptions in the group. This means ' 'that\n' - 'multiple except* clauses can execute, each handling part of the\n' + 'multiple "except*" clauses can execute, each handling part of ' + 'the\n' 'exception group. Each clause executes once and handles an ' 'exception\n' 'group of all matching exceptions. Each exception in the group ' 'is\n' - 'handled by at most one except* clause, the first that matches ' + 'handled by at most one "except*" clause, the first that matches ' 'it.\n' '\n' ' >>> try:\n' @@ -2548,22 +2578,26 @@ topics = {'assert': 'The "assert" statement\n' ' +-+---------------- 1 ----------------\n' ' | ValueError: 1\n' ' +------------------------------------\n' - ' >>>\n' '\n' - ' Any remaining exceptions that were not handled by any except* ' - 'clause\n' - ' are re-raised at the end, combined into an exception group ' - 'along with\n' - ' all exceptions that were raised from within except* clauses.\n' - '\n' - ' An except* clause must have a matching type, and this type ' - 'cannot be a\n' - ' subclass of :exc:`BaseExceptionGroup`. It is not possible to ' - 'mix except\n' - ' and except* in the same :keyword:`try`. :keyword:`break`,\n' - ' :keyword:`continue` and :keyword:`return` cannot appear in an ' - 'except*\n' - ' clause.\n' + ' Any remaining exceptions that were not handled by any ' + ':keyword:`!except*`\n' + ' clause are re-raised at the end, combined into an exception ' + 'group along with\n' + ' all exceptions that were raised from within ' + ':keyword:`!except*` clauses.\n' + '\n' + ' An :keyword:`!except*` clause must have a matching type,\n' + ' and this type cannot be a subclass of ' + ':exc:`BaseExceptionGroup`.\n' + ' It is not possible to mix :keyword:`except` and ' + ':keyword:`!except*`\n' + ' in the same :keyword:`try`.\n' + ' :keyword:`break`, :keyword:`continue` and :keyword:`return`\n' + ' cannot appear in an :keyword:`!except*` clause.\n' + '\n' + '\n' + '"else" clause\n' + '-------------\n' '\n' 'The optional "else" clause is executed if the control flow ' 'leaves the\n' @@ -2573,6 +2607,10 @@ topics = {'assert': 'The "assert" statement\n' 'are\n' 'not handled by the preceding "except" clauses.\n' '\n' + '\n' + '"finally" clause\n' + '----------------\n' + '\n' 'If "finally" is present, it specifies a ‘cleanup’ handler. The ' '"try"\n' 'clause is executed, including any "except" and "else" clauses. ' @@ -2626,11 +2664,6 @@ topics = {'assert': 'The "assert" statement\n' ' >>> foo()\n' " 'finally'\n" '\n' - 'Additional information on exceptions can be found in section\n' - 'Exceptions, and information on using the "raise" statement to ' - 'generate\n' - 'exceptions may be found in section The raise statement.\n' - '\n' 'Changed in version 3.8: Prior to Python 3.8, a "continue" ' 'statement\n' 'was illegal in the "finally" clause due to a problem with the\n' @@ -5540,9 +5573,10 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' * "for" loop header,\n' '\n' - ' * after "as" in a "with" statement, "except" clause or in the ' - 'as-\n' - ' pattern in structural pattern matching,\n' + ' * after "as" in a "with" statement, "except" clause, ' + '"except*"\n' + ' clause, or in the as-pattern in structural pattern ' + 'matching,\n' '\n' ' * in a capture pattern in structural pattern matching\n' '\n' @@ -7657,9 +7691,8 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' * "for" loop header,\n' '\n' - ' * after "as" in a "with" statement, "except" clause or in the ' - 'as-\n' - ' pattern in structural pattern matching,\n' + ' * after "as" in a "with" statement, "except" clause, "except*"\n' + ' clause, or in the as-pattern in structural pattern matching,\n' '\n' ' * in a capture pattern in structural pattern matching\n' '\n' @@ -8232,8 +8265,9 @@ topics = {'assert': 'The "assert" statement\n' 'the syntax is explicitly given, operators are binary. ' 'Operators in\n' 'the same box group left to right (except for ' - 'exponentiation, which\n' - 'groups from right to left).\n' + 'exponentiation and\n' + 'conditional expressions, which group from right to ' + 'left).\n' '\n' 'Note that comparisons, membership tests, and identity ' 'tests, all have\n' @@ -12500,31 +12534,39 @@ topics = {'assert': 'The "assert" statement\n' ' try3_stmt ::= "try" ":" suite\n' ' "finally" ":" suite\n' '\n' + 'Additional information on exceptions can be found in section\n' + 'Exceptions, and information on using the "raise" statement to ' + 'generate\n' + 'exceptions may be found in section The raise statement.\n' + '\n' + '\n' + '"except" clause\n' + '===============\n' + '\n' 'The "except" clause(s) specify one or more exception handlers. When ' 'no\n' 'exception occurs in the "try" clause, no exception handler is\n' 'executed. When an exception occurs in the "try" suite, a search for ' 'an\n' - 'exception handler is started. This search inspects the except ' - 'clauses\n' - 'in turn until one is found that matches the exception. An ' - 'expression-\n' - 'less except clause, if present, must be last; it matches any\n' - 'exception. For an except clause with an expression, that expression\n' - 'is evaluated, and the clause matches the exception if the resulting\n' - 'object is “compatible” with the exception. An object is compatible\n' - 'with an exception if the object is the class or a *non-virtual base\n' - 'class* of the exception object, or a tuple containing an item that ' - 'is\n' - 'the class or a non-virtual base class of the exception object.\n' + 'exception handler is started. This search inspects the "except"\n' + 'clauses in turn until one is found that matches the exception. An\n' + 'expression-less "except" clause, if present, must be last; it ' + 'matches\n' + 'any exception. For an "except" clause with an expression, that\n' + 'expression is evaluated, and the clause matches the exception if the\n' + 'resulting object is “compatible” with the exception. An object is\n' + 'compatible with an exception if the object is the class or a *non-\n' + 'virtual base class* of the exception object, or a tuple containing ' + 'an\n' + 'item that is the class or a non-virtual base class of the exception\n' + 'object.\n' '\n' - 'If no except clause matches the exception, the search for an ' - 'exception\n' - 'handler continues in the surrounding code and on the invocation ' - 'stack.\n' - '[1]\n' + 'If no "except" clause matches the exception, the search for an\n' + 'exception handler continues in the surrounding code and on the\n' + 'invocation stack. [1]\n' '\n' - 'If the evaluation of an expression in the header of an except clause\n' + 'If the evaluation of an expression in the header of an "except" ' + 'clause\n' 'raises an exception, the original search for a handler is canceled ' 'and\n' 'a search starts for the new exception in the surrounding code and on\n' @@ -12532,21 +12574,20 @@ topics = {'assert': 'The "assert" statement\n' 'raised\n' 'the exception).\n' '\n' - 'When a matching except clause is found, the exception is assigned to\n' - 'the target specified after the "as" keyword in that except clause, ' - 'if\n' - 'present, and the except clause’s suite is executed. All except\n' - 'clauses must have an executable block. When the end of this block ' - 'is\n' - 'reached, execution continues normally after the entire try ' - 'statement.\n' - '(This means that if two nested handlers exist for the same ' - 'exception,\n' - 'and the exception occurs in the try clause of the inner handler, the\n' - 'outer handler will not handle the exception.)\n' + 'When a matching "except" clause is found, the exception is assigned ' + 'to\n' + 'the target specified after the "as" keyword in that "except" clause,\n' + 'if present, and the "except" clause’s suite is executed. All ' + '"except"\n' + 'clauses must have an executable block. When the end of this block is\n' + 'reached, execution continues normally after the entire "try"\n' + 'statement. (This means that if two nested handlers exist for the ' + 'same\n' + 'exception, and the exception occurs in the "try" clause of the inner\n' + 'handler, the outer handler will not handle the exception.)\n' '\n' 'When an exception has been assigned using "as target", it is cleared\n' - 'at the end of the except clause. This is as if\n' + 'at the end of the "except" clause. This is as if\n' '\n' ' except E as N:\n' ' foo\n' @@ -12560,12 +12601,13 @@ topics = {'assert': 'The "assert" statement\n' ' del N\n' '\n' 'This means the exception must be assigned to a different name to be\n' - 'able to refer to it after the except clause. Exceptions are cleared\n' + 'able to refer to it after the "except" clause. Exceptions are ' + 'cleared\n' 'because with the traceback attached to them, they form a reference\n' 'cycle with the stack frame, keeping all locals in that frame alive\n' 'until the next garbage collection occurs.\n' '\n' - 'Before an except clause’s suite is executed, details about the\n' + 'Before an "except" clause’s suite is executed, details about the\n' 'exception are stored in the "sys" module and can be accessed via\n' '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting of ' 'the\n' @@ -12597,16 +12639,20 @@ topics = {'assert': 'The "assert" statement\n' ' >>> print(sys.exc_info())\n' ' (None, None, None)\n' '\n' + '\n' + '"except*" clause\n' + '================\n' + '\n' 'The "except*" clause(s) are used for handling "ExceptionGroup"s. The\n' 'exception type for matching is interpreted as in the case of ' '"except",\n' 'but in the case of exception groups we can have partial matches when\n' 'the type matches some of the exceptions in the group. This means ' 'that\n' - 'multiple except* clauses can execute, each handling part of the\n' + 'multiple "except*" clauses can execute, each handling part of the\n' 'exception group. Each clause executes once and handles an exception\n' 'group of all matching exceptions. Each exception in the group is\n' - 'handled by at most one except* clause, the first that matches it.\n' + 'handled by at most one "except*" clause, the first that matches it.\n' '\n' ' >>> try:\n' ' ... raise ExceptionGroup("eg",\n' @@ -12626,22 +12672,25 @@ topics = {'assert': 'The "assert" statement\n' ' +-+---------------- 1 ----------------\n' ' | ValueError: 1\n' ' +------------------------------------\n' - ' >>>\n' '\n' - ' Any remaining exceptions that were not handled by any except* ' - 'clause\n' - ' are re-raised at the end, combined into an exception group along ' - 'with\n' - ' all exceptions that were raised from within except* clauses.\n' + ' Any remaining exceptions that were not handled by any ' + ':keyword:`!except*`\n' + ' clause are re-raised at the end, combined into an exception group ' + 'along with\n' + ' all exceptions that were raised from within :keyword:`!except*` ' + 'clauses.\n' + '\n' + ' An :keyword:`!except*` clause must have a matching type,\n' + ' and this type cannot be a subclass of :exc:`BaseExceptionGroup`.\n' + ' It is not possible to mix :keyword:`except` and ' + ':keyword:`!except*`\n' + ' in the same :keyword:`try`.\n' + ' :keyword:`break`, :keyword:`continue` and :keyword:`return`\n' + ' cannot appear in an :keyword:`!except*` clause.\n' + '\n' '\n' - ' An except* clause must have a matching type, and this type cannot ' - 'be a\n' - ' subclass of :exc:`BaseExceptionGroup`. It is not possible to mix ' - 'except\n' - ' and except* in the same :keyword:`try`. :keyword:`break`,\n' - ' :keyword:`continue` and :keyword:`return` cannot appear in an ' - 'except*\n' - ' clause.\n' + '"else" clause\n' + '=============\n' '\n' 'The optional "else" clause is executed if the control flow leaves ' 'the\n' @@ -12650,6 +12699,10 @@ topics = {'assert': 'The "assert" statement\n' '"break" statement was executed. Exceptions in the "else" clause are\n' 'not handled by the preceding "except" clauses.\n' '\n' + '\n' + '"finally" clause\n' + '================\n' + '\n' 'If "finally" is present, it specifies a ‘cleanup’ handler. The ' '"try"\n' 'clause is executed, including any "except" and "else" clauses. If ' @@ -12697,11 +12750,6 @@ topics = {'assert': 'The "assert" statement\n' ' >>> foo()\n' " 'finally'\n" '\n' - 'Additional information on exceptions can be found in section\n' - 'Exceptions, and information on using the "raise" statement to ' - 'generate\n' - 'exceptions may be found in section The raise statement.\n' - '\n' 'Changed in version 3.8: Prior to Python 3.8, a "continue" statement\n' 'was illegal in the "finally" clause due to a problem with the\n' 'implementation.\n', @@ -12901,7 +12949,7 @@ topics = {'assert': 'The "assert" statement\n' ' points. All the code points in the range "U+0000 - ' 'U+10FFFF"\n' ' can be represented in a string. Python doesn’t have a ' - '*char*\n' + 'char\n' ' type; instead, every code point in the string is ' 'represented\n' ' as a string object with length "1". The built-in ' diff --git a/Misc/NEWS.d/3.11.0.rst b/Misc/NEWS.d/3.11.0.rst new file mode 100644 index 0000000..2e1c49d --- /dev/null +++ b/Misc/NEWS.d/3.11.0.rst @@ -0,0 +1,255 @@ +.. date: 2022-09-28-17-09-37 +.. gh-issue: 97616 +.. nonce: K1e3Xs +.. release date: 2022-10-24 +.. section: Security + +Fix multiplying a list by an integer (``list *= int``): detect the integer +overflow when the new allocated length is close to the maximum size. Issue +reported by Jordan Limor. Patch by Victor Stinner. + +.. + +.. date: 2022-09-07-10-42-00 +.. gh-issue: 97514 +.. nonce: Yggdsl +.. section: Security + +On Linux the :mod:`multiprocessing` module returns to using filesystem +backed unix domain sockets for communication with the *forkserver* process +instead of the Linux abstract socket namespace. Only code that chooses to +use the :ref:`"forkserver" start method ` is +affected. + +Abstract sockets have no permissions and could allow any user on the system +in the same `network namespace +`_ (often +the whole system) to inject code into the multiprocessing *forkserver* +process. This was a potential privilege escalation. Filesystem based socket +permissions restrict this to the *forkserver* process user as was the +default in Python 3.8 and earlier. + +This prevents Linux `CVE-2022-42919 +`_. + +.. + +.. date: 2022-10-06-02-11-34 +.. gh-issue: 97002 +.. nonce: Zvsk71 +.. section: Core and Builtins + +Fix an issue where several frame objects could be backed by the same +interpreter frame, possibly leading to corrupted memory and hard crashes of +the interpreter. + +.. + +.. date: 2022-10-03-13-35-48 +.. gh-issue: 97752 +.. nonce: 0xTjJY +.. section: Core and Builtins + +Fix possible data corruption or crashes when accessing the ``f_back`` member +of newly-created generator or coroutine frames. + +.. + +.. date: 2022-09-21-16-06-37 +.. gh-issue: 96975 +.. nonce: BmE0XY +.. section: Core and Builtins + +Fix a crash occurring when :c:func:`PyEval_GetFrame` is called while the +topmost Python frame is in a partially-initialized state. + +.. + +.. date: 2022-09-21-14-38-31 +.. gh-issue: 96848 +.. nonce: WuoLzU +.. section: Core and Builtins + +Fix command line parsing: reject :option:`-X int_max_str_digits <-X>` option +with no value (invalid) when the :envvar:`PYTHONINTMAXSTRDIGITS` environment +variable is set to a valid limit. Patch by Victor Stinner. + +.. + +.. date: 2022-09-18-08-47-40 +.. gh-issue: 96821 +.. nonce: Co2iOq +.. section: Core and Builtins + +Fix undefined behaviour in ``_testcapimodule.c``. + +.. + +.. date: 2022-09-16-19-02-40 +.. gh-issue: 95778 +.. nonce: cJmnst +.. section: Core and Builtins + +When :exc:`ValueError` is raised if an integer is larger than the limit, +mention the :func:`sys.set_int_max_str_digits` function in the error +message. Patch by Victor Stinner. + +.. + +.. date: 2022-09-05-19-20-44 +.. gh-issue: 96587 +.. nonce: bVxhX2 +.. section: Core and Builtins + +Correctly raise ``SyntaxError`` on exception groups (:pep:`654`) on python +versions prior to 3.11 + +.. + +.. bpo: 42316 +.. date: 2020-11-15-02-08-43 +.. nonce: LqdkWK +.. section: Core and Builtins + +Document some places where an assignment expression needs parentheses. + +.. + +.. date: 2022-10-16-15-31-50 +.. gh-issue: 98331 +.. nonce: Y5kPOX +.. section: Library + +Update the bundled copies of pip and setuptools to versions 22.3 and 65.5.0 +respectively. + +.. + +.. date: 2022-10-06-23-42-00 +.. gh-issue: 90985 +.. nonce: s280JY +.. section: Library + +Earlier in 3.11 we deprecated ``asyncio.Task.cancel("message")``. We +realized we were too harsh, and have undeprecated it. + +.. + +.. date: 2022-09-25-23-24-52 +.. gh-issue: 97545 +.. nonce: HZLSNt +.. section: Library + +Make Semaphore run faster. + +.. + +.. date: 2022-09-24-18-56-23 +.. gh-issue: 96865 +.. nonce: o9WUkW +.. section: Library + +fix Flag to use boundary CONFORM + +This restores previous Flag behavior of allowing flags with non-sequential +values to be combined; e.g. + +class Skip(Flag): TWO = 2 EIGHT = 8 + +Skip.TWO | Skip.EIGHT -> + +.. + +.. date: 2022-05-25-15-57-39 +.. gh-issue: 90155 +.. nonce: YMstB5 +.. section: Library + +Fix broken :class:`asyncio.Semaphore` when acquire is cancelled. + +.. + +.. date: 2022-10-02-10-58-52 +.. gh-issue: 97741 +.. nonce: 39l023 +.. section: Documentation + +Fix ``!`` in c domain ref target syntax via a ``conf.py`` patch, so it works +as intended to disable ref target resolution. + +.. + +.. date: 2022-05-20-18-42-10 +.. gh-issue: 93031 +.. nonce: c2RdJe +.. section: Documentation + +Update tutorial introduction output to use 3.10+ SyntaxError invalid range. + +.. + +.. date: 2022-10-20-17-49-50 +.. gh-issue: 95027 +.. nonce: viRpJB +.. section: Tests + +On Windows, when the Python test suite is run with the ``-jN`` option, the +ANSI code page is now used as the encoding for the stdout temporary file, +rather than using UTF-8 which can lead to decoding errors. Patch by Victor +Stinner. + +.. + +.. date: 2022-09-11-14-23-49 +.. gh-issue: 96729 +.. nonce: W4uBWL +.. section: Build + +Ensure that Windows releases built with ``Tools\msi\buildrelease.bat`` are +upgradable to and from official Python releases. + +.. + +.. date: 2022-10-19-20-00-28 +.. gh-issue: 98360 +.. nonce: O2m6YG +.. section: Windows + +Fixes :mod:`multiprocessing` spawning child processes on Windows from a +virtual environment to ensure that child processes that also use +:mod:`multiprocessing` to spawn more children will recognize that they are +in a virtual environment. + +.. + +.. date: 2022-10-19-19-35-37 +.. gh-issue: 98414 +.. nonce: FbHZuS +.. section: Windows + +Fix :file:`py.exe` launcher handling of ``-V:/`` option when +default preferences have been set in environment variables or configuration +files. + +.. + +.. date: 2022-09-29-23-08-49 +.. gh-issue: 90989 +.. nonce: no89Q2 +.. section: Windows + +Clarify some text in the Windows installer. + +.. + +.. date: 2022-10-05-15-26-58 +.. gh-issue: 97897 +.. nonce: Rf-C6u +.. section: macOS + +The macOS 13 SDK includes support for the ``mkfifoat`` and ``mknodat`` +system calls. Using the ``dir_fd`` option with either :func:`os.mkfifo` or +:func:`os.mknod` could result in a segfault if cpython is built with the +macOS 13 SDK but run on an earlier version of macOS. Prevent this by adding +runtime support for detection of these system calls ("weaklinking") as is +done for other newer syscalls on macOS. diff --git a/Misc/NEWS.d/next/Build/2022-09-11-14-23-49.gh-issue-96729.W4uBWL.rst b/Misc/NEWS.d/next/Build/2022-09-11-14-23-49.gh-issue-96729.W4uBWL.rst deleted file mode 100644 index b67cd20..0000000 --- a/Misc/NEWS.d/next/Build/2022-09-11-14-23-49.gh-issue-96729.W4uBWL.rst +++ /dev/null @@ -1,2 +0,0 @@ -Ensure that Windows releases built with ``Tools\msi\buildrelease.bat`` are -upgradable to and from official Python releases. diff --git a/Misc/NEWS.d/next/Core and Builtins/2020-11-15-02-08-43.bpo-42316.LqdkWK.rst b/Misc/NEWS.d/next/Core and Builtins/2020-11-15-02-08-43.bpo-42316.LqdkWK.rst deleted file mode 100644 index ea99780..0000000 --- a/Misc/NEWS.d/next/Core and Builtins/2020-11-15-02-08-43.bpo-42316.LqdkWK.rst +++ /dev/null @@ -1 +0,0 @@ -Document some places where an assignment expression needs parentheses. diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-09-05-19-20-44.gh-issue-96587.bVxhX2.rst b/Misc/NEWS.d/next/Core and Builtins/2022-09-05-19-20-44.gh-issue-96587.bVxhX2.rst deleted file mode 100644 index 37e9dcb..0000000 --- a/Misc/NEWS.d/next/Core and Builtins/2022-09-05-19-20-44.gh-issue-96587.bVxhX2.rst +++ /dev/null @@ -1,2 +0,0 @@ -Correctly raise ``SyntaxError`` on exception groups (:pep:`654`) on python -versions prior to 3.11 diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-09-16-19-02-40.gh-issue-95778.cJmnst.rst b/Misc/NEWS.d/next/Core and Builtins/2022-09-16-19-02-40.gh-issue-95778.cJmnst.rst deleted file mode 100644 index ebf6377..0000000 --- a/Misc/NEWS.d/next/Core and Builtins/2022-09-16-19-02-40.gh-issue-95778.cJmnst.rst +++ /dev/null @@ -1,3 +0,0 @@ -When :exc:`ValueError` is raised if an integer is larger than the limit, -mention the :func:`sys.set_int_max_str_digits` function in the error message. -Patch by Victor Stinner. diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-09-18-08-47-40.gh-issue-96821.Co2iOq.rst b/Misc/NEWS.d/next/Core and Builtins/2022-09-18-08-47-40.gh-issue-96821.Co2iOq.rst deleted file mode 100644 index 4fd0532..0000000 --- a/Misc/NEWS.d/next/Core and Builtins/2022-09-18-08-47-40.gh-issue-96821.Co2iOq.rst +++ /dev/null @@ -1 +0,0 @@ -Fix undefined behaviour in ``_testcapimodule.c``. diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-09-21-14-38-31.gh-issue-96848.WuoLzU.rst b/Misc/NEWS.d/next/Core and Builtins/2022-09-21-14-38-31.gh-issue-96848.WuoLzU.rst deleted file mode 100644 index a9b04ce..0000000 --- a/Misc/NEWS.d/next/Core and Builtins/2022-09-21-14-38-31.gh-issue-96848.WuoLzU.rst +++ /dev/null @@ -1,3 +0,0 @@ -Fix command line parsing: reject :option:`-X int_max_str_digits <-X>` option -with no value (invalid) when the :envvar:`PYTHONINTMAXSTRDIGITS` environment -variable is set to a valid limit. Patch by Victor Stinner. diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-09-21-16-06-37.gh-issue-96975.BmE0XY.rst b/Misc/NEWS.d/next/Core and Builtins/2022-09-21-16-06-37.gh-issue-96975.BmE0XY.rst deleted file mode 100644 index e6fcb84..0000000 --- a/Misc/NEWS.d/next/Core and Builtins/2022-09-21-16-06-37.gh-issue-96975.BmE0XY.rst +++ /dev/null @@ -1,2 +0,0 @@ -Fix a crash occurring when :c:func:`PyEval_GetFrame` is called while the -topmost Python frame is in a partially-initialized state. diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-10-03-13-35-48.gh-issue-97752.0xTjJY.rst b/Misc/NEWS.d/next/Core and Builtins/2022-10-03-13-35-48.gh-issue-97752.0xTjJY.rst deleted file mode 100644 index c656350..0000000 --- a/Misc/NEWS.d/next/Core and Builtins/2022-10-03-13-35-48.gh-issue-97752.0xTjJY.rst +++ /dev/null @@ -1,2 +0,0 @@ -Fix possible data corruption or crashes when accessing the ``f_back`` member -of newly-created generator or coroutine frames. diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-10-06-02-11-34.gh-issue-97002.Zvsk71.rst b/Misc/NEWS.d/next/Core and Builtins/2022-10-06-02-11-34.gh-issue-97002.Zvsk71.rst deleted file mode 100644 index 1f577e0..0000000 --- a/Misc/NEWS.d/next/Core and Builtins/2022-10-06-02-11-34.gh-issue-97002.Zvsk71.rst +++ /dev/null @@ -1,3 +0,0 @@ -Fix an issue where several frame objects could be backed by the same -interpreter frame, possibly leading to corrupted memory and hard crashes of -the interpreter. diff --git a/Misc/NEWS.d/next/Documentation/2022-05-20-18-42-10.gh-issue-93031.c2RdJe.rst b/Misc/NEWS.d/next/Documentation/2022-05-20-18-42-10.gh-issue-93031.c2RdJe.rst deleted file mode 100644 index c46b45d..0000000 --- a/Misc/NEWS.d/next/Documentation/2022-05-20-18-42-10.gh-issue-93031.c2RdJe.rst +++ /dev/null @@ -1 +0,0 @@ -Update tutorial introduction output to use 3.10+ SyntaxError invalid range. diff --git a/Misc/NEWS.d/next/Documentation/2022-10-02-10-58-52.gh-issue-97741.39l023.rst b/Misc/NEWS.d/next/Documentation/2022-10-02-10-58-52.gh-issue-97741.39l023.rst deleted file mode 100644 index 8da9c92..0000000 --- a/Misc/NEWS.d/next/Documentation/2022-10-02-10-58-52.gh-issue-97741.39l023.rst +++ /dev/null @@ -1,2 +0,0 @@ -Fix ``!`` in c domain ref target syntax via a ``conf.py`` patch, so it works -as intended to disable ref target resolution. diff --git a/Misc/NEWS.d/next/Library/2022-05-25-15-57-39.gh-issue-90155.YMstB5.rst b/Misc/NEWS.d/next/Library/2022-05-25-15-57-39.gh-issue-90155.YMstB5.rst deleted file mode 100644 index 8def769..0000000 --- a/Misc/NEWS.d/next/Library/2022-05-25-15-57-39.gh-issue-90155.YMstB5.rst +++ /dev/null @@ -1 +0,0 @@ -Fix broken :class:`asyncio.Semaphore` when acquire is cancelled. diff --git a/Misc/NEWS.d/next/Library/2022-09-24-18-56-23.gh-issue-96865.o9WUkW.rst b/Misc/NEWS.d/next/Library/2022-09-24-18-56-23.gh-issue-96865.o9WUkW.rst deleted file mode 100644 index b054fde..0000000 --- a/Misc/NEWS.d/next/Library/2022-09-24-18-56-23.gh-issue-96865.o9WUkW.rst +++ /dev/null @@ -1,9 +0,0 @@ -fix Flag to use boundary CONFORM - -This restores previous Flag behavior of allowing flags with non-sequential values to be combined; e.g. - - class Skip(Flag): - TWO = 2 - EIGHT = 8 - - Skip.TWO | Skip.EIGHT -> diff --git a/Misc/NEWS.d/next/Library/2022-09-25-23-24-52.gh-issue-97545.HZLSNt.rst b/Misc/NEWS.d/next/Library/2022-09-25-23-24-52.gh-issue-97545.HZLSNt.rst deleted file mode 100644 index a53902e..0000000 --- a/Misc/NEWS.d/next/Library/2022-09-25-23-24-52.gh-issue-97545.HZLSNt.rst +++ /dev/null @@ -1 +0,0 @@ -Make Semaphore run faster. diff --git a/Misc/NEWS.d/next/Library/2022-10-06-23-42-00.gh-issue-90985.s280JY.rst b/Misc/NEWS.d/next/Library/2022-10-06-23-42-00.gh-issue-90985.s280JY.rst deleted file mode 100644 index 964aa39..0000000 --- a/Misc/NEWS.d/next/Library/2022-10-06-23-42-00.gh-issue-90985.s280JY.rst +++ /dev/null @@ -1 +0,0 @@ -Earlier in 3.11 we deprecated ``asyncio.Task.cancel("message")``. We realized we were too harsh, and have undeprecated it. diff --git a/Misc/NEWS.d/next/Library/2022-10-16-15-31-50.gh-issue-98331.Y5kPOX.rst b/Misc/NEWS.d/next/Library/2022-10-16-15-31-50.gh-issue-98331.Y5kPOX.rst deleted file mode 100644 index b4cf943..0000000 --- a/Misc/NEWS.d/next/Library/2022-10-16-15-31-50.gh-issue-98331.Y5kPOX.rst +++ /dev/null @@ -1 +0,0 @@ -Update the bundled copies of pip and setuptools to versions 22.3 and 65.5.0 respectively. diff --git a/Misc/NEWS.d/next/Security/2022-09-07-10-42-00.gh-issue-97514.Yggdsl.rst b/Misc/NEWS.d/next/Security/2022-09-07-10-42-00.gh-issue-97514.Yggdsl.rst deleted file mode 100644 index 02d95b5..0000000 --- a/Misc/NEWS.d/next/Security/2022-09-07-10-42-00.gh-issue-97514.Yggdsl.rst +++ /dev/null @@ -1,15 +0,0 @@ -On Linux the :mod:`multiprocessing` module returns to using filesystem backed -unix domain sockets for communication with the *forkserver* process instead of -the Linux abstract socket namespace. Only code that chooses to use the -:ref:`"forkserver" start method ` is affected. - -Abstract sockets have no permissions and could allow any user on the system in -the same `network namespace -`_ (often the -whole system) to inject code into the multiprocessing *forkserver* process. -This was a potential privilege escalation. Filesystem based socket permissions -restrict this to the *forkserver* process user as was the default in Python 3.8 -and earlier. - -This prevents Linux `CVE-2022-42919 -`_. diff --git a/Misc/NEWS.d/next/Security/2022-09-28-17-09-37.gh-issue-97616.K1e3Xs.rst b/Misc/NEWS.d/next/Security/2022-09-28-17-09-37.gh-issue-97616.K1e3Xs.rst deleted file mode 100644 index 721427f..0000000 --- a/Misc/NEWS.d/next/Security/2022-09-28-17-09-37.gh-issue-97616.K1e3Xs.rst +++ /dev/null @@ -1,3 +0,0 @@ -Fix multiplying a list by an integer (``list *= int``): detect the integer -overflow when the new allocated length is close to the maximum size. Issue -reported by Jordan Limor. Patch by Victor Stinner. diff --git a/Misc/NEWS.d/next/Tests/2022-10-20-17-49-50.gh-issue-95027.viRpJB.rst b/Misc/NEWS.d/next/Tests/2022-10-20-17-49-50.gh-issue-95027.viRpJB.rst deleted file mode 100644 index 8bf1a9d..0000000 --- a/Misc/NEWS.d/next/Tests/2022-10-20-17-49-50.gh-issue-95027.viRpJB.rst +++ /dev/null @@ -1,4 +0,0 @@ -On Windows, when the Python test suite is run with the ``-jN`` option, the -ANSI code page is now used as the encoding for the stdout temporary file, -rather than using UTF-8 which can lead to decoding errors. Patch by Victor -Stinner. diff --git a/Misc/NEWS.d/next/Windows/2022-09-29-23-08-49.gh-issue-90989.no89Q2.rst b/Misc/NEWS.d/next/Windows/2022-09-29-23-08-49.gh-issue-90989.no89Q2.rst deleted file mode 100644 index 34fffdf..0000000 --- a/Misc/NEWS.d/next/Windows/2022-09-29-23-08-49.gh-issue-90989.no89Q2.rst +++ /dev/null @@ -1 +0,0 @@ -Clarify some text in the Windows installer. diff --git a/Misc/NEWS.d/next/Windows/2022-10-19-19-35-37.gh-issue-98414.FbHZuS.rst b/Misc/NEWS.d/next/Windows/2022-10-19-19-35-37.gh-issue-98414.FbHZuS.rst deleted file mode 100644 index df07b7f..0000000 --- a/Misc/NEWS.d/next/Windows/2022-10-19-19-35-37.gh-issue-98414.FbHZuS.rst +++ /dev/null @@ -1,3 +0,0 @@ -Fix :file:`py.exe` launcher handling of ``-V:/`` option when -default preferences have been set in environment variables or configuration -files. diff --git a/Misc/NEWS.d/next/Windows/2022-10-19-20-00-28.gh-issue-98360.O2m6YG.rst b/Misc/NEWS.d/next/Windows/2022-10-19-20-00-28.gh-issue-98360.O2m6YG.rst deleted file mode 100644 index 61c1e5e..0000000 --- a/Misc/NEWS.d/next/Windows/2022-10-19-20-00-28.gh-issue-98360.O2m6YG.rst +++ /dev/null @@ -1,4 +0,0 @@ -Fixes :mod:`multiprocessing` spawning child processes on Windows from a -virtual environment to ensure that child processes that also use -:mod:`multiprocessing` to spawn more children will recognize that they are -in a virtual environment. diff --git a/Misc/NEWS.d/next/macOS/2022-10-05-15-26-58.gh-issue-97897.Rf-C6u.rst b/Misc/NEWS.d/next/macOS/2022-10-05-15-26-58.gh-issue-97897.Rf-C6u.rst deleted file mode 100644 index 0d21e98..0000000 --- a/Misc/NEWS.d/next/macOS/2022-10-05-15-26-58.gh-issue-97897.Rf-C6u.rst +++ /dev/null @@ -1,6 +0,0 @@ -The macOS 13 SDK includes support for the ``mkfifoat`` and ``mknodat`` system calls. -Using the ``dir_fd`` option with either :func:`os.mkfifo` or :func:`os.mknod` could result in a -segfault if cpython is built with the macOS 13 SDK but run on an earlier -version of macOS. Prevent this by adding runtime support for detection of -these system calls ("weaklinking") as is done for other newer syscalls on -macOS. diff --git a/README.rst b/README.rst index 2e7eb04..8b5b52a 100644 --- a/README.rst +++ b/README.rst @@ -1,5 +1,5 @@ -This is Python version 3.11.0 release candidate 2 -================================================= +This is Python version 3.11.0 +============================= .. image:: https://github.com/python/cpython/workflows/Tests/badge.svg :alt: CPython build status on GitHub Actions -- cgit v0.12