# os-aio-pod
[](https://www.travis-ci.org/cfhamlet/os-aio-pod)
[](https://codecov.io/gh/cfhamlet/os-aio-pod)
[](https://pypi.python.org/pypi/os-aio-pod)
[](https://pypi.python.org/pypi/os-aio-pod)
A container of AIO components.
This project is a framework for combining multiple AIO components into one. For example, you can easily extend your TCP server with a HTTP server to offer HTTP API. Usage is simple, write regular coroutine and config file, start with the command line tool, the framework will take care of the work loop.
Each of the coroutine is a magic bean, this framework is a magic pod.
## Conception
Custom coroutine is packed as a ``asyncio.Task``, we call it: *bean*. Thanks to the Python asyncio, all beans can work together. A runner named *pod* maintains the beans and the whole work loop life cycle.
Each bean has a unique id. label can also be used for identifying one or more beans.
You can access other beans by using a context object with id or label.
Signals can be dispatched to each beans which registered callback function.
## Install
```
pip install os-aio-pod
```
There are some extra packages can be installed for more features.
| subpackage | install command | enables |
| ---------- | -------------------------------------- | ------------------------------------------------------------ |
| uvloop | ``pip install os-aio-pod[uvloop]`` | enable [uvloop](https://github.com/MagicStack/uvloop) |
| uvicorn | ``pip install os-aio-pod[uvicorn]`` | enable [uvicorn](https://github.com/encode/uvicorn) http server adapter |
| aiohttp | ``pip install os-aio-pod[aiohttp]`` | enable [aiohttp](https://github.com/aio-libs/aiohttp) http server adapter |
| aiomonitor | ``pip install os-aio-pod[aiomonitor]`` | enable [aiomonitor](https://github.com/aio-libs/aiomonitor) adapter |
## Usage
### Quick start
1. Write your coroutine function
```
# example.py
import asyncio
async def helloworld(**kwargs):
await asyncio.sleep(1)
print("hello world!", kwargs)
```
2. run with ``os-aio-pod``
```
os-aio-pod run example.helloworld:hi="Ozzy"
```
### APIs
#### Custom coroutine
Actually, there are three types of coroutine code for your choice:
1. Regular coroutine, the ``hello`` object of the following example.
```
import asyncio
async def hello_world(**kwargs):
print('hello world!')
await asyncio.sleep(1)
hello = hello_world()
```
2. Regular coroutine fucntion, the ``hello_world`` function of the above example. Keyword arguments can be set in the config file.
3. A class with ``async def __call__(self)`` method and have context as init arguments:
```
class HelloWorld(object):
def __init__(self, context):
self.context = context
async def __call__(self, **kwargs):
print('hello world!')
await asyncio.sleep(1)
```
#### Context
When you use class type coroutine, you can use the context to communicate with the framework and other beans.
Since v0.1.27, ``pass_context`` decorator can be used for passing context to function as the first argument if it is invoked by the framework. ``lable`` can also be specified as argument ``@pass_context(label="app")``
```
from os_aio_pod.decorators import pass_context
@pass_context
async def hello_world(context, **kwargs):
print(context, kwargs)
```
#### Signals
Thanks to [asyncio_dispatch](https://github.com/lenzenmi/asyncio_dispatch), we easily can register and deliver signals.
Typically, you should only use context APIs to process signals.
The system ``SIGINT``,``SIGTERM`` are caught by the framework to handler shutdown stuff after dispatch to each registered callback.
Other system signals are not supported yet.
### Configure
Config file is a regular Python file, all upper case variables will pass to the frame work which can be accessed later. The reserved key words:
* ``BEANS``: a list of bean config dict, the reserved key words of each bean config are: ``core``, ``label``, other keyword arguments will pass to your function
``core``: string path of your coroutine
``label``: optional, can be used to trace your bean
* ``LOG_LEVEL``: logger level, default ``INFO``
* ``LOOP_TYPE``: default is ``asyncio``, can be ``uvloop`` when you install uvloop
* ``DEBUG``: enable debug mode, default ``False``
* ``STOP_WAIT_TIME``: the wait time when recieve signal(``SIGINT``, ``SIGTERM``). Once timeout, all unfinished bean will be cancelled. Default is ``None``, indicate wait until all beans done
Example:
``config.py``
```
BEANS = [
{
'core' : 'hello_world.HelloWorld',
'label': 'first-bean',
'key1' : 'value1',
}
]
LOG_LEVEL = 'debug'
LOOP_TYPE = 'asyncio'
DEBUG = False
STOP_WAIT_TIME = 10
```
### Command line
``os-aio-pod`` command can be used to start the whole framework, the typical usage:
```
$ os-aio-pod run -c config.py
```
or quick start
```
$ os-aio-pod run [awaitable-func1:k1=v1,k2=v2] [awaitable-func2:k3=v3,k4=v4]
```
The reserved config key words(exclude ``BEANS``) can be set by passing command line options.
```
$ os-aio-pod run --help
```
### Built-In Components
There are some built-in adapters can be used for convenient:
* built-in simple server class ``os_aio_pod.contrib.simple.Server``
It is a scaffold base class for simple server
```
from os_aio_pod.contrib.simple import Server
class YourServer(Server):
# can be async/sync
async def startup(self, **kwargs):
pass
# can be async/sync
async def cleanup(self, **kwargs):
pass
async def run(self, **kwargs):
print(self.config)
# on kill(Ctrl+C)
def on_stop(self, **kwargs):
pass
```
* [ptpython](https://github.com/prompt-toolkit/ptpython), python REPL
```
pip install ptpython contextvars
```
```
BEANS = [
{
'core': 'os_aio_pod.contrib.pypython.TelnetServerAdapter',
}
]
```
you can connect this server with telnet
* [uvicorn](https://github.com/encode/uvicorn), a lightning-fast ASGI server
```
pip install uvicorn
```
```
BEANS = [
{
'core': 'os_aio_pod.contrib.uvicorn.UvicornAdapter',
'app' : 'your.app.object.path'
}
]
```
a context object named ``aio_pod_context`` will attached to the app object
* [aiohttp](https://github.com/aio-libs/aiohttp), a well known aio http server
```
pip install aiohttp
```
```
BEANS = [
{
'core': 'os_aio_pod.contrib.aiohttp.WebAdapter',
'app' : 'your.app.object.path'
}
]
```
a context object named ``aio_pod_context`` will attached to the app object
* [aiomonitor](https://github.com/aio-libs/aiomonitor), adds monitor and python REPL capabilities for asyncio application
```
pip install aiomonitor
```
```
BEANS = [
{
'core': 'os_aio_pod.contrib.aiomonitor.AioMonitorAdapter',
}
]
```
* built-in tcp server
An event driven server can be inherited from ``os_aio_pod.contrib.tcp_server.Server``(default server).
If protocol is configured, low-level networking protocol interface will be used instead of the server's on_connect method. The server instance can be accessed with ``your_protocol.server``
```
BEANS = [
{
'core': 'os_aio_pod.contrib.tcp_server.TCPServerAdapter',
# 'protocol': 'your.asyncio.Protocol.path'
# 'server': 'your.event.driven.server'
}
]
```
* built-in producer-consumer model
One producer and multi-consumers is a common model. You can inherit from ``os_aio_pod.contrib.pcflow.Server``(which is inherit from built-in simple server) and implement ``produce`` and ``consume`` methods to run as this model.
```
import asyncio
from os_aio_pod.contrib.pcflow import Server
class YourProducerConsumerServer(Server):
def startup(self, **kwargs):
self.stopping = False
def on_stop(self, **kwargs):
self.stopping = True
async def produce(self, **kwargs):
while not self.stopping:
await asyncio.sleep(1)
yield 1
async def consume(self, obj, **kwargs):
print(obj)
```
```
BEANS = [
{
'core': 'YourProducerConsumerServer',
'consumer_num': 10,
}
]
```
## Unit Tests
```
tox
```
## License
MIT licensed.
Raw data
{
"_id": null,
"home_page": "https://github.com/cfhamlet/os-aio-pod",
"name": "os-aio-pod",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Ozzy",
"author_email": "cfhamlet@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1f/3d/e1869450afd5bed76280d9ad53145b292351e64887c7828b6f27aa49a3ea/os-aio-pod-0.1.40.tar.gz",
"platform": null,
"description": "# os-aio-pod\n\n[](https://www.travis-ci.org/cfhamlet/os-aio-pod)\n[](https://codecov.io/gh/cfhamlet/os-aio-pod)\n[](https://pypi.python.org/pypi/os-aio-pod)\n[](https://pypi.python.org/pypi/os-aio-pod)\n\n\nA container of AIO components.\n\nThis project is a framework for combining multiple AIO components into one. For example, you can easily extend your TCP server with a HTTP server to offer HTTP API. Usage is simple, write regular coroutine and config file, start with the command line tool, the framework will take care of the work loop.\n\nEach of the coroutine is a magic bean, this framework is a magic pod.\n\n\n\n## Conception\n\nCustom coroutine is packed as a ``asyncio.Task``, we call it: *bean*. Thanks to the Python asyncio, all beans can work together. A runner named *pod* maintains the beans and the whole work loop life cycle.\n\nEach bean has a unique id. label can also be used for identifying one or more beans.\n\nYou can access other beans by using a context object with id or label.\n\nSignals can be dispatched to each beans which registered callback function.\n\n## Install\n\n```\npip install os-aio-pod\n```\n\nThere are some extra packages can be installed for more features.\n\n| subpackage | install command | enables |\n| ---------- | -------------------------------------- | ------------------------------------------------------------ |\n| uvloop | ``pip install os-aio-pod[uvloop]`` | enable [uvloop](https://github.com/MagicStack/uvloop) |\n| uvicorn | ``pip install os-aio-pod[uvicorn]`` | enable [uvicorn](https://github.com/encode/uvicorn) http server adapter |\n| aiohttp | ``pip install os-aio-pod[aiohttp]`` | enable [aiohttp](https://github.com/aio-libs/aiohttp) http server adapter |\n| aiomonitor | ``pip install os-aio-pod[aiomonitor]`` | enable [aiomonitor](https://github.com/aio-libs/aiomonitor) adapter |\n\n\n\n## Usage\n\n### Quick start\n\n1. Write your coroutine function\n\n ```\n # example.py\n import asyncio\n\n async def helloworld(**kwargs):\n await asyncio.sleep(1)\n print(\"hello world!\", kwargs)\n ```\n\n2. run with ``os-aio-pod``\n \n ```\n os-aio-pod run example.helloworld:hi=\"Ozzy\"\n ```\n\n### APIs\n\n#### Custom coroutine\n\nActually, there are three types of coroutine code for your choice:\n\n1. Regular coroutine, the ``hello`` object of the following example.\n\n ```\n import asyncio\n \n async def hello_world(**kwargs):\n print('hello world!')\n await asyncio.sleep(1)\n \n hello = hello_world()\n ```\n\n2. Regular coroutine fucntion, the ``hello_world`` function of the above example. Keyword arguments can be set in the config file.\n3. A class with ``async def __call__(self)`` method and have context as init arguments:\n\n ```\n class HelloWorld(object):\n \n def __init__(self, context):\n self.context = context\n \n async def __call__(self, **kwargs):\n print('hello world!')\n await asyncio.sleep(1)\n ```\n\n#### Context\n\nWhen you use class type coroutine, you can use the context to communicate with the framework and other beans.\n\nSince v0.1.27, ``pass_context`` decorator can be used for passing context to function as the first argument if it is invoked by the framework. ``lable`` can also be specified as argument ``@pass_context(label=\"app\")``\n\n```\nfrom os_aio_pod.decorators import pass_context\n\n@pass_context\nasync def hello_world(context, **kwargs):\n print(context, kwargs)\n```\n\n#### Signals\n\nThanks to [asyncio_dispatch](https://github.com/lenzenmi/asyncio_dispatch), we easily can register and deliver signals.\n\nTypically, you should only use context APIs to process signals.\n\nThe system ``SIGINT``,``SIGTERM`` are caught by the framework to handler shutdown stuff after dispatch to each registered callback.\n\nOther system signals are not supported yet.\n\n### Configure\n\nConfig file is a regular Python file, all upper case variables will pass to the frame work which can be accessed later. The reserved key words:\n\n* ``BEANS``: a list of bean config dict, the reserved key words of each bean config are: ``core``, ``label``, other keyword arguments will pass to your function\n\n ``core``: string path of your coroutine\n\n ``label``: optional, can be used to trace your bean\n\n* ``LOG_LEVEL``: logger level, default ``INFO``\n* ``LOOP_TYPE``: default is ``asyncio``, can be ``uvloop`` when you install uvloop\n* ``DEBUG``: enable debug mode, default ``False``\n* ``STOP_WAIT_TIME``: the wait time when recieve signal(``SIGINT``, ``SIGTERM``). Once timeout, all unfinished bean will be cancelled. Default is ``None``, indicate wait until all beans done\n\n\n\nExample:\n\n``config.py``\n\n```\nBEANS = [\n {\n 'core' : 'hello_world.HelloWorld',\n 'label': 'first-bean',\n 'key1' : 'value1',\n }\n]\n\nLOG_LEVEL = 'debug'\nLOOP_TYPE = 'asyncio'\nDEBUG = False\nSTOP_WAIT_TIME = 10\n```\n\n\n\n### Command line\n\n``os-aio-pod`` command can be used to start the whole framework, the typical usage:\n\n```\n$ os-aio-pod run -c config.py\n```\n\nor quick start\n\n```\n$ os-aio-pod run [awaitable-func1:k1=v1,k2=v2] [awaitable-func2:k3=v3,k4=v4]\n```\n\nThe reserved config key words(exclude ``BEANS``) can be set by passing command line options.\n\n```\n$ os-aio-pod run --help\n```\n\n\n\n### Built-In Components\n\nThere are some built-in adapters can be used for convenient:\n\n\n* built-in simple server class ``os_aio_pod.contrib.simple.Server``\n\n It is a scaffold base class for simple server\n\n ```\n from os_aio_pod.contrib.simple import Server\n\n class YourServer(Server):\n\n # can be async/sync \n async def startup(self, **kwargs):\n pass\n\n # can be async/sync \n async def cleanup(self, **kwargs):\n pass\n\n async def run(self, **kwargs):\n print(self.config)\n\n # on kill(Ctrl+C)\n def on_stop(self, **kwargs):\n pass\n ```\n\n* [ptpython](https://github.com/prompt-toolkit/ptpython), python REPL\n\n\n ```\n pip install ptpython contextvars\n ```\n\n ```\n BEANS = [\n {\n 'core': 'os_aio_pod.contrib.pypython.TelnetServerAdapter',\n }\n ]\n ```\n you can connect this server with telnet\n\n* [uvicorn](https://github.com/encode/uvicorn), a lightning-fast ASGI server\n\n ```\n pip install uvicorn\n ```\n\n ```\n BEANS = [\n {\n 'core': 'os_aio_pod.contrib.uvicorn.UvicornAdapter',\n 'app' : 'your.app.object.path'\n }\n ]\n ```\n\n a context object named ``aio_pod_context`` will attached to the app object\n\n* [aiohttp](https://github.com/aio-libs/aiohttp), a well known aio http server\n\n ```\n pip install aiohttp\n ```\n\n ```\n BEANS = [\n {\n 'core': 'os_aio_pod.contrib.aiohttp.WebAdapter',\n 'app' : 'your.app.object.path'\n }\n ]\n ```\n\n a context object named ``aio_pod_context`` will attached to the app object\n\n* [aiomonitor](https://github.com/aio-libs/aiomonitor), adds monitor and python REPL capabilities for asyncio application\n ```\n pip install aiomonitor\n ```\n\n ```\n BEANS = [\n {\n 'core': 'os_aio_pod.contrib.aiomonitor.AioMonitorAdapter',\n }\n ]\n ```\n\n* built-in tcp server\n\n An event driven server can be inherited from ``os_aio_pod.contrib.tcp_server.Server``(default server).\n \n If protocol is configured, low-level networking protocol interface will be used instead of the server's on_connect method. The server instance can be accessed with ``your_protocol.server``\n\n ```\n BEANS = [\n {\n 'core': 'os_aio_pod.contrib.tcp_server.TCPServerAdapter',\n # 'protocol': 'your.asyncio.Protocol.path'\n # 'server': 'your.event.driven.server'\n }\n ]\n ```\n\n* built-in producer-consumer model\n\n One producer and multi-consumers is a common model. You can inherit from ``os_aio_pod.contrib.pcflow.Server``(which is inherit from built-in simple server) and implement ``produce`` and ``consume`` methods to run as this model.\n\n ```\n import asyncio\n\n from os_aio_pod.contrib.pcflow import Server\n\n\n class YourProducerConsumerServer(Server):\n def startup(self, **kwargs):\n self.stopping = False\n\n def on_stop(self, **kwargs):\n self.stopping = True\n\n async def produce(self, **kwargs):\n while not self.stopping:\n await asyncio.sleep(1)\n yield 1\n\n async def consume(self, obj, **kwargs):\n print(obj) \n ```\n\n\n ```\n BEANS = [\n {\n 'core': 'YourProducerConsumerServer',\n 'consumer_num': 10,\n }\n ]\n ```\n\n## Unit Tests\n\n```\ntox\n```\n\n## License\n\nMIT licensed.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A container of aio components.",
"version": "0.1.40",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d9cec89e3614b69da20c699a269357d3efd722643c24faa776fa83c560045d9b",
"md5": "1733718b205a5aa4ace0d221d0aed81d",
"sha256": "4803fc34e0c2c63d515ca116bf68ba748797807ab65a94ffc6551178a435bb99"
},
"downloads": -1,
"filename": "os_aio_pod-0.1.40-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1733718b205a5aa4ace0d221d0aed81d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 22598,
"upload_time": "2023-02-11T16:39:23",
"upload_time_iso_8601": "2023-02-11T16:39:23.608610Z",
"url": "https://files.pythonhosted.org/packages/d9/ce/c89e3614b69da20c699a269357d3efd722643c24faa776fa83c560045d9b/os_aio_pod-0.1.40-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1f3de1869450afd5bed76280d9ad53145b292351e64887c7828b6f27aa49a3ea",
"md5": "1f9418c2a3cc82c6fc7b12cd17871d35",
"sha256": "2889907841460745d5ebaff6b8cf88175dc802a376ed5709849e829c32664d6c"
},
"downloads": -1,
"filename": "os-aio-pod-0.1.40.tar.gz",
"has_sig": false,
"md5_digest": "1f9418c2a3cc82c6fc7b12cd17871d35",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 20668,
"upload_time": "2023-02-11T16:39:26",
"upload_time_iso_8601": "2023-02-11T16:39:26.187354Z",
"url": "https://files.pythonhosted.org/packages/1f/3d/e1869450afd5bed76280d9ad53145b292351e64887c7828b6f27aa49a3ea/os-aio-pod-0.1.40.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-11 16:39:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "cfhamlet",
"github_project": "os-aio-pod",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"tox": true,
"lcname": "os-aio-pod"
}
JSON
