Add Google Cloud Functions Python runtime samples (GoogleCloudPlatform#1583)

Author: andrewsg

functions/README.rst

@@ -0,0 +1,84 @@
+.. This file is automatically generated. Do not edit this file directly.
+
+Google Cloud Functions Python Samples
+===============================================================================
+
+.. image:: https://gstatic.com/cloudssh/images/open-btn.png
+   :target: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/python-docs-samples&page=editor&open_in_editor=/README.rst
+
+
+This directory contains samples for Google Cloud Functions. `Cloud Functions`_ is a lightweight, event-based, asynchronous compute solution that allows you to create small, single-purpose functions that respond to Cloud events without the need to manage a server or a runtime environment.
+
+
+
+
+.. _Cloud Functions: https://cloud.google.com/functions/docs/
+
+Setup
+-------------------------------------------------------------------------------
+
+
+Authentication
+++++++++++++++
+
+This sample requires you to have authentication setup. Refer to the
+`Authentication Getting Started Guide`_ for instructions on setting up
+credentials for applications.
+
+.. _Authentication Getting Started Guide:
+    https://cloud.google.com/docs/authentication/getting-started
+
+Install Dependencies
+++++++++++++++++++++
+
+#. Install `pip`_ and `virtualenv`_ if you do not already have them. You may want to refer to the `Python Development Environment Setup Guide`_ for Google Cloud Platform for instructions.
+
+ .. _Python Development Environment Setup Guide:
+     https://cloud.google.com/python/setup
+
+#. Create a virtualenv. Samples are compatible with Python 2.7 and 3.4+.
+
+    .. code-block:: bash
+
+        $ virtualenv env
+        $ source env/bin/activate
+
+#. Install the dependencies needed to run the samples.
+
+    .. code-block:: bash
+
+        $ pip install -r requirements.txt
+
+.. _pip: https://pip.pypa.io/
+.. _virtualenv: https://virtualenv.pypa.io/
+
+Samples
+-------------------------------------------------------------------------------
+
+- `Hello World`_
+- Concepts_
+- `Logging & Monitoring`_
+- Tips_
+
+
+.. _Hello World: helloworld/
+.. _Concepts: concepts/
+.. _Logging & Monitoring: log/
+.. _Tips: tips/
+
+The client library
+-------------------------------------------------------------------------------
+
+This sample uses the `Google Cloud Client Library for Python`_.
+You can read the documentation for more details on API usage and use GitHub
+to `browse the source`_ and  `report issues`_.
+
+.. _Google Cloud Client Library for Python:
+    https://googlecloudplatform.github.io/google-cloud-python/
+.. _browse the source:
+    https://github.com/GoogleCloudPlatform/google-cloud-python
+.. _report issues:
+    https://github.com/GoogleCloudPlatform/google-cloud-python/issues
+
+
+.. _Google Cloud SDK: https://cloud.google.com/sdk/

functions/README.rst.in

@@ -0,0 +1,18 @@
+# This file is used to generate README.rst
+
+product:
+  name: Google Cloud Functions
+  short_name: GCF
+  url: https://cloud.google.com/functions/docs/
+  description: >
+    Cloud Functions is a lightweight, event-based, asynchronous compute solution that allows you to create small, single-purpose functions that respond to Cloud events without the need to manage a server or a runtime environment.
+
+setup:
+- auth
+- install_deps
+
+samples:
+- name: Hello World
+  file: helloworld/main.py
+
+cloud_client_library: true

functions/concepts/README.md

@@ -0,0 +1,11 @@
+<img src="https://avatars2.githubusercontent.com/u/2810941?v=3&s=96" alt="Google Cloud Platform logo" title="Google Cloud Platform" align="right" height="96" width="96"/>
+
+# Google Cloud Functions - Concepts sample
+
+See:
+
+* [Cloud Functions Concepts tutorial][tutorial]
+* [Cloud Functions Concepts sample source code][code]
+
+[tutorial]: https://cloud.google.com/functions/docs/concepts/exec
+[code]: main.py

functions/concepts/main.py

@@ -0,0 +1,117 @@
+# Copyright 2018 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.
+
+import time
+
+
+# [START functions_concepts_stateless]
+# Global variable, modified within the function by using the global keyword.
+count = 0
+
+
+def statelessness(request):
+    """
+    HTTP Cloud Function that counts how many times it is executed
+    within a specific instance.
+    Args:
+        request (flask.Request): The request object.
+    Returns:
+        The response text, or any set of values that can be turned into a
+        Response object using `make_response`
+        <http://flask.pocoo.org/docs/0.12/api/#flask.Flask.make_response>.
+    """
+    global count
+    count += 1
+
+    # Note: the total function invocation count across
+    # all instances may not be equal to this value!
+    return 'Instance execution count: {}'.format(count)
+# [END functions_concepts_stateless]
+
+
+def heavy_computation():
+    return time.time()
+
+
+def light_computation():
+    return time.time()
+
+
+# [START functions_tips_scopes]
+# Global (instance-wide) scope
+# This computation runs at instance cold-start
+instance_var = heavy_computation()
+
+
+def scope_demo(request):
+    """
+    HTTP Cloud Function that declares a variable.
+    Args:
+        request (flask.Request): The request object.
+    Returns:
+        The response text, or any set of values that can be turned into a
+        Response object using `make_response`
+        <http://flask.pocoo.org/docs/0.12/api/#flask.Flask.make_response>.
+    """
+
+    # Per-function scope
+    # This computation runs every time this function is called
+    function_var = light_computation()
+    return 'Instance: {}; function: {}'.format(instance_var, function_var)
+# [END functions_tips_scopes]
+
+
+# [START functions_concepts_requests]
+def make_request(request):
+    """
+    HTTP Cloud Function that makes another HTTP request.
+    Args:
+        request (flask.Request): The request object.
+    Returns:
+        The response text, or any set of values that can be turned into a
+        Response object using `make_response`
+        <http://flask.pocoo.org/docs/0.12/api/#flask.Flask.make_response>.
+    """
+    import requests
+
+    # The URL to send the request to
+    url = 'http://example.com'
+
+    # Process the request
+    response = requests.get(url)
+    response.raise_for_status()
+    return 'Success!'
+# [END functions_concepts_requests]
+
+
+# [START functions_concepts_after_timeout]
+def timeout(request):
+    print('Function running...')
+    time.sleep(120)
+
+    # May not execute if function's timeout is <2 minutes
+    return 'Done!'
+# [END functions_concepts_after_timeout]
+
+
+# [START functions_concepts_filesystem]
+def list_files(request):
+    import os
+    from os import path
+
+    root = path.dirname(path.abspath(__file__))
+    children = os.listdir(root)
+    files = [c for c in children if path.isfile(path.join(root, c))]
+    return 'Files: {}'.format(files)
+# [END functions_concepts_filesystem]

functions/concepts/main_test.py

@@ -0,0 +1,63 @@
+# Copyright 2018 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.
+
+
+import flask
+import pytest
+import requests
+import responses
+
+import main
+
+
+# Create a fake "app" for generating test request contexts.
+@pytest.fixture(scope="module")
+def app():
+    return flask.Flask(__name__)
+
+
+def test_statelessness(app):
+    with app.test_request_context():
+        res = main.statelessness(flask.request)
+        assert res == 'Instance execution count: 1'
+        res = main.statelessness(flask.request)
+        assert res == 'Instance execution count: 2'
+
+
+def test_scope_demo(app):
+    with app.test_request_context():
+        main.scope_demo(flask.request)
+
+
+@responses.activate
+def test_make_request_200(app):
+    responses.add(responses.GET, 'http://example.com',
+                  json={'status': 'OK'}, status=200)
+    with app.test_request_context():
+        main.make_request(flask.request)
+
+
+@responses.activate
+def test_make_request_404(app):
+    responses.add(responses.GET, 'http://example.com',
+                  json={'error': 'not found'}, status=404)
+    with app.test_request_context():
+        with pytest.raises(requests.exceptions.HTTPError):
+            main.make_request(flask.request)
+
+
+def test_list_files(app):
+    with app.test_request_context():
+        res = main.list_files(flask.request)
+        assert 'main.py' in res

functions/helloworld/README.md

@@ -0,0 +1,11 @@
+<img src="https://avatars2.githubusercontent.com/u/2810941?v=3&s=96" alt="Google Cloud Platform logo" title="Google Cloud Platform" align="right" height="96" width="96"/>
+
+# Google Cloud Functions - Hello World sample
+
+See:
+
+* [Cloud Functions Hello World tutorial][tutorial]
+* [Cloud Functions Hello World sample source code][code]
+
+[tutorial]: https://cloud.google.com/functions/docs/quickstart
+[code]: main.py