More documentation updates #5053
Conversation
Partial list of changes: * Move a bunch of less core functionality to later in the documentation to make it easier to get started with mypy. * Remove some obsolete things. * Migrate more examples to use variable annotations. * Clarify various explanations.
docs/source/additional_features.rst
Outdated
| first overloaded definition, and ignores the type annotations on the | ||
| implementation of ``__getitem__``. The code in the body of the | ||
| definition of ``__getitem__`` is checked against the annotations on | ||
| the the corresponding declaration. In this case the body is checked |
docs/source/additional_features.rst
Outdated
|
|
||
| The annotations on the function body must be compatible with the | ||
| types given for the overloaded variants listed above it. The type | ||
| checker will verify that all the types listed the overloaded variants |
There was a problem hiding this comment.
missing a preposition between "listed" and "the" (probably "for")
docs/source/additional_features.rst
Outdated
| case it checks that the parameter type ``int`` and the return type | ||
| ``T`` are compatible with ``Union[int, slice]`` and | ||
| ``Union[T, Sequence[T]]`` for the first variant. For the second | ||
| variant it verifies that the parameter type ``slice`` are the return |
docs/source/additional_features.rst
Outdated
| *********************** | ||
|
|
||
| As an experimental mypy extension, you can specify ``Callable`` types | ||
| that support keyword arguments, optional arguments, and more. Where |
| .. code-block:: python | ||
|
|
||
| class A: | ||
| x = None # type: List[int] # Declare attribute 'x' of type List[int] |
There was a problem hiding this comment.
Should we mention the special case where this allows None even if strict optional is on?
There was a problem hiding this comment.
Good idea, added a short discussion of the special case.
| def __iter__(self) -> Iterator[T] | ||
|
|
||
| ``Iterator[T]`` | ||
| --------------- |
There was a problem hiding this comment.
Is there a syntax error here? GitHub highlights it.
There was a problem hiding this comment.
It seems to work fine. Could be a problem with the syntax highlighter that GitHub uses.
There was a problem hiding this comment.
Maybe because there's no colon or body on the def in the preceding code block?
docs/source/protocols.rst
Outdated
|
|
||
| class SupportsClose(Protocol): | ||
| def close(self) -> None: | ||
| ... # Explicit '...' |
There was a problem hiding this comment.
I'm not sure why this is "Explicit" or why this is significant.
There was a problem hiding this comment.
Made the comment more explicit (ha).
docs/source/protocols.rst
Outdated
|
|
||
| close_all([Resource(), open('some/file')]) # Okay! | ||
|
|
||
| ``Resource`` is a subtype of the ``SupportClose`` protocol since it defines |
There was a problem hiding this comment.
SupportsClose, not SupportClose
docs/source/protocols.rst
Outdated
|
|
||
| .. code-block:: python | ||
|
|
||
| class NewProtocol(SupportsClose): # This is NOT a protocol |
There was a problem hiding this comment.
To make this clearer, maybe name this class NotAProtocol.
docs/source/protocols.rst
Outdated
| self.left: Optional['SimpleTree'] = None | ||
| self.right: Optional['SimpleTree'] = None | ||
|
|
||
| root = SimpleTree(0) # type: TreeLike # OK |
There was a problem hiding this comment.
Use variable annotation here.
|
This should be rebased on top of the new re-write. |
Also update some section titles.
|
This is ready for another round of review. |
| def __iter__(self) -> Iterator[T] | ||
|
|
||
| ``Iterator[T]`` | ||
| --------------- |
There was a problem hiding this comment.
Maybe because there's no colon or body on the def in the preceding code block?
There was a problem hiding this comment.
I went ahead and skimmed it, didn't see any other obvious issues beyond the note by @gvanrossum.
Partial list of changes: * Move a bunch of less core functionality to later in the documentation to make it easier to get started with mypy. * Remove some obsolete things. * Migrate more examples to use variable annotations. * Clarify various explanations. * Address feedback * Move a few sections around in the table of contents Also update some section titles.
Partial list of changes:
Move a bunch of less core functionality to later in the documentation to
make it easier to get started with mypy.
Remove some obsolete things.
Migrate more examples to use variable annotations.
Clarify various explanations.