documentation
This commit is contained in:
Andrea Spacca
parent
4af5825bff
commit
63035eea8d
140
README.md
140
README.md
|
|
@ -464,6 +464,77 @@ SVG files are printed as text currently, avoid printing them.
|
|||
|
||||
This module is disabled by default.
|
||||
|
||||
### Giphy
|
||||
|
||||
Can be used to post a picture from giphy given a query string.
|
||||
|
||||
API Key:
|
||||
|
||||
The module has no API Key set up by defualt. You have to provide an api key by setting the environment variable `GIPHY_API_KEY`.
|
||||
|
||||
Read the documentation to create one at https://developers.giphy.com/docs/api
|
||||
|
||||
Environ variables seen by commands:
|
||||
|
||||
* GIPHY_API_KEY: API Key for Giphy access
|
||||
|
||||
Commands:
|
||||
|
||||
* !giphy "query" - Post the first image result from giphy for the given "query"
|
||||
|
||||
Example:
|
||||
|
||||
* !giphy test
|
||||
|
||||
### Gfycat
|
||||
|
||||
Can be used to post a picture from Gfycat given a query string.
|
||||
|
||||
Commands:
|
||||
|
||||
* !gfycat "query" - Post the first image result from gfycat for the given "query"
|
||||
|
||||
Example:
|
||||
|
||||
* !gfycat test
|
||||
|
||||
### Tautulli
|
||||
|
||||
Can be used to fetch recently added information from Tautulli or receive Tautulli recently added notification webhook
|
||||
|
||||
Commands:
|
||||
|
||||
* !tautulli movie - Show the last 10 recently added movies to Plex library monitered by Tautulli
|
||||
* !tautulli show - Show the last 10 recently added tv series epsiodes to Plex library monitered by Tautulli
|
||||
* !tautulli artist - Show the last 10 recently added music artists to Plex library monitered by Tautulli
|
||||
* !tautulli add "room_id" encrypted - Add the provided encrypted "room_id" to the list of rooms to post the recently added notifications received by the webhook
|
||||
* !tautulli add "room_id" plain - Add the provided unencrypted "room_id" to the list of rooms to post the recently added notifications received by the webhook
|
||||
* !tautulli remove "room_id" encrypted - Remove the provided encrypted "room_id" to the list of rooms to post the recently added notifications received by the webhook
|
||||
* !tautulli remove "room_id" plain - Remove the provided unencrypted "room_id" to the list of rooms to post the recently added notifications received by the webhook
|
||||
|
||||
Tautulli instance and API Key:
|
||||
|
||||
The module work with an existing installed instance of Tautulli accessible on the machine at the path defined by env variable `TAUTULLI_PATH`
|
||||
You have to provide an api key by setting the environment variable `TAUTULLI_API_KEY`.
|
||||
|
||||
Read the documentation to create one at https://developers.giphy.com/docs/api
|
||||
|
||||
Environ variables seen by commands:
|
||||
|
||||
* TAUTULLI_PATH: Path accessible from the machine to the installed instance of Tautulli
|
||||
* TAUTULLI_URL: Url accessible from the machine to the installed instance of Tautulli
|
||||
* TAUTULLI_API_KEY: API Key for Tautulli access
|
||||
* TAUTULLI_NOTIFIER_ADDR: Listening address for the Tautulli webhook handler target
|
||||
* TAUTULLI_NOTIFIER_PORT: Listening port for the Tautulli webhook handler target
|
||||
* BOT_OWNERS: Owner of the rooms in the list for the notification webhook
|
||||
|
||||
|
||||
Example:
|
||||
|
||||
* !tautulli movie
|
||||
* !tautulli add !OGEhHVWSdvArJzumhm:matrix.org plain
|
||||
* !tautulli remove !OGEhHVWSdvArJzumhm:matrix.org plain
|
||||
|
||||
### Github based asset management
|
||||
|
||||
This module was written for asset (machines, tasks and todo) management by
|
||||
|
|
@ -632,6 +703,75 @@ class MatrixModule(BotModule):
|
|||
|
||||
You only need to implement the ones you need. See existing bots for examples.
|
||||
|
||||
## Bot API
|
||||
```python
|
||||
class Bot:
|
||||
async def send_msg(self, mxid, roomname, message):
|
||||
"""
|
||||
|
||||
:param mxid: A Matrix user id to send the message to
|
||||
:param roomname: A Matrix room id to send the message to
|
||||
:param message: Text to be sent as message
|
||||
:return bool: Success upon sending the message
|
||||
"""
|
||||
|
||||
async def send_text(self, room, body, msgtype="m.notice", bot_ignore=False):
|
||||
"""
|
||||
|
||||
:param room: A MatrixRoom the text should be send to
|
||||
:param body: Textual content of the message
|
||||
:param msgtype: The message type for the room https://matrix.org/docs/spec/client_server/latest#m-room-message-msgtypes
|
||||
:param bot_ignore: Flag to mark the message to be ignored by the bot
|
||||
:return:
|
||||
"""
|
||||
|
||||
async def send_html(self, room, html, plaintext, msgtype="m.notice", bot_ignore=False):
|
||||
"""
|
||||
|
||||
:param room: A MatrixRoom the html should be send to
|
||||
:param html: Html content of the message
|
||||
:param plaintext: Plaintext content of the message
|
||||
:param msgtype: The message type for the room https://matrix.org/docs/spec/client_server/latest#m-room-message-msgtypes
|
||||
:param bot_ignore: Flag to mark the message to be ignored by the bot
|
||||
:return:
|
||||
"""
|
||||
|
||||
async def send_image(self, room, url, body, mimetype=None, width=None, height=None, size=None):
|
||||
"""
|
||||
|
||||
:param room: A MatrixRoom the image should be send to
|
||||
:param url: A MXC-Uri https://matrix.org/docs/spec/client_server/r0.6.0#mxc-uri
|
||||
:param body: A textual representation of the image
|
||||
:param mimetype: The mimetype of the image
|
||||
:param width: Width in pixel of the image
|
||||
:param height: Height in pixel of the image
|
||||
:param size: Size in bytes of the image
|
||||
:return:
|
||||
"""
|
||||
|
||||
async def upload_image(self, url, blob=False, blob_content_type="image/png"):
|
||||
"""
|
||||
|
||||
:param url: Url of binary content of the image to upload
|
||||
:param blob: Flag to indicate if the first param is an url or a binary content
|
||||
:param blob_content_type: Content type of the image in case of binary content
|
||||
:return: A MXC-Uri https://matrix.org/docs/spec/client_server/r0.6.0#mxc-uri, Content type, Width, Height, Image size in bytes
|
||||
"""
|
||||
|
||||
|
||||
async def upload_and_send_image(self, room, url, text=None, blob=False, blob_content_type="image/png"):
|
||||
"""
|
||||
|
||||
:param room: A MatrixRoom the image should be send to after uploading
|
||||
:param url: Url of binary content of the image to upload
|
||||
:param text: A textual representation of the image
|
||||
:param blob: Flag to indicate if the second param is an url or a binary content
|
||||
:param blob_content_type: Content type of the image in case of binary content
|
||||
:return:
|
||||
"""
|
||||
|
||||
```
|
||||
|
||||
### Logging
|
||||
|
||||
Uses [python logging facility](https://docs.python.org/3/library/logging.html) to print information to the console. Customize it to your needs editing `config/logging.yml`.
|
||||
|
|
|
|||
47
bot.py
47
bot.py
|
|
@ -74,6 +74,15 @@ class Bot:
|
|||
self.logger.debug("Logger initialized")
|
||||
|
||||
async def upload_and_send_image(self, room, url, text=None, blob=False, blob_content_type="image/png"):
|
||||
"""
|
||||
|
||||
:param room: A MatrixRoom the image should be send to after uploading
|
||||
:param url: Url of binary content of the image to upload
|
||||
:param text: A textual representation of the image
|
||||
:param blob: Flag to indicate if the second param is an url or a binary content
|
||||
:param blob_content_type: Content type of the image in case of binary content
|
||||
:return:
|
||||
"""
|
||||
matrix_uri, mimetype, w, h, size = await self.upload_image(url, blob, blob_content_type)
|
||||
|
||||
if not text and not blob:
|
||||
|
|
@ -86,6 +95,14 @@ class Bot:
|
|||
|
||||
# Helper function to upload a image from URL to homeserver. Use send_image() to actually send it to room.
|
||||
async def upload_image(self, url, blob=False, blob_content_type="image/png"):
|
||||
"""
|
||||
|
||||
:param url: Url of binary content of the image to upload
|
||||
:param blob: Flag to indicate if the first param is an url or a binary content
|
||||
:param blob_content_type: Content type of the image in case of binary content
|
||||
:return: A MXC-Uri https://matrix.org/docs/spec/client_server/r0.6.0#mxc-uri, Content type, Width, Height, Image size in bytes
|
||||
"""
|
||||
|
||||
self.client: AsyncClient
|
||||
response: UploadResponse
|
||||
if blob:
|
||||
|
|
@ -121,6 +138,15 @@ class Bot:
|
|||
return None, None, None, None
|
||||
|
||||
async def send_text(self, room, body, msgtype="m.notice", bot_ignore=False):
|
||||
"""
|
||||
|
||||
:param room: A MatrixRoom the text should be send to
|
||||
:param body: Textual content of the message
|
||||
:param msgtype: The message type for the room https://matrix.org/docs/spec/client_server/latest#m-room-message-msgtypes
|
||||
:param bot_ignore: Flag to mark the message to be ignored by the bot
|
||||
:return:
|
||||
"""
|
||||
|
||||
msg = {
|
||||
"body": body,
|
||||
"msgtype": msgtype,
|
||||
|
|
@ -131,6 +157,16 @@ class Bot:
|
|||
await self.client.room_send(room.room_id, 'm.room.message', msg)
|
||||
|
||||
async def send_html(self, room, html, plaintext, msgtype="m.notice", bot_ignore=False):
|
||||
"""
|
||||
|
||||
:param room: A MatrixRoom the html should be send to
|
||||
:param html: Html content of the message
|
||||
:param plaintext: Plaintext content of the message
|
||||
:param msgtype: The message type for the room https://matrix.org/docs/spec/client_server/latest#m-room-message-msgtypes
|
||||
:param bot_ignore: Flag to mark the message to be ignored by the bot
|
||||
:return:
|
||||
"""
|
||||
|
||||
msg = {
|
||||
"msgtype": msgtype,
|
||||
"format": "org.matrix.custom.html",
|
||||
|
|
@ -147,6 +183,10 @@ class Bot:
|
|||
:param room: A MatrixRoom the image should be send to
|
||||
:param url: A MXC-Uri https://matrix.org/docs/spec/client_server/r0.6.0#mxc-uri
|
||||
:param body: A textual representation of the image
|
||||
:param mimetype: The mimetype of the image
|
||||
:param width: Width in pixel of the image
|
||||
:param height: Height in pixel of the image
|
||||
:param size: Size in bytes of the image
|
||||
:return:
|
||||
"""
|
||||
msg = {
|
||||
|
|
@ -170,6 +210,13 @@ class Bot:
|
|||
await self.client.room_send(room.room_id, 'm.room.message', msg)
|
||||
|
||||
async def send_msg(self, mxid, roomname, message):
|
||||
"""
|
||||
|
||||
:param mxid: A Matrix user id to send the message to
|
||||
:param roomname: A Matrix room id to send the message to
|
||||
:param message: Text to be sent as message
|
||||
:return bool: Success upon sending the message
|
||||
"""
|
||||
# Sends private message to user. Returns true on success.
|
||||
|
||||
# Find if we already have a common room with user:
|
||||
|
|
|
|||
Loading…
Reference in New Issue