Mailman 3 April 2022 - Python-checkins

Rephrase typing.assert_never docs (#92061)
by JelleZijlstra April 30, 2022

April 30, 2022

https://github.com/python/cpython/commit/2f7952c35b8fb2487cb9749081d2c0c604… commit: 2f7952c35b8fb2487cb9749081d2c0c604d41107 branch: main author: Shantanu <12621235+hauntsaninja(a)users.noreply.github.com> committer: JelleZijlstra <jelle.zijlstra(a)gmail.com> date: 2022-04-29T21:13:21-06:00 summary: Rephrase typing.assert_never docs (#92061) This change is similar to that in #32069 files: M Doc/library/typing.rst diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 0f31b90b7610e..426cbf12b8c92 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -2337,7 +2337,7 @@ Functions and decorators .. function:: assert_never(arg, /) - Assert to the type checker that a line of code is unreachable. + Ask a static type checker to confirm that a line of code is unreachable. Example:: @@ -2358,7 +2358,7 @@ Functions and decorators reachable, it will emit an error. For example, if the type annotation for ``arg`` was instead ``int | str | float``, the type checker would emit an error pointing out that ``unreachable`` is of type :class:`float`. - For a call to ``assert_never`` to succeed, the inferred type of + For a call to ``assert_never`` to pass type checking, the inferred type of the argument passed in must be the bottom type, :data:`Never`, and nothing else.

1 0

gh-91491: Add several typing features to What's New (#92060)
by JelleZijlstra April 30, 2022

April 30, 2022

https://github.com/python/cpython/commit/d0064a1e72c6709ede3f2ac1db109c9208… commit: d0064a1e72c6709ede3f2ac1db109c9208d42eb0 branch: main author: Shantanu <12621235+hauntsaninja(a)users.noreply.github.com> committer: JelleZijlstra <jelle.zijlstra(a)gmail.com> date: 2022-04-29T21:12:45-06:00 summary: gh-91491: Add several typing features to What's New (#92060) This gets all the major items in #91491. However, I didn't get around to adding what's new entries for the large clump of changes in the last bullet point in the issue. Co-authored-by: Jelle Zijlstra <jelle.zijlstra(a)gmail.com> files: M Doc/whatsnew/3.11.rst diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 3ba35a8620a56..fdd35ce14317e 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -297,6 +297,38 @@ See :pep:`675` for more details. (Contributed by Jelle Zijlstra in :issue:`47088`. PEP written by Pradeep Kumar Srinivasan and Graham Bleaney.) +PEP 681: Data Class Transforms +------------------------------ + +The new :data:`~typing.dataclass_transform` annotation may be used to +decorate a function that is itself a decorator, a class, or a metaclass. +The presence of ``@dataclass_transform()`` tells a static type checker that the +decorated function, class, or metaclass performs runtime "magic" that +transforms a class, endowing it with dataclass-like behaviors. + +For example:: + + # The ``create_model`` decorator is defined by a library. + @typing.dataclass_transform() + def create_model(cls: Type[_T]) -> Type[_T]: + cls.__init__ = ... + cls.__eq__ = ... + cls.__ne__ = ... + return cls + + # The ``create_model`` decorator can now be used to create new model + # classes, like this: + @create_model + class CustomerModel: + id: int + name: str + + c = CustomerModel(id=327, name="John Smith") + +See :pep:`681` for more details. + +(Contributed by Jelle Zijlstra in :gh:`91860`. PEP written by +Erik De Bonte and Eric Traut.) Other Language Changes ====================== @@ -649,6 +681,39 @@ time it had a resolution of 1 millisecond (10\ :sup:`-3` seconds). (Contributed by Benjamin Szőke, Dong-hee Na, Eryk Sun and Victor Stinner in :issue:`21302` and :issue:`45429`.) +typing +------ + +For major changes, see :ref:`new-feat-related-type-hints-311`. + +* Add :func:`typing.assert_never` and :class:`typing.Never`. + :func:`typing.assert_never` is useful for asking a type checker to confirm + that a line of code is not reachable. At runtime, it raises an + :exc:`AssertionError`. + (Contributed by Jelle Zijlstra in :gh:`90633`.) + +* Add :func:`typing.reveal_type`. This is useful for asking a type checker + what type it has inferred for a given expression. At runtime it prints + the type of the received value. + (Contributed by Jelle Zijlstra in :gh:`90572`.) + +* Add :func:`typing.assert_type`. This is useful for asking a type checker + to confirm that the type it has inferred for a given expression matches + the given type. At runtime it simply returns the received value. + (Contributed by Jelle Zijlstra in :gh:`90638`.) + +* Allow subclassing of :class:`typing.Any`. This is useful for avoiding + type checker errors related to highly dynamic class, such as mocks. + (Contributed by Shantanu Jain in :gh:`91154`.) + +* The :func:`typing.final` decorator now sets the ``__final__`` attributed on + the decorated object. + (Contributed by Jelle Zijlstra in :gh:`90500`.) + +* The :func:`typing.get_overloads` function can be used for introspecting + the overloads of a function. :func:`typing.clear_overloads` can be used + to clear all registered overloads of a function. + (Contributed by Jelle Zijlstra in :gh:`89263`.) unicodedata -----------

1 0

gh-91217: deprecate xdrlib (GH-92066)
by miss-islington April 30, 2022

April 30, 2022

https://github.com/python/cpython/commit/c2b579741dc36f4b7da00d4361d6515449… commit: c2b579741dc36f4b7da00d4361d651544996d8f4 branch: main author: Brett Cannon <brett(a)python.org> committer: miss-islington <31488909+miss-islington(a)users.noreply.github.com> date: 2022-04-29T18:22:10-07:00 summary: gh-91217: deprecate xdrlib (GH-92066) Automerge-Triggered-By: GH:brettcannon files: A Misc/NEWS.d/next/Library/2022-04-21-21-06-54.gh-issue-91217.2cVma_.rst M Doc/whatsnew/3.11.rst M Lib/test/test_xdrlib.py M Lib/xdrlib.py diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 5f1f995a0fe2f..3ba35a8620a56 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -1081,6 +1081,7 @@ Deprecated * :mod:`sunau` * :mod:`telnetlib` * :mod:`uu` + * :mod:`xdrlib` (Contributed by Brett Cannon in :issue:`47061` and Victor Stinner in :gh:`68966`.) diff --git a/Lib/test/test_xdrlib.py b/Lib/test/test_xdrlib.py index 3df5f264ced46..226b70ae87b0b 100644 --- a/Lib/test/test_xdrlib.py +++ b/Lib/test/test_xdrlib.py @@ -1,6 +1,8 @@ import unittest +from test.support import warnings_helper + +xdrlib = warnings_helper.import_deprecated("xdrlib") -import xdrlib class XDRTest(unittest.TestCase): diff --git a/Lib/xdrlib.py b/Lib/xdrlib.py index d6e1aeb527266..b56ffa59b73dc 100644 --- a/Lib/xdrlib.py +++ b/Lib/xdrlib.py @@ -7,6 +7,9 @@ import struct from io import BytesIO from functools import wraps +import warnings + +warnings._deprecated(__name__, remove=(3, 13)) __all__ = ["Error", "Packer", "Unpacker", "ConversionError"] diff --git a/Misc/NEWS.d/next/Library/2022-04-21-21-06-54.gh-issue-91217.2cVma_.rst b/Misc/NEWS.d/next/Library/2022-04-21-21-06-54.gh-issue-91217.2cVma_.rst new file mode 100644 index 0000000000000..14f2c4d06491b --- /dev/null +++ b/Misc/NEWS.d/next/Library/2022-04-21-21-06-54.gh-issue-91217.2cVma_.rst @@ -0,0 +1 @@ +Deprecate the xdrlib module.

1 0

Fix indentation for typing.Unpack docs (#92058)
by JelleZijlstra April 29, 2022

April 29, 2022

https://github.com/python/cpython/commit/7861a9e3276cf9bf2bfa56d86f29ef06b2… commit: 7861a9e3276cf9bf2bfa56d86f29ef06b2456f87 branch: main author: Jelle Zijlstra <jelle.zijlstra(a)gmail.com> committer: JelleZijlstra <jelle.zijlstra(a)gmail.com> date: 2022-04-29T16:58:40-06:00 summary: Fix indentation for typing.Unpack docs (#92058) https://docs.python.org/3.11/library/typing.html#typing.Unpack files: M Doc/library/typing.rst diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 0de380551c9fb..0f31b90b7610e 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1368,27 +1368,27 @@ These are not used in annotations. They are building blocks for creating generic .. data:: Unpack - A typing operator that conceptually marks an object as having been - unpacked. For example, using the unpack operator ``*`` on a - :class:`type variable tuple <TypeVarTuple>` is equivalent to using ``Unpack`` - to mark the type variable tuple as having been unpacked:: - - Ts = TypeVarTuple('Ts') - tup: tuple[*Ts] - # Effectively does: - tup: tuple[Unpack[Ts]] - - In fact, ``Unpack`` can be used interchangeably with ``*`` in the context - of types. You might see ``Unpack`` being used explicitly in older versions - of Python, where ``*`` couldn't be used in certain places:: - - # In older versions of Python, TypeVarTuple and Unpack - # are located in the `typing_extensions` backports package. - from typing_extensions import TypeVarTuple, Unpack - - Ts = TypeVarTuple('Ts') - tup: tuple[*Ts] # Syntax error on Python <= 3.10! - tup: tuple[Unpack[Ts]] # Semantically equivalent, and backwards-compatible + A typing operator that conceptually marks an object as having been + unpacked. For example, using the unpack operator ``*`` on a + :class:`type variable tuple <TypeVarTuple>` is equivalent to using ``Unpack`` + to mark the type variable tuple as having been unpacked:: + + Ts = TypeVarTuple('Ts') + tup: tuple[*Ts] + # Effectively does: + tup: tuple[Unpack[Ts]] + + In fact, ``Unpack`` can be used interchangeably with ``*`` in the context + of types. You might see ``Unpack`` being used explicitly in older versions + of Python, where ``*`` couldn't be used in certain places:: + + # In older versions of Python, TypeVarTuple and Unpack + # are located in the `typing_extensions` backports package. + from typing_extensions import TypeVarTuple, Unpack + + Ts = TypeVarTuple('Ts') + tup: tuple[*Ts] # Syntax error on Python <= 3.10! + tup: tuple[Unpack[Ts]] # Semantically equivalent, and backwards-compatible .. versionadded:: 3.11

1 0

sorting howto: Add clarification on < using __lt__ (GH-92010)
by miss-islington April 29, 2022

April 29, 2022

https://github.com/python/cpython/commit/869a89433899950f925d177bacd8fdd43a… commit: 869a89433899950f925d177bacd8fdd43affe827 branch: 3.9 author: Miss Islington (bot) <31488909+miss-islington(a)users.noreply.github.com> committer: miss-islington <31488909+miss-islington(a)users.noreply.github.com> date: 2022-04-29T15:26:51-07:00 summary: sorting howto: Add clarification on < using __lt__ (GH-92010) (cherry picked from commit 53ca774497fde7c5fcf3a84813ea42f95f75c639) Co-authored-by: slateny <46876382+slateny(a)users.noreply.github.com> files: M Doc/howto/sorting.rst diff --git a/Doc/howto/sorting.rst b/Doc/howto/sorting.rst index a8efe65353d6e..be017cfba35ff 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

1 0

sorting howto: Add clarification on < using __lt__ (GH-92010)
by miss-islington April 29, 2022

April 29, 2022

https://github.com/python/cpython/commit/7149b21c2e990d1b641bc71c6ffc3cb153… commit: 7149b21c2e990d1b641bc71c6ffc3cb153d0500d branch: 3.10 author: Miss Islington (bot) <31488909+miss-islington(a)users.noreply.github.com> committer: miss-islington <31488909+miss-islington(a)users.noreply.github.com> date: 2022-04-29T15:25:31-07:00 summary: sorting howto: Add clarification on < using __lt__ (GH-92010) (cherry picked from commit 53ca774497fde7c5fcf3a84813ea42f95f75c639) Co-authored-by: slateny <46876382+slateny(a)users.noreply.github.com> files: M Doc/howto/sorting.rst diff --git a/Doc/howto/sorting.rst b/Doc/howto/sorting.rst index 37328c82dff27..32b47711f8570 100644 --- a/Doc/howto/sorting.rst +++ b/Doc/howto/sorting.rst @@ -325,7 +325,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: @@ -335,6 +335,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

1 0

sorting howto: Add clarification on < using __lt__ (#92010)
by JelleZijlstra April 29, 2022

April 29, 2022

https://github.com/python/cpython/commit/53ca774497fde7c5fcf3a84813ea42f95f… commit: 53ca774497fde7c5fcf3a84813ea42f95f75c639 branch: main author: slateny <46876382+slateny(a)users.noreply.github.com> committer: JelleZijlstra <jelle.zijlstra(a)gmail.com> date: 2022-04-29T16:08:07-06:00 summary: sorting howto: Add clarification on < using __lt__ (#92010) files: M Doc/howto/sorting.rst diff --git a/Doc/howto/sorting.rst b/Doc/howto/sorting.rst index 37328c82dff27..32b47711f8570 100644 --- a/Doc/howto/sorting.rst +++ b/Doc/howto/sorting.rst @@ -325,7 +325,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: @@ -335,6 +335,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

1 0

bpo-44791: Accept ellipsis as the last argument of typing.Concatenate (#30969)
by JelleZijlstra April 29, 2022

April 29, 2022

https://github.com/python/cpython/commit/81120b6754c67a8f1f00cbc3af6963c0e1… commit: 81120b6754c67a8f1f00cbc3af6963c0e1945911 branch: main author: Serhiy Storchaka <storchaka(a)gmail.com> committer: JelleZijlstra <jelle.zijlstra(a)gmail.com> date: 2022-04-29T15:01:40-06:00 summary: bpo-44791: Accept ellipsis as the last argument of typing.Concatenate (#30969) files: A Misc/NEWS.d/next/Library/2022-01-27-14-46-15.bpo-44791.tR1JFG.rst M Doc/library/typing.rst M Lib/test/test_typing.py M Lib/typing.py diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index d4a6f32aa36d2..0de380551c9fb 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -852,7 +852,8 @@ These can be used as types in annotations using ``[]``, each having a unique syn callable. Usage is in the form ``Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable]``. ``Concatenate`` is currently only valid when used as the first argument to a :data:`Callable`. - The last parameter to ``Concatenate`` must be a :class:`ParamSpec`. + The last parameter to ``Concatenate`` must be a :class:`ParamSpec` or + ellipsis (``...``). For example, to annotate a decorator ``with_lock`` which provides a :class:`threading.Lock` to the decorated function, ``Concatenate`` can be diff --git a/Lib/test/test_typing.py b/Lib/test/test_typing.py index dab549b17e149..929f0df960ae0 100644 --- a/Lib/test/test_typing.py +++ b/Lib/test/test_typing.py @@ -1755,8 +1755,7 @@ def test_concatenate(self): self.assertEqual(C[[], int], Callable[[int], int]) self.assertEqual(C[Concatenate[str, P2], int], Callable[Concatenate[int, str, P2], int]) - with self.assertRaises(TypeError): - C[..., int] + self.assertEqual(C[..., int], Callable[Concatenate[int, ...], int]) C = Callable[Concatenate[int, P], int] self.assertEqual(repr(C), @@ -1767,8 +1766,7 @@ def test_concatenate(self): self.assertEqual(C[[]], Callable[[int], int]) self.assertEqual(C[Concatenate[str, P2]], Callable[Concatenate[int, str, P2], int]) - with self.assertRaises(TypeError): - C[...] + self.assertEqual(C[...], Callable[Concatenate[int, ...], int]) def test_errors(self): Callable = self.Callable @@ -6739,8 +6737,7 @@ def test_var_substitution(self): self.assertEqual(C[int, []], (int,)) self.assertEqual(C[int, Concatenate[str, P2]], Concatenate[int, str, P2]) - with self.assertRaises(TypeError): - C[int, ...] + self.assertEqual(C[int, ...], Concatenate[int, ...]) C = Concatenate[int, P] self.assertEqual(C[P2], Concatenate[int, P2]) @@ -6748,8 +6745,7 @@ def test_var_substitution(self): self.assertEqual(C[str, float], (int, str, float)) self.assertEqual(C[[]], (int,)) self.assertEqual(C[Concatenate[str, P2]], Concatenate[int, str, P2]) - with self.assertRaises(TypeError): - C[...] + self.assertEqual(C[...], Concatenate[int, ...]) class TypeGuardTests(BaseTestCase): def test_basics(self): diff --git a/Lib/typing.py b/Lib/typing.py index f4d4fa4d6713c..b250f2992dfff 100644 --- a/Lib/typing.py +++ b/Lib/typing.py @@ -714,9 +714,9 @@ def Concatenate(self, parameters): raise TypeError("Cannot take a Concatenate of no types.") if not isinstance(parameters, tuple): parameters = (parameters,) - if not isinstance(parameters[-1], ParamSpec): + if not (parameters[-1] is ... or isinstance(parameters[-1], ParamSpec)): raise TypeError("The last parameter to Concatenate should be a " - "ParamSpec variable.") + "ParamSpec variable or ellipsis.") msg = "Concatenate[arg, ...]: each arg must be a type." parameters = (*(_type_check(p, msg) for p in parameters[:-1]), parameters[-1]) return _ConcatenateGenericAlias(self, parameters, @@ -1641,9 +1641,6 @@ def copy_with(self, params): return (*params[:-1], *params[-1]) if isinstance(params[-1], _ConcatenateGenericAlias): params = (*params[:-1], *params[-1].__args__) - elif not isinstance(params[-1], ParamSpec): - raise TypeError("The last parameter to Concatenate should be a " - "ParamSpec variable.") return super().copy_with(params) diff --git a/Misc/NEWS.d/next/Library/2022-01-27-14-46-15.bpo-44791.tR1JFG.rst b/Misc/NEWS.d/next/Library/2022-01-27-14-46-15.bpo-44791.tR1JFG.rst new file mode 100644 index 0000000000000..31c6dcc058e94 --- /dev/null +++ b/Misc/NEWS.d/next/Library/2022-01-27-14-46-15.bpo-44791.tR1JFG.rst @@ -0,0 +1 @@ +Accept ellipsis as the last argument of :data:`typing.Concatenate`.

1 0

gh-87390: Add tests demonstrating current type variable substitution behaviour (#32341)
by JelleZijlstra April 29, 2022

April 29, 2022

https://github.com/python/cpython/commit/f6656163de483003697d510031827b7512… commit: f6656163de483003697d510031827b7512056d55 branch: main author: Matthew Rahtz <matthew.rahtz(a)gmail.com> committer: JelleZijlstra <jelle.zijlstra(a)gmail.com> date: 2022-04-29T14:03:21-06:00 summary: gh-87390: Add tests demonstrating current type variable substitution behaviour (#32341) files: M Lib/test/test_typing.py diff --git a/Lib/test/test_typing.py b/Lib/test/test_typing.py index a904b7a790c04..dab549b17e149 100644 --- a/Lib/test/test_typing.py +++ b/Lib/test/test_typing.py @@ -3,6 +3,7 @@ from collections import defaultdict from functools import lru_cache, wraps import inspect +import itertools import pickle import re import sys @@ -476,6 +477,392 @@ def test_bad_var_substitution(self): list[T][arg] +def template_replace(templates: list[str], replacements: dict[str, list[str]]) -> list[tuple[str]]: + """Renders templates with possible combinations of replacements. + + Example 1: Suppose that: + templates = ["dog_breed are awesome", "dog_breed are cool"] + replacements = ["dog_breed": ["Huskies", "Beagles"]] + Then we would return: + [ + ("Huskies are awesome", "Huskies are cool"), + ("Beagles are awesome", "Beagles are cool") + ] + + Example 2: Suppose that: + templates = ["Huskies are word1 but also word2"] + replacements = {"word1": ["playful", "cute"], + "word2": ["feisty", "tiring"]} + Then we would return: + [ + ("Huskies are playful but also feisty"), + ("Huskies are playful but also tiring"), + ("Huskies are cute but also feisty"), + ("Huskies are cute but also tiring") + ] + + Note that if any of the replacements do not occur in any template: + templates = ["Huskies are word1", "Beagles!"] + replacements = {"word1": ["playful", "cute"], + "word2": ["feisty", "tiring"]} + Then we do not generate duplicates, returning: + [ + ("Huskies are playful", "Beagles!"), + ("Huskies are cute", "Beagles!") + ] + """ + # First, build a structure like: + # [ + # [("word1", "playful"), ("word1", "cute")], + # [("word2", "feisty"), ("word2", "tiring")] + # ] + replacement_combos = [] + for original, possible_replacements in replacements.items(): + original_replacement_tuples = [] + for replacement in possible_replacements: + original_replacement_tuples.append((original, replacement)) + replacement_combos.append(original_replacement_tuples) + + # Second, generate rendered templates, including possible duplicates. + rendered_templates = [] + for replacement_combo in itertools.product(*replacement_combos): + # replacement_combo would be e.g. + # [("word1", "playful"), ("word2", "feisty")] + templates_with_replacements = [] + for template in templates: + for original, replacement in replacement_combo: + template = template.replace(original, replacement) + templates_with_replacements.append(template) + rendered_templates.append(tuple(templates_with_replacements)) + + # Finally, remove the duplicates (but keep the order). + rendered_templates_no_duplicates = [] + for x in rendered_templates: + # Inefficient, but should be fine for our purposes. + if x not in rendered_templates_no_duplicates: + rendered_templates_no_duplicates.append(x) + + return rendered_templates_no_duplicates + + +class TemplateReplacementTests(BaseTestCase): + + def test_two_templates_two_replacements_yields_correct_renders(self): + actual = template_replace( + templates=["Cats are word1", "Dogs are word2"], + replacements={ + "word1": ["small", "cute"], + "word2": ["big", "fluffy"], + }, + ) + expected = [ + ("Cats are small", "Dogs are big"), + ("Cats are small", "Dogs are fluffy"), + ("Cats are cute", "Dogs are big"), + ("Cats are cute", "Dogs are fluffy"), + ] + self.assertEqual(actual, expected) + + def test_no_duplicates_if_replacement_not_in_templates(self): + actual = template_replace( + templates=["Cats are word1", "Dogs!"], + replacements={ + "word1": ["small", "cute"], + "word2": ["big", "fluffy"], + }, + ) + expected = [ + ("Cats are small", "Dogs!"), + ("Cats are cute", "Dogs!"), + ] + self.assertEqual(actual, expected) + + +class GenericAliasSubstitutionTests(BaseTestCase): + """Tests for type variable substitution in generic aliases. + + Note that the expected results here are tentative, based on a + still-being-worked-out spec for what we allow at runtime (given that + implementation of *full* substitution logic at runtime would add too much + complexity to typing.py). This spec is currently being discussed at + https://github.com/python/cpython/issues/91162. + """ + + def test_one_parameter(self): + T = TypeVar('T') + Ts = TypeVarTuple('Ts') + + class C(Generic[T]): pass + + generics = ['C', 'list', 'List'] + tuple_types = ['tuple', 'Tuple'] + + tests = [ + # Alias # Args # Expected result + ('generic[T]', '[()]', 'TypeError'), + ('generic[T]', '[int]', 'generic[int]'), + ('generic[T]', '[int, str]', 'TypeError'), + ('generic[T]', '[tuple_type[int, ...]]', 'generic[tuple_type[int, ...]]'), + # Should raise TypeError: a) according to the tentative spec, + # unpacked types cannot be used as arguments to aliases that expect + # a fixed number of arguments; b) it's equivalent to generic[()]. + ('generic[T]', '[*tuple[()]]', 'generic[*tuple[()]]'), + ('generic[T]', '[*Tuple[()]]', 'TypeError'), + # Should raise TypeError according to the tentative spec: unpacked + # types cannot be used as arguments to aliases that expect a fixed + # number of arguments. + ('generic[T]', '[*tuple[int]]', 'generic[*tuple[int]]'), + ('generic[T]', '[*Tuple[int]]', 'TypeError'), + # Ditto. + ('generic[T]', '[*tuple[int, str]]', 'generic[*tuple[int, str]]'), + ('generic[T]', '[*Tuple[int, str]]', 'TypeError'), + # Ditto. + ('generic[T]', '[*tuple[int, ...]]', 'generic[*tuple[int, ...]]'), + ('generic[T]', '[*Tuple[int, ...]]', 'TypeError'), + ('generic[T]', '[*Ts]', 'TypeError'), + ('generic[T]', '[T, *Ts]', 'TypeError'), + ('generic[T]', '[*Ts, T]', 'TypeError'), + # Raises TypeError because C is not variadic. + # (If C _were_ variadic, it'd be fine.) + ('C[T, *tuple_type[int, ...]]', '[int]', 'TypeError'), + # Should definitely raise TypeError: list only takes one argument. + ('list[T, *tuple_type[int, ...]]', '[int]', 'list[int, *tuple_type[int, ...]]'), + ('List[T, *tuple_type[int, ...]]', '[int]', 'TypeError'), + ] + + for alias_template, args_template, expected_template in tests: + rendered_templates = template_replace( + templates=[alias_template, args_template, expected_template], + replacements={'generic': generics, 'tuple_type': tuple_types} + ) + for alias_str, args_str, expected_str in rendered_templates: + with self.subTest(alias=alias_str, args=args_str, expected=expected_str): + if expected_str == 'TypeError': + with self.assertRaises(TypeError): + eval(alias_str + args_str) + else: + self.assertEqual( + eval(alias_str + args_str), + eval(expected_str) + ) + + + def test_two_parameters(self): + T1 = TypeVar('T1') + T2 = TypeVar('T2') + Ts = TypeVarTuple('Ts') + + class C(Generic[T1, T2]): pass + + generics = ['C', 'dict', 'Dict'] + tuple_types = ['tuple', 'Tuple'] + + tests = [ + # Alias # Args # Expected result + ('generic[T1, T2]', '[()]', 'TypeError'), + ('generic[T1, T2]', '[int]', 'TypeError'), + ('generic[T1, T2]', '[int, str]', 'generic[int, str]'), + ('generic[T1, T2]', '[int, str, bool]', 'TypeError'), + ('generic[T1, T2]', '[*tuple_type[int]]', 'TypeError'), + ('generic[T1, T2]', '[*tuple_type[int, str]]', 'TypeError'), + ('generic[T1, T2]', '[*tuple_type[int, str, bool]]', 'TypeError'), + + # Should raise TypeError according to the tentative spec: unpacked + # types cannot be used as arguments to aliases that expect a fixed + # number of arguments. + ('generic[T1, T2]', '[*tuple[int, str], *tuple[float, bool]]', 'generic[*tuple[int, str], *tuple[float, bool]]'), + ('generic[T1, T2]', '[*Tuple[int, str], *Tuple[float, bool]]', 'TypeError'), + + ('generic[T1, T2]', '[tuple_type[int, ...]]', 'TypeError'), + ('generic[T1, T2]', '[tuple_type[int, ...], tuple_type[str, ...]]', 'generic[tuple_type[int, ...], tuple_type[str, ...]]'), + ('generic[T1, T2]', '[*tuple_type[int, ...]]', 'TypeError'), + + # Ditto. + ('generic[T1, T2]', '[*tuple[int, ...], *tuple[str, ...]]', 'generic[*tuple[int, ...], *tuple[str, ...]]'), + ('generic[T1, T2]', '[*Tuple[int, ...], *Tuple[str, ...]]', 'TypeError'), + + ('generic[T1, T2]', '[*Ts]', 'TypeError'), + ('generic[T1, T2]', '[T, *Ts]', 'TypeError'), + ('generic[T1, T2]', '[*Ts, T]', 'TypeError'), + # Should raise TypeError according to the tentative spec: unpacked + # types cannot be used as arguments to generics that expect a fixed + # number of arguments. + # (None of the things in `generics` were defined using *Ts.) + ('generic[T1, *tuple_type[int, ...]]', '[str]', 'generic[str, *tuple_type[int, ...]]'), + ] + + for alias_template, args_template, expected_template in tests: + rendered_templates = template_replace( + templates=[alias_template, args_template, expected_template], + replacements={'generic': generics, 'tuple_type': tuple_types} + ) + for alias_str, args_str, expected_str in rendered_templates: + with self.subTest(alias=alias_str, args=args_str, expected=expected_str): + if expected_str == 'TypeError': + with self.assertRaises(TypeError): + eval(alias_str + args_str) + else: + self.assertEqual( + eval(alias_str + args_str), + eval(expected_str) + ) + + def test_three_parameters(self): + T1 = TypeVar('T1') + T2 = TypeVar('T2') + T3 = TypeVar('T3') + + class C(Generic[T1, T2, T3]): pass + + generics = ['C'] + tuple_types = ['tuple', 'Tuple'] + + tests = [ + # Alias # Args # Expected result + ('generic[T1, bool, T2]', '[int, str]', 'generic[int, bool, str]'), + ('generic[T1, bool, T2]', '[*tuple_type[int, str]]', 'TypeError'), + ] + + for alias_template, args_template, expected_template in tests: + rendered_templates = template_replace( + templates=[alias_template, args_template, expected_template], + replacements={'generic': generics, 'tuple_type': tuple_types} + ) + for alias_str, args_str, expected_str in rendered_templates: + with self.subTest(alias=alias_str, args=args_str, expected=expected_str): + if expected_str == 'TypeError': + with self.assertRaises(TypeError): + eval(alias_str + args_str) + else: + self.assertEqual( + eval(alias_str + args_str), + eval(expected_str) + ) + + def test_variadic_parameters(self): + T1 = TypeVar('T1') + T2 = TypeVar('T2') + Ts = TypeVarTuple('Ts') + + class C(Generic[*Ts]): pass + + generics = ['C', 'tuple', 'Tuple'] + tuple_types = ['tuple', 'Tuple'] + + # The majority of these have three separate cases for C, tuple and + # Tuple because tuple currently behaves differently. + tests = [ + # Alias # Args # Expected result + ('C[*Ts]', '[()]', 'C[()]'), + ('tuple[*Ts]', '[()]', 'TypeError'), # Should be tuple[()] + ('Tuple[*Ts]', '[()]', 'Tuple[()]'), + + ('C[*Ts]', '[int]', 'C[int]'), + ('tuple[*Ts]', '[int]', 'tuple[(int,),]'), # Should be tuple[int] + ('Tuple[*Ts]', '[int]', 'Tuple[int]'), + + ('C[*Ts]', '[int, str]', 'C[int, str]'), + ('tuple[*Ts]', '[int, str]', 'TypeError'), # Should be tuple[int, str] + ('Tuple[*Ts]', '[int, str]', 'Tuple[int, str]'), + + ('C[*Ts]', '[*tuple_type[int]]', 'C[*tuple_type[int]]'), # Should be C[int] + ('tuple[*Ts]', '[*tuple_type[int]]', 'tuple[(*tuple_type[int],),]'), # Should be tuple[int] + ('Tuple[*Ts]', '[*tuple_type[int]]', 'Tuple[*tuple_type[int]]'), # Should be Tuple[int] + + ('C[*Ts]', '[*tuple_type[*Ts]]', 'C[*tuple_type[*Ts]]'), # Should be C[*Ts] + ('tuple[*Ts]', '[*tuple_type[*Ts]]', 'tuple[(*tuple_type[*Ts],),]'), # Should be tuple[*Ts] + ('Tuple[*Ts]', '[*tuple_type[*Ts]]', 'Tuple[*tuple_type[*Ts]]'), # Should be Tuple[*Ts] + + ('C[*Ts]', '[*tuple_type[int, str]]', 'C[*tuple_type[int, str]]'), # Should be C[int, str] + ('tuple[*Ts]', '[*tuple_type[int, str]]', 'tuple[(*tuple_type[int, str],),]'), # Should be tuple[int, str] + ('Tuple[*Ts]', '[*tuple_type[int, str]]', 'Tuple[*tuple_type[int, str]]'), # Should be Tuple[int, str] + + ('C[*Ts]', '[tuple_type[int, ...]]', 'C[tuple_type[int, ...]]'), + ('tuple[*Ts]', '[tuple_type[int, ...]]', 'tuple[(tuple_type[int, ...],),]'), # Should be tuple[tuple_type[int, ...]] + ('Tuple[*Ts]', '[tuple_type[int, ...]]', 'Tuple[tuple_type[int, ...]]'), + + ('C[*Ts]', '[tuple_type[int, ...], tuple_type[str, ...]]', 'C[tuple_type[int, ...], tuple_type[str, ...]]'), + ('tuple[*Ts]', '[tuple_type[int, ...], tuple_type[str, ...]]', 'TypeError'), # Should be tuple[tuple_type[int, ...], tuple_type[str, ...]] + ('Tuple[*Ts]', '[tuple_type[int, ...], tuple_type[str, ...]]', 'Tuple[tuple_type[int, ...], tuple_type[str, ...]]'), + + ('C[*Ts]', '[*tuple_type[int, ...]]', 'C[*tuple_type[int, ...]]'), + ('tuple[*Ts]', '[*tuple_type[int, ...]]', 'tuple[(*tuple_type[int, ...],),]'), # Should be tuple[*tuple_type[int, ...]] + ('Tuple[*Ts]', '[*tuple_type[int, ...]]', 'Tuple[*tuple_type[int, ...]]'), + + # Technically, multiple unpackings are forbidden by PEP 646, but we + # choose to be less restrictive at runtime, to allow folks room + # to experiment. So all three of these should be valid. + ('C[*Ts]', '[*tuple_type[int, ...], *tuple_type[str, ...]]', 'C[*tuple_type[int, ...], *tuple_type[str, ...]]'), + # Should be tuple[*tuple_type[int, ...], *tuple_type[str, ...]], to match the other two. + ('tuple[*Ts]', '[*tuple_type[int, ...], *tuple_type[str, ...]]', 'TypeError'), + ('Tuple[*Ts]', '[*tuple_type[int, ...], *tuple_type[str, ...]]', 'Tuple[*tuple_type[int, ...], *tuple_type[str, ...]]'), + + ('C[*Ts]', '[*Ts]', 'C[*Ts]'), + ('tuple[*Ts]', '[*Ts]', 'tuple[(*Ts,),]'), # Should be tuple[*Ts] + ('Tuple[*Ts]', '[*Ts]', 'Tuple[*Ts]'), + + ('C[*Ts]', '[T, *Ts]', 'C[T, *Ts]'), + ('tuple[*Ts]', '[T, *Ts]', 'TypeError'), # Should be tuple[T, *Ts] + ('Tuple[*Ts]', '[T, *Ts]', 'Tuple[T, *Ts]'), + + ('C[*Ts]', '[*Ts, T]', 'C[*Ts, T]'), + ('tuple[*Ts]', '[*Ts, T]', 'TypeError'), # Should be tuple[*Ts, T] + ('Tuple[*Ts]', '[*Ts, T]', 'Tuple[*Ts, T]'), + + ('C[T, *Ts]', '[int]', 'C[int]'), + ('tuple[T, *Ts]', '[int]', 'TypeError'), # Should be tuple[int] + ('Tuple[T, *Ts]', '[int]', 'Tuple[int]'), + + ('C[T, *Ts]', '[int, str]', 'C[int, str]'), + ('tuple[T, *Ts]', '[int, str]', 'tuple[int, (str,)]'), # Should be tuple[int, str] + ('Tuple[T, *Ts]', '[int, str]', 'Tuple[int, str]'), + + ('C[T, *Ts]', '[int, str, bool]', 'C[int, str, bool]'), + ('tuple[T, *Ts]', '[int, str, bool]', 'TypeError'), # Should be tuple[int, str, bool] + ('Tuple[T, *Ts]', '[int, str, bool]', 'Tuple[int, str, bool]'), + + ('C[T, *Ts]', '[*tuple[int, ...]]', 'C[*tuple[int, ...]]'), # Should be C[int, *tuple[int, ...]] + ('C[T, *Ts]', '[*Tuple[int, ...]]', 'TypeError'), # Ditto + ('tuple[T, *Ts]', '[*tuple_type[int, ...]]', 'TypeError'), # Should be tuple[int, *tuple[int, ...]] + ('Tuple[T, *Ts]', '[*tuple[int, ...]]', 'Tuple[*tuple[int, ...]]'), # Ditto + ('Tuple[T, *Ts]', '[*Tuple[int, ...]]', 'TypeError'), # Ditto + + ('C[*Ts, T]', '[int]', 'C[int]'), + ('tuple[*Ts, T]', '[int]', 'TypeError'), # Should be tuple[int] + ('Tuple[*Ts, T]', '[int]', 'Tuple[int]'), + + ('C[*Ts, T]', '[int, str]', 'C[int, str]'), + ('tuple[*Ts, T]', '[int, str]', 'tuple[(int,), str]'), # Should be tuple[int, str] + ('Tuple[*Ts, T]', '[int, str]', 'Tuple[int, str]'), + + ('C[*Ts, T]', '[int, str, bool]', 'C[int, str, bool]'), + ('tuple[*Ts, T]', '[int, str, bool]', 'TypeError'), # Should be tuple[int, str, bool] + ('Tuple[*Ts, T]', '[int, str, bool]', 'Tuple[int, str, bool]'), + + ('generic[T, *tuple_type[int, ...]]', '[str]', 'generic[str, *tuple_type[int, ...]]'), + ('generic[T1, T2, *tuple_type[int, ...]]', '[str, bool]', 'generic[str, bool, *tuple_type[int, ...]]'), + ('generic[T1, *tuple_type[int, ...], T2]', '[str, bool]', 'generic[str, *tuple_type[int, ...], bool]'), + ('generic[T1, *tuple_type[int, ...], T2]', '[str, bool, float]', 'TypeError'), + ] + + for alias_template, args_template, expected_template in tests: + rendered_templates = template_replace( + templates=[alias_template, args_template, expected_template], + replacements={'generic': generics, 'tuple_type': tuple_types} + ) + for alias_str, args_str, expected_str in rendered_templates: + with self.subTest(alias=alias_str, args=args_str, expected=expected_str): + if expected_str == 'TypeError': + with self.assertRaises(TypeError): + eval(alias_str + args_str) + else: + self.assertEqual( + eval(alias_str + args_str), + eval(expected_str) + ) + + + class UnpackTests(BaseTestCase): def test_accepts_single_type(self):

1 0

bpo-26792: Improve docstrings of runpy module run_functions (GH-30729)
by miss-islington April 29, 2022

April 29, 2022

https://github.com/python/cpython/commit/36de20d0f9191c74048474afc989296665… commit: 36de20d0f9191c74048474afc989296665362f10 branch: 3.9 author: Miss Islington (bot) <31488909+miss-islington(a)users.noreply.github.com> committer: miss-islington <31488909+miss-islington(a)users.noreply.github.com> date: 2022-04-29T11:46:47-07:00 summary: bpo-26792: Improve docstrings of runpy module run_functions (GH-30729) Co-authored-by: Jelle Zijlstra <jelle.zijlstra(a)gmail.com> Co-authored-by: Kumar Aditya <59607654+kumaraditya303(a)users.noreply.github.com> (cherry picked from commit 117836f123a1c65d9ba50401822b883f11f0a347) Co-authored-by: Humbled Drugman <humbled.drugman(a)gmail.com> files: A Misc/NEWS.d/next/Documentation/2022-01-23-20-44-53.bpo-26792.dQ1v1W.rst M Lib/runpy.py diff --git a/Lib/runpy.py b/Lib/runpy.py index 7e1e1ac5dde2d..c602bbe3f7d63 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, '<run_path>' 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 = "<run_path>" diff --git a/Misc/NEWS.d/next/Documentation/2022-01-23-20-44-53.bpo-26792.dQ1v1W.rst b/Misc/NEWS.d/next/Documentation/2022-01-23-20-44-53.bpo-26792.dQ1v1W.rst new file mode 100644 index 0000000000000..64a3956447601 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2022-01-23-20-44-53.bpo-26792.dQ1v1W.rst @@ -0,0 +1,2 @@ +Improve the docstrings of :func:`runpy.run_module` and :func:`runpy.run_path`. +Original patch by Andrew Brezovsky.

1 0