docs: miscellaneous improvements (#9762)

Co-authored-by: hauntsaninja <>

Author: hauntsaninja

docs/source/builtin_types.rst

@@ -31,10 +31,10 @@ strings and ``Dict[Any, Any]`` is a dictionary of dynamically typed
 (arbitrary) values and keys. ``List`` is another generic class. ``Dict`` and
 ``List`` are aliases for the built-ins ``dict`` and ``list``, respectively.
 
-``Iterable``, ``Sequence``, and ``Mapping`` are generic types that
-correspond to Python protocols. For example, a ``str`` object or a
-``List[str]`` object is valid
-when ``Iterable[str]`` or ``Sequence[str]`` is expected. Note that even though
-they are similar to abstract base classes defined in :py:mod:`collections.abc`
-(formerly ``collections``), they are not identical, since the built-in
-collection type objects do not support indexing.
+``Iterable``, ``Sequence``, and ``Mapping`` are generic types that correspond to
+Python protocols. For example, a ``str`` object or a ``List[str]`` object is
+valid when ``Iterable[str]`` or ``Sequence[str]`` is expected. Note that even
+though they are similar to abstract base classes defined in
+:py:mod:`collections.abc` (formerly ``collections``), they are not identical. In
+particular, prior to Python 3.9, the built-in collection type objects do not
+support indexing.

docs/source/cheat_sheet_py3.rst

@@ -67,7 +67,7 @@ Built-in types
 
    # For tuples of fixed size, we specify the types of all the elements
    x: Tuple[int, str, float] = (3, "yes", 7.5)
-   
+
    # For tuples of variable size, we use one type and ellipsis
    x: Tuple[int, ...] = (1, 2, 3)
 
@@ -226,6 +226,8 @@ that are common in idiomatic Python are standardized.
    f({3: 'yes', 4: 'no'})
 
 
+You can even make your own duck types using :ref:`protocol-types`.
+
 Classes
 *******
 
@@ -319,7 +321,7 @@ Decorators
 **********
 
 Decorator functions can be expressed via generics. See
-:ref:`declaring-decorators` for the more details.
+:ref:`declaring-decorators` for more details.
 
 .. code-block:: python
 

docs/source/duck_type_compatibility.rst

@@ -8,6 +8,7 @@ supported for a small set of built-in types:
 
 * ``int`` is duck type compatible with ``float`` and ``complex``.
 * ``float`` is duck type compatible with ``complex``.
+* ``bytearray`` and ``memoryview`` are duck type compatible with ``bytes``.
 * In Python 2, ``str`` is duck type compatible with ``unicode``.
 
 For example, mypy considers an ``int`` object to be valid whenever a

docs/source/existing_code.rst

@@ -114,8 +114,8 @@ A simple CI script could look something like this:
 
 .. code-block:: text
 
-    python3 -m pip install mypy==0.600  # Pinned version avoids surprises
-    scripts/mypy  # Runs with the correct options
+    python3 -m pip install mypy==0.790  # Pinned version avoids surprises
+    scripts/mypy  # Run the mypy runner script you set up
 
 Annotate widely imported modules
 --------------------------------
@@ -168,12 +168,11 @@ for further speedups.
 Introduce stricter options
 --------------------------
 
-Mypy is very configurable. Once you get started with static typing,
-you may want to explore the various
-strictness options mypy provides to
-catch more bugs. For example, you can ask mypy to require annotations
-for all functions in certain modules to avoid accidentally introducing
-code that won't be type checked. Refer to :ref:`command-line` for the
-details.
+Mypy is very configurable. Once you get started with static typing, you may want
+to explore the various strictness options mypy provides to catch more bugs. For
+example, you can ask mypy to require annotations for all functions in certain
+modules to avoid accidentally introducing code that won't be type checked using
+:confval:`disallow_untyped_defs`, or type check code without annotations as well
+with :confval:`check_untyped_defs`. Refer to :ref:`config-file` for the details.
 
 .. _PyAnnotate: https://github.com/dropbox/pyannotate

docs/source/index.rst

@@ -69,7 +69,6 @@ Mypy is a static type checker for Python 3 and Python 2.7.
    error_codes
    error_code_list
    error_code_list2
-   python36
    additional_features
    faq
 

docs/source/introduction.rst

@@ -8,12 +8,12 @@ annotations are just hints for mypy and don't interfere when running your progra
 You run your program with a standard Python interpreter, and the annotations
 are treated effectively as comments.
 
-Using the Python 3 function annotation syntax (using the :pep:`484` notation) or
-a comment-based annotation syntax for Python 2 code, you will be able to
-efficiently annotate your code and use mypy to check the code for common
-errors. Mypy has a powerful and easy-to-use type system with modern features
-such as type inference, generics, callable types, tuple types,
-union types, and structural subtyping.
+Using the Python 3 annotation syntax (using :pep:`484` and :pep:`526` notation)
+or a comment-based annotation syntax for Python 2 code, you will be able to
+efficiently annotate your code and use mypy to check the code for common errors.
+Mypy has a powerful and easy-to-use type system with modern features such as
+type inference, generics, callable types, tuple types, union types, and
+structural subtyping.
 
 As a developer, you decide how to use mypy in your workflow. You can always
 escape to dynamic typing as mypy's approach to static typing doesn't restrict

docs/source/python36.rst

@@ -41,8 +41,6 @@ code that uses the library. If you write a stub for a library module,
 consider making it available for other programmers that use mypy
 by contributing it back to the typeshed repo.
 
-There is more information about creating stubs in the
-`mypy wiki <https://github.com/python/mypy/wiki/Creating-Stubs-For-Python-Modules>`_.
 The following sections explain the kinds of type annotations you can use
 in your programs and stub files.
 

docs/source/stubs.rst

@@ -182,17 +182,17 @@ must give each variable a type separately:
 
 .. code-block:: python
 
-   i, found = 0, False # type: int, bool
+   i, found = 0, False  # type: int, bool
 
 You can optionally use parentheses around the types, assignment targets
 and assigned expression:
 
 .. code-block:: python
 
-   i, found = 0, False # type: (int, bool)      # OK
-   (i, found) = 0, False # type: int, bool      # OK
-   i, found = (0, False) # type: int, bool      # OK
-   (i, found) = (0, False) # type: (int, bool)  # OK
+   i, found = 0, False  # type: (int, bool)      # OK
+   (i, found) = 0, False  # type: int, bool      # OK
+   i, found = (0, False)  # type: int, bool      # OK
+   (i, found) = (0, False)  # type: (int, bool)  # OK
 
 Starred expressions
 *******************