# Apache Flink Stateful Functions
Stateful Functions is an API that simplifies the building of **distributed stateful applications** with a **runtime built for serverless architectures**.
It brings together the benefits of stateful stream processing - the processing of large datasets with low latency and bounded resource constraints -
along with a runtime for modeling stateful entities that supports location transparency, concurrency, scaling, and resiliency.
<img alt="Stateful Functions Architecture" width="80%" src="https://github.com/apache/flink-statefun/blob/master/docs/fig/concepts/arch_overview.svg">
It is designed to work with modern architectures, like cloud-native deployments and popular event-driven FaaS platforms
like AWS Lambda and KNative, and to provide out-of-the-box consistent state and messaging while preserving the serverless
experience and elasticity of these platforms.
Stateful Functions is developed under the umbrella of [Apache Flink](https://flink.apache.org/).
This README is meant as a brief walkthrough on the StateFun Python SDK and how to set things up
to get yourself started with Stateful Functions in Python.
For a fully detailed documentation, please visit the [official docs](https://ci.apache.org/projects/flink/flink-statefun-docs-master).
For code examples, please take a look at the [examples](https://github.com/apache/flink-statefun-playground/tree/release-3.3/python).
## Table of Contents
- [Python SDK Overview](#sdkoverview)
- [Contributing](#contributing)
- [License](#license)
## <a name="sdkoverview"></a> Python SDK Overview
### Background
The JVM-based Stateful Functions implementation has a `RequestReply` extension (a protocol and an implementation) that allows calling into any HTTP endpoint that implements that protocol. Although it is possible to implement this protocol independently, this is a minimal library for the Python programing language that:
* Allows users to define and declare their functions in a convenient way.
* Dispatches an invocation request sent from the JVM to the appropriate function previously declared.
### A Mini-Tutorial
#### Define and Declare a Function
```
from statefun import *
functions = StatefulFunctions()
@functions.bind(typename="demo/greeter")
def greet(context, message):
print(f"Hey {message.as_string()}!")
```
This code declares a function with of type `demo/greeter` and binds it to the instance.
#### Registering and accessing persisted state
You can register persistent state that will be managed by the Stateful Functions workers
for state consistency and fault-tolerance. Values can be generally obtained via the context parameter:
```
from statefun import *
functions = StatefulFunctions()
@functions.bind(
typename="demo/greeter",
specs=[ValueSpec(name="seen", type=IntType)])
def greet(context, message):
seen = context.storage.seen or 0
seen += 1
context.storage.seen = seen
print(f"Hey {message.as_string()} I've seen you {seen} times")
```
#### Expose with a Request Reply Handler
```
handler = RequestReplyHandler(functions)
```
#### Using the Handler with your Favorite HTTP Serving Framework
For example, using Flask:
```
@app.route('/statefun', methods=['POST'])
def handle():
response_data = handler.handle_sync(request.data)
response = make_response(response_data)
response.headers.set('Content-Type', 'application/octet-stream')
return response
if __name__ == "__main__":
app.run()
```
This creates an HTTP server that accepts requests from the Stateful Functions cluster and
dispatches it to the handler.
#### Composing the Module YAML File
The remaining step would be to declare this function type in a module.yaml
```
functions:
- function:
meta:
kind: http
type: demo/greeter
spec:
endpoint: http://<end point url>/statefun
```
### Testing
1. Create a virtual environment
```
python3 -m venv venv
source venv/bin/activate
```
2. Install dependencies
```
pip3 install .
```
3. Run unit tests
```
python3 -m unittest tests
```
## <a name="contributing"></a>Contributing
There are multiple ways to enhance the Stateful Functions API for different types of applications; the runtime and operations will also evolve with the developments in Apache Flink.
You can learn more about how to contribute in the [Apache Flink website](https://flink.apache.org/contributing/how-to-contribute.html). For code contributions, please read carefully the [Contributing Code](https://flink.apache.org/contributing/contribute-code.html) section and check the _Stateful Functions_ component in [Jira](https://issues.apache.org/jira/browse/FLINK-15969?jql=project%20%3D%20FLINK%20AND%20component%20%3D%20%22Stateful%20Functions%22) for an overview of ongoing community work.
## <a name="license"></a>License
The code in this repository is licensed under the [Apache Software License 2](LICENSE).
Raw data
{
"_id": null,
"home_page": "https://github.com/apache/flink-statefun",
"name": "apache-flink-statefun",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Apache Software Foundation",
"author_email": "dev@flink.apache.org",
"download_url": "https://files.pythonhosted.org/packages/28/41/f52192c1d6303682f3076b443842fa94504ab13835c3328d46e85c71a733/apache-flink-statefun-3.3.0.tar.gz",
"platform": null,
"description": "# Apache Flink Stateful Functions\n\nStateful Functions is an API that simplifies the building of **distributed stateful applications** with a **runtime built for serverless architectures**.\nIt brings together the benefits of stateful stream processing - the processing of large datasets with low latency and bounded resource constraints -\nalong with a runtime for modeling stateful entities that supports location transparency, concurrency, scaling, and resiliency.\n\n<img alt=\"Stateful Functions Architecture\" width=\"80%\" src=\"https://github.com/apache/flink-statefun/blob/master/docs/fig/concepts/arch_overview.svg\">\n\nIt is designed to work with modern architectures, like cloud-native deployments and popular event-driven FaaS platforms\nlike AWS Lambda and KNative, and to provide out-of-the-box consistent state and messaging while preserving the serverless\nexperience and elasticity of these platforms.\n\nStateful Functions is developed under the umbrella of [Apache Flink](https://flink.apache.org/).\n\nThis README is meant as a brief walkthrough on the StateFun Python SDK and how to set things up\nto get yourself started with Stateful Functions in Python.\n\nFor a fully detailed documentation, please visit the [official docs](https://ci.apache.org/projects/flink/flink-statefun-docs-master).\n\nFor code examples, please take a look at the [examples](https://github.com/apache/flink-statefun-playground/tree/release-3.3/python).\n\n## Table of Contents\n\n- [Python SDK Overview](#sdkoverview)\n- [Contributing](#contributing)\n- [License](#license)\n\n## <a name=\"sdkoverview\"></a> Python SDK Overview\n\n### Background\n\nThe JVM-based Stateful Functions implementation has a `RequestReply` extension (a protocol and an implementation) that allows calling into any HTTP endpoint that implements that protocol. Although it is possible to implement this protocol independently, this is a minimal library for the Python programing language that:\n\n* Allows users to define and declare their functions in a convenient way.\n\n* Dispatches an invocation request sent from the JVM to the appropriate function previously declared.\n\n### A Mini-Tutorial\n\n#### Define and Declare a Function\n\n```\nfrom statefun import *\n\nfunctions = StatefulFunctions()\n\n@functions.bind(typename=\"demo/greeter\")\ndef greet(context, message):\n print(f\"Hey {message.as_string()}!\")\n```\n\nThis code declares a function with of type `demo/greeter` and binds it to the instance.\n\n#### Registering and accessing persisted state\n\nYou can register persistent state that will be managed by the Stateful Functions workers\nfor state consistency and fault-tolerance. Values can be generally obtained via the context parameter:\n\n```\nfrom statefun import *\n\nfunctions = StatefulFunctions()\n\n@functions.bind(\n typename=\"demo/greeter\",\n specs=[ValueSpec(name=\"seen\", type=IntType)])\ndef greet(context, message):\n seen = context.storage.seen or 0\n seen += 1\n context.storage.seen = seen\n print(f\"Hey {message.as_string()} I've seen you {seen} times\")\n```\n\n#### Expose with a Request Reply Handler\n\n```\nhandler = RequestReplyHandler(functions)\n```\n\n#### Using the Handler with your Favorite HTTP Serving Framework\n\nFor example, using Flask:\n\n```\n@app.route('/statefun', methods=['POST'])\ndef handle():\n response_data = handler.handle_sync(request.data)\n response = make_response(response_data)\n response.headers.set('Content-Type', 'application/octet-stream')\n return response\n\nif __name__ == \"__main__\":\n app.run()\n```\n\nThis creates an HTTP server that accepts requests from the Stateful Functions cluster and\ndispatches it to the handler.\n\n#### Composing the Module YAML File\n\nThe remaining step would be to declare this function type in a module.yaml\n\n```\nfunctions:\n - function:\n meta:\n kind: http\n type: demo/greeter\n spec:\n endpoint: http://<end point url>/statefun\n```\n\n### Testing\n\n1. Create a virtual environment\n\n```\npython3 -m venv venv\nsource venv/bin/activate\n```\n\n2. Install dependencies\n\n```\npip3 install .\n```\n\n3. Run unit tests\n\n```\npython3 -m unittest tests\n```\n\n## <a name=\"contributing\"></a>Contributing\n\nThere are multiple ways to enhance the Stateful Functions API for different types of applications; the runtime and operations will also evolve with the developments in Apache Flink.\n\nYou can learn more about how to contribute in the [Apache Flink website](https://flink.apache.org/contributing/how-to-contribute.html). For code contributions, please read carefully the [Contributing Code](https://flink.apache.org/contributing/contribute-code.html) section and check the _Stateful Functions_ component in [Jira](https://issues.apache.org/jira/browse/FLINK-15969?jql=project%20%3D%20FLINK%20AND%20component%20%3D%20%22Stateful%20Functions%22) for an overview of ongoing community work.\n\n## <a name=\"license\"></a>License\n\nThe code in this repository is licensed under the [Apache Software License 2](LICENSE).\n\n\n",
"bugtrack_url": null,
"license": "https://www.apache.org/licenses/LICENSE-2.0",
"summary": "Python SDK for Apache Flink Stateful functions",
"version": "3.3.0",
"project_urls": {
"Homepage": "https://github.com/apache/flink-statefun"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5df615731ed367d7ca4bbf346d3124450608a0590abcf0a30f86b56bef3c179e",
"md5": "182173983325f2e1322418750174c2c5",
"sha256": "9b572e23672708b5212f5d139a457a2c112c62ae1d643bd363094d9bd168bc4f"
},
"downloads": -1,
"filename": "apache_flink_statefun-3.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "182173983325f2e1322418750174c2c5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 30108,
"upload_time": "2023-09-19T07:58:07",
"upload_time_iso_8601": "2023-09-19T07:58:07.591920Z",
"url": "https://files.pythonhosted.org/packages/5d/f6/15731ed367d7ca4bbf346d3124450608a0590abcf0a30f86b56bef3c179e/apache_flink_statefun-3.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2841f52192c1d6303682f3076b443842fa94504ab13835c3328d46e85c71a733",
"md5": "36268ca854fd562eb830df20926e6b58",
"sha256": "b5ec271f476e86eb6cdb6b7d4013aaa022606ad27134bfebe228c49156c7da14"
},
"downloads": -1,
"filename": "apache-flink-statefun-3.3.0.tar.gz",
"has_sig": false,
"md5_digest": "36268ca854fd562eb830df20926e6b58",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19903,
"upload_time": "2023-09-19T07:58:09",
"upload_time_iso_8601": "2023-09-19T07:58:09.376300Z",
"url": "https://files.pythonhosted.org/packages/28/41/f52192c1d6303682f3076b443842fa94504ab13835c3328d46e85c71a733/apache-flink-statefun-3.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-19 07:58:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "apache",
"github_project": "flink-statefun",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "apache-flink-statefun"
}
JSON
