Functions Framework for Python

The Functions Framework is an open-source FaaS (Function as a service) framework that allows you to write portable Python functions. It abstracts away the complexity of writing an HTTP server or handling request logic, allowing your code to run in multiple environments:

• Google Cloud Run Functions (via direct deployment with gcloud)
• Local development machines (using the functions-framework CLI)
• Knative-based environments (by building a container with Buildpacks)

The Functions Framework for Python supports various deployment patterns to Google Cloud Run. Depending on your function type, you can use the following example patterns:

• HTTP Functions: Use cloud_run_http for standard request/response HTTP functions.
• CloudEvent Functions: Use cloud_run_event or cloud_run_cloud_events to deploy functions triggered by CloudEvents.
• Asynchronous Functions: Use cloud_run_async for deploying asynchronous HTTP and CloudEvent functions.
• Streaming HTTP: Use cloud_run_streaming_http for functions that require streaming HTTP responses.

Use the gcloud run deploy command to deploy an asynchronous HTTP function to Cloud Run. You must specify the source directory, the function target name, and a base image (e.g., python312).

gcloud run deploy async-http-function \
    --source . \
    --function hello_async_http \
    --base-image python312 \
    --region <YOUR_REGION>

To test a CloudEvent function locally, you can build a Docker image from the provided sample and run it. The function expects to bind to a specific port (defaulting to 8080) via the PORT environment variable.

1. Build the image: Use docker build to create the container image.
2. Run the container: Use docker run to start the service, mapping the host port to the container port and setting the PORT environment variable.
3. Send an event: Use the provided script to trigger an event against the running container.

# Build the Docker image
docker build -t cloud_event_example .

# Run the image and bind the correct ports
docker run --rm -p 8080:8080 -e PORT=8080 cloud_event_example

# Send an event to the container (in a separate terminal)
docker run -t cloud_event_example send_cloud_event.py

You can deploy streaming functions to Cloud Run using the gcloud run deploy command. You must specify the --function flag to indicate which function target to run and the --base-image to define the Python runtime environment.

# Deploy the synchronous streaming function
gcloud run deploy streaming-function \
    --source . \
    --function hello_stream \
    --base-image python312 \
    --region <YOUR_REGION>

# Deploy the asynchronous streaming function
gcloud run deploy streaming-async-function \
    --source . \
    --function hello_stream_async \
    --base-image python312 \
    --region <YOUR_REGION>

To run an asynchronous HTTP function locally for testing, use the functions-framework CLI and point it to the specific function target. By default, the framework listens on port 8080.

functions-framework --target=hello_async_http

# In another terminal, test the endpoint:
curl localhost:8080

Install skaffold following the instructions for your platform at https://skaffold.dev/docs/install/.

Verify the installation:

skaffold version

To start the development workflow, run skaffold dev. This command watches for code changes and automatically redeploys your functions to the local cluster, providing a live-reloading experience.

skaffold version
# In a separate terminal to start watching for changes:
skaffold dev

Before running or deploying the async examples, install the required Python packages using pip.

pip install -r requirements.txt

To run a Python function in a container, create a Dockerfile that uses a Python base image, copies your local code (including main.py and requirements.txt), installs functions-framework and your dependencies, and uses the functions-framework CLI to start the web service.

Note that the CMD must use the --target flag to specify the name of the function defined in your code.

# 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
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

The project uses tox to manage test execution across different Python versions. Use the following commands to run various test configurations:

• Run all tests: Executes the full test suite.
• Run tests for the current Python version: Uses the py environment.
• Run tests for a specific Python version: Use the environment name for that version (e.g., py3.12).
• Run a specific test file: Pass the file path after the -- separator.
• Run a specific test case: Pass the file path and the test function name using the :: syntax after the -- separator.

# All tests
$ python -m tox

# Current Python version
$ python -m tox -e py

# Specific Python version
$ python -m tox -e py3.12

# Specific test file
$ python -m tox -e py -- tests/test_cli.py

# Specific test in a file
$ python -m tox -e py -- tests/test_cli.py::test_cli_no_arguments

Build and run your function container locally using Docker. Ensure you map the port (typically 8080) and set the PORT environment variable so the Functions Framework knows which port to listen on.

docker build -t helloworld . && docker run --rm -p 8080:8080 -e PORT=8080 helloworld

# Test the function with curl
curl localhost:8080