https://github.com/babetoduarte/tootnotify
Python command line tool to send DM notifications to a mastodon user.
https://github.com/babetoduarte/tootnotify
Last synced: 4 months ago
JSON representation
Python command line tool to send DM notifications to a mastodon user.
- Host: GitHub
- URL: https://github.com/babetoduarte/tootnotify
- Owner: babetoduarte
- License: gpl-3.0
- Created: 2023-07-10T20:24:31.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2023-07-17T19:13:12.000Z (almost 3 years ago)
- Last Synced: 2025-07-09T00:21:27.883Z (12 months ago)
- Language: Python
- Size: 1.05 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# TootNotify
This is a python command line utility based on [Mastodon.py](https://github.com/halcy/Mastodon.py) , which is able to send direct messages to a given user on Mastodon:
`foo@bar:~$> tootnotify -r @user@instance -m "Message from TootNotify!"`
I built this tool to **notify myself via a secondary (bot) Mastodon account, when long-running processes and tasks finish**. FIY, **you don't need a second account to use TootNotify**, you can use your own account and DM yourself! Also, I'm sure there can be many more uses for this tool.
>Because of the way Mastodon works, direct messages are just regular *Toots* that mention a single user on the content of its body, and are set to have `private` visibility (only the accounts mentioned can see the *Toot*).
This tool allows to *attach* image, video and audio files to the direct message:
`foo@bar:~$> tootnotify -r @user@instance -m "Message with media" -f image1.png image2.jpg`
Due to mastodon's API specifications, media attached to posts must be of the same type: only images (up to 4 images per *Toot*), only video (a *single* video file __or GIF__), or only audio (a single *audio* file). **The current implementation allows the API to determine the MIME type of each media file by the media's extension**.
Note that these **attachments are done asynchronously** following Mastodon's guidelines, and the *Toot* is not sent until all data is uploaded (confirmed by the API call), which means your notification may take a few seconds to be sent while the attachments are uploaded. __If the upload takes more than the stipulated timeout parameter, the *Toot* is sent without any media__ (better to receive an incomplete notification than no notification at all!).
There are also command line arguments to flag your post as `sensitive content` (which will blur out the media you upload), as well as labeling the direct message with a `spoiler/content warning`, which will force the recipient to read your warning and click `Show More` to see the body and attachments of the message.
## Mastodon API
To use this tool you will need to have a Mastodon API application created, with its corresponding API credentials.
The simplest way to do this, is through the Mastodon web interface: go to Preferences > Development (*i.e.* [mastodon.social/settings/applications](https://mastodon.social/settings/applications))
Once there, click on the `New Application` button. There, give your application a Name, and click the `Submit` button on the bottom of the page. Having created an App on your account, you should be presented with a `Client key`, a `Client secret`, and `Your Access Token`. You'll need to put these strings into a text configuration file called `.tootnotifyrc` located in your `$HOME` directory, as instructed below.
## Installation
This section presents the steps needed to install TootNotify, once the API credentials have been obtained.
### Create `~/.tootnotifyrc` file
TootNotify looks for API credentials stored as variables in the `~/.tootnotifyrc` file within the user's `$HOME` folder. By default, **the `.tootnotifyrc` file is not shipped with the project, which means you need to create it**:
`foo@bar:~$> touch ~/.tootnotifyrc`
Make sure that the content of `~/.tootnotify` corresponds to the following (and be sure to assign values to these variables **without any quotes**!):
``` shell
## FILE: ~/.tootnotifyrc
[tootnotify]
# Instance url (e.g. https://mastodon.social)
api_base_url = YOUR_INSTANCE_URL
# API Client Key
client_id = YOUR CLIENT_ID
# API Client Secret
client_secret = YOUR_CLIENT_SECRET
# API Access Token
access_token = YOU_ACCESS_TOKEN
# Default recipient for the private toots (e.g. @account@mastodon.social)
DEFAULT_RECIPIENT = YOUR_DEFAULT_RECIPIENT
```
Among the variables, a DEFAULT_RECIPIENT can be configured, so that when using TootNotify systematically to notify the same user, the recipient address doesn't have to be provided every time:
`foo@bar:~$> tootnotify -m "Message to the default recipient!"`
### Install from PyPI
Once the `~/.tootnotifyrc` control file is in place, we can use PIP to install TootNotify from PyPI
``` bash
foo@bar:~$> pip install tootnotify
```
### Install from this repository
Once the `~/.tootnotifyrc` control file is in place, we can use PIP to install TootNotify (make sure you navigate to the root of the `TootNotify` project folder):
``` bash
foo@bar:TootNotify$> pip install .
```
We can check whether TootNotify was installed correctly, by invoking it (from anywhere) and passing it the `-h`/`--help` flag:
``` bash
foo@bar:~$> tootnotify -h
```
and if all goes well, we should be presented with the help dialog:
``` bash
usage: tootnotify [-h] [-r <@user@instan.ce>] [-m ] [-s ]
[-f [ ...]] [-x] [-t ] [-v] [--version]
Send a Direct Message to someone on Mastodon!
optional arguments:
-h, --help show this help message and exit
-r <@user@instan.ce>, --recipient <@user@instan.ce>
User who will receive a direct message.
-m , --message
Body of the message to be sent.
-s , --spoiler
Description for the spoiler warning which hides the message.
-f [ ...], --files [ ...]
List of up to 4 media files to attach to the message.
-x, --sensitive Flag post/media as sensitive content (blur media).
-t , --timeout
Number of seconds to wait for a single media file to upload.
-v, --verbose Print out verbose messages.
--version show program's version number and exit
```
## Usage from the command line
This section presents several examples on how to use TootNotify from the command line once it has been installed.
### Toot to a single user
`foo@bar:~$> tootnotify -r @user@instance -m "Message!"`
### Toot with spoiler/content warning
`foo@bar:~$> tootnotify -r @user@instance -s "Movie spoiler" -m "I can't believe Jhon dies at the end of the movie!"`
### Toot and single media file
`foo@bar:~$> tootnotify -r @user@instance -m "Look at this animation!" -f animated.gif`
### Toot and multiple media files
`foo@bar:~$> tootnotify -r @user@instance -m "Nice image gallery!" -f image1.png image2.jpg image3.jpeg`
__If more than four media files are passed to `tootnotify -f` only the first four media files will be attached to the direct message.__
### Toot with 'sensitive' media
`foo@bar:~$> tootnotify -r @user@instance -m "Check out this sensitive content!" -f sensitive.png -x`
### Combining options
All these arguments can be used in combination with one another, meaning a *Toot* can: have a message body, have up to four images attached, have a spoiler/content warning, and be flagged as 'sensitive'!
`foo@bar:~$> tootnotify -r @usert@instance -m "Check out this sensitive gallery!" -f 1.png 2.png 3.png 4.png -s "Very blue images containing numbers and circles" -x`
### Toot to multiple users
This is an unintended use case, and it's sort of _hacky_, but you can add multiple recipients to the *Toot*, by adding multiple Mastodon handles with their respective instances as a `quoted string` passed to the `-r`/`--recipient` argument:
`foo@bar:~$> tootnotify -r "@user1@instance1 @user2@instance2" -m "Group Message!"`
## License Notice
TootNotify Copyright (C) 2023 Jorge A. Duarte
This program comes with ABSOLUTELY NO WARRANTY; for details see [LICENSE](LICENSE). This is free software, and you are welcome to redistribute it under certain conditions; see [LICENSE](LICENSE) for details.
