Merge pull request #32181 from abrennan89/techpreview2

[srvls][SRVOCF-278] Adding Python functions docs

Author: kalexand-rh

_topic_map.yml

@@ -2942,15 +2942,17 @@ Topics:
 - Name: Using Apache Kafka with OpenShift Serverless
   File: serverless-kafka
 # Functions - uncomment at tech preview
-#- Name: Functions
-#  Dir: functions
+# - Name: OpenShift Serverless Functions
+#   Dir: functions
 #  Topics:
-#  - Name: About Functions
+#  - Name: About OpenShift Serverless Functions
 #    File: serverless-functions-about
-#  - Name: Setting up Functions
-#    File: serverless-functions-setup
-#  - Name: Getting started with Functions
+#  - Name: Getting started
 #    File: serverless-functions-getting-started
+#  - Name: Setting up OpenShift Serverless Functions
+#    File: serverless-functions-setup
+#  - Name: Developing Python functions
+#    File: serverless-developing-python-functions
 # Networking
 - Name: Networking
   Dir: networking

modules/serverless-create-func-kn.adoc

@@ -28,7 +28,7 @@ envVars: {}
 
 .Procedure
 
-* Create a {FunctionsProductShortName} project:
+* Create a function project:
 +
 [source,terminal]
 ----

modules/serverless-document-attributes.adoc

@@ -11,7 +11,6 @@
 :ServerlessProductShortName: Serverless
 :ServerlessOperatorName: OpenShift Serverless Operator
 :FunctionsProductName: OpenShift Serverless Functions
-:FunctionsProductShortName: Functions
 //
 // Documentation publishing attributes used in the master-docinfo.xml file
 // Note that the DocInfoProductName generates the URL for the product page.

modules/serverless-invoking-python-functions.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies
+//
+// * /serverless/functions/serverless-developing-python-functions.adoc
+
+[id="serverless-invoking-python-functions_{context}"]
+= About invoking Python functions
+
+Python functions can be invoked with a simple HTTP request. When an incoming request is received, functions are invoked with a `context` object as the first parameter. The `context` object is a Python class with two attributes:
+
+* The `request` attribute is always present, and contains the Flask `request` object.
+* The second attribute, `cloud_event`, is populated if the incoming request is a `CloudEvent`.
+
+Developers can access any `CloudEvent` data from the context object.
+
+.Example context object
+[source,python]
+----
+def main(context: Context):
+    """
+    The context parameter contains the Flask request object and any
+    CloudEvent received with the request.
+    """
+    print(f"Method: {context.request.method}")
+    print(f"Event data {context.cloud_event.data}")
+    # ... business logic here
+----

modules/serverless-python-function-return-values.adoc

@@ -0,0 +1,37 @@
+// Module included in the following assemblies
+//
+// * /serverless/functions/serverless-developing-python-functions.adoc
+
+[id="serverless-python-function-return-values_{context}"]
+= Python function return values
+
+Functions can return any value supported by https://flask.palletsprojects.com/en/1.1.x/quickstart/#about-responses[Flask] because the invocation framework proxies these values directly to the Flask server.
+
+.Example
+[source,python]
+----
+def main(context: Context):
+    body = { "message": "Howdy!" }
+    headers = { "content-type": "application/json" }
+    return body, 200, headers
+----
+
+Functions can set both headers and response codes as secondary and tertiary response values from function invocation.
+
+[id="serverless-python-function-return-values-returning-events_{context}"]
+== Returning CloudEvents
+
+Developers can use the `@event` decorator to tell the invoker that the function return value must be converted to a CloudEvent before sending the response.
+
+.Example
+[source,python]
+----
+@event("event_source"="/my/function", "event_type"="my.type")
+def main(context):
+    # business logic here
+    data = do_something()
+    # more data processing
+    return data
+----
+
+This example sends a CloudEvent as the response value, with a type of `"my.type"` and a source of `"/my/function"`. The CloudEvent [`data` property](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#event-data) is set to the returned `data` variable. The `event_source` and `event_type` decorator attributes are both optional.

modules/serverless-python-template.adoc

@@ -0,0 +1,28 @@
+// Module included in the following assemblies
+//
+// * /serverless/functions/serverless-developing-python-functions.adoc
+
+[id="serverless-python-template_{context}"]
+= Python function template structure
+
+When you create a Python function by using the `kn func` CLI, the project directory looks similar to a typical Python project.
+
+Python functions have very few restrictions. The only requirements are that your project contains a `func.py` file that contains a `main()` function, and a `func.yaml` configuration file.
+
+Developers are not restricted to the dependencies provided in the template `requirements.txt` file. Additional dependencies can be added as they would be in any other Python project. When the project is built for deployment, these dependencies will be included in the created runtime container image.
+
+Both `http` and `event` trigger functions have the same template structure:
+
+.Template structure
+[source,terminal]
+----
+fn
+├── func.py <1>
+├── func.yaml <2>
+├── requirements.txt <3>
+└── test_func.py <4>
+----
+<1> Contains a `main()` function.
+<2> Used to determine the image name and registry.
+<3> Additional dependencies can be added to the `requirements.txt` file as they are in any other Python project.
+<4> Contains a simple unit test that can be used to test your function locally.

modules/serverless-testing-python-functions.adoc

@@ -0,0 +1,31 @@
+// Module included in the following assemblies
+//
+// * /serverless/functions/serverless-developing-python-functions.adoc
+
+[id="serverless-testing-python-functions_{context}"]
+= Testing Python functions
+
+Python functions can be tested locally on your computer. The default project contains a `test_func.py` file, which provides a simple unit test for functions.
+
+.Prerequisites
+
+* To run Python functions tests locally, you must install the required dependencies:
++
+[source,terminal]
+----
+$ pip install -r requirements.txt
+----
+
+.Procedure
+
+. After you have installed the dependencies, run the tests:
++
+[source,terminal]
+----
+$ python3 test_func.py
+----
+
+[NOTE]
+====
+The default test framework for Python functions is `unittest`. You can use a different test framework if you prefer.
+====

serverless/functions/serverless-developing-python-functions.adoc

@@ -0,0 +1,27 @@
+include::modules/serverless-document-attributes.adoc[]
+[id="serverless-developing-python-functions"]
+= Developing Python functions
+:context: serverless-developing-python-functions
+include::modules/common-attributes.adoc[]
+
+toc::[]
+
+:FeatureName: {FunctionsProductName}
+include::modules/technology-preview.adoc[leveloffset=+2]
+
+After you have xref:../../serverless/functions/serverless-functions-getting-started.adoc#serverless-functions-getting-started[created a Python function project], you can modify the template files provided to add business logic to your function.
+
+[id="prerequisites_serverless-developing-python-functions"]
+== Prerequisites
+
+* Before you can develop functions, you must complete the set up steps in xref:../../serverless/functions/serverless-functions-setup.adoc#serverless-functions-setup[Setting up {FunctionsProductName}].
+
+include::modules/serverless-python-template.adoc[leveloffset=+1]
+include::modules/serverless-invoking-python-functions.adoc[leveloffset=+1]
+include::modules/serverless-python-function-return-values.adoc[leveloffset=+1]
+include::modules/serverless-testing-python-functions.adoc[leveloffset=+1]
+
+[id="next-steps_serverless-developing-python-functions"]
+== Next steps
+
+* xref:../../serverless/functions/serverless-functions-getting-started.adoc#serverless-functions-getting-started[Build and deploy a function].

serverless/functions/serverless-functions-about.adoc

@@ -1,6 +1,6 @@
 include::modules/serverless-document-attributes.adoc[]
 [id="serverless-functions-about"]
-= About {FunctionsProductShortName}
+= About {FunctionsProductName}
 :context: serverless-functions-about
 include::modules/common-attributes.adoc[]
 
@@ -20,7 +20,12 @@ The `kn func` CLI is provided as a plug-in for the Knative `kn` CLI. {FunctionsP
 
 // add xref links to docs once added
 * Node.js
-* Python
+* xref:../../serverless/functions/serverless-developing-python-functions.adoc#serverless-developing-python-functions[Python]
 * Golang
 * Quarkus
 //* SpringBoot - TBC
+
+[id="next-steps_serverless-functions-about"]
+== Next steps
+
+* See xref:../../serverless/functions/serverless-functions-getting-started.adoc#serverless-functions-getting-started[Getting started].

serverless/functions/serverless-functions-getting-started.adoc

@@ -1,6 +1,6 @@
 include::modules/serverless-document-attributes.adoc[]
 [id="serverless-functions-getting-started"]
-= Getting started with {FunctionsProductShortName}
+= Getting started
 :context: serverless-functions-getting-started
 include::modules/common-attributes.adoc[]
 
@@ -12,10 +12,10 @@ include::modules/technology-preview.adoc[leveloffset=+2]
 This guide explains how you can create and manage a function on an {ServerlessProductName} installation by using the `kn` CLI.
 // TODO: add info about developer console at 4.8 when this is supported.
 
-[id="prerequisites_serverless-functions-getting-started]
+[id="prerequisites_serverless-functions-getting-started"]
 == Prerequisites
 
-Before you can complete the following procedures, you must ensure that you have completed all of the prerequisite tasks in xref:../../serverless/functions/serverless-functions-setup.adoc#serverless-functions-setup[Setting up {FunctionsProductShortName}].
+Before you can complete the following procedures, you must ensure that you have completed all of the prerequisite tasks in xref:../../serverless/functions/serverless-functions-setup.adoc#serverless-functions-setup[Setting up {FunctionsProductName}].
 
 include::modules/serverless-create-func-kn.adoc[leveloffset=+1]
 include::modules/serverless-build-func-kn.adoc[leveloffset=+1]