Initial typing of the public API

This adds type annotations for the 2 main decorators of the library.

Closes: GoogleCloudPlatform#190

README.md

@@ -62,7 +62,7 @@ Create an `main.py` file with the following contents:
 import functions_framework
 
 @functions_framework.http
-def hello(request):
+def hello(request: flask.Request) -> flask.typing.ResponseReturnValue:
     return "Hello world!"
 ```
 
@@ -98,9 +98,10 @@ Create an `main.py` file with the following contents:
 
 ```python
 import functions_framework
+from cloudevents.http.event import CloudEvent
 
 @functions_framework.cloud_event
-def hello_cloud_event(cloud_event):
+def hello_cloud_event(cloud_event: CloudEvent) -> None:
    print(f"Received event with ID: {cloud_event['id']} and data {cloud_event.data}")
 ```
 

setup.py

@@ -23,6 +23,7 @@
 with open(path.join(here, "README.md"), encoding="utf-8") as f:
     long_description = f.read()
 
+
 setup(
     name="functions-framework",
     version="3.4.0",
@@ -46,6 +47,10 @@
     ],
     keywords="functions-framework",
     packages=find_packages(where="src"),
+    package_data={
+        "functions_framework": ["py.typed"],
+    },
+    zip_safe=False,
     namespace_packages=["google", "google.cloud"],
     package_dir={"": "src"},
     python_requires=">=3.5, <4",

src/functions_framework/__init__.py

@@ -23,13 +23,14 @@
 import types
 
 from inspect import signature
-from typing import Type
+from typing import Callable, Type
 
 import cloudevents.exceptions as cloud_exceptions
 import flask
 import werkzeug
 
 from cloudevents.http import from_http, is_binary
+from cloudevents.http.event import CloudEvent
 
 from functions_framework import _function_registry, _typed_event, event_conversion
 from functions_framework.background_event import BackgroundEvent
@@ -45,6 +46,8 @@
 
 _CLOUDEVENT_MIME_TYPE = "application/cloudevents+json"
 
+CloudEventFunction = Callable[[CloudEvent], None]
+HTTPFunction = Callable[[flask.Request], flask.typing.ResponseReturnValue]
 
 class _LoggingHandler(io.TextIOWrapper):
     """Logging replacement for stdout and stderr in GCF Python 3.7."""
@@ -59,7 +62,7 @@ def write(self, out):
         return self.stderr.write(json.dumps(payload) + "\n")
 
 
-def cloud_event(func):
+def cloud_event(func: CloudEventFunction) -> CloudEventFunction:
     """Decorator that registers cloudevent as user function signature type."""
     _function_registry.REGISTRY_MAP[
         func.__name__
@@ -99,7 +102,7 @@ def wrapper(*args, **kwargs):
         return _typed
 
 
-def http(func):
+def http(func: HTTPFunction) -> HTTPFunction:
     """Decorator that registers http as user function signature type."""
     _function_registry.REGISTRY_MAP[
         func.__name__

tests/test_typing.py

@@ -0,0 +1,14 @@
+import typing
+
+if typing.TYPE_CHECKING:  # pragma: no cover
+    import flask
+    import functions_framework
+    from cloudevents.http.event import CloudEvent
+
+    @functions_framework.http
+    def hello(request: flask.Request) -> flask.typing.ResponseReturnValue:
+        return "Hello world!"
+
+    @functions_framework.cloud_event
+    def hello_cloud_event(cloud_event: CloudEvent) -> None:
+        print(f"Received event: id={cloud_event['id']} and data={cloud_event.data}")

tox.ini

@@ -19,7 +19,9 @@ deps =
     black
     twine
     isort
+    mypy
 commands =
+    mypy tests/test_typing.py
     black --check src tests setup.py conftest.py --exclude tests/test_functions/background_load_error/main.py
     isort -c src tests setup.py conftest.py
     python setup.py --quiet sdist bdist_wheel