{"id":13824866,"url":"https://github.com/GoogleCloudPlatform/functions-framework-python","last_synced_at":"2025-07-08T20:32:22.708Z","repository":{"id":37773983,"uuid":"231433569","full_name":"GoogleCloudPlatform/functions-framework-python","owner":"GoogleCloudPlatform","description":"FaaS (Function as a service) framework for writing portable Python functions","archived":false,"fork":false,"pushed_at":"2025-06-17T21:10:13.000Z","size":473,"stargazers_count":936,"open_issues_count":39,"forks_count":119,"subscribers_count":42,"default_branch":"main","last_synced_at":"2025-06-17T22:23:00.061Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://pypi.org/p/functions-framework/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GoogleCloudPlatform.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-01-02T18:01:56.000Z","updated_at":"2025-06-17T21:04:42.000Z","dependencies_parsed_at":"2023-01-30T04:01:05.371Z","dependency_job_id":"41158fd6-d5fb-4f91-b9b4-e9c3eb3d1303","html_url":"https://github.com/GoogleCloudPlatform/functions-framework-python","commit_stats":{"total_commits":167,"total_committers":34,"mean_commits":4.911764705882353,"dds":0.7365269461077844,"last_synced_commit":"e17555304cfaab6494f4a97e0df6d6f9249de4e2"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"purl":"pkg:github/GoogleCloudPlatform/functions-framework-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Ffunctions-framework-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Ffunctions-framework-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Ffunctions-framework-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Ffunctions-framework-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GoogleCloudPlatform","download_url":"https://codeload.github.com/GoogleCloudPlatform/functions-framework-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Ffunctions-framework-python/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264343728,"owners_count":23593777,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T09:01:10.757Z","updated_at":"2025-07-08T20:32:22.701Z","avatar_url":"https://github.com/GoogleCloudPlatform.png","language":"Python","readme":"# Functions Framework for Python\n\n[![PyPI version](https://badge.fury.io/py/functions-framework.svg)](https://badge.fury.io/py/functions-framework)\n\n[![Python unit CI][ff_python_unit_img]][ff_python_unit_link] [![Python lint CI][ff_python_lint_img]][ff_python_lint_link] [![Python conformace CI][ff_python_conformance_img]][ff_python_conformance_link] ![Security Scorecard](https://api.securityscorecards.dev/projects/github.com/GoogleCloudPlatform/functions-framework-python/badge)\n\nAn open source FaaS (Function as a service) framework for writing portable\nPython functions -- brought to you by the Google Cloud Functions team.\n\nThe Functions Framework lets you write lightweight functions that run in many\ndifferent environments, including:\n\n*   [Google Cloud Run Functions](https://cloud.google.com/functions/)\n*   Your local development machine\n*   [Knative](https://github.com/knative/)-based environments\n\nThe framework allows you to go from:\n\n```python\ndef hello(request):\n    return \"Hello world!\"\n```\n\nTo:\n\n```sh\ncurl http://my-url\n# Output: Hello world!\n```\n\nAll without needing to worry about writing an HTTP server or complicated request handling logic.\n\n## Features\n\n*   Spin up a local development server for quick testing\n*   Invoke a function in response to a request\n*   Automatically unmarshal events conforming to the [CloudEvents](https://cloudevents.io/) spec\n*   Portable between serverless platforms\n\n## Installation\n\nInstall the Functions Framework via `pip`:\n\n```sh\npip install functions-framework\n```\n\nOr, for deployment, add the Functions Framework to your `requirements.txt` file:\n\n```\nfunctions-framework==3.*\n```\n\n## Quickstarts\n\n### Quickstart: HTTP Function (Hello World)\n\nCreate an `main.py` file with the following contents:\n\n```python\nimport flask\nimport functions_framework\n\n@functions_framework.http\ndef hello(request: flask.Request) -\u003e flask.typing.ResponseReturnValue:\n    return \"Hello world!\"\n```\n\n\u003e Your function is passed a single parameter, `(request)`, which is a Flask [`Request`](https://flask.palletsprojects.com/en/3.0.x/api/#flask.Request) object.\n\nRun the following command:\n\n```sh\nfunctions-framework --target hello --debug\n * Serving Flask app \"hello\" (lazy loading)\n * Environment: production\n   WARNING: This is a development server. Do not use it in a production deployment.\n   Use a production WSGI server instead.\n * Debug mode: on\n * Running on http://0.0.0.0:8080/ (Press CTRL+C to quit)\n```\n\n(You can also use `functions-framework-python` if you have multiple\nlanguage frameworks installed).\n\nOpen http://localhost:8080/ in your browser and see *Hello world!*.\n\nOr send requests to this function using `curl` from another terminal window:\n\n```sh\ncurl localhost:8080\n# Output: Hello world!\n```\n\n### Quickstart: CloudEvent Function\n\nCreate an `main.py` file with the following contents:\n\n```python\nimport functions_framework\nfrom cloudevents.http.event import CloudEvent\n\n@functions_framework.cloud_event\ndef hello_cloud_event(cloud_event: CloudEvent) -\u003e None:\n   print(f\"Received event with ID: {cloud_event['id']} and data {cloud_event.data}\")\n```\n\n\u003e Your function is passed a single [CloudEvent](https://github.com/cloudevents/sdk-python/blob/main/cloudevents/sdk/event/v1.py) parameter.\n\nRun the following command to run `hello_cloud_event` target locally:\n\n```sh\nfunctions-framework --target=hello_cloud_event\n```\n\nIn a different terminal, `curl` the Functions Framework server:\n\n```sh\ncurl -X POST localhost:8080 \\\n   -H \"Content-Type: application/cloudevents+json\" \\\n   -d '{\n\t\"specversion\" : \"1.0\",\n\t\"type\" : \"example.com.cloud.event\",\n\t\"source\" : \"https://example.com/cloudevents/pull\",\n\t\"subject\" : \"123\",\n\t\"id\" : \"A234-1234-1234\",\n\t\"time\" : \"2018-04-05T17:31:00Z\",\n\t\"data\" : \"hello world\"\n}'\n```\n\nOutput from the terminal running `functions-framework`:\n```\nReceived event with ID: A234-1234-1234 and data hello world\n``` \n\nMore info on sending [CloudEvents](http://cloudevents.io) payloads, see [`examples/cloud_run_cloud_events`](examples/cloud_run_cloud_events/) instruction.\n\n\n### Quickstart: Error handling\n\nThe framework includes an error handler that is similar to the\n[`flask.Flask.errorhandler`](https://flask.palletsprojects.com/en/1.1.x/api/#flask.Flask.errorhandler)\nfunction, which allows you to handle specific error types with a decorator:\n\n```python\nimport functions_framework\n\n\n@functions_framework.errorhandler(ZeroDivisionError)\ndef handle_zero_division(e):\n    return \"I'm a teapot\", 418\n\n\ndef function(request):\n    1 / 0\n    return \"Success\", 200\n```\n\nThis function will catch the `ZeroDivisionError` and return a different\nresponse instead.\n\n### Quickstart: Pub/Sub emulator\n1. Create a `main.py` file with the following contents:\n\n   ```python\n   def hello(event, context):\n        print(\"Received\", context.event_id)\n   ```\n\n1. Start the Functions Framework on port 8080:\n\n   ```sh\n   functions-framework --target=hello --signature-type=event --debug --port=8080\n   ```\n\n1. In a second terminal, start the Pub/Sub emulator on port 8085.\n\n   ```sh\n   export PUBSUB_PROJECT_ID=my-project\n   gcloud beta emulators pubsub start \\\n       --project=$PUBSUB_PROJECT_ID \\\n       --host-port=localhost:8085\n   ```\n\n   You should see the following after the Pub/Sub emulator has started successfully:\n\n   ```none\n   [pubsub] INFO: Server started, listening on 8085\n   ```\n\n1. In a third terminal, create a Pub/Sub topic and attach a push subscription to the topic, using `http://localhost:8080` as its push endpoint. [Publish](https://cloud.google.com/pubsub/docs/quickstart-client-libraries#publish_messages) some messages to the topic. Observe your function getting triggered by the Pub/Sub messages.\n\n   ```sh\n   export PUBSUB_PROJECT_ID=my-project\n   export TOPIC_ID=my-topic\n   export PUSH_SUBSCRIPTION_ID=my-subscription\n   $(gcloud beta emulators pubsub env-init)\n\n   git clone https://github.com/googleapis/python-pubsub.git\n   cd python-pubsub/samples/snippets/\n   pip install -r requirements.txt\n\n   python publisher.py $PUBSUB_PROJECT_ID create $TOPIC_ID\n   python subscriber.py $PUBSUB_PROJECT_ID create-push $TOPIC_ID $PUSH_SUBSCRIPTION_ID http://localhost:8080\n   python publisher.py $PUBSUB_PROJECT_ID publish $TOPIC_ID\n   ```\n\n   You should see the following after the commands have run successfully:\n\n   ```none\n   Created topic: projects/my-project/topics/my-topic\n\n   topic: \"projects/my-project/topics/my-topic\"\n   push_config {\n     push_endpoint: \"http://localhost:8080\"\n   }\n   ack_deadline_seconds: 10\n   message_retention_duration {\n     seconds: 604800\n   }\n   .\n   Endpoint for subscription is: http://localhost:8080\n\n   1\n   2\n   3\n   4\n   5\n   6\n   7\n   8\n   9\n   Published messages to projects/my-project/topics/my-topic.\n   ```\n\n   And in the terminal where the Functions Framework is running:\n\n   ```none\n    * Serving Flask app \"hello\" (lazy loading)\n    * Environment: production\n      WARNING: This is a development server. Do not use it in a production deployment.\n      Use a production WSGI server instead.\n    * Debug mode: on\n    * Running on http://0.0.0.0:8080/ (Press CTRL+C to quit)\n    * Restarting with fsevents reloader\n    * Debugger is active!\n    * Debugger PIN: 911-794-046\n   Received 1\n   127.0.0.1 - - [11/Aug/2021 14:42:22] \"POST / HTTP/1.1\" 200 -\n   Received 2\n   127.0.0.1 - - [11/Aug/2021 14:42:22] \"POST / HTTP/1.1\" 200 -\n   Received 5\n   127.0.0.1 - - [11/Aug/2021 14:42:22] \"POST / HTTP/1.1\" 200 -\n   Received 6\n   127.0.0.1 - - [11/Aug/2021 14:42:22] \"POST / HTTP/1.1\" 200 -\n   Received 7\n   127.0.0.1 - - [11/Aug/2021 14:42:22] \"POST / HTTP/1.1\" 200 -\n   Received 8\n   127.0.0.1 - - [11/Aug/2021 14:42:22] \"POST / HTTP/1.1\" 200 -\n   Received 9\n   127.0.0.1 - - [11/Aug/2021 14:42:39] \"POST / HTTP/1.1\" 200 -\n   Received 3\n   127.0.0.1 - - [11/Aug/2021 14:42:39] \"POST / HTTP/1.1\" 200 -\n   Received 4\n   127.0.0.1 - - [11/Aug/2021 14:42:39] \"POST / HTTP/1.1\" 200 -\n   ```\n\nFor more details on extracting data from a Pub/Sub event, see\nhttps://cloud.google.com/functions/docs/tutorials/pubsub#functions_helloworld_pubsub_tutorial-python\n\n### Quickstart: Build a Deployable Container\n\n1. Install [Docker](https://store.docker.com/search?type=edition\u0026offering=community) and the [`pack` tool](https://buildpacks.io/docs/install-pack/).\n\n1. Build a container from your function using the Functions [buildpacks](https://github.com/GoogleCloudPlatform/buildpacks):\n\n        pack build \\\n            --builder gcr.io/buildpacks/builder:v1 \\\n            --env GOOGLE_FUNCTION_SIGNATURE_TYPE=http \\\n            --env GOOGLE_FUNCTION_TARGET=hello \\\n            my-first-function\n\n1. Start the built container:\n\n        docker run --rm -p 8080:8080 my-first-function\n        # Output: Serving function...\n\n1. Send requests to this function using `curl` from another terminal window:\n\n        curl localhost:8080\n        # Output: Hello World!\n\n## Run your function on serverless platforms\n\n### Google Cloud Run functions\n\nThis Functions Framework is based on the [Python Runtime on Google Cloud Functions](https://cloud.google.com/functions/docs/concepts/python-runtime).\n\nOn Cloud Functions, using the Functions Framework is not necessary: you don't need to add it to your `requirements.txt` file.\n\nAfter you've written your function, you can simply deploy it from your local machine using the `gcloud` command-line tool. [Check out the Cloud Functions quickstart](https://cloud.google.com/functions/docs/quickstart).\n\n### Container environments based on Knative\n\nCloud Run and Cloud Run on GKE both implement the [Knative Serving API](https://www.knative.dev/docs/). The Functions Framework is designed to be compatible with Knative environments. Just build and deploy your container to a Knative environment.\n\n## Configure the Functions Framework\n\nYou can configure the Functions Framework using command-line flags or environment variables. If you specify both, the environment variable will be ignored.\n\n| Command-line flag  | Environment variable      | Description                                                                                                                                                                                      |\n| ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `--host`           | `HOST`                    | The host on which the Functions Framework listens for requests. Default: `0.0.0.0`                                                                                                               |\n| `--port`           | `PORT`                    | The port on which the Functions Framework listens for requests. Default: `8080`                                                                                                                  |\n| `--target`         | `FUNCTION_TARGET`         | The name of the exported function to be invoked in response to requests. Default: `function`                                                                                                     |\n| `--signature-type` | `FUNCTION_SIGNATURE_TYPE` | The signature used when writing your function. Controls unmarshalling rules and determines which arguments are used to invoke your function. Default: `http`; accepted values: `http`, `event` or `cloudevent` |\n| `--source`         | `FUNCTION_SOURCE`         | The path to the file containing your function. Default: `main.py` (in the current working directory)                                                                                             |\n| `--debug`          | `DEBUG`                   | A flag that allows to run functions-framework to run in debug mode, including live reloading. Default: `False`                                                                                   |\n\n## Enable Google Cloud Run function Events\n\nThe Functions Framework can unmarshall incoming\nGoogle Cloud Run functions [event](https://cloud.google.com/functions/docs/concepts/events-triggers#events) payloads to `event` and `context` objects.\nThese will be passed as arguments to your function when it receives a request.\nNote that your function must use the `event`-style function signature:\n\n```python\ndef hello(event, context):\n    print(event)\n    print(context)\n```\n\nTo enable automatic unmarshalling, set the function signature type to `event`\n using the `--signature-type` command-line flag or the `FUNCTION_SIGNATURE_TYPE` environment variable. By default, the HTTP\nsignature will be used and automatic event unmarshalling will be disabled.\n\nFor more details on this signature type, see the Google Cloud Functions\ndocumentation on\n[background functions](https://cloud.google.com/functions/docs/writing/background#cloud_pubsub_example).\n\nSee the [running example](examples/cloud_run_event).\n\n## Advanced Examples\n\nMore advanced guides can be found in the [`examples/`](examples/) directory.\nYou can also find examples on using the CloudEvent Python SDK [here](https://github.com/cloudevents/sdk-python).\n\n## Contributing\n\nContributions to this library are welcome and encouraged. See [CONTRIBUTING](CONTRIBUTING.md) for more information on how to get started.\n\n[ff_python_unit_img]: https://github.com/GoogleCloudPlatform/functions-framework-python/workflows/Python%20Unit%20CI/badge.svg\n[ff_python_unit_link]: https://github.com/GoogleCloudPlatform/functions-framework-python/actions?query=workflow%3A\"Python+Unit+CI\"\n[ff_python_lint_img]: https://github.com/GoogleCloudPlatform/functions-framework-python/workflows/Python%20Lint%20CI/badge.svg\n[ff_python_lint_link]: https://github.com/GoogleCloudPlatform/functions-framework-python/actions?query=workflow%3A\"Python+Lint+CI\"\n[ff_python_conformance_img]: https://github.com/GoogleCloudPlatform/functions-framework-python/workflows/Python%20Conformance%20CI/badge.svg\n[ff_python_conformance_link]: https://github.com/GoogleCloudPlatform/functions-framework-python/actions?query=workflow%3A\"Python+Conformance+CI\"\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGoogleCloudPlatform%2Ffunctions-framework-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGoogleCloudPlatform%2Ffunctions-framework-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGoogleCloudPlatform%2Ffunctions-framework-python/lists"}