Skip to content

Latest commit

 

History

History
160 lines (126 loc) · 5.71 KB

python.md

File metadata and controls

160 lines (126 loc) · 5.71 KB

Python Function Developer's Guide

When creating a Python function using the func CLI, the project directory looks like a typical Python project. Both HTTP and Event functions have the same template structure.

❯ func create -l python fn
Project path: /home/developer/src/fn
Function name: fn
Runtime: python

❯ tree
fn
├── func.py
├── func.yaml
├── requirements.txt
└── test_func.py

Aside from the func.yaml file, this looks like the beginning of just about any Python project. For now, we will ignore the func.yaml file, and just say that it is a configuration file that is used when building your project. If you're really interested, check out the reference doc. To learn more about the CLI and the details for each supported command, see the CLI Commands document.

Running the function locally

To run a function, you'll first need to build it. This step creates an OCI container image that can be run locally on your computer, or on a Kubernetes cluster.

❯ func build

After the function has been built, it can be run locally.

❯ func run

Functions can be invoked with a simple HTTP request. You can test to see if the function is working by using your browser to visit http://localhost:8080. You can also access liveness and readiness endpoints at http://localhost:8080/health/liveness and http://localhost:8080/health/readiness. These two endpoints are used by Kubernetes to determine the health of your function. If everything is good, both of these will return OK.

Deploying the function to a cluster

To deploy your function to a Kubernetes cluster, use the deploy command.

❯ func deploy

You can get the URL for your deployed function with the info command.

❯ func info

Testing a function locally

Python functions can be tested locally on your computer. In the project there is a test_func.py file which contains a simple unit test. To run the test locally, you'll need to install the required dependencies. You do this as you would with any Python project.

❯ pip install -r requirements.txt

Once you have done this, you can run the provided tests with python3 test_func.py. The default test framework for Python functions is unittest. If you prefer another, that's no problem. Just install a test framework more to your liking.

Function reference

Boson Python functions have very few restrictions. You can add any required dependencies in requirements.txt, and you may include additional local Python files. The only real requirements are that your project contain a func.py file which contains a main() function. In this section, we will look in a little more detail at how Boson functions are invoked, and what APIs are available to you as a developer.

Invocation parameters

When using the func CLI to create a function project, you may choose to generate a project that responds to a CloudEvent or simple HTTP. CloudEvents in Knative are transported over HTTP as a POST request, so in many ways, the two types of functions are very much the same. They each will listen and respond to incoming HTTP events.

When an incoming request is received, your function will be invoked with a Context object as the first parameter. This object is a Python class with two attributes. The request attribute will always be present, and contains the Flask request object. The second attribute, cloud_event, will be populated if the incoming request is a CloudEvent. Developers may access any CloudEvent data from the context object. For example:

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

Return Values

Functions may return any value supported by Flask, as the invocation framework proxies these values directly to the Flask server. See the Flask documentation for more information.

Example

def main(context: Context):
    body = { "message": "Howdy!" }
    headers = { "content-type": "application/json" }
    return body, 200, headers

Note that functions may set both headers and response codes as secondary and tertiary response values from function invocation.

CloudEvents

All event messages in Knative are sent as CloudEvents over HTTP. As noted above, function developers may access an event through the context parameter when the function is invoked. Additionally, developers may use an @event decorator to inform the invoker that this function's return value should be converted to a CloudEvent before sending the response. For example:

@event("event_source"="/my/function", "event_type"="my.type")
def main(context):
    # business logic here
    data = do_something()
    # more data processing
    return data

This will result in a CloudEvent as the response value, with a type of "my.type", a source of "/my/function", and the data property set to data. Both the event_source and event_type decorator attributes are optional. If not supplied, the CloudEvent's source attribute will be set to "/parliament/function" and the type will be set to "parliament.response".

Dependencies

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 project by simply adding them to the requirements.txt file. When the project is built for deployment, these dependencies will be included in the container image.