diff options
Diffstat (limited to 'Doc/library')
| -rw-r--r-- | Doc/library/abc.rst | 26 | ||||
| -rw-r--r-- | Doc/library/array.rst | 5 | ||||
| -rw-r--r-- | Doc/library/ast.rst | 33 | ||||
| -rw-r--r-- | Doc/library/bisect.rst | 2 | ||||
| -rw-r--r-- | Doc/library/codecs.rst | 11 | ||||
| -rw-r--r-- | Doc/library/collections.abc.rst | 2 | ||||
| -rw-r--r-- | Doc/library/collections.rst | 4 | ||||
| -rw-r--r-- | Doc/library/dataclasses.rst | 4 | ||||
| -rw-r--r-- | Doc/library/difflib.rst | 2 | ||||
| -rw-r--r-- | Doc/library/functions.rst | 45 | ||||
| -rw-r--r-- | Doc/library/functools.rst | 7 | ||||
| -rw-r--r-- | Doc/library/math.rst | 4 | ||||
| -rw-r--r-- | Doc/library/optparse.rst | 2 | ||||
| -rw-r--r-- | Doc/library/pathlib.rst | 8 | ||||
| -rw-r--r-- | Doc/library/random.rst | 67 | ||||
| -rw-r--r-- | Doc/library/secrets.rst | 2 | ||||
| -rw-r--r-- | Doc/library/shelve.rst | 2 | ||||
| -rw-r--r-- | Doc/library/shutil.rst | 2 | ||||
| -rw-r--r-- | Doc/library/site.rst | 4 | ||||
| -rw-r--r-- | Doc/library/stdtypes.rst | 124 | ||||
| -rw-r--r-- | Doc/library/sys.rst | 2 | ||||
| -rw-r--r-- | Doc/library/test.rst | 2 | ||||
| -rw-r--r-- | Doc/library/types.rst | 5 | ||||
| -rw-r--r-- | Doc/library/typing.rst | 105 | ||||
| -rw-r--r-- | Doc/library/unittest.rst | 3 | ||||
| -rw-r--r-- | Doc/library/xml.etree.elementtree.rst | 6 |
26 files changed, 380 insertions, 99 deletions
diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst index 424ae547d8..3a7414d735 100644 --- a/Doc/library/abc.rst +++ b/Doc/library/abc.rst @@ -174,10 +174,11 @@ The :mod:`abc` module also provides the following decorator: to declare abstract methods for properties and descriptors. Dynamically adding abstract methods to a class, or attempting to modify the - abstraction status of a method or class once it is created, are not - supported. The :func:`abstractmethod` only affects subclasses derived using - regular inheritance; "virtual subclasses" registered with the ABC's - :meth:`register` method are not affected. + abstraction status of a method or class once it is created, are only + supported using the :func:`update_abstractmethods` function. The + :func:`abstractmethod` only affects subclasses derived using regular + inheritance; "virtual subclasses" registered with the ABC's :meth:`register` + method are not affected. When :func:`abstractmethod` is applied in combination with other method descriptors, it should be applied as the innermost decorator, as shown in @@ -235,7 +236,6 @@ The :mod:`abc` module also provides the following decorator: super-call in a framework that uses cooperative multiple-inheritance. - The :mod:`abc` module also supports the following legacy decorators: .. decorator:: abstractclassmethod @@ -335,6 +335,22 @@ The :mod:`abc` module also provides the following functions: .. versionadded:: 3.4 +.. function:: update_abstractmethods(cls) + A function to recalculate an abstract class's abstraction status. This + function should be called if a class's abstract methods have been + implemented or changed after it was created. Usually, this function should + be called from within a class decorator. + + Returns *cls*, to allow usage as a class decorator. + + If *cls* is not an instance of ABCMeta, does nothing. + + .. note:: + + This function assumes that *cls*'s superclasses are already updated. + It does not update any subclasses. + + .. versionadded:: 3.10 .. rubric:: Footnotes diff --git a/Doc/library/array.rst b/Doc/library/array.rst index 78020738bf..ff3ec6b1fd 100644 --- a/Doc/library/array.rst +++ b/Doc/library/array.rst @@ -257,7 +257,6 @@ Examples:: Packing and unpacking of External Data Representation (XDR) data as used in some remote procedure call systems. - `The Numerical Python Documentation <https://docs.scipy.org/doc/>`_ - The Numeric Python extension (NumPy) defines another array type; see - http://www.numpy.org/ for further information about Numerical Python. + `NumPy <https://numpy.org/>`_ + The NumPy package defines another array type. diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index 755c60fba6..f95ee1d5c6 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -1586,6 +1586,9 @@ and classes for traversing abstract syntax trees: .. versionchanged:: 3.9 Now supports creating empty sets with ``'set()'``. + .. versionchanged:: 3.10 + For string inputs, leading spaces and tabs are now stripped. + .. function:: get_docstring(node, clean=True) @@ -1753,6 +1756,34 @@ and classes for traversing abstract syntax trees: Added the *indent* option. +.. _ast-compiler-flags: + +Compiler Flags +-------------- + +The following flags may be passed to :func:`compile` in order to change +effects on the compilation of a program: + +.. data:: PyCF_ALLOW_TOP_LEVEL_AWAIT + + Enables support for top-level ``await``, ``async for``, ``async with`` + and async comprehensions. + + .. versionadded:: 3.8 + +.. data:: PyCF_ONLY_AST + + Generates and returns an abstract syntax tree instead of returning a + compiled code object. + +.. data:: PyCF_TYPE_COMMENTS + + Enables support for :pep:`484` and :pep:`526` style type comments + (``# type: <type>``, ``# type: ignore <stuff>``). + + .. versionadded:: 3.8 + + .. _ast-cli: Command-Line Usage @@ -1820,4 +1851,4 @@ to stdout. Otherwise, the content is read from stdin. `Parso <https://parso.readthedocs.io>`_ is a Python parser that supports error recovery and round-trip parsing for different Python versions (in multiple Python versions). Parso is also able to list multiple syntax errors - in your python file.
\ No newline at end of file + in your python file. diff --git a/Doc/library/bisect.rst b/Doc/library/bisect.rst index 6666d55abe..6bf7814b25 100644 --- a/Doc/library/bisect.rst +++ b/Doc/library/bisect.rst @@ -60,7 +60,7 @@ The following functions are provided: .. seealso:: `SortedCollection recipe - <https://github.com/ActiveState/code/tree/master/recipes/Python/577197_SortedCollection/recipe-577197.py>`_ that uses + <https://code.activestate.com/recipes/577197-sortedcollection/>`_ that uses bisect to build a full-featured collection class with straight-forward search methods and support for a key-function. The keys are precomputed to save unnecessary calls to the key function during searches. diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst index f071057293..a026513520 100644 --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@ -163,11 +163,14 @@ function: :class:`CodecInfo` object. In case a search function cannot find a given encoding, it should return ``None``. - .. note:: - Search function registration is not currently reversible, - which may cause problems in some cases, such as unit testing or - module reloading. +.. function:: unregister(search_function) + + Unregister a codec search function and clear the registry's cache. + If the search function is not registered, do nothing. + + .. versionadded:: 3.10 + While the builtin :func:`open` and the associated :mod:`io` module are the recommended approach for working with encoded text files, this module diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst index a603809867..db0e25bb07 100644 --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -308,7 +308,7 @@ Notes on using :class:`Set` and :class:`MutableSet` as a mixin: .. seealso:: - * `OrderedSet recipe <https://github.com/ActiveState/code/tree/master/recipes/Python/576694_OrderedSet/recipe-576694.py>`_ for an + * `OrderedSet recipe <https://code.activestate.com/recipes/576694/>`_ for an example built on :class:`MutableSet`. * For more about ABCs, see the :mod:`abc` module and :pep:`3119`. diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index a7d01b3f39..f538da5e1c 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -135,12 +135,12 @@ The class can be used to simulate nested scopes and is useful in templating. :attr:`~collections.ChainMap.parents` property. * The `Nested Contexts recipe - <https://github.com/ActiveState/code/tree/master/recipes/Python/577434_Nested_contexts__chamapping/recipe-577434.py>`_ has options to control + <https://code.activestate.com/recipes/577434/>`_ has options to control whether writes and other mutations apply only to the first mapping or to any mapping in the chain. * A `greatly simplified read-only version of Chainmap - <https://github.com/ActiveState/code/tree/master/recipes/Python/305268_Chained_map_lookups/recipe-305268.py>`_. + <https://code.activestate.com/recipes/305268/>`_. :class:`ChainMap` Examples and Recipes diff --git a/Doc/library/dataclasses.rst b/Doc/library/dataclasses.rst index 6e74af062d..e706f7fcc5 100644 --- a/Doc/library/dataclasses.rst +++ b/Doc/library/dataclasses.rst @@ -188,7 +188,7 @@ Module-level decorators, classes, and functions @dataclass class C: - mylist: List[int] = field(default_factory=list) + mylist: list[int] = field(default_factory=list) c = C() c.mylist += [1, 2, 3] @@ -301,7 +301,7 @@ Module-level decorators, classes, and functions @dataclass class C: - mylist: List[Point] + mylist: list[Point] p = Point(10, 20) assert asdict(p) == {'x': 10, 'y': 20} diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst index 009b7976df..aa08988c8b 100644 --- a/Doc/library/difflib.rst +++ b/Doc/library/difflib.rst @@ -633,7 +633,7 @@ If you want to know how to change the first sequence into the second, use work. * `Simple version control recipe - <https://github.com/ActiveState/code/tree/master/recipes/Python/576729_Simple_Version_Control/recipe-576729.py>`_ for a small application + <https://code.activestate.com/recipes/576729/>`_ for a small application built with :class:`SequenceMatcher`. diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 7543fc4b10..a052e724c5 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -259,26 +259,24 @@ are always available. They are listed here in alphabetical order. interactive statement (in the latter case, expression statements that evaluate to something other than ``None`` will be printed). - The optional arguments *flags* and *dont_inherit* control which :ref:`future - statements <future>` affect the compilation of *source*. If neither - is present (or both are zero) the code is compiled with those future - statements that are in effect in the code that is calling :func:`compile`. If the - *flags* argument is given and *dont_inherit* is not (or is zero) then the - future statements specified by the *flags* argument are used in addition to - those that would be used anyway. If *dont_inherit* is a non-zero integer then - the *flags* argument is it -- the future statements in effect around the call - to compile are ignored. - - Future statements are specified by bits which can be bitwise ORed together to - specify multiple statements. The bitfield required to specify a given feature - can be found as the :attr:`~__future__._Feature.compiler_flag` attribute on - the :class:`~__future__._Feature` instance in the :mod:`__future__` module. - - The optional argument *flags* also controls whether the compiled source is - allowed to contain top-level ``await``, ``async for`` and ``async with``. - When the bit ``ast.PyCF_ALLOW_TOP_LEVEL_AWAIT`` is set, the return code - object has ``CO_COROUTINE`` set in ``co_code``, and can be interactively - executed via ``await eval(code_object)``. + The optional argument *flags* and *dont_inherit* controls which + :ref:`compiler options <ast-compiler-flags>` should be activated + and which :ref:`future features <future>` should be allowed. If neither + is present (or both are zero) the code is compiled with the same flags that + affect the code that is calling :func:`compile`. If the *flags* + argument is given and *dont_inherit* is not (or is zero) then the compiler + options and the future statements specified by the *flags* argument are used + in addition to those that would be used anyway. If *dont_inherit* is a + non-zero integer then the *flags* argument is it -- the flags (future + features and compiler options) in the surrounding code are ignored. + + Compiler options and future statements are specified by bits which can be + bitwise ORed together to specify multiple options. The bitfield required to + specify a given future feature can be found as the + :attr:`~__future__._Feature.compiler_flag` attribute on the + :class:`~__future__._Feature` instance in the :mod:`__future__` module. + :ref:`Compiler flags <ast-compiler-flags>` can be found in :mod:`ast` + module, with ``PyCF_`` prefix. The argument *optimize* specifies the optimization level of the compiler; the default value of ``-1`` selects the optimization level of the interpreter as @@ -506,6 +504,9 @@ are always available. They are listed here in alphabetical order. returns the current global and local dictionary, respectively, which may be useful to pass around for use by :func:`eval` or :func:`exec`. + If the given source is a string, then leading and trailing spaces and tabs + are stripped. + See :func:`ast.literal_eval` for a function that can safely evaluate strings with expressions containing only literals. @@ -1512,14 +1513,12 @@ are always available. They are listed here in alphabetical order. .. class:: slice(stop) slice(start, stop[, step]) - .. index:: single: Numerical Python - Return a :term:`slice` object representing the set of indices specified by ``range(start, stop, step)``. The *start* and *step* arguments default to ``None``. Slice objects have read-only data attributes :attr:`~slice.start`, :attr:`~slice.stop` and :attr:`~slice.step` which merely return the argument values (or their default). They have no other explicit functionality; - however they are used by Numerical Python and other third party extensions. + however they are used by NumPy and other third party packages. Slice objects are also generated when extended indexing syntax is used. For example: ``a[start:stop:step]`` or ``a[start:stop, i]``. See :func:`itertools.islice` for an alternate version that returns an iterator. diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 14aa184e2c..186cb4c381 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -254,6 +254,13 @@ The :mod:`functools` module defines the following functions: application, implementing all six rich comparison methods instead is likely to provide an easy speed boost. + .. note:: + + This decorator makes no attempt to override methods that have been + declared in the class *or its superclasses*. Meaning that if a + superclass defines a comparison operator, *total_ordering* will not + implement it again, even if the original method is abstract. + .. versionadded:: 3.2 .. versionchanged:: 3.4 diff --git a/Doc/library/math.rst b/Doc/library/math.rst index f152c45a87..145bac4966 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -123,14 +123,14 @@ Number-theoretic and representation functions For further discussion and two alternative approaches, see the `ASPN cookbook recipes for accurate floating point summation - <https://github.com/ActiveState/code/tree/master/recipes/Python/393090_Binary_floating_point_summatiaccurate_full/recipe-393090.py>`_\. + <https://code.activestate.com/recipes/393090/>`_\. .. function:: gcd(*integers) Return the greatest common divisor of the specified integer arguments. If any of the arguments is nonzero, then the returned value is the largest - positive integer that is a divisor af all arguments. If all arguments + positive integer that is a divisor of all arguments. If all arguments are zero, then the returned value is ``0``. ``gcd()`` without arguments returns ``0``. diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index c1a18e0147..b1094198f4 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -55,7 +55,7 @@ equivalent to the above example:: <yourscript> -q -foutfile <yourscript> -qfoutfile -Additionally, users can run one of :: +Additionally, users can run one of the following :: <yourscript> -h <yourscript> --help diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 23486b6250..9526a03b05 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1008,6 +1008,10 @@ call fails (for example because the path doesn't exist). >>> target.open().read() 'some text' + The target path may be absolute or relative. Relative paths are interpreted + relative to the current working directory, *not* the directory of the Path + object. + .. versionchanged:: 3.8 Added return value, return the new Path instance. @@ -1018,6 +1022,10 @@ call fails (for example because the path doesn't exist). instance pointing to *target*. If *target* points to an existing file or 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 + object. + .. versionchanged:: 3.8 Added return value, return the new Path instance. diff --git a/Doc/library/random.rst b/Doc/library/random.rst index 4e97b1dbad..5a9359484d 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -57,7 +57,7 @@ from sources provided by the operating system. `Complementary-Multiply-with-Carry recipe - <https://github.com/ActiveState/code/tree/master/recipes/Python/576707_Long_period_random_number/recipe-576707.py>`_ for a compatible alternative + <https://code.activestate.com/recipes/576707/>`_ for a compatible alternative random number generator with a long period and comparatively simple update operations. @@ -180,8 +180,8 @@ Functions for sequences The *weights* or *cum_weights* can use any numeric type that interoperates with the :class:`float` values returned by :func:`random` (that includes - integers, floats, and fractions but excludes decimals). Behavior is - undefined if any weight is negative. A :exc:`ValueError` is raised if all + integers, floats, and fractions but excludes decimals). Weights are assumed + to be non-negative and finite. A :exc:`ValueError` is raised if all weights are zero. For a given seed, the :func:`choices` function with equal weighting @@ -253,6 +253,8 @@ Functions for sequences order so that the sample is reproducible. +.. _real-valued-distributions: + Real-valued distributions ------------------------- @@ -391,8 +393,8 @@ change across Python versions, but two aspects are guaranteed not to change: .. _random-examples: -Examples and Recipes --------------------- +Examples +-------- Basic examples:: @@ -536,3 +538,58 @@ Simulation of arrival times and service deliveries for a multiserver queue:: a tutorial by `Peter Norvig <http://norvig.com/bio.html>`_ covering the basics of probability theory, how to write simulations, and how to perform data analysis using Python. + + +Recipes +------- + +The default :func:`.random` returns multiples of 2⁻⁵³ in the range +*0.0 ≤ x < 1.0*. All such numbers are evenly spaced and are exactly +representable as Python floats. However, many other representable +floats in that interval are not possible selections. For example, +``0.05954861408025609`` isn't an integer multiple of 2⁻⁵³. + +The following recipe takes a different approach. All floats in the +interval are possible selections. The mantissa comes from a uniform +distribution of integers in the range *2⁵² ≤ mantissa < 2⁵³*. The +exponent comes from a geometric distribution where exponents smaller +than *-53* occur half as often as the next larger exponent. + +:: + + from random import Random + from math import ldexp + + class FullRandom(Random): + + def random(self): + mantissa = 0x10_0000_0000_0000 | self.getrandbits(52) + exponent = -53 + x = 0 + while not x: + x = self.getrandbits(32) + exponent += x.bit_length() - 32 + return ldexp(mantissa, exponent) + +All :ref:`real valued distributions <real-valued-distributions>` +in the class will use the new method:: + + >>> fr = FullRandom() + >>> fr.random() + 0.05954861408025609 + >>> fr.expovariate(0.25) + 8.87925541791544 + +The recipe is conceptually equivalent to an algorithm that chooses from +all the multiples of 2⁻¹⁰⁷⁴ in the range *0.0 ≤ x < 1.0*. All such +numbers are evenly spaced, but most have to be rounded down to the +nearest representable Python float. (The value 2⁻¹⁰⁷⁴ is the smallest +positive unnormalized float and is equal to ``math.ulp(0.0)``.) + + +.. seealso:: + + `Generating Pseudo-random Floating-Point Values + <https://allendowney.com/research/rand/downey07randfloat.pdf>`_ a + paper by Allen B. Downey describing ways to generate more + fine-grained floats than normally generated by :func:`.random`. diff --git a/Doc/library/secrets.rst b/Doc/library/secrets.rst index bc4766da27..afa8e2d385 100644 --- a/Doc/library/secrets.rst +++ b/Doc/library/secrets.rst @@ -21,7 +21,7 @@ The :mod:`secrets` module is used for generating cryptographically strong random numbers suitable for managing data such as passwords, account authentication, security tokens, and related secrets. -In particularly, :mod:`secrets` should be used in preference to the +In particular, :mod:`secrets` should be used in preference to the default pseudo-random number generator in the :mod:`random` module, which is designed for modelling and simulation, not security or cryptography. diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst index a94255bbf6..f08c58179a 100644 --- a/Doc/library/shelve.rst +++ b/Doc/library/shelve.rst @@ -75,7 +75,7 @@ Two additional methods are supported: .. seealso:: - `Persistent dictionary recipe <https://github.com/ActiveState/code/tree/master/recipes/Python/576642_Persistent_dict_multiple_standard_file/recipe-576642.py>`_ + `Persistent dictionary recipe <https://code.activestate.com/recipes/576642/>`_ with widely supported storage formats and having the speed of native dictionaries. diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index ecc3309ed5..3f5122760e 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -349,7 +349,7 @@ Directory and files operations will be created in or as *dst* and *src* will be removed. If *copy_function* is given, it must be a callable that takes two arguments - *src* and *dst*, and will be used to copy *src* to *dest* if + *src* and *dst*, and will be used to copy *src* to *dst* if :func:`os.rename` cannot be used. If the source is a directory, :func:`copytree` is called, passing it the :func:`copy_function`. The default *copy_function* is :func:`copy2`. Using :func:`~shutil.copy` as the diff --git a/Doc/library/site.rst b/Doc/library/site.rst index b424e1ba34..2e3646f6a7 100644 --- a/Doc/library/site.rst +++ b/Doc/library/site.rst @@ -231,7 +231,9 @@ Module contents Return the path of the user-specific site-packages directory, :data:`USER_SITE`. If it is not initialized yet, this function will also set - it, respecting :envvar:`PYTHONNOUSERSITE` and :data:`USER_BASE`. + it, respecting :data:`USER_BASE`. To determine if the user-specific + site-packages was added to ``sys.path`` :data:`ENABLE_USER_SITE` should be + used. .. versionadded:: 3.2 diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 2eee22c79a..5c6acc66bb 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1404,7 +1404,7 @@ objects that compare equal might have different :attr:`~range.start`, .. seealso:: - * The `linspace recipe <https://github.com/ActiveState/code/tree/master/recipes/Python/579000_Equallyspaced_numbers_linspace/recipe-579000.py>`_ + * The `linspace recipe <http://code.activestate.com/recipes/579000/>`_ shows how to implement a lazy version of range suitable for floating point applications. @@ -4749,6 +4749,128 @@ define these methods must provide them as a normal Python accessible method. Compared to the overhead of setting up the runtime context, the overhead of a single class dictionary lookup is negligible. +.. _types-union: + +Union Type +========== + +.. index:: + object: Union + pair: union; type + +A union object holds the value of the ``|`` (bitwise or) operation on +multiple :ref:`type objects<bltin-type-objects>`. These types are intended +primarily for type annotations. The union type expression enables cleaner +type hinting syntax compared to :data:`typing.Union`. + +.. describe:: X | Y | ... + + Defines a union object which holds types *X*, *Y*, and so forth. ``X | Y`` + means either X or Y. It is equivalent to ``typing.Union[X, Y]``. + Example:: + + def square(number: int | float) -> int | float: + return number ** 2 + +.. describe:: union_object == other + + Union objects can be tested for equality with other union objects. Details: + + * Unions of unions are flattened, e.g.:: + + (int | str) | float == int | str | float + + * Redundant types are removed, e.g.:: + + int | str | int == int | str + + * When comparing unions, the order is ignored, e.g.:: + + int | str == str | int + + * It is compatible with :data:`typing.Union`:: + + int | str == typing.Union[int, str] + + * Optional types can be spelled as a union with ``None``:: + + str | None == typing.Optional[str] + +.. describe:: isinstance(obj, union_object) + + Calls to :func:`isinstance` are also supported with a Union object:: + + >>> isinstance("", int | str) + True + + .. + At the time of writing this, there is no documentation for parameterized + generics or PEP 585. Thus the link currently points to PEP 585 itself. + Please change the link for parameterized generics to reference the correct + documentation once documentation for PEP 585 becomes available. + + However, union objects containing `parameterized generics + <https://www.python.org/dev/peps/pep-0585/>`_ cannot be used:: + + >>> isinstance(1, int | list[int]) + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + TypeError: isinstance() argument 2 cannot contain a parameterized generic + +.. describe:: issubclass(obj, union_object) + + Calls to :func:`issubclass` are also supported with a Union Object.:: + + >>> issubclass(bool, int | str) + True + + .. + Once again, please change the link below for parameterized generics to + reference the correct documentation once documentation for PEP 585 + becomes available. + + However, union objects containing `parameterized generics + <https://www.python.org/dev/peps/pep-0585/>`_ cannot be used:: + + >>> issubclass(bool, bool | list[str]) + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + TypeError: issubclass() argument 2 cannot contain a parameterized generic + +The type for the Union object is :data:`types.Union`. An object cannot be +instantiated from the type:: + + >>> import types + >>> isinstance(int | str, types.Union) + True + >>> types.Union() + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + TypeError: cannot create 'types.Union' instances + +.. note:: + The :meth:`__or__` method for type objects was added to support the syntax + ``X | Y``. If a metaclass implements :meth:`__or__`, the Union may + override it:: + + >>> class M(type): + ... def __or__(self, other): + ... return "Hello" + ... + >>> class C(metaclass=M): + ... pass + ... + >>> C | int + 'Hello' + >>> int | C + int | __main__.C + +.. seealso:: + + :pep:`604` -- PEP proposing the ``X | Y`` syntax and the Union type. + +.. versionadded:: 3.10 + .. _typesother: diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index aa417ede40..d201d7061f 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -679,7 +679,7 @@ always available. additional garbage collector overhead if the object is managed by the garbage collector. - See `recursive sizeof recipe <https://github.com/ActiveState/code/tree/master/recipes/Python/577504_Compute_Memory_footprint_object_its/recipe-577504.py>`_ + See `recursive sizeof recipe <https://code.activestate.com/recipes/577504>`_ for an example of using :func:`getsizeof` recursively to find the size of containers and all their contents. diff --git a/Doc/library/test.rst b/Doc/library/test.rst index 6495b48444..ce6b868458 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -1168,6 +1168,8 @@ script execution tests. The :mod:`test.support.bytecode_helper` module provides support for testing and inspecting bytecode generation. +.. versionadded:: 3.9 + The module defines the following class: .. class:: BytecodeTestCase(unittest.TestCase) diff --git a/Doc/library/types.rst b/Doc/library/types.rst index 25fa750f2c..e4a8dec5cb 100644 --- a/Doc/library/types.rst +++ b/Doc/library/types.rst @@ -256,6 +256,11 @@ Standard names are defined for the following types: .. versionadded:: 3.10 +.. data:: Union + + The type of :ref:`union type expressions<types-union>`. + + .. versionadded:: 3.10 .. class:: TracebackType(tb_next, tb_frame, tb_lasti, tb_lineno) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index d31c65d38e..402dd24fde 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -18,7 +18,7 @@ -------------- This module provides runtime support for type hints as specified by -:pep:`484`, :pep:`526`, :pep:`544`, :pep:`586`, :pep:`589`, and :pep:`591`. +:pep:`484`, :pep:`526`, :pep:`544`, :pep:`586`, :pep:`589`, :pep:`591`, and :pep:`613`. The most fundamental support consists of the types :data:`Any`, :data:`Union`, :data:`Tuple`, :data:`Callable`, :class:`TypeVar`, and :class:`Generic`. For full specification please see :pep:`484`. For @@ -34,14 +34,15 @@ In the function ``greeting``, the argument ``name`` is expected to be of type :class:`str` and the return type :class:`str`. Subtypes are accepted as arguments. +.. _type-aliases: + Type aliases ============ A type alias is defined by assigning the type to the alias. In this example, -``Vector`` and ``List[float]`` will be treated as interchangeable synonyms:: +``Vector`` and ``list[float]`` will be treated as interchangeable synonyms:: - from typing import List - Vector = List[float] + Vector = list[float] def scale(scalar: float, vector: Vector) -> Vector: return [scalar * num for num in vector] @@ -51,11 +52,11 @@ A type alias is defined by assigning the type to the alias. In this example, Type aliases are useful for simplifying complex type signatures. For example:: - from typing import Dict, Tuple, Sequence + from collections.abc import Sequence - ConnectionOptions = Dict[str, str] - Address = Tuple[str, int] - Server = Tuple[Address, ConnectionOptions] + ConnectionOptions = dict[str, str] + Address = tuple[str, int] + Server = tuple[Address, ConnectionOptions] def broadcast_message(message: str, servers: Sequence[Server]) -> None: ... @@ -64,7 +65,7 @@ Type aliases are useful for simplifying complex type signatures. For example:: # being exactly equivalent to this one. def broadcast_message( message: str, - servers: Sequence[Tuple[Tuple[str, int], Dict[str, str]]]) -> None: + servers: Sequence[tuple[tuple[str, int], dict[str, str]]]) -> None: ... Note that ``None`` as a type hint is a special case and is replaced by @@ -157,7 +158,7 @@ type hinted using ``Callable[[Arg1Type, Arg2Type], ReturnType]``. For example:: - from typing import Callable + from collections.abc import Callable def feeder(get_next_item: Callable[[], str]) -> None: # Body @@ -181,7 +182,7 @@ subscription to denote expected types for container elements. :: - from typing import Mapping, Sequence + from collections.abc import Mapping, Sequence def notify_by_email(employees: Sequence[Employee], overrides: Mapping[str, str]) -> None: ... @@ -191,7 +192,8 @@ called :class:`TypeVar`. :: - from typing import Sequence, TypeVar + from collections.abc import Sequence + from typing import TypeVar T = TypeVar('T') # Declare type variable @@ -235,7 +237,7 @@ class body. The :class:`Generic` base class defines :meth:`__class_getitem__` so that ``LoggedVar[t]`` is valid as a type:: - from typing import Iterable + from collections.abc import Iterable def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None: for var in vars: @@ -266,7 +268,8 @@ This is thus invalid:: You can use multiple inheritance with :class:`Generic`:: - from typing import TypeVar, Generic, Sized + from collections.abc import Sized + from typing import TypeVar, Generic T = TypeVar('T') @@ -275,7 +278,8 @@ You can use multiple inheritance with :class:`Generic`:: When inheriting from generic classes, some type variables could be fixed:: - from typing import TypeVar, Mapping + from collections.abc import Mapping + from typing import TypeVar T = TypeVar('T') @@ -288,13 +292,14 @@ Using a generic class without specifying type parameters assumes :data:`Any` for each position. In the following example, ``MyIterable`` is not generic but implicitly inherits from ``Iterable[Any]``:: - from typing import Iterable + from collections.abc import Iterable class MyIterable(Iterable): # Same as Iterable[Any] User defined generic type aliases are also supported. Examples:: - from typing import TypeVar, Iterable, Tuple, Union + from collections.abc import Iterable + from typing import TypeVar, Union S = TypeVar('S') Response = Union[Iterable[S], int] @@ -303,9 +308,9 @@ User defined generic type aliases are also supported. Examples:: ... T = TypeVar('T', int, float, complex) - Vec = Iterable[Tuple[T, T]] + Vec = Iterable[tuple[T, T]] - def inproduct(v: Vec[T]) -> T: # Same as Iterable[Tuple[T, T]] + def inproduct(v: Vec[T]) -> T: # Same as Iterable[tuple[T, T]] return sum(x*y for x, y in v) .. versionchanged:: 3.7 @@ -403,12 +408,12 @@ Initially :pep:`484` defined Python static type system as using a class ``B`` is expected if and only if ``A`` is a subclass of ``B``. This requirement previously also applied to abstract base classes, such as -:class:`Iterable`. The problem with this approach is that a class had +:class:`~collections.abc.Iterable`. The problem with this approach is that a class had to be explicitly marked to support them, which is unpythonic and unlike what one would normally do in idiomatic dynamically typed Python code. -For example, this conforms to the :pep:`484`:: +For example, this conforms to :pep:`484`:: - from typing import Sized, Iterable, Iterator + from collections.abc import Sized, Iterable, Iterator class Bucket(Sized, Iterable[int]): ... @@ -421,7 +426,7 @@ allowing ``Bucket`` to be implicitly considered a subtype of both ``Sized`` and ``Iterable[int]`` by static type checkers. This is known as *structural subtyping* (or static duck-typing):: - from typing import Iterator, Iterable + from collections.abc import Iterator, Iterable class Bucket: # Note: no base classes ... @@ -486,6 +491,19 @@ These can be used as types in annotations and do not support ``[]``. .. versionadded:: 3.5.4 .. versionadded:: 3.6.2 +.. data:: TypeAlias + + Special annotation for explicitly declaring a :ref:`type alias <type-aliases>`. + For example:: + + from typing import TypeAlias + + Factors: TypeAlias = list[int] + + See :pep:`613` for more details about explicit type aliases. + + .. versionadded:: 3.10 + Special forms """"""""""""" @@ -541,6 +559,10 @@ These can be used as types in annotations using ``[]``, each having a unique syn .. versionchanged:: 3.7 Don't remove explicit subclasses from unions at runtime. + .. versionchanged:: 3.10 + Unions can now be written as ``X | Y``. See + :ref:`union type expressions<types-union>`. + .. data:: Optional Optional type. @@ -658,7 +680,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn and should not be set on instances of that class. Usage:: class Starship: - stats: ClassVar[Dict[str, int]] = {} # class variable + stats: ClassVar[dict[str, int]] = {} # class variable damage: int = 10 # instance variable :data:`ClassVar` accepts only types and cannot be further subscribed. @@ -771,10 +793,10 @@ These can be used as types in annotations using ``[]``, each having a unique syn * ``Annotated`` can be used with nested and generic aliases:: T = TypeVar('T') - Vec = Annotated[List[Tuple[T, T]], MaxLen(10)] + Vec = Annotated[list[tuple[T, T]], MaxLen(10)] V = Vec[int] - V == Annotated[List[Tuple[int, int]], MaxLen(10)] + V == Annotated[list[tuple[int, int]], MaxLen(10)] .. versionadded:: 3.9 @@ -900,7 +922,7 @@ These are not used in annotations. They are building blocks for creating generic Such a protocol can be used with :func:`isinstance` and :func:`issubclass`. This raises :exc:`TypeError` when applied to a non-protocol class. This allows a simple-minded structural check, very similar to "one trick ponies" - in :mod:`collections.abc` such as :class:`Iterable`. For example:: + in :mod:`collections.abc` such as :class:`~collections.abc.Iterable`. For example:: @runtime_checkable class Closable(Protocol): @@ -1371,10 +1393,10 @@ Asynchronous programming The variance and order of type variables correspond to those of :class:`Generator`, for example:: - from typing import List, Coroutine - c = None # type: Coroutine[List[str], str, int] + from collections.abc import Coroutine + c = None # type: Coroutine[list[str], str, int] ... - x = c.send('hi') # type: List[str] + x = c.send('hi') # type: list[str] async def bar() -> None: x = await c # type: int @@ -1458,7 +1480,7 @@ Context manager types .. versionadded:: 3.6.0 .. deprecated:: 3.9 - :class:`collections.contextlib.AbstractContextManager` now supports ``[]``. See :pep:`585`. + :class:`contextlib.AbstractContextManager` now supports ``[]``. See :pep:`585`. .. class:: AsyncContextManager(Generic[T_co]) @@ -1468,7 +1490,7 @@ Context manager types .. versionadded:: 3.6.2 .. deprecated:: 3.9 - :class:`collections.contextlib.AbstractAsyncContextManager` now supports ``[]``. See :pep:`585`. + :class:`contextlib.AbstractAsyncContextManager` now supports ``[]``. See :pep:`585`. Protocols --------- @@ -1537,7 +1559,7 @@ Functions and decorators def process(response: None) -> None: ... @overload - def process(response: int) -> Tuple[int, str]: + def process(response: int) -> tuple[int, str]: ... @overload def process(response: bytes) -> str: @@ -1663,20 +1685,21 @@ Introspection helpers Check if a type is a :class:`TypedDict`. For example:: - class Film(TypedDict): - title: str - year: int - is_typeddict(Film) # => True - is_typeddict(Union[list, str]) # => False + class Film(TypedDict): + title: str + year: int + + is_typeddict(Film) # => True + is_typeddict(Union[list, str]) # => False .. versionadded:: 3.10 .. class:: ForwardRef A class used for internal typing representation of string forward references. - For example, ``List["SomeClass"]`` is implicitly transformed into - ``List[ForwardRef("SomeClass")]``. This class should not be instantiated by + For example, ``list["SomeClass"]`` is implicitly transformed into + ``list[ForwardRef("SomeClass")]``. This class should not be instantiated by a user, but may be used by introspection tools. Constant @@ -1702,7 +1725,7 @@ Constant If ``from __future__ import annotations`` is used in Python 3.7 or later, annotations are not evaluated at function definition time. - Instead, the are stored as strings in ``__annotations__``, + Instead, they are stored as strings in ``__annotations__``, This makes it unnecessary to use quotes around the annotation. (see :pep:`563`). diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index a52df9ee01..f04ec91270 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -1091,7 +1091,8 @@ Test cases If given, *logger* should be a :class:`logging.Logger` object or a :class:`str` giving the name of a logger. The default is the root - logger, which will catch all messages. + logger, which will catch all messages that were not blocked by a + non-propagating descendent logger. If given, *level* should be either a numeric logging level or its string equivalent (for example either ``"ERROR"`` or diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index 7725e4d158..f4bccf6609 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -251,12 +251,18 @@ We can remove elements using :meth:`Element.remove`. Let's say we want to remove all countries with a rank higher than 50:: >>> for country in root.findall('country'): + ... # using root.findall() to avoid removal during traversal ... rank = int(country.find('rank').text) ... if rank > 50: ... root.remove(country) ... >>> tree.write('output.xml') +Note that concurrent modification while iterating can lead to problems, +just like when iterating and modifying Python lists or dicts. +Therefore, the example first collects all matching elements with +``root.findall()``, and only then iterates over the list of matches. + Our XML now looks like this: .. code-block:: xml |