| Name | tootnotify JSON |
| Version |
1.0.0rc1
JSON |
| download |
| home_page | |
| Summary | Command line tool to send DM notifications to a mastodon user. |
| upload_time | 2023-07-13 01:16:32 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | |
| keywords |
mastodon
notification
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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.
>Becasue 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 notificatio 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](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 users `$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` correspond 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 via PIP
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 <message_body>] [-s <spoiler_description>]
[-f <path_to_media_file> [<path_to_media_file> ...]] [-x] [-t <timeout_in_seconds>] [-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>, --message <message_body>
Body of the message to be sent.
-s <spoiler_description>, --spoiler <spoiler_description>
Description for the spoiler warning which hides the message.
-f <path_to_media_file> [<path_to_media_file> ...], --files <path_to_media_file> [<path_to_media_file> ...]
List of up to 4 media files to attach to the message.
-x, --sensitive Flag post/media as sensitive content (blur media).
-t <timeout_in_seconds>, --timeout <timeout_in_seconds>
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.
Raw data
{
"_id": null,
"home_page": "",
"name": "tootnotify",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "mastodon,notification",
"author": "",
"author_email": "\"Jorge A. Duarte\" <babetoduarte@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/83/67/8450c70442d1f2f8ce788eb559bc8a7d86affff1412484af2be4318f7e8e/tootnotify-1.0.0rc1.tar.gz",
"platform": null,
"description": "# TootNotify \n\nThis 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:\n\n`foo@bar:~$> tootnotify -r @user@instance -m \"Message from TootNotify!\"`\n\nI 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.\n\n\n>Becasue 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*).\n\nThis tool allows to *attach* image, video and audio files to the direct message:\n\n`foo@bar:~$> tootnotify -r @user@instance -m \"Message with media\" -f image1.png image2.jpg`\n \nDue 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**.\n\nNote 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 notificatio at all!).\n\nThere 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.\n\n## Mastodon API\n\nTo use this tool you will need to have a Mastodon API application created, with its corresponding API credentials. \n\nThe simplest way to do this, is through the Mastodon web interface: go to Preferences > Development (*i.e.* [mastodon.social/settings/applications](mastodon.social/settings/applications))\n\n![Mastodon Preferences - Development Settings](./media/0-mastodon_app_credentials.png \"Mastodon Preferences - Development Settings\")\n\nOnce 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.\n## Installation\n\nThis section presents the steps needed to install TootNotify, once the API credentials have been obtained.\n\n### Create `~/.tootnotifyrc` file\n\nTootNotify looks for API credentials stored as variables in the `~/.tootnotifyrc` file within the users `$HOME` folder. By default, **the `.tootnotifyrc` file is not shipped with the project, which means you need to create it**:\n\n`foo@bar:~$> touch ~/.tootnotifyrc`\n\nMake sure that the content of `~/.tootnotify` correspond to the following (and be sure to assign values to these variables **without any quotes**!):\n\n``` shell\n## FILE: ~/.tootnotifyrc\n[tootnotify]\n# Instance url (e.g. https://mastodon.social)\napi_base_url = YOUR_INSTANCE_URL\n# API Client Key\nclient_id = YOUR CLIENT_ID\n# API Client Secret\nclient_secret = YOUR_CLIENT_SECRET\n# API Access Token\naccess_token = YOU_ACCESS_TOKEN\n# Default recipient for the private toots (e.g. @account@mastodon.social)\nDEFAULT_RECIPIENT = YOUR_DEFAULT_RECIPIENT\n```\n\nAmong 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:\n\n`foo@bar:~$> tootnotify -m \"Message to the default recipient!\"`\n\n### Install via PIP\n\nOnce 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):\n\n``` bash\nfoo@bar:TootNotify$> pip install .\n```\n\nWe can check whether TootNotify was installed correctly, by invoking it (from anywhere) and passing it the `-h`/`--help` flag:\n\n``` bash\nfoo@bar:~$> tootnotify -h\n```\n\nand if all goes well, we should be presented with the help dialog:\n\n``` bash\nusage: tootnotify [-h] [-r <@user@instan.ce>] [-m <message_body>] [-s <spoiler_description>]\n [-f <path_to_media_file> [<path_to_media_file> ...]] [-x] [-t <timeout_in_seconds>] [-v] [--version]\n\nSend a Direct Message to someone on Mastodon!\n\noptional arguments:\n -h, --help show this help message and exit\n -r <@user@instan.ce>, --recipient <@user@instan.ce>\n User who will receive a direct message.\n -m <message_body>, --message <message_body>\n Body of the message to be sent.\n -s <spoiler_description>, --spoiler <spoiler_description>\n Description for the spoiler warning which hides the message.\n -f <path_to_media_file> [<path_to_media_file> ...], --files <path_to_media_file> [<path_to_media_file> ...]\n List of up to 4 media files to attach to the message.\n -x, --sensitive Flag post/media as sensitive content (blur media).\n -t <timeout_in_seconds>, --timeout <timeout_in_seconds>\n Number of seconds to wait for a single media file to upload.\n -v, --verbose Print out verbose messages.\n --version show program's version number and exit\n```\n\n## Usage from the command line\n\nThis section presents several examples on how to use TootNotify from the command line once it has been installed.\n\n### Toot to a single user\n\n`foo@bar:~$> tootnotify -r @user@instance -m \"Message!\"`\n\n![Toot - DM to user](./media/1-Toot_Single.png \"Toot - DM to user\")\n\n### Toot with spoiler/content warning\n\n`foo@bar:~$> tootnotify -r @user@instance -s \"Movie spoiler\" -m \"I can't believe Jhon dies at the end of the movie!\"`\n\n![Toot - DM to user with Content Warning and hidden message](./media/2-Toot_CW1.png \"Toot - DM to user with Content Warning and hidden message\")\n\n![Toot - DM to user with CW and message visible](./media/2-Toot_CW2.png \"Toot - DM to user with CW and message visible\")\n\n### Toot and single media file\n\n`foo@bar:~$> tootnotify -r @user@instance -m \"Look at this animation!\" -f animated.gif`\n\n![Toot - DM to user with attached GIF](./media/3-Toot_GIF.png \"Toot - DM to user with attached GIF\")\n\n### Toot and multiple media files\n\n`foo@bar:~$> tootnotify -r @user@instance -m \"Nice image gallery!\" -f image1.png image2.jpg image3.jpeg`\n\n![Toot - DM to user with four images attached](./media/4-Toot_Gallery.png \"Toot - DM to user with four images attached\")\n\n__If more than four media files are passed to `tootnotify -f` only the first four media files will be attached to the direct message.__\n\n### Toot with 'sensitive' media\n\n`foo@bar:~$> tootnotify -r @user@instance -m \"Check out this sensitive content!\" -f sensitive.png -x`\n\n![Toot - DM to user with Sensitive Content hidden](./media/5-Toot_Sensitive1.png \"Toot - DM to user with Sensitive Content hidden\")\n\n![Toot - DM to user with Sensitive Content visible](./media/5-Toot_Sensitive2.png \"Toot - DM to user with Sensitive Content visible\")\n\n### Combining options\n\nAll 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'!\n\n`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`\n\n![Toot - DM to user containing multiple images, a content warning, and flagged as sensitive content](./media/6-Toot_All1.png \"Toot - DM to user containing multiple images, a content warning, and flagged as sensitive content\")\n\n![Toot - DM to user containing multiple images, a content warning, and flagged as sensitive content - content visible](./media/6-Toot_All2.png \"Toot - DM to user containing multiple images, a content warning, and flagged as sensitive content - content visible\")\n\n### Toot to multiple users\n\nThis 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:\n\n`foo@bar:~$> tootnotify -r \"@user1@instance1 @user2@instance2\" -m \"Group Message!\"`\n\n## License Notice\n\nTootNotify Copyright (C) 2023 Jorge A. Duarte\nThis 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. \n\n",
"bugtrack_url": null,
"license": "",
"summary": "Command line tool to send DM notifications to a mastodon user.",
"version": "1.0.0rc1",
"project_urls": {
"Bug Tracker": "https://github.com/babetoduarte/TootNotify/issues",
"Homepage": "https://github.com/babetoduarte/TootNotify"
},
"split_keywords": [
"mastodon",
"notification"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "211aa66d876b318aa84445001143f0a72f48b32f56a199ead182535bb4fe4880",
"md5": "bcbba0beb2bf541ca829021afed77342",
"sha256": "4a3e095ffcae11310fc2ecfbdddc1e135193788f88a7ad754e05d169d0b83bcd"
},
"downloads": -1,
"filename": "tootnotify-1.0.0rc1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bcbba0beb2bf541ca829021afed77342",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 22898,
"upload_time": "2023-07-13T01:16:30",
"upload_time_iso_8601": "2023-07-13T01:16:30.993028Z",
"url": "https://files.pythonhosted.org/packages/21/1a/a66d876b318aa84445001143f0a72f48b32f56a199ead182535bb4fe4880/tootnotify-1.0.0rc1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "83678450c70442d1f2f8ce788eb559bc8a7d86affff1412484af2be4318f7e8e",
"md5": "05f6e3b9fcfc29ce47dde8e91c671a2d",
"sha256": "d83a70305c27420250a07f5d14a14be2d118d6d772719cf004ff81486d9536f0"
},
"downloads": -1,
"filename": "tootnotify-1.0.0rc1.tar.gz",
"has_sig": false,
"md5_digest": "05f6e3b9fcfc29ce47dde8e91c671a2d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 24237,
"upload_time": "2023-07-13T01:16:32",
"upload_time_iso_8601": "2023-07-13T01:16:32.596568Z",
"url": "https://files.pythonhosted.org/packages/83/67/8450c70442d1f2f8ce788eb559bc8a7d86affff1412484af2be4318f7e8e/tootnotify-1.0.0rc1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-13 01:16:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "babetoduarte",
"github_project": "TootNotify",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "tootnotify"
}
