bpo-35581: Document @typing.type_check_only (GH-11312)
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index fad9dc6..ed5f547 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -951,6 +951,24 @@
This wraps the decorator with something that wraps the decorated
function in :func:`no_type_check`.
+.. decorator:: type_check_only
+
+ Decorator to mark a class or function to be unavailable at runtime.
+
+ This decorator is itself not available at runtime. It is mainly
+ intended to mark classes that are defined in type stub files if
+ an implementation returns an instance of a private class::
+
+ @type_check_only
+ class Response: # private or not available at runtime
+ code: int
+ def get_header(self, name: str) -> str: ...
+
+ def fetch_response() -> Response: ...
+
+ Note that returning instances of private classes is not recommended.
+ It is usually preferable to make such classes public.
+
.. data:: Any
Special type indicating an unconstrained type.
diff --git a/Misc/NEWS.d/next/Documentation/2018-12-25-12-56-57.bpo-35581.aA7r6T.rst b/Misc/NEWS.d/next/Documentation/2018-12-25-12-56-57.bpo-35581.aA7r6T.rst
new file mode 100644
index 0000000..2fad300
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2018-12-25-12-56-57.bpo-35581.aA7r6T.rst
@@ -0,0 +1 @@
+@typing.type_check_only now allows type stubs to mark functions and classes not available during runtime.
\ No newline at end of file