feat!: Declarative function signatures for python (GoogleCloudPlatform#160)

Author: KaylaNguyen

.gitignore

@@ -6,6 +6,7 @@ build/
 dist/
 .coverage
 .vscode/
+.idea/
 function_output.json
 serverlog_stderr.txt
 serverlog_stdout.txt

README.md

@@ -111,6 +111,40 @@ curl localhost:8080
 # Output: Hello world!
 ```
 
+### Quickstart: Register your function using decorator
+
+Create an `main.py` file with the following contents:
+
+```python
+import functions_framework
+
+@functions_framework.cloudevent
+def hello_cloudevent(cloudevent):
+   return f"Received event with ID: {cloudevent['id']} and data {cloudevent.data}"
+
+@functions_framework.http
+def hello_http(request):
+   return "Hello world!"
+
+```
+
+Run the following command to run `hello_http` target locally:
+
+```sh
+functions-framework --target=hello_http
+```
+
+Open http://localhost:8080/ in your browser and see *Hello world!*.
+
+Run the following command to run `hello_cloudevent` target locally:
+
+```sh
+functions-framework --target=hello_cloudevent
+```
+
+More info on sending [CloudEvents](http://cloudevents.io) payloads, see [`examples/cloud_run_cloudevents`](examples/cloud_run_cloudevents/) instruction.
+
+
 ### Quickstart: Error handling
 
 The framework includes an error handler that is similar to the
@@ -337,7 +371,7 @@ For more details on this signature type, check out the Google Cloud Functions do
 
 ## Advanced Examples
 
-More advanced guides can be found in the [`examples/`](https://github.com/GoogleCloudPlatform/functions-framework-python/blob/master/examples/) directory.
+More advanced guides can be found in the [`examples/`](examples/) directory.
 You can also find examples on using the CloudEvent Python SDK [here](https://github.com/cloudevents/sdk-python).
 
 ## Contributing

examples/cloud_run_cloudevents/main.py

@@ -14,7 +14,6 @@
 
 # This sample creates a function using the CloudEvents SDK
 # (https://github.com/cloudevents/sdk-python)
-import sys
 
 
 def hello(cloudevent):

examples/cloud_run_cloudevents/send_cloudevent.py

@@ -15,19 +15,18 @@
 # limitations under the License.
 from cloudevents.http import CloudEvent, to_structured
 import requests
-import json
 
 
 # Create a cloudevent using https://github.com/cloudevents/sdk-python
-# Note we only need source and type because the cloudevents constructor by 
-# default will set "specversion" to the most recent cloudevent version (e.g. 1.0) 
-# and "id" to a generated uuid.uuid4 string. 
+# Note we only need source and type because the cloudevents constructor by
+# default will set "specversion" to the most recent cloudevent version (e.g. 1.0)
+# and "id" to a generated uuid.uuid4 string.
 attributes = {
     "Content-Type": "application/json",
     "source": "from-galaxy-far-far-away",
-    "type": "cloudevent.greet.you"
+    "type": "cloudevent.greet.you",
 }
-data = {"name":"john"}
+data = {"name": "john"}
 
 event = CloudEvent(attributes, data)
 

examples/cloud_run_decorator/Dockerfile

@@ -0,0 +1,17 @@
+# Use the official Python image.
+# https://hub.docker.com/_/python
+FROM python:3.7-slim
+
+# Copy local code to the container image.
+ENV APP_HOME /app
+ENV PYTHONUNBUFFERED TRUE
+
+WORKDIR $APP_HOME
+COPY . .
+
+# Install production dependencies.
+RUN pip install functions-framework
+RUN pip install -r requirements.txt
+
+# Run the web service on container startup.
+CMD exec functions-framework --target=hello_http

examples/cloud_run_decorator/README.md

@@ -0,0 +1,23 @@
+## How to run this locally
+
+This guide shows how to run `hello_http` target locally.
+To test with `hello_cloudevent`, change the target accordingly in Dockerfile.
+
+Build the Docker image:
+
+```commandline
+docker build -t decorator_example .
+```
+
+Run the image and bind the correct ports:
+
+```commandline
+docker run --rm -p 8080:8080 -e PORT=8080 decorator_example
+```
+
+Send requests to this function using `curl` from another terminal window:
+
+```sh
+curl localhost:8080
+# Output: Hello world!
+```

examples/cloud_run_decorator/main.py

@@ -0,0 +1,27 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# This sample creates a function using the CloudEvents SDK
+# (https://github.com/cloudevents/sdk-python)
+import functions_framework
+
+
+@functions_framework.cloudevent
+def hello_cloudevent(cloudevent):
+    return f"Received event with ID: {cloudevent['id']} and data {cloudevent.data}"
+
+
+@functions_framework.http
+def hello_http(request):
+    return "Hello world!"

examples/cloud_run_decorator/requirements.txt

@@ -0,0 +1 @@
+# Optionally include additional dependencies here

examples/cloud_run_http/main.py

@@ -12,5 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 def hello(request):
     return "Hello world!"

setup.cfg

@@ -1,10 +1,10 @@
 [isort]
-multi_line_output=3
-include_trailing_comma=True
-force_grid_wrap=0
-use_parentheses=True
-line_length=88
-lines_between_types=1
-combine_as_imports=True
-default_section=THIRDPARTY
-known_first_party=functions_framework,google.cloud.functions
+multi_line_output = 3
+include_trailing_comma = True
+force_grid_wrap = 0
+use_parentheses = True
+line_length = 88
+lines_between_types = 1
+combine_as_imports = True
+default_section = THIRDPARTY
+known_first_party = functions_framework, google.cloud.functions