From 1e8295402bf5e81d327ed2b5eb88a6b6de449d63 Mon Sep 17 00:00:00 2001
From: Sebastian Rittau <srittau@rittau.biz>
Date: Sat, 13 Apr 2019 00:33:40 +0200
Subject: [PATCH] bpo-35581: Document @typing.type_check_only (GH-11312)

---
 Doc/library/typing.rst                         | 18 ++++++++++++++++++
 .../2018-12-25-12-56-57.bpo-35581.aA7r6T.rst   |  1 +
 2 files changed, 19 insertions(+)
 create mode 100644 Misc/NEWS.d/next/Documentation/2018-12-25-12-56-57.bpo-35581.aA7r6T.rst

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index fad9dc69431..ed5f547e3ce 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -951,6 +951,24 @@ The module defines the following classes, functions and decorators:
    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 00000000000..2fad3003e3b
--- /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