<br />
<div align="center">
<h1 align="center">Ditch The Bell</h1>
<a href="https://github.com/EscherMoore/DitchTheBell">
<img src="https://raw.githubusercontent.com/EscherMoore/DitchTheBell/main/logo.png" alt="Logo">
</a>
<p align="center">
A desktop notifier for RSS/Atom feeds that lets you closely configure features of the <a href="https://specifications.freedesktop.org/notification-spec/latest/ar01s02.html">freedesktop notification specification</a> to unlock the most customizable feed notification experience possible on Linux.
</p>
</div>
## Features
* Configure a custom command to launch when clicking on a notification (e.g., your favorite application, shell command, custom script). The feed entry link will be passed as an argument, allowing the command to open the link directly.
* A feed profile system built to separate notification behaviors for each of your different types of feeds (e.g., news, blogs, podcasts, videos, etc).
* Define patterns in your profiles to filter feeds so you're only notified for the entries that are relevant to you.
* Configuration options to fine-tune feed fetching behavior such as the search window, search interval, etc.
<br />
## Install
##### PyPI
###### Dependencies:
* `Python 3.7+`
* **Optional**: Before installing, it is recommended that you install <a href="https://pygobject.readthedocs.io/en/latest/devguide/dev_environ.html?highlight=install#install-dependencies">PyGObject</a> from your distribution's package manager for <a href="https://wiki.gnome.org/Projects/GObjectIntrospection">GObject Introspection</a>. The package is typically named one of the following: `python-gi`, `python-gobject`, or `pygobject` on most distributions.
Ditch The Bell is available on <a href="https://pypi.org/project/dtbell/">PyPI</a> and can be installed via <a href="https://pip.pypa.io/en/stable/">pip</a>, the Python package manager.
```bash
pip install dtbell
```
---
##### Arch Linux (AUR):
Ditch The Bell is available in the Arch AUR: <a href="https://aur.archlinux.org/packages/dtbell-git">dtbell-git</a>
<br />
## Usage
To run, simply execute:
```bash
dtbell
```
If needed, use the `--debug` flag to print debug logs to the console:
```bash
dtbell --debug
```
<br />
## Configuring
#### File Locations
All relevant files are stored in accordance with the <a href="https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG Base Directory Specification</a>.
Configuration files `config.ini`, `urls`: are located in `$XDG_CONFIG_HOME/dtbell/`.
> If `$XDG_CONFIG_HOME` is not set, the default location is `$HOME/.config/dtbell/`.
Data files `dtbell.db`, `dtbell.log`: are located in `$XDG_DATA_HOME/dtbell/`.
> If `$XDG_DATA_HOME` is not set, the default location is `$HOME/.local/share/dtbell/`.
If you enable thumbnail downloads, thumbnails will be temporarily downloaded to `/tmp/dtbell/`.
### Adding Feeds
To add feeds, edit the `urls` file, adding one URL per line.
```text
https://example.com/feed/rss.xml
https://another-example.com/feed/rss.xml
```
Authenticated feeds are not yet supported.
### Configuration Options
To modify the configuration settings, edit the `config.ini` file.
#### Feed Configuration
The `[feed]` section in your `config.ini` file serves as the primary area for defining feed fetch behavior. Below are the available configuration options for the `[feed]` section:
| Name | Description | Data Type | Default Value |
|---------------------|------------------------------------------------------------------------------------------------------------|-----------|---------------|
| `search_window` | The number of days to go back when searching for new feeds. Cached entries are retained for this duration. | Integer | `1` |
| `search_interval` | Time interval (in minutes) between each search for new entries. | Integer | `30` |
| `search_on_startup` | Determines if a search is initiated upon application launch. | Boolean | `true` |
| `flood_cap` | Maximum number of notifications to avoid notification flooding. Set to 0 for unlimited. | Integer | `10` |
| `fetch_timeout` | Maximum time (in seconds) the app will wait for a response after requesting a feed. | Integer | `10` |
#### Defining Profiles
The profile system is designed to adapt to the diverse array of feeds that modern RSS users often manage (news feeds, blog feeds, podcast feeds, etc). It allows for tailored notification behavior based on the nature of each feed. You can define custom notification profiles for these specific types of feeds in your `config.ini` file. For instance, a profile for video based feeds could look like this:
```ini
[video]
entry_age = true
persist_on_click = true
launcher = mpv
launcher_args = '--save-position-on-quit'
```
A `[default]` profile is defined in the `config.ini` file and serves as the baseline configuration for all feeds not tagged with a custom profile. Below are the available configuration options for the `[default]` section:
| Name | Description | Data Type | Default Value |
|-----------------------|------------------------------------------------------------------------------------------|----------------------------------|-------------------|
| `launcher` | Shell command to open notifications; must accept a URL as argument. | String | `default_browser` |
| `launch_args` | Argument(s) to pass to `launcher`; e.g., `'-P news'` if `launcher` was set to `firefox`. | String | `''` |
| `transience` | Determines whether notifications are temporary and disappear after a short time. | Boolean | `false` |
| `persist_on_click` | Keep notification after click; useful if transience is set to false. | Boolean | `false` |
| `urgency` | Notification urgency: 0 (low), 1 (normal), 2 (critical). | Integer | `1` |
| `timeout` | Timeout in ms; -1 for server default, 0 for never. | Integer | `-1` |
| `entry_age` | Display entry age. | Boolean | `false` |
| `download_thumbnails` | Download thumbnails; consult your feed's TOS and be mindful of bandwidth usage. | Boolean | `true` |
| `require_patterns` | Require entries to contain at least one of these patterns; e.g., `'Open Source', Linux` | Custom (Comma-separated values) | `''` |
| `exclude_patterns` | Exclude entries that contain any one of these patterns; e.g., `Proprietary, Windows` | Custom (Comma-separated values) | `''` |
You can modify the default profile directly to affect all untagged feeds, or define custom profiles like the `[video]` profile if you wish to customize settings for a select group of feeds. Omitting fields in a custom profile will cause those settings to fall back to the values defined in the default profile.
#### Adding Profiles to URLs
As mentioned earlier, the `urls` file should contain one RSS feed URL per line. To associate a profile with a specific feed, simply append the profile name (the name within the square brackets `[ ]` in your `config.ini`) to the end of the feed URL, separated by a space. The format is simply `url profile`. For instance, using the `[video]` profile from earlier, an example `urls` file would look like this:
```text
https://example.com/feed/rss.xml video
https://another-example.com/feed/rss.xml video
```
<br />
## Contributing
This program is in its early stages of development and may have some rough edges or bugs. If you encounter any issues and want to contribute, feel free to submit an issue or open a PR!
Note: All PRs must adhere to PEP 8 and pass pylint checks.
<br />
#### License
This program is licensed under the GPLv3; see the LICENSE file.
Raw data
{
"_id": null,
"home_page": "",
"name": "dtbell",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "atom,desktop,linux,notifications,notify,rss",
"author": "Escher Moore",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/b8/eb/991a44002674b644a418dac5a5d13eed943d102dbb7321125d5096d4b2e7/dtbell-1.1.1.tar.gz",
"platform": null,
"description": "<br />\n<div align=\"center\">\n <h1 align=\"center\">Ditch The Bell</h1>\n <a href=\"https://github.com/EscherMoore/DitchTheBell\">\n <img src=\"https://raw.githubusercontent.com/EscherMoore/DitchTheBell/main/logo.png\" alt=\"Logo\">\n </a>\n <p align=\"center\">\n A desktop notifier for RSS/Atom feeds that lets you closely configure features of the <a href=\"https://specifications.freedesktop.org/notification-spec/latest/ar01s02.html\">freedesktop notification specification</a> to unlock the most customizable feed notification experience possible on Linux.\n </p>\n</div>\n\n## Features\n\n* Configure a custom command to launch when clicking on a notification (e.g., your favorite application, shell command, custom script). The feed entry link will be passed as an argument, allowing the command to open the link directly.\n\n* A feed profile system built to separate notification behaviors for each of your different types of feeds (e.g., news, blogs, podcasts, videos, etc).\n\n* Define patterns in your profiles to filter feeds so you're only notified for the entries that are relevant to you.\n\n* Configuration options to fine-tune feed fetching behavior such as the search window, search interval, etc.\n\n<br />\n\n## Install\n\n##### PyPI\n\n###### Dependencies:\n\n* `Python 3.7+`\n* **Optional**: Before installing, it is recommended that you install <a href=\"https://pygobject.readthedocs.io/en/latest/devguide/dev_environ.html?highlight=install#install-dependencies\">PyGObject</a> from your distribution's package manager for <a href=\"https://wiki.gnome.org/Projects/GObjectIntrospection\">GObject Introspection</a>. The package is typically named one of the following: `python-gi`, `python-gobject`, or `pygobject` on most distributions.\n\nDitch The Bell is available on <a href=\"https://pypi.org/project/dtbell/\">PyPI</a> and can be installed via <a href=\"https://pip.pypa.io/en/stable/\">pip</a>, the Python package manager.\n\n```bash\npip install dtbell\n```\n\n---\n\n##### Arch Linux (AUR):\n\nDitch The Bell is available in the Arch AUR: <a href=\"https://aur.archlinux.org/packages/dtbell-git\">dtbell-git</a>\n\n<br />\n\n## Usage\n\nTo run, simply execute:\n\n```bash\ndtbell\n```\n\nIf needed, use the `--debug` flag to print debug logs to the console:\n\n```bash\ndtbell --debug \n```\n\n<br />\n\n## Configuring\n\n#### File Locations\n\nAll relevant files are stored in accordance with the <a href=\"https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html\">XDG Base Directory Specification</a>.\n\nConfiguration files `config.ini`, `urls`: are located in `$XDG_CONFIG_HOME/dtbell/`. \n> If `$XDG_CONFIG_HOME` is not set, the default location is `$HOME/.config/dtbell/`.\n\nData files `dtbell.db`, `dtbell.log`: are located in `$XDG_DATA_HOME/dtbell/`. \n> If `$XDG_DATA_HOME` is not set, the default location is `$HOME/.local/share/dtbell/`.\n\nIf you enable thumbnail downloads, thumbnails will be temporarily downloaded to `/tmp/dtbell/`.\n\n### Adding Feeds\n\nTo add feeds, edit the `urls` file, adding one URL per line.\n\n```text\nhttps://example.com/feed/rss.xml\nhttps://another-example.com/feed/rss.xml\n```\n\nAuthenticated feeds are not yet supported.\n\n### Configuration Options \n\nTo modify the configuration settings, edit the `config.ini` file.\n\n#### Feed Configuration\n\nThe `[feed]` section in your `config.ini` file serves as the primary area for defining feed fetch behavior. Below are the available configuration options for the `[feed]` section:\n\n| Name | Description | Data Type | Default Value |\n|---------------------|------------------------------------------------------------------------------------------------------------|-----------|---------------|\n| `search_window` | The number of days to go back when searching for new feeds. Cached entries are retained for this duration. | Integer | `1` |\n| `search_interval` | Time interval (in minutes) between each search for new entries. | Integer | `30` |\n| `search_on_startup` | Determines if a search is initiated upon application launch. | Boolean | `true` |\n| `flood_cap` | Maximum number of notifications to avoid notification flooding. Set to 0 for unlimited. | Integer | `10` |\n| `fetch_timeout` | Maximum time (in seconds) the app will wait for a response after requesting a feed. | Integer | `10` |\n\n#### Defining Profiles\n\nThe profile system is designed to adapt to the diverse array of feeds that modern RSS users often manage (news feeds, blog feeds, podcast feeds, etc). It allows for tailored notification behavior based on the nature of each feed. You can define custom notification profiles for these specific types of feeds in your `config.ini` file. For instance, a profile for video based feeds could look like this:\n\n```ini\n[video]\nentry_age = true\npersist_on_click = true\nlauncher = mpv \nlauncher_args = '--save-position-on-quit'\n```\n\nA `[default]` profile is defined in the `config.ini` file and serves as the baseline configuration for all feeds not tagged with a custom profile. Below are the available configuration options for the `[default]` section:\n\n| Name | Description | Data Type | Default Value |\n|-----------------------|------------------------------------------------------------------------------------------|----------------------------------|-------------------|\n| `launcher` | Shell command to open notifications; must accept a URL as argument. | String | `default_browser` |\n| `launch_args` | Argument(s) to pass to `launcher`; e.g., `'-P news'` if `launcher` was set to `firefox`. | String | `''` |\n| `transience` | Determines whether notifications are temporary and disappear after a short time. | Boolean | `false` |\n| `persist_on_click` | Keep notification after click; useful if transience is set to false. | Boolean | `false` |\n| `urgency` | Notification urgency: 0 (low), 1 (normal), 2 (critical). | Integer | `1` |\n| `timeout` | Timeout in ms; -1 for server default, 0 for never. | Integer | `-1` |\n| `entry_age` | Display entry age. | Boolean | `false` |\n| `download_thumbnails` | Download thumbnails; consult your feed's TOS and be mindful of bandwidth usage. | Boolean | `true` |\n| `require_patterns` | Require entries to contain at least one of these patterns; e.g., `'Open Source', Linux` | Custom (Comma-separated values) | `''` |\n| `exclude_patterns` | Exclude entries that contain any one of these patterns; e.g., `Proprietary, Windows` | Custom (Comma-separated values) | `''` |\n\nYou can modify the default profile directly to affect all untagged feeds, or define custom profiles like the `[video]` profile if you wish to customize settings for a select group of feeds. Omitting fields in a custom profile will cause those settings to fall back to the values defined in the default profile.\n\n#### Adding Profiles to URLs\n\nAs mentioned earlier, the `urls` file should contain one RSS feed URL per line. To associate a profile with a specific feed, simply append the profile name (the name within the square brackets `[ ]` in your `config.ini`) to the end of the feed URL, separated by a space. The format is simply `url profile`. For instance, using the `[video]` profile from earlier, an example `urls` file would look like this:\n\n```text\nhttps://example.com/feed/rss.xml video\nhttps://another-example.com/feed/rss.xml video\n```\n\n<br />\n\n## Contributing\n\nThis program is in its early stages of development and may have some rough edges or bugs. If you encounter any issues and want to contribute, feel free to submit an issue or open a PR!\n\nNote: All PRs must adhere to PEP 8 and pass pylint checks.\n\n<br />\n\n#### License\n\nThis program is licensed under the GPLv3; see the LICENSE file.\n",
"bugtrack_url": null,
"license": "",
"summary": "A highly configurable desktop notifier for RSS/Atom feeds.",
"version": "1.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/EscherMoore/DitchTheBell/issues",
"Documentation": "https://github.com/EscherMoore/DitchTheBell/blob/main/README.md",
"Homepage": "https://github.com/EscherMoore/DitchTheBell",
"repository": "https://github.com/EscherMoore/DitchTheBell"
},
"split_keywords": [
"atom",
"desktop",
"linux",
"notifications",
"notify",
"rss"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3c8452bbe373869a1af8894aa7569db0effe8dd3a7d94b1b8cec1e212b11a8e1",
"md5": "787e3402b469c3e2e3275ccaa06017db",
"sha256": "f8528bd9543f916e6a8599cbe8d3fa6b82db8c8ea0195d0f0156348feb0c2d84"
},
"downloads": -1,
"filename": "dtbell-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "787e3402b469c3e2e3275ccaa06017db",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 104957,
"upload_time": "2024-03-15T18:06:20",
"upload_time_iso_8601": "2024-03-15T18:06:20.752775Z",
"url": "https://files.pythonhosted.org/packages/3c/84/52bbe373869a1af8894aa7569db0effe8dd3a7d94b1b8cec1e212b11a8e1/dtbell-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b8eb991a44002674b644a418dac5a5d13eed943d102dbb7321125d5096d4b2e7",
"md5": "07df3e086bab273dc15fe15b1dc31b9d",
"sha256": "1182cfd161896c42581fd9352f13c97b6e0c74ac5867bf76e3f60cc0b3f5ba7d"
},
"downloads": -1,
"filename": "dtbell-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "07df3e086bab273dc15fe15b1dc31b9d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 1759152,
"upload_time": "2024-03-15T18:06:22",
"upload_time_iso_8601": "2024-03-15T18:06:22.355582Z",
"url": "https://files.pythonhosted.org/packages/b8/eb/991a44002674b644a418dac5a5d13eed943d102dbb7321125d5096d4b2e7/dtbell-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-15 18:06:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "EscherMoore",
"github_project": "DitchTheBell",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "aiohttp",
"specs": []
},
{
"name": "feedparser",
"specs": []
},
{
"name": "PyGObject",
"specs": []
},
{
"name": "pydbus",
"specs": []
},
{
"name": "python-dateutil",
"specs": []
},
{
"name": "pytz",
"specs": []
}
],
"lcname": "dtbell"
}
JSON
