diff options
Diffstat (limited to 'Doc/library')
| -rw-r--r-- | Doc/library/annotationlib.rst | 104 | ||||
| -rw-r--r-- | Doc/library/ast.rst | 34 | ||||
| -rw-r--r-- | Doc/library/asyncio-eventloop.rst | 10 | ||||
| -rw-r--r-- | Doc/library/cmdline.rst | 2 | ||||
| -rw-r--r-- | Doc/library/ctypes.rst | 15 | ||||
| -rw-r--r-- | Doc/library/curses.rst | 29 | ||||
| -rw-r--r-- | Doc/library/fnmatch.rst | 2 | ||||
| -rw-r--r-- | Doc/library/gc.rst | 5 | ||||
| -rw-r--r-- | Doc/library/glob.rst | 2 | ||||
| -rw-r--r-- | Doc/library/heapq.rst | 110 | ||||
| -rw-r--r-- | Doc/library/io.rst | 3 | ||||
| -rw-r--r-- | Doc/library/os.rst | 1 | ||||
| -rw-r--r-- | Doc/library/pathlib.rst | 8 | ||||
| -rw-r--r-- | Doc/library/pdb.rst | 8 | ||||
| -rw-r--r-- | Doc/library/platform.rst | 44 | ||||
| -rw-r--r-- | Doc/library/re.rst | 12 | ||||
| -rw-r--r-- | Doc/library/subprocess.rst | 18 | ||||
| -rw-r--r-- | Doc/library/sys.rst | 58 | ||||
| -rw-r--r-- | Doc/library/threading.rst | 127 | ||||
| -rw-r--r-- | Doc/library/urllib.request.rst | 18 |
20 files changed, 524 insertions, 86 deletions
diff --git a/Doc/library/annotationlib.rst b/Doc/library/annotationlib.rst index 7946cd3a3ce..ff9578b6088 100644 --- a/Doc/library/annotationlib.rst +++ b/Doc/library/annotationlib.rst @@ -40,7 +40,7 @@ The :func:`get_annotations` function is the main entry point for retrieving annotations. Given a function, class, or module, it returns an annotations dictionary in the requested format. This module also provides functionality for working directly with the :term:`annotate function` -that is used to evaluate annotations, such as :func:`get_annotate_function` +that is used to evaluate annotations, such as :func:`get_annotate_from_class_namespace` and :func:`call_annotate_function`, as well as the :func:`call_evaluate_function` function for working with :term:`evaluate functions <evaluate function>`. @@ -132,7 +132,7 @@ Classes Values are real annotation values (as per :attr:`Format.VALUE` format) for defined values, and :class:`ForwardRef` proxies for undefined - values. Real objects may contain references to, :class:`ForwardRef` + values. Real objects may contain references to :class:`ForwardRef` proxy objects. .. attribute:: STRING @@ -172,14 +172,21 @@ Classes :class:`~ForwardRef`. The string may not be exactly equivalent to the original source. - .. method:: evaluate(*, owner=None, globals=None, locals=None, type_params=None) + .. method:: evaluate(*, owner=None, globals=None, locals=None, type_params=None, format=Format.VALUE) Evaluate the forward reference, returning its value. - This may throw an exception, such as :exc:`NameError`, if the forward + If the *format* argument is :attr:`~Format.VALUE` (the default), + this method may throw an exception, such as :exc:`NameError`, if the forward reference refers to a name that cannot be resolved. The arguments to this method can be used to provide bindings for names that would otherwise - be undefined. + be undefined. If the *format* argument is :attr:`~Format.FORWARDREF`, + the method will never throw an exception, but may return a :class:`~ForwardRef` + instance. For example, if the forward reference object contains the code + ``list[undefined]``, where ``undefined`` is a name that is not defined, + evaluating it with the :attr:`~Format.FORWARDREF` format will return + ``list[ForwardRef('undefined')]``. If the *format* argument is + :attr:`~Format.STRING`, the method will return :attr:`~ForwardRef.__forward_arg__`. The *owner* parameter provides the preferred mechanism for passing scope information to this method. The owner of a :class:`~ForwardRef` is the @@ -300,15 +307,13 @@ Functions .. versionadded:: 3.14 -.. function:: get_annotate_function(obj) +.. function:: get_annotate_from_class_namespace(namespace) - Retrieve the :term:`annotate function` for *obj*. Return :const:`!None` - if *obj* does not have an annotate function. *obj* may be a class, function, - module, or a namespace dictionary for a class. The last case is useful during - class creation, e.g. in the ``__new__`` method of a metaclass. - - This is usually equivalent to accessing the :attr:`~object.__annotate__` - attribute of *obj*, but access through this public function is preferred. + Retrieve the :term:`annotate function` from a class namespace dictionary *namespace*. + Return :const:`!None` if the namespace does not contain an annotate function. + This is primarily useful before the class has been fully created (e.g., in a metaclass); + after the class exists, the annotate function can be retrieved with ``cls.__annotate__``. + See :ref:`below <annotationlib-metaclass>` for an example using this function in a metaclass. .. versionadded:: 3.14 @@ -407,3 +412,76 @@ Functions .. versionadded:: 3.14 + +Recipes +------- + +.. _annotationlib-metaclass: + +Using annotations in a metaclass +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A :ref:`metaclass <metaclasses>` may want to inspect or even modify the annotations +in a class body during class creation. Doing so requires retrieving annotations +from the class namespace dictionary. For classes created with +``from __future__ import annotations``, the annotations will be in the ``__annotations__`` +key of the dictionary. For other classes with annotations, +:func:`get_annotate_from_class_namespace` can be used to get the +annotate function, and :func:`call_annotate_function` can be used to call it and +retrieve the annotations. Using the :attr:`~Format.FORWARDREF` format will usually +be best, because this allows the annotations to refer to names that cannot yet be +resolved when the class is created. + +To modify the annotations, it is best to create a wrapper annotate function +that calls the original annotate function, makes any necessary adjustments, and +returns the result. + +Below is an example of a metaclass that filters out all :class:`typing.ClassVar` +annotations from the class and puts them in a separate attribute: + +.. code-block:: python + + import annotationlib + import typing + + class ClassVarSeparator(type): + def __new__(mcls, name, bases, ns): + if "__annotations__" in ns: # from __future__ import annotations + annotations = ns["__annotations__"] + classvar_keys = { + key for key, value in annotations.items() + # Use string comparison for simplicity; a more robust solution + # could use annotationlib.ForwardRef.evaluate + if value.startswith("ClassVar") + } + classvars = {key: annotations[key] for key in classvar_keys} + ns["__annotations__"] = { + key: value for key, value in annotations.items() + if key not in classvar_keys + } + wrapped_annotate = None + elif annotate := annotationlib.get_annotate_from_class_namespace(ns): + annotations = annotationlib.call_annotate_function( + annotate, format=annotationlib.Format.FORWARDREF + ) + classvar_keys = { + key for key, value in annotations.items() + if typing.get_origin(value) is typing.ClassVar + } + classvars = {key: annotations[key] for key in classvar_keys} + + def wrapped_annotate(format): + annos = annotationlib.call_annotate_function(annotate, format, owner=typ) + return {key: value for key, value in annos.items() if key not in classvar_keys} + + else: # no annotations + classvars = {} + wrapped_annotate = None + typ = super().__new__(mcls, name, bases, ns) + + if wrapped_annotate is not None: + # Wrap the original __annotate__ with a wrapper that removes ClassVars + typ.__annotate__ = wrapped_annotate + typ.classvars = classvars # Store the ClassVars in a separate attribute + return typ + diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index 776c63d1f0f..c9ae0abdd66 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -1,4 +1,4 @@ -:mod:`!ast` --- Abstract Syntax Trees +:mod:`!ast` --- Abstract syntax trees ===================================== .. module:: ast @@ -29,7 +29,7 @@ compiled into a Python code object using the built-in :func:`compile` function. .. _abstract-grammar: -Abstract Grammar +Abstract grammar ---------------- The abstract grammar is currently defined as follows: @@ -2156,10 +2156,10 @@ Async and await of :class:`ast.operator`, :class:`ast.unaryop`, :class:`ast.cmpop`, :class:`ast.boolop` and :class:`ast.expr_context`) on the returned tree will be singletons. Changes to one will be reflected in all other - occurrences of the same value (e.g. :class:`ast.Add`). + occurrences of the same value (for example, :class:`ast.Add`). -:mod:`ast` Helpers +:mod:`ast` helpers ------------------ Apart from the node classes, the :mod:`ast` module defines these utility functions @@ -2484,7 +2484,7 @@ and classes for traversing abstract syntax trees: .. _ast-compiler-flags: -Compiler Flags +Compiler flags -------------- The following flags may be passed to :func:`compile` in order to change @@ -2533,7 +2533,7 @@ effects on the compilation of a program: .. _ast-cli: -Command-Line Usage +Command-line usage ------------------ .. versionadded:: 3.9 @@ -2572,6 +2572,28 @@ The following options are accepted: Indentation of nodes in AST (number of spaces). +.. option:: --feature-version <version> + + Python version in the format 3.x (for example, 3.10). Defaults to the + current version of the interpreter. + + .. versionadded:: next + +.. option:: -O <level> + --optimize <level> + + Optimization level for parser. Defaults to no optimization. + + .. versionadded:: next + +.. option:: --show-empty + + Show empty lists and fields that are ``None``. Defaults to not showing empty + objects. + + .. versionadded:: next + + If :file:`infile` is specified its contents are parsed to AST and dumped to stdout. Otherwise, the content is read from stdin. diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 8f561744fe4..e25f6e52efc 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -361,7 +361,7 @@ Creating Futures and Tasks .. versionadded:: 3.5.2 -.. method:: loop.create_task(coro, *, name=None, context=None) +.. method:: loop.create_task(coro, *, name=None, context=None, eager_start=None) Schedule the execution of :ref:`coroutine <coroutine>` *coro*. Return a :class:`Task` object. @@ -377,12 +377,20 @@ Creating Futures and Tasks custom :class:`contextvars.Context` for the *coro* to run in. The current context copy is created when no *context* is provided. + An optional keyword-only *eager_start* argument allows specifying + if the task should execute eagerly during the call to create_task, + or be scheduled later. If *eager_start* is not passed the mode set + by :meth:`loop.set_task_factory` will be used. + .. versionchanged:: 3.8 Added the *name* parameter. .. versionchanged:: 3.11 Added the *context* parameter. + .. versionchanged:: next + Added the *eager_start* parameter. + .. method:: loop.set_task_factory(factory) Set a task factory that will be used by diff --git a/Doc/library/cmdline.rst b/Doc/library/cmdline.rst index 85e82f6292a..f7ae2133a70 100644 --- a/Doc/library/cmdline.rst +++ b/Doc/library/cmdline.rst @@ -27,7 +27,7 @@ The following modules have a command-line interface. * :mod:`pdb` * :ref:`pickle <pickle-cli>` * :ref:`pickletools <pickletools-cli>` -* :mod:`platform` +* :ref:`platform <platform-cli>` * :mod:`poplib` * :ref:`profile <profile-cli>` * :mod:`pstats` diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 2825590400c..1b78b33b69f 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -2754,6 +2754,16 @@ fields, or any other data types containing pointer type fields. when :attr:`_fields_` is assigned, otherwise it will have no effect. Setting this attribute to 0 is the same as not setting it at all. + This is only implemented for the MSVC-compatible memory layout. + + .. deprecated-removed:: next 3.19 + + For historical reasons, if :attr:`!_pack_` is non-zero, + the MSVC-compatible layout will be used by default. + On non-Windows platforms, this default is deprecated and is slated to + become an error in Python 3.19. + If it is intended, set :attr:`~Structure._layout_` to ``'ms'`` + explicitly. .. attribute:: _align_ @@ -2782,12 +2792,15 @@ fields, or any other data types containing pointer type fields. Currently the default will be: - On Windows: ``"ms"`` - - When :attr:`~Structure._pack_` is specified: ``"ms"`` + - When :attr:`~Structure._pack_` is specified: ``"ms"``. + (This is deprecated; see :attr:`~Structure._pack_` documentation.) - Otherwise: ``"gcc-sysv"`` :attr:`!_layout_` must already be defined when :attr:`~Structure._fields_` is assigned, otherwise it will have no effect. + .. versionadded:: next + .. attribute:: _anonymous_ An optional sequence that lists the names of unnamed (anonymous) fields. diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst index 6c7fc721a3e..4bccfdde664 100644 --- a/Doc/library/curses.rst +++ b/Doc/library/curses.rst @@ -68,6 +68,21 @@ The module :mod:`curses` defines the following exception: The module :mod:`curses` defines the following functions: +.. function:: assume_default_colors(fg, bg) + + Allow use of default values for colors on terminals supporting this feature. + Use this to support transparency in your application. + + * Assign terminal default foreground/background colors to color number ``-1``. + So ``init_pair(x, COLOR_RED, -1)`` will initialize pair *x* as red + on default background and ``init_pair(x, -1, COLOR_BLUE)`` will + initialize pair *x* as default foreground on blue. + + * Change the definition of the color-pair ``0`` to ``(fg, bg)``. + + .. versionadded:: next + + .. function:: baudrate() Return the output speed of the terminal in bits per second. On software @@ -290,9 +305,11 @@ The module :mod:`curses` defines the following functions: Change the definition of a color-pair. It takes three arguments: the number of the color-pair to be changed, the foreground color number, and the background color number. The value of *pair_number* must be between ``1`` and - ``COLOR_PAIRS - 1`` (the ``0`` color pair is wired to white on black and cannot - be changed). The value of *fg* and *bg* arguments must be between ``0`` and - ``COLORS - 1``, or, after calling :func:`use_default_colors`, ``-1``. + ``COLOR_PAIRS - 1`` (the ``0`` color pair can only be changed by + :func:`use_default_colors` and :func:`assume_default_colors`). + The value of *fg* and *bg* arguments must be between ``0`` and + ``COLORS - 1``, or, after calling :func:`!use_default_colors` or + :func:`!assume_default_colors`, ``-1``. If the color-pair was previously initialized, the screen is refreshed and all occurrences of that color-pair are changed to the new definition. @@ -678,11 +695,7 @@ The module :mod:`curses` defines the following functions: .. function:: use_default_colors() - Allow use of default values for colors on terminals supporting this feature. Use - this to support transparency in your application. The default color is assigned - to the color number ``-1``. After calling this function, ``init_pair(x, - curses.COLOR_RED, -1)`` initializes, for instance, color pair *x* to a red - foreground color on the default background. + Equivalent to ``assume_default_colors(-1, -1)``. .. function:: wrapper(func, /, *args, **kwargs) diff --git a/Doc/library/fnmatch.rst b/Doc/library/fnmatch.rst index 8674e855b8e..12e61bc36f5 100644 --- a/Doc/library/fnmatch.rst +++ b/Doc/library/fnmatch.rst @@ -111,7 +111,7 @@ functions: :func:`fnmatch`, :func:`fnmatchcase`, :func:`.filter`. >>> >>> regex = fnmatch.translate('*.txt') >>> regex - '(?s:.*\\.txt)\\Z' + '(?s:.*\\.txt)\\z' >>> reobj = re.compile(regex) >>> reobj.match('foobar.txt') <re.Match object; span=(0, 10), match='foobar.txt'> diff --git a/Doc/library/gc.rst b/Doc/library/gc.rst index 480a9dec7f1..7ccb0e6bdf9 100644 --- a/Doc/library/gc.rst +++ b/Doc/library/gc.rst @@ -128,6 +128,11 @@ The :mod:`gc` module provides the following functions: starts. For each collection, all the objects in the young generation and some fraction of the old generation is collected. + In the free-threaded build, the increase in process memory usage is also + checked before running the collector. If the memory usage has not increased + by 10% since the last collection and the net number of object allocations + has not exceeded 40 times *threshold0*, the collection is not run. + The fraction of the old generation that is collected is **inversely** proportional to *threshold1*. The larger *threshold1* is, the slower objects in the old generation are collected. diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst index 684466d354a..59ad1b07f27 100644 --- a/Doc/library/glob.rst +++ b/Doc/library/glob.rst @@ -134,7 +134,7 @@ The :mod:`glob` module defines the following functions: >>> >>> regex = glob.translate('**/*.txt', recursive=True, include_hidden=True) >>> regex - '(?s:(?:.+/)?[^/]*\\.txt)\\Z' + '(?s:(?:.+/)?[^/]*\\.txt)\\z' >>> reobj = re.compile(regex) >>> reobj.match('foo/bar/baz.txt') <re.Match object; span=(0, 15), match='foo/bar/baz.txt'> diff --git a/Doc/library/heapq.rst b/Doc/library/heapq.rst index d3c4b920ba5..2bd0162a982 100644 --- a/Doc/library/heapq.rst +++ b/Doc/library/heapq.rst @@ -16,40 +16,56 @@ This module provides an implementation of the heap queue algorithm, also known as the priority queue algorithm. -Heaps are binary trees for which every parent node has a value less than or -equal to any of its children. We refer to this condition as the heap invariant. +Min-heaps are binary trees for which every parent node has a value less than +or equal to any of its children. +We refer to this condition as the heap invariant. -This implementation uses arrays for which -``heap[k] <= heap[2*k+1]`` and ``heap[k] <= heap[2*k+2]`` for all *k*, counting -elements from zero. For the sake of comparison, non-existing elements are -considered to be infinite. The interesting property of a heap is that its -smallest element is always the root, ``heap[0]``. +For min-heaps, this implementation uses lists for which +``heap[k] <= heap[2*k+1]`` and ``heap[k] <= heap[2*k+2]`` for all *k* for which +the compared elements exist. Elements are counted from zero. The interesting +property of a min-heap is that its smallest element is always the root, +``heap[0]``. -The API below differs from textbook heap algorithms in two aspects: (a) We use -zero-based indexing. This makes the relationship between the index for a node -and the indexes for its children slightly less obvious, but is more suitable -since Python uses zero-based indexing. (b) Our pop method returns the smallest -item, not the largest (called a "min heap" in textbooks; a "max heap" is more -common in texts because of its suitability for in-place sorting). +Max-heaps satisfy the reverse invariant: every parent node has a value +*greater* than any of its children. These are implemented as lists for which +``maxheap[2*k+1] <= maxheap[k]`` and ``maxheap[2*k+2] <= maxheap[k]`` for all +*k* for which the compared elements exist. +The root, ``maxheap[0]``, contains the *largest* element; +``heap.sort(reverse=True)`` maintains the max-heap invariant. -These two make it possible to view the heap as a regular Python list without -surprises: ``heap[0]`` is the smallest item, and ``heap.sort()`` maintains the -heap invariant! +The :mod:`!heapq` API differs from textbook heap algorithms in two aspects: (a) +We use zero-based indexing. This makes the relationship between the index for +a node and the indexes for its children slightly less obvious, but is more +suitable since Python uses zero-based indexing. (b) Textbooks often focus on +max-heaps, due to their suitability for in-place sorting. Our implementation +favors min-heaps as they better correspond to Python :class:`lists <list>`. -To create a heap, use a list initialized to ``[]``, or you can transform a -populated list into a heap via function :func:`heapify`. +These two aspects make it possible to view the heap as a regular Python list +without surprises: ``heap[0]`` is the smallest item, and ``heap.sort()`` +maintains the heap invariant! -The following functions are provided: +Like :meth:`list.sort`, this implementation uses only the ``<`` operator +for comparisons, for both min-heaps and max-heaps. + +In the API below, and in this documentation, the unqualified term *heap* +generally refers to a min-heap. +The API for max-heaps is named using a ``_max`` suffix. + +To create a heap, use a list initialized as ``[]``, or transform an existing list +into a min-heap or max-heap using the :func:`heapify` or :func:`heapify_max` +functions, respectively. + +The following functions are provided for min-heaps: .. function:: heappush(heap, item) - Push the value *item* onto the *heap*, maintaining the heap invariant. + Push the value *item* onto the *heap*, maintaining the min-heap invariant. .. function:: heappop(heap) - Pop and return the smallest item from the *heap*, maintaining the heap + Pop and return the smallest item from the *heap*, maintaining the min-heap invariant. If the heap is empty, :exc:`IndexError` is raised. To access the smallest item without popping it, use ``heap[0]``. @@ -63,7 +79,7 @@ The following functions are provided: .. function:: heapify(x) - Transform list *x* into a heap, in-place, in linear time. + Transform list *x* into a min-heap, in-place, in linear time. .. function:: heapreplace(heap, item) @@ -82,6 +98,56 @@ The following functions are provided: on the heap. +For max-heaps, the following functions are provided: + + +.. function:: heapify_max(x) + + Transform list *x* into a max-heap, in-place, in linear time. + + .. versionadded:: next + + +.. function:: heappush_max(heap, item) + + Push the value *item* onto the max-heap *heap*, maintaining the max-heap + invariant. + + .. versionadded:: next + + +.. function:: heappop_max(heap) + + Pop and return the largest item from the max-heap *heap*, maintaining the + max-heap invariant. If the max-heap is empty, :exc:`IndexError` is raised. + To access the largest item without popping it, use ``maxheap[0]``. + + .. versionadded:: next + + +.. function:: heappushpop_max(heap, item) + + Push *item* on the max-heap *heap*, then pop and return the largest item + from *heap*. + The combined action runs more efficiently than :func:`heappush_max` + followed by a separate call to :func:`heappop_max`. + + .. versionadded:: next + + +.. function:: heapreplace_max(heap, item) + + Pop and return the largest item from the max-heap *heap* and also push the + new *item*. + The max-heap size doesn't change. If the max-heap is empty, + :exc:`IndexError` is raised. + + The value returned may be smaller than the *item* added. Refer to the + analogous function :func:`heapreplace` for detailed usage notes. + + .. versionadded:: next + + The module also offers three general purpose functions based on heaps. diff --git a/Doc/library/io.rst b/Doc/library/io.rst index fcd7afea354..3aa2f35f05e 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -965,7 +965,8 @@ Text I/O :class:`TextIOBase`. *encoding* gives the name of the encoding that the stream will be decoded or - encoded with. It defaults to :func:`locale.getencoding`. + encoded with. In :ref:`UTF-8 Mode <utf8-mode>`, this defaults to UTF-8. + Otherwise, it defaults to :func:`locale.getencoding`. ``encoding="locale"`` can be used to specify the current locale's encoding explicitly. See :ref:`io-text-encoding` for more information. diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 54a5d3b98e8..1e54cfec609 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -2338,6 +2338,7 @@ features: This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to supply :ref:`paths relative to directory descriptors <dir_fd>`, and :ref:`not following symlinks <follow_symlinks>`. + The default value of *follow_symlinks* is ``False`` on Windows. .. audit-event:: os.link src,dst,src_dir_fd,dst_dir_fd os.link diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index b8298690286..acb91812818 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -872,10 +872,10 @@ conforming to :rfc:`8089`. .. versionadded:: 3.13 .. versionchanged:: next - If a URL authority (e.g. a hostname) is present and resolves to a local - address, it is discarded. If an authority is present and *doesn't* - resolve to a local address, then on Windows a UNC path is returned (as - before), and on other platforms a :exc:`ValueError` is raised. + The URL authority is discarded if it matches the local hostname. + Otherwise, if the authority isn't empty or ``localhost``, then on + Windows a UNC path is returned (as before), and on other platforms a + :exc:`ValueError` is raised. .. method:: Path.as_uri() diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst index 3c8c0707499..a0304edddf6 100644 --- a/Doc/library/pdb.rst +++ b/Doc/library/pdb.rst @@ -243,7 +243,7 @@ The ``run*`` functions and :func:`set_trace` are aliases for instantiating the access further features, you have to do this yourself: .. class:: Pdb(completekey='tab', stdin=None, stdout=None, skip=None, \ - nosigint=False, readrc=True, mode=None, backend=None) + nosigint=False, readrc=True, mode=None, backend=None, colorize=False) :class:`Pdb` is the debugger class. @@ -273,6 +273,9 @@ access further features, you have to do this yourself: is passed, the default backend will be used. See :func:`set_default_backend`. Otherwise the supported backends are ``'settrace'`` and ``'monitoring'``. + The *colorize* argument, if set to ``True``, will enable colorized output in the + debugger, if color is supported. This will highlight source code displayed in pdb. + Example call to enable tracing with *skip*:: import pdb; pdb.Pdb(skip=['django.*']).set_trace() @@ -295,6 +298,9 @@ access further features, you have to do this yourself: .. versionadded:: 3.14 Added the *backend* argument. + .. versionadded:: 3.14 + Added the *colorize* argument. + .. versionchanged:: 3.14 Inline breakpoints like :func:`breakpoint` or :func:`pdb.set_trace` will always stop the program at calling frame, ignoring the *skip* pattern (if any). diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst index cfe1e7ba48d..5c999054323 100644 --- a/Doc/library/platform.rst +++ b/Doc/library/platform.rst @@ -17,7 +17,7 @@ section. -Cross Platform +Cross platform -------------- @@ -188,7 +188,7 @@ Cross Platform :attr:`processor` is resolved late instead of immediately. -Java Platform +Java platform ------------- @@ -206,7 +206,7 @@ Java Platform and was only useful for Jython support. -Windows Platform +Windows platform ---------------- @@ -240,7 +240,7 @@ Windows Platform .. versionadded:: 3.8 -macOS Platform +macOS platform -------------- .. function:: mac_ver(release='', versioninfo=('','',''), machine='') @@ -252,7 +252,7 @@ macOS Platform Entries which cannot be determined are set to ``''``. All tuple entries are strings. -iOS Platform +iOS platform ------------ .. function:: ios_ver(system='', release='', model='', is_simulator=False) @@ -271,7 +271,7 @@ iOS Platform parameters. -Unix Platforms +Unix platforms -------------- .. function:: libc_ver(executable=sys.executable, lib='', version='', chunksize=16384) @@ -287,7 +287,7 @@ Unix Platforms The file is read and scanned in chunks of *chunksize* bytes. -Linux Platforms +Linux platforms --------------- .. function:: freedesktop_os_release() @@ -325,7 +325,7 @@ Linux Platforms .. versionadded:: 3.10 -Android Platform +Android platform ---------------- .. function:: android_ver(release="", api_level=0, manufacturer="", \ @@ -360,6 +360,34 @@ Android Platform .. versionadded:: 3.13 +.. _platform-cli: + +Command-line usage +------------------ + +:mod:`platform` can also be invoked directly using the :option:`-m` +switch of the interpreter:: + + python -m platform [--terse] [--nonaliased] [{nonaliased,terse} ...] + +The following options are accepted: + +.. program:: platform + +.. option:: --terse + + Print terse information about the platform. This is equivalent to + calling :func:`platform.platform` with the *terse* argument set to ``True``. + +.. option:: --nonaliased + + Print platform information without system/OS name aliasing. This is + equivalent to calling :func:`platform.platform` with the *aliased* argument + set to ``True``. + +You can also pass one or more positional arguments (``terse``, ``nonaliased``) +to explicitly control the output format. These behave similarly to their +corresponding options. Miscellaneous ------------- diff --git a/Doc/library/re.rst b/Doc/library/re.rst index a91bac53fb4..0ee2d68bcbe 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -266,7 +266,7 @@ The special characters are: not a word boundary as outside a set, and numeric escapes such as ``\1`` are always octal escapes, not group references. Special sequences which do not match a single character such as ``\A`` - and ``\Z`` are not allowed. + and ``\z`` are not allowed. .. index:: single: ^ (caret); in regular expressions @@ -661,11 +661,17 @@ character ``'$'``. matches characters which are neither alphanumeric in the current locale nor the underscore. -.. index:: single: \Z; in regular expressions +.. index:: single: \z; in regular expressions + single: \Z; in regular expressions -``\Z`` +``\z`` Matches only at the end of the string. + .. versionadded:: next + +``\Z`` + The same as ``\z``. For compatibility with old Python versions. + .. index:: single: \a; in regular expressions single: \b; in regular expressions diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 05d09e304b3..028a7861f36 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -1525,6 +1525,24 @@ handling consistency are valid for these functions. Notes ----- +.. _subprocess-timeout-behavior: + +Timeout Behavior +^^^^^^^^^^^^^^^^ + +When using the ``timeout`` parameter in functions like :func:`run`, +:meth:`Popen.wait`, or :meth:`Popen.communicate`, +users should be aware of the following behaviors: + +1. **Process Creation Delay**: The initial process creation itself cannot be interrupted + on many platform APIs. This means that even when specifying a timeout, you are not + guaranteed to see a timeout exception until at least after however long process + creation takes. + +2. **Extremely Small Timeout Values**: Setting very small timeout values (such as a few + milliseconds) may result in almost immediate :exc:`TimeoutExpired` exceptions because + process creation and system scheduling inherently require time. + .. _converting-argument-sequence: Converting an argument sequence to a string on Windows diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index fbfd5e1e75b..a5c4ffa38fe 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -1282,6 +1282,64 @@ always available. Unless explicitly noted otherwise, all variables are read-only .. versionadded:: 3.5 +.. data:: _jit + + Utilities for observing just-in-time compilation. + + .. impl-detail:: + + JIT compilation is an *experimental implementation detail* of CPython. + ``sys._jit`` is not guaranteed to exist or behave the same way in all + Python implementations, versions, or build configurations. + + .. versionadded:: next + + .. function:: _jit.is_available() + + Return ``True`` if the current Python executable supports JIT compilation, + and ``False`` otherwise. This can be controlled by building CPython with + the ``--experimental-jit`` option on Windows, and the + :option:`--enable-experimental-jit` option on all other platforms. + + .. function:: _jit.is_enabled() + + Return ``True`` if JIT compilation is enabled for the current Python + process (implies :func:`sys._jit.is_available`), and ``False`` otherwise. + If JIT compilation is available, this can be controlled by setting the + :envvar:`PYTHON_JIT` environment variable to ``0`` (disabled) or ``1`` + (enabled) at interpreter startup. + + .. function:: _jit.is_active() + + Return ``True`` if the topmost Python frame is currently executing JIT + code (implies :func:`sys._jit.is_enabled`), and ``False`` otherwise. + + .. note:: + + This function is intended for testing and debugging the JIT itself. + It should be avoided for any other purpose. + + .. note:: + + Due to the nature of tracing JIT compilers, repeated calls to this + function may give surprising results. For example, branching on its + return value will likely lead to unexpected behavior (if doing so + causes JIT code to be entered or exited): + + .. code-block:: pycon + + >>> for warmup in range(BIG_NUMBER): + ... # This line is "hot", and is eventually JIT-compiled: + ... if sys._jit.is_active(): + ... # This line is "cold", and is run in the interpreter: + ... assert sys._jit.is_active() + ... + Traceback (most recent call last): + File "<stdin>", line 5, in <module> + assert sys._jit.is_active() + ~~~~~~~~~~~~~~~~~~^^ + AssertionError + .. data:: last_exc This variable is not always defined; it is set to the exception instance diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index d948493c210..de9ee427bd7 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -260,23 +260,132 @@ All of the methods described below are executed atomically. Thread-Local Data ----------------- -Thread-local data is data whose values are thread specific. To manage -thread-local data, just create an instance of :class:`local` (or a -subclass) and store attributes on it:: +Thread-local data is data whose values are thread specific. If you +have data that you want to be local to a thread, create a +:class:`local` object and use its attributes:: - mydata = threading.local() - mydata.x = 1 + >>> mydata = local() + >>> mydata.number = 42 + >>> mydata.number + 42 -The instance's values will be different for separate threads. +You can also access the :class:`local`-object's dictionary:: + + >>> mydata.__dict__ + {'number': 42} + >>> mydata.__dict__.setdefault('widgets', []) + [] + >>> mydata.widgets + [] + +If we access the data in a different thread:: + + >>> log = [] + >>> def f(): + ... items = sorted(mydata.__dict__.items()) + ... log.append(items) + ... mydata.number = 11 + ... log.append(mydata.number) + + >>> import threading + >>> thread = threading.Thread(target=f) + >>> thread.start() + >>> thread.join() + >>> log + [[], 11] + +we get different data. Furthermore, changes made in the other thread +don't affect data seen in this thread:: + + >>> mydata.number + 42 + +Of course, values you get from a :class:`local` object, including their +:attr:`~object.__dict__` attribute, are for whatever thread was current +at the time the attribute was read. For that reason, you generally +don't want to save these values across threads, as they apply only to +the thread they came from. + +You can create custom :class:`local` objects by subclassing the +:class:`local` class:: + + >>> class MyLocal(local): + ... number = 2 + ... def __init__(self, /, **kw): + ... self.__dict__.update(kw) + ... def squared(self): + ... return self.number ** 2 + +This can be useful to support default values, methods and +initialization. Note that if you define an :py:meth:`~object.__init__` +method, it will be called each time the :class:`local` object is used +in a separate thread. This is necessary to initialize each thread's +dictionary. + +Now if we create a :class:`local` object:: + + >>> mydata = MyLocal(color='red') + +we have a default number:: + + >>> mydata.number + 2 + +an initial color:: + + >>> mydata.color + 'red' + >>> del mydata.color + +And a method that operates on the data:: + + >>> mydata.squared() + 4 + +As before, we can access the data in a separate thread:: + + >>> log = [] + >>> thread = threading.Thread(target=f) + >>> thread.start() + >>> thread.join() + >>> log + [[('color', 'red')], 11] + +without affecting this thread's data:: + + >>> mydata.number + 2 + >>> mydata.color + Traceback (most recent call last): + ... + AttributeError: 'MyLocal' object has no attribute 'color' + +Note that subclasses can define :term:`__slots__`, but they are not +thread local. They are shared across threads:: + + >>> class MyLocal(local): + ... __slots__ = 'number' + + >>> mydata = MyLocal() + >>> mydata.number = 42 + >>> mydata.color = 'red' + +So, the separate thread:: + + >>> thread = threading.Thread(target=f) + >>> thread.start() + >>> thread.join() + +affects what we see:: + + >>> mydata.number + 11 .. class:: local() A class that represents thread-local data. - For more details and extensive examples, see the documentation string of the - :mod:`!_threading_local` module: :source:`Lib/_threading_local.py`. - .. _thread-objects: diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst index b7c0c7d5099..234827132bf 100644 --- a/Doc/library/urllib.request.rst +++ b/Doc/library/urllib.request.rst @@ -172,10 +172,10 @@ The :mod:`urllib.request` module defines the following functions: the URL ``///etc/hosts``. .. versionchanged:: next - The *add_scheme* argument was added. + The *add_scheme* parameter was added. -.. function:: url2pathname(url, *, require_scheme=False) +.. function:: url2pathname(url, *, require_scheme=False, resolve_host=False) Convert the given ``file:`` URL to a local path. This function uses :func:`~urllib.parse.unquote` to decode the URL. @@ -185,6 +185,13 @@ The :mod:`urllib.request` module defines the following functions: value should include the prefix; a :exc:`~urllib.error.URLError` is raised if it doesn't. + The URL authority is discarded if it is empty, ``localhost``, or the local + hostname. Otherwise, if *resolve_host* is set to true, the authority is + resolved using :func:`socket.gethostbyname` and discarded if it matches a + local IP address (as per :rfc:`RFC 8089 ยง3 <8089#section-3>`). If the + authority is still unhandled, then on Windows a UNC path is returned, and + on other platforms a :exc:`~urllib.error.URLError` is raised. + This example shows the function being used on Windows:: >>> from urllib.request import url2pathname @@ -198,14 +205,13 @@ The :mod:`urllib.request` module defines the following functions: :exc:`OSError` exception to be raised on Windows. .. versionchanged:: next - This function calls :func:`socket.gethostbyname` if the URL authority - isn't empty, ``localhost``, or the machine hostname. If the authority - resolves to a local IP address then it is discarded; otherwise, on + The URL authority is discarded if it matches the local hostname. + Otherwise, if the authority isn't empty or ``localhost``, then on Windows a UNC path is returned (as before), and on other platforms a :exc:`~urllib.error.URLError` is raised. .. versionchanged:: next - The *require_scheme* argument was added. + The *require_scheme* and *resolve_host* parameters were added. .. function:: getproxies() |