From 83d8a4c7cd9738b32841dd587ae8a83c0c020821 Mon Sep 17 00:00:00 2001 From: Jukka Lehtosalo Date: Wed, 5 Dec 2018 15:54:22 +0000 Subject: [PATCH 1/2] Document supported TypedDict operations and methods Follow-up to #6011 (this must be merged after it). --- docs/source/more_types.rst | 39 ++++++++++++++++++++++++++++++++------ 1 file changed, 33 insertions(+), 6 deletions(-) diff --git a/docs/source/more_types.rst b/docs/source/more_types.rst index abbb8335536b..265d793d3d32 100644 --- a/docs/source/more_types.rst +++ b/docs/source/more_types.rst @@ -200,7 +200,7 @@ Our first attempt at writing this function might look like this: from typing import Union, Optional - def mouse_event(x1: int, + def mouse_event(x1: int, y1: int, x2: Optional[int] = None, y2: Optional[int] = None) -> Union[ClickEvent, DragEvent]: @@ -245,7 +245,7 @@ to more accurately describe the function's behavior: # Mypy will also check and make sure the signature is # consistent with the provided variants. - def mouse_event(x1: int, + def mouse_event(x1: int, y1: int, x2: Optional[int] = None, y2: Optional[int] = None) -> Union[ClickEvent, DragEvent]: @@ -374,7 +374,7 @@ First, if multiple variants match due to an argument being of type output2 = summarize(dynamic_var) Second, if multiple variants match due to one or more of the arguments -being a union, mypy will make the inferred type be the union of the +being a union, mypy will make the inferred type be the union of the matching variant returns: .. code-block:: python @@ -390,9 +390,9 @@ matching variant returns: overload variants can change how mypy type checks your program. To minimize potential issues, we recommend that you: - + 1. Make sure your overload variants are listed in the same order as - the runtime checks (e.g. ``isinstance`` checks) in your implementation. + the runtime checks (e.g. ``isinstance`` checks) in your implementation. 2. Order your variants and runtime checks from most to least specific. (See the following section for an example). @@ -533,7 +533,7 @@ Type checking the implementation The body of an implementation is type-checked against the type hints provided on the implementation. For example, in the ``MyList`` example up above, the code in the body is checked with -argument list ``index: Union[int, slice]`` and a return type of +argument list ``index: Union[int, slice]`` and a return type of ``Union[T, Sequence[T]]``. If there are no annotations on the implementation, then the body is not type checked. If you want to force mypy to check the body anyways, use the ``--check-untyped-defs`` @@ -879,6 +879,33 @@ Totality also affects structural compatibility. You can't use a partial TypedDict when a total one is expected. Also, a total TypedDict is not valid when a partial one is expected. +Supported operations +-------------------- + +TypedDict objects support a subset of dictionary operations and methods: + +* Anything included in the mapping protocol, such as indexing, + ``get()``, ``keys()`` and ``items()`` +* ``copy()`` +* ``setdefault(k, default)`` +* ``update(d)`` +* ``pop(k[, default])`` (partial TypedDicts only) +* ``del d[k]`` (partial TypedDicts only) + +These methods are also supported in Python 2 code: + +* ``has_key(k)`` +* ``viewitems()`` +* ``viewkeys()`` +* ``viervalues()`` + +You must use string literals as keys when calling most of the above methods, +as otherwise mypy won't be able to check that the key is valid. + +``clear()`` and ``popitem()`` are not supported since they are unsafe +-- they could delete required TypedDict items that are not visible to +mypy because of structural subtyping. + Class-based syntax ------------------ From 4c404ea5e45d144e1928944360cc630e98a59875 Mon Sep 17 00:00:00 2001 From: Jukka Lehtosalo Date: Thu, 6 Dec 2018 12:28:43 +0000 Subject: [PATCH 2/2] Update based on feedback --- docs/source/more_types.rst | 47 +++++++++++++++++++++++--------------- 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/docs/source/more_types.rst b/docs/source/more_types.rst index 265d793d3d32..f0fb3d1c0ab9 100644 --- a/docs/source/more_types.rst +++ b/docs/source/more_types.rst @@ -882,29 +882,40 @@ valid when a partial one is expected. Supported operations -------------------- -TypedDict objects support a subset of dictionary operations and methods: - -* Anything included in the mapping protocol, such as indexing, - ``get()``, ``keys()`` and ``items()`` -* ``copy()`` -* ``setdefault(k, default)`` -* ``update(d)`` -* ``pop(k[, default])`` (partial TypedDicts only) -* ``del d[k]`` (partial TypedDicts only) - -These methods are also supported in Python 2 code: - -* ``has_key(k)`` +TypedDict objects support a subset of dictionary operations and methods. +You must use string literals as keys when calling most of the methods, +as otherwise mypy won't be able to check that the key is valid. List +of supported operations: + +* Anything included in ``typing.Mapping``: + + * ``d[key]`` + * ``key in d`` + * ``len(d)`` + * ``for key in d`` (iteration) + * ``d.get(key[, default])`` + * ``d.keys()`` + * ``d.values()`` + * ``d.items()`` + +* ``d.copy()`` +* ``d.setdefault(key, default)`` +* ``d1.update(d2)`` +* ``d.pop(key[, default])`` (partial TypedDicts only) +* ``del d[key]`` (partial TypedDicts only) + +In Python 2 code, these methods are also supported: + +* ``has_key(key)`` * ``viewitems()`` * ``viewkeys()`` * ``viervalues()`` -You must use string literals as keys when calling most of the above methods, -as otherwise mypy won't be able to check that the key is valid. +.. note:: -``clear()`` and ``popitem()`` are not supported since they are unsafe --- they could delete required TypedDict items that are not visible to -mypy because of structural subtyping. + ``clear()`` and ``popitem()`` are not supported since they are unsafe + -- they could delete required TypedDict items that are not visible to + mypy because of structural subtyping. Class-based syntax ------------------