Better callable: Callable[[Arg('x', int), VarArg(str)], int] now a thing you can do (#2607)

Implements an experimental feature to allow Callable to have any kind of signature an actual function definition does.

This should enable better typing of callbacks &c.

Initial discussion: python/typing#239
Proposal, v. similar to this impl: python/typing#264
Relevant typeshed PR: python/typeshed#793

Author: sixolet

mypy_extensions.py

@@ -5,6 +5,8 @@
     from mypy_extensions import TypedDict
 """
 
+from typing import Any
+
 # NOTE: This module must support Python 2.7 in addition to Python 3.x
 
 import sys
@@ -92,6 +94,40 @@ class Point2D(TypedDict):
     syntax forms work for Python 2.7 and 3.2+
     """
 
+# Argument constructors for making more-detailed Callables. These all just
+# return their type argument, to make them complete noops in terms of the
+# `typing` module.
+
+
+def Arg(type=Any, name=None):
+    """A normal positional argument"""
+    return type
+
+
+def DefaultArg(type=Any, name=None):
+    """A positional argument with a default value"""
+    return type
+
+
+def NamedArg(type=Any, name=None):
+    """A keyword-only argument"""
+    return type
+
+
+def DefaultNamedArg(type=Any, name=None):
+    """A keyword-only argument with a default value"""
+    return type
+
+
+def VarArg(type=Any):
+    """A *args-style variadic positional argument"""
+    return type
+
+
+def KwArg(type=Any):
+    """A **kwargs-style variadic keyword argument"""
+    return type
+
 
 # Return type that indicates a function does not return
 class NoReturn: pass