Add plugin API reference

This commit is contained in:
s3lph 2019-11-30 04:39:33 +01:00
parent 6a84976d84
commit f6ad53555c

131
README.md
View file

@ -106,7 +106,7 @@ the space as open depending on its existence.
@plugins.template_function @plugins.template_function
def space_state(): def space_state():
# Get the plugin config dict # Get the plugin config dict
conf = config.get_plugin_config(filestate') conf = config.get_plugin_config('filestate')
# Get the filename # Get the filename
filename = conf.get('filename', '/var/space_state') filename = conf.get('filename', '/var/space_state')
try: try:
@ -185,6 +185,135 @@ curl http://localhost:8000/
You should be greeted with the SpaceAPI endpoint response. You should be greeted with the SpaceAPI endpoint response.
## Plugin API Reference
### Configuration
The following functions provide access to values defined in the
configuration file.
#### `spaceapi_server.config.get_plugin_config(name: str)`
This function returns a plugin's configuration.
The function takes one argument, the name of the plugin. This name is
used to look up the plugin configuration.
The function returns the content present at the key `.plugins.<name>`
of the global configuration file, or an empty object if absent.
Usage:
```python
from spaceapi_server import config
print(config.get_plugin_config('my_plugin'))
```
### Templating
The following decorators register a function in the Jinja2
environment, so they become usable from within templates. They are
invoked when the template is rendered, which happens for each HTTP
request.
If performance is an issue, consider applying caching, either in your
plugins, or by using a caching HTTP reverse proxy.
#### `spaceapi_server.plugins.template_function`
This decorator registers a function as a **global function** in the
Jinja2 environment.
The decorated function may take any arguments that can be represented
in a Jinja2 template.
The decorated function may return any value that can be serialized
into JSON. This includes objects and arrays.
Usage:
```python
from spaceapi_server import plugins
@plugins.template_function
def lookup_sensor(query, default=None):
# Do something with the query
result = ...
# If the loo
if not result:
return default or []
```
```json
{
# ...
"state": "{{ lookup_sensor('SELECT timestamp, value FROM people_now_present LIMIT 1') }}"
# ...
}
```
#### `spaceapi_server.plugins.template_filter`
This decorator registers a function as a **filter** in the Jinja2
environment. The decorated function must take at least one argument.
The decorated function may take any arguments that can be represented
in a Jinja2 template.
The decorated function may return any value that can be serialized
into JSON. This includes objects and arrays.
Usage:
```python
from spaceapi_server import plugins
@plugins.template_filter
def lookup_sensor(query, default=None):
# Do something with the query
result = ...
# If the loo
if not result:
return default or []
```
```json
{
# ...
"state": "{{ 'SELECT timestamp, value FROM people_now_present LIMIT 1' | lookup_sensor }}"
# ...
}
```
#### `spaceapi_server.plugins.template_test`
This decorator registers a function as a **test** in the Jinja2
environment. The decorated function must take exactly one argument.
The decorated function may take any argument that can be represented
in a Jinja2 template.
The decorated function must return either `True` or `False`.
Usage:
```python
from spaceapi_server import plugins
@plugins.template_test
def easteregg(expr):
return expr == 23
```
```json
{
# ...
message": "{% if people_present() is easteregg -%} Nobody expects the Spanish Iniqusition! {%- endif %}"
# ...
}
```
[master]: https://gitlab.com/s3lph/spaceapi-server/commits/master [master]: https://gitlab.com/s3lph/spaceapi-server/commits/master
[releases]: https://gitlab.com/s3lph/spaceapi-server/-/releases [releases]: https://gitlab.com/s3lph/spaceapi-server/-/releases
[spaceapi]: https://spaceapi.io/ [spaceapi]: https://spaceapi.io/