Repository: python/mypy
Pull request: Add documentation for type: ignore
### Description

Adds a reference on how `# type: ignore` can be used.

Resolves #11354 


Problem statement:
Expand `type: ignore` documentation
**Feature**

Allowing a short message with your type ignore comments, for better context

**Pitch**

I wanted to add a little comment with my `type: ignore` to provide some context as to why that ignore is present in the code.

This is the thing that I tried:

```python
for text in iter(buff.read1, b""):  # type: ignore - typeshed bug
    print(decoder.decode(text), end="")
```

Unfortunately that doesn't work.
I tried a few other variants, like `# type: ignore; typeshed bug`, but I could find no way to add a message to the ignore comment.

It also seems like an easy feature that I could work on :)

Hints from issue discussion:
Per PEP 484:

> In some cases, linting tools or other comments may be needed on the same line as a type comment. In these cases, the type comment should be before other comments and linting markers:

    # type: ignore # <comment or other marker>
I wish this was mentioned in mypy docs... perhaps in [this section](https://mypy.readthedocs.io/en/stable/common_issues.html#spurious-errors-and-locally-silencing-the-checker)
It is (briefly) covered here, but almost as an aside https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html#when-you-re-puzzled-or-when-things-are-complicated

If you want to suggest a change in a PR I'm happy to take a look, but I think the bigger issue is we don't really talk much about `# type: ignore` in the typesystem reference to begin with. It might be useful to add a section about `# type: ignore` to this page: https://mypy.readthedocs.io/en/stable/type_inference_and_annotations.html#type-inference-and-type-annotations

Commit message: Add documentation for type: ignore

Patch to review:
diff --git a/docs/source/type_inference_and_annotations.rst b/docs/source/type_inference_and_annotations.rst
index 38518a8f2c3b..81c748e02771 100644
--- a/docs/source/type_inference_and_annotations.rst
+++ b/docs/source/type_inference_and_annotations.rst
@@ -216,3 +216,54 @@ to be annotated with a starred type:
     p, q, *rs = 1, 2  # type: int, int, List[int]
 
 Here, the type of ``rs`` is set to ``List[int]``.
+
+Disabling type checks
+*********************
+
+You might want to disable type checking on specific lines, or within specific
+files in your codebase. To do that, you can use a ``type: ignore`` comment.
+
+For example, say that the web framework that you use now takes an integer
+argument to ``run()``, which starts it on localhost on that port. Liks so:
+
+.. code-block:: python
+
+    # Starting app on http://localhost:8000
+    app.run(8000)
+
+However, the type stubs that the package uses is not up-to-date, and it still
+expects only `str` types for `run()`. This would give you the following error:
+
+.. code-block:: text
+
+    error: Argument 1 to "run" of "A" has incompatible type "int"; expected "str"
+
+If you cannot directly fix the type stubs yourself, you can temporarily
+disable type checking on that line, by adding a ``# type: ignore``:
+
+.. code-block:: python
+
+    # Starting app on http://localhost:8000
+    app.run(8000)  # type: ignore
+
+This will suppress any mypy errors that would have raised on that specific line.
+
+You should probably add some more information on the ``type: ignore`` comment,
+to explain why the ignore was added in the first place. This could be a link to
+an issue on the repository responsible for the type stubs, or it could be a
+short explanation of the bug. To do that, use this format:
+
+.. code-block:: python
+
+    # Starting app on http://localhost:8000
+    app.run(8000)  # type: ignore  # `run()` now accepts an `int`, as a port
+
+Similarly, you can also ignore all mypy checks in a file, by adding a
+``# type: ignore`` on the top of the file:
+
+.. code-block:: python
+
+    # type: ignore
+    # This is a test file, skipping type checking in it.
+    import unittest
+    ...


Code review comments:
diff_hunk: @@ -216,3 +216,54 @@ to be annotated with a starred type:
     p, q, *rs = 1, 2  # type: int, int, List[int]
 
 Here, the type of ``rs`` is set to ``List[int]``.
+
+Disabling type checks
path: docs/source/type_inference_and_annotations.rst
text: @user1:
```suggestion
Silencing type errors
```

ignores don't disable any checks per se (though I suppose they do so effectively), they only silence the error.