https://github.com/d-k-bo/python-gotify
Python library to access your gotify server
https://github.com/d-k-bo/python-gotify
api-client async asyncio gotify httpx push-notifications python self-hosted websockets
Last synced: 5 days ago
JSON representation
Python library to access your gotify server
- Host: GitHub
- URL: https://github.com/d-k-bo/python-gotify
- Owner: d-k-bo
- License: mit
- Created: 2021-05-27T22:03:38.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-07-22T03:24:31.000Z (over 1 year ago)
- Last Synced: 2026-01-13T03:41:17.457Z (about 1 month ago)
- Topics: api-client, async, asyncio, gotify, httpx, push-notifications, python, self-hosted, websockets
- Language: Python
- Homepage: https://pypi.org/project/gotify/
- Size: 85 KB
- Stars: 30
- Watchers: 2
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# python-gotify
[](https://pypi.python.org/pypi/gotify)
[](https://pypi.python.org/pypi/gotify)
[](https://pypi.python.org/pypi/gotify)
[](https://github.com/psf/black)
[](https://app.codecov.io/gh/d-k-bo/python-gotify)
python-gotify is a python client library to interact with your [gotify](https://github.com/gotify/server) server without having to handle requests manually.
It offers both a synchronous and an asynchronous interface powered by [httpx](https://www.python-httpx.org/).
Optionally, push messages can be received via websockets.
## Installation
python-gotify can be installed from [PyPi](https://pypi.org/project/gotify/) using pip:
```
pip install gotify
```
If you want to listen to push messages, the additional dependency on [websockets](https://websockets.readthedocs.io/en/stable/) can be installed with
```
pip install gotify[stream]
```
## Usage
To send messages:
```python
from gotify import Gotify
gotify = Gotify(
base_url="https://gotify.example.com",
app_token="AsWIJhvlHb.xgKe",
)
gotify.create_message(
"Hello you wonderful people!",
title="Hello World",
priority=0,
)
```
**Note:** To send messages you need to create a new application and set `app_token` accordingly.
You can also manage things like applications:
```python
from gotify import Gotify
gotify = Gotify(
base_url="https://gotify.example.com",
client_token="CoLwHBCAr8z2MMA",
)
app = gotify.create_application("foobar", description="test application")
print("Created new application:", app)
```
would result in
```plain
Created new application: {'id': 42, 'token': 'ArHD_yGYf63-A13', 'name': 'foobar', 'description': 'test application', 'internal': False, 'image': 'static/defaultapp.png'}
```
**Note:** For most things you need to create a new client and set `client_token` accordingly.
This library tries to implement every endpoint of the gotify API as an instance method of the `Gotify` class.
More details about the capabilities of gotify's API can be found in its [API documentation](https://gotify.net/api-docs).
**Note:** since I don't use any gotify plugins, plugin-related functions are currently completely untested.
### Async Usage
python-gotify's asynchronous client works similar to the synchronous one, you just need to `await` all methods. It is recommended to use it as a context manager if you want to send multiple requests.
```python
import asyncio
from gotify import AsyncGotify
async def send_message_async():
async_gotify = AsyncGotify(
base_url="https://gotify.example.com",
app_token="AsWIJhvlHb.xgKe",
)
await async_gotify.create_message(
"This message was sent asynchronously!",
title="Hello Asynchronous World",
)
asyncio.run(send_message_async())
```
### Reusing HTTP sessions
If you want to send multiple requests to a server you can use both `Gotify` and `AsyncGotify` as a (asynchronous) context manager which will use a single HTTP session to reduce some connection overhead.
```python
with Gotify(...) as gotify:
...
async with AsyncGotify(...) as async_gotify:
...
```
### Receive push messages via websockets
`AsyncGotify` implements gotify's `/stream` endpoint which allows to receive push messages via websockets. To use it make sure you installed python-gotify with `pip install gotify[stream]`.
`AsyncGotify.stream()` is implemented as an asynchronous generator that waits for incoming messages and yields `Message` dictionaries.
```python
import asyncio
from gotify import AsyncGotify
async def log_push_messages():
async_gotify = AsyncGotify(
base_url="https://gotify.example.com",
client_token="CoLwHBCAr8z2MMA",
)
async for msg in async_gotify.stream():
print(msg)
asyncio.run(log_push_messages())
```
## Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please use [nox](https://nox.thea.codes/en/stable/tutorial.html#installation) to format, lint, type-check and test your code by calling `nox` in your project directory.
The test suite downloads a server binary and starts a preconfigured test server on port 30080 (this doesn't work on MacOS). If you encounter issues starting the test server, please create an issue.
## License
This project is licensed under the MIT License.
See [LICENSE](LICENSE) for more information.