# Automata
<!-- TABLE OF CONTENTS -->
<details>
<summary>Table of Contents</summary>
<ol>
<li><a href="#introduction">Introduction</a></li>
<li>
<a href="#getting-started">Getting Started</a>
<ul>
<li><a href="#prerequisites">Prerequisites</a></li>
<li><a href="#installation-and-setup">Installation and Setup</a></li>
</ul>
</li>
<li><a href="#states-events-state-changes-data-events-and-payloads">States, Events, State Changes, Data Events, and Payloads</a></li>
<li><a href="#advanced">Advanced</a></li>
<li><a href="#license">License</a></li>
</ol>
</details>
## Introduction
Automata is a lightweight framework that allows users to define a state machine based websocket server. Each machine has a collection of states, for example, a traffic light state machine has Green, Yellow, and Red states. Each state can have any number of events, these events can be defined by the developer to do whatever they want. They can return data back to the client, transition to a new state, process data, or even do nothing; that is all up the the desired implementation. Overall, the goal of Automata is to provide a unified methodology and doctrine for defining and improving the clarity of websocket communication.
## Getting Started
This is a simple example of how you to set up your Automata instance and run your application.
### Prerequisites
* `python version >= 3.7`
### Installation and Setup
1. Install with `pip install automata-ws`
2. Initialize your Automata (we use app.py)
```python3
from automata import Automata
my_machine = Automata(
name="myMachine"
)
```
3. Create your states and any events (in any directory you want)
```python3
from automata import State, EventStatus, transition, transmit
red_light = State('red_light')
@red_light.event('change_to_green')
async def handler(automata, data):
#do something here...
run_some_func()
await transition(automata, 'green', EventStatus.OK) #will change the state of our machine and will report this to the client
green_state = State(
name="green",
targets=["yellow"]
)
@green_light.event('change_to_yellow')
async def handler(automata, data):
await transmit(automata, EventStatus.OK, some_data) #will send back data without changing state
#and so on and so on...
```
4. Register states in your machine (back in the file you defined the machine)
```python3
my_machine.register_state(red_light) #the first state that is registered will be the initial state for new sessions
my_machine.register_state(green_light)
```
5. Run the machine
```python3
my_machine.run('localhost', 8000)
```
## States, Events, State Changes, Data Events, and Payloads
### 1. States
- Every state must be unique: there cannot exist two states with the same name
- A state may have a list of target states: all of the states in which a transition from the referenced state is possible
- Trying to transition to a state that is not in the target list for the referenced state will raise an exception
- An undefined target list means that a transition to any state is allowed
###
```python3
green_state = State(
name="green",
targets=["yellow"] #the target list with all the states that the green_state can transition to
)
```
- The initial state is the one that is registered first in the `Automata` instance
### 2. Events
- Events defined for a specific state must be unique
- All events are identified by their name and defined by their handler
- Each handler will recieve an `Automata` instance and a `data` instance (either as a `dict` or a `str`)
###
```python3
@green_state.event('change_to_yellow') #this annotation will create an event for the corresponding state (green_state in this case)
async def handler(automata: Automata, data):
run_some_code()
do_whatever_you_want()
await transition(automata, 'yellow', EventStatus.OK)
@green_state.event('ping')
def handler(automata: Automata, data): #the handler doesn't necessarily have to be async
print('pong')
```
### 3. State Changes
- Each state transition has to be relayed to the client: they will receive data about their new state and all events they can call
- Each state transition has to be accompanied with a status code: these are similar to the 100, 200, 300, 400, 500 status codes defined in HTTP and are found in the `EventStatus` enum
- A state transition may have data associated with it if needed (data is optional)
- A state transition is achieved through the `transition` function
###
- ```python3
await transition(automata, 'logged_in', EventStatus.OK, some_data) #a state transition with some data
```
### 4. Data Events
- It is possible to send data back to the client without changing state: this is achieved through the `transmit` function
- Each data event must be accompanied with a status code (as mentioned above)
###
- ```python3
await transmit(automata, EventStatus.OK, some_data) #a data event with no state transition
```
### 5. Payloads
- All client to server payloads must follow the format below
###
- ```json
{
"event" : "event_name",
"data" : data
}
```
- A state change will be relayed to the client in the following format (occurs when `transition` is called)
###
- ```json
{
"state" : "new_state",
"events" : [
"event1",
"event2", //Any number of possible events associated with the new state
],
"status" : 200,
"data": "some_data" //optional: can be None/Null
}
```
- Any generic data event will be returned back in the following format (occurs when `transmit` is called)
###
- ```json
{
"status" : 200,
"data": "some_data" //optional
}
```
## Advanced
### 1. Custom HTTP Endpoint(s)
- As of now all websocket connections are served on `/`
- It is possible to implement a custom endpoint using the `automata.endpoint('/endpoint')` annotation
- This is useful if a health check (or something generic) is needed
###
- ```python3
@my_machine.endpoint('/health')
async def some_handler(request_headers):
return 'OK'
```
- **Note**: only `get` requests can be handled
## License
Apache License 2.0
Raw data
{
"_id": null,
"home_page": "",
"name": "automata-ws",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "automata,websocket,server,state machine,event",
"author": "Erik Lungulescu",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/ce/6b/40ab37e14ecfc82e32595d7ec14be0ab22f833498e14a719be89a49df330/automata-ws-0.1.1.tar.gz",
"platform": null,
"description": "# Automata \r\n\r\n\r\n<!-- TABLE OF CONTENTS -->\r\n<details>\r\n <summary>Table of Contents</summary>\r\n <ol>\r\n <li><a href=\"#introduction\">Introduction</a></li>\r\n <li>\r\n <a href=\"#getting-started\">Getting Started</a>\r\n <ul>\r\n <li><a href=\"#prerequisites\">Prerequisites</a></li>\r\n <li><a href=\"#installation-and-setup\">Installation and Setup</a></li>\r\n </ul>\r\n </li>\r\n <li><a href=\"#states-events-state-changes-data-events-and-payloads\">States, Events, State Changes, Data Events, and Payloads</a></li>\r\n <li><a href=\"#advanced\">Advanced</a></li>\r\n <li><a href=\"#license\">License</a></li>\r\n </ol>\r\n</details>\r\n\r\n## Introduction\r\n\r\nAutomata is a lightweight framework that allows users to define a state machine based websocket server. Each machine has a collection of states, for example, a traffic light state machine has Green, Yellow, and Red states. Each state can have any number of events, these events can be defined by the developer to do whatever they want. They can return data back to the client, transition to a new state, process data, or even do nothing; that is all up the the desired implementation. Overall, the goal of Automata is to provide a unified methodology and doctrine for defining and improving the clarity of websocket communication.\r\n\r\n## Getting Started\r\n\r\nThis is a simple example of how you to set up your Automata instance and run your application.\r\n\r\n### Prerequisites\r\n* `python version >= 3.7`\r\n\r\n### Installation and Setup\r\n\r\n1. Install with `pip install automata-ws`\r\n\r\n2. Initialize your Automata (we use app.py)\r\n ```python3\r\n from automata import Automata\r\n \r\n my_machine = Automata(\r\n name=\"myMachine\"\r\n )\r\n ```\r\n\r\n3. Create your states and any events (in any directory you want)\r\n ```python3\r\n from automata import State, EventStatus, transition, transmit\r\n \r\n red_light = State('red_light')\r\n \r\n @red_light.event('change_to_green')\r\n async def handler(automata, data):\r\n #do something here...\r\n run_some_func()\r\n await transition(automata, 'green', EventStatus.OK) #will change the state of our machine and will report this to the client\r\n \r\n green_state = State(\r\n name=\"green\",\r\n targets=[\"yellow\"]\r\n )\r\n \r\n @green_light.event('change_to_yellow')\r\n async def handler(automata, data):\r\n await transmit(automata, EventStatus.OK, some_data) #will send back data without changing state\r\n \r\n #and so on and so on...\r\n ```\r\n\r\n4. Register states in your machine (back in the file you defined the machine)\r\n ```python3\r\n my_machine.register_state(red_light) #the first state that is registered will be the initial state for new sessions\r\n my_machine.register_state(green_light)\r\n ```\r\n\r\n5. Run the machine\r\n ```python3\r\n my_machine.run('localhost', 8000)\r\n ```\r\n\r\n## States, Events, State Changes, Data Events, and Payloads \r\n\r\n### 1. States\r\n - Every state must be unique: there cannot exist two states with the same name\r\n - A state may have a list of target states: all of the states in which a transition from the referenced state is possible\r\n - Trying to transition to a state that is not in the target list for the referenced state will raise an exception\r\n - An undefined target list means that a transition to any state is allowed \r\n ###\r\n \r\n ```python3\r\n green_state = State(\r\n name=\"green\",\r\n targets=[\"yellow\"] #the target list with all the states that the green_state can transition to\r\n )\r\n ```\r\n - The initial state is the one that is registered first in the `Automata` instance\r\n\r\n### 2. Events\r\n - Events defined for a specific state must be unique\r\n - All events are identified by their name and defined by their handler\r\n - Each handler will recieve an `Automata` instance and a `data` instance (either as a `dict` or a `str`)\r\n ###\r\n \r\n ```python3\r\n @green_state.event('change_to_yellow') #this annotation will create an event for the corresponding state (green_state in this case)\r\n async def handler(automata: Automata, data):\r\n run_some_code()\r\n do_whatever_you_want()\r\n await transition(automata, 'yellow', EventStatus.OK)\r\n \r\n @green_state.event('ping')\r\n def handler(automata: Automata, data): #the handler doesn't necessarily have to be async\r\n print('pong')\r\n \r\n ```\r\n\r\n### 3. State Changes\r\n - Each state transition has to be relayed to the client: they will receive data about their new state and all events they can call\r\n - Each state transition has to be accompanied with a status code: these are similar to the 100, 200, 300, 400, 500 status codes defined in HTTP and are found in the `EventStatus` enum\r\n - A state transition may have data associated with it if needed (data is optional)\r\n - A state transition is achieved through the `transition` function\r\n ###\r\n - ```python3\r\n await transition(automata, 'logged_in', EventStatus.OK, some_data) #a state transition with some data\r\n ```\r\n\r\n### 4. Data Events\r\n - It is possible to send data back to the client without changing state: this is achieved through the `transmit` function\r\n - Each data event must be accompanied with a status code (as mentioned above)\r\n ###\r\n - ```python3\r\n await transmit(automata, EventStatus.OK, some_data) #a data event with no state transition\r\n ```\r\n\r\n### 5. Payloads\r\n - All client to server payloads must follow the format below\r\n ###\r\n - ```json\r\n {\r\n \"event\" : \"event_name\",\r\n \"data\" : data\r\n }\r\n ```\r\n - A state change will be relayed to the client in the following format (occurs when `transition` is called)\r\n ###\r\n - ```json\r\n {\r\n \"state\" : \"new_state\",\r\n \"events\" : [\r\n \"event1\",\r\n \"event2\", //Any number of possible events associated with the new state\r\n ],\r\n \"status\" : 200,\r\n \"data\": \"some_data\" //optional: can be None/Null\r\n }\r\n ```\r\n - Any generic data event will be returned back in the following format (occurs when `transmit` is called)\r\n ###\r\n - ```json\r\n {\r\n \"status\" : 200,\r\n \"data\": \"some_data\" //optional\r\n }\r\n ```\r\n\r\n## Advanced\r\n\r\n### 1. Custom HTTP Endpoint(s)\r\n - As of now all websocket connections are served on `/`\r\n - It is possible to implement a custom endpoint using the `automata.endpoint('/endpoint')` annotation\r\n - This is useful if a health check (or something generic) is needed\r\n ###\r\n - ```python3\r\n @my_machine.endpoint('/health')\r\n async def some_handler(request_headers):\r\n return 'OK'\r\n ```\r\n - **Note**: only `get` requests can be handled \r\n \r\n## License \r\n\r\nApache License 2.0\r\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Automata is a lightweight framework that allows users to define a state machine based websocket server.",
"version": "0.1.1",
"split_keywords": [
"automata",
"websocket",
"server",
"state machine",
"event"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ca70cc833ec09695c1c3ce7f0591e9deac62756b935c9715302c19e8d8d91261",
"md5": "192a3c0b20b200e6b50645c5adb0e7f9",
"sha256": "6580eb5dbf17182d79be1ea687a93c660a31493869bfece51fbc7106e67077e0"
},
"downloads": -1,
"filename": "automata_ws-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "192a3c0b20b200e6b50645c5adb0e7f9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 8222,
"upload_time": "2023-01-08T06:04:49",
"upload_time_iso_8601": "2023-01-08T06:04:49.806294Z",
"url": "https://files.pythonhosted.org/packages/ca/70/cc833ec09695c1c3ce7f0591e9deac62756b935c9715302c19e8d8d91261/automata_ws-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ce6b40ab37e14ecfc82e32595d7ec14be0ab22f833498e14a719be89a49df330",
"md5": "5d11837dd8e970ee2f074587245d60c8",
"sha256": "85614a00f1a482d0a7f54e17b26fc70caf935c4e17f40bd12c5d3d812ee4fc7c"
},
"downloads": -1,
"filename": "automata-ws-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "5d11837dd8e970ee2f074587245d60c8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 10943,
"upload_time": "2023-01-08T06:04:51",
"upload_time_iso_8601": "2023-01-08T06:04:51.156656Z",
"url": "https://files.pythonhosted.org/packages/ce/6b/40ab37e14ecfc82e32595d7ec14be0ab22f833498e14a719be89a49df330/automata-ws-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-08 06:04:51",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "automata-ws"
}
JSON