Various doc updates #3314
Various doc updates #3314
Conversation
This goes in the 3.6 section because it only works for Python 3.6.
|
@sixolet Can you review the docs I wrote for flexible callable here? |
docs/source/kinds_of_types.rst
Outdated
|
|
||
| As an experimental mypy extension, you can specify ``Callable`` types | ||
| that support keyword arguments, optional arguments, and more. The | ||
| "argument" part of the ``Callable`` specification (the part specifying |
There was a problem hiding this comment.
Where you specify the arguments of a Callable, you can choose to supply just the type of a nameless positional argument, or an "argument specifier" representing a more complicated form of argument.
docs/source/kinds_of_types.rst
Outdated
| **kwargs: int) -> int: | ||
| ... | ||
|
|
||
| F = Callable[[Arg(int), # No argument name given |
There was a problem hiding this comment.
Consider making this just int, to show that a raw type has no arg name and that you can mix them?
|
|
||
| MyFunc = Callable[[Arg(int), Arg(str), Arg(int)], float] | ||
|
|
||
| A ``Callable`` with unspecified argument types, such as |
There was a problem hiding this comment.
This equivalency is near, but not entirely true. A Callable[..., int] gets is_ellipsis_args set to True, unlike Callable[[VarArg(), KwArg()], int]. A Callable with ellipsis args is not only considered a subtype of all Callables with compatible return types (which it naturally is), but also a supertype of all Callables with compatible return types (which is weird and special). This is the only other wart in the type system I know of that's comparable to Any.
docs/source/kinds_of_types.rst
Outdated
| .. note:: | ||
|
|
||
| This feature is experimental. Details of the implementation may | ||
| change and there may be unknown limitations. **IMPORTANT:** At |
There was a problem hiding this comment.
Remove the first "at runtime" and maybe make it "Each of the functions above currently returns its type argument..."
(to remove the awkwardly repeated phrase)
docs/source/kinds_of_types.rst
Outdated
| Arg(int, 'b'), | ||
| DefaultArg(int, 'c'), | ||
| VarArg(int), | ||
| NamedArg(int, 'd'), |
There was a problem hiding this comment.
This is probably the wrong place for this discussion, but why don't we call this KeywordOnlyArg? NamedArg is confusing because normal args are also named.
There was a problem hiding this comment.
That discussion can go in python/typing#264, which itself has a few naming differences from Naomi's PRs (#2426 and python/typeshed#684). Or it can go into Naomi's PEP once she's written it.
docs/source/python36.rst
Outdated
| @@ -16,6 +16,7 @@ now have type annotations using either of the two forms: | |||
|
|
|||
| .. code-block:: python | |||
|
|
|||
| from typing import Optionsl | |||
|
Addressed the review comments. I decided not to explain in detail the difference between Callable[..., T] and the other form -- it's esoteric and hard to explain and nobody outside mypy dev circles cares. |
|
|
||
| MyOtherFunc = Callable[..., int] | ||
|
|
||
| is (roughly) equivalent to |
No description provided.