craftbeerpi4-pione/docs/_sources/standards.rst.txt
2019-01-05 23:27:29 +01:00

114 lines
No EOL
3.1 KiB
ReStructuredText

Standard & Guidelines
=====================
Python
^^^^^^
CraftBeerPi 4.x is based on Pyhton 3.7x.
As a main framework CraftBeerPi is based on `aiohttp`
* aioHTTP https://aiohttp.readthedocs.io/en/stable/
CBPiEventBus
--------
One core concept of CraftBeerPi 4.x is the CBPiEventBus.
It should be avoided to call method on a controller directly. Events should be fired and listener methods should be used.
This makes sure that all components are loosely coupled. New plugins can listen on events and extend or change the functionality easily.
Here an example how to fire an event
.. code-block:: python
cbpi.bus.fire(topic="notification/hello", key="hello", message="Hello World")
Here an example how listen on an event.
.. code-block:: python
@on_event(topic="actor/+/switch/on")
def listener(self, id , power=100, **kwargs) -> None:
pass
.. note::
It's imporante to add **kwargs as parameter to the listening method. This makes sure that maybe addtional event paramenter are not causing an exception.
A list of all registered events listeners can be found under: `http://<IP_ADDRESS>:<PORT>/system/events`
HTTP Endpoints
--------------
A new HTTP endpoints should be exposed by adding the `@request_mapping` decorator on top of an async method.
The `path` parameter defines the URL path. The `auth_required` defines whether the endpoint should be accessible public or within a user session only.
Typically you perform just some basing parameter validation and fire an event so that other components and controllers can perform some actions.
.. code-block:: python
@request_mapping(path="/{id:\d+}/on", auth_required=False)
async def http_on(self, request) -> web.Response:
self.cbpi.bus.fire(topic="actor/%s/switch/on" % id, id=id, power=99)
return web.Response(status=204)
.. note::
The Events are process in an async way. Results will be pushed to the client via CBPiWebSocket Event.
CBPiWebSocket
---------
The CBPiWebSocket is listening on `http://<IP_ADDRESS>:<PORT>/ws`
All events are forwarded to all connected web socket clients.
The CBPiWebSocket Event is having the following structure.
* topic -> is the bus topic
* data -> the event data
.. code-block:: json
{
"topic":"notification/step",
"data":{
"key":"step",
"message":"Hello World",
"type":"info"
}
}
SQL Files
---------
Currently only one SQL file for database initialisation is available.
It's located under: `./core/sql`
Web User Interface
^^^^^^^^^^^^^^^^^^
The Web UI is based on ReactJS + Redux.
The build process is based on webpack and bable.
* ReactJS: https://reactjs.org/
* Redux: https://redux.js.org/
* WebPack: https://webpack.js.org/
* Babel: https://babeljs.io
REST API
^^^^^^^^
The REST API of CraftBeerPi is documented using Swagger.io
After server startup you can find the API documentaiton under: `http://<IP_ADDRESS>:<PORT>/api/doc`
To generate the swagger file `aiohttp-swagger` is used. for more information see: https://aiohttp-swagger.readthedocs.io/en/latest/
Custom Extensions & Pluins
^^^^^^^^^^^^^^^^^^^^^^^^^^
Custom Extension should be placed under `./core/extensions`