From: JinWang An Date: Wed, 18 Jan 2023 06:01:28 +0000 (+0900) Subject: Imported Upstream version 3.9.13 X-Git-Tag: upstream/3.9.13^0 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=d1028df2c8c786fb6167f22c53c4a954b554de81;p=platform%2Fupstream%2Fpython3.git Imported Upstream version 3.9.13 --- diff --git a/Doc/about.rst b/Doc/about.rst index 3ea311fa..f0b90848 100644 --- a/Doc/about.rst +++ b/Doc/about.rst @@ -23,9 +23,8 @@ Many thanks go to: and writer of much of the content; * the `Docutils `_ project for creating reStructuredText and the Docutils suite; -* Fredrik Lundh for his `Alternative Python Reference - `_ project from which Sphinx got many good - ideas. +* Fredrik Lundh for his Alternative Python Reference project from which Sphinx + got many good ideas. Contributors to the Python Documentation diff --git a/Doc/bugs.rst b/Doc/bugs.rst index 192995ab..6654a23c 100644 --- a/Doc/bugs.rst +++ b/Doc/bugs.rst @@ -35,6 +35,10 @@ though it may take a while to be processed. `Helping with Documentation `_ Comprehensive guide for individuals that are interested in contributing to Python documentation. + `Documentation Translations `_ + A list of GitHub pages for documentation translation and their primary contacts. + + .. _using-the-tracker: Using the Python issue tracker diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index 7a318800..6b60344a 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -288,7 +288,7 @@ Numbers Convert a Python integer to a C :c:type:`unsigned long long` without overflow checking. -``n`` (:class:`int`) [Py_ssize_t] +``n`` (:class:`int`) [:c:type:`Py_ssize_t`] Convert a Python integer to a C :c:type:`Py_ssize_t`. ``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char] @@ -614,7 +614,7 @@ Building values ``K`` (:class:`int`) [unsigned long long] Convert a C :c:type:`unsigned long long` to a Python integer object. - ``n`` (:class:`int`) [Py_ssize_t] + ``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] diff --git a/Doc/c-api/bytearray.rst b/Doc/c-api/bytearray.rst index 30bcfc7c..85a7d137 100644 --- a/Doc/c-api/bytearray.rst +++ b/Doc/c-api/bytearray.rst @@ -42,8 +42,6 @@ Direct API functions Return a new bytearray object from any object, *o*, that implements the :ref:`buffer protocol `. - .. XXX expand about the buffer protocol, at least somewhere - .. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len) diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst index de657010..ffbfb5a6 100644 --- a/Doc/c-api/bytes.rst +++ b/Doc/c-api/bytes.rst @@ -5,7 +5,7 @@ Bytes Objects ------------- -These functions raise :exc:`TypeError` when expecting a bytes parameter and are +These functions raise :exc:`TypeError` when expecting a bytes parameter and called with a non-bytes parameter. .. index:: object: bytes @@ -84,8 +84,8 @@ called with a non-bytes parameter. | :attr:`%lu` | unsigned long | Equivalent to | | | | ``printf("%lu")``. [1]_ | +-------------------+---------------+--------------------------------+ - | :attr:`%zd` | Py_ssize_t | Equivalent to | - | | | ``printf("%zd")``. [1]_ | + | :attr:`%zd` | :c:type:`\ | Equivalent to | + | | Py_ssize_t` | ``printf("%zd")``. [1]_ | +-------------------+---------------+--------------------------------+ | :attr:`%zu` | size_t | Equivalent to | | | | ``printf("%zu")``. [1]_ | diff --git a/Doc/c-api/call.rst b/Doc/c-api/call.rst index 739b5e97..cdf72bc1 100644 --- a/Doc/c-api/call.rst +++ b/Doc/c-api/call.rst @@ -26,7 +26,7 @@ This convention is not only used by *tp_call*: :c:member:`~PyTypeObject.tp_new` and :c:member:`~PyTypeObject.tp_init` also pass arguments this way. -To call an object, use :c:func:`PyObject_Call` or other +To call an object, use :c:func:`PyObject_Call` or another :ref:`call API `. diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index df38ba43..0e35590c 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -281,7 +281,7 @@ For convenience, some of these functions will always return a .. c:function:: void PyErr_SyntaxLocation(const char *filename, int lineno) - Like :c:func:`PyErr_SyntaxLocationEx`, but the col_offset parameter is + Like :c:func:`PyErr_SyntaxLocationEx`, but the *col_offset* parameter is omitted. @@ -333,7 +333,7 @@ an error value). Issue a warning message with explicit control over all warning attributes. This is a straightforward wrapper around the Python function - :func:`warnings.warn_explicit`, see there for more information. The *module* + :func:`warnings.warn_explicit`; see there for more information. The *module* and *registry* arguments may be set to ``NULL`` to get the default effect described there. @@ -441,7 +441,7 @@ Querying the error indicator error indicator. -.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb) +.. c:function:: void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb) Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is @@ -845,11 +845,11 @@ the variables: +-----------------------------------------+---------------------------------+----------+ | C Name | Python Name | Notes | +=========================================+=================================+==========+ -| :c:data:`PyExc_BaseException` | :exc:`BaseException` | \(1) | +| :c:data:`PyExc_BaseException` | :exc:`BaseException` | [1]_ | +-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) | +| :c:data:`PyExc_Exception` | :exc:`Exception` | [1]_ | +-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) | +| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | [1]_ | +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | | +-----------------------------------------+---------------------------------+----------+ @@ -895,7 +895,7 @@ the variables: +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | | +-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) | +| :c:data:`PyExc_LookupError` | :exc:`LookupError` | [1]_ | +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | | +-----------------------------------------+---------------------------------+----------+ @@ -907,7 +907,7 @@ the variables: +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | | +-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_OSError` | :exc:`OSError` | \(1) | +| :c:data:`PyExc_OSError` | :exc:`OSError` | [1]_ | +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | | +-----------------------------------------+---------------------------------+----------+ @@ -917,7 +917,7 @@ the variables: +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_RecursionError` | :exc:`RecursionError` | | +-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) | +| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | | +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | | +-----------------------------------------+---------------------------------+----------+ @@ -982,7 +982,7 @@ These are compatibility aliases to :c:data:`PyExc_OSError`: +-------------------------------------+----------+ | :c:data:`PyExc_IOError` | | +-------------------------------------+----------+ -| :c:data:`PyExc_WindowsError` | \(3) | +| :c:data:`PyExc_WindowsError` | [2]_ | +-------------------------------------+----------+ .. versionchanged:: 3.3 @@ -990,10 +990,10 @@ These are compatibility aliases to :c:data:`PyExc_OSError`: Notes: -(1) +.. [1] This is a base class for other standard exceptions. -(2) +.. [2] Only defined on Windows; protect code that uses this by testing that the preprocessor macro ``MS_WINDOWS`` is defined. @@ -1023,7 +1023,7 @@ the variables: +------------------------------------------+---------------------------------+----------+ | C Name | Python Name | Notes | +==========================================+=================================+==========+ -| :c:data:`PyExc_Warning` | :exc:`Warning` | \(1) | +| :c:data:`PyExc_Warning` | :exc:`Warning` | [3]_ | +------------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_BytesWarning` | :exc:`BytesWarning` | | +------------------------------------------+---------------------------------+----------+ @@ -1051,5 +1051,5 @@ the variables: Notes: -(1) +.. [3] This is a base class for other standard warning categories. diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 9d7876e0..06e88683 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -498,7 +498,7 @@ Process-wide parameters .. index:: single: version (in module sys) The first word (up to the first space character) is the current Python version; - the first three characters are the major and minor version separated by a + the first characters are the major and minor version separated by a period. The returned string points into static storage; the caller should not modify its value. The value is available to Python code as :data:`sys.version`. @@ -1688,7 +1688,7 @@ is not possible due to its implementation being opaque at build time. argument is `NULL`. .. note:: - A freed key becomes a dangling pointer, you should reset the key to + A freed key becomes a dangling pointer. You should reset the key to `NULL`. diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst index 23009e41..f44c7bb5 100644 --- a/Doc/c-api/init_config.rst +++ b/Doc/c-api/init_config.rst @@ -823,7 +823,7 @@ Isolated Configuration isolate Python from the system. For example, to embed Python into an application. -This configuration ignores global configuration variables, environments +This configuration ignores global configuration variables, environment variables, command line arguments (:c:member:`PyConfig.argv` is not parsed) and user site directory. The C standard streams (ex: ``stdout``) and the LC_CTYPE locale are left unchanged. Signal handlers are not installed. @@ -1000,7 +1000,7 @@ Multi-Phase Initialization Private Provisional API -------------------------------------------------- This section is a private provisional API introducing multi-phase -initialization, the core feature of the :pep:`432`: +initialization, the core feature of :pep:`432`: * "Core" initialization phase, "bare minimum Python": diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 7ca8693a..ac1024cd 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -502,6 +502,13 @@ 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 use them. +.. c:type:: Py_ssize_t + + A signed integral type such that ``sizeof(Py_ssize_t) == sizeof(size_t)``. + C99 doesn't define such a thing directly (size_t is an unsigned integral type). + See :pep:`353` for details. ``PY_SSIZE_T_MAX`` is the largest positive value + of type :c:type:`Py_ssize_t`. + .. _api-exceptions: diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index 60e1791d..95796e0f 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -41,7 +41,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. Return a new :c:type:`PyLongObject` object from *v*, or ``NULL`` on failure. The current implementation keeps an array of integer objects for all integers - between ``-5`` and ``256``, when you create an int in that range you actually + between ``-5`` and ``256``. When you create an int in that range you actually just get back a reference to the existing object. diff --git a/Doc/c-api/mapping.rst b/Doc/c-api/mapping.rst index 682160d1..3c9d282c 100644 --- a/Doc/c-api/mapping.rst +++ b/Doc/c-api/mapping.rst @@ -11,10 +11,10 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and .. c:function:: int PyMapping_Check(PyObject *o) - Return ``1`` if the object provides mapping protocol or supports slicing, + Return ``1`` if the object provides the mapping protocol or supports slicing, and ``0`` otherwise. Note that it returns ``1`` for Python classes with - a :meth:`__getitem__` method since in general case it is impossible to - determine what type of keys it supports. This function always succeeds. + a :meth:`__getitem__` method, since in general it is impossible to + determine what type of keys the class supports. This function always succeeds. .. c:function:: Py_ssize_t PyMapping_Size(PyObject *o) diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst index 91b901d7..624bddcb 100644 --- a/Doc/c-api/memory.rst +++ b/Doc/c-api/memory.rst @@ -362,7 +362,7 @@ Customize Memory Allocators .. c:type:: PyMemAllocatorEx Structure used to describe a memory block allocator. The structure has - four fields: + the following fields: +----------------------------------------------------------+---------------------------------------+ | Field | Meaning | diff --git a/Doc/c-api/method.rst b/Doc/c-api/method.rst index 23852251..6e7e1e21 100644 --- a/Doc/c-api/method.rst +++ b/Doc/c-api/method.rst @@ -27,7 +27,7 @@ to bind a :c:data:`PyCFunction` to a class object. It replaces the former call .. c:function:: PyObject* PyInstanceMethod_New(PyObject *func) - Return a new instance method object, with *func* being any callable object + Return a new instance method object, with *func* being any callable object. *func* is the function that will be called when the instance method is called. diff --git a/Doc/c-api/number.rst b/Doc/c-api/number.rst index 620204ca..47033a38 100644 --- a/Doc/c-api/number.rst +++ b/Doc/c-api/number.rst @@ -44,7 +44,7 @@ Number Protocol .. c:function:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2) Return the floor of *o1* divided by *o2*, or ``NULL`` on failure. This is - equivalent to the "classic" division of integers. + the equivalent of the Python expression ``o1 // o2``. .. c:function:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2) @@ -53,7 +53,7 @@ Number Protocol *o2*, or ``NULL`` on failure. The return value is "approximate" because binary floating point numbers are approximate; it is not possible to represent all real numbers in base two. This function can return a floating point value when - passed two integers. + passed two integers. This is the equivalent of the Python expression ``o1 / o2``. .. c:function:: PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2) @@ -180,6 +180,7 @@ Number Protocol floating point numbers are approximate; it is not possible to represent all real numbers in base two. This function can return a floating point value when passed two integers. The operation is done *in-place* when *o1* supports it. + This is the equivalent of the Python statement ``o1 /= o2``. .. c:function:: PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2) @@ -268,11 +269,11 @@ Number Protocol .. c:function:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc) - Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an + Returns *o* converted to a :c:type:`Py_ssize_t` value if *o* can be interpreted as an integer. If the call fails, an exception is raised and ``-1`` is returned. If *o* can be converted to a Python int but the attempt to - convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the + convert to a :c:type:`Py_ssize_t` value would raise an :exc:`OverflowError`, then the *exc* argument is the type of exception that will be raised (usually :exc:`IndexError` or :exc:`OverflowError`). If *exc* is ``NULL``, then the exception is cleared and the value is clipped to ``PY_SSIZE_T_MIN`` for a negative @@ -281,6 +282,6 @@ Number Protocol .. c:function:: int PyIndex_Check(PyObject *o) - Returns ``1`` if *o* is an index integer (has the nb_index slot of the - tp_as_number structure filled in), and ``0`` otherwise. + Returns ``1`` if *o* is an index integer (has the ``nb_index`` slot of the + ``tp_as_number`` structure filled in), and ``0`` otherwise. This function always succeeds. diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 9f874382..3e4f61ac 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -93,7 +93,7 @@ Object Protocol return ``0`` on success. This is the equivalent of the Python statement ``o.attr_name = v``. - If *v* is ``NULL``, the attribute is deleted, however this feature is + If *v* is ``NULL``, the attribute is deleted, but this feature is deprecated in favour of using :c:func:`PyObject_DelAttrString`. @@ -258,7 +258,7 @@ Object Protocol .. versionchanged:: 3.2 The return type is now Py_hash_t. This is a signed integer the same size - as Py_ssize_t. + as :c:type:`Py_ssize_t`. .. c:function:: Py_hash_t PyObject_HashNotImplemented(PyObject *o) @@ -291,7 +291,7 @@ Object Protocol of object *o*. On failure, raises :exc:`SystemError` and returns ``NULL``. This 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 common expression ``o->ob_type``, which returns a + function instead of the :c:func:`Py_TYPE()` function, which returns a pointer of type :c:type:`PyTypeObject*`, except when the incremented reference count is needed. diff --git a/Doc/c-api/sequence.rst b/Doc/c-api/sequence.rst index 65818859..c78d273f 100644 --- a/Doc/c-api/sequence.rst +++ b/Doc/c-api/sequence.rst @@ -8,10 +8,10 @@ Sequence Protocol .. c:function:: int PySequence_Check(PyObject *o) - Return ``1`` if the object provides sequence protocol, and ``0`` otherwise. + Return ``1`` if the object provides the sequence protocol, and ``0`` otherwise. Note that it returns ``1`` for Python classes with a :meth:`__getitem__` - method unless they are :class:`dict` subclasses since in general case it - is impossible to determine what the type of keys it supports. This + method, unless they are :class:`dict` subclasses, since in general it + is impossible to determine what type of keys the class supports. This function always succeeds. @@ -69,7 +69,7 @@ Sequence Protocol is the equivalent of the Python statement ``o[i] = v``. This function *does not* steal a reference to *v*. - If *v* is ``NULL``, the element is deleted, however this feature is + If *v* is ``NULL``, the element is deleted, but this feature is deprecated in favour of using :c:func:`PySequence_DelItem`. @@ -147,7 +147,7 @@ Sequence Protocol Returns the length of *o*, assuming that *o* was returned by :c:func:`PySequence_Fast` and that *o* is not ``NULL``. The size can also be - gotten by calling :c:func:`PySequence_Size` on *o*, but + retrieved by calling :c:func:`PySequence_Size` on *o*, but :c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list or tuple. diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst index 84f34e7d..9e3045e7 100644 --- a/Doc/c-api/set.rst +++ b/Doc/c-api/set.rst @@ -13,7 +13,7 @@ Set Objects object: frozenset This section details the public API for :class:`set` and :class:`frozenset` -objects. Any functionality not listed below is best accessed using the either +objects. Any functionality not listed below is best accessed using either the abstract object protocol (including :c:func:`PyObject_CallMethod`, :c:func:`PyObject_RichCompareBool`, :c:func:`PyObject_Hash`, :c:func:`PyObject_Repr`, :c:func:`PyObject_IsTrue`, :c:func:`PyObject_Print`, and @@ -31,7 +31,7 @@ the abstract object protocol (including :c:func:`PyObject_CallMethod`, in that it is a fixed size for small sets (much like tuple storage) and will point to a separate, variable sized block of memory for medium and large sized sets (much like list storage). None of the fields of this structure should be - considered public and are subject to change. All access should be done through + considered public and all are subject to change. All access should be done through the documented API rather than by manipulating the values in the structure. @@ -125,7 +125,7 @@ or :class:`frozenset` or instances of their subtypes. .. c:function:: int PySet_Add(PyObject *set, PyObject *key) Add *key* to a :class:`set` instance. Also works with :class:`frozenset` - instances (like :c:func:`PyTuple_SetItem` it can be used to fill-in the values + instances (like :c:func:`PyTuple_SetItem` it can be used to fill in the values of brand new frozensets before they are exposed to other code). Return ``0`` on success or ``-1`` on failure. Raise a :exc:`TypeError` if the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to grow. Raise a diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 1e30d408..1599b88e 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -461,7 +461,7 @@ Accessing attributes of extension types +=============+==================+===================================+ | name | const char \* | attribute name | +-------------+------------------+-----------------------------------+ - | get | getter | C Function to get the attribute | + | get | getter | C function to get the attribute | +-------------+------------------+-----------------------------------+ | set | setter | optional C function to set or | | | | delete the attribute, if omitted | diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst index 9ac91790..0a5c8d70 100644 --- a/Doc/c-api/sys.rst +++ b/Doc/c-api/sys.rst @@ -185,7 +185,7 @@ Operating System Utilities Return a pointer to a newly allocated byte string, use :c:func:`PyMem_Free` to free the memory. Return ``NULL`` on encoding error or memory allocation - error + error. If error_pos is not ``NULL``, ``*error_pos`` is set to ``(size_t)-1`` on success, or set to the index of the invalid character on encoding error. @@ -205,7 +205,7 @@ Operating System Utilities .. versionchanged:: 3.8 The function now uses the UTF-8 encoding on Windows if - :c:data:`Py_LegacyWindowsFSEncodingFlag` is zero; + :c:data:`Py_LegacyWindowsFSEncodingFlag` is zero. .. _systemfunctions: @@ -321,7 +321,7 @@ accessible to C code. They all work with the current interpreter thread's leaks.) Note that ``#`` format characters should always be treated as - ``Py_ssize_t``, regardless of whether ``PY_SSIZE_T_CLEAN`` was defined. + :c:type:`Py_ssize_t`, regardless of whether ``PY_SSIZE_T_CLEAN`` was defined. :func:`sys.audit` performs the same function from Python code. @@ -329,14 +329,14 @@ accessible to C code. They all work with the current interpreter thread's .. versionchanged:: 3.8.2 - Require ``Py_ssize_t`` for ``#`` format characters. Previously, an + Require :c:type:`Py_ssize_t` for ``#`` format characters. Previously, an unavoidable deprecation warning was raised. .. c:function:: int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData) Append the callable *hook* to the list of active auditing hooks. - Return zero for success + Return zero on success and non-zero on failure. If the runtime has been initialized, also set an error on failure. Hooks added through this API are called for all interpreters created by the runtime. diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst index cc2d8fda..119a9081 100644 --- a/Doc/c-api/type.rst +++ b/Doc/c-api/type.rst @@ -266,7 +266,7 @@ The following functions and structs are used to create .. versionchanged:: 3.9 - Slots in :c:type:`PyBufferProcs` in may be set in the unlimited API. + Slots in :c:type:`PyBufferProcs` may be set in the unlimited API. .. c:member:: void *PyType_Slot.pfunc diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index d58a53b1..eedefd7c 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -43,13 +43,13 @@ Quick Reference +================================================+===================================+===================+===+===+===+===+ | :c:member:`~PyTypeObject.tp_name` | const char * | __name__ | X | X | | | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_basicsize` | Py_ssize_t | | X | X | | X | + | :c:member:`~PyTypeObject.tp_basicsize` | :c:type:`Py_ssize_t` | | X | X | | X | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_itemsize` | Py_ssize_t | | | X | | X | + | :c:member:`~PyTypeObject.tp_itemsize` | :c:type:`Py_ssize_t` | | | X | | X | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ | :c:member:`~PyTypeObject.tp_dealloc` | :c:type:`destructor` | | X | X | | X | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_vectorcall_offset` | Py_ssize_t | | | X | | X | + | :c:member:`~PyTypeObject.tp_vectorcall_offset` | :c:type:`Py_ssize_t` | | | X | | X | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ | (:c:member:`~PyTypeObject.tp_getattr`) | :c:type:`getattrfunc` | __getattribute__, | | | | G | | | | __getattr__ | | | | | @@ -96,7 +96,7 @@ Quick Reference | | | __gt__, | | | | | | | | __ge__ | | | | | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_weaklistoffset` | Py_ssize_t | | | X | | ? | + | :c:member:`~PyTypeObject.tp_weaklistoffset` | :c:type:`Py_ssize_t` | | | X | | ? | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ | :c:member:`~PyTypeObject.tp_iter` | :c:type:`getiterfunc` | __iter__ | | | | X | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ @@ -117,7 +117,7 @@ Quick Reference | :c:member:`~PyTypeObject.tp_descr_set` | :c:type:`descrsetfunc` | __set__, | | | | X | | | | __delete__ | | | | | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_dictoffset` | Py_ssize_t | | | X | | ? | + | :c:member:`~PyTypeObject.tp_dictoffset` | :c:type:`Py_ssize_t` | | | X | | ? | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ | :c:member:`~PyTypeObject.tp_init` | :c:type:`initproc` | __init__ | X | X | | X | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ @@ -331,7 +331,7 @@ slot typedefs | :c:type:`allocfunc` | .. line-block:: | :c:type:`PyObject` * | | | | | | | :c:type:`PyTypeObject` * | | -| | Py_ssize_t | | +| | :c:type:`Py_ssize_t` | | +-----------------------------+-----------------------------+----------------------+ | :c:type:`destructor` | void * | void | +-----------------------------+-----------------------------+----------------------+ @@ -403,7 +403,7 @@ slot typedefs +-----------------------------+-----------------------------+----------------------+ | :c:type:`iternextfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | +-----------------------------+-----------------------------+----------------------+ -| :c:type:`lenfunc` | :c:type:`PyObject` * | Py_ssize_t | +| :c:type:`lenfunc` | :c:type:`PyObject` * | :c:type:`Py_ssize_t` | +-----------------------------+-----------------------------+----------------------+ | :c:type:`getbufferproc` | .. line-block:: | int | | | | | @@ -436,12 +436,12 @@ slot typedefs | :c:type:`ssizeargfunc` | .. line-block:: | :c:type:`PyObject` * | | | | | | | :c:type:`PyObject` * | | -| | Py_ssize_t | | +| | :c:type:`Py_ssize_t` | | +-----------------------------+-----------------------------+----------------------+ | :c:type:`ssizeobjargproc` | .. line-block:: | int | | | | | | | :c:type:`PyObject` * | | -| | Py_ssize_t | | +| | :c:type:`Py_ssize_t` | | +-----------------------------+-----------------------------+----------------------+ | :c:type:`objobjproc` | .. line-block:: | int | | | | | @@ -2482,7 +2482,7 @@ A basic static type:: PyVarObject_HEAD_INIT(NULL, 0) .tp_name = "mymod.MyObject", .tp_basicsize = sizeof(MyObject), - .tp_doc = "My objects", + .tp_doc = PyDoc_STR("My objects"), .tp_new = myobj_new, .tp_dealloc = (destructor)myobj_dealloc, .tp_repr = (reprfunc)myobj_repr, @@ -2512,7 +2512,7 @@ with a more verbose initializer:: 0, /* tp_setattro */ 0, /* tp_as_buffer */ 0, /* tp_flags */ - "My objects", /* tp_doc */ + PyDoc_STR("My objects"), /* tp_doc */ 0, /* tp_traverse */ 0, /* tp_clear */ 0, /* tp_richcompare */ @@ -2545,7 +2545,7 @@ A type that supports weakrefs, instance dicts, and hashing:: PyVarObject_HEAD_INIT(NULL, 0) .tp_name = "mymod.MyObject", .tp_basicsize = sizeof(MyObject), - .tp_doc = "My objects", + .tp_doc = PyDoc_STR("My objects"), .tp_weaklistoffset = offsetof(MyObject, weakreflist), .tp_dictoffset = offsetof(MyObject, inst_dict), .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, @@ -2572,7 +2572,7 @@ to create instances (e.g. uses a separate factory func):: .tp_name = "mymod.MyStr", .tp_basicsize = sizeof(MyStr), .tp_base = NULL, // set to &PyUnicode_Type in module init - .tp_doc = "my custom str", + .tp_doc = PyDoc_STR("my custom str"), .tp_flags = Py_TPFLAGS_DEFAULT, .tp_new = NULL, .tp_repr = (reprfunc)myobj_repr, diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index a6ae8ba1..4129c614 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -490,11 +490,11 @@ APIs: | :attr:`%llu` | unsigned long long | Equivalent to | | | | ``printf("%llu")``. [1]_ | +-------------------+---------------------+----------------------------------+ - | :attr:`%zd` | Py_ssize_t | Equivalent to | - | | | ``printf("%zd")``. [1]_ | + | :attr:`%zd` | :c:type:`\ | Equivalent to | + | | Py_ssize_t` | ``printf("%zd")``. [1]_ | +-------------------+---------------------+----------------------------------+ - | :attr:`%zi` | Py_ssize_t | Equivalent to | - | | | ``printf("%zi")``. [1]_ | + | :attr:`%zi` | :c:type:`\ | Equivalent to | + | | Py_ssize_t` | ``printf("%zi")``. [1]_ | +-------------------+---------------------+----------------------------------+ | :attr:`%zu` | size_t | Equivalent to | | | | ``printf("%zu")``. [1]_ | @@ -1110,7 +1110,8 @@ These are the UTF-8 codec APIs: This caches the UTF-8 representation of the string in the Unicode object, and subsequent calls will return a pointer to the same buffer. The caller is not - responsible for deallocating the buffer. + responsible for deallocating the buffer. The buffer is deallocated and + pointers to it become invalid when the Unicode object is garbage collected. .. versionadded:: 3.3 diff --git a/Doc/extending/newtypes_tutorial.rst b/Doc/extending/newtypes_tutorial.rst index 4da77e79..7771e205 100644 --- a/Doc/extending/newtypes_tutorial.rst +++ b/Doc/extending/newtypes_tutorial.rst @@ -67,8 +67,8 @@ The first bit is:: This is what a Custom object will contain. ``PyObject_HEAD`` is mandatory at the start of each object struct and defines a field called ``ob_base`` of type :c:type:`PyObject`, containing a pointer to a type object and a -reference count (these can be accessed using the macros :c:macro:`Py_REFCNT` -and :c:macro:`Py_TYPE` respectively). The reason for the macro is to +reference count (these can be accessed using the macros :c:macro:`Py_TYPE` +and :c:macro:`Py_REFCNT` respectively). The reason for the macro is to abstract away the layout and to enable additional fields in debug builds. .. note:: @@ -89,7 +89,7 @@ The second bit is the definition of the type object. :: static PyTypeObject CustomType = { PyVarObject_HEAD_INIT(NULL, 0) .tp_name = "custom.Custom", - .tp_doc = "Custom objects", + .tp_doc = PyDoc_STR("Custom objects"), .tp_basicsize = sizeof(CustomObject), .tp_itemsize = 0, .tp_flags = Py_TPFLAGS_DEFAULT, @@ -160,7 +160,7 @@ you will need to OR the corresponding flags. We provide a doc string for the type in :c:member:`~PyTypeObject.tp_doc`. :: - .tp_doc = "Custom objects", + .tp_doc = PyDoc_STR("Custom objects"), To enable object creation, we have to provide a :c:member:`~PyTypeObject.tp_new` handler. This is the equivalent of the Python method :meth:`__new__`, but diff --git a/Doc/extending/windows.rst b/Doc/extending/windows.rst index c7b92c6e..28d0350f 100644 --- a/Doc/extending/windows.rst +++ b/Doc/extending/windows.rst @@ -106,8 +106,7 @@ Using DLLs in Practice Windows Python is built in Microsoft Visual C++; using other compilers may or -may not work (though Borland seems to). The rest of this section is MSVC++ -specific. +may not work. The rest of this section is MSVC++ specific. When creating DLLs in Windows, you must pass :file:`pythonXY.lib` to the linker. To build two DLLs, spam and ni (which uses C functions found in spam), you could @@ -134,4 +133,3 @@ Developer Studio will throw in a lot of import libraries that you do not really need, adding about 100K to your executable. To get rid of them, use the Project Settings dialog, Link tab, to specify *ignore default libraries*. Add the correct :file:`msvcrtxx.lib` to the list of libraries. - diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst index 7703d48a..96525ddc 100644 --- a/Doc/faq/library.rst +++ b/Doc/faq/library.rst @@ -106,9 +106,6 @@ support, pads, and mouse support. This means the module isn't compatible with operating systems that only have BSD curses, but there don't seem to be any currently maintained OSes that fall into this category. -For Windows: use `the consolelib module -`_. - Is there an equivalent to C's onexit() in Python? ------------------------------------------------- diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index 3cf041e1..c2656382 100644 --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -78,7 +78,7 @@ set of modules required by a program and bind these modules together with a Python binary to produce a single executable. One is to use the freeze tool, which is included in the Python source tree as -``Tools/freeze``. It converts Python byte code to C arrays; a C compiler you can +``Tools/freeze``. It converts Python byte code to C arrays; with a C compiler you can embed all your modules into a new program, which is then linked with the standard Python modules. diff --git a/Doc/faq/windows.rst b/Doc/faq/windows.rst index 0153a4f3..4f50b3f1 100644 --- a/Doc/faq/windows.rst +++ b/Doc/faq/windows.rst @@ -26,8 +26,8 @@ with running programs from the Windows command line then everything will seem obvious; otherwise, you might need a little more guidance. Unless you use some sort of integrated development environment, you will end up -*typing* Windows commands into what is variously referred to as a "DOS window" -or "Command prompt window". Usually you can create such a window from your +*typing* Windows commands into what is referred to as a +"Command prompt window". Usually you can create such a window from your search bar by searching for ``cmd``. You should be able to recognize when you have started such a window because you will see a Windows "command prompt", which usually looks like this: @@ -186,9 +186,6 @@ Embedding the Python interpreter in a Windows app can be summarized as follows: by the Windows ``GetProcAddress()`` routine. Macros can make using these pointers transparent to any C code that calls routines in Python's C API. - Borland note: convert :file:`python{NN}.lib` to OMF format using Coff2Omf.exe - first. - .. XXX what about static linking? 2. If you use SWIG, it is easy to create a Python "extension module" that will @@ -279,4 +276,3 @@ 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. - diff --git a/Doc/glossary.rst b/Doc/glossary.rst index f759c3fb..b08e395b 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -1072,7 +1072,16 @@ Glossary as :keyword:`if`, :keyword:`while` or :keyword:`for`. text encoding - A codec which encodes Unicode strings to bytes. + A string in Python is a sequence of Unicode code points (in range + ``U+0000``--``U+10FFFF``). To store or transfer a string, it needs to be + serialized as a sequence of bytes. + + Serializing a string into a sequence of bytes is known as "encoding", and + recreating the string from the sequence of bytes is known as "decoding". + + There are a variety of different text serialization + :ref:`codecs `, which are collectively referred to as + "text encodings". text file A :term:`file object` able to read and write :class:`str` objects. diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 50041829..145febe0 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -1288,7 +1288,7 @@ Here's the simplest example of a custom converter, from ``Modules/zlibmodule.c`` /*[python end generated code: output=da39a3ee5e6b4b0d input=35521e4e733823c7]*/ This block adds a converter to Argument Clinic named ``ssize_t``. Parameters -declared as ``ssize_t`` will be declared as type ``Py_ssize_t``, and will +declared as ``ssize_t`` will be declared as type :c:type:`Py_ssize_t`, and will be parsed by the ``'O&'`` format unit, which will call the ``ssize_t_converter`` converter function. ``ssize_t`` variables automatically support default values. diff --git a/Doc/howto/curses.rst b/Doc/howto/curses.rst index cc4b4785..c0149fff 100644 --- a/Doc/howto/curses.rst +++ b/Doc/howto/curses.rst @@ -55,11 +55,7 @@ everything, though. The Windows version of Python doesn't include the :mod:`curses` module. A ported version called `UniCurses -`_ is available. You could -also try `the Console module `_ -written by Fredrik Lundh, which doesn't -use the same API as curses but provides cursor-addressable text output -and full support for mouse and keyboard input. +`_ is available. The Python curses module diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst index c7f8bc8f..695b9b31 100644 --- a/Doc/howto/functional.rst +++ b/Doc/howto/functional.rst @@ -589,7 +589,7 @@ generator function. In addition to :meth:`~generator.send`, there are two other methods on generators: -* :meth:`throw(type, value=None, traceback=None) ` is used to +* :meth:`throw(value) ` is used to raise an exception inside the generator; the exception is raised by the ``yield`` expression where the generator's execution is paused. diff --git a/Doc/howto/regex.rst b/Doc/howto/regex.rst index d574c373..c4ebbd31 100644 --- a/Doc/howto/regex.rst +++ b/Doc/howto/regex.rst @@ -89,7 +89,7 @@ is the same as ``[a-c]``, which uses a range to express the same set of characters. If you wanted to match only lowercase letters, your RE would be ``[a-z]``. -Metacharacters are not active inside classes. For example, ``[akm$]`` will +Metacharacters (except ``\``) are not active inside classes. For example, ``[akm$]`` will match any of the characters ``'a'``, ``'k'``, ``'m'``, or ``'$'``; ``'$'`` is usually a metacharacter, but inside a character class it's stripped of its special nature. diff --git a/Doc/howto/sorting.rst b/Doc/howto/sorting.rst index a8efe653..be017cfb 100644 --- a/Doc/howto/sorting.rst +++ b/Doc/howto/sorting.rst @@ -287,7 +287,7 @@ Odd and Ends >>> standard_way [('red', 1), ('red', 2), ('blue', 1), ('blue', 2)] -* The sort routines are guaranteed to use :meth:`__lt__` when making comparisons +* The sort routines use ``<`` when making comparisons between two objects. So, it is easy to add a standard sort order to a class by defining an :meth:`__lt__` method:: @@ -295,6 +295,9 @@ Odd and Ends >>> sorted(student_objects) [('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)] + However, note that ``<`` can fall back to using :meth:`__gt__` if + :meth:`__lt__` is not implemented (see :func:`object.__lt__`). + * Key functions need not depend directly on the objects being sorted. A key function can also access external resources. For instance, if the student grades are stored in a dictionary, they can be used to sort a separate list of student diff --git a/Doc/includes/custom.c b/Doc/includes/custom.c index f361baf8..26ca7549 100644 --- a/Doc/includes/custom.c +++ b/Doc/includes/custom.c @@ -9,7 +9,7 @@ typedef struct { static PyTypeObject CustomType = { PyVarObject_HEAD_INIT(NULL, 0) .tp_name = "custom.Custom", - .tp_doc = "Custom objects", + .tp_doc = PyDoc_STR("Custom objects"), .tp_basicsize = sizeof(CustomObject), .tp_itemsize = 0, .tp_flags = Py_TPFLAGS_DEFAULT, diff --git a/Doc/includes/custom2.c b/Doc/includes/custom2.c index 5bacab7a..2a3c59f8 100644 --- a/Doc/includes/custom2.c +++ b/Doc/includes/custom2.c @@ -98,7 +98,7 @@ static PyMethodDef Custom_methods[] = { static PyTypeObject CustomType = { PyVarObject_HEAD_INIT(NULL, 0) .tp_name = "custom2.Custom", - .tp_doc = "Custom objects", + .tp_doc = PyDoc_STR("Custom objects"), .tp_basicsize = sizeof(CustomObject), .tp_itemsize = 0, .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, diff --git a/Doc/includes/custom3.c b/Doc/includes/custom3.c index 2b7a99ec..5a47530f 100644 --- a/Doc/includes/custom3.c +++ b/Doc/includes/custom3.c @@ -148,7 +148,7 @@ static PyMethodDef Custom_methods[] = { static PyTypeObject CustomType = { PyVarObject_HEAD_INIT(NULL, 0) .tp_name = "custom3.Custom", - .tp_doc = "Custom objects", + .tp_doc = PyDoc_STR("Custom objects"), .tp_basicsize = sizeof(CustomObject), .tp_itemsize = 0, .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, diff --git a/Doc/includes/custom4.c b/Doc/includes/custom4.c index 584992fc..c7ee5557 100644 --- a/Doc/includes/custom4.c +++ b/Doc/includes/custom4.c @@ -160,7 +160,7 @@ static PyMethodDef Custom_methods[] = { static PyTypeObject CustomType = { PyVarObject_HEAD_INIT(NULL, 0) .tp_name = "custom4.Custom", - .tp_doc = "Custom objects", + .tp_doc = PyDoc_STR("Custom objects"), .tp_basicsize = sizeof(CustomObject), .tp_itemsize = 0, .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, diff --git a/Doc/includes/sublist.c b/Doc/includes/sublist.c index b2c26e73..b36dadf0 100644 --- a/Doc/includes/sublist.c +++ b/Doc/includes/sublist.c @@ -31,7 +31,7 @@ SubList_init(SubListObject *self, PyObject *args, PyObject *kwds) static PyTypeObject SubListType = { PyVarObject_HEAD_INIT(NULL, 0) .tp_name = "sublist.SubList", - .tp_doc = "SubList objects", + .tp_doc = PyDoc_STR("SubList objects"), .tp_basicsize = sizeof(SubListObject), .tp_itemsize = 0, .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, diff --git a/Doc/library/__future__.rst b/Doc/library/__future__.rst index 41399942..8bd23dae 100644 --- a/Doc/library/__future__.rst +++ b/Doc/library/__future__.rst @@ -90,12 +90,20 @@ language using this mechanism: | generator_stop | 3.5.0b1 | 3.7 | :pep:`479`: | | | | | *StopIteration handling inside generators* | +------------------+-------------+--------------+---------------------------------------------+ -| annotations | 3.7.0b1 | 3.10 | :pep:`563`: | +| annotations | 3.7.0b1 | TBD [1]_ | :pep:`563`: | | | | | *Postponed evaluation of annotations* | +------------------+-------------+--------------+---------------------------------------------+ .. XXX Adding a new entry? Remember to update simple_stmts.rst, too. +.. [1] + ``from __future__ import annotations`` was previously scheduled to + become mandatory in Python 3.10, but the Python Steering Council + twice decided to delay the change + (`announcement for Python 3.10 `__; + `announcement for Python 3.11 `__). + No final decision has been made yet. See also :pep:`563` and :pep:`649`. + .. seealso:: diff --git a/Doc/library/aifc.rst b/Doc/library/aifc.rst index edb4bf86..fa277857 100644 --- a/Doc/library/aifc.rst +++ b/Doc/library/aifc.rst @@ -14,7 +14,8 @@ .. deprecated:: 3.11 - The :mod:`aifc` module is deprecated (see :pep:`594` for details). + The :mod:`aifc` module is deprecated + (see :pep:`PEP 594 <594#aifc>` for details). -------------- diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index fa731fec..8989d1ce 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -501,7 +501,7 @@ disallowed. fromfile_prefix_chars ^^^^^^^^^^^^^^^^^^^^^ -Sometimes, for example when dealing with a particularly long argument lists, it +Sometimes, for example when dealing with a particularly long argument list, it may make sense to keep the list of arguments in a file rather than typing it out at the command line. If the ``fromfile_prefix_chars=`` argument is given to the :class:`ArgumentParser` constructor, then arguments that start with any of the diff --git a/Doc/library/asynchat.rst b/Doc/library/asynchat.rst index 4354444a..7cc9d997 100644 --- a/Doc/library/asynchat.rst +++ b/Doc/library/asynchat.rst @@ -11,7 +11,8 @@ **Source code:** :source:`Lib/asynchat.py` .. deprecated:: 3.6 - :mod:`asynchat` will be removed in Python 3.12 (:pep:`594`). + :mod:`asynchat` will be removed in Python 3.12 + (see :pep:`PEP 594 <594#asynchat>` for details). Please use :mod:`asyncio` instead. -------------- diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst index 6ba24249..fbe68f78 100644 --- a/Doc/library/asyncio-subprocess.rst +++ b/Doc/library/asyncio-subprocess.rst @@ -278,7 +278,7 @@ their completion. Use the :meth:`communicate` method rather than :attr:`process.stdin.write() `, :attr:`await process.stdout.read() ` or - :attr:`await process.stderr.read `. + :attr:`await process.stderr.read() `. This avoids deadlocks due to streams pausing reading or writing and blocking the child process. diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 38b12e44..7c12e2ed 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -20,7 +20,7 @@ Coroutines :term:`Coroutines ` declared with the async/await syntax is the preferred way of writing asyncio applications. For example, the following -snippet of code (requires Python 3.7+) prints "hello", waits 1 second, +snippet of code prints "hello", waits 1 second, and then prints "world":: >>> import asyncio @@ -259,21 +259,6 @@ Creating Tasks :exc:`RuntimeError` is raised if there is no running loop in current thread. - This function has been **added in Python 3.7**. Prior to - Python 3.7, the low-level :func:`asyncio.ensure_future` function - can be used instead:: - - async def coro(): - ... - - # In Python 3.7+ - task = asyncio.create_task(coro()) - ... - - # This works in all Python versions but is less readable - task = asyncio.ensure_future(coro()) - ... - .. important:: Save a reference to the result of this function, to avoid diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst index 94a85325..a6429394 100644 --- a/Doc/library/asyncio.rst +++ b/Doc/library/asyncio.rst @@ -17,7 +17,6 @@ await asyncio.sleep(1) print('... World!') - # Python 3.7+ asyncio.run(main()) asyncio is a library to write **concurrent** code using diff --git a/Doc/library/asyncore.rst b/Doc/library/asyncore.rst index e481e13d..a732fd7b 100644 --- a/Doc/library/asyncore.rst +++ b/Doc/library/asyncore.rst @@ -14,7 +14,8 @@ **Source code:** :source:`Lib/asyncore.py` .. deprecated:: 3.6 - :mod:`asyncore` will be removed in Python 3.12 (:pep:`594`). + :mod:`asyncore` will be removed in Python 3.12 + (see :pep:`PEP 594 <594#asyncore>` for details). Please use :mod:`asyncio` instead. -------------- diff --git a/Doc/library/audioop.rst b/Doc/library/audioop.rst index eae20608..649c99e7 100644 --- a/Doc/library/audioop.rst +++ b/Doc/library/audioop.rst @@ -6,7 +6,8 @@ :deprecated: .. deprecated:: 3.11 - The :mod:`audioop` module is deprecated (see :pep:`594` for details). + The :mod:`audioop` module is deprecated + (see :pep:`PEP 594 <594#audioop>` for details). -------------- diff --git a/Doc/library/cgi.rst b/Doc/library/cgi.rst index 80c4d803..5744ee54 100644 --- a/Doc/library/cgi.rst +++ b/Doc/library/cgi.rst @@ -16,7 +16,8 @@ single: Common Gateway Interface .. deprecated:: 3.11 - The :mod:`cgi` module is deprecated (see :pep:`594` for details). + The :mod:`cgi` module is deprecated + (see :pep:`PEP 594 <594#cgi>` for details and alternatives). -------------- diff --git a/Doc/library/cgitb.rst b/Doc/library/cgitb.rst index 34941461..3b0b106a 100644 --- a/Doc/library/cgitb.rst +++ b/Doc/library/cgitb.rst @@ -17,7 +17,8 @@ single: tracebacks; in CGI scripts .. deprecated:: 3.11 - The :mod:`cgitb` module is deprecated (see :pep:`594` for details). + The :mod:`cgitb` module is deprecated + (see :pep:`PEP 594 <594#cgitb>` for details). -------------- diff --git a/Doc/library/chunk.rst b/Doc/library/chunk.rst index 7999420f..5a84c890 100644 --- a/Doc/library/chunk.rst +++ b/Doc/library/chunk.rst @@ -18,7 +18,8 @@ single: RMFF .. deprecated:: 3.11 - The :mod:`chunk` module is deprecated (see :pep:`594` for details). + The :mod:`chunk` module is deprecated + (see :pep:`PEP 594 <594#chunk>` for details). -------------- diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst index 3386208d..d4ea2b34 100644 --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@ -23,11 +23,11 @@ This module defines base classes for standard Python codecs (encoders and decoders) and provides access to the internal Python codec registry, which manages the codec and error handling lookup process. Most standard codecs -are :term:`text encodings `, which encode text to bytes, -but there are also codecs provided that encode text to text, and bytes to -bytes. Custom codecs may encode and decode between arbitrary types, but some -module features are restricted to use specifically with -:term:`text encodings `, or with codecs that encode to +are :term:`text encodings `, which encode text to bytes (and +decode bytes to text), but there are also codecs provided that encode text to +text, and bytes to bytes. Custom codecs may encode and decode between arbitrary +types, but some module features are restricted to be used specifically with +:term:`text encodings ` or with codecs that encode to :class:`bytes`. The module defines the following functions for encoding and decoding with @@ -294,58 +294,56 @@ codec will handle encoding and decoding errors. Error Handlers ^^^^^^^^^^^^^^ -To simplify and standardize error handling, -codecs may implement different error handling schemes by -accepting the *errors* string argument. The following string values are -defined and implemented by all standard Python codecs: +To simplify and standardize error handling, codecs may implement different +error handling schemes by accepting the *errors* string argument: -.. tabularcolumns:: |l|L| - -+-------------------------+-----------------------------------------------+ -| Value | Meaning | -+=========================+===============================================+ -| ``'strict'`` | Raise :exc:`UnicodeError` (or a subclass); | -| | this is the default. Implemented in | -| | :func:`strict_errors`. | -+-------------------------+-----------------------------------------------+ -| ``'ignore'`` | Ignore the malformed data and continue | -| | without further notice. Implemented in | -| | :func:`ignore_errors`. | -+-------------------------+-----------------------------------------------+ - -The following error handlers are only applicable to -:term:`text encodings `: + >>> 'German ß, ♬'.encode(encoding='ascii', errors='backslashreplace') + b'German \\xdf, \\u266c' + >>> 'German ß, ♬'.encode(encoding='ascii', errors='xmlcharrefreplace') + b'German ß, ♬' .. index:: + pair: strict; error handler's name + pair: ignore; error handler's name + pair: replace; error handler's name + pair: backslashreplace; error handler's name + pair: surrogateescape; error handler's name single: ? (question mark); replacement character single: \ (backslash); escape sequence single: \x; escape sequence single: \u; escape sequence single: \U; escape sequence - single: \N; escape sequence + +The following error handlers can be used with all Python +:ref:`standard-encodings` codecs: + +.. tabularcolumns:: |l|L| +-------------------------+-----------------------------------------------+ | Value | Meaning | +=========================+===============================================+ -| ``'replace'`` | Replace with a suitable replacement | -| | marker; Python will use the official | -| | ``U+FFFD`` REPLACEMENT CHARACTER for the | -| | built-in codecs on decoding, and '?' on | -| | encoding. Implemented in | -| | :func:`replace_errors`. | +| ``'strict'`` | Raise :exc:`UnicodeError` (or a subclass), | +| | this is the default. Implemented in | +| | :func:`strict_errors`. | +-------------------------+-----------------------------------------------+ -| ``'xmlcharrefreplace'`` | Replace with the appropriate XML character | -| | reference (only for encoding). Implemented | -| | in :func:`xmlcharrefreplace_errors`. | +| ``'ignore'`` | Ignore the malformed data and continue without| +| | further notice. Implemented in | +| | :func:`ignore_errors`. | ++-------------------------+-----------------------------------------------+ +| ``'replace'`` | Replace with a replacement marker. On | +| | encoding, use ``?`` (ASCII character). On | +| | decoding, use ``�`` (U+FFFD, the official | +| | REPLACEMENT CHARACTER). Implemented in | +| | :func:`replace_errors`. | +-------------------------+-----------------------------------------------+ | ``'backslashreplace'`` | Replace with backslashed escape sequences. | +| | On encoding, use hexadecimal form of Unicode | +| | code point with formats ``\xhh`` ``\uxxxx`` | +| | ``\Uxxxxxxxx``. On decoding, use hexadecimal | +| | form of byte value with format ``\xhh``. | | | Implemented in | | | :func:`backslashreplace_errors`. | +-------------------------+-----------------------------------------------+ -| ``'namereplace'`` | Replace with ``\N{...}`` escape sequences | -| | (only for encoding). Implemented in | -| | :func:`namereplace_errors`. | -+-------------------------+-----------------------------------------------+ | ``'surrogateescape'`` | On decoding, replace byte with individual | | | surrogate code ranging from ``U+DC80`` to | | | ``U+DCFF``. This code will then be turned | @@ -355,27 +353,55 @@ The following error handlers are only applicable to | | more.) | +-------------------------+-----------------------------------------------+ +.. index:: + pair: xmlcharrefreplace; error handler's name + pair: namereplace; error handler's name + single: \N; escape sequence + +The following error handlers are only applicable to encoding (within +:term:`text encodings `): + ++-------------------------+-----------------------------------------------+ +| Value | Meaning | ++=========================+===============================================+ +| ``'xmlcharrefreplace'`` | Replace with XML/HTML numeric character | +| | reference, which is a decimal form of Unicode | +| | code point with format ``&#num;`` Implemented | +| | in :func:`xmlcharrefreplace_errors`. | ++-------------------------+-----------------------------------------------+ +| ``'namereplace'`` | Replace with ``\N{...}`` escape sequences, | +| | what appears in the braces is the Name | +| | property from Unicode Character Database. | +| | Implemented in :func:`namereplace_errors`. | ++-------------------------+-----------------------------------------------+ + +.. index:: + pair: surrogatepass; error handler's name + In addition, the following error handler is specific to the given codecs: +-------------------+------------------------+-------------------------------------------+ | Value | Codecs | Meaning | +===================+========================+===========================================+ -|``'surrogatepass'``| utf-8, utf-16, utf-32, | Allow encoding and decoding of surrogate | -| | utf-16-be, utf-16-le, | codes. These codecs normally treat the | -| | utf-32-be, utf-32-le | presence of surrogates as an error. | +|``'surrogatepass'``| utf-8, utf-16, utf-32, | Allow encoding and decoding surrogate code| +| | utf-16-be, utf-16-le, | point (``U+D800`` - ``U+DFFF``) as normal | +| | utf-32-be, utf-32-le | code point. Otherwise these codecs treat | +| | | the presence of surrogate code point in | +| | | :class:`str` as an error. | +-------------------+------------------------+-------------------------------------------+ .. versionadded:: 3.1 The ``'surrogateescape'`` and ``'surrogatepass'`` error handlers. .. versionchanged:: 3.4 - The ``'surrogatepass'`` error handlers now works with utf-16\* and utf-32\* codecs. + The ``'surrogatepass'`` error handler now works with utf-16\* and utf-32\* + codecs. .. versionadded:: 3.5 The ``'namereplace'`` error handler. .. versionchanged:: 3.5 - The ``'backslashreplace'`` error handlers now works with decoding and + The ``'backslashreplace'`` error handler now works with decoding and translating. The set of allowed values can be extended by registering a new named error @@ -418,42 +444,59 @@ functions: .. function:: strict_errors(exception) - Implements the ``'strict'`` error handling: each encoding or - decoding error raises a :exc:`UnicodeError`. + Implements the ``'strict'`` error handling. + Each encoding or decoding error raises a :exc:`UnicodeError`. -.. function:: replace_errors(exception) - Implements the ``'replace'`` error handling (for :term:`text encodings - ` only): substitutes ``'?'`` for encoding errors - (to be encoded by the codec), and ``'\ufffd'`` (the Unicode replacement - character) for decoding errors. +.. function:: ignore_errors(exception) + Implements the ``'ignore'`` error handling. -.. function:: ignore_errors(exception) + Malformed data is ignored; encoding or decoding is continued without + further notice. - Implements the ``'ignore'`` error handling: malformed data is ignored and - encoding or decoding is continued without further notice. +.. function:: replace_errors(exception) -.. function:: xmlcharrefreplace_errors(exception) + Implements the ``'replace'`` error handling. - Implements the ``'xmlcharrefreplace'`` error handling (for encoding with - :term:`text encodings ` only): the - unencodable character is replaced by an appropriate XML character reference. + Substitutes ``?`` (ASCII character) for encoding errors or ``�`` (U+FFFD, + the official REPLACEMENT CHARACTER) for decoding errors. .. function:: backslashreplace_errors(exception) - Implements the ``'backslashreplace'`` error handling (for - :term:`text encodings ` only): malformed data is - replaced by a backslashed escape sequence. + Implements the ``'backslashreplace'`` error handling. + + Malformed data is replaced by a backslashed escape sequence. + On encoding, use the hexadecimal form of Unicode code point with formats + ``\xhh`` ``\uxxxx`` ``\Uxxxxxxxx``. On decoding, use the hexadecimal form of + byte value with format ``\xhh``. + + .. versionchanged:: 3.5 + Works with decoding and translating. + + +.. function:: xmlcharrefreplace_errors(exception) + + Implements the ``'xmlcharrefreplace'`` error handling (for encoding within + :term:`text encoding` only). + + The unencodable character is replaced by an appropriate XML/HTML numeric + character reference, which is a decimal form of Unicode code point with + format ``&#num;`` . + .. function:: namereplace_errors(exception) - Implements the ``'namereplace'`` error handling (for encoding with - :term:`text encodings ` only): the - unencodable character is replaced by a ``\N{...}`` escape sequence. + Implements the ``'namereplace'`` error handling (for encoding within + :term:`text encoding` only). + + The unencodable character is replaced by a ``\N{...}`` escape sequence. The + set of characters that appear in the braces is the Name property from + Unicode Character Database. For example, the German lowercase letter ``'ß'`` + will be converted to byte sequence ``\N{LATIN SMALL LETTER SHARP S}`` . .. versionadded:: 3.5 @@ -467,7 +510,7 @@ The base :class:`Codec` class defines these methods which also define the function interfaces of the stateless encoder and decoder: -.. method:: Codec.encode(input[, errors]) +.. method:: Codec.encode(input, errors='strict') Encodes the object *input* and returns a tuple (output object, length consumed). For instance, :term:`text encoding` converts @@ -485,7 +528,7 @@ function interfaces of the stateless encoder and decoder: of the output object type in this situation. -.. method:: Codec.decode(input[, errors]) +.. method:: Codec.decode(input, errors='strict') Decodes the object *input* and returns a tuple (output object, length consumed). For instance, for a :term:`text encoding`, decoding converts @@ -552,7 +595,7 @@ define in order to be compatible with the Python codec registry. object. - .. method:: encode(object[, final]) + .. method:: encode(object, final=False) Encodes *object* (taking the current state of the encoder into account) and returns the resulting encoded object. If this is the last call to @@ -609,7 +652,7 @@ define in order to be compatible with the Python codec registry. object. - .. method:: decode(object[, final]) + .. method:: decode(object, final=False) Decodes *object* (taking the current state of the decoder into account) and returns the resulting decoded object. If this is the last call to @@ -743,7 +786,7 @@ compatible with the Python codec registry. :func:`register_error`. - .. method:: read([size[, chars, [firstline]]]) + .. method:: read(size=-1, chars=-1, firstline=False) Decodes data from the stream and returns the resulting object. @@ -769,7 +812,7 @@ compatible with the Python codec registry. available on the stream, these should be read too. - .. method:: readline([size[, keepends]]) + .. method:: readline(size=None, keepends=True) Read one line from the input stream and return the decoded data. @@ -780,7 +823,7 @@ compatible with the Python codec registry. returned. - .. method:: readlines([sizehint[, keepends]]) + .. method:: readlines(sizehint=None, keepends=True) Read all lines available on the input stream and return them as a list of lines. @@ -871,7 +914,7 @@ Encodings and Unicode --------------------- Strings are stored internally as sequences of code points in -range ``0x0``--``0x10FFFF``. (See :pep:`393` for +range ``U+0000``--``U+10FFFF``. (See :pep:`393` for more details about the implementation.) Once a string object is used outside of CPU and memory, endianness and how these arrays are stored as bytes become an issue. As with other @@ -909,7 +952,7 @@ there's the so called BOM ("Byte Order Mark"). This is the Unicode character ``U+FEFF``. This character can be prepended to every ``UTF-16`` or ``UTF-32`` byte sequence. The byte swapped version of this character (``0xFFFE``) is an illegal character that may not appear in a Unicode text. So when the -first character in an ``UTF-16`` or ``UTF-32`` byte sequence +first character in a ``UTF-16`` or ``UTF-32`` byte sequence appears to be a ``U+FFFE`` the bytes have to be swapped on decoding. Unfortunately the character ``U+FEFF`` had a second purpose as a ``ZERO WIDTH NO-BREAK SPACE``: a character that has no width and doesn't allow @@ -952,7 +995,7 @@ encoding was used for encoding a string. Each charmap encoding can decode any random byte sequence. However that's not possible with UTF-8, as UTF-8 byte sequences have a structure that doesn't allow arbitrary byte sequences. To increase the reliability with which a UTF-8 encoding can be -detected, Microsoft invented a variant of UTF-8 (that Python 2.5 calls +detected, Microsoft invented a variant of UTF-8 (that Python calls ``"utf-8-sig"``) for its Notepad program: Before any of the Unicode characters is written to the file, a UTF-8 encoded BOM (which looks like this as a byte sequence: ``0xef``, ``0xbb``, ``0xbf``) is written. As it's rather improbable @@ -1420,7 +1463,7 @@ Internationalized Domain Names (IDN)). It builds upon the ``punycode`` encoding and :mod:`stringprep`. If you need the IDNA 2008 standard from :rfc:`5891` and :rfc:`5895`, use the -third-party `idna module _`. +third-party `idna module `_. These RFCs together define a protocol to support non-ASCII characters in domain names. A domain name containing non-ASCII characters (such as diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index 66a0f17a..d471c8ce 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -368,6 +368,9 @@ Functions and classes provided: # the with statement, even if attempts to open files later # in the list raise an exception + The :meth:`__enter__` method returns the :class:`ExitStack` instance, and + performs no additional operations. + Each instance maintains a stack of registered callbacks that are called in reverse order when the instance is closed (either explicitly or implicitly at the end of a :keyword:`with` statement). Note that callbacks are *not* diff --git a/Doc/library/crypt.rst b/Doc/library/crypt.rst index 73df87ca..e795f10f 100644 --- a/Doc/library/crypt.rst +++ b/Doc/library/crypt.rst @@ -17,7 +17,9 @@ pair: cipher; DES .. deprecated:: 3.11 - The :mod:`crypt` module is deprecated (see :pep:`594` for details). + The :mod:`crypt` module is deprecated + (see :pep:`PEP 594 <594#crypt>` for details and alternatives). + The :mod:`hashlib` module is a potential replacement for certain use cases. -------------- @@ -96,8 +98,7 @@ The :mod:`crypt` module defines the following functions: :func:`mksalt`, one of the ``crypt.METHOD_*`` values (though not all may be available on all platforms), or a full encrypted password including salt, as returned by this function. If *salt* is not - provided, the strongest method will be used (as returned by - :func:`methods`). + provided, the strongest method available in :attr:`methods` will be used. Checking a password is usually done by passing the plain-text password as *word* and the full results of a previous :func:`crypt` call, @@ -125,8 +126,8 @@ The :mod:`crypt` module defines the following functions: .. function:: mksalt(method=None, *, rounds=None) Return a randomly generated salt of the specified method. If no - *method* is given, the strongest method available as returned by - :func:`methods` is used. + *method* is given, the strongest method available in :attr:`methods` is + used. The return value is a string suitable for passing as the *salt* argument to :func:`crypt`. diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index c10e54f1..19ce19b1 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1361,10 +1361,6 @@ way is to instantiate one of the following classes: functions in these libraries use the ``stdcall`` calling convention, and are assumed to return :c:type:`int` by default. - On Windows CE only the standard calling convention is used, for convenience the - :class:`WinDLL` and :class:`OleDLL` use the standard calling convention on this - platform. - The Python :term:`global interpreter lock` is released before calling any function exported by these libraries, and reacquired afterwards. @@ -1665,8 +1661,7 @@ See :ref:`ctypes-callback-functions` for examples. .. function:: WINFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False) Windows only: The returned function prototype creates functions that use the - ``stdcall`` calling convention, except on Windows CE where - :func:`WINFUNCTYPE` is the same as :func:`CFUNCTYPE`. The function will + ``stdcall`` calling convention. The function will release the GIL during the call. *use_errno* and *use_last_error* have the same meaning as above. @@ -2513,7 +2508,7 @@ Arrays and pointers Abstract base class for arrays. The recommended way to create concrete array types is by multiplying any - :mod:`ctypes` data type with a positive integer. Alternatively, you can subclass + :mod:`ctypes` data type with a non-negative integer. Alternatively, you can subclass this type and define :attr:`_length_` and :attr:`_type_` class variables. Array elements can be read and written using standard subscript and slice accesses; for slice reads, the resulting object is diff --git a/Doc/library/email.charset.rst b/Doc/library/email.charset.rst index 38fda23b..adbe6c1c 100644 --- a/Doc/library/email.charset.rst +++ b/Doc/library/email.charset.rst @@ -58,9 +58,9 @@ Import this class from the :mod:`email.charset` module. .. attribute:: header_encoding If the character set must be encoded before it can be used in an email - header, this attribute will be set to ``Charset.QP`` (for - quoted-printable), ``Charset.BASE64`` (for base64 encoding), or - ``Charset.SHORTEST`` for the shortest of QP or BASE64 encoding. Otherwise, + header, this attribute will be set to ``charset.QP`` (for + quoted-printable), ``charset.BASE64`` (for base64 encoding), or + ``charset.SHORTEST`` for the shortest of QP or BASE64 encoding. Otherwise, it will be ``None``. @@ -68,7 +68,7 @@ Import this class from the :mod:`email.charset` module. Same as *header_encoding*, but describes the encoding for the mail message's body, which indeed may be different than the header encoding. - ``Charset.SHORTEST`` is not allowed for *body_encoding*. + ``charset.SHORTEST`` is not allowed for *body_encoding*. .. attribute:: output_charset @@ -175,9 +175,9 @@ new entries to the global character set, alias, and codec registries: *charset* is the input character set, and must be the canonical name of a character set. - Optional *header_enc* and *body_enc* is either ``Charset.QP`` for - quoted-printable, ``Charset.BASE64`` for base64 encoding, - ``Charset.SHORTEST`` for the shortest of quoted-printable or base64 encoding, + Optional *header_enc* and *body_enc* is either ``charset.QP`` for + quoted-printable, ``charset.BASE64`` for base64 encoding, + ``charset.SHORTEST`` for the shortest of quoted-printable or base64 encoding, or ``None`` for no encoding. ``SHORTEST`` is only valid for *header_enc*. The default is ``None`` for no encoding. diff --git a/Doc/library/errno.rst b/Doc/library/errno.rst index 1cbd51c5..c87da091 100644 --- a/Doc/library/errno.rst +++ b/Doc/library/errno.rst @@ -8,7 +8,7 @@ This module makes available standard ``errno`` system symbols. The value of each symbol is the corresponding integer value. The names and descriptions are -borrowed from :file:`linux/include/errno.h`, which should be pretty +borrowed from :file:`linux/include/errno.h`, which should be all-inclusive. @@ -27,25 +27,26 @@ defined by the module. The specific list of defined symbols is available as .. data:: EPERM - Operation not permitted + Operation not permitted. This error is mapped to the exception + :exc:`PermissionError`. .. data:: ENOENT - No such file or directory + No such file or directory. This error is mapped to the exception + :exc:`FileNotFoundError`. .. data:: ESRCH - No such process + No such process. This error is mapped to the exception + :exc:`ProcessLookupError`. .. data:: EINTR - Interrupted system call. - - .. seealso:: - This error is mapped to the exception :exc:`InterruptedError`. + Interrupted system call. This error is mapped to the exception + :exc:`InterruptedError`. .. data:: EIO @@ -75,12 +76,13 @@ defined by the module. The specific list of defined symbols is available as .. data:: ECHILD - No child processes + No child processes. This error is mapped to the exception + :exc:`ChildProcessError`. .. data:: EAGAIN - Try again + Try again. This error is mapped to the exception :exc:`BlockingIOError`. .. data:: ENOMEM @@ -90,7 +92,8 @@ defined by the module. The specific list of defined symbols is available as .. data:: EACCES - Permission denied + Permission denied. This error is mapped to the exception + :exc:`PermissionError`. .. data:: EFAULT @@ -110,7 +113,8 @@ defined by the module. The specific list of defined symbols is available as .. data:: EEXIST - File exists + File exists. This error is mapped to the exception + :exc:`FileExistsError`. .. data:: EXDEV @@ -125,12 +129,14 @@ defined by the module. The specific list of defined symbols is available as .. data:: ENOTDIR - Not a directory + Not a directory. This error is mapped to the exception + :exc:`NotADirectoryError`. .. data:: EISDIR - Is a directory + Is a directory. This error is mapped to the exception + :exc:`IsADirectoryError`. .. data:: EINVAL @@ -185,7 +191,8 @@ defined by the module. The specific list of defined symbols is available as .. data:: EPIPE - Broken pipe + Broken pipe. This error is mapped to the exception + :exc:`BrokenPipeError`. .. data:: EDOM @@ -230,7 +237,8 @@ defined by the module. The specific list of defined symbols is available as .. data:: EWOULDBLOCK - Operation would block + Operation would block. This error is mapped to the exception + :exc:`BlockingIOError`. .. data:: ENOMSG @@ -540,12 +548,14 @@ defined by the module. The specific list of defined symbols is available as .. data:: ECONNABORTED - Software caused connection abort + Software caused connection abort. This error is mapped to the + exception :exc:`ConnectionAbortedError`. .. data:: ECONNRESET - Connection reset by peer + Connection reset by peer. This error is mapped to the exception + :exc:`ConnectionResetError`. .. data:: ENOBUFS @@ -565,7 +575,8 @@ defined by the module. The specific list of defined symbols is available as .. data:: ESHUTDOWN - Cannot send after transport endpoint shutdown + Cannot send after transport endpoint shutdown. This error is mapped + to the exception :exc:`BrokenPipeError`. .. data:: ETOOMANYREFS @@ -575,12 +586,14 @@ defined by the module. The specific list of defined symbols is available as .. data:: ETIMEDOUT - Connection timed out + Connection timed out. This error is mapped to the exception + :exc:`TimeoutError`. .. data:: ECONNREFUSED - Connection refused + Connection refused. This error is mapped to the exception + :exc:`ConnectionRefusedError`. .. data:: EHOSTDOWN @@ -595,12 +608,14 @@ defined by the module. The specific list of defined symbols is available as .. data:: EALREADY - Operation already in progress + Operation already in progress. This error is mapped to the + exception :exc:`BlockingIOError`. .. data:: EINPROGRESS - Operation now in progress + Operation now in progress. This error is mapped to the exception + :exc:`BlockingIOError`. .. data:: ESTALE diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index c4945679..b6a5df87 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -234,6 +234,15 @@ The following exceptions are the exceptions that are usually raised. accidentally caught by code that catches :exc:`Exception` and thus prevent the interpreter from exiting. + .. note:: + + Catching a :exc:`KeyboardInterrupt` requires special consideration. + Because it can be raised at unpredictable points, it may, in some + circumstances, leave the running program in an inconsistent state. It is + generally best to allow :exc:`KeyboardInterrupt` to end the program as + quickly as possible or avoid raising it entirely. (See + :ref:`handlers-and-exceptions`.) + .. exception:: MemoryError @@ -604,8 +613,8 @@ depending on the system error code. Raised when an operation would block on an object (e.g. socket) set for non-blocking operation. - Corresponds to :c:data:`errno` ``EAGAIN``, ``EALREADY``, - ``EWOULDBLOCK`` and ``EINPROGRESS``. + Corresponds to :c:data:`errno` :py:data:`~errno.EAGAIN`, :py:data:`~errno.EALREADY`, + :py:data:`~errno.EWOULDBLOCK` and :py:data:`~errno.EINPROGRESS`. In addition to those of :exc:`OSError`, :exc:`BlockingIOError` can have one more attribute: @@ -619,7 +628,7 @@ depending on the system error code. .. exception:: ChildProcessError Raised when an operation on a child process failed. - Corresponds to :c:data:`errno` ``ECHILD``. + Corresponds to :c:data:`errno` :py:data:`~errno.ECHILD`. .. exception:: ConnectionError @@ -633,35 +642,35 @@ depending on the system error code. A subclass of :exc:`ConnectionError`, raised when trying to write on a pipe while the other end has been closed, or trying to write on a socket which has been shutdown for writing. - Corresponds to :c:data:`errno` ``EPIPE`` and ``ESHUTDOWN``. + Corresponds to :c:data:`errno` :py:data:`~errno.EPIPE` and :py:data:`~errno.ESHUTDOWN`. .. exception:: ConnectionAbortedError A subclass of :exc:`ConnectionError`, raised when a connection attempt is aborted by the peer. - Corresponds to :c:data:`errno` ``ECONNABORTED``. + Corresponds to :c:data:`errno` :py:data:`~errno.ECONNABORTED`. .. exception:: ConnectionRefusedError A subclass of :exc:`ConnectionError`, raised when a connection attempt is refused by the peer. - Corresponds to :c:data:`errno` ``ECONNREFUSED``. + Corresponds to :c:data:`errno` :py:data:`~errno.ECONNREFUSED`. .. exception:: ConnectionResetError A subclass of :exc:`ConnectionError`, raised when a connection is reset by the peer. - Corresponds to :c:data:`errno` ``ECONNRESET``. + Corresponds to :c:data:`errno` :py:data:`~errno.ECONNRESET`. .. exception:: FileExistsError Raised when trying to create a file or directory which already exists. - Corresponds to :c:data:`errno` ``EEXIST``. + Corresponds to :c:data:`errno` :py:data:`~errno.EEXIST`. .. exception:: FileNotFoundError Raised when a file or directory is requested but doesn't exist. - Corresponds to :c:data:`errno` ``ENOENT``. + Corresponds to :c:data:`errno` :py:data:`~errno.ENOENT`. .. exception:: InterruptedError @@ -677,7 +686,7 @@ depending on the system error code. Raised when a file operation (such as :func:`os.remove`) is requested on a directory. - Corresponds to :c:data:`errno` ``EISDIR``. + Corresponds to :c:data:`errno` :py:data:`~errno.EISDIR`. .. exception:: NotADirectoryError @@ -685,23 +694,23 @@ depending on the system error code. something which is not a directory. On most POSIX platforms, it may also be raised if an operation attempts to open or traverse a non-directory file as if it were a directory. - Corresponds to :c:data:`errno` ``ENOTDIR``. + Corresponds to :c:data:`errno` :py:data:`~errno.ENOTDIR`. .. exception:: PermissionError Raised when trying to run an operation without the adequate access rights - for example filesystem permissions. - Corresponds to :c:data:`errno` ``EACCES`` and ``EPERM``. + Corresponds to :c:data:`errno` :py:data:`~errno.EACCES` and :py:data:`~errno.EPERM`. .. exception:: ProcessLookupError Raised when a given process doesn't exist. - Corresponds to :c:data:`errno` ``ESRCH``. + Corresponds to :c:data:`errno` :py:data:`~errno.ESRCH`. .. exception:: TimeoutError Raised when a system function timed out at the system level. - Corresponds to :c:data:`errno` ``ETIMEDOUT``. + Corresponds to :c:data:`errno` :py:data:`~errno.ETIMEDOUT`. .. versionadded:: 3.3 All the above :exc:`OSError` subclasses were added. diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst index 07a15d27..f1c071ab 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -37,7 +37,8 @@ descriptor. On macOS, the fcntl module exposes the ``F_GETPATH`` constant, which obtains the path of a file from a file descriptor. On Linux(>=3.15), the fcntl module exposes the ``F_OFD_GETLK``, ``F_OFD_SETLK`` - and ``F_OFD_SETLKW`` constants, which working with open file description locks. + and ``F_OFD_SETLKW`` constants, which are used when working with open file + description locks. The module defines the following functions: diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 9a9c707d..13d7d6e5 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -862,7 +862,8 @@ are always available. They are listed here in alphabetical order. Return ``True`` if *class* is a subclass (direct, indirect or :term:`virtual `) of *classinfo*. A class is considered a subclass of itself. *classinfo* may be a tuple of class - objects, in which case return ``True`` if *class* is a subclass of any entry + objects (or recursively, other such tuples), + in which case return ``True`` if *class* is a subclass of any entry in *classinfo*. In any other case, a :exc:`TypeError` exception is raised. @@ -1113,7 +1114,11 @@ are always available. They are listed here in alphabetical order. *buffering* is an optional integer used to set the buffering policy. Pass 0 to switch buffering off (only allowed in binary mode), 1 to select line buffering (only usable in text mode), and an integer > 1 to indicate the size - in bytes of a fixed-size chunk buffer. When no *buffering* argument is + in bytes of a fixed-size chunk buffer. Note that specifying a buffer size this + way applies for binary buffered I/O, but ``TextIOWrapper`` (i.e., files opened + with ``mode='r+'``) would have another buffering. To disable buffering in + ``TextIOWrapper``, consider using the ``write_through`` flag for + :func:`io.TextIOWrapper.reconfigure`. When no *buffering* argument is given, the default buffering policy works as follows: * Binary files are buffered in fixed-size chunks; the size of the buffer is diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst index 3c468ebf..ced84c7f 100644 --- a/Doc/library/glob.rst +++ b/Doc/library/glob.rst @@ -23,8 +23,11 @@ according to the rules used by the Unix shell, although results are returned in arbitrary order. No tilde expansion is done, but ``*``, ``?``, and character ranges expressed with ``[]`` will be correctly matched. This is done by using the :func:`os.scandir` and :func:`fnmatch.fnmatch` functions in concert, and -not by actually invoking a subshell. Note that unlike :func:`fnmatch.fnmatch`, -:mod:`glob` treats filenames beginning with a dot (``.``) as special cases. +not by actually invoking a subshell. + +Note that files beginning with a dot (``.``) can only be matched by +patterns that also start with a dot, +unlike :func:`fnmatch.fnmatch` or :func:`pathlib.Path.glob`. (For tilde and shell variable expansion, use :func:`os.path.expanduser` and :func:`os.path.expandvars`.) diff --git a/Doc/library/grp.rst b/Doc/library/grp.rst index 74de3f95..fbfb922d 100644 --- a/Doc/library/grp.rst +++ b/Doc/library/grp.rst @@ -12,7 +12,7 @@ Unix versions. Group database entries are reported as a tuple-like object, whose attributes correspond to the members of the ``group`` structure (Attribute field below, see -````): +````): +-------+-----------+---------------------------------+ | Index | Attribute | Meaning | diff --git a/Doc/library/imghdr.rst b/Doc/library/imghdr.rst index f63a0fa5..186480be 100644 --- a/Doc/library/imghdr.rst +++ b/Doc/library/imghdr.rst @@ -8,7 +8,8 @@ **Source code:** :source:`Lib/imghdr.py` .. deprecated:: 3.11 - The :mod:`imghdr` module is deprecated (see :pep:`594` for details). + The :mod:`imghdr` module is deprecated + (see :pep:`PEP 594 <594#imghdr>` for details and alternatives). -------------- diff --git a/Doc/library/index.rst b/Doc/library/index.rst index 0fd6e4c0..5007bacb 100644 --- a/Doc/library/index.rst +++ b/Doc/library/index.rst @@ -75,5 +75,4 @@ the `Python Package Index `_. windows.rst unix.rst superseded.rst - undoc.rst security_warnings.rst diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 9f62dd21..ea57aae7 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -299,7 +299,7 @@ I/O Base Classes Return ``True`` if the stream can be read from. If ``False``, :meth:`read` will raise :exc:`OSError`. - .. method:: readline(size=-1) + .. method:: readline(size=-1, /) Read and return one line from the stream. If *size* is specified, at most *size* bytes will be read. @@ -308,7 +308,7 @@ I/O Base Classes the *newline* argument to :func:`open` can be used to select the line terminator(s) recognized. - .. method:: readlines(hint=-1) + .. method:: readlines(hint=-1, /) Read and return a list of lines from the stream. *hint* can be specified to control the number of lines read: no more lines will be read if the @@ -320,7 +320,7 @@ I/O Base Classes Note that it's already possible to iterate on file objects using ``for line in file: ...`` without calling ``file.readlines()``. - .. method:: seek(offset, whence=SEEK_SET) + .. method:: seek(offset, whence=SEEK_SET, /) Change the stream position to the given byte *offset*. *offset* is interpreted relative to the position indicated by *whence*. The default @@ -352,7 +352,7 @@ I/O Base Classes Return the current stream position. - .. method:: truncate(size=None) + .. method:: truncate(size=None, /) Resize the stream to the given *size* in bytes (or the current position if *size* is not specified). The current stream position isn't changed. @@ -369,7 +369,7 @@ I/O Base Classes Return ``True`` if the stream supports writing. If ``False``, :meth:`write` and :meth:`truncate` will raise :exc:`OSError`. - .. method:: writelines(lines) + .. method:: writelines(lines, /) Write a list of lines to the stream. Line separators are not added, so it is usual for each of the lines provided to have a line separator at the @@ -394,7 +394,7 @@ I/O Base Classes :class:`RawIOBase` provides these methods in addition to those from :class:`IOBase`: - .. method:: read(size=-1) + .. method:: read(size=-1, /) Read up to *size* bytes from the object and return them. As a convenience, if *size* is unspecified or -1, all bytes until EOF are returned. @@ -413,7 +413,7 @@ I/O Base Classes Read and return all the bytes from the stream until EOF, using multiple calls to the stream if necessary. - .. method:: readinto(b) + .. method:: readinto(b, /) Read bytes into a pre-allocated, writable :term:`bytes-like object` *b*, and return the @@ -421,7 +421,7 @@ I/O Base Classes If the object is in non-blocking mode and no bytes are available, ``None`` is returned. - .. method:: write(b) + .. method:: write(b, /) Write the given :term:`bytes-like object`, *b*, to the underlying raw stream, and return the number of @@ -478,7 +478,7 @@ I/O Base Classes .. versionadded:: 3.1 - .. method:: read(size=-1) + .. method:: read(size=-1, /) Read and return up to *size* bytes. If the argument is omitted, ``None``, or negative, data is read and returned until EOF is reached. An empty @@ -493,7 +493,7 @@ I/O Base Classes A :exc:`BlockingIOError` is raised if the underlying raw stream is in non blocking-mode, and has no data available at the moment. - .. method:: read1([size]) + .. method:: read1(size=-1, /) Read and return up to *size* bytes, with at most one call to the underlying raw stream's :meth:`~RawIOBase.read` (or @@ -504,7 +504,7 @@ I/O Base Classes If *size* is ``-1`` (the default), an arbitrary number of bytes are returned (more than zero unless EOF is reached). - .. method:: readinto(b) + .. method:: readinto(b, /) Read bytes into a pre-allocated, writable :term:`bytes-like object` *b* and return the number of bytes read. @@ -516,7 +516,7 @@ I/O Base Classes A :exc:`BlockingIOError` is raised if the underlying raw stream is in non blocking-mode, and has no data available at the moment. - .. method:: readinto1(b) + .. method:: readinto1(b, /) Read bytes into a pre-allocated, writable :term:`bytes-like object` *b*, using at most one call to @@ -528,7 +528,7 @@ I/O Base Classes .. versionadded:: 3.5 - .. method:: write(b) + .. method:: write(b, /) Write the given :term:`bytes-like object`, *b*, and return the number of bytes written (always equal to the length of *b* in bytes, since if @@ -611,7 +611,7 @@ Buffered Streams Buffered I/O streams provide a higher-level interface to an I/O device than raw I/O does. -.. class:: BytesIO([initial_bytes]) +.. class:: BytesIO(initial_bytes=b'') A binary stream using an in-memory bytes buffer. It inherits :class:`BufferedIOBase`. The buffer is discarded when the @@ -646,14 +646,14 @@ than raw I/O does. Return :class:`bytes` containing the entire contents of the buffer. - .. method:: read1([size]) + .. method:: read1(size=-1, /) In :class:`BytesIO`, this is the same as :meth:`~BufferedIOBase.read`. .. versionchanged:: 3.7 The *size* argument is now optional. - .. method:: readinto1(b) + .. method:: readinto1(b, /) In :class:`BytesIO`, this is the same as :meth:`~BufferedIOBase.readinto`. @@ -676,18 +676,18 @@ than raw I/O does. :class:`BufferedReader` provides or overrides these methods in addition to those from :class:`BufferedIOBase` and :class:`IOBase`: - .. method:: peek([size]) + .. method:: peek(size=0, /) Return bytes from the stream without advancing the position. At most one single read on the raw stream is done to satisfy the call. The number of bytes returned may be less or more than requested. - .. method:: read([size]) + .. method:: read(size=-1, /) Read and return *size* bytes, or if *size* is not given or negative, until EOF or if the read call would block in non-blocking mode. - .. method:: read1([size]) + .. method:: read1(size=-1, /) Read and return up to *size* bytes with only one call on the raw stream. If at least one byte is buffered, only buffered bytes are returned. @@ -724,7 +724,7 @@ than raw I/O does. Force bytes held in the buffer into the raw stream. A :exc:`BlockingIOError` should be raised if the raw stream blocks. - .. method:: write(b) + .. method:: write(b, /) Write the :term:`bytes-like object`, *b*, and return the number of bytes written. When in non-blocking mode, a @@ -747,7 +747,7 @@ than raw I/O does. are guaranteed to be implemented. -.. class:: BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE) +.. class:: BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE, /) A buffered binary stream providing higher-level access to two non seekable :class:`RawIOBase` raw binary streams---one readable, the other writeable. @@ -814,19 +814,19 @@ Text I/O .. versionadded:: 3.1 - .. method:: read(size=-1) + .. method:: read(size=-1, /) Read and return at most *size* characters from the stream as a single :class:`str`. If *size* is negative or ``None``, reads until EOF. - .. method:: readline(size=-1) + .. method:: readline(size=-1, /) Read until newline or EOF and return a single ``str``. If the stream is already at EOF, an empty string is returned. If *size* is specified, at most *size* characters will be read. - .. method:: seek(offset, whence=SEEK_SET) + .. method:: seek(offset, whence=SEEK_SET, /) Change the stream position to the given *offset*. Behaviour depends on the *whence* parameter. The default value for *whence* is @@ -853,7 +853,7 @@ Text I/O does not usually represent a number of bytes in the underlying binary storage. - .. method:: write(s) + .. method:: write(s, /) Write the string *s* to the stream and return the number of characters written. diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 1810e04c..608e70df 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -125,13 +125,6 @@ See :ref:`json-commandline` for detailed documentation. This module's encoders and decoders preserve input and output order by default. Order is only lost if the underlying containers are unordered. - Prior to Python 3.7, :class:`dict` was not guaranteed to be ordered, so - inputs and outputs were typically scrambled unless - :class:`collections.OrderedDict` was specifically requested. Starting - with Python 3.7, the regular :class:`dict` became order preserving, so - it is no longer necessary to specify :class:`collections.OrderedDict` for - JSON generation and parsing. - Basic Usage ----------- diff --git a/Doc/library/locale.rst b/Doc/library/locale.rst index bf57a083..5b5a0c75 100644 --- a/Doc/library/locale.rst +++ b/Doc/library/locale.rst @@ -423,10 +423,10 @@ The :mod:`locale` module defines the following exception and functions: .. versionadded:: 3.5 -.. function:: atof(string) +.. function:: atof(string, func=float) - Converts a string to a floating point number, following the :const:`LC_NUMERIC` - settings. + Converts a string to a number, following the :const:`LC_NUMERIC` settings, + by calling *func* on the result of calling :func:`delocalize` on *string*. .. function:: atoi(string) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 9d6167cc..f85c691f 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -1073,16 +1073,6 @@ functions. Logs a message with level *level* on the root logger. The other arguments are interpreted as for :func:`debug`. - .. note:: The above module-level convenience functions, which delegate to the - root logger, call :func:`basicConfig` to ensure that at least one handler - is available. Because of this, they should *not* be used in threads, - in versions of Python earlier than 2.7.1 and 3.2, unless at least one - handler has been added to the root logger *before* the threads are - started. In earlier versions of Python, due to a thread safety shortcoming - in :func:`basicConfig`, this can (under rare circumstances) lead to - handlers being added multiple times to the root logger, which can in turn - lead to multiple messages for the same event. - .. function:: disable(level=CRITICAL) Provides an overriding level *level* for all loggers which takes precedence over diff --git a/Doc/library/mailcap.rst b/Doc/library/mailcap.rst index bf9639bd..a22b5b9c 100644 --- a/Doc/library/mailcap.rst +++ b/Doc/library/mailcap.rst @@ -3,9 +3,15 @@ .. module:: mailcap :synopsis: Mailcap file handling. + :deprecated: **Source code:** :source:`Lib/mailcap.py` +.. deprecated:: 3.11 + The :mod:`mailcap` module is deprecated + (see :pep:`PEP 594 <594#mailcap>` for details). + The :mod:`mimetypes` module provides an alternative. + -------------- Mailcap files are used to configure how MIME-aware applications such as mail diff --git a/Doc/library/math.rst b/Doc/library/math.rst index b20e557b..ad9116b6 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -32,8 +32,8 @@ Number-theoretic and representation functions .. function:: ceil(x) Return the ceiling of *x*, the smallest integer greater than or equal to *x*. - If *x* is not a float, delegates to ``x.__ceil__()``, which should return an - :class:`~numbers.Integral` value. + If *x* is not a float, delegates to :meth:`x.__ceil__ `, + which should return an :class:`~numbers.Integral` value. .. function:: comb(n, k) @@ -77,9 +77,9 @@ Number-theoretic and representation functions .. function:: floor(x) - Return the floor of *x*, the largest integer less than or equal to *x*. - If *x* is not a float, delegates to ``x.__floor__()``, which should return an - :class:`~numbers.Integral` value. + Return the floor of *x*, the largest integer less than or equal to *x*. If + *x* is not a float, delegates to :meth:`x.__floor__ `, which + should return an :class:`~numbers.Integral` value. .. function:: fmod(x, y) @@ -298,9 +298,11 @@ Number-theoretic and representation functions .. function:: trunc(x) - Return the :class:`~numbers.Real` value *x* truncated to an - :class:`~numbers.Integral` (usually an integer). Delegates to - :meth:`x.__trunc__() `. + Return *x* with the fractional part + removed, leaving the integer part. This rounds toward 0: ``trunc()`` is + equivalent to :func:`floor` for positive *x*, and equivalent to :func:`ceil` + for negative *x*. If *x* is not a float, delegates to :meth:`x.__trunc__ + `, which should return an :class:`~numbers.Integral` value. .. function:: ulp(x) @@ -622,8 +624,23 @@ Constants .. data:: nan - A floating-point "not a number" (NaN) value. Equivalent to the output of - ``float('nan')``. + A floating-point "not a number" (NaN) value. Equivalent to the output of + ``float('nan')``. Due to the requirements of the `IEEE-754 standard + `_, ``math.nan`` and ``float('nan')`` are + not considered to equal to any other numeric value, including themselves. To check + whether a number is a NaN, use the :func:`isnan` function to test + for NaNs instead of ``is`` or ``==``. + Example:: + + >>> import math + >>> math.nan == math.nan + False + >>> float('nan') == float('nan') + False + >>> math.isnan(math.nan) + True + >>> math.isnan(float('nan')) + True .. versionadded:: 3.5 diff --git a/Doc/library/msilib.rst b/Doc/library/msilib.rst index 5ce18a1f..0eba2275 100644 --- a/Doc/library/msilib.rst +++ b/Doc/library/msilib.rst @@ -14,7 +14,8 @@ .. index:: single: msi .. deprecated:: 3.11 - The :mod:`msilib` module is deprecated (see :pep:`594` for details). + The :mod:`msilib` module is deprecated + (see :pep:`PEP 594 <594#msilib>` for details). -------------- diff --git a/Doc/library/netdata.rst b/Doc/library/netdata.rst index 8a3ad687..2520036c 100644 --- a/Doc/library/netdata.rst +++ b/Doc/library/netdata.rst @@ -13,7 +13,6 @@ on the Internet. email.rst json.rst - mailcap.rst mailbox.rst mimetypes.rst base64.rst diff --git a/Doc/library/nis.rst b/Doc/library/nis.rst index f6b6ea83..49fe6295 100644 --- a/Doc/library/nis.rst +++ b/Doc/library/nis.rst @@ -11,7 +11,8 @@ .. sectionauthor:: Moshe Zadka .. deprecated:: 3.11 - The :mod:`nis` module is deprecated (see :pep:`594` for details). + The :mod:`nis` module is deprecated + (see :pep:`PEP 594 <594#nis>` for details). -------------- diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index b1094198..0d686b10 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -131,7 +131,7 @@ option These option syntaxes are not supported by :mod:`optparse`, and they never will be. This is deliberate: the first three are non-standard on any environment, and the last only makes sense if you're exclusively targeting - VMS, MS-DOS, and/or Windows. + Windows or certain legacy platforms (e.g. VMS, MS-DOS). option argument an argument that follows an option, is closely associated with that option, diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index 2fb6ea9d..97bb684a 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -5,22 +5,16 @@ :synopsis: Operations on pathnames. **Source code:** :source:`Lib/posixpath.py` (for POSIX) and -:source:`Lib/ntpath.py` (for Windows NT). +:source:`Lib/ntpath.py` (for Windows). .. index:: single: path; operations -------------- -This module implements some useful functions on pathnames. To read or -write files see :func:`open`, and for accessing the filesystem see the -:mod:`os` module. The path parameters can be passed as either strings, -or bytes. Applications are encouraged to represent file names as -(Unicode) character strings. Unfortunately, some file names may not be -representable as strings on Unix, so applications that need to support -arbitrary file names on Unix should use bytes objects to represent -path names. Vice versa, using bytes objects cannot represent all file -names on Windows (in the standard ``mbcs`` encoding), hence Windows -applications should use string objects to access all files. +This module implements some useful functions on pathnames. To read or write +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. Functions such as :func:`expanduser` and :func:`expandvars` can be invoked @@ -38,7 +32,6 @@ the :mod:`glob` module.) their parameters. The result is an object of the same type, if a path or file name is returned. - .. note:: Since different operating systems have different path name conventions, there diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 2f7b3701..35a7e1e9 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -109,8 +109,8 @@ process and user. This mapping is captured the first time the :mod:`os` module is imported, typically during Python startup as part of processing :file:`site.py`. Changes - to the environment made after this time are not reflected in ``os.environ``, - except for changes made by modifying ``os.environ`` directly. + to the environment made after this time are not reflected in :data:`os.environ`, + except for changes made by modifying :data:`os.environ` directly. This mapping may be used to modify the environment as well as query the environment. :func:`putenv` will be called automatically when the mapping @@ -122,8 +122,8 @@ process and user. .. note:: - Calling :func:`putenv` directly does not change ``os.environ``, so it's better - to modify ``os.environ``. + Calling :func:`putenv` directly does not change :data:`os.environ`, so it's better + to modify :data:`os.environ`. .. note:: @@ -133,7 +133,7 @@ process and user. You can delete items in this mapping to unset environment variables. :func:`unsetenv` will be called automatically when an item is deleted from - ``os.environ``, and when one of the :meth:`pop` or :meth:`clear` methods is + :data:`os.environ`, and when one of the :meth:`pop` or :meth:`clear` methods is called. .. versionchanged:: 3.9 @@ -224,7 +224,10 @@ 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. + *default* if it doesn't. *key*, *default* and the result are str. 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. On Unix, keys and values are decoded with :func:`sys.getfilesystemencoding` and ``'surrogateescape'`` error handler. Use :func:`os.getenvb` if you @@ -236,7 +239,11 @@ 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. + *default* if it doesn't. *key*, *default* and the result are 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. + :func:`getenvb` is only available if :data:`supports_bytes_environ` is ``True``. @@ -287,7 +294,8 @@ process and user. 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 - field from the password record for *user*. + field from the password record for *user*, because that group ID will + otherwise be potentially omitted. .. availability:: Unix. @@ -442,10 +450,11 @@ process and user. changes to the environment affect subprocesses started with :func:`os.system`, :func:`popen` or :func:`fork` and :func:`execv`. - Assignments to items in ``os.environ`` are automatically translated into + Assignments to items in :data:`os.environ` are automatically translated into corresponding calls to :func:`putenv`; however, calls to :func:`putenv` - don't update ``os.environ``, so it is actually preferable to assign to items - of ``os.environ``. + don't update :data:`os.environ`, so it is actually preferable to assign to items + of :data:`os.environ`. This also applies to :func:`getenv` and :func:`getenvb`, which + respectively use :data:`os.environ` and :data:`os.environb` in their implementations. .. note:: @@ -644,10 +653,10 @@ process and user. environment affect subprocesses started with :func:`os.system`, :func:`popen` or :func:`fork` and :func:`execv`. - Deletion of items in ``os.environ`` is automatically translated into a + Deletion of items in :data:`os.environ` is automatically translated into a corresponding call to :func:`unsetenv`; however, calls to :func:`unsetenv` - don't update ``os.environ``, so it is actually preferable to delete items of - ``os.environ``. + don't update :data:`os.environ`, so it is actually preferable to delete items of + :data:`os.environ`. .. audit-event:: os.unsetenv key os.unsetenv @@ -2206,7 +2215,7 @@ features: .. function:: replace(src, dst, *, src_dir_fd=None, dst_dir_fd=None) - Rename the file or directory *src* to *dst*. If *dst* is a directory, + Rename the file or directory *src* to *dst*. If *dst* is a non-empty directory, :exc:`OSError` will be raised. If *dst* exists and is a file, it will be replaced silently if the user has permission. The operation may fail if *src* and *dst* are on different filesystems. If successful, @@ -3318,8 +3327,8 @@ to be ignored. Add a path to the DLL search path. This search path is used when resolving dependencies for imported - extension modules (the module itself is resolved through sys.path), - and also by :mod:`ctypes`. + extension modules (the module itself is resolved through + :data:`sys.path`), and also by :mod:`ctypes`. Remove the directory by calling **close()** on the returned object or using it in a :keyword:`with` statement. diff --git a/Doc/library/ossaudiodev.rst b/Doc/library/ossaudiodev.rst index e0f0a6b8..728ee303 100644 --- a/Doc/library/ossaudiodev.rst +++ b/Doc/library/ossaudiodev.rst @@ -7,7 +7,8 @@ :deprecated: .. deprecated:: 3.11 - The :mod:`ossaudiodev` module is deprecated (see :pep:`594` for details). + The :mod:`ossaudiodev` module is deprecated + (see :pep:`PEP 594 <594#ossaudiodev>` for details). -------------- diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 3a41b545..30611abc 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1028,7 +1028,7 @@ call fails (for example because the path doesn't exist). Rename this file or directory to the given *target*, and return a new Path instance pointing to *target*. If *target* points to an existing file or - directory, it will be unconditionally replaced. + empty directory, it will be unconditionally replaced. The target path may be absolute or relative. Relative paths are interpreted relative to the current working directory, *not* the directory of the Path diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst index 13e1a199..dcd509de 100644 --- a/Doc/library/pdb.rst +++ b/Doc/library/pdb.rst @@ -233,7 +233,8 @@ Multiple commands may be entered on a single line, separated by ``;;``. (A single ``;`` is not used as it is the separator for multiple commands in a line that is passed to the Python parser.) No intelligence is applied to separating the commands; the input is split at the first ``;;`` pair, even if it is in the -middle of a quoted string. +middle of a quoted string. A workaround for strings with double semicolons +is to use implicit string concatenation ``';'';'`` or ``";"";"``. .. index:: pair: .pdbrc; file diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index be48561e..f7db0e84 100644 --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -147,7 +147,7 @@ to read the pickle produced. earlier versions of Python. * Protocol version 2 was introduced in Python 2.3. It provides much more - efficient pickling of :term:`new-style class`\es. Refer to :pep:`307` for + efficient pickling of :term:`new-style classes `. Refer to :pep:`307` for information about improvements brought by protocol 2. * Protocol version 3 was added in Python 3.0. It has explicit support for @@ -261,7 +261,7 @@ process more convenient: protocol argument is needed. Bytes past the pickled representation of the object are ignored. - Arguments *file*, *fix_imports*, *encoding*, *errors*, *strict* and *buffers* + Arguments *fix_imports*, *encoding*, *errors*, *strict* and *buffers* have the same meaning as in the :class:`Unpickler` constructor. .. versionchanged:: 3.8 @@ -368,7 +368,7 @@ The :mod:`pickle` module exports three classes, :class:`Pickler`, .. versionadded:: 3.3 - .. method:: reducer_override(self, obj) + .. method:: reducer_override(obj) Special reducer that can be defined in :class:`Pickler` subclasses. This method has priority over any reducer in the :attr:`dispatch_table`. It @@ -494,20 +494,18 @@ What can be pickled and unpickled? The following types can be pickled: -* ``None``, ``True``, and ``False`` - -* integers, floating point numbers, complex numbers +* ``None``, ``True``, and ``False``; -* strings, bytes, bytearrays +* integers, floating-point numbers, complex numbers; -* tuples, lists, sets, and dictionaries containing only picklable objects +* strings, bytes, bytearrays; -* functions defined at the top level of a module (using :keyword:`def`, not - :keyword:`lambda`) +* tuples, lists, sets, and dictionaries containing only picklable objects; -* built-in functions defined at the top level of a module +* functions (built-in and user-defined) defined at the top level of a module + (using :keyword:`def`, not :keyword:`lambda`); -* classes that are defined at the top level of a module +* classes defined at the top level of a module; * instances of such classes whose :attr:`~object.__dict__` or the result of calling :meth:`__getstate__` is picklable (see section :ref:`pickle-inst` for @@ -520,14 +518,14 @@ structure may exceed the maximum recursion depth, a :exc:`RecursionError` will b raised in this case. You can carefully raise this limit with :func:`sys.setrecursionlimit`. -Note that functions (built-in and user-defined) are pickled by "fully qualified" -name reference, not by value. [#]_ This means that only the function name is +Note that functions (built-in and user-defined) are pickled by fully qualified +name, not by value. [#]_ This means that only the function name is pickled, along with the name of the module the function is defined in. Neither the function's code, nor any of its function attributes are pickled. Thus the defining module must be importable in the unpickling environment, and the module must contain the named object, otherwise an exception will be raised. [#]_ -Similarly, classes are pickled by named reference, so the same restrictions in +Similarly, classes are pickled by fully qualified name, so the same restrictions in the unpickling environment apply. Note that none of the class's code or data is pickled, so in the following example the class attribute ``attr`` is not restored in the unpickling environment:: @@ -537,7 +535,7 @@ restored in the unpickling environment:: picklestring = pickle.dumps(Foo) -These restrictions are why picklable functions and classes must be defined in +These restrictions are why picklable functions and classes must be defined at the top level of a module. Similarly, when class instances are pickled, their class's code and data are not @@ -569,7 +567,7 @@ implementation of this behaviour:: def save(obj): return (obj.__class__, obj.__dict__) - def load(cls, attributes): + def restore(cls, attributes): obj = cls.__new__(cls) obj.__dict__.update(attributes) return obj @@ -788,14 +786,15 @@ the code :: f = io.BytesIO() p = MyPickler(f) -does the same, but all instances of ``MyPickler`` will by default -share the same dispatch table. The equivalent code using the -:mod:`copyreg` module is :: +does the same but all instances of ``MyPickler`` will by default +share the private dispatch table. On the other hand, the code :: copyreg.pickle(SomeClass, reduce_SomeClass) f = io.BytesIO() p = pickle.Pickler(f) +modifies the global dispatch table shared by all users of the :mod:`copyreg` module. + .. _pickle-state: Handling Stateful Objects @@ -1098,7 +1097,7 @@ Here is an example of an unpickler allowing only few safe classes from the """Helper function analogous to pickle.loads().""" return RestrictedUnpickler(io.BytesIO(s)).load() -A sample usage of our unpickler working has intended:: +A sample usage of our unpickler working as intended:: >>> restricted_loads(pickle.dumps([1, 2, range(15)])) [1, 2, range(0, 15)] @@ -1142,7 +1141,7 @@ For the simplest code, use the :func:`dump` and :func:`load` functions. :: # An arbitrary collection of objects supported by pickle. data = { - 'a': [1, 2.0, 3, 4+6j], + 'a': [1, 2.0, 3+4j], 'b': ("character string", b"byte string"), 'c': {None, True, False} } @@ -1198,6 +1197,6 @@ The following example reads the resulting pickled data. :: operations. .. [#] The limitation on alphanumeric characters is due to the fact - the persistent IDs, in protocol 0, are delimited by the newline + that persistent IDs in protocol 0 are delimited by the newline character. Therefore if any kind of newline characters occurs in - persistent IDs, the resulting pickle will become unreadable. + persistent IDs, the resulting pickled data will become unreadable. diff --git a/Doc/library/pipes.rst b/Doc/library/pipes.rst index 25f80856..bc21c097 100644 --- a/Doc/library/pipes.rst +++ b/Doc/library/pipes.rst @@ -11,7 +11,9 @@ **Source code:** :source:`Lib/pipes.py` .. deprecated:: 3.11 - The :mod:`pipes` module is deprecated (see :pep:`594` for details). + The :mod:`pipes` module is deprecated + (see :pep:`PEP 594 <594#pipes>` for details). + Please use the :mod:`subprocess` module instead. -------------- diff --git a/Doc/library/pkgutil.rst b/Doc/library/pkgutil.rst index 3b17b9a6..788a02dc 100644 --- a/Doc/library/pkgutil.rst +++ b/Doc/library/pkgutil.rst @@ -26,7 +26,7 @@ support. __path__ = extend_path(__path__, __name__) This will add to the package's ``__path__`` all subdirectories of directories - on ``sys.path`` named after the package. This is useful if one wants to + on :data:`sys.path` named after the package. This is useful if one wants to distribute different parts of a single logical package as multiple directories. @@ -128,9 +128,9 @@ support. Yield :term:`finder` objects for the given module name. - If fullname contains a '.', the finders will be for the package + If fullname contains a ``'.'``, the finders will be for the package containing fullname, otherwise they will be all registered top level - finders (i.e. those on both sys.meta_path and sys.path_hooks). + finders (i.e. those on both :data:`sys.meta_path` and :data:`sys.path_hooks`). If the named module is in a package, that package is imported as a side effect of invoking this function. @@ -145,7 +145,7 @@ support. .. function:: iter_modules(path=None, prefix='') Yields :class:`ModuleInfo` for all submodules on *path*, or, if - *path* is ``None``, all top-level modules on ``sys.path``. + *path* is ``None``, all top-level modules on :data:`sys.path`. *path* should be either ``None`` or a list of paths to look for modules in. diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst index d87205c3..722a5b59 100644 --- a/Doc/library/platform.rst +++ b/Doc/library/platform.rst @@ -139,7 +139,7 @@ Cross Platform .. function:: release() - Returns the system's release, e.g. ``'2.2.0'`` or ``'NT'`` An empty string is + Returns the system's release, e.g. ``'2.2.0'`` or ``'NT'``. An empty string is returned if the value cannot be determined. @@ -176,7 +176,7 @@ Cross Platform Entries which cannot be determined are set to ``''``. .. versionchanged:: 3.3 - Result changed from a tuple to a namedtuple. + Result changed from a tuple to a :func:`~collections.namedtuple`. Java Platform @@ -201,7 +201,9 @@ Windows Platform Get additional version information from the Windows Registry and return a tuple ``(release, version, csd, ptype)`` referring to OS release, version number, - CSD level (service pack) and OS type (multi/single processor). + CSD level (service pack) and OS type (multi/single processor). Values which + cannot be determined are set to the defaults given as parameters (which all + default to an empty string). As a hint: *ptype* is ``'Uniprocessor Free'`` on single processor NT machines and ``'Multiprocessor Free'`` on multi processor machines. The *'Free'* refers @@ -211,9 +213,9 @@ Windows Platform .. function:: win32_edition() - Returns a string representing the current Windows edition. Possible - values include but are not limited to ``'Enterprise'``, ``'IoTUAP'``, - ``'ServerStandard'``, and ``'nanoserver'``. + Returns a string representing the current Windows edition, or ``None`` if the + value cannot be determined. Possible values include but are not limited to + ``'Enterprise'``, ``'IoTUAP'``, ``'ServerStandard'``, and ``'nanoserver'``. .. versionadded:: 3.8 diff --git a/Doc/library/queue.rst b/Doc/library/queue.rst index 0ec5900b..def39eae 100644 --- a/Doc/library/queue.rst +++ b/Doc/library/queue.rst @@ -138,7 +138,7 @@ provide the public methods described below. .. method:: Queue.put_nowait(item) - Equivalent to ``put(item, False)``. + Equivalent to ``put(item, block=False)``. .. method:: Queue.get(block=True, timeout=None) @@ -249,7 +249,7 @@ SimpleQueue Objects .. method:: SimpleQueue.put_nowait(item) - Equivalent to ``put(item)``, provided for compatibility with + Equivalent to ``put(item, block=False)``, provided for compatibility with :meth:`Queue.put_nowait`. diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst index af35e81a..26a4f143 100644 --- a/Doc/library/runpy.rst +++ b/Doc/library/runpy.rst @@ -93,7 +93,7 @@ The :mod:`runpy` module provides two functions: run this way, as well as ensuring the real module name is always accessible as ``__spec__.name``. -.. function:: run_path(file_path, init_globals=None, run_name=None) +.. function:: run_path(path_name, init_globals=None, run_name=None) .. index:: module: __main__ @@ -140,7 +140,7 @@ The :mod:`runpy` module provides two functions: A number of alterations are also made to the :mod:`sys` module. Firstly, ``sys.path`` may be altered as described above. ``sys.argv[0]`` is updated - with the value of ``file_path`` and ``sys.modules[__name__]`` is updated + with the value of ``path_name`` and ``sys.modules[__name__]`` is updated with a temporary module object for the module being executed. All modifications to items in :mod:`sys` are reverted before the function returns. diff --git a/Doc/library/secrets.rst b/Doc/library/secrets.rst index afa8e2d3..c22da727 100644 --- a/Doc/library/secrets.rst +++ b/Doc/library/secrets.rst @@ -193,7 +193,7 @@ suitable for password recovery applications: .. testcode:: import secrets - url = 'https://mydomain.com/reset=' + secrets.token_urlsafe() + url = 'https://example.com/reset=' + secrets.token_urlsafe() diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index 11c67074..193c0100 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -160,7 +160,8 @@ Directory and files operations Copies the file *src* to the file or directory *dst*. *src* and *dst* should be :term:`path-like objects ` or strings. If *dst* specifies a directory, the file will be copied into *dst* using the - base filename from *src*. Returns the path to the newly created file. + base filename from *src*. If *dst* specifies a file that already exists, + it will be replaced. Returns the path to the newly created file. If *follow_symlinks* is false, and *src* is a symbolic link, *dst* will be created as a symbolic link. If *follow_symlinks* @@ -230,9 +231,8 @@ Directory and files operations dirs_exist_ok=False) Recursively copy an entire directory tree rooted at *src* to a directory - named *dst* and return the destination directory. *dirs_exist_ok* dictates - whether to raise an exception in case *dst* or any missing parent directory - already exists. + named *dst* and return the destination directory. All intermediate + directories needed to contain *dst* will also be created by default. Permissions and times of directories are copied with :func:`copystat`, individual files are copied using :func:`~shutil.copy2`. @@ -263,8 +263,14 @@ Directory and files operations If *copy_function* is given, it must be a callable that will be used to copy each file. It will be called with the source path and the destination path -   as arguments. By default, :func:`~shutil.copy2` is used, but any function -   that supports the same signature (like :func:`~shutil.copy`) can be used. + as arguments. By default, :func:`~shutil.copy2` is used, but any function + that supports the same signature (like :func:`~shutil.copy`) can be used. + + If *dirs_exist_ok* is false (the default) and *dst* already exists, a + :exc:`FileExistsError` is raised. If *dirs_exist_ok* is true, the copying + operation will continue if it encounters existing directories, and files + within the *dst* tree will be overwritten by corresponding files from the + *src* tree. .. audit-event:: shutil.copytree src,dst shutil.copytree @@ -275,7 +281,7 @@ Directory and files operations .. versionchanged:: 3.2 Added the *copy_function* argument to be able to provide a custom copy function. - Added the *ignore_dangling_symlinks* argument to silent dangling symlinks + Added the *ignore_dangling_symlinks* argument to silence dangling symlinks errors when *symlinks* is false. .. versionchanged:: 3.8 @@ -470,42 +476,7 @@ file then shutil will silently fallback on using less efficient copytree example ~~~~~~~~~~~~~~~~ -This example is the implementation of the :func:`copytree` function, described -above, with the docstring omitted. It demonstrates many of the other functions -provided by this module. :: - - def copytree(src, dst, symlinks=False): - names = os.listdir(src) - os.makedirs(dst) - errors = [] - for name in names: - srcname = os.path.join(src, name) - dstname = os.path.join(dst, name) - try: - if symlinks and os.path.islink(srcname): - linkto = os.readlink(srcname) - os.symlink(linkto, dstname) - elif os.path.isdir(srcname): - copytree(srcname, dstname, symlinks) - else: - copy2(srcname, dstname) - # XXX What about devices, sockets etc.? - except OSError as why: - errors.append((srcname, dstname, str(why))) - # catch the Error from the recursive copytree so that we can - # continue with other files - except Error as err: - errors.extend(err.args[0]) - try: - copystat(src, dst) - except OSError as why: - # can't copy file access times on Windows - if why.winerror is None: - errors.extend((src, dst, str(why))) - if errors: - raise Error(errors) - -Another example that uses the :func:`ignore_patterns` helper:: +An example that uses the :func:`ignore_patterns` helper:: from shutil import copytree, ignore_patterns @@ -659,10 +630,16 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules. .. audit-event:: shutil.unpack_archive filename,extract_dir,format shutil.unpack_archive + .. warning:: + + Never extract archives from untrusted sources without prior inspection. + It is possible that files are created outside of the path specified in + the *extract_dir* argument, e.g. members that have absolute filenames + starting with "/" or filenames with two dots "..". + .. versionchanged:: 3.7 Accepts a :term:`path-like object` for *filename* and *extract_dir*. - .. function:: register_unpack_format(name, extensions, function[, extra_args[, description]]) Registers an unpack format. *name* is the name of the format and diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst index e1daeff4..1a419f42 100644 --- a/Doc/library/signal.rst +++ b/Doc/library/signal.rst @@ -46,6 +46,9 @@ This has consequences: arbitrary amount of time, regardless of any signals received. The Python signal handlers will be called when the calculation finishes. +* If the handler raises an exception, it will be raised "out of thin air" in + the main thread. See the :ref:`note below ` for a + discussion. .. _signals-and-threads: @@ -673,7 +676,75 @@ case, wrap your entry point to catch this exception as follows:: if __name__ == '__main__': main() -Do not set :const:`SIGPIPE`'s disposition to :const:`SIG_DFL` -in order to avoid :exc:`BrokenPipeError`. Doing that would cause -your program to exit unexpectedly also whenever any socket connection -is interrupted while your program is still writing to it. +Do not set :const:`SIGPIPE`'s disposition to :const:`SIG_DFL` in +order to avoid :exc:`BrokenPipeError`. Doing that would cause +your program to exit unexpectedly whenever any socket +connection is interrupted while your program is still writing to +it. + +.. _handlers-and-exceptions: + +Note on Signal Handlers and Exceptions +-------------------------------------- + +If a signal handler raises an exception, the exception will be propagated to +the main thread and may be raised after any :term:`bytecode` instruction. Most +notably, a :exc:`KeyboardInterrupt` may appear at any point during execution. +Most Python code, including the standard library, cannot be made robust against +this, and so a :exc:`KeyboardInterrupt` (or any other exception resulting from +a signal handler) may on rare occasions put the program in an unexpected state. + +To illustrate this issue, consider the following code:: + + class SpamContext: + def __init__(self): + self.lock = threading.Lock() + + def __enter__(self): + # If KeyboardInterrupt occurs here, everything is fine + self.lock.acquire() + # If KeyboardInterrupt occcurs here, __exit__ will not be called + ... + # KeyboardInterrupt could occur just before the function returns + + def __exit__(self, exc_type, exc_val, exc_tb): + ... + self.lock.release() + +For many programs, especially those that merely want to exit on +:exc:`KeyboardInterrupt`, this is not a problem, but applications that are +complex or require high reliability should avoid raising exceptions from signal +handlers. They should also avoid catching :exc:`KeyboardInterrupt` as a means +of gracefully shutting down. Instead, they should install their own +:const:`SIGINT` handler. Below is an example of an HTTP server that avoids +:exc:`KeyboardInterrupt`:: + + import signal + import socket + from selectors import DefaultSelector, EVENT_READ + from http.server import HTTPServer, SimpleHTTPRequestHandler + + interrupt_read, interrupt_write = socket.socketpair() + + def handler(signum, frame): + print('Signal handler called with signal', signum) + interrupt_write.send(b'\0') + signal.signal(signal.SIGINT, handler) + + def serve_forever(httpd): + sel = DefaultSelector() + sel.register(interrupt_read, EVENT_READ) + sel.register(httpd, EVENT_READ) + + while True: + for key, _ in sel.select(): + if key.fileobj == interrupt_read: + interrupt_read.recv(1) + return + if key.fileobj == httpd: + httpd.handle_request() + + print("Serving on port 8000") + httpd = HTTPServer(('', 8000), SimpleHTTPRequestHandler) + serve_forever(httpd) + print("Shutdown...") diff --git a/Doc/library/smtpd.rst b/Doc/library/smtpd.rst index a39bc024..8fd009e5 100644 --- a/Doc/library/smtpd.rst +++ b/Doc/library/smtpd.rst @@ -15,7 +15,8 @@ This module offers several classes to implement SMTP (email) servers. .. deprecated:: 3.6 - :mod:`smtpd` will be removed in Python 3.12 (:pep:`594`). + :mod:`smtpd` will be removed in Python 3.12 + (see :pep:`PEP 594 <594#smtpd>` for details). The `aiosmtpd `_ package is a recommended replacement for this module. It is based on :mod:`asyncio` and provides a more straightforward API. diff --git a/Doc/library/sndhdr.rst b/Doc/library/sndhdr.rst index 41bce18b..3ca36f27 100644 --- a/Doc/library/sndhdr.rst +++ b/Doc/library/sndhdr.rst @@ -15,7 +15,8 @@ single: u-LAW .. deprecated:: 3.11 - The :mod:`sndhdr` module is deprecated (see :pep:`594` for details). + The :mod:`sndhdr` module is deprecated + (see :pep:`PEP 594 <594#sndhdr>` for details and alternatives). -------------- diff --git a/Doc/library/spwd.rst b/Doc/library/spwd.rst index cb31a10a..40f50de0 100644 --- a/Doc/library/spwd.rst +++ b/Doc/library/spwd.rst @@ -7,7 +7,8 @@ :deprecated: .. deprecated:: 3.11 - The :mod:`spwd` module is deprecated (see :pep:`594` for details). + The :mod:`spwd` module is deprecated + (see :pep:`PEP 594 <594#spwd>` for details and alternatives). -------------- diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 9e695065..d4ba3e26 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -373,24 +373,21 @@ Connection Objects .. method:: execute(sql[, parameters]) - This is a nonstandard shortcut that creates a cursor object by calling - the :meth:`~Connection.cursor` method, calls the cursor's - :meth:`~Cursor.execute` method with the *parameters* given, and returns - the cursor. + Create a new :class:`Cursor` object and call + :meth:`~Cursor.execute` on it with the given *sql* and *parameters*. + Return the new cursor object. .. method:: executemany(sql[, parameters]) - This is a nonstandard shortcut that creates a cursor object by - calling the :meth:`~Connection.cursor` method, calls the cursor's - :meth:`~Cursor.executemany` method with the *parameters* given, and - returns the cursor. + Create a new :class:`Cursor` object and call + :meth:`~Cursor.executemany` on it with the given *sql* and *parameters*. + Return the new cursor object. .. method:: executescript(sql_script) - This is a nonstandard shortcut that creates a cursor object by - calling the :meth:`~Connection.cursor` method, calls the cursor's - :meth:`~Cursor.executescript` method with the given *sql_script*, and - returns the cursor. + Create a new :class:`Cursor` object and call + :meth:`~Cursor.executescript` on it with the given *sql_script*. + Return the new cursor object. .. method:: create_function(name, num_params, func, *, deterministic=False) diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index c3acf61d..af9bf798 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -1357,7 +1357,7 @@ SSL sockets also have the following additional methods and attributes: .. method:: SSLSocket.version() Return the actual SSL protocol version negotiated by the connection - as a string, or ``None`` is no secure connection is established. + as a string, or ``None`` if no secure connection is established. As of this writing, possible return values include ``"SSLv2"``, ``"SSLv3"``, ``"TLSv1"``, ``"TLSv1.1"`` and ``"TLSv1.2"``. Recent OpenSSL versions may define more return values. @@ -1494,7 +1494,7 @@ to speed up repeated connections from the same clients. string must be the path to a single file in PEM format containing the certificate as well as any number of CA certificates needed to establish the certificate's authenticity. The *keyfile* string, if present, must - point to a file containing the private key in. Otherwise the private + point to a file containing the private key. Otherwise the private key will be taken from *certfile* as well. See the discussion of :ref:`ssl-certificates` for more information on how the certificate is stored in the *certfile*. @@ -2345,7 +2345,7 @@ waiting for clients to connect:: context.load_cert_chain(certfile="mycertfile", keyfile="mykeyfile") bindsocket = socket.socket() - bindsocket.bind(('myaddr.mydomain.com', 10023)) + bindsocket.bind(('myaddr.example.com', 10023)) bindsocket.listen(5) When a client connects, you'll call :meth:`accept` on the socket to get the diff --git a/Doc/library/stat.rst b/Doc/library/stat.rst index 98219eae..083dc5e3 100644 --- a/Doc/library/stat.rst +++ b/Doc/library/stat.rst @@ -109,7 +109,7 @@ Example:: for f in os.listdir(top): pathname = os.path.join(top, f) - mode = os.stat(pathname).st_mode + mode = os.lstat(pathname).st_mode if S_ISDIR(mode): # It's a directory, recurse into it walktree(pathname, callback) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index b10909d8..28924867 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1448,7 +1448,8 @@ multiple fragments. depends on whether *encoding* or *errors* is given, as follows. If neither *encoding* nor *errors* is given, ``str(object)`` returns - :meth:`object.__str__() `, which is the "informal" or nicely + :meth:`type(object).__str__(object) `, + which is the "informal" or nicely printable string representation of *object*. For string objects, this is the string itself. If *object* does not have a :meth:`~object.__str__` method, then :func:`str` falls back to returning @@ -2117,7 +2118,11 @@ expression support in the :mod:`re` module). >>> "they're bill's friends from the UK".title() "They'Re Bill'S Friends From The Uk" - A workaround for apostrophes can be constructed using regular expressions:: + The :func:`string.capwords` function does not have this problem, as it + splits words on spaces only. + + Alternatively, a workaround for apostrophes can be constructed using regular + expressions:: >>> import re >>> def titlecase(s): @@ -2497,16 +2502,6 @@ The representation of bytes objects uses the literal format (``b'...'``) since it is often more useful than e.g. ``bytes([46, 46, 46])``. You can always convert a bytes object into a list of integers using ``list(b)``. -.. note:: - For Python 2.x users: In the Python 2.x series, a variety of implicit - conversions between 8-bit strings (the closest thing 2.x offers to a - built-in binary data type) and Unicode strings were permitted. This was a - backwards compatibility workaround to account for the fact that Python - originally only supported 8-bit text, and Unicode text was a later - addition. In Python 3.x, those implicit conversions are gone - conversions - between 8-bit binary data and Unicode text must be explicit, and bytes and - string objects will always compare unequal. - .. _typebytearray: @@ -3545,7 +3540,7 @@ The conversion types are: | | be used for Python2/3 code bases. | | +------------+-----------------------------------------------------+-------+ | ``'a'`` | Bytes (converts any Python object using | \(5) | -| | ``repr(obj).encode('ascii','backslashreplace)``). | | +| | ``repr(obj).encode('ascii', 'backslashreplace')``). | | +------------+-----------------------------------------------------+-------+ | ``'r'`` | ``'r'`` is an alias for ``'a'`` and should only | \(7) | | | be used for Python2/3 code bases. | | @@ -4306,10 +4301,6 @@ then they can be used interchangeably to index the same dictionary entry. (Note however, that since computers store floating-point numbers as approximations it is usually unwise to use them as dictionary keys.) -Dictionaries can be created by placing a comma-separated list of ``key: value`` -pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: -'jack', 4127: 'sjoerd'}``, or by the :class:`dict` constructor. - .. class:: dict(**kwargs) dict(mapping, **kwargs) dict(iterable, **kwargs) diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index f9e9f63f..45eff7ff 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -214,7 +214,9 @@ compatibility with older versions, see the :ref:`call-function-trio` section. .. exception:: CalledProcessError Subclass of :exc:`SubprocessError`, raised when a process run by - :func:`check_call` or :func:`check_output` returns a non-zero exit status. + :func:`check_call`, :func:`check_output`, or :func:`run` (with ``check=True``) + returns a non-zero exit status. + .. attribute:: returncode diff --git a/Doc/library/sunau.rst b/Doc/library/sunau.rst index cfb1257f..b4d996e6 100644 --- a/Doc/library/sunau.rst +++ b/Doc/library/sunau.rst @@ -10,7 +10,8 @@ **Source code:** :source:`Lib/sunau.py` .. deprecated:: 3.11 - The :mod:`sunau` module is deprecated (see :pep:`594` for details). + The :mod:`sunau` module is deprecated + (see :pep:`PEP 594 <594#sunau>` for details). -------------- diff --git a/Doc/library/superseded.rst b/Doc/library/superseded.rst index e3f9b0d3..b38f1669 100644 --- a/Doc/library/superseded.rst +++ b/Doc/library/superseded.rst @@ -20,9 +20,10 @@ backwards compatibility. They have been superseded by other modules. crypt.rst imghdr.rst imp.rst + mailcap.rst msilib.rst - nntplib.rst nis.rst + nntplib.rst optparse.rst ossaudiodev.rst pipes.rst diff --git a/Doc/library/telnetlib.rst b/Doc/library/telnetlib.rst index 97b0a713..48a927c8 100644 --- a/Doc/library/telnetlib.rst +++ b/Doc/library/telnetlib.rst @@ -12,7 +12,8 @@ .. index:: single: protocol; Telnet .. deprecated:: 3.11 - The :mod:`telnetlib` module is deprecated (see :pep:`594` for details). + The :mod:`telnetlib` module is deprecated + (see :pep:`PEP 594 <594#telnetlib>` for details and alternatives). -------------- diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst index 6bd7d003..fe47a4f0 100644 --- a/Doc/library/tempfile.rst +++ b/Doc/library/tempfile.rst @@ -84,7 +84,7 @@ The module defines the following user-callable items: file-like object. Whether the name can be used to open the file a second time, while the named temporary file is still open, varies across platforms (it can be so used on Unix; it cannot - on Windows NT or later). If *delete* is true (the default), the file is + on Windows). If *delete* is true (the default), the file is deleted as soon as it is closed. The returned object is always a file-like object whose :attr:`!file` attribute is the underlying true file object. This file-like object can diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 999852a5..401887f2 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -63,16 +63,72 @@ the modern themed widget set and API:: from tkinter import ttk -.. class:: Tk(screenName=None, baseName=None, className='Tk', useTk=1) - - The :class:`Tk` class is instantiated without arguments. This creates a toplevel - widget of Tk which usually is the main window of an application. Each instance - has its own associated Tcl interpreter. - - .. FIXME: The following keyword arguments are currently recognized: - - -.. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=0) +.. class:: Tk(screenName=None, baseName=None, className='Tk', useTk=True, sync=False, use=None) + + Construct a toplevel Tk widget, which is usually the main window of an + application, and initialize a Tcl interpreter for this widget. Each + instance has its own associated Tcl interpreter. + + The :class:`Tk` class is typically instantiated using all default values. + However, the following keyword arguments are currently recognized: + + *screenName* + When given (as a string), sets the :envvar:`DISPLAY` environment + variable. (X11 only) + *baseName* + Name of the profile file. By default, *baseName* is derived from the + program name (``sys.argv[0]``). + *className* + Name of the widget class. Used as a profile file and also as the name + with which Tcl is invoked (*argv0* in *interp*). + *useTk* + If ``True``, initialize the Tk subsystem. The :func:`tkinter.Tcl() ` + function sets this to ``False``. + *sync* + If ``True``, execute all X server commands synchronously, so that errors + are reported immediately. Can be used for debugging. (X11 only) + *use* + Specifies the *id* of the window in which to embed the application, + instead of it being created as an independent toplevel window. *id* must + be specified in the same way as the value for the -use option for + toplevel widgets (that is, it has a form like that returned by + :meth:`winfo_id`). + + Note that on some platforms this will only work correctly if *id* refers + to a Tk frame or toplevel that has its -container option enabled. + + :class:`Tk` reads and interprets profile files, named + :file:`.{className}.tcl` and :file:`.{baseName}.tcl`, into the Tcl + interpreter and calls :func:`exec` on the contents of + :file:`.{className}.py` and :file:`.{baseName}.py`. The path for the + profile files is the :envvar:`HOME` environment variable or, if that + isn't defined, then :attr:`os.curdir`. + + .. attribute:: tk + + The Tk application object created by instantiating :class:`Tk`. This + provides access to the Tcl interpreter. Each widget that is attached + the same instance of :class:`Tk` has the same value for its :attr:`tk` + attribute. + + .. attribute:: master + + The widget object that contains this widget. For :class:`Tk`, the + *master* is :const:`None` because it is the main window. The terms + *master* and *parent* are similar and sometimes used interchangeably + as argument names; however, calling :meth:`winfo_parent` returns a + string of the widget name whereas :attr:`master` returns the object. + *parent*/*child* reflects the tree-like relationship while + *master*/*slave* reflects the container structure. + + .. attribute:: children + + The immediate descendants of this widget as a :class:`dict` with the + child widget names as the keys and the child instance objects as the + values. + + +.. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=False) The :func:`Tcl` function is a factory function which creates an object much like that created by the :class:`Tk` class, except that it does not initialize the Tk diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 2689c7f2..f3c6a2e0 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -103,7 +103,7 @@ Note that ``None`` as a type hint is a special case and is replaced by NewType ======= -Use the :func:`NewType` helper function to create distinct types:: +Use the :func:`NewType` helper to create distinct types:: from typing import NewType @@ -132,7 +132,7 @@ accidentally creating a ``UserId`` in an invalid way:: Note that these checks are enforced only by the static type checker. At runtime, the statement ``Derived = NewType('Derived', Base)`` will make ``Derived`` a -function that immediately returns whatever parameter you pass it. That means +callable that immediately returns whatever parameter you pass it. That means the expression ``Derived(some_value)`` does not create a new class or introduce any overhead beyond that of a regular function call. @@ -194,6 +194,10 @@ For example:: on_error: Callable[[int, Exception], None]) -> None: # Body + async def on_update(value: str) -> None: + # Body + callback: Callable[[str], Awaitable[None]] = on_update + It is possible to declare the return type of a callable without specifying the call signature by substituting a literal ellipsis for the list of arguments in the type hint: ``Callable[..., ReturnType]``. @@ -431,7 +435,7 @@ manner. Use :data:`Any` to indicate that a value is dynamically typed. Nominal vs structural subtyping =============================== -Initially :pep:`484` defined Python static type system as using +Initially :pep:`484` defined the Python static type system as using *nominal subtyping*. This means that a class ``A`` is allowed where a class ``B`` is expected if and only if ``A`` is a subclass of ``B``. @@ -749,7 +753,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn ``no_type_check`` functionality that currently exists in the ``typing`` module which completely disables typechecking annotations on a function or a class, the ``Annotated`` type allows for both static typechecking - of ``T`` (e.g., via mypy or Pyre, which can safely ignore ``x``) + of ``T`` (which can safely ignore ``x``) together with runtime access to ``x`` within a specific application. Ultimately, the responsibility of how to interpret the annotations (if @@ -930,7 +934,7 @@ These are not used in annotations. They are building blocks for creating generic self.radius = radius # Use a type variable to show that the return type - # will always be an instance of whatever `cls` is + # will always be an instance of whatever ``cls`` is @classmethod def with_circumference(cls: type[C], circumference: float) -> C: """Create a circle with the specified circumference""" @@ -1060,7 +1064,7 @@ These are not used in annotations. They are building blocks for declaring types. The resulting class has an extra attribute ``__annotations__`` giving a dict that maps the field names to the field types. (The field names are in the ``_fields`` attribute and the default values are in the - ``_field_defaults`` attribute both of which are part of the namedtuple + ``_field_defaults`` attribute, both of which are part of the :func:`~collections.namedtuple` API.) ``NamedTuple`` subclasses can also have docstrings and methods:: @@ -1136,7 +1140,7 @@ These are not used in annotations. They are building blocks for declaring types. Point2D = TypedDict('Point2D', x=int, y=int, label=str) The functional syntax should also be used when any of the keys are not valid - :ref:`identifiers`, for example because they are keywords or contain hyphens. + :ref:`identifiers `, for example because they are keywords or contain hyphens. Example:: # raises SyntaxError @@ -1178,7 +1182,7 @@ These are not used in annotations. They are building blocks for declaring types. y: int z: int - A ``TypedDict`` cannot inherit from a non-TypedDict class, + A ``TypedDict`` cannot inherit from a non-\ ``TypedDict`` class, notably including :class:`Generic`. For example:: class X(TypedDict): @@ -1586,7 +1590,7 @@ Corresponding to other types in :mod:`collections.abc` .. class:: Hashable - An alias to :class:`collections.abc.Hashable` + An alias to :class:`collections.abc.Hashable`. .. class:: Reversible(Iterable[T_co]) @@ -1598,7 +1602,7 @@ Corresponding to other types in :mod:`collections.abc` .. class:: Sized - An alias to :class:`collections.abc.Sized` + An alias to :class:`collections.abc.Sized`. Asynchronous programming """""""""""""""""""""""" @@ -1803,7 +1807,7 @@ Functions and decorators ... class Sub(Base): def done(self) -> None: # Error reported by type checker - ... + ... @final class Leaf: @@ -1940,10 +1944,10 @@ Constant .. note:: - If ``from __future__ import annotations`` is used in Python 3.7 or later, + If ``from __future__ import annotations`` is used, annotations are not evaluated at function definition time. - Instead, they are stored as strings in ``__annotations__``, - This makes it unnecessary to use quotes around the annotation. + Instead, they are stored as strings in ``__annotations__``. + This makes it unnecessary to use quotes around the annotation (see :pep:`563`). .. versionadded:: 3.5.2 diff --git a/Doc/library/undoc.rst b/Doc/library/undoc.rst deleted file mode 100644 index 2444080d..00000000 --- a/Doc/library/undoc.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _undoc: - -******************** -Undocumented Modules -******************** - -Here's a quick listing of modules that are currently undocumented, but that -should be documented. Feel free to contribute documentation for them! (Send -via email to docs@python.org.) - -The idea and original contents for this chapter were taken from a posting by -Fredrik Lundh; the specific contents of this chapter have been substantially -revised. - - -Platform specific modules -========================= - -These modules are used to implement the :mod:`os.path` module, and are not -documented beyond this mention. There's little need to document these. - -:mod:`ntpath` - --- Implementation of :mod:`os.path` on Win32 and Win64 platforms. - -:mod:`posixpath` - --- Implementation of :mod:`os.path` on POSIX. diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst index 3fbb1b6b..537fbcf4 100644 --- a/Doc/library/unittest.mock.rst +++ b/Doc/library/unittest.mock.rst @@ -2549,7 +2549,7 @@ your assertion is gone: >>> mock = Mock(name='Thing', return_value=None) >>> mock(1, 2, 3) - >>> mock.assret_called_once_with(4, 5, 6) + >>> mock.assret_called_once_with(4, 5, 6) # Intentional typo! Your tests can pass silently and incorrectly because of the typo. @@ -2569,7 +2569,7 @@ attributes on the mock that exist on the real class: >>> from urllib import request >>> mock = Mock(spec=request.Request) - >>> mock.assret_called_with + >>> mock.assret_called_with # Intentional typo! Traceback (most recent call last): ... AttributeError: Mock object has no attribute 'assret_called_with' @@ -2581,7 +2581,7 @@ with any methods on the mock: >>> mock.has_data() - >>> mock.has_data.assret_called_with() + >>> mock.has_data.assret_called_with() # Intentional typo! Auto-speccing solves this problem. You can either pass ``autospec=True`` to :func:`patch` / :func:`patch.object` or use the :func:`create_autospec` function to create a @@ -2624,7 +2624,7 @@ any typos in our asserts will raise the correct error:: >>> req.add_header('spam', 'eggs') - >>> req.add_header.assret_called_with + >>> req.add_header.assret_called_with # Intentional typo! Traceback (most recent call last): ... AttributeError: Mock object has no attribute 'assret_called_with' diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index 90807579..a000428c 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -2418,7 +2418,7 @@ To add cleanup code that must be run even in the case of an exception, use after :func:`setUpModule` if :func:`setUpModule` raises an exception. It is responsible for calling all the cleanup functions added by - :func:`addCleanupModule`. If you need cleanup functions to be called + :func:`addModuleCleanup`. If you need cleanup functions to be called *prior* to :func:`tearDownModule` then you can call :func:`doModuleCleanups` yourself. diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst index bfb994e3..ae9abe7d 100644 --- a/Doc/library/urllib.request.rst +++ b/Doc/library/urllib.request.rst @@ -213,6 +213,7 @@ The following classes are provided: (X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11"``, while :mod:`urllib`'s default user agent string is ``"Python-urllib/2.6"`` (on Python 2.6). + All header keys are sent in camel case. An appropriate ``Content-Type`` header should be included if the *data* argument is present. If this header has not been provided and *data* @@ -541,7 +542,8 @@ request. name, and later calls will overwrite previous calls in case the *key* collides. Currently, this is no loss of HTTP functionality, since all headers which have meaning when used more than once have a (header-specific) way of gaining the - same functionality using only one header. + same functionality using only one header. Note that headers added using + this method are also added to redirected requests. .. method:: Request.add_unredirected_header(key, header) @@ -732,7 +734,7 @@ The following attribute and methods should only be used by classes derived from This method, if implemented, will be called by the parent :class:`OpenerDirector`. It should return a file-like object as described in - the return value of the :meth:`open` of :class:`OpenerDirector`, or ``None``. + the return value of the :meth:`~OpenerDirector.open` method of :class:`OpenerDirector`, or ``None``. It should raise :exc:`~urllib.error.URLError`, unless a truly exceptional thing happens (for example, :exc:`MemoryError` should not be mapped to :exc:`URLError`). diff --git a/Doc/library/uu.rst b/Doc/library/uu.rst index c341bc83..026ec415 100644 --- a/Doc/library/uu.rst +++ b/Doc/library/uu.rst @@ -10,7 +10,9 @@ **Source code:** :source:`Lib/uu.py` .. deprecated:: 3.11 - The :mod:`uu` module is deprecated (see :pep:`594` for details). + The :mod:`uu` module is deprecated + (see :pep:`PEP 594 <594#uu-and-the-uu-encoding>` for details). + :mod:`base64` is a modern alternative. -------------- diff --git a/Doc/library/xdrlib.rst b/Doc/library/xdrlib.rst index 060b2e2c..a3124a98 100644 --- a/Doc/library/xdrlib.rst +++ b/Doc/library/xdrlib.rst @@ -12,7 +12,8 @@ single: External Data Representation .. deprecated:: 3.11 - The :mod:`xdrlib` module is deprecated (see :pep:`594` for details). + The :mod:`xdrlib` module is deprecated + (see :pep:`PEP 594 <594#xdrlib>` for details). -------------- diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index f4bccf66..92248e75 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -363,13 +363,6 @@ These two approaches both output:: |--> Commander Clement -Additional resources -^^^^^^^^^^^^^^^^^^^^ - -See http://effbot.org/zone/element-index.htm for tutorials and links to other -docs. - - .. _elementtree-xpath: XPath support diff --git a/Doc/library/xml.sax.handler.rst b/Doc/library/xml.sax.handler.rst index ae0877ca..c7831ce3 100644 --- a/Doc/library/xml.sax.handler.rst +++ b/Doc/library/xml.sax.handler.rst @@ -141,7 +141,7 @@ for the feature and property names. .. data:: property_xml_string | value: ``"http://xml.org/sax/properties/xml-string"`` - | data type: String + | data type: Bytes | description: The literal string of characters that was the source for the current event. | access: read-only diff --git a/Doc/library/xmlrpc.client.rst b/Doc/library/xmlrpc.client.rst index 32403819..30c5a710 100644 --- a/Doc/library/xmlrpc.client.rst +++ b/Doc/library/xmlrpc.client.rst @@ -169,12 +169,6 @@ between conformable Python objects and XML on the wire. `XML-RPC Specification `_ The official specification. - `Unofficial XML-RPC Errata `_ - Fredrik Lundh's "unofficial errata, intended to clarify certain - details in the XML-RPC specification, as well as hint at - 'best practices' to use when designing your own XML-RPC - implementations." - .. _serverproxy-objects: ServerProxy Objects diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst index 3d1e8d8c..de508cad 100644 --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -289,7 +289,7 @@ ZipFile Objects compressed text files in :term:`universal newlines` mode. .. versionchanged:: 3.6 - :meth:`open` can now be used to write files into the archive with the + :meth:`ZipFile.open` can now be used to write files into the archive with the ``mode='w'`` option. .. versionchanged:: 3.6 diff --git a/Doc/make.bat b/Doc/make.bat index d621bd16..93de1d8f 100644 --- a/Doc/make.bat +++ b/Doc/make.bat @@ -13,7 +13,7 @@ if not defined SPHINXBUILD ( %PYTHON% -c "import sphinx" > nul 2> nul if errorlevel 1 ( echo Installing sphinx with %PYTHON% - %PYTHON% -m pip install sphinx==2.2.0 + %PYTHON% -m pip install -r requirements.txt if errorlevel 1 exit /B ) set SPHINXBUILD=%PYTHON% -c "import sphinx.cmd.build, sys; sys.exit(sphinx.cmd.build.main())" @@ -30,6 +30,7 @@ if not defined BLURB ( %PYTHON% -c "import blurb" > nul 2> nul if errorlevel 1 ( echo Installing blurb with %PYTHON% + rem Should have been installed with Sphinx earlier %PYTHON% -m pip install blurb if errorlevel 1 exit /B ) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 84320f41..033d65fd 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2854,7 +2854,8 @@ generators, coroutines do not directly support iteration. :exc:`StopIteration`, or other exception) is the same as when iterating over the :meth:`__await__` return value, described above. -.. method:: coroutine.throw(type[, value[, traceback]]) +.. method:: coroutine.throw(value) + coroutine.throw(type[, value[, traceback]]) Raises the specified exception in the coroutine. This method delegates to the :meth:`~generator.throw` method of the iterator that caused diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 4ffb6512..502c0225 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -557,14 +557,27 @@ is already executing raises a :exc:`ValueError` exception. could receive the value. -.. method:: generator.throw(type[, value[, traceback]]) +.. method:: generator.throw(value) + generator.throw(type[, value[, traceback]]) - Raises an exception of type ``type`` at the point where the generator was paused, + Raises an exception at the point where the generator was paused, and returns the next value yielded by the generator function. If the generator exits without yielding another value, a :exc:`StopIteration` exception is raised. If the generator function does not catch the passed-in exception, or raises a different exception, then that exception propagates to the caller. + In typical use, this is called with a single exception instance similar to the + way the :keyword:`raise` keyword is used. + + For backwards compatability, however, the second signature is + supported, following a convention from older versions of Python. + The *type* argument should be an exception class, and *value* + should be an exception instance. If the *value* is not provided, the + *type* constructor is called to get an instance. If *traceback* + is provided, it is set on the exception, otherwise any existing + :attr:`~BaseException.__traceback__` attribute stored in *value* may + be cleared. + .. index:: exception: GeneratorExit diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index 2c84a97a..2d9802b0 100644 --- a/Doc/reference/import.rst +++ b/Doc/reference/import.rst @@ -483,21 +483,19 @@ submodule. Let's say you have the following directory structure:: spam/ __init__.py foo.py - bar.py -and ``spam/__init__.py`` has the following lines in it:: +and ``spam/__init__.py`` has the following line in it:: from .foo import Foo - from .bar import Bar -then executing the following puts a name binding to ``foo`` and ``bar`` in the +then executing the following puts name bindings for ``foo`` and ``Foo`` in the ``spam`` module:: >>> import spam >>> spam.foo - >>> spam.bar - + >>> spam.Foo + Given Python's familiar name binding rules this might seem surprising, but it's actually a fundamental feature of the import system. The invariant diff --git a/Doc/reference/lexical_analysis.rst b/Doc/reference/lexical_analysis.rst index 77e0578f..b8f9ca21 100644 --- a/Doc/reference/lexical_analysis.rst +++ b/Doc/reference/lexical_analysis.rst @@ -101,12 +101,11 @@ addition, if the first bytes of the file are the UTF-8 byte-order mark (``b'\xef\xbb\xbf'``), the declared file encoding is UTF-8 (this is supported, among others, by Microsoft's :program:`notepad`). -If an encoding is declared, the encoding name must be recognized by Python. The +If an encoding is declared, the encoding name must be recognized by Python +(see :ref:`standard-encodings`). The encoding is used for all lexical analysis, including string literals, comments and identifiers. -.. XXX there should be a list of supported encodings. - .. _explicit-joining: @@ -448,9 +447,11 @@ see section :ref:`encodings`. In plain English: Both types of literals can be enclosed in matching single quotes (``'``) or double quotes (``"``). They can also be enclosed in matching groups of three single or double quotes (these are generally referred to as -*triple-quoted strings*). The backslash (``\``) character is used to escape -characters that otherwise have a special meaning, such as newline, backslash -itself, or the quote character. +*triple-quoted strings*). The backslash (``\``) character is used to give special +meaning to otherwise ordinary characters like ``n``, which means 'newline' when +escaped (``\n``). It can also be used to escape characters that otherwise have a +special meaning, such as newline, backslash itself, or the quote character. +See :ref:`escape sequences ` below for examples. .. index:: single: b'; bytes literal @@ -509,6 +510,8 @@ retained), except that three unescaped quotes in a row terminate the literal. ( single: \u; escape sequence single: \U; escape sequence +.. _escape-sequences: + Unless an ``'r'`` or ``'R'`` prefix is present, escape sequences in string and bytes literals are interpreted according to rules similar to those used by Standard C. The recognized escape sequences are: diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index 79f40113..2c2c2453 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -124,9 +124,7 @@ square brackets, is recursively defined as follows. * If the target list is a single target with no trailing comma, optionally in parentheses, the object is assigned to that target. -* Else: The object must be an iterable with the same number of - items as there are targets in the target list, and the items are assigned, - from left to right, to the corresponding targets. +* Else: * If the target list contains one target prefixed with an asterisk, called a "starred" target: The object must be an iterable with at least as many items @@ -797,9 +795,9 @@ The :keyword:`from` form uses a slightly more complex process: Examples:: import foo # foo imported and bound locally - import foo.bar.baz # foo.bar.baz imported, foo bound locally - import foo.bar.baz as fbb # foo.bar.baz imported and bound as fbb - from foo.bar import baz # foo.bar.baz imported and bound as baz + import foo.bar.baz # foo, foo.bar, and foo.bar.baz imported, foo bound locally + import foo.bar.baz as fbb # foo, foo.bar, and foo.bar.baz imported, foo.bar.baz bound as fbb + from foo.bar import baz # foo, foo.bar, and foo.bar.baz imported, foo.bar.baz bound as baz from foo import attr # foo imported and foo.attr bound as attr .. index:: single: * (asterisk); import statement diff --git a/Doc/requirements.txt b/Doc/requirements.txt index 1b75aed0..cf659a0f 100644 --- a/Doc/requirements.txt +++ b/Doc/requirements.txt @@ -8,6 +8,8 @@ sphinx==2.4.4 # version 2.4.4. It can be removed after bumping Sphinx version to at # least 3.5.4. docutils==0.17.1 +# Jinja version is pinned to a version compatible with Sphinx version 2.4.4. +jinja2==3.0.3 blurb diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py index 74de6ffa..4575300f 100644 --- a/Doc/tools/extensions/pyspecific.py +++ b/Doc/tools/extensions/pyspecific.py @@ -43,7 +43,8 @@ except ImportError: import suspicious -ISSUE_URI = 'https://bugs.python.org/issue%s' +ISSUE_URI = 'https://bugs.python.org/issue?@action=redirect&bpo=%s' +GH_ISSUE_URI = 'https://github.com/python/cpython/issues/%s' SOURCE_URI = 'https://github.com/python/cpython/tree/3.9/%s' # monkey-patch reST parser to disable alphabetic and roman enumerated lists @@ -58,11 +59,33 @@ Body.enum.converters['loweralpha'] = \ def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): issue = utils.unescape(text) + # sanity check: there are no bpo issues within these two values + if 47261 < int(issue) < 400000: + msg = inliner.reporter.error(f'The BPO ID {text!r} seems too high -- ' + 'use :gh:`...` for GitHub IDs', line=lineno) + prb = inliner.problematic(rawtext, rawtext, msg) + return [prb], [msg] text = 'bpo-' + issue refnode = nodes.reference(text, text, refuri=ISSUE_URI % issue) return [refnode], [] +# Support for marking up and linking to GitHub issues + +def gh_issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): + issue = utils.unescape(text) + # sanity check: all GitHub issues have ID >= 32426 + # even though some of them are also valid BPO IDs + if int(issue) < 32426: + msg = inliner.reporter.error(f'The GitHub ID {text!r} seems too low -- ' + 'use :issue:`...` for BPO IDs', line=lineno) + prb = inliner.problematic(rawtext, rawtext, msg) + return [prb], [msg] + text = 'gh-' + issue + refnode = nodes.reference(text, text, refuri=GH_ISSUE_URI % issue) + return [refnode], [] + + # Support for linking to Python source files easily def source_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): @@ -368,7 +391,8 @@ class DeprecatedRemoved(Directive): # Support for including Misc/NEWS -issue_re = re.compile('(?:[Ii]ssue #|bpo-)([0-9]+)') +issue_re = re.compile('(?:[Ii]ssue #|bpo-)([0-9]+)', re.I) +gh_issue_re = re.compile('(?:gh-issue-|gh-)([0-9]+)', re.I) whatsnew_re = re.compile(r"(?im)^what's new in (.*?)\??$") @@ -395,8 +419,9 @@ class MiscNews(Directive): text = 'The NEWS file is not available.' node = nodes.strong(text, text) return [node] - content = issue_re.sub(r'`bpo-\1 `__', - content) + content = issue_re.sub(r':issue:`\1`', content) + # Fallback handling for the GitHub issue + content = gh_issue_re.sub(r':gh:`\1`', content) content = whatsnew_re.sub(r'\1', content) # remove first 3 lines as they are the main heading lines = ['.. default-role:: obj', ''] + content.splitlines()[3:] @@ -576,6 +601,7 @@ def process_audit_events(app, doctree, fromdocname): def setup(app): app.add_role('issue', issue_role) + app.add_role('gh', gh_issue_role) app.add_role('source', source_role) app.add_directive('impl-detail', ImplementationDetail) app.add_directive('availability', Availability) diff --git a/Doc/tools/susp-ignored.csv b/Doc/tools/susp-ignored.csv index 67e44931..3eb3d795 100644 --- a/Doc/tools/susp-ignored.csv +++ b/Doc/tools/susp-ignored.csv @@ -370,4 +370,4 @@ whatsnew/changelog,,::,default::DeprecationWarning library/importlib.metadata,,:main,"EntryPoint(name='wheel', value='wheel.cli:main', group='console_scripts')" library/importlib.metadata,,`,loading the metadata for packages for the indicated ``context``. library/re,,`,"`" -library/typing,,`, # will always be an instance of whatever `cls` is +library/typing,,`, # will always be an instance of whatever ``cls`` is diff --git a/Doc/tutorial/inputoutput.rst b/Doc/tutorial/inputoutput.rst index 7f83c4d4..b5006365 100644 --- a/Doc/tutorial/inputoutput.rst +++ b/Doc/tutorial/inputoutput.rst @@ -279,11 +279,12 @@ Reading and Writing Files object: file :func:`open` returns a :term:`file object`, and is most commonly used with -two arguments: ``open(filename, mode)``. +two positional arguments and one keyword argument: +``open(filename, mode, encoding=None)`` :: - >>> f = open('workfile', 'w') + >>> f = open('workfile', 'w', encoding="utf-8") .. XXX str(f) is @@ -300,11 +301,14 @@ writing. The *mode* argument is optional; ``'r'`` will be assumed if it's omitted. Normally, files are opened in :dfn:`text mode`, that means, you read and write -strings from and to the file, which are encoded in a specific encoding. If -encoding is not specified, the default is platform dependent (see -:func:`open`). ``'b'`` appended to the mode opens the file in -:dfn:`binary mode`: now the data is read and written in the form of bytes -objects. This mode should be used for all files that don't contain text. +strings from and to the file, which are encoded in a specific *encoding*. +If *encoding* is not specified, the default is platform dependent +(see :func:`open`). +Because UTF-8 is the modern de-facto standard, ``encoding="utf-8"`` is +recommended unless you know that you need to use a different encoding. +Appending a ``'b'`` to the mode opens the file in :dfn:`binary mode`. +Binary mode data is read and written as :class:`bytes` objects. +You can not specify *encoding* when opening file in binary mode. In text mode, the default when reading is to convert platform-specific line endings (``\n`` on Unix, ``\r\n`` on Windows) to just ``\n``. When writing in @@ -320,7 +324,7 @@ after its suite finishes, even if an exception is raised at some point. Using :keyword:`!with` is also much shorter than writing equivalent :keyword:`try`\ -\ :keyword:`finally` blocks:: - >>> with open('workfile') as f: + >>> with open('workfile', encoding="utf-8") as f: ... read_data = f.read() >>> # We can check that the file has been automatically closed. @@ -490,11 +494,15 @@ simply serializes the object to a :term:`text file`. So if ``f`` is a json.dump(x, f) -To decode the object again, if ``f`` is a :term:`text file` object which has -been opened for reading:: +To decode the object again, if ``f`` is a :term:`binary file` or +:term:`text file` object which has been opened for reading:: x = json.load(f) +.. note:: + JSON files must be encoded in UTF-8. Use ``encoding="utf-8"`` when opening + JSON file as a :term:`text file` for both of reading and writing. + This simple serialization technique can handle lists and dictionaries, but serializing arbitrary class instances in JSON requires a bit of extra effort. The reference for the :mod:`json` module contains an explanation of this. diff --git a/Doc/tutorial/modules.rst b/Doc/tutorial/modules.rst index f6250291..c5cca917 100644 --- a/Doc/tutorial/modules.rst +++ b/Doc/tutorial/modules.rst @@ -183,7 +183,8 @@ The Module Search Path .. index:: triple: module; search; path When a module named :mod:`spam` is imported, the interpreter first searches for -a built-in module with that name. If not found, it then searches for a file +a built-in module with that name. These module names are listed in +:data:`sys.builtin_module_names`. If not found, it then searches for a file named :file:`spam.py` in a list of directories given by the variable :data:`sys.path`. :data:`sys.path` is initialized from these locations: @@ -504,7 +505,7 @@ code:: __all__ = ["echo", "surround", "reverse"] This would mean that ``from sound.effects import *`` would import the three -named submodules of the :mod:`sound` package. +named submodules of the :mod:`sound.effects` package. If ``__all__`` is not defined, the statement ``from sound.effects import *`` does *not* import all submodules from the package :mod:`sound.effects` into the diff --git a/Doc/tutorial/stdlib.rst b/Doc/tutorial/stdlib.rst index ab64ca6d..32dda97c 100644 --- a/Doc/tutorial/stdlib.rst +++ b/Doc/tutorial/stdlib.rst @@ -78,8 +78,9 @@ and an optional number of lines to be displayed:: import argparse - parser = argparse.ArgumentParser(prog = 'top', - description = 'Show top lines from each file') + parser = argparse.ArgumentParser( + prog='top', + description='Show top lines from each file') parser.add_argument('filenames', nargs='+') parser.add_argument('-l', '--lines', type=int, default=10) args = parser.parse_args() @@ -326,7 +327,7 @@ Python has a "batteries included" philosophy. This is best seen through the sophisticated and robust capabilities of its larger packages. For example: * The :mod:`xmlrpc.client` and :mod:`xmlrpc.server` modules make implementing - remote procedure calls into an almost trivial task. Despite the modules + remote procedure calls into an almost trivial task. Despite the modules' names, no direct knowledge or handling of XML is needed. * The :mod:`email` package is a library for managing email messages, including diff --git a/Doc/using/mac.rst b/Doc/using/mac.rst index 2f132a96..f7db0384 100644 --- a/Doc/using/mac.rst +++ b/Doc/using/mac.rst @@ -160,7 +160,7 @@ Distributing Python Applications on the Mac The standard tool for deploying standalone Python applications on the Mac is :program:`py2app`. More information on installing and using py2app can be found -at http://undefined.org/python/#py2app. +at https://pypi.org/project/py2app/. Other Resources diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst index be21b55f..abb74637 100644 --- a/Doc/using/windows.rst +++ b/Doc/using/windows.rst @@ -374,7 +374,9 @@ may be changed from ``.``, and the package will be installed into a subdirectory. By default, the subdirectory is named the same as the package, and without the ``-ExcludeVersion`` option this name will include the specific version installed. Inside the subdirectory is a ``tools`` directory that -contains the Python installation:: +contains the Python installation: + +.. code-block:: doscon # Without -ExcludeVersion > .\python.3.5.2\tools\python.exe -V @@ -421,7 +423,7 @@ dependants, such as Idle), pip and the Python documentation are not included. .. note:: The embedded distribution does not include the `Microsoft C Runtime - `_ and it is + `_ and it is the responsibility of the application installer to provide this. The runtime may have already been installed on a user's system previously or automatically via Windows Update, and can be detected by finding @@ -555,27 +557,22 @@ System variables, you need non-restricted access to your machine Windows will concatenate User variables *after* System variables, which may cause unexpected results when modifying :envvar:`PATH`. - The :envvar:`PYTHONPATH` variable is used by all versions of Python 2 and - Python 3, so you should not permanently configure this variable unless it - only includes code that is compatible with all of your installed Python + The :envvar:`PYTHONPATH` variable is used by all versions of Python, + so you should not permanently configure it unless the listed paths + only include code that is compatible with all of your installed Python versions. .. seealso:: - https://www.microsoft.com/en-us/wdsi/help/folder-variables - Environment variables in Windows NT + https://docs.microsoft.com/en-us/windows/win32/procthread/environment-variables + Overview of environment variables on Windows - https://technet.microsoft.com/en-us/library/cc754250.aspx - The SET command, for temporarily modifying environment variables + https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1 + The ``set`` command, for temporarily modifying environment variables - https://technet.microsoft.com/en-us/library/cc755104.aspx - The SETX command, for permanently modifying environment variables + https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx + The ``setx`` command, for permanently modifying environment variables - https://support.microsoft.com/en-us/help/310519/how-to-manage-environment-variables-in-windows-xp - How To Manage Environment Variables in Windows XP - - https://www.chem.gla.ac.uk/~louis/software/faq/q1.html - Setting Environment variables, Louis J. Farrugia .. _windows-path-mod: @@ -679,9 +676,7 @@ From the command-line System-wide installations of Python 3.3 and later will put the launcher on your :envvar:`PATH`. The launcher is compatible with all available versions of Python, so it does not matter which version is installed. To check that the -launcher is available, execute the following command in Command Prompt: - -:: +launcher is available, execute the following command in Command Prompt:: py @@ -689,26 +684,20 @@ You should find that the latest version of Python you have installed is started - it can be exited as normal, and any additional command-line arguments specified will be sent directly to Python. -If you have multiple versions of Python installed (e.g., 2.7 and |version|) you -will have noticed that Python |version| was started - to launch Python 2.7, try -the command: - -:: +If you have multiple versions of Python installed (e.g., 3.7 and |version|) you +will have noticed that Python |version| was started - to launch Python 3.7, try +the command:: - py -2.7 + py -3.7 -If you want the latest version of Python 2.x you have installed, try the -command: - -:: +If you want the latest version of Python 2 you have installed, try the +command:: py -2 -You should find the latest version of Python 2.x starts. - -If you see the following error, you do not have the launcher installed: +You should find the latest version of Python 3.x starts. -:: +If you see the following error, you do not have the launcher installed:: 'py' is not recognized as an internal or external command, operable program or batch file. @@ -716,6 +705,12 @@ If you see the following error, you do not have the launcher installed: Per-user installations of Python do not add the launcher to :envvar:`PATH` unless the option was selected on installation. +The command:: + + py --list + +displays the currently installed version(s) of Python. + Virtual environments ^^^^^^^^^^^^^^^^^^^^ @@ -740,9 +735,7 @@ following contents import sys sys.stdout.write("hello from Python %s\n" % (sys.version,)) -From the directory in which hello.py lives, execute the command: - -:: +From the directory in which hello.py lives, execute the command:: py hello.py @@ -755,9 +748,9 @@ is printed. Now try changing the first line to be: Re-executing the command should now print the latest Python 3.x information. As with the above command-line examples, you can specify a more explicit -version qualifier. Assuming you have Python 2.6 installed, try changing the -first line to ``#! python2.6`` and you should find the 2.6 version -information printed. +version qualifier. Assuming you have Python 3.7 installed, try changing +the first line to ``#! python3.7`` and you should find the |version| +version information printed. Note that unlike interactive use, a bare "python" will use the latest version of Python 2.x that you have installed. This is for backward @@ -810,8 +803,8 @@ shebang lines starting with ``/usr``. Any of the above virtual commands can be suffixed with an explicit version (either just the major version, or the major and minor version). Furthermore the 32-bit version can be requested by adding "-32" after the -minor version. I.e. ``/usr/bin/python2.7-32`` will request usage of the -32-bit python 2.7. +minor version. I.e. ``/usr/bin/python3.7-32`` will request usage of the +32-bit python 3.7. .. versionadded:: 3.7 @@ -897,19 +890,19 @@ Examples: ``python2`` will use the latest Python 2.x version installed and the command ``python3`` will use the latest Python 3.x installed. -* The commands ``python3.1`` and ``python2.7`` will not consult any +* The command ``python3.7`` will not consult any options at all as the versions are fully specified. * If ``PY_PYTHON=3``, the commands ``python`` and ``python3`` will both use the latest installed Python 3 version. -* If ``PY_PYTHON=3.1-32``, the command ``python`` will use the 32-bit - implementation of 3.1 whereas the command ``python3`` will use the latest +* If ``PY_PYTHON=3.7-32``, the command ``python`` will use the 32-bit + implementation of 3.7 whereas the command ``python3`` will use the latest installed Python (PY_PYTHON was not considered at all as a major version was specified.) -* If ``PY_PYTHON=3`` and ``PY_PYTHON3=3.1``, the commands - ``python`` and ``python3`` will both use specifically 3.1 +* If ``PY_PYTHON=3`` and ``PY_PYTHON3=3.7``, the commands + ``python`` and ``python3`` will both use specifically 3.7 In addition to environment variables, the same settings can be configured in the .INI file used by the launcher. The section in the INI file is @@ -920,21 +913,21 @@ an environment variable will override things specified in the INI file. For example: -* Setting ``PY_PYTHON=3.1`` is equivalent to the INI file containing: +* Setting ``PY_PYTHON=3.7`` is equivalent to the INI file containing: .. code-block:: ini [defaults] - python=3.1 + python=3.7 -* Setting ``PY_PYTHON=3`` and ``PY_PYTHON3=3.1`` is equivalent to the INI file +* Setting ``PY_PYTHON=3`` and ``PY_PYTHON3=3.7`` is equivalent to the INI file containing: .. code-block:: ini [defaults] python=3 - python3=3.1 + python3=3.7 Diagnostics ----------- @@ -1088,13 +1081,14 @@ is a collection of modules for advanced Windows-specific support. This includes utilities for: * `Component Object Model - `_ + `_ (COM) * Win32 API calls * Registry * Event log -* `Microsoft Foundation Classes `_ (MFC) - user interfaces +* `Microsoft Foundation Classes + `_ + (MFC) user interfaces `PythonWin `_ is a sample MFC application @@ -1105,7 +1099,7 @@ shipped with PyWin32. It is an embeddable IDE with a built-in debugger. `Win32 How Do I...? `_ by Tim Golden - `Python and COM `_ + `Python and COM `_ by David and Paul Boddie @@ -1119,18 +1113,6 @@ you can distribute your application without requiring your users to install Python. -WConio ------- - -Since Python's advanced terminal handling layer, :mod:`curses`, is restricted to -Unix-like systems, there is a library exclusive to Windows as well: Windows -Console I/O for Python. - -`WConio `_ is a wrapper for -Turbo-C's :file:`CONIO.H`, used to create text user interfaces. - - - Compiling Python on Windows =========================== @@ -1140,21 +1122,13 @@ latest release's source or just grab a fresh `checkout `_. The source tree contains a build solution and project files for Microsoft -Visual Studio 2015, which is the compiler used to build the official Python +Visual Studio, which is the compiler used to build the official Python releases. These files are in the :file:`PCbuild` directory. Check :file:`PCbuild/readme.txt` for general information on the build process. - For extension modules, consult :ref:`building-on-windows`. -.. seealso:: - - `Python + Windows + distutils + SWIG + gcc MinGW `_ - or "Creating Python extensions in C/C++ with SWIG and compiling them with - MinGW gcc under Windows" or "Installing Python extension with distutils - and without Microsoft Visual C++" by Sébastien Sauvage, 2003 - Other Platforms =============== @@ -1163,12 +1137,12 @@ 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 still supported. -* The `Cygwin `_ installer offers to install the Python - interpreter as well (cf. `Cygwin package source - `_, `Maintainer releases - `_) +* `Windows CE `_ is + `no longer supported `__ + since Python 3 (if it ever was). +* The `Cygwin `_ installer offers to install the + `Python interpreter `__ + as well See `Python for Windows `_ for detailed information about platforms with pre-compiled installers. diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst index 4e85abae..5816380e 100644 --- a/Doc/whatsnew/2.5.rst +++ b/Doc/whatsnew/2.5.rst @@ -1767,7 +1767,7 @@ included. The rest of this section will provide a brief overview of using ElementTree. Full documentation for ElementTree is available at -http://effbot.org/zone/element-index.htm. +https://web.archive.org/web/20201124024954/http://effbot.org/zone/element-index.htm. ElementTree represents an XML document as a tree of element nodes. The text content of the document is stored as the :attr:`text` and :attr:`tail` @@ -1865,7 +1865,7 @@ read the package's official documentation for more details. .. seealso:: - http://effbot.org/zone/element-index.htm + https://web.archive.org/web/20201124024954/http://effbot.org/zone/element-index.htm Official documentation for ElementTree. .. ====================================================================== diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst index abb65222..6d704586 100644 --- a/Doc/whatsnew/2.7.rst +++ b/Doc/whatsnew/2.7.rst @@ -2089,7 +2089,7 @@ version 1.3. Some of the new features are: Fredrik Lundh develops ElementTree and produced the 1.3 version; you can read his article describing 1.3 at -http://effbot.org/zone/elementtree-13-intro.htm. +https://web.archive.org/web/20200703234532/http://effbot.org/zone/elementtree-13-intro.htm. Florent Xicluna updated the version included with Python, after discussions on python-dev and in :issue:`6472`.) diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst index 06bee996..828d7ca1 100644 --- a/Doc/whatsnew/3.2.rst +++ b/Doc/whatsnew/3.2.rst @@ -744,7 +744,8 @@ Two methods have been deprecated: * :meth:`xml.etree.ElementTree.getiterator` use ``Element.iter`` instead. For details of the update, see `Introducing ElementTree -`_ on Fredrik Lundh's website. +`_ +on Fredrik Lundh's website. (Contributed by Florent Xicluna and Fredrik Lundh, :issue:`6472`.) diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst index 1b3bb152..92bdb455 100644 --- a/Doc/whatsnew/3.8.rst +++ b/Doc/whatsnew/3.8.rst @@ -1489,7 +1489,7 @@ Optimizations first introduced in Python 3.4. It offers better performance and smaller size compared to Protocol 3 available since Python 3.0. -* Removed one ``Py_ssize_t`` member from ``PyGC_Head``. All GC tracked +* Removed one :c:type:`Py_ssize_t` member from ``PyGC_Head``. All GC tracked objects (e.g. tuple, list, dict) size is reduced 4 or 8 bytes. (Contributed by Inada Naoki in :issue:`33597`.) diff --git a/Include/patchlevel.h b/Include/patchlevel.h index a4418b0a..cf352947 100644 --- a/Include/patchlevel.h +++ b/Include/patchlevel.h @@ -18,12 +18,12 @@ /*--start constants--*/ #define PY_MAJOR_VERSION 3 #define PY_MINOR_VERSION 9 -#define PY_MICRO_VERSION 12 +#define PY_MICRO_VERSION 13 #define PY_RELEASE_LEVEL PY_RELEASE_LEVEL_FINAL #define PY_RELEASE_SERIAL 0 /* Version as a string */ -#define PY_VERSION "3.9.12" +#define PY_VERSION "3.9.13" /*--end constants--*/ /* Version as a single 4-byte hex number, e.g. 0x010502B2 == 1.5.2b2. diff --git a/Lib/_markupbase.py b/Lib/_markupbase.py index 2af5f1c2..7091eb63 100644 --- a/Lib/_markupbase.py +++ b/Lib/_markupbase.py @@ -157,6 +157,7 @@ class ParserBase: match= _msmarkedsectionclose.search(rawdata, i+3) else: self.error('unknown status keyword %r in marked section' % rawdata[i+3:j]) + match = None if not match: return -1 if report: diff --git a/Lib/argparse.py b/Lib/argparse.py index c46bb302..b9c22051 100644 --- a/Lib/argparse.py +++ b/Lib/argparse.py @@ -848,6 +848,7 @@ class Action(_AttributeHolder): 'default', 'type', 'choices', + 'required', 'help', 'metavar', ] diff --git a/Lib/asyncio/base_events.py b/Lib/asyncio/base_events.py index 7a14e5e1..4356bfae 100644 --- a/Lib/asyncio/base_events.py +++ b/Lib/asyncio/base_events.py @@ -885,7 +885,7 @@ class BaseEventLoop(events.AbstractEventLoop): # non-mmap files even if sendfile is supported by OS raise exceptions.SendfileNotAvailableError( f"syscall sendfile is not available for socket {sock!r} " - "and file {file!r} combination") + f"and file {file!r} combination") async def _sock_sendfile_fallback(self, sock, file, offset, count): if offset: diff --git a/Lib/asyncio/selector_events.py b/Lib/asyncio/selector_events.py index 71080b8a..572d4a8c 100644 --- a/Lib/asyncio/selector_events.py +++ b/Lib/asyncio/selector_events.py @@ -487,7 +487,8 @@ class BaseSelectorEventLoop(base_events.BaseEventLoop): if self._debug and sock.gettimeout() != 0: raise ValueError("the socket must be non-blocking") - if not hasattr(socket, 'AF_UNIX') or sock.family != socket.AF_UNIX: + if sock.family == socket.AF_INET or ( + base_events._HAS_IPv6 and sock.family == socket.AF_INET6): resolved = await self._ensure_resolved( address, family=sock.family, type=sock.type, proto=sock.proto, loop=self, diff --git a/Lib/concurrent/futures/_base.py b/Lib/concurrent/futures/_base.py index 5c00f2ed..cf119ac6 100644 --- a/Lib/concurrent/futures/_base.py +++ b/Lib/concurrent/futures/_base.py @@ -381,7 +381,7 @@ class Future(object): return self._state == RUNNING def done(self): - """Return True of the future was cancelled or finished executing.""" + """Return True if the future was cancelled or finished executing.""" with self._condition: return self._state in [CANCELLED, CANCELLED_AND_NOTIFIED, FINISHED] diff --git a/Lib/concurrent/futures/process.py b/Lib/concurrent/futures/process.py index a29e5247..f223b86d 100644 --- a/Lib/concurrent/futures/process.py +++ b/Lib/concurrent/futures/process.py @@ -126,6 +126,9 @@ class _ExceptionWithTraceback: tb = traceback.format_exception(type(exc), exc, tb) tb = ''.join(tb) self.exc = exc + # Traceback object needs to be garbage-collected as its frames + # contain references to all the objects in the exception scope + self.exc.__traceback__ = None self.tb = '\n"""\n%s"""' % tb def __reduce__(self): return _rebuild_exc, (self.exc, self.tb) @@ -604,6 +607,10 @@ class ProcessPoolExecutor(_base.Executor): mp_context = mp.get_context() self._mp_context = mp_context + # https://github.com/python/cpython/issues/90622 + self._safe_to_dynamically_spawn_children = ( + self._mp_context.get_start_method(allow_none=False) != "fork") + if initializer is not None and not callable(initializer): raise TypeError("initializer must be a callable") self._initializer = initializer @@ -654,6 +661,8 @@ class ProcessPoolExecutor(_base.Executor): def _start_executor_manager_thread(self): if self._executor_manager_thread is None: # Start the processes so that their sentinels are known. + if not self._safe_to_dynamically_spawn_children: # ie, using fork. + self._launch_processes() self._executor_manager_thread = _ExecutorManagerThread(self) self._executor_manager_thread.start() _threads_wakeups[self._executor_manager_thread] = \ @@ -666,14 +675,31 @@ class ProcessPoolExecutor(_base.Executor): process_count = len(self._processes) if process_count < self._max_workers: - p = self._mp_context.Process( - target=_process_worker, - args=(self._call_queue, - self._result_queue, - self._initializer, - self._initargs)) - p.start() - self._processes[p.pid] = p + # Assertion disabled as this codepath is also used to replace a + # worker that unexpectedly dies, even when using the 'fork' start + # method. That means there is still a potential deadlock bug. If a + # 'fork' mp_context worker dies, we'll be forking a new one when + # we know a thread is running (self._executor_manager_thread). + #assert self._safe_to_dynamically_spawn_children or not self._executor_manager_thread, 'https://github.com/python/cpython/issues/90622' + self._spawn_process() + + def _launch_processes(self): + # https://github.com/python/cpython/issues/90622 + assert not self._executor_manager_thread, ( + 'Processes cannot be fork()ed after the thread has started, ' + 'deadlock in the child processes could result.') + for _ in range(len(self._processes), self._max_workers): + self._spawn_process() + + def _spawn_process(self): + p = self._mp_context.Process( + target=_process_worker, + args=(self._call_queue, + self._result_queue, + self._initializer, + self._initargs)) + p.start() + self._processes[p.pid] = p def submit(self, fn, /, *args, **kwargs): with self._shutdown_lock: @@ -694,7 +720,8 @@ class ProcessPoolExecutor(_base.Executor): # Wake up queue management thread self._executor_manager_thread_wakeup.wakeup() - self._adjust_process_count() + if self._safe_to_dynamically_spawn_children: + self._adjust_process_count() self._start_executor_manager_thread() return f submit.__doc__ = _base.Executor.submit.__doc__ diff --git a/Lib/datetime.py b/Lib/datetime.py index 23d2bf09..51c70499 100644 --- a/Lib/datetime.py +++ b/Lib/datetime.py @@ -1683,7 +1683,7 @@ class datetime(date): y, m, d, hh, mm, ss, weekday, jday, dst = converter(t) ss = min(ss, 59) # clamp out leap seconds if the platform has them result = cls(y, m, d, hh, mm, ss, us, tz) - if tz is None: + if tz is None and not utc: # As of version 2015f max fold in IANA database is # 23 hours at 1969-09-30 13:00:00 in Kwajalein. # Let's probe 24 hours in the past to detect a transition: @@ -1704,7 +1704,7 @@ class datetime(date): probe2 = cls(y, m, d, hh, mm, ss, us, tz) if probe2 == result: result._fold = 1 - else: + elif tz is not None: result = tz.fromutc(result) return result diff --git a/Lib/email/_encoded_words.py b/Lib/email/_encoded_words.py index 295ae7eb..6795a606 100644 --- a/Lib/email/_encoded_words.py +++ b/Lib/email/_encoded_words.py @@ -179,15 +179,15 @@ def decode(ew): # Turn the CTE decoded bytes into unicode. try: string = bstring.decode(charset) - except UnicodeError: + except UnicodeDecodeError: defects.append(errors.UndecodableBytesDefect("Encoded word " - "contains bytes not decodable using {} charset".format(charset))) + f"contains bytes not decodable using {charset!r} charset")) string = bstring.decode(charset, 'surrogateescape') - except LookupError: + except (LookupError, UnicodeEncodeError): string = bstring.decode('ascii', 'surrogateescape') if charset.lower() != 'unknown-8bit': - defects.append(errors.CharsetError("Unknown charset {} " - "in encoded word; decoded as unknown bytes".format(charset))) + defects.append(errors.CharsetError(f"Unknown charset {charset!r} " + f"in encoded word; decoded as unknown bytes")) return string, charset, lang, defects diff --git a/Lib/email/_header_value_parser.py b/Lib/email/_header_value_parser.py index 51d355fb..8a8fb8bc 100644 --- a/Lib/email/_header_value_parser.py +++ b/Lib/email/_header_value_parser.py @@ -781,7 +781,7 @@ class MimeParameters(TokenList): else: try: value = value.decode(charset, 'surrogateescape') - except LookupError: + except (LookupError, UnicodeEncodeError): # XXX: there should really be a custom defect for # unknown character set to make it easy to find, # because otherwise unknown charset is a silent diff --git a/Lib/email/charset.py b/Lib/email/charset.py index d3d759ad..791b6584 100644 --- a/Lib/email/charset.py +++ b/Lib/email/charset.py @@ -112,8 +112,8 @@ def add_charset(charset, header_enc=None, body_enc=None, output_charset=None): charset is the input character set, and must be the canonical name of a character set. - Optional header_enc and body_enc is either Charset.QP for - quoted-printable, Charset.BASE64 for base64 encoding, Charset.SHORTEST for + Optional header_enc and body_enc is either charset.QP for + quoted-printable, charset.BASE64 for base64 encoding, charset.SHORTEST for the shortest of qp or base64 encoding, or None for no encoding. SHORTEST is only valid for header_enc. It describes how message headers and message bodies in the input charset are to be encoded. Default is no @@ -185,13 +185,13 @@ class Charset: header_encoding: If the character set must be encoded before it can be used in an email header, this attribute will be set to - Charset.QP (for quoted-printable), Charset.BASE64 (for - base64 encoding), or Charset.SHORTEST for the shortest of + charset.QP (for quoted-printable), charset.BASE64 (for + base64 encoding), or charset.SHORTEST for the shortest of QP or BASE64 encoding. Otherwise, it will be None. body_encoding: Same as header_encoding, but describes the encoding for the mail message's body, which indeed may be different than the - header encoding. Charset.SHORTEST is not allowed for + header encoding. charset.SHORTEST is not allowed for body_encoding. output_charset: Some character sets must be converted before they can be diff --git a/Lib/html/entities.py b/Lib/html/entities.py index 91ea5da2..dc508631 100644 --- a/Lib/html/entities.py +++ b/Lib/html/entities.py @@ -4,6 +4,7 @@ __all__ = ['html5', 'name2codepoint', 'codepoint2name', 'entitydefs'] # maps the HTML entity name to the Unicode code point +# from https://html.spec.whatwg.org/multipage/named-characters.html name2codepoint = { 'AElig': 0x00c6, # latin capital letter AE = latin capital ligature AE, U+00C6 ISOlat1 'Aacute': 0x00c1, # latin capital letter A with acute, U+00C1 ISOlat1 diff --git a/Lib/ipaddress.py b/Lib/ipaddress.py index 6cb92ed5..25f373a0 100644 --- a/Lib/ipaddress.py +++ b/Lib/ipaddress.py @@ -50,8 +50,7 @@ def ip_address(address): except (AddressValueError, NetmaskValueError): pass - raise ValueError('%r does not appear to be an IPv4 or IPv6 address' % - address) + raise ValueError(f'{address!r} does not appear to be an IPv4 or IPv6 address') def ip_network(address, strict=True): @@ -80,8 +79,7 @@ def ip_network(address, strict=True): except (AddressValueError, NetmaskValueError): pass - raise ValueError('%r does not appear to be an IPv4 or IPv6 network' % - address) + raise ValueError(f'{address!r} does not appear to be an IPv4 or IPv6 network') def ip_interface(address): @@ -115,8 +113,7 @@ def ip_interface(address): except (AddressValueError, NetmaskValueError): pass - raise ValueError('%r does not appear to be an IPv4 or IPv6 interface' % - address) + raise ValueError(f'{address!r} does not appear to be an IPv4 or IPv6 interface') def v4_int_to_packed(address): @@ -159,7 +156,7 @@ def _split_optional_netmask(address): """Helper to split the netmask and raise AddressValueError if needed""" addr = str(address).split('/') if len(addr) > 2: - raise AddressValueError("Only one '/' permitted in %r" % address) + raise AddressValueError(f"Only one '/' permitted in {address!r}") return addr @@ -1303,7 +1300,7 @@ class IPv4Address(_BaseV4, _BaseAddress): # which converts into a formatted IP string. addr_str = str(address) if '/' in addr_str: - raise AddressValueError("Unexpected '/' in %r" % address) + raise AddressValueError(f"Unexpected '/' in {address!r}") self._ip = self._ip_int_from_string(addr_str) @property @@ -1912,7 +1909,7 @@ class IPv6Address(_BaseV6, _BaseAddress): # which converts into a formatted IP string. addr_str = str(address) if '/' in addr_str: - raise AddressValueError("Unexpected '/' in %r" % address) + raise AddressValueError(f"Unexpected '/' in {address!r}") addr_str, self._scope_id = self._split_scope_id(addr_str) self._ip = self._ip_int_from_string(addr_str) diff --git a/Lib/multiprocessing/managers.py b/Lib/multiprocessing/managers.py index dfa566c6..1f929561 100644 --- a/Lib/multiprocessing/managers.py +++ b/Lib/multiprocessing/managers.py @@ -669,7 +669,7 @@ class BaseManager(object): if hasattr(process, 'terminate'): util.info('trying to `terminate()` manager process') process.terminate() - process.join(timeout=0.1) + process.join(timeout=1.0) if process.is_alive(): util.info('manager still alive after terminate') diff --git a/Lib/multiprocessing/queues.py b/Lib/multiprocessing/queues.py index a2901814..f37f114a 100644 --- a/Lib/multiprocessing/queues.py +++ b/Lib/multiprocessing/queues.py @@ -139,13 +139,10 @@ class Queue(object): def close(self): self._closed = True - try: - self._reader.close() - finally: - close = self._close - if close: - self._close = None - close() + close = self._close + if close: + self._close = None + close() def join_thread(self): debug('Queue.join_thread()') @@ -169,8 +166,9 @@ class Queue(object): self._thread = threading.Thread( target=Queue._feed, args=(self._buffer, self._notempty, self._send_bytes, - self._wlock, self._writer.close, self._ignore_epipe, - self._on_queue_feeder_error, self._sem), + self._wlock, self._reader.close, self._writer.close, + self._ignore_epipe, self._on_queue_feeder_error, + self._sem), name='QueueFeederThread' ) self._thread.daemon = True @@ -211,8 +209,8 @@ class Queue(object): notempty.notify() @staticmethod - def _feed(buffer, notempty, send_bytes, writelock, close, ignore_epipe, - onerror, queue_sem): + def _feed(buffer, notempty, send_bytes, writelock, reader_close, + writer_close, ignore_epipe, onerror, queue_sem): debug('starting thread to feed data to pipe') nacquire = notempty.acquire nrelease = notempty.release @@ -238,7 +236,8 @@ class Queue(object): obj = bpopleft() if obj is sentinel: debug('feeder thread got sentinel -- exiting') - close() + reader_close() + writer_close() return # serialize the data before acquiring the lock diff --git a/Lib/multiprocessing/util.py b/Lib/multiprocessing/util.py index 21f2a7eb..697b35a0 100644 --- a/Lib/multiprocessing/util.py +++ b/Lib/multiprocessing/util.py @@ -120,7 +120,7 @@ def is_abstract_socket_namespace(address): return address[0] == 0 elif isinstance(address, str): return address[0] == "\0" - raise TypeError('address type of {address!r} unrecognized') + raise TypeError(f'address type of {address!r} unrecognized') abstract_sockets_supported = _platform_supports_abstract_sockets() diff --git a/Lib/pydoc_data/topics.py b/Lib/pydoc_data/topics.py index 2546eb93..318e8566 100644 --- a/Lib/pydoc_data/topics.py +++ b/Lib/pydoc_data/topics.py @@ -1,5 +1,5 @@ # -*- coding: utf-8 -*- -# Autogenerated by Sphinx on Wed Mar 23 22:08:02 2022 +# Autogenerated by Sphinx on Tue May 17 12:57:36 2022 topics = {'assert': 'The "assert" statement\n' '**********************\n' '\n' @@ -93,11 +93,7 @@ topics = {'assert': 'The "assert" statement\n' ' optionally in parentheses, the object is assigned to that ' 'target.\n' '\n' - '* Else: The object must be an iterable with the same number of ' - 'items\n' - ' as there are targets in the target list, and the items are ' - 'assigned,\n' - ' from left to right, to the corresponding targets.\n' + '* Else:\n' '\n' ' * If the target list contains one target prefixed with an ' 'asterisk,\n' @@ -3980,7 +3976,10 @@ topics = {'assert': 'The "assert" statement\n' 'is\n' 'applied to separating the commands; the input is split at the ' 'first\n' - '";;" pair, even if it is in the middle of a quoted string.\n' + '";;" pair, even if it is in the middle of a quoted string. A\n' + 'workaround for strings with double semicolons is to use ' + 'implicit\n' + 'string concatenation "\';\'\';\'" or "";"";"".\n' '\n' 'If a file ".pdbrc" exists in the user’s home directory or in ' 'the\n' @@ -6402,12 +6401,12 @@ topics = {'assert': 'The "assert" statement\n' 'Examples:\n' '\n' ' import foo # foo imported and bound locally\n' - ' import foo.bar.baz # foo.bar.baz imported, foo bound ' - 'locally\n' - ' import foo.bar.baz as fbb # foo.bar.baz imported and bound as ' - 'fbb\n' - ' from foo.bar import baz # foo.bar.baz imported and bound as ' - 'baz\n' + ' import foo.bar.baz # foo, foo.bar, and foo.bar.baz ' + 'imported, foo bound locally\n' + ' import foo.bar.baz as fbb # foo, foo.bar, and foo.bar.baz ' + 'imported, foo.bar.baz bound as fbb\n' + ' from foo.bar import baz # foo, foo.bar, and foo.bar.baz ' + 'imported, foo.bar.baz bound as baz\n' ' from foo import attr # foo imported and foo.attr bound as ' 'attr\n' '\n' @@ -11091,9 +11090,13 @@ topics = {'assert': 'The "assert" statement\n' ' >>> "they\'re bill\'s friends from the UK".title()\n' ' "They\'Re Bill\'S Friends From The Uk"\n' '\n' - ' A workaround for apostrophes can be constructed using ' - 'regular\n' - ' expressions:\n' + ' The "string.capwords()" function does not have this ' + 'problem, as it\n' + ' splits words on spaces only.\n' + '\n' + ' Alternatively, a workaround for apostrophes can be ' + 'constructed\n' + ' using regular expressions:\n' '\n' ' >>> import re\n' ' >>> def titlecase(s):\n' @@ -11215,12 +11218,15 @@ topics = {'assert': 'The "assert" statement\n' 'single quotes ("\'") or double quotes ("""). They can also be ' 'enclosed\n' 'in matching groups of three single or double quotes (these are\n' - 'generally referred to as *triple-quoted strings*). The ' - 'backslash\n' - '("\\") character is used to escape characters that otherwise have ' - 'a\n' - 'special meaning, such as newline, backslash itself, or the quote\n' + 'generally referred to as *triple-quoted strings*). The backslash ' + '("\\")\n' + 'character is used to give special meaning to otherwise ordinary\n' + 'characters like "n", which means ‘newline’ when escaped ("\\n"). ' + 'It can\n' + 'also be used to escape characters that otherwise have a special\n' + 'meaning, such as newline, backslash itself, or the quote ' 'character.\n' + 'See escape sequences below for examples.\n' '\n' 'Bytes literals are always prefixed with "\'b\'" or "\'B\'"; they ' 'produce\n' @@ -12788,14 +12794,6 @@ topics = {'assert': 'The "assert" statement\n' 'unwise to use\n' 'them as dictionary keys.)\n' '\n' - 'Dictionaries can be created by placing a comma-separated ' - 'list of "key:\n' - 'value" pairs within braces, for example: "{\'jack\': 4098, ' - "'sjoerd':\n" - '4127}" or "{4098: \'jack\', 4127: \'sjoerd\'}", or by the ' - '"dict"\n' - 'constructor.\n' - '\n' 'class dict(**kwargs)\n' 'class dict(mapping, **kwargs)\n' 'class dict(iterable, **kwargs)\n' diff --git a/Lib/queue.py b/Lib/queue.py index 10dbcbc1..55f50088 100644 --- a/Lib/queue.py +++ b/Lib/queue.py @@ -298,7 +298,7 @@ class _PySimpleQueue: def put_nowait(self, item): '''Put an item into the queue without blocking. - This is exactly equivalent to `put(item)` and is only provided + This is exactly equivalent to `put(item, block=False)` and is only provided for compatibility with the Queue class. ''' return self.put(item, block=False) diff --git a/Lib/runpy.py b/Lib/runpy.py index 7e1e1ac5..c602bbe3 100644 --- a/Lib/runpy.py +++ b/Lib/runpy.py @@ -199,9 +199,24 @@ def _run_module_as_main(mod_name, alter_argv=True): def run_module(mod_name, init_globals=None, run_name=None, alter_sys=False): - """Execute a module's code without importing it + """Execute a module's code without importing it. - Returns the resulting top level namespace dictionary + mod_name -- an absolute module name or package name. + + Optional arguments: + init_globals -- dictionary used to pre-populate the module’s + globals dictionary before the code is executed. + + run_name -- if not None, this will be used for setting __name__; + otherwise, __name__ will be set to mod_name + '__main__' if the + named module is a package and to just mod_name otherwise. + + alter_sys -- if True, sys.argv[0] is updated with the value of + __file__ and sys.modules[__name__] is updated with a temporary + module object for the module being executed. Both are + restored to their original values before the function returns. + + Returns the resulting module globals dictionary. """ mod_name, mod_spec, code = _get_module_details(mod_name) if run_name is None: @@ -243,14 +258,19 @@ def _get_code_from_file(run_name, fname): return code, fname def run_path(path_name, init_globals=None, run_name=None): - """Execute code located at the specified filesystem location + """Execute code located at the specified filesystem location. + + path_name -- filesystem location of a Python script, zipfile, + or directory containing a top level __main__.py script. + + Optional arguments: + init_globals -- dictionary used to pre-populate the module’s + globals dictionary before the code is executed. - Returns the resulting top level namespace dictionary + run_name -- if not None, this will be used to set __name__; + otherwise, '' will be used for __name__. - The file path may refer directly to a Python script (i.e. - one that could be directly executed with execfile) or else - it may refer to a zipfile or directory containing a top - level __main__.py script. + Returns the resulting module globals dictionary. """ if run_name is None: run_name = "" diff --git a/Lib/shutil.py b/Lib/shutil.py index c048cdf9..48a60c0d 100644 --- a/Lib/shutil.py +++ b/Lib/shutil.py @@ -526,9 +526,6 @@ def copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2, ignore_dangling_symlinks=False, dirs_exist_ok=False): """Recursively copy a directory tree and return the destination directory. - dirs_exist_ok dictates whether to raise an exception in case dst or any - missing parent directory already exists. - If exception(s) occur, an Error is raised with a list of reasons. If the optional symlinks flag is true, symbolic links in the @@ -559,6 +556,11 @@ def copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2, destination path as arguments. By default, copy2() is used, but any function that supports the same signature (like copy()) can be used. + If dirs_exist_ok is false (the default) and `dst` already exists, a + `FileExistsError` is raised. If `dirs_exist_ok` is true, the copying + operation will continue if it encounters existing directories, and files + within the `dst` tree will be overwritten by corresponding files from the + `src` tree. """ sys.audit("shutil.copytree", src, dst) with os.scandir(src) as itr: diff --git a/Lib/sqlite3/__init__.py b/Lib/sqlite3/__init__.py index 1e717450..34a9c047 100644 --- a/Lib/sqlite3/__init__.py +++ b/Lib/sqlite3/__init__.py @@ -21,7 +21,7 @@ # 3. This notice may not be removed or altered from any source distribution. """ -The sqlite3 extension module provides a DB-API 2.0 (PEP 249) compilant +The sqlite3 extension module provides a DB-API 2.0 (PEP 249) compliant interface to the SQLite library, and requires SQLite 3.7.15 or newer. To use the module, start by creating a database Connection object: diff --git a/Lib/sqlite3/test/regression.py b/Lib/sqlite3/test/regression.py index 6ba33564..4d5b7b7a 100644 --- a/Lib/sqlite3/test/regression.py +++ b/Lib/sqlite3/test/regression.py @@ -28,6 +28,9 @@ import weakref import functools from test import support +from unittest.mock import patch + + class RegressionTests(unittest.TestCase): def setUp(self): self.con = sqlite.connect(":memory:") @@ -413,10 +416,50 @@ class RegressionTests(unittest.TestCase): +class RecursiveUseOfCursors(unittest.TestCase): + # GH-80254: sqlite3 should not segfault for recursive use of cursors. + msg = "Recursive use of cursors not allowed" + + def setUp(self): + self.con = sqlite.connect(":memory:", + detect_types=sqlite.PARSE_COLNAMES) + self.cur = self.con.cursor() + self.cur.execute("create table test(x foo)") + self.cur.executemany("insert into test(x) values (?)", + [("foo",), ("bar",)]) + + def tearDown(self): + self.cur.close() + self.con.close() + del self.cur + del self.con + + def test_recursive_cursor_init(self): + conv = lambda x: self.cur.__init__(self.con) + with patch.dict(sqlite.converters, {"INIT": conv}): + with self.assertRaisesRegex(sqlite.ProgrammingError, self.msg): + self.cur.execute(f'select x as "x [INIT]", x from test') + + def test_recursive_cursor_close(self): + conv = lambda x: self.cur.close() + with patch.dict(sqlite.converters, {"CLOSE": conv}): + with self.assertRaisesRegex(sqlite.ProgrammingError, self.msg): + self.cur.execute(f'select x as "x [CLOSE]", x from test') + + def test_recursive_cursor_fetch(self): + conv = lambda x, l=[]: self.cur.fetchone() if l else l.append(None) + with patch.dict(sqlite.converters, {"ITER": conv}): + self.cur.execute(f'select x as "x [ITER]", x from test') + with self.assertRaisesRegex(sqlite.ProgrammingError, self.msg): + self.cur.fetchall() + + def suite(): regression_suite = unittest.makeSuite(RegressionTests, "Check") + recursive_cursor = unittest.makeSuite(RecursiveUseOfCursors) return unittest.TestSuite(( regression_suite, + recursive_cursor, )) def test(): diff --git a/Lib/sre_compile.py b/Lib/sre_compile.py index c6398bfb..aed752d1 100644 --- a/Lib/sre_compile.py +++ b/Lib/sre_compile.py @@ -52,6 +52,22 @@ _equivalences = ( (0x3c2, 0x3c3), # ςσ # GREEK SMALL LETTER PHI, GREEK PHI SYMBOL (0x3c6, 0x3d5), # φϕ + # CYRILLIC SMALL LETTER VE, CYRILLIC SMALL LETTER ROUNDED VE + (0x432, 0x1c80), # вᲀ + # CYRILLIC SMALL LETTER DE, CYRILLIC SMALL LETTER LONG-LEGGED DE + (0x434, 0x1c81), # дᲁ + # CYRILLIC SMALL LETTER O, CYRILLIC SMALL LETTER NARROW O + (0x43e, 0x1c82), # оᲂ + # CYRILLIC SMALL LETTER ES, CYRILLIC SMALL LETTER WIDE ES + (0x441, 0x1c83), # сᲃ + # CYRILLIC SMALL LETTER TE, CYRILLIC SMALL LETTER TALL TE, CYRILLIC SMALL LETTER THREE-LEGGED TE + (0x442, 0x1c84, 0x1c85), # тᲄᲅ + # CYRILLIC SMALL LETTER HARD SIGN, CYRILLIC SMALL LETTER TALL HARD SIGN + (0x44a, 0x1c86), # ъᲆ + # CYRILLIC SMALL LETTER YAT, CYRILLIC SMALL LETTER TALL YAT + (0x463, 0x1c87), # ѣᲇ + # CYRILLIC SMALL LETTER UNBLENDED UK, CYRILLIC SMALL LETTER MONOGRAPH UK + (0x1c88, 0xa64b), # ᲈꙋ # LATIN SMALL LETTER S WITH DOT ABOVE, LATIN SMALL LETTER LONG S WITH DOT ABOVE (0x1e61, 0x1e9b), # ṡẛ # LATIN SMALL LIGATURE LONG S T, LATIN SMALL LIGATURE ST @@ -320,11 +336,19 @@ def _optimize_charset(charset, iscased=None, fixup=None, fixes=None): charmap += b'\0' * 0xff00 continue # Character set contains non-BMP character codes. + # For range, all BMP characters in the range are already + # proceeded. if fixup: hascased = True - # There are only two ranges of cased non-BMP characters: - # 10400-1044F (Deseret) and 118A0-118DF (Warang Citi), - # and for both ranges RANGE_UNI_IGNORE works. + # For now, IN_UNI_IGNORE+LITERAL and + # IN_UNI_IGNORE+RANGE_UNI_IGNORE work for all non-BMP + # characters, because two characters (at least one of + # which is not in the BMP) match case-insensitively + # if and only if: + # 1) c1.lower() == c2.lower() + # 2) c1.lower() == c2 or c1.lower().upper() == c2 + # Also, both c.lower() and c.lower().upper() are single + # characters for every non-BMP character. if op is RANGE: op = RANGE_UNI_IGNORE tail.append((op, av)) diff --git a/Lib/sre_constants.py b/Lib/sre_constants.py index 8e613cb3..db3ca51e 100644 --- a/Lib/sre_constants.py +++ b/Lib/sre_constants.py @@ -62,6 +62,8 @@ class _NamedIntConstant(int): def __repr__(self): return self.name + __reduce__ = None + MAXREPEAT = _NamedIntConstant(MAXREPEAT, 'MAXREPEAT') def _makecodes(names): diff --git a/Lib/sre_parse.py b/Lib/sre_parse.py index 53706676..20a60250 100644 --- a/Lib/sre_parse.py +++ b/Lib/sre_parse.py @@ -78,6 +78,7 @@ class State: self.groupdict = {} self.groupwidths = [None] # group 0 self.lookbehindgroups = None + self.grouprefpos = {} @property def groups(self): return len(self.groupwidths) @@ -330,7 +331,7 @@ def _class_escape(source, escape): charname = source.getuntil('}', 'character name') try: c = ord(unicodedata.lookup(charname)) - except KeyError: + except (KeyError, TypeError): raise source.error("undefined character name %r" % charname, len(charname) + len(r'\N{}')) return LITERAL, c @@ -390,7 +391,7 @@ def _escape(source, escape, state): charname = source.getuntil('}', 'character name') try: c = ord(unicodedata.lookup(charname)) - except KeyError: + except (KeyError, TypeError): raise source.error("undefined character name %r" % charname, len(charname) + len(r'\N{}')) return LITERAL, c @@ -786,6 +787,10 @@ def _parse(source, state, verbose, nested, first=False): if condgroup >= MAXGROUPS: msg = "invalid group reference %d" % condgroup raise source.error(msg, len(condname) + 1) + if condgroup not in state.grouprefpos: + state.grouprefpos[condgroup] = ( + source.tell() - len(condname) - 1 + ) state.checklookbehindgroup(condgroup, source) item_yes = _parse(source, state, verbose, nested + 1) if source.match("|"): @@ -963,6 +968,11 @@ def parse(str, flags=0, state=None): assert source.next == ")" raise source.error("unbalanced parenthesis") + for g in p.state.grouprefpos: + if g >= p.state.groups: + msg = "invalid group reference %d" % g + raise error(msg, str, p.state.grouprefpos[g]) + if flags & SRE_FLAG_DEBUG: p.dump() diff --git a/Lib/ssl.py b/Lib/ssl.py index 30f4e593..0e3606b8 100644 --- a/Lib/ssl.py +++ b/Lib/ssl.py @@ -18,9 +18,10 @@ Functions: seconds past the Epoch (the time values returned from time.time()) - fetch_server_certificate (HOST, PORT) -- fetch the certificate provided - by the server running on HOST at port PORT. No - validation of the certificate is performed. + get_server_certificate (addr, ssl_version, ca_certs, timeout) -- Retrieve the + certificate from the server at the specified + address and return it as a PEM-encoded string + Integer constants: diff --git a/Lib/test/datetimetester.py b/Lib/test/datetimetester.py index 361d5e9b..aa5fe82a 100644 --- a/Lib/test/datetimetester.py +++ b/Lib/test/datetimetester.py @@ -2467,45 +2467,101 @@ class TestDateTime(TestDate): self.assertEqual(t.microsecond, 7812) def test_timestamp_limits(self): - # minimum timestamp - min_dt = self.theclass.min.replace(tzinfo=timezone.utc) + with self.subTest("minimum UTC"): + min_dt = self.theclass.min.replace(tzinfo=timezone.utc) + min_ts = min_dt.timestamp() + + # This test assumes that datetime.min == 0000-01-01T00:00:00.00 + # If that assumption changes, this value can change as well + self.assertEqual(min_ts, -62135596800) + + with self.subTest("maximum UTC"): + # Zero out microseconds to avoid rounding issues + max_dt = self.theclass.max.replace(tzinfo=timezone.utc, + microsecond=0) + max_ts = max_dt.timestamp() + + # This test assumes that datetime.max == 9999-12-31T23:59:59.999999 + # If that assumption changes, this value can change as well + self.assertEqual(max_ts, 253402300799.0) + + def test_fromtimestamp_limits(self): + try: + self.theclass.fromtimestamp(-2**32 - 1) + except (OSError, OverflowError): + self.skipTest("Test not valid on this platform") + + # XXX: Replace these with datetime.{min,max}.timestamp() when we solve + # the issue with gh-91012 + min_dt = self.theclass.min + timedelta(days=1) min_ts = min_dt.timestamp() + + max_dt = self.theclass.max.replace(microsecond=0) + max_ts = ((self.theclass.max - timedelta(hours=23)).timestamp() + + timedelta(hours=22, minutes=59, seconds=59).total_seconds()) + + for (test_name, ts, expected) in [ + ("minimum", min_ts, min_dt), + ("maximum", max_ts, max_dt), + ]: + with self.subTest(test_name, ts=ts, expected=expected): + actual = self.theclass.fromtimestamp(ts) + + self.assertEqual(actual, expected) + + # Test error conditions + test_cases = [ + ("Too small by a little", min_ts - timedelta(days=1, hours=12).total_seconds()), + ("Too small by a lot", min_ts - timedelta(days=400).total_seconds()), + ("Too big by a little", max_ts + timedelta(days=1).total_seconds()), + ("Too big by a lot", max_ts + timedelta(days=400).total_seconds()), + ] + + for test_name, ts in test_cases: + with self.subTest(test_name, ts=ts): + with self.assertRaises((ValueError, OverflowError)): + # converting a Python int to C time_t can raise a + # OverflowError, especially on 32-bit platforms. + self.theclass.fromtimestamp(ts) + + def test_utcfromtimestamp_limits(self): try: - # date 0001-01-01 00:00:00+00:00: timestamp=-62135596800 - self.assertEqual(self.theclass.fromtimestamp(min_ts, tz=timezone.utc), - min_dt) - except (OverflowError, OSError) as exc: - # the date 0001-01-01 doesn't fit into 32-bit time_t, - # or platform doesn't support such very old date - self.skipTest(str(exc)) - - # maximum timestamp: set seconds to zero to avoid rounding issues - max_dt = self.theclass.max.replace(tzinfo=timezone.utc, - second=0, microsecond=0) + self.theclass.utcfromtimestamp(-2**32 - 1) + except (OSError, OverflowError): + self.skipTest("Test not valid on this platform") + + min_dt = self.theclass.min.replace(tzinfo=timezone.utc) + min_ts = min_dt.timestamp() + + max_dt = self.theclass.max.replace(microsecond=0, tzinfo=timezone.utc) max_ts = max_dt.timestamp() - # date 9999-12-31 23:59:00+00:00: timestamp 253402300740 - self.assertEqual(self.theclass.fromtimestamp(max_ts, tz=timezone.utc), - max_dt) - - # number of seconds greater than 1 year: make sure that the new date - # is not valid in datetime.datetime limits - delta = 3600 * 24 * 400 - - # too small - ts = min_ts - delta - # converting a Python int to C time_t can raise a OverflowError, - # especially on 32-bit platforms. - with self.assertRaises((ValueError, OverflowError)): - self.theclass.fromtimestamp(ts) - with self.assertRaises((ValueError, OverflowError)): - self.theclass.utcfromtimestamp(ts) - - # too big - ts = max_dt.timestamp() + delta - with self.assertRaises((ValueError, OverflowError)): - self.theclass.fromtimestamp(ts) - with self.assertRaises((ValueError, OverflowError)): - self.theclass.utcfromtimestamp(ts) + + for (test_name, ts, expected) in [ + ("minimum", min_ts, min_dt.replace(tzinfo=None)), + ("maximum", max_ts, max_dt.replace(tzinfo=None)), + ]: + with self.subTest(test_name, ts=ts, expected=expected): + try: + actual = self.theclass.utcfromtimestamp(ts) + except (OSError, OverflowError) as exc: + self.skipTest(str(exc)) + + self.assertEqual(actual, expected) + + # Test error conditions + test_cases = [ + ("Too small by a little", min_ts - 1), + ("Too small by a lot", min_ts - timedelta(days=400).total_seconds()), + ("Too big by a little", max_ts + 1), + ("Too big by a lot", max_ts + timedelta(days=400).total_seconds()), + ] + + for test_name, ts in test_cases: + with self.subTest(test_name, ts=ts): + with self.assertRaises((ValueError, OverflowError)): + # converting a Python int to C time_t can raise a + # OverflowError, especially on 32-bit platforms. + self.theclass.utcfromtimestamp(ts) def test_insane_fromtimestamp(self): # It's possible that some platform maps time_t to double, diff --git a/Lib/test/test_argparse.py b/Lib/test/test_argparse.py index dcc392fa..2d1cec13 100644 --- a/Lib/test/test_argparse.py +++ b/Lib/test/test_argparse.py @@ -4873,12 +4873,13 @@ class TestStrings(TestCase): nargs='+', default=42, choices=[1, 2, 3], + required=False, help='HELP', metavar='METAVAR') string = ( "Action(option_strings=['--foo', '-a', '-b'], dest='b', " "nargs='+', const=None, default=42, type='int', " - "choices=[1, 2, 3], help='HELP', metavar='METAVAR')") + "choices=[1, 2, 3], required=False, help='HELP', metavar='METAVAR')") self.assertStringEqual(option, string) def test_argument(self): @@ -4889,12 +4890,13 @@ class TestStrings(TestCase): nargs='?', default=2.5, choices=[0.5, 1.5, 2.5], + required=True, help='H HH H', metavar='MV MV MV') string = ( "Action(option_strings=[], dest='x', nargs='?', " "const=None, default=2.5, type=%r, choices=[0.5, 1.5, 2.5], " - "help='H HH H', metavar='MV MV MV')" % float) + "required=True, help='H HH H', metavar='MV MV MV')" % float) self.assertStringEqual(argument, string) def test_namespace(self): diff --git a/Lib/test/test_calendar.py b/Lib/test/test_calendar.py index 6241d114..d6170c7e 100644 --- a/Lib/test/test_calendar.py +++ b/Lib/test/test_calendar.py @@ -595,6 +595,14 @@ class CalendarTestCase(unittest.TestCase): self.assertEqual(days[0][1], firstweekday) self.assertEqual(days[-1][1], (firstweekday - 1) % 7) + def test_iterweekdays(self): + week0 = list(range(7)) + for firstweekday in range(7): + cal = calendar.Calendar(firstweekday) + week = list(cal.iterweekdays()) + expected = week0[firstweekday:] + week0[:firstweekday] + self.assertEqual(week, expected) + class MonthCalendarTestCase(unittest.TestCase): def setUp(self): diff --git a/Lib/test/test_codeccallbacks.py b/Lib/test/test_codeccallbacks.py index 243f002c..49913304 100644 --- a/Lib/test/test_codeccallbacks.py +++ b/Lib/test/test_codeccallbacks.py @@ -1,5 +1,6 @@ import codecs import html.entities +import itertools import sys import unicodedata import unittest @@ -22,6 +23,18 @@ class PosReturn: self.pos = len(exc.object) return ("", oldpos) +class RepeatedPosReturn: + def __init__(self, repl=""): + self.repl = repl + self.pos = 0 + self.count = 0 + + def handle(self, exc): + if self.count > 0: + self.count -= 1 + return (self.repl, self.pos) + return (self.repl, exc.end) + # A UnicodeEncodeError object with a bad start attribute class BadStartUnicodeEncodeError(UnicodeEncodeError): def __init__(self): @@ -783,20 +796,104 @@ class CodecCallbackTest(unittest.TestCase): codecs.lookup_error("namereplace") ) - def test_unencodablereplacement(self): + def test_encode_nonascii_replacement(self): + def handle(exc): + if isinstance(exc, UnicodeEncodeError): + return (repl, exc.end) + raise TypeError("don't know how to handle %r" % exc) + codecs.register_error("test.replacing", handle) + + for enc, input, repl in ( + ("ascii", "[¤]", "abc"), + ("iso-8859-1", "[€]", "½¾"), + ("iso-8859-15", "[¤]", "œŸ"), + ): + res = input.encode(enc, "test.replacing") + self.assertEqual(res, ("[" + repl + "]").encode(enc)) + + for enc, input, repl in ( + ("utf-8", "[\udc80]", "\U0001f40d"), + ("utf-16", "[\udc80]", "\U0001f40d"), + ("utf-32", "[\udc80]", "\U0001f40d"), + ): + with self.subTest(encoding=enc): + with self.assertRaises(UnicodeEncodeError) as cm: + input.encode(enc, "test.replacing") + exc = cm.exception + self.assertEqual(exc.start, 1) + self.assertEqual(exc.end, 2) + self.assertEqual(exc.object, input) + + def test_encode_unencodable_replacement(self): def unencrepl(exc): if isinstance(exc, UnicodeEncodeError): - return ("\u4242", exc.end) + return (repl, exc.end) else: raise TypeError("don't know how to handle %r" % exc) codecs.register_error("test.unencreplhandler", unencrepl) - for enc in ("ascii", "iso-8859-1", "iso-8859-15"): - self.assertRaises( - UnicodeEncodeError, - "\u4242".encode, - enc, - "test.unencreplhandler" - ) + + for enc, input, repl in ( + ("ascii", "[¤]", "½"), + ("iso-8859-1", "[€]", "œ"), + ("iso-8859-15", "[¤]", "½"), + ("utf-8", "[\udc80]", "\udcff"), + ("utf-16", "[\udc80]", "\udcff"), + ("utf-32", "[\udc80]", "\udcff"), + ): + with self.subTest(encoding=enc): + with self.assertRaises(UnicodeEncodeError) as cm: + input.encode(enc, "test.unencreplhandler") + exc = cm.exception + self.assertEqual(exc.start, 1) + self.assertEqual(exc.end, 2) + self.assertEqual(exc.object, input) + + def test_encode_bytes_replacement(self): + def handle(exc): + if isinstance(exc, UnicodeEncodeError): + return (repl, exc.end) + raise TypeError("don't know how to handle %r" % exc) + codecs.register_error("test.replacing", handle) + + # It works even if the bytes sequence is not decodable. + for enc, input, repl in ( + ("ascii", "[¤]", b"\xbd\xbe"), + ("iso-8859-1", "[€]", b"\xbd\xbe"), + ("iso-8859-15", "[¤]", b"\xbd\xbe"), + ("utf-8", "[\udc80]", b"\xbd\xbe"), + ("utf-16le", "[\udc80]", b"\xbd\xbe"), + ("utf-16be", "[\udc80]", b"\xbd\xbe"), + ("utf-32le", "[\udc80]", b"\xbc\xbd\xbe\xbf"), + ("utf-32be", "[\udc80]", b"\xbc\xbd\xbe\xbf"), + ): + with self.subTest(encoding=enc): + res = input.encode(enc, "test.replacing") + self.assertEqual(res, "[".encode(enc) + repl + "]".encode(enc)) + + def test_encode_odd_bytes_replacement(self): + def handle(exc): + if isinstance(exc, UnicodeEncodeError): + return (repl, exc.end) + raise TypeError("don't know how to handle %r" % exc) + codecs.register_error("test.replacing", handle) + + input = "[\udc80]" + # Tests in which the replacement bytestring contains not whole number + # of code units. + for enc, repl in ( + *itertools.product(("utf-16le", "utf-16be"), + [b"a", b"abc"]), + *itertools.product(("utf-32le", "utf-32be"), + [b"a", b"ab", b"abc", b"abcde"]), + ): + with self.subTest(encoding=enc, repl=repl): + with self.assertRaises(UnicodeEncodeError) as cm: + input.encode(enc, "test.replacing") + exc = cm.exception + self.assertEqual(exc.start, 1) + self.assertEqual(exc.end, 2) + self.assertEqual(exc.object, input) + self.assertEqual(exc.reason, "surrogates not allowed") def test_badregistercall(self): # enhance coverage of: @@ -940,6 +1037,68 @@ class CodecCallbackTest(unittest.TestCase): self.assertRaises(ValueError, codecs.charmap_encode, "\xff", err, D()) self.assertRaises(TypeError, codecs.charmap_encode, "\xff", err, {0xff: 300}) + def test_decodehelper_bug36819(self): + handler = RepeatedPosReturn("x") + codecs.register_error("test.bug36819", handler.handle) + + testcases = [ + ("ascii", b"\xff"), + ("utf-8", b"\xff"), + ("utf-16be", b'\xdc\x80'), + ("utf-32be", b'\x00\x00\xdc\x80'), + ("iso-8859-6", b"\xff"), + ] + for enc, bad in testcases: + input = "abcd".encode(enc) + bad + with self.subTest(encoding=enc): + handler.count = 50 + decoded = input.decode(enc, "test.bug36819") + self.assertEqual(decoded, 'abcdx' * 51) + + def test_encodehelper_bug36819(self): + handler = RepeatedPosReturn() + codecs.register_error("test.bug36819", handler.handle) + + input = "abcd\udc80" + encodings = ["ascii", "latin1", "utf-8", "utf-16", "utf-32"] # built-in + encodings += ["iso-8859-15"] # charmap codec + if sys.platform == 'win32': + encodings = ["mbcs", "oem"] # code page codecs + + handler.repl = "\udcff" + for enc in encodings: + with self.subTest(encoding=enc): + handler.count = 50 + with self.assertRaises(UnicodeEncodeError) as cm: + input.encode(enc, "test.bug36819") + exc = cm.exception + self.assertEqual(exc.start, 4) + self.assertEqual(exc.end, 5) + self.assertEqual(exc.object, input) + if sys.platform == "win32": + handler.count = 50 + with self.assertRaises(UnicodeEncodeError) as cm: + codecs.code_page_encode(437, input, "test.bug36819") + exc = cm.exception + self.assertEqual(exc.start, 4) + self.assertEqual(exc.end, 5) + self.assertEqual(exc.object, input) + + handler.repl = "x" + for enc in encodings: + with self.subTest(encoding=enc): + # The interpreter should segfault after a handful of attempts. + # 50 was chosen to try to ensure a segfault without a fix, + # but not OOM a machine with one. + handler.count = 50 + encoded = input.encode(enc, "test.bug36819") + self.assertEqual(encoded.decode(enc), "abcdx" * 51) + if sys.platform == "win32": + handler.count = 50 + encoded = codecs.code_page_encode(437, input, "test.bug36819") + self.assertEqual(encoded[0].decode(), "abcdx" * 51) + self.assertEqual(encoded[1], len(input)) + def test_translatehelper(self): # enhance coverage of: # Objects/unicodeobject.c::unicode_encode_call_errorhandler() diff --git a/Lib/test/test_compileall.py b/Lib/test/test_compileall.py index a904f426..ab647d66 100644 --- a/Lib/test/test_compileall.py +++ b/Lib/test/test_compileall.py @@ -449,32 +449,29 @@ class EncodingTest(unittest.TestCase): class CommandLineTestsBase: """Test compileall's CLI.""" - @classmethod - def setUpClass(cls): - for path in filter(os.path.isdir, sys.path): - directory_created = False - directory = pathlib.Path(path) / '__pycache__' - path = directory / 'test.try' - try: - if not directory.is_dir(): - directory.mkdir() - directory_created = True - with path.open('w') as file: - file.write('# for test_compileall') - except OSError: - sys_path_writable = False - break - finally: - support.unlink(str(path)) - if directory_created: - directory.rmdir() - else: - sys_path_writable = True - cls._sys_path_writable = sys_path_writable - - def _skip_if_sys_path_not_writable(self): - if not self._sys_path_writable: - raise unittest.SkipTest('not all entries on sys.path are writable') + def setUp(self): + self.directory = tempfile.mkdtemp() + self.addCleanup(shutil.rmtree, self.directory) + self.pkgdir = os.path.join(self.directory, 'foo') + os.mkdir(self.pkgdir) + self.pkgdir_cachedir = os.path.join(self.pkgdir, '__pycache__') + # Create the __init__.py and a package module. + self.initfn = script_helper.make_script(self.pkgdir, '__init__', '') + self.barfn = script_helper.make_script(self.pkgdir, 'bar', '') + + @contextlib.contextmanager + def temporary_pycache_prefix(self): + """Adjust and restore sys.pycache_prefix.""" + old_prefix = sys.pycache_prefix + new_prefix = os.path.join(self.directory, '__testcache__') + try: + sys.pycache_prefix = new_prefix + yield { + 'PYTHONPATH': self.directory, + 'PYTHONPYCACHEPREFIX': new_prefix, + } + finally: + sys.pycache_prefix = old_prefix def _get_run_args(self, args): return [*support.optim_args_from_interpreter_flags(), @@ -502,49 +499,39 @@ class CommandLineTestsBase: path = importlib.util.cache_from_source(fn) self.assertFalse(os.path.exists(path)) - def setUp(self): - self.directory = tempfile.mkdtemp() - self.addCleanup(support.rmtree, self.directory) - self.pkgdir = os.path.join(self.directory, 'foo') - os.mkdir(self.pkgdir) - self.pkgdir_cachedir = os.path.join(self.pkgdir, '__pycache__') - # Create the __init__.py and a package module. - self.initfn = script_helper.make_script(self.pkgdir, '__init__', '') - self.barfn = script_helper.make_script(self.pkgdir, 'bar', '') - def test_no_args_compiles_path(self): # Note that -l is implied for the no args case. - self._skip_if_sys_path_not_writable() bazfn = script_helper.make_script(self.directory, 'baz', '') - self.assertRunOK(PYTHONPATH=self.directory) - self.assertCompiled(bazfn) - self.assertNotCompiled(self.initfn) - self.assertNotCompiled(self.barfn) + with self.temporary_pycache_prefix() as env: + self.assertRunOK(**env) + self.assertCompiled(bazfn) + self.assertNotCompiled(self.initfn) + self.assertNotCompiled(self.barfn) @without_source_date_epoch # timestamp invalidation test def test_no_args_respects_force_flag(self): - self._skip_if_sys_path_not_writable() bazfn = script_helper.make_script(self.directory, 'baz', '') - self.assertRunOK(PYTHONPATH=self.directory) - pycpath = importlib.util.cache_from_source(bazfn) + with self.temporary_pycache_prefix() as env: + self.assertRunOK(**env) + pycpath = importlib.util.cache_from_source(bazfn) # Set atime/mtime backward to avoid file timestamp resolution issues os.utime(pycpath, (time.time()-60,)*2) mtime = os.stat(pycpath).st_mtime # Without force, no recompilation - self.assertRunOK(PYTHONPATH=self.directory) + self.assertRunOK(**env) mtime2 = os.stat(pycpath).st_mtime self.assertEqual(mtime, mtime2) # Now force it. - self.assertRunOK('-f', PYTHONPATH=self.directory) + self.assertRunOK('-f', **env) mtime2 = os.stat(pycpath).st_mtime self.assertNotEqual(mtime, mtime2) def test_no_args_respects_quiet_flag(self): - self._skip_if_sys_path_not_writable() script_helper.make_script(self.directory, 'baz', '') - noisy = self.assertRunOK(PYTHONPATH=self.directory) + with self.temporary_pycache_prefix() as env: + noisy = self.assertRunOK(**env) self.assertIn(b'Listing ', noisy) - quiet = self.assertRunOK('-q', PYTHONPATH=self.directory) + quiet = self.assertRunOK('-q', **env) self.assertNotIn(b'Listing ', quiet) # Ensure that the default behavior of compileall's CLI is to create diff --git a/Lib/test/test_concurrent_futures.py b/Lib/test/test_concurrent_futures.py index d421b027..2d27a294 100644 --- a/Lib/test/test_concurrent_futures.py +++ b/Lib/test/test_concurrent_futures.py @@ -26,10 +26,10 @@ from concurrent.futures._base import ( PENDING, RUNNING, CANCELLED, CANCELLED_AND_NOTIFIED, FINISHED, Future, BrokenExecutor) from concurrent.futures.process import BrokenProcessPool -from multiprocessing import get_context import multiprocessing.process import multiprocessing.util +import multiprocessing as mp if support.check_sanitizer(address=True, memory=True): @@ -131,7 +131,6 @@ class ExecutorMixin: self.executor = self.executor_type( max_workers=self.worker_count, **self.executor_kwargs) - self._prime_executor() def tearDown(self): self.executor.shutdown(wait=True) @@ -145,15 +144,7 @@ class ExecutorMixin: super().tearDown() def get_context(self): - return get_context(self.ctx) - - def _prime_executor(self): - # Make sure that the executor is ready to do work before running the - # tests. This should reduce the probability of timeouts in the tests. - futures = [self.executor.submit(time.sleep, 0.1) - for _ in range(self.worker_count)] - for f in futures: - f.result() + return mp.get_context(self.ctx) class ThreadPoolMixin(ExecutorMixin): @@ -261,9 +252,6 @@ class FailingInitializerMixin(ExecutorMixin): with self.assertRaises(BrokenExecutor): self.executor.submit(get_init_status) - def _prime_executor(self): - pass - @contextlib.contextmanager def _assert_logged(self, msg): if self.log_queue is not None: @@ -350,14 +338,14 @@ class ExecutorShutdownTest: f.result() def test_cancel_futures(self): - executor = self.executor_type(max_workers=3) - fs = [executor.submit(time.sleep, .1) for _ in range(50)] - executor.shutdown(cancel_futures=True) + assert self.worker_count <= 5, "test needs few workers" + fs = [self.executor.submit(time.sleep, .1) for _ in range(50)] + self.executor.shutdown(cancel_futures=True) # We can't guarantee the exact number of cancellations, but we can - # guarantee that *some* were cancelled. With setting max_workers to 3, - # most of the submitted futures should have been cancelled. + # guarantee that *some* were cancelled. With few workers, many of + # the submitted futures should have been cancelled. cancelled = [fut for fut in fs if fut.cancelled()] - self.assertTrue(len(cancelled) >= 35, msg=f"{len(cancelled)=}") + self.assertGreater(len(cancelled), 20) # Ensure the other futures were able to finish. # Use "not fut.cancelled()" instead of "fut.done()" to include futures @@ -370,33 +358,32 @@ class ExecutorShutdownTest: # Similar to the number of cancelled futures, we can't guarantee the # exact number that completed. But, we can guarantee that at least # one finished. - self.assertTrue(len(others) > 0, msg=f"{len(others)=}") + self.assertGreater(len(others), 0) - def test_hang_issue39205(self): + def test_hang_gh83386(self): """shutdown(wait=False) doesn't hang at exit with running futures. - See https://bugs.python.org/issue39205. + See https://github.com/python/cpython/issues/83386. """ if self.executor_type == futures.ProcessPoolExecutor: raise unittest.SkipTest( - "Hangs due to https://bugs.python.org/issue39205") + "Hangs, see https://github.com/python/cpython/issues/83386") rc, out, err = assert_python_ok('-c', """if True: from concurrent.futures import {executor_type} from test.test_concurrent_futures import sleep_and_print if __name__ == "__main__": + if {context!r}: multiprocessing.set_start_method({context!r}) t = {executor_type}(max_workers=3) t.submit(sleep_and_print, 1.0, "apple") t.shutdown(wait=False) - """.format(executor_type=self.executor_type.__name__)) + """.format(executor_type=self.executor_type.__name__, + context=getattr(self, 'ctx', None))) self.assertFalse(err) self.assertEqual(out.strip(), b"apple") class ThreadPoolShutdownTest(ThreadPoolMixin, ExecutorShutdownTest, BaseTestCase): - def _prime_executor(self): - pass - def test_threads_terminate(self): def acquire_lock(lock): lock.acquire() @@ -491,18 +478,21 @@ class ThreadPoolShutdownTest(ThreadPoolMixin, ExecutorShutdownTest, BaseTestCase class ProcessPoolShutdownTest(ExecutorShutdownTest): - def _prime_executor(self): - pass - def test_processes_terminate(self): def acquire_lock(lock): lock.acquire() - mp_context = get_context() + mp_context = self.get_context() + if mp_context.get_start_method(allow_none=False) == "fork": + # fork pre-spawns, not on demand. + expected_num_processes = self.worker_count + else: + expected_num_processes = 3 + sem = mp_context.Semaphore(0) for _ in range(3): self.executor.submit(acquire_lock, sem) - self.assertEqual(len(self.executor._processes), 3) + self.assertEqual(len(self.executor._processes), expected_num_processes) for _ in range(3): sem.release() processes = self.executor._processes @@ -512,7 +502,8 @@ class ProcessPoolShutdownTest(ExecutorShutdownTest): p.join() def test_context_manager_shutdown(self): - with futures.ProcessPoolExecutor(max_workers=5) as e: + with futures.ProcessPoolExecutor( + max_workers=5, mp_context=self.get_context()) as e: processes = e._processes self.assertEqual(list(e.map(abs, range(-5, 5))), [5, 4, 3, 2, 1, 0, 1, 2, 3, 4]) @@ -521,7 +512,8 @@ class ProcessPoolShutdownTest(ExecutorShutdownTest): p.join() def test_del_shutdown(self): - executor = futures.ProcessPoolExecutor(max_workers=5) + executor = futures.ProcessPoolExecutor( + max_workers=5, mp_context=self.get_context()) res = executor.map(abs, range(-5, 5)) executor_manager_thread = executor._executor_manager_thread processes = executor._processes @@ -544,7 +536,8 @@ class ProcessPoolShutdownTest(ExecutorShutdownTest): def test_shutdown_no_wait(self): # Ensure that the executor cleans up the processes when calling # shutdown with wait=False - executor = futures.ProcessPoolExecutor(max_workers=5) + executor = futures.ProcessPoolExecutor( + max_workers=5, mp_context=self.get_context()) res = executor.map(abs, range(-5, 5)) processes = executor._processes call_queue = executor._call_queue @@ -921,7 +914,7 @@ class ThreadPoolExecutorTest(ThreadPoolMixin, ExecutorTest, BaseTestCase): pool.submit(submit, pool) for _ in range(50): - with futures.ProcessPoolExecutor(1, mp_context=get_context('fork')) as workers: + with futures.ProcessPoolExecutor(1, mp_context=mp.get_context('fork')) as workers: workers.submit(tuple) @@ -991,7 +984,7 @@ class ProcessPoolExecutorTest(ExecutorTest): def test_ressources_gced_in_workers(self): # Ensure that argument for a job are correctly gc-ed after the job # is finished - mgr = get_context(self.ctx).Manager() + mgr = self.get_context().Manager() obj = EventfulGCObj(mgr) future = self.executor.submit(id, obj) future.result() @@ -1007,36 +1000,41 @@ class ProcessPoolExecutorTest(ExecutorTest): mgr.join() def test_saturation(self): - executor = self.executor_type(4) - mp_context = get_context() + executor = self.executor + mp_context = self.get_context() sem = mp_context.Semaphore(0) job_count = 15 * executor._max_workers - try: - for _ in range(job_count): - executor.submit(sem.acquire) - self.assertEqual(len(executor._processes), executor._max_workers) - for _ in range(job_count): - sem.release() - finally: - executor.shutdown() + for _ in range(job_count): + executor.submit(sem.acquire) + self.assertEqual(len(executor._processes), executor._max_workers) + for _ in range(job_count): + sem.release() def test_idle_process_reuse_one(self): - executor = self.executor_type(4) + executor = self.executor + assert executor._max_workers >= 4 + if self.get_context().get_start_method(allow_none=False) == "fork": + raise unittest.SkipTest("Incompatible with the fork start method.") executor.submit(mul, 21, 2).result() executor.submit(mul, 6, 7).result() executor.submit(mul, 3, 14).result() self.assertEqual(len(executor._processes), 1) - executor.shutdown() def test_idle_process_reuse_multiple(self): - executor = self.executor_type(4) + executor = self.executor + assert executor._max_workers <= 5 + if self.get_context().get_start_method(allow_none=False) == "fork": + raise unittest.SkipTest("Incompatible with the fork start method.") executor.submit(mul, 12, 7).result() executor.submit(mul, 33, 25) executor.submit(mul, 25, 26).result() executor.submit(mul, 18, 29) - self.assertLessEqual(len(executor._processes), 2) + executor.submit(mul, 1, 2).result() + executor.submit(mul, 0, 9) + self.assertLessEqual(len(executor._processes), 3) executor.shutdown() + create_executor_tests(ProcessPoolExecutorTest, executor_mixins=(ProcessPoolForkMixin, ProcessPoolForkserverMixin, @@ -1138,7 +1136,7 @@ class ExecutorDeadlockTest: self.executor.shutdown(wait=True) executor = self.executor_type( - max_workers=2, mp_context=get_context(self.ctx)) + max_workers=2, mp_context=self.get_context()) res = executor.submit(func, *args) if ignore_stderr: @@ -1217,7 +1215,7 @@ class ExecutorDeadlockTest: # if a worker fails after the shutdown call. self.executor.shutdown(wait=True) with self.executor_type(max_workers=2, - mp_context=get_context(self.ctx)) as executor: + mp_context=self.get_context()) as executor: self.executor = executor # Allow clean up in fail_on_deadlock f = executor.submit(_crash, delay=.1) executor.shutdown(wait=True) @@ -1230,7 +1228,7 @@ class ExecutorDeadlockTest: # Reported in bpo-39104. self.executor.shutdown(wait=True) with self.executor_type(max_workers=2, - mp_context=get_context(self.ctx)) as executor: + mp_context=self.get_context()) as executor: self.executor = executor # Allow clean up in fail_on_deadlock # Start the executor and get the executor_manager_thread to collect diff --git a/Lib/test/test_curses.py b/Lib/test/test_curses.py index 4bdc2379..48b1d53f 100644 --- a/Lib/test/test_curses.py +++ b/Lib/test/test_curses.py @@ -266,7 +266,12 @@ class TestCurses(unittest.TestCase): stdscr.echochar(b'A') stdscr.echochar(65) with self.assertRaises((UnicodeEncodeError, OverflowError)): - stdscr.echochar('\u20ac') + # Unicode is not fully supported yet, but at least it does + # not crash. + # It is supposed to fail because either the character is + # not encodable with the current encoding, or it is encoded to + # a multibyte sequence. + stdscr.echochar('\u0114') stdscr.echochar('A', curses.A_BOLD) self.assertIs(stdscr.is_wintouched(), False) diff --git a/Lib/test/test_descr.py b/Lib/test/test_descr.py index e5e9f493..a8fe3ef6 100644 --- a/Lib/test/test_descr.py +++ b/Lib/test/test_descr.py @@ -5686,6 +5686,23 @@ class MroTest(unittest.TestCase): class A(metaclass=M): pass + def test_disappearing_custom_mro(self): + """ + gh-92112: A custom mro() returning a result conflicting with + __bases__ and deleting itself caused a double free. + """ + class B: + pass + + class M(DebugHelperMeta): + def mro(cls): + del M.mro + return (B,) + + with self.assertRaises(TypeError): + class A(metaclass=M): + pass + if __name__ == "__main__": unittest.main() diff --git a/Lib/test/test_email/test__encoded_words.py b/Lib/test/test_email/test__encoded_words.py index 0b8b1de3..1713962f 100644 --- a/Lib/test/test_email/test__encoded_words.py +++ b/Lib/test/test_email/test__encoded_words.py @@ -130,6 +130,13 @@ class TestDecode(TestEmailBase): # XXX Should this be a new Defect instead? defects = [errors.CharsetError]) + def test_invalid_character_in_charset(self): + self._test('=?utf-8\udce2\udc80\udc9d?q?foo=ACbar?=', + b'foo\xacbar'.decode('ascii', 'surrogateescape'), + charset = 'utf-8\udce2\udc80\udc9d', + # XXX Should this be a new Defect instead? + defects = [errors.CharsetError]) + def test_q_nonascii(self): self._test('=?utf-8?q?=C3=89ric?=', 'Éric', diff --git a/Lib/test/test_email/test_email.py b/Lib/test/test_email/test_email.py index 489cd05b..761ea90b 100644 --- a/Lib/test/test_email/test_email.py +++ b/Lib/test/test_email/test_email.py @@ -5323,6 +5323,15 @@ Content-Disposition: inline; Content-Transfer-Encoding: 8bit Content-Disposition: inline; filename*=X-UNKNOWN''myfile.txt +""" + msg = email.message_from_string(m) + self.assertEqual(msg.get_filename(), 'myfile.txt') + + def test_rfc2231_bad_character_in_encoding(self): + m = """\ +Content-Transfer-Encoding: 8bit +Content-Disposition: inline; filename*=utf-8\udce2\udc80\udc9d''myfile.txt + """ msg = email.message_from_string(m) self.assertEqual(msg.get_filename(), 'myfile.txt') diff --git a/Lib/test/test_email/test_headerregistry.py b/Lib/test/test_email/test_headerregistry.py index 68bbc956..9a512fdb 100644 --- a/Lib/test/test_email/test_headerregistry.py +++ b/Lib/test/test_email/test_headerregistry.py @@ -698,6 +698,18 @@ class TestContentTypeHeader(TestHeaderBase): " charset*=unknown-8bit''utf-8%E2%80%9D\n", ), + 'rfc2231_nonascii_in_charset_of_charset_parameter_value': ( + "text/plain; charset*=utf-8”''utf-8%E2%80%9D", + 'text/plain', + 'text', + 'plain', + {'charset': 'utf-8”'}, + [], + 'text/plain; charset="utf-8”"', + "Content-Type: text/plain;" + " charset*=utf-8''utf-8%E2%80%9D\n", + ), + 'rfc2231_encoded_then_unencoded_segments': ( ('application/x-foo;' '\tname*0*="us-ascii\'en-us\'My";' diff --git a/Lib/test/test_embed.py b/Lib/test/test_embed.py index 11c8f012..8e5cfa48 100644 --- a/Lib/test/test_embed.py +++ b/Lib/test/test_embed.py @@ -1145,20 +1145,11 @@ class InitConfigTests(EmbeddingTestsMixin, unittest.TestCase): if MS_WINDOWS: # Copy pythonXY.dll (or pythonXY_d.dll) - ver = sys.version_info - dll = f'python{ver.major}{ver.minor}' - dll3 = f'python{ver.major}' - if debug_build(sys.executable): - dll += '_d' - dll3 += '_d' - dll += '.dll' - dll3 += '.dll' - dll = os.path.join(os.path.dirname(self.test_exe), dll) - dll3 = os.path.join(os.path.dirname(self.test_exe), dll3) - dll_copy = os.path.join(tmpdir, os.path.basename(dll)) - dll3_copy = os.path.join(tmpdir, os.path.basename(dll3)) - shutil.copyfile(dll, dll_copy) - shutil.copyfile(dll3, dll3_copy) + import fnmatch + exedir = os.path.dirname(self.test_exe) + for f in os.listdir(exedir): + if fnmatch.fnmatch(f, '*.dll'): + shutil.copyfile(os.path.join(exedir, f), os.path.join(tmpdir, f)) # Copy Python program exec_copy = os.path.join(tmpdir, os.path.basename(self.test_exe)) diff --git a/Lib/test/test_htmlparser.py b/Lib/test/test_htmlparser.py index 12917755..44a76a44 100644 --- a/Lib/test/test_htmlparser.py +++ b/Lib/test/test_htmlparser.py @@ -787,5 +787,27 @@ class AttributesTestCase(TestCaseBase): ('starttag', 'form', [('action', 'bogus|&#()value')])]) + def test_invalid_keyword_error_exception(self): + # bpo-34480: check that subclasses that define an + # error method that raises an exception work + class InvalidMarkupException(Exception): + pass + class MyHTMLParser(html.parser.HTMLParser): + def error(self, message): + raise InvalidMarkupException(message) + parser = MyHTMLParser() + with self.assertRaises(InvalidMarkupException): + parser.feed('') + + def test_invalid_keyword_error_pass(self): + # bpo-34480: check that subclasses that define an + # error method that doesn't raise an exception work + class MyHTMLParser(html.parser.HTMLParser): + def error(self, message): + pass + parser = MyHTMLParser() + self.assertEqual(parser.feed(''), None) + + if __name__ == "__main__": unittest.main() diff --git a/Lib/test/test_ipaddress.py b/Lib/test/test_ipaddress.py index cdd9880c..90897f6b 100644 --- a/Lib/test/test_ipaddress.py +++ b/Lib/test/test_ipaddress.py @@ -580,6 +580,10 @@ class NetmaskTestMixin_v4(CommonTestMixin_v4): assertBadAddress("1.2.3.256", re.escape("256 (> 255)")) def test_valid_netmask(self): + self.assertEqual(str(self.factory(('192.0.2.0', 24))), '192.0.2.0/24') + self.assertEqual(str(self.factory(('192.0.2.0', '24'))), '192.0.2.0/24') + self.assertEqual(str(self.factory(('192.0.2.0', '255.255.255.0'))), + '192.0.2.0/24') self.assertEqual(str(self.factory('192.0.2.0/255.255.255.0')), '192.0.2.0/24') for i in range(0, 33): @@ -740,6 +744,10 @@ class NetmaskTestMixin_v6(CommonTestMixin_v6): def test_valid_netmask(self): # We only support CIDR for IPv6, because expanded netmasks are not # standard notation. + self.assertEqual(str(self.factory(('2001:db8::', 32))), + '2001:db8::/32') + self.assertEqual(str(self.factory(('2001:db8::', '32'))), + '2001:db8::/32') self.assertEqual(str(self.factory('2001:db8::/32')), '2001:db8::/32') for i in range(0, 129): # Generate and re-parse the CIDR format (trivial). @@ -1133,6 +1141,14 @@ class IpaddrUnitTest(unittest.TestCase): self.assertEqual(ipaddress.IPv4Interface((3221225985, 24)), ipaddress.IPv4Interface('192.0.2.1/24')) + # Invalid netmask + with self.assertRaises(ValueError): + ipaddress.IPv4Network(('192.0.2.1', '255.255.255.255.0')) + + # Invalid netmask using factory + with self.assertRaises(ValueError): + ipaddress.ip_network(('192.0.2.1', '255.255.255.255.0')) + # issue #16531: constructing IPv6Network from an (address, mask) tuple def testIPv6Tuple(self): # /128 @@ -1192,6 +1208,14 @@ class IpaddrUnitTest(unittest.TestCase): ipaddress.IPv6Network((ip_scoped, 96)) # strict=False and host bits set + # Invalid netmask + with self.assertRaises(ValueError): + ipaddress.IPv6Network(('2001:db8::1', '255.255.255.0')) + + # Invalid netmask using factory + with self.assertRaises(ValueError): + ipaddress.ip_network(('2001:db8::1', '255.255.255.0')) + # issue57 def testAddressIntMath(self): self.assertEqual(ipaddress.IPv4Address('1.1.1.1') + 255, diff --git a/Lib/test/test_os.py b/Lib/test/test_os.py index e48157a3..78dd3151 100644 --- a/Lib/test/test_os.py +++ b/Lib/test/test_os.py @@ -23,6 +23,7 @@ import subprocess import sys import sysconfig import tempfile +import textwrap import threading import time import types @@ -2714,6 +2715,48 @@ class Win32NtTests(unittest.TestCase): self.assertEqual(0, handle_delta) + def test_stat_unlink_race(self): + # bpo-46785: the implementation of os.stat() falls back to reading + # the parent directory if CreateFileW() fails with a permission + # error. If reading the parent directory fails because the file or + # directory are subsequently unlinked, or because the volume or + # share are no longer available, then the original permission error + # should not be restored. + filename = support.TESTFN + self.addCleanup(support.unlink, filename) + deadline = time.time() + 5 + command = textwrap.dedent("""\ + import os + import sys + import time + + filename = sys.argv[1] + deadline = float(sys.argv[2]) + + while time.time() < deadline: + try: + with open(filename, "w") as f: + pass + except OSError: + pass + try: + os.remove(filename) + except OSError: + pass + """) + + with subprocess.Popen([sys.executable, '-c', command, filename, str(deadline)]) as proc: + while time.time() < deadline: + try: + os.stat(filename) + except FileNotFoundError as e: + assert e.winerror == 2 # ERROR_FILE_NOT_FOUND + try: + proc.wait(1) + except subprocess.TimeoutExpired: + proc.terminate() + + @support.skip_unless_symlink class NonLocalSymlinkTests(unittest.TestCase): diff --git a/Lib/test/test_posix.py b/Lib/test/test_posix.py index a8db3067..6ba14547 100644 --- a/Lib/test/test_posix.py +++ b/Lib/test/test_posix.py @@ -1153,7 +1153,9 @@ class PosixTester(unittest.TestCase): mask = posix.sched_getaffinity(0) self.assertIsInstance(mask, set) self.assertGreaterEqual(len(mask), 1) - self.assertRaises(OSError, posix.sched_getaffinity, -1) + if not sys.platform.startswith("freebsd"): + # bpo-47205: does not raise OSError on FreeBSD + self.assertRaises(OSError, posix.sched_getaffinity, -1) for cpu in mask: self.assertIsInstance(cpu, int) self.assertGreaterEqual(cpu, 0) @@ -1171,7 +1173,9 @@ class PosixTester(unittest.TestCase): self.assertRaises(ValueError, posix.sched_setaffinity, 0, [-10]) self.assertRaises(ValueError, posix.sched_setaffinity, 0, map(int, "0X")) self.assertRaises(OverflowError, posix.sched_setaffinity, 0, [1<<128]) - self.assertRaises(OSError, posix.sched_setaffinity, -1, mask) + if not sys.platform.startswith("freebsd"): + # bpo-47205: does not raise OSError on FreeBSD + self.assertRaises(OSError, posix.sched_setaffinity, -1, mask) def test_rtld_constants(self): # check presence of major RTLD_* constants diff --git a/Lib/test/test_re.py b/Lib/test/test_re.py index 48a609b5..c779057b 100644 --- a/Lib/test/test_re.py +++ b/Lib/test/test_re.py @@ -217,6 +217,16 @@ class ReTests(unittest.TestCase): re.compile(r'(?Px)(?P=a)(?(a)y)') re.compile(r'(?Px)(?P=a1)(?(a1)y)') re.compile(r'(?Px)\1(?(1)y)') + re.compile(b'(?Px)(?P=a1)(?(a1)y)') + # New valid identifiers in Python 3 + re.compile('(?P<µ>x)(?P=µ)(?(µ)y)') + re.compile('(?P<𝔘𝔫𝔦𝔠𝔬𝔡𝔢>x)(?P=𝔘𝔫𝔦𝔠𝔬𝔡𝔢)(?(𝔘𝔫𝔦𝔠𝔬𝔡𝔢)y)') + # Support > 100 groups. + pat = '|'.join('x(?P%x)y' % (i, i) for i in range(1, 200 + 1)) + pat = '(?:%s)(?(200)z|t)' % pat + self.assertEqual(re.match(pat, 'xc8yz').span(), (0, 5)) + + def test_symbolic_groups_errors(self): self.checkPatternError(r'(?P)(?P)', "redefinition of group name 'a' as group 2; " "was group 1") @@ -242,16 +252,22 @@ class ReTests(unittest.TestCase): self.checkPatternError(r'(?(-1))', "bad character in group name '-1'", 3) self.checkPatternError(r'(?(1a))', "bad character in group name '1a'", 3) self.checkPatternError(r'(?(a.))', "bad character in group name 'a.'", 3) - # New valid/invalid identifiers in Python 3 - re.compile('(?P<µ>x)(?P=µ)(?(µ)y)') - re.compile('(?P<𝔘𝔫𝔦𝔠𝔬𝔡𝔢>x)(?P=𝔘𝔫𝔦𝔠𝔬𝔡𝔢)(?(𝔘𝔫𝔦𝔠𝔬𝔡𝔢)y)') self.checkPatternError('(?P<©>x)', "bad character in group name '©'", 4) + self.checkPatternError('(?P=©)', "bad character in group name '©'", 4) + self.checkPatternError('(?(©)y)', "bad character in group name '©'", 3) + + def test_symbolic_refs(self): + self.assertEqual(re.sub('(?Px)|(?Py)', r'\g', 'xx'), '') + self.assertEqual(re.sub('(?Px)|(?Py)', r'\2', 'xx'), '') + self.assertEqual(re.sub(b'(?Px)', br'\g', b'xx'), b'xx') + # New valid identifiers in Python 3 + self.assertEqual(re.sub('(?P<µ>x)', r'\g<µ>', 'xx'), 'xx') + self.assertEqual(re.sub('(?P<𝔘𝔫𝔦𝔠𝔬𝔡𝔢>x)', r'\g<𝔘𝔫𝔦𝔠𝔬𝔡𝔢>', 'xx'), 'xx') # Support > 100 groups. pat = '|'.join('x(?P%x)y' % (i, i) for i in range(1, 200 + 1)) - pat = '(?:%s)(?(200)z|t)' % pat - self.assertEqual(re.match(pat, 'xc8yz').span(), (0, 5)) + self.assertEqual(re.sub(pat, r'\g<200>', 'xc8yzxc8y'), 'c8zc8') - def test_symbolic_refs(self): + def test_symbolic_refs_errors(self): self.checkTemplateError('(?Px)', r'\g, unterminated name', 3) self.checkTemplateError('(?Px)', r'\g<', 'xx', @@ -269,18 +285,14 @@ class ReTests(unittest.TestCase): 'invalid group reference 2', 1) with self.assertRaisesRegex(IndexError, "unknown group name 'ab'"): re.sub('(?Px)', r'\g', 'xx') - self.assertEqual(re.sub('(?Px)|(?Py)', r'\g', 'xx'), '') - self.assertEqual(re.sub('(?Px)|(?Py)', r'\2', 'xx'), '') self.checkTemplateError('(?Px)', r'\g<-1>', 'xx', "bad character in group name '-1'", 3) - # New valid/invalid identifiers in Python 3 - self.assertEqual(re.sub('(?P<µ>x)', r'\g<µ>', 'xx'), 'xx') - self.assertEqual(re.sub('(?P<𝔘𝔫𝔦𝔠𝔬𝔡𝔢>x)', r'\g<𝔘𝔫𝔦𝔠𝔬𝔡𝔢>', 'xx'), 'xx') self.checkTemplateError('(?Px)', r'\g<©>', 'xx', "bad character in group name '©'", 3) - # Support > 100 groups. - pat = '|'.join('x(?P%x)y' % (i, i) for i in range(1, 200 + 1)) - self.assertEqual(re.sub(pat, r'\g<200>', 'xc8yzxc8y'), 'c8zc8') + self.checkTemplateError('(?Px)', r'\g<㊀>', 'xx', + "bad character in group name '㊀'", 3) + self.checkTemplateError('(?Px)', r'\g<¹>', 'xx', + "bad character in group name '¹'", 3) def test_re_subn(self): self.assertEqual(re.subn("(?i)b+", "x", "bbbb BBBB"), ('x x', 2)) @@ -542,12 +554,28 @@ class ReTests(unittest.TestCase): pat = '(?:%s)(?(200)z)' % pat self.assertEqual(re.match(pat, 'xc8yz').span(), (0, 5)) - self.checkPatternError(r'(?P)(?(0))', 'bad group number', 10) + def test_re_groupref_exists_errors(self): + self.checkPatternError(r'(?P)(?(0)a|b)', 'bad group number', 10) + self.checkPatternError(r'()(?(-1)a|b)', + "bad character in group name '-1'", 5) + self.checkPatternError(r'()(?(㊀)a|b)', + "bad character in group name '㊀'", 5) + self.checkPatternError(r'()(?(¹)a|b)', + "bad character in group name '¹'", 5) + self.checkPatternError(r'()(?(1', + "missing ), unterminated name", 5) + self.checkPatternError(r'()(?(1)a', + "missing ), unterminated subpattern", 2) self.checkPatternError(r'()(?(1)a|b', 'missing ), unterminated subpattern', 2) + self.checkPatternError(r'()(?(1)a|b|c', + 'conditional backref with more than ' + 'two branches', 10) self.checkPatternError(r'()(?(1)a|b|c)', 'conditional backref with more than ' 'two branches', 10) + self.checkPatternError(r'()(?(2)a)', + "invalid group reference 2", 5) def test_re_groupref_overflow(self): from sre_constants import MAXGROUPS @@ -727,6 +755,10 @@ class ReTests(unittest.TestCase): "undefined character name 'SPAM'", 0) self.checkPatternError(r'[\N{SPAM}]', "undefined character name 'SPAM'", 1) + self.checkPatternError(r'\N{KEYCAP NUMBER SIGN}', + "undefined character name 'KEYCAP NUMBER SIGN'", 0) + self.checkPatternError(r'[\N{KEYCAP NUMBER SIGN}]', + "undefined character name 'KEYCAP NUMBER SIGN'", 1) self.checkPatternError(br'\N{LESS-THAN SIGN}', r'bad escape \N', 0) self.checkPatternError(br'[\N{LESS-THAN SIGN}]', r'bad escape \N', 1) @@ -840,16 +872,30 @@ class ReTests(unittest.TestCase): self.assertEqual(re.match(r"((a)\s(abc|a))", "a a", re.I).group(1), "a a") self.assertEqual(re.match(r"((a)\s(abc|a)*)", "a aa", re.I).group(1), "a aa") - assert '\u212a'.lower() == 'k' # 'K' + # Two different characters have the same lowercase. + assert 'K'.lower() == '\u212a'.lower() == 'k' # 'K' self.assertTrue(re.match(r'K', '\u212a', re.I)) self.assertTrue(re.match(r'k', '\u212a', re.I)) self.assertTrue(re.match(r'\u212a', 'K', re.I)) self.assertTrue(re.match(r'\u212a', 'k', re.I)) - assert '\u017f'.upper() == 'S' # 'Å¿' + + # Two different characters have the same uppercase. + assert 's'.upper() == '\u017f'.upper() == 'S' # 'Å¿' self.assertTrue(re.match(r'S', '\u017f', re.I)) self.assertTrue(re.match(r's', '\u017f', re.I)) self.assertTrue(re.match(r'\u017f', 'S', re.I)) self.assertTrue(re.match(r'\u017f', 's', re.I)) + + # Two different characters have the same uppercase. Unicode 9.0+. + assert '\u0432'.upper() == '\u1c80'.upper() == '\u0412' # 'в', 'ᲀ', 'В' + self.assertTrue(re.match(r'\u0412', '\u0432', re.I)) + self.assertTrue(re.match(r'\u0412', '\u1c80', re.I)) + self.assertTrue(re.match(r'\u0432', '\u0412', re.I)) + self.assertTrue(re.match(r'\u0432', '\u1c80', re.I)) + self.assertTrue(re.match(r'\u1c80', '\u0412', re.I)) + self.assertTrue(re.match(r'\u1c80', '\u0432', re.I)) + + # Two different characters have the same multicharacter uppercase. assert '\ufb05'.upper() == '\ufb06'.upper() == 'ST' # 'ſt', 'st' self.assertTrue(re.match(r'\ufb05', '\ufb06', re.I)) self.assertTrue(re.match(r'\ufb06', '\ufb05', re.I)) @@ -863,16 +909,31 @@ class ReTests(unittest.TestCase): self.assertTrue(re.match(br'[19a]', b'a', re.I)) self.assertTrue(re.match(br'[19a]', b'A', re.I)) self.assertTrue(re.match(br'[19A]', b'a', re.I)) - assert '\u212a'.lower() == 'k' # 'K' + + # Two different characters have the same lowercase. + assert 'K'.lower() == '\u212a'.lower() == 'k' # 'K' self.assertTrue(re.match(r'[19K]', '\u212a', re.I)) self.assertTrue(re.match(r'[19k]', '\u212a', re.I)) self.assertTrue(re.match(r'[19\u212a]', 'K', re.I)) self.assertTrue(re.match(r'[19\u212a]', 'k', re.I)) - assert '\u017f'.upper() == 'S' # 'Å¿' + + # Two different characters have the same uppercase. + assert 's'.upper() == '\u017f'.upper() == 'S' # 'Å¿' self.assertTrue(re.match(r'[19S]', '\u017f', re.I)) self.assertTrue(re.match(r'[19s]', '\u017f', re.I)) self.assertTrue(re.match(r'[19\u017f]', 'S', re.I)) self.assertTrue(re.match(r'[19\u017f]', 's', re.I)) + + # Two different characters have the same uppercase. Unicode 9.0+. + assert '\u0432'.upper() == '\u1c80'.upper() == '\u0412' # 'в', 'ᲀ', 'В' + self.assertTrue(re.match(r'[19\u0412]', '\u0432', re.I)) + self.assertTrue(re.match(r'[19\u0412]', '\u1c80', re.I)) + self.assertTrue(re.match(r'[19\u0432]', '\u0412', re.I)) + self.assertTrue(re.match(r'[19\u0432]', '\u1c80', re.I)) + self.assertTrue(re.match(r'[19\u1c80]', '\u0412', re.I)) + self.assertTrue(re.match(r'[19\u1c80]', '\u0432', re.I)) + + # Two different characters have the same multicharacter uppercase. assert '\ufb05'.upper() == '\ufb06'.upper() == 'ST' # 'ſt', 'st' self.assertTrue(re.match(r'[19\ufb05]', '\ufb06', re.I)) self.assertTrue(re.match(r'[19\ufb06]', '\ufb05', re.I)) @@ -896,16 +957,30 @@ class ReTests(unittest.TestCase): self.assertTrue(re.match(r'[\U00010400-\U00010427]', '\U00010428', re.I)) self.assertTrue(re.match(r'[\U00010400-\U00010427]', '\U00010400', re.I)) - assert '\u212a'.lower() == 'k' # 'K' + # Two different characters have the same lowercase. + assert 'K'.lower() == '\u212a'.lower() == 'k' # 'K' self.assertTrue(re.match(r'[J-M]', '\u212a', re.I)) self.assertTrue(re.match(r'[j-m]', '\u212a', re.I)) self.assertTrue(re.match(r'[\u2129-\u212b]', 'K', re.I)) self.assertTrue(re.match(r'[\u2129-\u212b]', 'k', re.I)) - assert '\u017f'.upper() == 'S' # 'Å¿' + + # Two different characters have the same uppercase. + assert 's'.upper() == '\u017f'.upper() == 'S' # 'Å¿' self.assertTrue(re.match(r'[R-T]', '\u017f', re.I)) self.assertTrue(re.match(r'[r-t]', '\u017f', re.I)) self.assertTrue(re.match(r'[\u017e-\u0180]', 'S', re.I)) self.assertTrue(re.match(r'[\u017e-\u0180]', 's', re.I)) + + # Two different characters have the same uppercase. Unicode 9.0+. + assert '\u0432'.upper() == '\u1c80'.upper() == '\u0412' # 'в', 'ᲀ', 'В' + self.assertTrue(re.match(r'[\u0411-\u0413]', '\u0432', re.I)) + self.assertTrue(re.match(r'[\u0411-\u0413]', '\u1c80', re.I)) + self.assertTrue(re.match(r'[\u0431-\u0433]', '\u0412', re.I)) + self.assertTrue(re.match(r'[\u0431-\u0433]', '\u1c80', re.I)) + self.assertTrue(re.match(r'[\u1c80-\u1c82]', '\u0412', re.I)) + self.assertTrue(re.match(r'[\u1c80-\u1c82]', '\u0432', re.I)) + + # Two different characters have the same multicharacter uppercase. assert '\ufb05'.upper() == '\ufb06'.upper() == 'ST' # 'ſt', 'st' self.assertTrue(re.match(r'[\ufb04-\ufb05]', '\ufb06', re.I)) self.assertTrue(re.match(r'[\ufb06-\ufb07]', '\ufb05', re.I)) @@ -1607,11 +1682,6 @@ class ReTests(unittest.TestCase): self.assertIsNone(re.match(r'(?i:(?-i:a)b)', 'Ab')) self.assertTrue(re.match(r'(?i:(?-i:a)b)', 'aB')) - self.assertTrue(re.match(r'(?x: a) b', 'a b')) - self.assertIsNone(re.match(r'(?x: a) b', ' a b')) - self.assertTrue(re.match(r'(?-x: a) b', ' ab', re.VERBOSE)) - self.assertIsNone(re.match(r'(?-x: a) b', 'ab', re.VERBOSE)) - self.assertTrue(re.match(r'\w(?a:\W)\w', '\xe0\xe0\xe0')) self.assertTrue(re.match(r'(?a:\W(?u:\w)\W)', '\xe0\xe0\xe0')) self.assertTrue(re.match(r'\W(?u:\w)\W', '\xe0\xe0\xe0', re.ASCII)) @@ -1637,6 +1707,33 @@ class ReTests(unittest.TestCase): self.checkPatternError(r'(?i+', 'missing -, : or )', 3) self.checkPatternError(r'(?iz', 'unknown flag', 3) + def test_ignore_spaces(self): + for space in " \t\n\r\v\f": + self.assertTrue(re.fullmatch(space + 'a', 'a', re.VERBOSE)) + for space in b" ", b"\t", b"\n", b"\r", b"\v", b"\f": + self.assertTrue(re.fullmatch(space + b'a', b'a', re.VERBOSE)) + self.assertTrue(re.fullmatch('(?x) a', 'a')) + self.assertTrue(re.fullmatch(' (?x) a', 'a', re.VERBOSE)) + self.assertTrue(re.fullmatch('(?x) (?x) a', 'a')) + self.assertTrue(re.fullmatch(' a(?x: b) c', ' ab c')) + self.assertTrue(re.fullmatch(' a(?-x: b) c', 'a bc', re.VERBOSE)) + self.assertTrue(re.fullmatch('(?x) a(?-x: b) c', 'a bc')) + self.assertTrue(re.fullmatch('(?x) a| b', 'a')) + self.assertTrue(re.fullmatch('(?x) a| b', 'b')) + + def test_comments(self): + self.assertTrue(re.fullmatch('#x\na', 'a', re.VERBOSE)) + self.assertTrue(re.fullmatch(b'#x\na', b'a', re.VERBOSE)) + self.assertTrue(re.fullmatch('(?x)#x\na', 'a')) + self.assertTrue(re.fullmatch('#x\n(?x)#y\na', 'a', re.VERBOSE)) + self.assertTrue(re.fullmatch('(?x)#x\n(?x)#y\na', 'a')) + self.assertTrue(re.fullmatch('#x\na(?x:#y\nb)#z\nc', '#x\nab#z\nc')) + self.assertTrue(re.fullmatch('#x\na(?-x:#y\nb)#z\nc', 'a#y\nbc', + re.VERBOSE)) + self.assertTrue(re.fullmatch('(?x)#x\na(?-x:#y\nb)#z\nc', 'a#y\nbc')) + self.assertTrue(re.fullmatch('(?x)#x\na|#y\nb', 'a')) + self.assertTrue(re.fullmatch('(?x)#x\na|#y\nb', 'b')) + def test_bug_6509(self): # Replacement strings of both types must parse properly. # all strings diff --git a/Lib/test/test_runpy.py b/Lib/test/test_runpy.py index 4aaf75b1..c734f0d6 100644 --- a/Lib/test/test_runpy.py +++ b/Lib/test/test_runpy.py @@ -740,8 +740,7 @@ class RunPathTestCase(unittest.TestCase, CodeExecutionMixin): "runpy.run_path(%r)\n") % dummy_dir script_name = self._make_test_script(script_dir, mod_name, source) zip_name, fname = make_zip_script(script_dir, 'test_zip', script_name) - msg = "recursion depth exceeded" - self.assertRaisesRegex(RecursionError, msg, run_path, zip_name) + self.assertRaises(RecursionError, run_path, zip_name) def test_encoding(self): with temp_dir() as script_dir: diff --git a/Lib/test/test_sys.py b/Lib/test/test_sys.py index 2f1e5e97..ed85d185 100644 --- a/Lib/test/test_sys.py +++ b/Lib/test/test_sys.py @@ -982,8 +982,8 @@ class UnraisableHookTest(unittest.TestCase): with test.support.captured_stderr() as stderr, \ test.support.swap_attr(sys, 'unraisablehook', sys.__unraisablehook__): - expected = self.write_unraisable_exc( - A.B.X(), "msg", "obj"); + expected = self.write_unraisable_exc( + A.B.X(), "msg", "obj"); report = stderr.getvalue() testName = 'test_original_unraisablehook_exception_qualname' self.assertIn(f"{testName}..A.B.X", report) diff --git a/Lib/test/test_sys_settrace.py b/Lib/test/test_sys_settrace.py index 7519309c..8884bf45 100644 --- a/Lib/test/test_sys_settrace.py +++ b/Lib/test/test_sys_settrace.py @@ -1603,6 +1603,54 @@ output.append(4) next(gen()) output.append(5) + @jump_test(2, 3, [1, 3]) + def test_jump_forward_over_listcomp(output): + output.append(1) + x = [i for i in range(10)] + output.append(3) + + # checking for segfaults. + # See https://github.com/python/cpython/issues/92311 + @jump_test(3, 1, []) + def test_jump_backward_over_listcomp(output): + a = 1 + x = [i for i in range(10)] + c = 3 + + @jump_test(8, 2, [2, 7, 2]) + def test_jump_backward_over_listcomp_v2(output): + flag = False + output.append(2) + if flag: + return + x = [i for i in range(5)] + flag = 6 + output.append(7) + output.append(8) + + @async_jump_test(2, 3, [1, 3]) + async def test_jump_forward_over_async_listcomp(output): + output.append(1) + x = [i async for i in asynciter(range(10))] + output.append(3) + + @async_jump_test(3, 1, []) + async def test_jump_backward_over_async_listcomp(output): + a = 1 + x = [i async for i in asynciter(range(10))] + c = 3 + + @async_jump_test(8, 2, [2, 7, 2]) + async def test_jump_backward_over_async_listcomp_v2(output): + flag = False + output.append(2) + if flag: + return + x = [i async for i in asynciter(range(5))] + flag = 6 + output.append(7) + output.append(8) + if __name__ == "__main__": unittest.main() diff --git a/Lib/test/test_typing.py b/Lib/test/test_typing.py index 08eddb09..3fec59a8 100644 --- a/Lib/test/test_typing.py +++ b/Lib/test/test_typing.py @@ -4076,6 +4076,19 @@ class TypedDictTests(BaseTestCase): {'a': typing.Optional[int], 'b': int} ) + def test_non_generic_subscript(self): + # For backward compatibility, subscription works + # on arbitrary TypedDict types. + class TD(TypedDict): + a: T + A = TD[int] + self.assertEqual(A.__origin__, TD) + self.assertEqual(A.__parameters__, ()) + self.assertEqual(A.__args__, (int,)) + a = A(a = 1) + self.assertIs(type(a), dict) + self.assertEqual(a, {'a': 1}) + class IOTests(BaseTestCase): diff --git a/Lib/test/test_urllib2_localnet.py b/Lib/test/test_urllib2_localnet.py index 74374c08..162e356d 100644 --- a/Lib/test/test_urllib2_localnet.py +++ b/Lib/test/test_urllib2_localnet.py @@ -613,6 +613,15 @@ class TestUrlopen(unittest.TestCase): pass self.assertEqual(handler.headers_received["Range"], "bytes=20-39") + def test_sending_headers_camel(self): + handler = self.start_server() + req = urllib.request.Request("http://localhost:%s/" % handler.port, + headers={"X-SoMe-hEader": "foobar"}) + with urllib.request.urlopen(req): + pass + self.assertIn("X-Some-Header", handler.headers_received.keys()) + self.assertNotIn("X-SoMe-hEader", handler.headers_received.keys()) + def test_basic(self): handler = self.start_server() with urllib.request.urlopen("http://localhost:%s" % handler.port) as open_url: diff --git a/Lib/test/test_xml_etree.py b/Lib/test/test_xml_etree.py index 0f45fc71..956d4c58 100644 --- a/Lib/test/test_xml_etree.py +++ b/Lib/test/test_xml_etree.py @@ -10,7 +10,6 @@ import functools import html import io import itertools -import locale import operator import os import pickle @@ -112,6 +111,9 @@ def checkwarnings(*filters, quiet=False): return newtest return decorator +def convlinesep(data): + return data.replace(b'\n', os.linesep.encode()) + class ModuleTest(unittest.TestCase): def test_sanity(self): @@ -957,15 +959,13 @@ class ElementTreeTest(unittest.TestCase): def test_tostring_xml_declaration_unicode_encoding(self): elem = ET.XML('') - preferredencoding = locale.getpreferredencoding() self.assertEqual( - f"\n", - ET.tostring(elem, encoding='unicode', xml_declaration=True) + ET.tostring(elem, encoding='unicode', xml_declaration=True), + "\n" ) def test_tostring_xml_declaration_cases(self): elem = ET.XML('ø') - preferredencoding = locale.getpreferredencoding() TESTCASES = [ # (expected_retval, encoding, xml_declaration) # ... xml_declaration = None @@ -992,7 +992,7 @@ class ElementTreeTest(unittest.TestCase): b"ø", 'US-ASCII', True), (b"\n" b"\xf8", 'ISO-8859-1', True), - (f"\n" + ("\n" "ø", 'unicode', True), ] @@ -1030,11 +1030,10 @@ class ElementTreeTest(unittest.TestCase): b"\n" ) - preferredencoding = locale.getpreferredencoding() stringlist = ET.tostringlist(elem, encoding='unicode', xml_declaration=True) self.assertEqual( ''.join(stringlist), - f"\n" + "\n" ) self.assertRegex(stringlist[0], r"^<\?xml version='1.0' encoding='.+'?>") self.assertEqual(['', '', ''], stringlist[1:]) @@ -3654,32 +3653,95 @@ class IOTest(unittest.TestCase): def test_write_to_filename(self): self.addCleanup(support.unlink, TESTFN) - tree = ET.ElementTree(ET.XML('''''')) + tree = ET.ElementTree(ET.XML('''\xf8''')) tree.write(TESTFN) with open(TESTFN, 'rb') as f: - self.assertEqual(f.read(), b'''''') + self.assertEqual(f.read(), b'''ø''') + + def test_write_to_filename_with_encoding(self): + self.addCleanup(support.unlink, TESTFN) + tree = ET.ElementTree(ET.XML('''\xf8''')) + tree.write(TESTFN, encoding='utf-8') + with open(TESTFN, 'rb') as f: + self.assertEqual(f.read(), b'''\xc3\xb8''') + + tree.write(TESTFN, encoding='ISO-8859-1') + with open(TESTFN, 'rb') as f: + self.assertEqual(f.read(), convlinesep( + b'''\n''' + b'''\xf8''')) + + def test_write_to_filename_as_unicode(self): + self.addCleanup(support.unlink, TESTFN) + with open(TESTFN, 'w') as f: + encoding = f.encoding + support.unlink(TESTFN) + + tree = ET.ElementTree(ET.XML('''\xf8''')) + tree.write(TESTFN, encoding='unicode') + with open(TESTFN, 'rb') as f: + data = f.read() + expected = "\xf8".encode(encoding, 'xmlcharrefreplace') + if encoding.lower() in ('utf-8', 'ascii'): + self.assertEqual(data, expected) + else: + self.assertIn(b"''')) + tree = ET.ElementTree(ET.XML('''\xf8''')) with open(TESTFN, 'w', encoding='utf-8') as f: tree.write(f, encoding='unicode') self.assertFalse(f.closed) with open(TESTFN, 'rb') as f: - self.assertEqual(f.read(), b'''''') + self.assertEqual(f.read(), b'''\xc3\xb8''') + + with open(TESTFN, 'w', encoding='ascii', errors='xmlcharrefreplace') as f: + tree.write(f, encoding='unicode') + self.assertFalse(f.closed) + with open(TESTFN, 'rb') as f: + self.assertEqual(f.read(), convlinesep( + b'''\n''' + b'''ø''')) + + with open(TESTFN, 'w', encoding='ISO-8859-1') as f: + tree.write(f, encoding='unicode') + self.assertFalse(f.closed) + with open(TESTFN, 'rb') as f: + self.assertEqual(f.read(), convlinesep( + b'''\n''' + b'''\xf8''')) def test_write_to_binary_file(self): self.addCleanup(support.unlink, TESTFN) - tree = ET.ElementTree(ET.XML('''''')) + tree = ET.ElementTree(ET.XML('''\xf8''')) with open(TESTFN, 'wb') as f: tree.write(f) self.assertFalse(f.closed) with open(TESTFN, 'rb') as f: - self.assertEqual(f.read(), b'''''') + self.assertEqual(f.read(), b'''ø''') + + def test_write_to_binary_file_with_encoding(self): + self.addCleanup(support.unlink, TESTFN) + tree = ET.ElementTree(ET.XML('''\xf8''')) + with open(TESTFN, 'wb') as f: + tree.write(f, encoding='utf-8') + self.assertFalse(f.closed) + with open(TESTFN, 'rb') as f: + self.assertEqual(f.read(), b'''\xc3\xb8''') + + with open(TESTFN, 'wb') as f: + tree.write(f, encoding='ISO-8859-1') + self.assertFalse(f.closed) + with open(TESTFN, 'rb') as f: + self.assertEqual(f.read(), + b'''\n''' + b'''\xf8''') def test_write_to_binary_file_with_bom(self): self.addCleanup(support.unlink, TESTFN) - tree = ET.ElementTree(ET.XML('''''')) + tree = ET.ElementTree(ET.XML('''\xf8''')) # test BOM writing to buffered file with open(TESTFN, 'wb') as f: tree.write(f, encoding='utf-16') @@ -3687,7 +3749,7 @@ class IOTest(unittest.TestCase): with open(TESTFN, 'rb') as f: self.assertEqual(f.read(), '''\n''' - ''''''.encode("utf-16")) + '''\xf8'''.encode("utf-16")) # test BOM writing to non-buffered file with open(TESTFN, 'wb', buffering=0) as f: tree.write(f, encoding='utf-16') @@ -3695,7 +3757,7 @@ class IOTest(unittest.TestCase): with open(TESTFN, 'rb') as f: self.assertEqual(f.read(), '''\n''' - ''''''.encode("utf-16")) + '''\xf8'''.encode("utf-16")) def test_read_from_stringio(self): tree = ET.ElementTree() @@ -3704,10 +3766,10 @@ class IOTest(unittest.TestCase): self.assertEqual(tree.getroot().tag, 'site') def test_write_to_stringio(self): - tree = ET.ElementTree(ET.XML('''''')) + tree = ET.ElementTree(ET.XML('''\xf8''')) stream = io.StringIO() tree.write(stream, encoding='unicode') - self.assertEqual(stream.getvalue(), '''''') + self.assertEqual(stream.getvalue(), '''\xf8''') def test_read_from_bytesio(self): tree = ET.ElementTree() @@ -3716,10 +3778,10 @@ class IOTest(unittest.TestCase): self.assertEqual(tree.getroot().tag, 'site') def test_write_to_bytesio(self): - tree = ET.ElementTree(ET.XML('''''')) + tree = ET.ElementTree(ET.XML('''\xf8''')) raw = io.BytesIO() tree.write(raw) - self.assertEqual(raw.getvalue(), b'''''') + self.assertEqual(raw.getvalue(), b'''ø''') class dummy: pass @@ -3733,12 +3795,12 @@ class IOTest(unittest.TestCase): self.assertEqual(tree.getroot().tag, 'site') def test_write_to_user_text_writer(self): - tree = ET.ElementTree(ET.XML('''''')) + tree = ET.ElementTree(ET.XML('''\xf8''')) stream = io.StringIO() writer = self.dummy() writer.write = stream.write tree.write(writer, encoding='unicode') - self.assertEqual(stream.getvalue(), '''''') + self.assertEqual(stream.getvalue(), '''\xf8''') def test_read_from_user_binary_reader(self): raw = io.BytesIO(b'''''') @@ -3750,12 +3812,12 @@ class IOTest(unittest.TestCase): tree = ET.ElementTree() def test_write_to_user_binary_writer(self): - tree = ET.ElementTree(ET.XML('''''')) + tree = ET.ElementTree(ET.XML('''\xf8''')) raw = io.BytesIO() writer = self.dummy() writer.write = raw.write tree.write(writer) - self.assertEqual(raw.getvalue(), b'''''') + self.assertEqual(raw.getvalue(), b'''ø''') def test_write_to_user_binary_writer_with_bom(self): tree = ET.ElementTree(ET.XML('''''')) diff --git a/Lib/threading.py b/Lib/threading.py index a3cb245a..565f868e 100644 --- a/Lib/threading.py +++ b/Lib/threading.py @@ -360,14 +360,21 @@ class Condition: """ if not self._is_owned(): raise RuntimeError("cannot notify on un-acquired lock") - all_waiters = self._waiters - waiters_to_notify = _deque(_islice(all_waiters, n)) - if not waiters_to_notify: - return - for waiter in waiters_to_notify: - waiter.release() + waiters = self._waiters + while waiters and n > 0: + waiter = waiters[0] + try: + waiter.release() + except RuntimeError: + # gh-92530: The previous call of notify() released the lock, + # but was interrupted before removing it from the queue. + # It can happen if a signal handler raises an exception, + # like CTRL+C which raises KeyboardInterrupt. + pass + else: + n -= 1 try: - all_waiters.remove(waiter) + waiters.remove(waiter) except ValueError: pass diff --git a/Lib/tkinter/__init__.py b/Lib/tkinter/__init__.py index 9049ca30..7e4f444c 100644 --- a/Lib/tkinter/__init__.py +++ b/Lib/tkinter/__init__.py @@ -2070,7 +2070,7 @@ class Wm: the bitmap if None is given. Under Windows, the DEFAULT parameter can be used to set the icon - for the widget and any descendents that don't have an icon set + for the widget and any descendants that don't have an icon set explicitly. DEFAULT can be the relative path to a .ico file (example: root.iconbitmap(default='myicon.ico') ). See Tk documentation for more information.""" @@ -2316,9 +2316,9 @@ class Tk(Misc, Wm): _default_root = None def readprofile(self, baseName, className): - """Internal function. It reads BASENAME.tcl and CLASSNAME.tcl into - the Tcl Interpreter and calls exec on the contents of BASENAME.py and - CLASSNAME.py if such a file exists in the home directory.""" + """Internal function. It reads .BASENAME.tcl and .CLASSNAME.tcl into + the Tcl Interpreter and calls exec on the contents of .BASENAME.py and + .CLASSNAME.py if such a file exists in the home directory.""" import os if 'HOME' in os.environ: home = os.environ['HOME'] else: home = os.curdir diff --git a/Lib/unittest/async_case.py b/Lib/unittest/async_case.py index a2980e79..d9c694e3 100644 --- a/Lib/unittest/async_case.py +++ b/Lib/unittest/async_case.py @@ -134,7 +134,7 @@ class IsolatedAsyncioTestCase(TestCase): task.cancel() loop.run_until_complete( - asyncio.gather(*to_cancel, loop=loop, return_exceptions=True)) + asyncio.gather(*to_cancel, return_exceptions=True)) for task in to_cancel: if task.cancelled(): @@ -148,6 +148,8 @@ class IsolatedAsyncioTestCase(TestCase): # shutdown asyncgens loop.run_until_complete(loop.shutdown_asyncgens()) finally: + # Prevent our executor environment from leaking to future tests. + loop.run_until_complete(loop.shutdown_default_executor()) asyncio.set_event_loop(None) loop.close() diff --git a/Lib/unittest/test/test_async_case.py b/Lib/unittest/test/test_async_case.py index 2b6e751f..22e2d086 100644 --- a/Lib/unittest/test/test_async_case.py +++ b/Lib/unittest/test/test_async_case.py @@ -278,6 +278,26 @@ class TestAsyncCase(unittest.TestCase): output = test.run() self.assertFalse(output.wasSuccessful()) + def test_cancellation_hanging_tasks(self): + cancelled = False + class Test(unittest.IsolatedAsyncioTestCase): + async def test_leaking_task(self): + async def coro(): + nonlocal cancelled + try: + await asyncio.sleep(1) + except asyncio.CancelledError: + cancelled = True + raise + + # Leave this running in the background + asyncio.create_task(coro()) + + test = Test("test_leaking_task") + output = test.run() + self.assertTrue(cancelled) + + if __name__ == "__main__": unittest.main() diff --git a/Lib/urllib/request.py b/Lib/urllib/request.py index 4e289fc6..2e7d01fd 100644 --- a/Lib/urllib/request.py +++ b/Lib/urllib/request.py @@ -2672,22 +2672,26 @@ elif os.name == 'nt': # Returned as Unicode but problems if not converted to ASCII proxyServer = str(winreg.QueryValueEx(internetSettings, 'ProxyServer')[0]) - if '=' in proxyServer: - # Per-protocol settings - for p in proxyServer.split(';'): - protocol, address = p.split('=', 1) - # See if address has a type:// prefix - if not re.match('(?:[^/:]+)://', address): - address = '%s://%s' % (protocol, address) - proxies[protocol] = address - else: - # Use one setting for all protocols - if proxyServer[:5] == 'http:': - proxies['http'] = proxyServer - else: - proxies['http'] = 'http://%s' % proxyServer - proxies['https'] = 'https://%s' % proxyServer - proxies['ftp'] = 'ftp://%s' % proxyServer + if '=' not in proxyServer and ';' not in proxyServer: + # Use one setting for all protocols. + proxyServer = 'http={0};https={0};ftp={0}'.format(proxyServer) + for p in proxyServer.split(';'): + protocol, address = p.split('=', 1) + # See if address has a type:// prefix + if not re.match('(?:[^/:]+)://', address): + # Add type:// prefix to address without specifying type + if protocol in ('http', 'https', 'ftp'): + # The default proxy type of Windows is HTTP + address = 'http://' + address + elif protocol == 'socks': + address = 'socks://' + address + proxies[protocol] = address + # Use SOCKS proxy for HTTP(S) protocols + if proxies.get('socks'): + # The default SOCKS proxy type of Windows is SOCKS4 + address = re.sub(r'^socks://', 'socks4://', proxies['socks']) + proxies['http'] = proxies.get('http') or address + proxies['https'] = proxies.get('https') or address internetSettings.Close() except (OSError, ValueError, TypeError): # Either registry key not found etc, or the value in an diff --git a/Lib/xml/etree/ElementPath.py b/Lib/xml/etree/ElementPath.py index 880ea7bd..493c026d 100644 --- a/Lib/xml/etree/ElementPath.py +++ b/Lib/xml/etree/ElementPath.py @@ -225,7 +225,6 @@ def prepare_parent(next, token): def prepare_predicate(next, token): # FIXME: replace with real parser!!! refs: - # http://effbot.org/zone/simple-iterator-parser.htm # http://javascript.crockford.com/tdop/tdop.html signature = [] predicate = [] diff --git a/Lib/xml/etree/ElementTree.py b/Lib/xml/etree/ElementTree.py index dae2251d..66c43c2d 100644 --- a/Lib/xml/etree/ElementTree.py +++ b/Lib/xml/etree/ElementTree.py @@ -728,16 +728,10 @@ class ElementTree: encoding = "utf-8" else: encoding = "us-ascii" - enc_lower = encoding.lower() - with _get_writer(file_or_filename, enc_lower) as write: + with _get_writer(file_or_filename, encoding) as (write, declared_encoding): if method == "xml" and (xml_declaration or (xml_declaration is None and - enc_lower not in ("utf-8", "us-ascii", "unicode"))): - declared_encoding = encoding - if enc_lower == "unicode": - # Retrieve the default encoding for the xml declaration - import locale - declared_encoding = locale.getpreferredencoding() + declared_encoding.lower() not in ("utf-8", "us-ascii"))): write("\n" % ( declared_encoding,)) if method == "text": @@ -762,19 +756,20 @@ def _get_writer(file_or_filename, encoding): write = file_or_filename.write except AttributeError: # file_or_filename is a file name - if encoding == "unicode": - file = open(file_or_filename, "w") + if encoding.lower() == "unicode": + file = open(file_or_filename, "w", + errors="xmlcharrefreplace") else: file = open(file_or_filename, "w", encoding=encoding, errors="xmlcharrefreplace") with file: - yield file.write + yield file.write, file.encoding else: # file_or_filename is a file-like object # encoding determines if it is a text or binary writer - if encoding == "unicode": + if encoding.lower() == "unicode": # use a text writer as is - yield write + yield write, getattr(file_or_filename, "encoding", None) or "utf-8" else: # wrap a binary writer with TextIOWrapper with contextlib.ExitStack() as stack: @@ -805,7 +800,7 @@ def _get_writer(file_or_filename, encoding): # Keep the original file open when the TextIOWrapper is # destroyed stack.callback(file.detach) - yield file.write + yield file.write, encoding def _namespaces(elem, default_namespace=None): # identify namespaces used in this tree diff --git a/Misc/ACKS b/Misc/ACKS index d043195a..a9f15b4f 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -1269,6 +1269,7 @@ Ethan Onstott Piet van Oostrum Tomas Oppelstrup Jason Orendorff +Yan "yyyyyyyan" Orestes Bastien Orivel orlnub123 Douglas Orr @@ -1663,6 +1664,7 @@ Anthony Starks David Steele Oliver Steele Greg Stein +Itai Steinherz Marek Stepniowski Baruch Sterin Chris Stern @@ -1840,6 +1842,7 @@ Jacob Walls Kevin Walzer Rodrigo Steinmuller Wanderley Dingyuan Wang +Jiahua Wang Ke Wang Liang-Bo Wang Greg Ward diff --git a/Misc/NEWS b/Misc/NEWS index 7d815048..55d7f5ba 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -2,6 +2,235 @@ Python News +++++++++++ +What's New in Python 3.9.13 final? +================================== + +*Release date: 2022-05-17* + +Core and Builtins +----------------- + +- gh-issue-92311: Fixed a bug where setting ``frame.f_lineno`` to jump over + a list comprehension could misbehave or crash. + +- gh-issue-92112: Fix crash triggered by an evil custom ``mro()`` on a + metaclass. + +- gh-issue-92036: Fix a crash in subinterpreters related to the garbage + collector. When a subinterpreter is deleted, untrack all objects tracked + by its GC. To prevent a crash in deallocator functions expecting objects + to be tracked by the GC, leak a strong reference to these objects on + purpose, so they are never deleted and their deallocator functions are not + called. Patch by Victor Stinner. + +- gh-issue-91421: Fix a potential integer overflow in _Py_DecodeUTF8Ex. + +- bpo-46775: Some Windows system error codes(>= 10000) are now mapped into + the correct errno and may now raise a subclass of :exc:`OSError`. Patch by + Dong-hee Na. + +- bpo-46962: Classes and functions that unconditionally declared their + docstrings ignoring the `--without-doc-strings` compilation flag no longer + do so. + + The classes affected are :class:`pickle.PickleBuffer`, + :class:`testcapi.RecursingInfinitelyError`, and + :class:`types.GenericAlias`. + + The functions affected are 24 methods in :mod:`ctypes`. + + Patch by Oleg Iarygin. + +- bpo-36819: Fix crashes in built-in encoders with error handlers that + return position less or equal than the starting position of non-encodable + characters. + +Library +------- + +- gh-issue-91581: :meth:`~datetime.datetime.utcfromtimestamp` no longer + attempts to resolve ``fold`` in the pure Python implementation, since the + fold is never 1 in UTC. In addition to being slightly faster in the common + case, this also prevents some errors when the timestamp is close to + :attr:`datetime.min `. Patch by Paul Ganssle. + +- gh-issue-92530: Fix an issue that occurred after interrupting + :func:`threading.Condition.notify`. + +- gh-issue-92049: Forbid pickling constants ``re._constants.SUCCESS`` etc. + Previously, pickling did not fail, but the result could not be unpickled. + +- bpo-47029: Always close the read end of the pipe used by + :class:`multiprocessing.Queue` *after* the last write of buffered data to + the write end of the pipe to avoid :exc:`BrokenPipeError` at garbage + collection and at :meth:`multiprocessing.Queue.close` calls. Patch by Géry + Ogam. + +- gh-issue-91910: Add missing f prefix to f-strings in error messages from + the :mod:`multiprocessing` and :mod:`asyncio` modules. + +- gh-issue-91810: :class:`~xml.etree.ElementTree.ElementTree` method + :meth:`~xml.etree.ElementTree.ElementTree.write` and function + :func:`~xml.etree.ElementTree.tostring` now use the text file's encoding + ("UTF-8" if not available) instead of locale encoding in XML declaration + when ``encoding="unicode"`` is specified. + +- gh-issue-91832: Add ``required`` attribute to :class:`argparse.Action` + repr output. + +- gh-issue-91734: Fix OSS audio support on Solaris. + +- gh-issue-91700: Compilation of regular expression containing a conditional + expression ``(?(group)...)`` now raises an appropriate :exc:`re.error` if + the group number refers to not defined group. Previously an internal + RuntimeError was raised. + +- gh-issue-91676: Fix :class:`unittest.IsolatedAsyncioTestCase` to shutdown + the per test event loop executor before returning from its ``run`` method + so that a not yet stopped or garbage collected executor state does not + persist beyond the test. + +- gh-issue-90568: Parsing ``\N`` escapes of Unicode Named Character + Sequences in a :mod:`regular expression ` raises now :exc:`re.error` + instead of ``TypeError``. + +- gh-issue-91595: Fix the comparison of character and integer inside + :func:`Tools.gdb.libpython.write_repr`. Patch by Yu Liu. + +- gh-issue-90622: Worker processes for + :class:`concurrent.futures.ProcessPoolExecutor` are no longer spawned on + demand (a feature added in 3.9) when the multiprocessing context start + method is ``"fork"`` as that can lead to deadlocks in the child processes + due to a fork happening while threads are running. + +- gh-issue-91575: Update case-insensitive matching in the :mod:`re` module + to the latest Unicode version. + +- gh-issue-91581: Remove an unhandled error case in the C implementation of + calls to :meth:`datetime.fromtimestamp ` + with no time zone (i.e. getting a local time from an epoch timestamp). + This should have no user-facing effect other than giving a possibly more + accurate error message when called with timestamps that fall on + 10000-01-01 in the local time. Patch by Paul Ganssle. + +- bpo-34480: Fix a bug where :mod:`_markupbase` raised an + :exc:`UnboundLocalError` when an invalid keyword was found in marked + section. Patch by Marek Suscak. + +- bpo-27929: Fix :meth:`asyncio.loop.sock_connect` to only resolve names for + :const:`socket.AF_INET` or :const:`socket.AF_INET6` families. Resolution + may not make sense for other families, like :const:`socket.AF_BLUETOOTH` + and :const:`socket.AF_UNIX`. + +- bpo-43323: Fix errors in the :mod:`email` module if the charset itself + contains undecodable/unencodable characters. + +- bpo-46787: Fix :class:`concurrent.futures.ProcessPoolExecutor` exception + memory leak + +- bpo-46415: Fix ipaddress.ip_{address,interface,network} raising TypeError + instead of ValueError if given invalid tuple as address parameter. + +- bpo-44911: :class:`~unittest.IsolatedAsyncioTestCase` will no longer throw + an exception while cancelling leaked tasks. Patch by Bar Harel. + +- bpo-44493: Add missing terminated NUL in sockaddr_un's length + + This was potentially observable when using non-abstract AF_UNIX datagram + sockets to processes written in another programming language. + +- bpo-42627: Fix incorrect parsing of Windows registry proxy settings + +- bpo-36073: Raise :exc:`~sqlite3.ProgrammingError` instead of segfaulting + on recursive usage of cursors in :mod:`sqlite3` converters. Patch by + Sergey Fedoseev. + +Documentation +------------- + +- gh-issue-91888: Add a new ``gh`` role to the documentation to link to + GitHub issues. + +- gh-issue-91783: Document security issues concerning the use of the + function :meth:`shutil.unpack_archive` + +- gh-issue-91547: Remove "Undocumented modules" page. + +- bpo-44347: Clarify the meaning of *dirs_exist_ok*, a kwarg of + :func:`shutil.copytree`. + +- bpo-38668: Update the introduction to documentation for :mod:`os.path` to + remove warnings that became irrelevant after the implementations of + :pep:`383` and :pep:`529`. + +- bpo-47138: Pin Jinja to a version compatible with Sphinx version 2.4.4. + +- bpo-46962: All docstrings in code snippets are now wrapped into + :func:`PyDoc_STR` to follow the guideline of `PEP 7's Documentation + Strings paragraph + `_. Patch + by Oleg Iarygin. + +- bpo-26792: Improve the docstrings of :func:`runpy.run_module` and + :func:`runpy.run_path`. Original patch by Andrew Brezovsky. + +- bpo-45790: Adjust inaccurate phrasing in + :doc:`../extending/newtypes_tutorial` about the ``ob_base`` field and the + macros used to access its contents. + +- bpo-42340: Document that in some circumstances :exc:`KeyboardInterrupt` + may cause the code to enter an inconsistent state. Provided a sample + workaround to avoid it if needed. + +- bpo-41233: Link the errnos referenced in ``Doc/library/exceptions.rst`` to + their respective section in ``Doc/library/errno.rst``, and vice versa. + Previously this was only done for EINTR and InterruptedError. Patch by Yan + "yyyyyyyan" Orestes. + +- bpo-38056: Overhaul the :ref:`error-handlers` documentation in + :mod:`codecs`. + +- bpo-13553: Document tkinter.Tk args. + +Tests +----- + +- gh-issue-91607: Fix ``test_concurrent_futures`` to test the correct + multiprocessing start method context in several cases where the test logic + mixed this up. + +- bpo-47205: Skip test for :func:`~os.sched_getaffinity` and + :func:`~os.sched_setaffinity` error case on FreeBSD. + +- bpo-29890: Add tests for :class:`ipaddress.IPv4Interface` and + :class:`ipaddress.IPv6Interface` construction with tuple arguments. + Original patch and tests by louisom. + +Build +----- + +- bpo-47103: Windows ``PGInstrument`` builds now copy a required DLL into + the output directory, making it easier to run the profile stage of a PGO + build. + +Windows +------- + +- bpo-47194: Update ``zlib`` to v1.2.12 to resolve CVE-2018-25032. + +- bpo-46785: Fix race condition between :func:`os.stat` and unlinking a file + on Windows, by using errors codes returned by ``FindFirstFileW()`` when + appropriate in ``win32_xstat_impl``. + +- bpo-40859: Update Windows build to use xz-5.2.5 + +Tools/Demos +----------- + +- gh-issue-91583: Fix regression in the code generated by Argument Clinic + for functions with the ``defining_class`` parameter. + + What's New in Python 3.9.12 final? ================================== @@ -6222,7 +6451,7 @@ Library - bpo-38417: Added support for setting the umask in the child process to the subprocess module on POSIX systems. -- bpo-38449: Revert GH-15522, which introduces a regression in +- bpo-38449: Revert PR 15522, which introduces a regression in :meth:`mimetypes.guess_type` due to improper handling of filenames as urls. @@ -11134,7 +11363,7 @@ Library the decoding. Based on patch by c-fos. - bpo-33604: Remove HMAC default to md5 marked for removal in 3.8 (removal - originally planned in 3.6, bump to 3.8 in gh-7062). + originally planned in 3.6, bump to 3.8 in PR 7062). - bpo-33582: Emit a deprecation warning for inspect.formatargspec @@ -14291,7 +14520,7 @@ Library when getting the file size. Fixed hang of all threads with inaccessible NFS server. Patch by Nir Soffer. -- bpo-321010: Add :attr:`sys.flags.dev_mode` flag +- bpo-32101: Add :attr:`sys.flags.dev_mode` flag - bpo-32154: The ``asyncio.windows_utils.socketpair()`` function has been removed: use directly :func:`socket.socketpair` which is available on all @@ -18737,6 +18966,13 @@ What's New in Python 3.6.2 release candidate 1? *Release date: 2017-06-17* +Security +-------- + +- bpo-29591: Update expat copy from 2.1.1 to 2.2.0 to get fixes of + CVE-2016-0718 and CVE-2016-4472. See + https://sourceforge.net/p/expat/bugs/537/ for more information. + Core and Builtins ----------------- @@ -18812,16 +19048,6 @@ Library - bpo-30605: re.compile() no longer raises a BytesWarning when compiling a bytes instance with misplaced inline modifier. Patch by Roy Williams. -Security --------- - -- bpo-29591: Update expat copy from 2.1.1 to 2.2.0 to get fixes of - CVE-2016-0718 and CVE-2016-4472. See - https://sourceforge.net/p/expat/bugs/537/ for more information. - -Library -------- - - bpo-24484: Avoid race condition in multiprocessing cleanup (#2159) - bpo-28994: The traceback no longer displayed for SystemExit raised in a @@ -20784,6 +21010,15 @@ What's New in Python 3.6.0 alpha 3? *Release date: 2016-07-11* +Security +-------- + +- bpo-27278: Fix os.urandom() implementation using getrandom() on Linux. + Truncate size to INT_MAX and loop until we collected enough random bytes, + instead of casting a directly Py_ssize_t to int. + +- bpo-22636: Avoid shell injection problems with ctypes.util.find_library(). + Core and Builtins ----------------- @@ -20878,16 +21113,6 @@ Library let the new chained one through. This avoids the :pep:`479` bug described in issue25782. -Security --------- - -- bpo-27278: Fix os.urandom() implementation using getrandom() on Linux. - Truncate size to INT_MAX and loop until we collected enough random bytes, - instead of casting a directly Py_ssize_t to int. - -Library -------- - - bpo-16864: sqlite3.Cursor.lastrowid now supports REPLACE statement. Initial patch by Alex LordThorsen. @@ -20897,14 +21122,6 @@ Library - bpo-8637: Honor a pager set by the env var MANPAGER (in preference to one set by the env var PAGER). -Security --------- - -- bpo-22636: Avoid shell injection problems with ctypes.util.find_library(). - -Library -------- - - bpo-16182: Fix various functions in the "readline" module to use the locale encoding, and fix get_begidx() and get_endidx() to return code point indexes. @@ -21004,6 +21221,18 @@ What's New in Python 3.6.0 alpha 2? *Release date: 2016-06-13* +Security +-------- + +- bpo-26556: Update expat to 2.1.1, fixes CVE-2015-1283. + +- Fix TLS stripping vulnerability in smtplib, CVE-2016-0772. Reported by + Team Oststrom. + +- bpo-26839: On Linux, :func:`os.urandom` now calls ``getrandom()`` with + ``GRND_NONBLOCK`` to fall back on reading ``/dev/urandom`` if the urandom + entropy pool is not initialized yet. Patch written by Colm Buckley. + Core and Builtins ----------------- @@ -21062,17 +21291,6 @@ Library - bpo-20508: Improve exception message of IPv{4,6}Network.__getitem__. Patch by Gareth Rees. -Security --------- - -- bpo-26556: Update expat to 2.1.1, fixes CVE-2015-1283. - -- Fix TLS stripping vulnerability in smtplib, CVE-2016-0772. Reported by - Team Oststrom. - -Library -------- - - bpo-21386: Implement missing IPv4Address.is_global property. It was documented since 07a5610bae9d. Initial patch by Roger Luethi. @@ -21113,16 +21331,6 @@ Library - bpo-21313: Fix the "platform" module to tolerate when sys.version contains truncated build information. -Security --------- - -- bpo-26839: On Linux, :func:`os.urandom` now calls ``getrandom()`` with - ``GRND_NONBLOCK`` to fall back on reading ``/dev/urandom`` if the urandom - entropy pool is not initialized yet. Patch written by Colm Buckley. - -Library -------- - - bpo-23883: Added missing APIs to __all__ to match the documented APIs for the following modules: cgi, mailbox, mimetypes, plistlib and smtpd. Patches by Jacek Kołodziej. @@ -21272,6 +21480,9 @@ Windows launcher ``py.exe`` no longer prefers an installed Python 2 version over Python 3 by default when used interactively. +- bpo-17500: Remove unused and outdated icons. (See also: + https://github.com/python/pythondotorg/issues/945) + Build ----- @@ -21281,12 +21492,6 @@ Build - bpo-26930: Update OS X 10.5+ 32-bit-only installer to build and link with OpenSSL 1.0.2h. -Windows -------- - -- bpo-17500: Remove unused and outdated icons. (See also: - https://github.com/python/pythondotorg/issues/945) - C API ----- @@ -21307,6 +21512,19 @@ What's New in Python 3.6.0 alpha 1? *Release date: 2016-05-16* +Security +-------- + +- bpo-26657: Fix directory traversal vulnerability with http.server on + Windows. This fixes a regression that was introduced in 3.3.4rc1 and + 3.4.0rc1. Based on patch by Philipp Hagemeister. + +- bpo-26313: ssl.py _load_windows_store_certs fails if windows cert store is + empty. Patch by Baji. + +- bpo-25939: On Windows open the cert store readonly in + ssl.enum_certificates. + Core and Builtins ----------------- @@ -21708,16 +21926,6 @@ Library - bpo-24838: tarfile's ustar and gnu formats now correctly calculate name and link field limits for multibyte character encodings like utf-8. -Security --------- - -- bpo-26657: Fix directory traversal vulnerability with http.server on - Windows. This fixes a regression that was introduced in 3.3.4rc1 and - 3.4.0rc1. Based on patch by Philipp Hagemeister. - -Library -------- - - bpo-26717: Stop encoding Latin-1-ized WSGI paths with UTF-8. Patch by Anthony Sottile. @@ -21819,15 +22027,6 @@ Library :class:`warnings.WarningMessage`. Add warnings._showwarnmsg() which uses tracemalloc to get the traceback where source object was allocated. -Security --------- - -- bpo-26313: ssl.py _load_windows_store_certs fails if windows cert store is - empty. Patch by Baji. - -Library -------- - - bpo-26569: Fix :func:`pyclbr.readmodule` and :func:`pyclbr.readmodule_ex` to support importing packages. @@ -21909,15 +22108,6 @@ Library trigger the handle_error() method, and will now to stop a single-threaded server. -Security --------- - -- bpo-25939: On Windows open the cert store readonly in - ssl.enum_certificates. - -Library -------- - - bpo-25995: os.walk() no longer uses FDs proportional to the tree depth. - bpo-25994: Added the close() method and the support of the context manager @@ -23094,6 +23284,15 @@ What's New in Python 3.5.3 release candidate 1? *Release date: 2017-01-02* +Security +-------- + +- bpo-27278: Fix os.urandom() implementation using getrandom() on Linux. + Truncate size to INT_MAX and loop until we collected enough random bytes, + instead of casting a directly Py_ssize_t to int. + +- bpo-22636: Avoid shell injection problems with ctypes.util.find_library(). + Core and Builtins ----------------- @@ -23532,27 +23731,9 @@ Library let the new chained one through. This avoids the :pep:`479` bug described in issue25782. -Security --------- - -- bpo-27278: Fix os.urandom() implementation using getrandom() on Linux. - Truncate size to INT_MAX and loop until we collected enough random bytes, - instead of casting a directly Py_ssize_t to int. - -Library -------- - - bpo-26386: Fixed ttk.TreeView selection operations with item id's containing spaces. -Security --------- - -- bpo-22636: Avoid shell injection problems with ctypes.util.find_library(). - -Library -------- - - bpo-16182: Fix various functions in the "readline" module to use the locale encoding, and fix get_begidx() and get_endidx() to return code point indexes. @@ -23806,6 +23987,28 @@ What's New in Python 3.5.2 release candidate 1? *Release date: 2016-06-12* +Security +-------- + +- bpo-26556: Update expat to 2.1.1, fixes CVE-2015-1283. + +- Fix TLS stripping vulnerability in smtplib, CVE-2016-0772. Reported by + Team Oststrom + +- bpo-26839: On Linux, :func:`os.urandom` now calls ``getrandom()`` with + ``GRND_NONBLOCK`` to fall back on reading ``/dev/urandom`` if the urandom + entropy pool is not initialized yet. Patch written by Colm Buckley. + +- bpo-26657: Fix directory traversal vulnerability with http.server on + Windows. This fixes a regression that was introduced in 3.3.4rc1 and + 3.4.0rc1. Based on patch by Philipp Hagemeister. + +- bpo-26313: ssl.py _load_windows_store_certs fails if windows cert store is + empty. Patch by Baji. + +- bpo-25939: On Windows open the cert store readonly in + ssl.enum_certificates. + Core and Builtins ----------------- @@ -23936,14 +24139,6 @@ Core and Builtins iterator should be returned directly. Doing the former will trigger a PendingDeprecationWarning. -Security --------- - -- bpo-26556: Update expat to 2.1.1, fixes CVE-2015-1283. - -- Fix TLS stripping vulnerability in smtplib, CVE-2016-0772. Reported by - Team Oststrom - Library ------- @@ -23969,16 +24164,6 @@ Library - bpo-21313: Fix the "platform" module to tolerate when sys.version contains truncated build information. -Security --------- - -- bpo-26839: On Linux, :func:`os.urandom` now calls ``getrandom()`` with - ``GRND_NONBLOCK`` to fall back on reading ``/dev/urandom`` if the urandom - entropy pool is not initialized yet. Patch written by Colm Buckley. - -Library -------- - - bpo-27164: In the zlib module, allow decompressing raw Deflate streams with a predefined zdict. Based on patch by Xiang Zhang. @@ -24081,16 +24266,6 @@ Library - bpo-24838: tarfile's ustar and gnu formats now correctly calculate name and link field limits for multibyte character encodings like utf-8. -Security --------- - -- bpo-26657: Fix directory traversal vulnerability with http.server on - Windows. This fixes a regression that was introduced in 3.3.4rc1 and - 3.4.0rc1. Based on patch by Philipp Hagemeister. - -Library -------- - - bpo-26717: Stop encoding Latin-1-ized WSGI paths with UTF-8. Patch by Anthony Sottile. @@ -24136,15 +24311,6 @@ Library - bpo-26560: Avoid potential ValueError in BaseHandler.start_response. Initial patch by Peter Inglesby. -Security --------- - -- bpo-26313: ssl.py _load_windows_store_certs fails if windows cert store is - empty. Patch by Baji. - -Library -------- - - bpo-26569: Fix :func:`pyclbr.readmodule` and :func:`pyclbr.readmodule_ex` to support importing packages. @@ -24205,15 +24371,6 @@ Library the connected socket) when verify_request() returns false. Patch by Aviv Palivoda. -Security --------- - -- bpo-25939: On Windows open the cert store readonly in - ssl.enum_certificates. - -Library -------- - - bpo-25995: os.walk() no longer uses FDs proportional to the tree depth. - bpo-26117: The os.scandir() iterator now closes file descriptor not only @@ -24535,6 +24692,9 @@ Windows - bpo-26065: Excludes venv from library when generating embeddable distro. +- bpo-17500: Remove unused and outdated icons. (See also: + https://github.com/python/pythondotorg/issues/945) + Tools/Demos ----------- @@ -24551,12 +24711,6 @@ Tools/Demos - bpo-26316: Fix variable name typo in Argument Clinic. -Windows -------- - -- bpo-17500: Remove unused and outdated icons. (See also: - https://github.com/python/pythondotorg/issues/945) - What's New in Python 3.5.1 final? ================================= diff --git a/Modules/_ctypes/_ctypes.c b/Modules/_ctypes/_ctypes.c index ceae67eb..0ffc8858 100644 --- a/Modules/_ctypes/_ctypes.c +++ b/Modules/_ctypes/_ctypes.c @@ -181,7 +181,7 @@ static PyTypeObject DictRemover_Type = { 0, /* tp_as_buffer */ /* XXX should participate in GC? */ Py_TPFLAGS_DEFAULT, /* tp_flags */ - "deletes a key from a dictionary", /* tp_doc */ + PyDoc_STR("deletes a key from a dictionary"), /* tp_doc */ 0, /* tp_traverse */ 0, /* tp_clear */ 0, /* tp_richcompare */ @@ -563,8 +563,8 @@ UnionType_new(PyTypeObject *type, PyObject *args, PyObject *kwds) return StructUnionType_new(type, args, kwds, 0); } -static const char from_address_doc[] = -"C.from_address(integer) -> C instance\naccess a C instance at the specified address"; +PyDoc_STRVAR(from_address_doc, +"C.from_address(integer) -> C instance\naccess a C instance at the specified address"); static PyObject * CDataType_from_address(PyObject *type, PyObject *value) @@ -581,8 +581,8 @@ CDataType_from_address(PyObject *type, PyObject *value) return PyCData_AtAddress(type, buf); } -static const char from_buffer_doc[] = -"C.from_buffer(object, offset=0) -> C instance\ncreate a C instance from a writeable buffer"; +PyDoc_STRVAR(from_buffer_doc, +"C.from_buffer(object, offset=0) -> C instance\ncreate a C instance from a writeable buffer"); static int KeepRef(CDataObject *target, Py_ssize_t index, PyObject *keep); @@ -661,8 +661,8 @@ CDataType_from_buffer(PyObject *type, PyObject *args) return result; } -static const char from_buffer_copy_doc[] = -"C.from_buffer_copy(object, offset=0) -> C instance\ncreate a C instance from a readable buffer"; +PyDoc_STRVAR(from_buffer_copy_doc, +"C.from_buffer_copy(object, offset=0) -> C instance\ncreate a C instance from a readable buffer"); static PyObject * GenericPyCData_new(PyTypeObject *type, PyObject *args, PyObject *kwds); @@ -712,8 +712,8 @@ CDataType_from_buffer_copy(PyObject *type, PyObject *args) return result; } -static const char in_dll_doc[] = -"C.in_dll(dll, name) -> C instance\naccess a C instance in a dll"; +PyDoc_STRVAR(in_dll_doc, +"C.in_dll(dll, name) -> C instance\naccess a C instance in a dll"); static PyObject * CDataType_in_dll(PyObject *type, PyObject *args) @@ -774,8 +774,8 @@ CDataType_in_dll(PyObject *type, PyObject *args) return PyCData_AtAddress(type, address); } -static const char from_param_doc[] = -"Convert a Python object into a function call parameter."; +PyDoc_STRVAR(from_param_doc, +"Convert a Python object into a function call parameter."); static PyObject * CDataType_from_param(PyObject *type, PyObject *value) @@ -929,7 +929,7 @@ PyTypeObject PyCStructType_Type = { PyCStructType_setattro, /* tp_setattro */ 0, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */ - "metatype for the CData Objects", /* tp_doc */ + PyDoc_STR("metatype for the CData Objects"), /* tp_doc */ (traverseproc)CDataType_traverse, /* tp_traverse */ (inquiry)CDataType_clear, /* tp_clear */ 0, /* tp_richcompare */ @@ -971,7 +971,7 @@ static PyTypeObject UnionType_Type = { UnionType_setattro, /* tp_setattro */ 0, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */ - "metatype for the CData Objects", /* tp_doc */ + PyDoc_STR("metatype for the CData Objects"), /* tp_doc */ (traverseproc)CDataType_traverse, /* tp_traverse */ (inquiry)CDataType_clear, /* tp_clear */ 0, /* tp_richcompare */ @@ -1229,7 +1229,7 @@ PyTypeObject PyCPointerType_Type = { 0, /* tp_setattro */ 0, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */ - "metatype for the Pointer Objects", /* tp_doc */ + PyDoc_STR("metatype for the Pointer Objects"), /* tp_doc */ (traverseproc)CDataType_traverse, /* tp_traverse */ (inquiry)CDataType_clear, /* tp_clear */ 0, /* tp_richcompare */ @@ -1651,7 +1651,7 @@ PyTypeObject PyCArrayType_Type = { 0, /* tp_setattro */ 0, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */ - "metatype for the Array Objects", /* tp_doc */ + PyDoc_STR("metatype for the Array Objects"), /* tp_doc */ 0, /* tp_traverse */ 0, /* tp_clear */ 0, /* tp_richcompare */ @@ -2345,7 +2345,7 @@ PyTypeObject PyCSimpleType_Type = { 0, /* tp_setattro */ 0, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */ - "metatype for the PyCSimpleType Objects", /* tp_doc */ + PyDoc_STR("metatype for the PyCSimpleType Objects"), /* tp_doc */ 0, /* tp_traverse */ 0, /* tp_clear */ 0, /* tp_richcompare */ @@ -2627,7 +2627,7 @@ PyTypeObject PyCFuncPtrType_Type = { 0, /* tp_setattro */ 0, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */ - "metatype for C function pointers", /* tp_doc */ + PyDoc_STR("metatype for C function pointers"), /* tp_doc */ (traverseproc)CDataType_traverse, /* tp_traverse */ (inquiry)CDataType_clear, /* tp_clear */ 0, /* tp_richcompare */ @@ -2932,7 +2932,7 @@ PyTypeObject PyCData_Type = { 0, /* tp_setattro */ &PyCData_as_buffer, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */ - "XXX to be provided", /* tp_doc */ + PyDoc_STR("XXX to be provided"), /* tp_doc */ (traverseproc)PyCData_traverse, /* tp_traverse */ (inquiry)PyCData_clear, /* tp_clear */ 0, /* tp_richcompare */ @@ -4327,7 +4327,7 @@ PyTypeObject PyCFuncPtr_Type = { 0, /* tp_setattro */ &PyCData_as_buffer, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */ - "Function Pointer", /* tp_doc */ + PyDoc_STR("Function Pointer"), /* tp_doc */ (traverseproc)PyCFuncPtr_traverse, /* tp_traverse */ (inquiry)PyCFuncPtr_clear, /* tp_clear */ 0, /* tp_richcompare */ @@ -4481,7 +4481,7 @@ static PyTypeObject Struct_Type = { 0, /* tp_setattro */ &PyCData_as_buffer, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */ - "Structure base class", /* tp_doc */ + PyDoc_STR("Structure base class"), /* tp_doc */ (traverseproc)PyCData_traverse, /* tp_traverse */ (inquiry)PyCData_clear, /* tp_clear */ 0, /* tp_richcompare */ @@ -4523,7 +4523,7 @@ static PyTypeObject Union_Type = { 0, /* tp_setattro */ &PyCData_as_buffer, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */ - "Union base class", /* tp_doc */ + PyDoc_STR("Union base class"), /* tp_doc */ (traverseproc)PyCData_traverse, /* tp_traverse */ (inquiry)PyCData_clear, /* tp_clear */ 0, /* tp_richcompare */ @@ -4845,7 +4845,7 @@ PyTypeObject PyCArray_Type = { 0, /* tp_setattro */ &PyCData_as_buffer, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */ - "XXX to be provided", /* tp_doc */ + PyDoc_STR("XXX to be provided"), /* tp_doc */ (traverseproc)PyCData_traverse, /* tp_traverse */ (inquiry)PyCData_clear, /* tp_clear */ 0, /* tp_richcompare */ @@ -5064,7 +5064,7 @@ static PyTypeObject Simple_Type = { 0, /* tp_setattro */ &PyCData_as_buffer, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */ - "XXX to be provided", /* tp_doc */ + PyDoc_STR("XXX to be provided"), /* tp_doc */ (traverseproc)PyCData_traverse, /* tp_traverse */ (inquiry)PyCData_clear, /* tp_clear */ 0, /* tp_richcompare */ @@ -5448,7 +5448,7 @@ PyTypeObject PyCPointer_Type = { 0, /* tp_setattro */ &PyCData_as_buffer, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */ - "XXX to be provided", /* tp_doc */ + PyDoc_STR("XXX to be provided"), /* tp_doc */ (traverseproc)PyCData_traverse, /* tp_traverse */ (inquiry)PyCData_clear, /* tp_clear */ 0, /* tp_richcompare */ @@ -5475,12 +5475,12 @@ PyTypeObject PyCPointer_Type = { * Module initialization. */ -static const char module_docs[] = -"Create and manipulate C compatible data types in Python."; +PyDoc_STRVAR(module_docs, +"Create and manipulate C compatible data types in Python."); #ifdef MS_WIN32 -static const char comerror_doc[] = "Raised when a COM method call failed."; +PyDoc_STRVAR(comerror_doc, "Raised when a COM method call failed."); int comerror_init(PyObject *self, PyObject *args, PyObject *kwds) diff --git a/Modules/_ctypes/callbacks.c b/Modules/_ctypes/callbacks.c index e6e10182..dbe6f29f 100644 --- a/Modules/_ctypes/callbacks.c +++ b/Modules/_ctypes/callbacks.c @@ -65,7 +65,7 @@ PyTypeObject PyCThunk_Type = { 0, /* tp_setattro */ 0, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC, /* tp_flags */ - "CThunkObject", /* tp_doc */ + PyDoc_STR("CThunkObject"), /* tp_doc */ CThunkObject_traverse, /* tp_traverse */ CThunkObject_clear, /* tp_clear */ 0, /* tp_richcompare */ diff --git a/Modules/_ctypes/callproc.c b/Modules/_ctypes/callproc.c index 9aff890a..b83f7364 100644 --- a/Modules/_ctypes/callproc.c +++ b/Modules/_ctypes/callproc.c @@ -1316,11 +1316,11 @@ _parse_voidp(PyObject *obj, void **address) #ifdef MS_WIN32 -static const char format_error_doc[] = +PyDoc_STRVAR(format_error_doc, "FormatError([integer]) -> string\n\ \n\ Convert a win32 error code into a string. If the error code is not\n\ -given, the return value of a call to GetLastError() is used.\n"; +given, the return value of a call to GetLastError() is used.\n"); static PyObject *format_error(PyObject *self, PyObject *args) { PyObject *result; @@ -1340,13 +1340,13 @@ static PyObject *format_error(PyObject *self, PyObject *args) return result; } -static const char load_library_doc[] = +PyDoc_STRVAR(load_library_doc, "LoadLibrary(name, load_flags) -> handle\n\ \n\ Load an executable (usually a DLL), and return a handle to it.\n\ The handle may be used to locate exported functions in this\n\ module. load_flags are as defined for LoadLibraryEx in the\n\ -Windows API.\n"; +Windows API.\n"); static PyObject *load_library(PyObject *self, PyObject *args) { const WCHAR *name; @@ -1394,10 +1394,10 @@ _Py_COMP_DIAG_POP #endif } -static const char free_library_doc[] = +PyDoc_STRVAR(free_library_doc, "FreeLibrary(handle) -> void\n\ \n\ -Free the handle of an executable previously loaded by LoadLibrary.\n"; +Free the handle of an executable previously loaded by LoadLibrary.\n"); static PyObject *free_library(PyObject *self, PyObject *args) { void *hMod; @@ -1417,8 +1417,8 @@ static PyObject *free_library(PyObject *self, PyObject *args) Py_RETURN_NONE; } -static const char copy_com_pointer_doc[] = -"CopyComPointer(src, dst) -> HRESULT value\n"; +PyDoc_STRVAR(copy_com_pointer_doc, +"CopyComPointer(src, dst) -> HRESULT value\n"); static PyObject * copy_com_pointer(PyObject *self, PyObject *args) @@ -1656,10 +1656,10 @@ call_cdeclfunction(PyObject *self, PyObject *args) /***************************************************************** * functions */ -static const char sizeof_doc[] = +PyDoc_STRVAR(sizeof_doc, "sizeof(C type) -> integer\n" "sizeof(C instance) -> integer\n" -"Return the size in bytes of a C instance"; +"Return the size in bytes of a C instance"); static PyObject * sizeof_func(PyObject *self, PyObject *obj) @@ -1677,10 +1677,10 @@ sizeof_func(PyObject *self, PyObject *obj) return NULL; } -static const char alignment_doc[] = +PyDoc_STRVAR(alignment_doc, "alignment(C type) -> integer\n" "alignment(C instance) -> integer\n" -"Return the alignment requirements of a C instance"; +"Return the alignment requirements of a C instance"); static PyObject * align_func(PyObject *self, PyObject *obj) @@ -1700,10 +1700,10 @@ align_func(PyObject *self, PyObject *obj) return NULL; } -static const char byref_doc[] = +PyDoc_STRVAR(byref_doc, "byref(C instance[, offset=0]) -> byref-object\n" "Return a pointer lookalike to a C instance, only usable\n" -"as function argument"; +"as function argument"); /* * We must return something which can be converted to a parameter, @@ -1744,9 +1744,9 @@ byref(PyObject *self, PyObject *args) return (PyObject *)parg; } -static const char addressof_doc[] = +PyDoc_STRVAR(addressof_doc, "addressof(C instance) -> integer\n" -"Return the address of the C instance internal buffer"; +"Return the address of the C instance internal buffer"); static PyObject * addressof(PyObject *self, PyObject *obj) diff --git a/Modules/_ctypes/cfield.c b/Modules/_ctypes/cfield.c index 06b98a6d..8582af9c 100644 --- a/Modules/_ctypes/cfield.c +++ b/Modules/_ctypes/cfield.c @@ -320,7 +320,7 @@ PyTypeObject PyCField_Type = { 0, /* tp_setattro */ 0, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC, /* tp_flags */ - "Structure/Union member", /* tp_doc */ + PyDoc_STR("Structure/Union member"), /* tp_doc */ (traverseproc)PyCField_traverse, /* tp_traverse */ (inquiry)PyCField_clear, /* tp_clear */ 0, /* tp_richcompare */ diff --git a/Modules/_datetimemodule.c b/Modules/_datetimemodule.c index 96023754..51f363d8 100644 --- a/Modules/_datetimemodule.c +++ b/Modules/_datetimemodule.c @@ -5013,6 +5013,10 @@ datetime_from_timet_and_us(PyObject *cls, TM_FUNC f, time_t timet, int us, result_seconds = utc_to_seconds(year, month, day, hour, minute, second); + if (result_seconds == -1 && PyErr_Occurred()) { + return NULL; + } + /* Probe max_fold_seconds to detect a fold. */ probe_seconds = local(epoch + timet - max_fold_seconds); if (probe_seconds == -1) diff --git a/Modules/_sqlite/cursor.c b/Modules/_sqlite/cursor.c index e2635e18..5c83eef4 100644 --- a/Modules/_sqlite/cursor.c +++ b/Modules/_sqlite/cursor.c @@ -27,10 +27,25 @@ PyObject* pysqlite_cursor_iternext(pysqlite_Cursor* self); +static inline int +check_cursor_locked(pysqlite_Cursor *cur) +{ + if (cur->locked) { + PyErr_SetString(pysqlite_ProgrammingError, + "Recursive use of cursors not allowed."); + return 0; + } + return 1; +} + static const char errmsg_fetch_across_rollback[] = "Cursor needed to be reset because of commit/rollback and can no longer be fetched from."; static int pysqlite_cursor_init(pysqlite_Cursor* self, PyObject* args, PyObject* kwargs) { + if (!check_cursor_locked(self)) { + return -1; + } + pysqlite_Connection* connection; if (!PyArg_ParseTuple(args, "O!", &pysqlite_ConnectionType, &connection)) @@ -357,12 +372,9 @@ static int check_cursor(pysqlite_Cursor* cur) return 0; } - if (cur->locked) { - PyErr_SetString(pysqlite_ProgrammingError, "Recursive use of cursors not allowed."); - return 0; - } - - return pysqlite_check_thread(cur->connection) && pysqlite_check_connection(cur->connection); + return (pysqlite_check_thread(cur->connection) + && pysqlite_check_connection(cur->connection) + && check_cursor_locked(cur)); } static PyObject * @@ -750,27 +762,29 @@ PyObject* pysqlite_cursor_iternext(pysqlite_Cursor *self) if (self->statement) { rc = pysqlite_step(self->statement->st, self->connection); if (PyErr_Occurred()) { - (void)pysqlite_statement_reset(self->statement); - Py_DECREF(next_row); - return NULL; + goto error; } if (rc != SQLITE_DONE && rc != SQLITE_ROW) { - (void)pysqlite_statement_reset(self->statement); - Py_DECREF(next_row); _pysqlite_seterror(self->connection->db, NULL); - return NULL; + goto error; } if (rc == SQLITE_ROW) { + self->locked = 1; // GH-80254: Prevent recursive use of cursors. self->next_row = _pysqlite_fetch_one_row(self); + self->locked = 0; if (self->next_row == NULL) { - (void)pysqlite_statement_reset(self->statement); - return NULL; + goto error; } } } return next_row; + +error: + (void)pysqlite_statement_reset(self->statement); + Py_DECREF(next_row); + return NULL; } PyObject* pysqlite_cursor_fetchone(pysqlite_Cursor* self, PyObject* args) @@ -857,6 +871,10 @@ PyObject* pysqlite_noop(pysqlite_Connection* self, PyObject* args) PyObject* pysqlite_cursor_close(pysqlite_Cursor* self, PyObject* args) { + if (!check_cursor_locked(self)) { + return NULL; + } + if (!self->connection) { PyErr_SetString(pysqlite_ProgrammingError, "Base Cursor.__init__ not called."); diff --git a/Modules/_testcapimodule.c b/Modules/_testcapimodule.c index ad1b0745..90841270 100644 --- a/Modules/_testcapimodule.c +++ b/Modules/_testcapimodule.c @@ -5990,7 +5990,7 @@ static PyTypeObject PyRecursingInfinitelyError_Type = { 0, /* tp_setattro */ 0, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */ - "Instantiating this exception starts infinite recursion.", /* tp_doc */ + PyDoc_STR("Instantiating this exception starts infinite recursion."), /* tp_doc */ 0, /* tp_traverse */ 0, /* tp_clear */ 0, /* tp_richcompare */ diff --git a/Modules/clinic/_testmultiphase.c.h b/Modules/clinic/_testmultiphase.c.h index 0d38c230..23180d0a 100644 --- a/Modules/clinic/_testmultiphase.c.h +++ b/Modules/clinic/_testmultiphase.c.h @@ -18,18 +18,11 @@ _testmultiphase_StateAccessType_get_defining_module_impl(StateAccessTypeObject * static PyObject * _testmultiphase_StateAccessType_get_defining_module(StateAccessTypeObject *self, PyTypeObject *cls, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames) { - PyObject *return_value = NULL; - static const char * const _keywords[] = { NULL}; - static _PyArg_Parser _parser = {":get_defining_module", _keywords, 0}; - - if (!_PyArg_ParseStackAndKeywords(args, nargs, kwnames, &_parser - )) { - goto exit; + if (nargs) { + PyErr_SetString(PyExc_TypeError, "get_defining_module() takes no arguments"); + return NULL; } - return_value = _testmultiphase_StateAccessType_get_defining_module_impl(self, cls); - -exit: - return return_value; + return _testmultiphase_StateAccessType_get_defining_module_impl(self, cls); } PyDoc_STRVAR(_testmultiphase_StateAccessType_increment_count_clinic__doc__, @@ -55,14 +48,42 @@ _testmultiphase_StateAccessType_increment_count_clinic(StateAccessTypeObject *se { PyObject *return_value = NULL; static const char * const _keywords[] = {"n", "twice", NULL}; - static _PyArg_Parser _parser = {"|i$p:increment_count_clinic", _keywords, 0}; + static _PyArg_Parser _parser = {NULL, _keywords, "increment_count_clinic", 0}; + PyObject *argsbuf[2]; + Py_ssize_t noptargs = nargs + (kwnames ? PyTuple_GET_SIZE(kwnames) : 0) - 0; int n = 1; int twice = 0; - if (!_PyArg_ParseStackAndKeywords(args, nargs, kwnames, &_parser, - &n, &twice)) { + args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser, 0, 1, 0, argsbuf); + if (!args) { goto exit; } + if (!noptargs) { + goto skip_optional_pos; + } + if (args[0]) { + if (PyFloat_Check(args[0])) { + PyErr_SetString(PyExc_TypeError, + "integer argument expected, got float" ); + goto exit; + } + n = _PyLong_AsInt(args[0]); + if (n == -1 && PyErr_Occurred()) { + goto exit; + } + if (!--noptargs) { + goto skip_optional_pos; + } + } +skip_optional_pos: + if (!noptargs) { + goto skip_optional_kwonly; + } + twice = PyObject_IsTrue(args[1]); + if (twice < 0) { + goto exit; + } +skip_optional_kwonly: return_value = _testmultiphase_StateAccessType_increment_count_clinic_impl(self, cls, n, twice); exit: @@ -85,17 +106,10 @@ _testmultiphase_StateAccessType_get_count_impl(StateAccessTypeObject *self, static PyObject * _testmultiphase_StateAccessType_get_count(StateAccessTypeObject *self, PyTypeObject *cls, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames) { - PyObject *return_value = NULL; - static const char * const _keywords[] = { NULL}; - static _PyArg_Parser _parser = {":get_count", _keywords, 0}; - - if (!_PyArg_ParseStackAndKeywords(args, nargs, kwnames, &_parser - )) { - goto exit; + if (nargs) { + PyErr_SetString(PyExc_TypeError, "get_count() takes no arguments"); + return NULL; } - return_value = _testmultiphase_StateAccessType_get_count_impl(self, cls); - -exit: - return return_value; + return _testmultiphase_StateAccessType_get_count_impl(self, cls); } -/*[clinic end generated code: output=39eea487e94e7f5d input=a9049054013a1b77]*/ +/*[clinic end generated code: output=60d68e2336064f96 input=a9049054013a1b77]*/ diff --git a/Modules/clinic/posixmodule.c.h b/Modules/clinic/posixmodule.c.h index 28798ab9..f5df5c3b 100644 --- a/Modules/clinic/posixmodule.c.h +++ b/Modules/clinic/posixmodule.c.h @@ -8438,12 +8438,10 @@ static PyObject * os_DirEntry_is_symlink(DirEntry *self, PyTypeObject *defining_class, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames) { PyObject *return_value = NULL; - static const char * const _keywords[] = { NULL}; - static _PyArg_Parser _parser = {":is_symlink", _keywords, 0}; int _return_value; - if (!_PyArg_ParseStackAndKeywords(args, nargs, kwnames, &_parser - )) { + if (nargs) { + PyErr_SetString(PyExc_TypeError, "is_symlink() takes no arguments"); goto exit; } _return_value = os_DirEntry_is_symlink_impl(self, defining_class); @@ -8474,13 +8472,23 @@ os_DirEntry_stat(DirEntry *self, PyTypeObject *defining_class, PyObject *const * { PyObject *return_value = NULL; static const char * const _keywords[] = {"follow_symlinks", NULL}; - static _PyArg_Parser _parser = {"|$p:stat", _keywords, 0}; + static _PyArg_Parser _parser = {NULL, _keywords, "stat", 0}; + PyObject *argsbuf[1]; + Py_ssize_t noptargs = nargs + (kwnames ? PyTuple_GET_SIZE(kwnames) : 0) - 0; int follow_symlinks = 1; - if (!_PyArg_ParseStackAndKeywords(args, nargs, kwnames, &_parser, - &follow_symlinks)) { + args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser, 0, 0, 0, argsbuf); + if (!args) { goto exit; } + if (!noptargs) { + goto skip_optional_kwonly; + } + follow_symlinks = PyObject_IsTrue(args[0]); + if (follow_symlinks < 0) { + goto exit; + } +skip_optional_kwonly: return_value = os_DirEntry_stat_impl(self, defining_class, follow_symlinks); exit: @@ -8505,14 +8513,24 @@ os_DirEntry_is_dir(DirEntry *self, PyTypeObject *defining_class, PyObject *const { PyObject *return_value = NULL; static const char * const _keywords[] = {"follow_symlinks", NULL}; - static _PyArg_Parser _parser = {"|$p:is_dir", _keywords, 0}; + static _PyArg_Parser _parser = {NULL, _keywords, "is_dir", 0}; + PyObject *argsbuf[1]; + Py_ssize_t noptargs = nargs + (kwnames ? PyTuple_GET_SIZE(kwnames) : 0) - 0; int follow_symlinks = 1; int _return_value; - if (!_PyArg_ParseStackAndKeywords(args, nargs, kwnames, &_parser, - &follow_symlinks)) { + args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser, 0, 0, 0, argsbuf); + if (!args) { goto exit; } + if (!noptargs) { + goto skip_optional_kwonly; + } + follow_symlinks = PyObject_IsTrue(args[0]); + if (follow_symlinks < 0) { + goto exit; + } +skip_optional_kwonly: _return_value = os_DirEntry_is_dir_impl(self, defining_class, follow_symlinks); if ((_return_value == -1) && PyErr_Occurred()) { goto exit; @@ -8541,14 +8559,24 @@ os_DirEntry_is_file(DirEntry *self, PyTypeObject *defining_class, PyObject *cons { PyObject *return_value = NULL; static const char * const _keywords[] = {"follow_symlinks", NULL}; - static _PyArg_Parser _parser = {"|$p:is_file", _keywords, 0}; + static _PyArg_Parser _parser = {NULL, _keywords, "is_file", 0}; + PyObject *argsbuf[1]; + Py_ssize_t noptargs = nargs + (kwnames ? PyTuple_GET_SIZE(kwnames) : 0) - 0; int follow_symlinks = 1; int _return_value; - if (!_PyArg_ParseStackAndKeywords(args, nargs, kwnames, &_parser, - &follow_symlinks)) { + args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser, 0, 0, 0, argsbuf); + if (!args) { goto exit; } + if (!noptargs) { + goto skip_optional_kwonly; + } + follow_symlinks = PyObject_IsTrue(args[0]); + if (follow_symlinks < 0) { + goto exit; + } +skip_optional_kwonly: _return_value = os_DirEntry_is_file_impl(self, defining_class, follow_symlinks); if ((_return_value == -1) && PyErr_Occurred()) { goto exit; @@ -9441,4 +9469,4 @@ exit: #ifndef OS_WAITSTATUS_TO_EXITCODE_METHODDEF #define OS_WAITSTATUS_TO_EXITCODE_METHODDEF #endif /* !defined(OS_WAITSTATUS_TO_EXITCODE_METHODDEF) */ -/*[clinic end generated code: output=c7c8796918b09139 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=08879489d9e259a1 input=a9049054013a1b77]*/ diff --git a/Modules/gcmodule.c b/Modules/gcmodule.c index 3cf1a00b..cb5989e6 100644 --- a/Modules/gcmodule.c +++ b/Modules/gcmodule.c @@ -2157,6 +2157,12 @@ gc_fini_untrack(PyGC_Head *list) for (gc = GC_NEXT(list); gc != list; gc = GC_NEXT(list)) { PyObject *op = FROM_GC(gc); _PyObject_GC_UNTRACK(op); + // gh-92036: If a deallocator function expect the object to be tracked + // by the GC (ex: func_dealloc()), it can crash if called on an object + // which is no longer tracked by the GC. Leak one strong reference on + // purpose so the object is never deleted and its deallocator is not + // called. + Py_INCREF(op); } } diff --git a/Modules/ossaudiodev.c b/Modules/ossaudiodev.c index 2a1ac108..fb57764b 100644 --- a/Modules/ossaudiodev.c +++ b/Modules/ossaudiodev.c @@ -1243,8 +1243,12 @@ PyInit_ossaudiodev(void) _EXPORT_INT(m, SNDCTL_DSP_GETSPDIF); #endif _EXPORT_INT(m, SNDCTL_DSP_GETTRIGGER); +#ifdef SNDCTL_DSP_MAPINBUF _EXPORT_INT(m, SNDCTL_DSP_MAPINBUF); +#endif +#ifdef SNDCTL_DSP_MAPOUTBUF _EXPORT_INT(m, SNDCTL_DSP_MAPOUTBUF); +#endif _EXPORT_INT(m, SNDCTL_DSP_NONBLOCK); _EXPORT_INT(m, SNDCTL_DSP_POST); #ifdef SNDCTL_DSP_PROFILE diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c index 29d61268..1270af73 100644 --- a/Modules/posixmodule.c +++ b/Modules/posixmodule.c @@ -1853,7 +1853,17 @@ win32_xstat_impl(const wchar_t *path, struct _Py_stat_struct *result, /* Try reading the parent directory. */ if (!attributes_from_dir(path, &fileInfo, &tagInfo.ReparseTag)) { /* Cannot read the parent directory. */ - SetLastError(error); + switch (GetLastError()) { + case ERROR_FILE_NOT_FOUND: /* File cannot be found */ + case ERROR_PATH_NOT_FOUND: /* File parent directory cannot be found */ + case ERROR_NOT_READY: /* Drive exists but unavailable */ + case ERROR_BAD_NET_NAME: /* Remote drive unavailable */ + break; + /* Restore the error from CreateFileW(). */ + default: + SetLastError(error); + } + return -1; } if (fileInfo.dwFileAttributes & FILE_ATTRIBUTE_REPARSE_POINT) { diff --git a/Modules/socketmodule.c b/Modules/socketmodule.c index a22060d3..6d6c92e4 100644 --- a/Modules/socketmodule.c +++ b/Modules/socketmodule.c @@ -1722,6 +1722,8 @@ getsockaddrarg(PySocketSockObject *s, PyObject *args, "AF_UNIX path too long"); goto unix_out; } + + *len_ret = path.len + offsetof(struct sockaddr_un, sun_path); } else #endif /* linux */ @@ -1733,10 +1735,13 @@ getsockaddrarg(PySocketSockObject *s, PyObject *args, goto unix_out; } addr->sun_path[path.len] = 0; + + /* including the tailing NUL */ + *len_ret = path.len + offsetof(struct sockaddr_un, sun_path) + 1; } addr->sun_family = s->sock_family; memcpy(addr->sun_path, path.buf, path.len); - *len_ret = path.len + offsetof(struct sockaddr_un, sun_path); + retval = 1; unix_out: PyBuffer_Release(&path); diff --git a/Objects/exceptions.c b/Objects/exceptions.c index e67ecfab..57ddbb00 100644 --- a/Objects/exceptions.c +++ b/Objects/exceptions.c @@ -844,14 +844,7 @@ oserror_parse_args(PyObject **p_args, winerrcode = PyLong_AsLong(*winerror); if (winerrcode == -1 && PyErr_Occurred()) return -1; - /* Set errno to the corresponding POSIX errno (overriding - first argument). Windows Socket error codes (>= 10000) - have the same value as their POSIX counterparts. - */ - if (winerrcode < 10000) - errcode = winerror_to_errno(winerrcode); - else - errcode = winerrcode; + errcode = winerror_to_errno(winerrcode); *myerrno = PyLong_FromLong(errcode); if (!*myerrno) return -1; diff --git a/Objects/frameobject.c b/Objects/frameobject.c index 4ae17bcf..10db68ef 100644 --- a/Objects/frameobject.c +++ b/Objects/frameobject.c @@ -173,7 +173,10 @@ markblocks(PyCodeObject *code_obj, int len) break; case GET_ITER: case GET_AITER: - block_stack = push_block(block_stack, Loop); + // For-loops get a Loop block, but comprehensions do not. + if (_Py_OPCODE(code[i + 1]) != CALL_FUNCTION) { + block_stack = push_block(block_stack, Loop); + } blocks[i+1] = block_stack; break; case FOR_ITER: diff --git a/Objects/genericaliasobject.c b/Objects/genericaliasobject.c index acbb01cf..36dfbe43 100644 --- a/Objects/genericaliasobject.c +++ b/Objects/genericaliasobject.c @@ -293,6 +293,11 @@ subs_tvars(PyObject *obj, PyObject *params, PyObject **argitems) return obj; } +PyDoc_STRVAR(genericalias_doc, +"Represent a PEP 585 generic type\n" +"\n" +"E.g. for t = list[int], t.__origin__ is list and t.__args__ is (int,)."); + static PyObject * ga_getitem(PyObject *self, PyObject *item) { @@ -612,14 +617,11 @@ ga_new(PyTypeObject *type, PyObject *args, PyObject *kwds) // TODO: // - argument clinic? -// - __doc__? // - cache? PyTypeObject Py_GenericAliasType = { PyVarObject_HEAD_INIT(&PyType_Type, 0) .tp_name = "types.GenericAlias", - .tp_doc = "Represent a PEP 585 generic type\n" - "\n" - "E.g. for t = list[int], t.__origin__ is list and t.__args__ is (int,).", + .tp_doc = genericalias_doc, .tp_basicsize = sizeof(gaobject), .tp_dealloc = ga_dealloc, .tp_repr = ga_repr, diff --git a/Objects/genobject.c b/Objects/genobject.c index 5ba4de82..95614729 100644 --- a/Objects/genobject.c +++ b/Objects/genobject.c @@ -384,8 +384,11 @@ gen_close(PyGenObject *gen, PyObject *args) PyDoc_STRVAR(throw_doc, -"throw(typ[,val[,tb]]) -> raise exception in generator,\n\ -return next yielded value or raise StopIteration."); +"throw(value)\n\ +throw(type[,value[,tb]])\n\ +\n\ +Raise exception in generator, return next yielded value or raise\n\ +StopIteration."); static PyObject * _gen_throw(PyGenObject *gen, int close_on_genexit, @@ -943,8 +946,11 @@ PyDoc_STRVAR(coro_send_doc, return next iterated value or raise StopIteration."); PyDoc_STRVAR(coro_throw_doc, -"throw(typ[,val[,tb]]) -> raise exception in coroutine,\n\ -return next iterated value or raise StopIteration."); +"throw(value)\n\ +throw(type[,value[,traceback]])\n\ +\n\ +Raise exception in coroutine, return next iterated value or raise\n\ +StopIteration."); PyDoc_STRVAR(coro_close_doc, "close() -> raise GeneratorExit inside coroutine."); diff --git a/Objects/picklebufobject.c b/Objects/picklebufobject.c index a135e557..aaa852cf 100644 --- a/Objects/picklebufobject.c +++ b/Objects/picklebufobject.c @@ -206,7 +206,7 @@ static PyMethodDef picklebuf_methods[] = { PyTypeObject PyPickleBuffer_Type = { PyVarObject_HEAD_INIT(NULL, 0) .tp_name = "pickle.PickleBuffer", - .tp_doc = "Wrapper for potentially out-of-band buffers", + .tp_doc = PyDoc_STR("Wrapper for potentially out-of-band buffers"), .tp_basicsize = sizeof(PyPickleBufferObject), .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC, .tp_new = picklebuf_new, diff --git a/Objects/stringlib/codecs.h b/Objects/stringlib/codecs.h index 9b2a29ba..c8da7d57 100644 --- a/Objects/stringlib/codecs.h +++ b/Objects/stringlib/codecs.h @@ -388,8 +388,19 @@ STRINGLIB(utf8_encoder)(_PyBytesWriter *writer, if (!rep) goto error; - /* subtract preallocated bytes */ - writer->min_size -= max_char_size * (newpos - startpos); + if (newpos < startpos) { + writer->overallocate = 1; + p = _PyBytesWriter_Prepare(writer, p, + max_char_size * (startpos - newpos)); + if (p == NULL) + goto error; + } + else { + /* subtract preallocated bytes */ + writer->min_size -= max_char_size * (newpos - startpos); + /* Only overallocate the buffer if it's not the last write */ + writer->overallocate = (newpos < size); + } if (PyBytes_Check(rep)) { p = _PyBytesWriter_WriteBytes(writer, p, diff --git a/Objects/stringlib/fastsearch.h b/Objects/stringlib/fastsearch.h index 56a4467d..84b415a9 100644 --- a/Objects/stringlib/fastsearch.h +++ b/Objects/stringlib/fastsearch.h @@ -4,7 +4,8 @@ /* fast search/count implementation, based on a mix between boyer- moore and horspool, with a few more bells and whistles on the top. - for some more background, see: http://effbot.org/zone/stringlib.htm */ + for some more background, see: + https://web.archive.org/web/20201107074620/http://effbot.org/zone/stringlib.htm */ /* note: fastsearch may access s[n], which isn't a problem when using Python's ordinary string types, but may cause problems if you're diff --git a/Objects/typeobject.c b/Objects/typeobject.c index cb0bb461..755d3361 100644 --- a/Objects/typeobject.c +++ b/Objects/typeobject.c @@ -317,25 +317,29 @@ type_mro_modified(PyTypeObject *type, PyObject *bases) { Py_ssize_t i, n; int custom = !Py_IS_TYPE(type, &PyType_Type); int unbound; - PyObject *mro_meth = NULL; - PyObject *type_mro_meth = NULL; if (!_PyType_HasFeature(type, Py_TPFLAGS_HAVE_VERSION_TAG)) return; if (custom) { + PyObject *mro_meth, *type_mro_meth; mro_meth = lookup_maybe_method( (PyObject *)type, &PyId_mro, &unbound); - if (mro_meth == NULL) + if (mro_meth == NULL) { goto clear; + } type_mro_meth = lookup_maybe_method( (PyObject *)&PyType_Type, &PyId_mro, &unbound); - if (type_mro_meth == NULL) + if (type_mro_meth == NULL) { + Py_DECREF(mro_meth); goto clear; - if (mro_meth != type_mro_meth) + } + int custom_mro = (mro_meth != type_mro_meth); + Py_DECREF(mro_meth); + Py_DECREF(type_mro_meth); + if (custom_mro) { goto clear; - Py_XDECREF(mro_meth); - Py_XDECREF(type_mro_meth); + } } n = PyTuple_GET_SIZE(bases); for (i = 0; i < n; i++) { @@ -352,8 +356,6 @@ type_mro_modified(PyTypeObject *type, PyObject *bases) { } return; clear: - Py_XDECREF(mro_meth); - Py_XDECREF(type_mro_meth); type->tp_flags &= ~(Py_TPFLAGS_HAVE_VERSION_TAG| Py_TPFLAGS_VALID_VERSION_TAG); } diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c index 7767d140..e5e9ba20 100644 --- a/Objects/unicodeobject.c +++ b/Objects/unicodeobject.c @@ -5219,7 +5219,7 @@ _Py_DecodeUTF8Ex(const char *s, Py_ssize_t size, wchar_t **wstr, size_t *wlen, /* Note: size will always be longer than the resulting Unicode character count */ - if (PY_SSIZE_T_MAX / (Py_ssize_t)sizeof(wchar_t) < (size + 1)) { + if (PY_SSIZE_T_MAX / (Py_ssize_t)sizeof(wchar_t) - 1 < size) { return -1; } @@ -5805,7 +5805,7 @@ _PyUnicode_EncodeUTF32(PyObject *str, pos = 0; while (pos < len) { - Py_ssize_t repsize, moreunits; + Py_ssize_t newpos, repsize, moreunits; if (kind == PyUnicode_2BYTE_KIND) { pos += ucs2lib_utf32_encode((const Py_UCS2 *)data + pos, len - pos, @@ -5822,7 +5822,7 @@ _PyUnicode_EncodeUTF32(PyObject *str, rep = unicode_encode_call_errorhandler( errors, &errorHandler, encoding, "surrogates not allowed", - str, &exc, pos, pos + 1, &pos); + str, &exc, pos, pos + 1, &newpos); if (!rep) goto error; @@ -5830,7 +5830,7 @@ _PyUnicode_EncodeUTF32(PyObject *str, repsize = PyBytes_GET_SIZE(rep); if (repsize & 3) { raise_encode_exception(&exc, encoding, - str, pos - 1, pos, + str, pos, pos + 1, "surrogates not allowed"); goto error; } @@ -5843,28 +5843,30 @@ _PyUnicode_EncodeUTF32(PyObject *str, moreunits = repsize = PyUnicode_GET_LENGTH(rep); if (!PyUnicode_IS_ASCII(rep)) { raise_encode_exception(&exc, encoding, - str, pos - 1, pos, + str, pos, pos + 1, "surrogates not allowed"); goto error; } } + moreunits += pos - newpos; + pos = newpos; /* four bytes are reserved for each surrogate */ - if (moreunits > 1) { + if (moreunits > 0) { Py_ssize_t outpos = out - (uint32_t*) PyBytes_AS_STRING(v); if (moreunits >= (PY_SSIZE_T_MAX - PyBytes_GET_SIZE(v)) / 4) { /* integer overflow */ PyErr_NoMemory(); goto error; } - if (_PyBytes_Resize(&v, PyBytes_GET_SIZE(v) + 4 * (moreunits - 1)) < 0) + if (_PyBytes_Resize(&v, PyBytes_GET_SIZE(v) + 4 * moreunits) < 0) goto error; out = (uint32_t*) PyBytes_AS_STRING(v) + outpos; } if (PyBytes_Check(rep)) { memcpy(out, PyBytes_AS_STRING(rep), repsize); - out += moreunits; + out += repsize / 4; } else /* rep is unicode */ { assert(PyUnicode_KIND(rep) == PyUnicode_1BYTE_KIND); ucs1lib_utf32_encode(PyUnicode_1BYTE_DATA(rep), repsize, @@ -6157,7 +6159,7 @@ _PyUnicode_EncodeUTF16(PyObject *str, pos = 0; while (pos < len) { - Py_ssize_t repsize, moreunits; + Py_ssize_t newpos, repsize, moreunits; if (kind == PyUnicode_2BYTE_KIND) { pos += ucs2lib_utf16_encode((const Py_UCS2 *)data + pos, len - pos, @@ -6174,7 +6176,7 @@ _PyUnicode_EncodeUTF16(PyObject *str, rep = unicode_encode_call_errorhandler( errors, &errorHandler, encoding, "surrogates not allowed", - str, &exc, pos, pos + 1, &pos); + str, &exc, pos, pos + 1, &newpos); if (!rep) goto error; @@ -6182,7 +6184,7 @@ _PyUnicode_EncodeUTF16(PyObject *str, repsize = PyBytes_GET_SIZE(rep); if (repsize & 1) { raise_encode_exception(&exc, encoding, - str, pos - 1, pos, + str, pos, pos + 1, "surrogates not allowed"); goto error; } @@ -6195,28 +6197,30 @@ _PyUnicode_EncodeUTF16(PyObject *str, moreunits = repsize = PyUnicode_GET_LENGTH(rep); if (!PyUnicode_IS_ASCII(rep)) { raise_encode_exception(&exc, encoding, - str, pos - 1, pos, + str, pos, pos + 1, "surrogates not allowed"); goto error; } } + moreunits += pos - newpos; + pos = newpos; /* two bytes are reserved for each surrogate */ - if (moreunits > 1) { + if (moreunits > 0) { Py_ssize_t outpos = out - (unsigned short*) PyBytes_AS_STRING(v); if (moreunits >= (PY_SSIZE_T_MAX - PyBytes_GET_SIZE(v)) / 2) { /* integer overflow */ PyErr_NoMemory(); goto error; } - if (_PyBytes_Resize(&v, PyBytes_GET_SIZE(v) + 2 * (moreunits - 1)) < 0) + if (_PyBytes_Resize(&v, PyBytes_GET_SIZE(v) + 2 * moreunits) < 0) goto error; out = (unsigned short*) PyBytes_AS_STRING(v) + outpos; } if (PyBytes_Check(rep)) { memcpy(out, PyBytes_AS_STRING(rep), repsize); - out += moreunits; + out += repsize / 2; } else /* rep is unicode */ { assert(PyUnicode_KIND(rep) == PyUnicode_1BYTE_KIND); ucs1lib_utf16_encode(PyUnicode_1BYTE_DATA(rep), repsize, @@ -7143,8 +7147,19 @@ unicode_encode_ucs1(PyObject *unicode, if (rep == NULL) goto onError; - /* subtract preallocated bytes */ - writer.min_size -= newpos - collstart; + if (newpos < collstart) { + writer.overallocate = 1; + str = _PyBytesWriter_Prepare(&writer, str, + collstart - newpos); + if (str == NULL) + goto onError; + } + else { + /* subtract preallocated bytes */ + writer.min_size -= newpos - collstart; + /* Only overallocate the buffer if it's not the last write */ + writer.overallocate = (newpos < size); + } if (PyBytes_Check(rep)) { /* Directly copy bytes result to output. */ @@ -7933,13 +7948,14 @@ encode_code_page_errors(UINT code_page, PyObject **outbytes, pos, pos + 1, &newpos); if (rep == NULL) goto error; - pos = newpos; + Py_ssize_t morebytes = pos - newpos; if (PyBytes_Check(rep)) { outsize = PyBytes_GET_SIZE(rep); - if (outsize != 1) { + morebytes += outsize; + if (morebytes > 0) { Py_ssize_t offset = out - PyBytes_AS_STRING(*outbytes); - newoutsize = PyBytes_GET_SIZE(*outbytes) + (outsize - 1); + newoutsize = PyBytes_GET_SIZE(*outbytes) + morebytes; if (_PyBytes_Resize(outbytes, newoutsize) < 0) { Py_DECREF(rep); goto error; @@ -7960,9 +7976,10 @@ encode_code_page_errors(UINT code_page, PyObject **outbytes, } outsize = PyUnicode_GET_LENGTH(rep); - if (outsize != 1) { + morebytes += outsize; + if (morebytes > 0) { Py_ssize_t offset = out - PyBytes_AS_STRING(*outbytes); - newoutsize = PyBytes_GET_SIZE(*outbytes) + (outsize - 1); + newoutsize = PyBytes_GET_SIZE(*outbytes) + morebytes; if (_PyBytes_Resize(outbytes, newoutsize) < 0) { Py_DECREF(rep); goto error; @@ -7985,6 +8002,7 @@ encode_code_page_errors(UINT code_page, PyObject **outbytes, out++; } } + pos = newpos; Py_DECREF(rep); } /* write a NUL byte */ diff --git a/PC/readme.txt b/PC/readme.txt index b7969018..e1af101f 100644 --- a/PC/readme.txt +++ b/PC/readme.txt @@ -18,7 +18,7 @@ All PC ports use this scheme to try to set up a module search path: 1) The script location; the current directory without script. 2) The PYTHONPATH variable, if set. - 3) For Win32 platforms (NT/95), paths specified in the Registry. + 3) Paths specified in the Registry. 4) Default directories lib, lib/win, lib/test, lib/tkinter; these are searched relative to the environment variable PYTHONHOME, if set, or relative to the executable and its @@ -26,8 +26,8 @@ All PC ports use this scheme to try to set up a module search path: or the current directory (not useful). 5) The directory containing the executable. -The best installation strategy is to put the Python executable (and -DLL, for Win32 platforms) in some convenient directory such as +The best installation strategy is to put the Python executable and +DLL in some convenient directory such as C:/python, and copy all library files and subdirectories (using XCOPY) to C:/python/lib. Then you don't need to set PYTHONPATH. Otherwise, set the environment variable PYTHONPATH to your Python search path. diff --git a/PCbuild/get_externals.bat b/PCbuild/get_externals.bat index 475ddb36..8d7b918e 100644 --- a/PCbuild/get_externals.bat +++ b/PCbuild/get_externals.bat @@ -58,8 +58,8 @@ set libraries=%libraries% sqlite-3.37.2.0 if NOT "%IncludeTkinterSrc%"=="false" set libraries=%libraries% tcl-core-8.6.12.0 if NOT "%IncludeTkinterSrc%"=="false" set libraries=%libraries% tk-8.6.12.0 if NOT "%IncludeTkinterSrc%"=="false" set libraries=%libraries% tix-8.4.3.6 -set libraries=%libraries% xz-5.2.2 -set libraries=%libraries% zlib-1.2.11 +set libraries=%libraries% xz-5.2.5 +set libraries=%libraries% zlib-1.2.12 for %%e in (%libraries%) do ( if exist "%EXTERNALS_DIR%\%%e" ( diff --git a/PCbuild/liblzma.vcxproj b/PCbuild/liblzma.vcxproj index 8e77062c..fb1e37d1 100644 --- a/PCbuild/liblzma.vcxproj +++ b/PCbuild/liblzma.vcxproj @@ -92,7 +92,7 @@ WIN32;HAVE_CONFIG_H;_LIB;%(PreprocessorDefinitions) - $(lzmaDir)windows;$(lzmaDir)src/liblzma/common;$(lzmaDir)src/common;$(lzmaDir)src/liblzma/api;$(lzmaDir)src/liblzma/check;$(lzmaDir)src/liblzma/delta;$(lzmaDir)src/liblzma/lz;$(lzmaDir)src/liblzma/lzma;$(lzmaDir)src/liblzma/rangecoder;$(lzmaDir)src/liblzma/simple;%(AdditionalIncludeDirectories) + $(lzmaDir)windows/vs2019;$(lzmaDir)src/liblzma/common;$(lzmaDir)src/common;$(lzmaDir)src/liblzma/api;$(lzmaDir)src/liblzma/check;$(lzmaDir)src/liblzma/delta;$(lzmaDir)src/liblzma/lz;$(lzmaDir)src/liblzma/lzma;$(lzmaDir)src/liblzma/rangecoder;$(lzmaDir)src/liblzma/simple;%(AdditionalIncludeDirectories) 4028;4113;4133;4244;4267;4996;%(DisableSpecificWarnings) @@ -238,7 +238,7 @@ - + diff --git a/PCbuild/liblzma.vcxproj.filters b/PCbuild/liblzma.vcxproj.filters index adb2ba8b..4a2d1886 100644 --- a/PCbuild/liblzma.vcxproj.filters +++ b/PCbuild/liblzma.vcxproj.filters @@ -428,7 +428,7 @@ Header Files - + Header Files diff --git a/PCbuild/python.props b/PCbuild/python.props index 3e441989..80c5c2e9 100644 --- a/PCbuild/python.props +++ b/PCbuild/python.props @@ -59,7 +59,7 @@ $(ExternalsDir)\ $(ExternalsDir)sqlite-3.37.2.0\ $(ExternalsDir)bzip2-1.0.8\ - $(ExternalsDir)xz-5.2.2\ + $(ExternalsDir)xz-5.2.5\ $(ExternalsDir)libffi-3.3.0\ $(ExternalsDir)libffi-3.3.0\$(ArchName)\ $(libffiOutDir)include @@ -67,7 +67,7 @@ $(ExternalsDir)openssl-bin-1.1.1n\$(ArchName)\ $(opensslOutDir)include $(ExternalsDir)\nasm-2.11.06\ - $(ExternalsDir)\zlib-1.2.11\ + $(ExternalsDir)\zlib-1.2.12\ _d diff --git a/PCbuild/python.vcxproj b/PCbuild/python.vcxproj index a6892221..44ac0b8d 100644 --- a/PCbuild/python.vcxproj +++ b/PCbuild/python.vcxproj @@ -126,9 +126,6 @@ set PYTHONPATH=$(PySourcePath)Lib - <_PGOPath Condition="$(Configuration) == 'PGInstrument' and $(Platform) == 'Win32'">@set PATH=%PATH%%3B$(VCInstallDir)bin - <_PGOPath Condition="$(Configuration) == 'PGInstrument' and $(Platform) == 'x64'">@set PATH=%PATH%%3B$(VCInstallDir)bin\amd64 - <_PGOPath Condition="$(Configuration) == 'PGInstrument' and $(VC_PGO_RunTime_Dir) != ''">@set PATH=%PATH%%3B$(VC_PGO_RunTime_Dir) <_Content>@rem This script invokes the most recently built Python with all arguments @rem passed through to the interpreter. This file is generated by the @rem build process and any changes *will* be thrown away by the next @@ -138,7 +135,6 @@ set PYTHONPATH=$(PySourcePath)Lib @echo Running $(Configuration)^|$(Platform) interpreter... @setlocal @set PYTHONHOME=$(PySourcePath) -$(_PGOPath) @"$(OutDir)python$(PyDebugExt).exe" %* <_ExistingContent Condition="Exists('$(PySourcePath)python.bat')">$([System.IO.File]::ReadAllText('$(PySourcePath)python.bat')) @@ -164,4 +160,15 @@ $(_PGOPath) Overwrite="true" Lines="@(_LicenseFiles->'%(Content)')" /> + + + <_PGORT Include="$(VCToolsInstallDir)bin\Hostx86\x86\pgort140.dll" Condition="$(Platform) == 'Win32'" /> + <_PGORT Include="$(VCToolsInstallDir)bin\Hostx64\x64\pgort140.dll" Condition="$(Platform) == 'x64'" /> + <_PGORT Include="$(VCToolsInstallDir)bin\arm64\pgort140.dll" Condition="$(Platform) == 'ARM64'" /> + + + + + + diff --git a/PCbuild/pythoncore.vcxproj b/PCbuild/pythoncore.vcxproj index 1df62ca3..41dc79d3 100644 --- a/PCbuild/pythoncore.vcxproj +++ b/PCbuild/pythoncore.vcxproj @@ -500,7 +500,9 @@ - + + 4244 + diff --git a/PCbuild/readme.txt b/PCbuild/readme.txt index d21dd8e6..3c262438 100644 --- a/PCbuild/readme.txt +++ b/PCbuild/readme.txt @@ -13,12 +13,10 @@ Quick Start Guide Building Python using Microsoft Visual C++ ------------------------------------------ -This directory is used to build CPython for Microsoft Windows NT version -6.0 or higher (Windows Vista, Windows Server 2008, or later) on 32 and 64 +This directory is used to build CPython for Microsoft Windows on 32- and 64- bit platforms. Using this directory requires an installation of -Microsoft Visual Studio 2017 (MSVC 14.1) with the *Python workload* and -its optional *Python native development* component selected. (For -command-line builds, Visual Studio 2015 may also be used.) +Microsoft Visual Studio (MSVC) with the *Python workload* and +its optional *Python native development* component selected. Building from the command line is recommended in order to obtain any external dependencies. To build, simply run the "build.bat" script without @@ -105,7 +103,7 @@ pythonw Prompt window pylauncher py.exe, the Python Launcher for Windows, see - http://docs.python.org/3/using/windows.html#launcher + https://docs.python.org/3/using/windows.html#launcher pywlauncher pyw.exe, a variant of py.exe that doesn't open a Command Prompt window @@ -164,14 +162,14 @@ _bz2 _lzma Python wrapper for version 5.2.2 of the liblzma compression library Homepage: - http://tukaani.org/xz/ + https://tukaani.org/xz/ _ssl Python wrapper for version 1.1.1k of the OpenSSL secure sockets library, which is downloaded from our binaries repository at https://github.com/python/cpython-bin-deps. Homepage: - http://www.openssl.org/ + https://www.openssl.org/ Building OpenSSL requires Perl on your path, and can be performed by running PCbuild\prepare_ssl.bat. This will retrieve the version of @@ -187,14 +185,14 @@ _ssl _sqlite3 Wraps SQLite 3.37.2, which is itself built by sqlite3.vcxproj Homepage: - http://www.sqlite.org/ + https://www.sqlite.org/ _tkinter Wraps version 8.6.6 of the Tk windowing system, which is downloaded from our binaries repository at https://github.com/python/cpython-bin-deps. Homepage: - http://www.tcl.tk/ + https://www.tcl.tk/ Building Tcl and Tk can be performed by running PCbuild\prepare_tcltk.bat. This will retrieve the version of the @@ -253,7 +251,7 @@ It creates the PGI files, runs the unit test suite or PyBench with the PGI python, and finally creates the optimized files. See - http://msdn.microsoft.com/en-us/library/e7k32f4k(VS.140).aspx + https://docs.microsoft.com/en-us/cpp/build/profile-guided-optimizations for more on this topic. diff --git a/README.rst b/README.rst index d3b2521a..7a842390 100644 --- a/README.rst +++ b/README.rst @@ -1,4 +1,4 @@ -This is Python version 3.9.12 +This is Python version 3.9.13 ============================= .. image:: https://travis-ci.org/python/cpython.svg?branch=3.9 diff --git a/Tools/clinic/clinic.py b/Tools/clinic/clinic.py index 61d30b01..c68ee9a2 100755 --- a/Tools/clinic/clinic.py +++ b/Tools/clinic/clinic.py @@ -636,6 +636,10 @@ class CLanguage(Language): assert parameters assert isinstance(parameters[0].converter, self_converter) del parameters[0] + requires_defining_class = False + if parameters and isinstance(parameters[0].converter, defining_class_converter): + requires_defining_class = True + del parameters[0] converters = [p.converter for p in parameters] has_option_groups = parameters and (parameters[0].group or parameters[-1].group) @@ -657,10 +661,6 @@ class CLanguage(Language): if not p.is_optional(): min_pos = i - requires_defining_class = any( - isinstance(p.converter, defining_class_converter) - for p in parameters) - meth_o = (len(parameters) == 1 and parameters[0].is_positional_only() and not converters[0].is_optional() and @@ -763,24 +763,40 @@ class CLanguage(Language): return linear_format(output(), parser_declarations=declarations) if not parameters: - # no parameters, METH_NOARGS + if not requires_defining_class: + # no parameters, METH_NOARGS + flags = "METH_NOARGS" - flags = "METH_NOARGS" + parser_prototype = normalize_snippet(""" + static PyObject * + {c_basename}({self_type}{self_name}, PyObject *Py_UNUSED(ignored)) + """) + parser_code = [] - parser_prototype = normalize_snippet(""" - static PyObject * - {c_basename}({self_type}{self_name}, PyObject *Py_UNUSED(ignored)) - """) - parser_definition = parser_prototype + else: + assert not new_or_init - if default_return_converter: - parser_definition = parser_prototype + '\n' + normalize_snippet(""" - {{ - return {c_basename}_impl({impl_arguments}); + flags = "METH_METHOD|METH_FASTCALL|METH_KEYWORDS" + + parser_prototype = parser_prototype_def_class + return_error = ('return NULL;' if default_return_converter + else 'goto exit;') + parser_code = [normalize_snippet(""" + if (nargs) {{ + PyErr_SetString(PyExc_TypeError, "{name}() takes no arguments"); + %s }} - """) + """ % return_error, indent=4)] + + if default_return_converter: + parser_definition = '\n'.join([ + parser_prototype, + '{{', + *parser_code, + ' return {c_basename}_impl({impl_arguments});', + '}}']) else: - parser_definition = parser_body(parser_prototype) + parser_definition = parser_body(parser_prototype, *parser_code) elif meth_o: flags = "METH_O" @@ -939,6 +955,9 @@ class CLanguage(Language): add_label = None for i, p in enumerate(parameters): + if isinstance(p.converter, defining_class_converter): + raise ValueError("defining_class should be the first " + "parameter (after self)") displayname = p.get_displayname(i+1) parsearg = p.converter.parse_arg(argname_fmt % i, displayname) if parsearg is None: @@ -1547,10 +1566,16 @@ class BlockParser: def is_stop_line(line): # make sure to recognize stop line even if it # doesn't end with EOL (it could be the very end of the file) - if not line.startswith(stop_line): + if line.startswith(stop_line): + remainder = line[len(stop_line):] + if remainder and not remainder.isspace(): + fail(f"Garbage after stop line: {remainder!r}") + return True + else: + # gh-92256: don't allow incorrectly formatted stop lines + if line.lstrip().startswith(stop_line): + fail(f"Whitespace is not allowed before the stop line: {line!r}") return False - remainder = line[len(stop_line):] - return (not remainder) or remainder.isspace() # consume body of program while self.input: diff --git a/Tools/gdb/libpython.py b/Tools/gdb/libpython.py index 45be5ab9..cc0cd2fd 100755 --- a/Tools/gdb/libpython.py +++ b/Tools/gdb/libpython.py @@ -1285,7 +1285,7 @@ class PyUnicodeObjectPtr(PyObjectPtr): out.write('\\r') # Map non-printable US ASCII to '\xhh' */ - elif ch < ' ' or ch == 0x7F: + elif ch < ' ' or ord(ch) == 0x7F: out.write('\\x') out.write(hexdigits[(ord(ch) >> 4) & 0x000F]) out.write(hexdigits[ord(ch) & 0x000F])