@ -540,15 +540,17 @@ You can read more about creating your own custom notifications and/or hooks [her
Persistent storage allows Apprise to cache re-occurring actions optionaly to disk. This can greatly reduce the overhead used to send a notification.
There are 3 options Apprise can operate using this:
1. `AUTO`: Flush any gathered data for persistent storage on demand. This option is incredibly light weight. This is the default behavior for all CLI usage. Content can be manually flushed to disk using this option as well should a developer choose to do so. The CLI uses this option by default and only writes anything accumulated to disk after all of it's notifications have completed.
1. `FLUSH`: Flushes any gathered data for persistent storage as often as it is acquired.
1. `MEMORY`: Only store information in memory, never write to disk. This is the option one would set if they simply wish to disable Persistent Storage entirely. By default this is the mode used by the API and is at the developers discretion to enable one of the other options.
There are 3 Persistent Storage operational states Apprise can operate using:
1. `auto`: Flush gathered cache information to the filesystem on demand. This option is incredibly light weight. This is the default behavior for all CLI usage.
* Developers who choose to use this operational mode can also force cached information manually if they choose.
* The CLI will use this operational mode by default.
1. `flush`: Flushes any cache information to the filesystem during every transaction.
1. `memory`: Effectively disable Persistent Storage. Any caching of data required by each plugin used is done in memory. Apprise effectively operates as it always did before peristent storage was available. This setting ensures no content is every written to disk.
* By default this is the mode Apprise will operate under for those developing with it unless they configure it to otherwise operate as `auto` or `flush`. This is done through the `AppriseAsset()` object and is explained further on in this documentation.
## CLI Persistent Storage Commands
Persistent storage is set to `AUTO` mode by default.
Specifying the keyword `storage` will assume that all subseqent calls are related to the storage subsection of Apprise.
You can provide the keyword `storage` on your CLI call to see the persistent storage options available to you.
```bash
# List all of the occupied space used by Apprise's Persistent Storage:
apprise storage list
@ -579,12 +581,12 @@ You can also filter your results by adding tags and/or URL Identifiers. When yo
3. abcd123 12.00B stale
```
The states are:
The (persistent storage) cache states are:
- `unused`: This plugin has not commited anything to disk for reuse/cache purposes
- `active`: This plugin has written content to disk. Or at the very least, it has prepared a persistent storage location it can write into.
- `stale`: The system detected a location where a URL may have possibly written to in the past, but there is nothing linking to it using the URLs provided. It is likely wasting space or is no longer of any use.
You can use this information to filter your results by specifying _URL ID_ values after your command. For example:
You can use this information to filter your results by specifying _URL ID_(UID) values after your command. For example:
```bash
# The below commands continue with the example already identified above
# the following would match abcd123 (even though just ab was provided)
@ -603,13 +605,14 @@ apprise storage list --tag=team
# The followin would actually match the URL ID's of 1. and .2 above
apprise storage list f 0
```
When using the CLI, Persistent storage is set to the operational mode of `auto` by default, you can change this by providing `--storage-mode=` (`-SM`) during your calls. If you want to ensure it's always set to a value of your choice.
For more information on persistent storage, [visit here](https://github.com/caronc/apprise/wiki/persistent_storage).
## API Persistent Storage Commands
By default, no persistent storage is set to be in `MEMORY` mode for those building from within the Apprise API.
It's at the developers discretion to enable it. But should you choose to do so, it's as easy as including the information in the `AppriseAsset()` object prior to the initialization of your `Apprise()` instance.
For developers, persistent storage is set in the operational mode of `memory` by default.
It's at the developers discretion to enable it (by switching it to either `auto` or `flush`). Should you choose to do so: it's as easy as including the information in the `AppriseAsset()` object prior to the initialization of your `Apprise()` instance.
For example:
```python
@ -617,12 +620,13 @@ from apprise import Apprise
from apprise import AppriseAsset
from apprise import PersistentStoreMode
# Prepare a location the persistent storage can write to
# This immediately assumes you wish to write in AUTO mode
# Prepare a location the persistent storage can write it's cached content to.
# By setting this path, this immediately assumes you wish to operate the
# persistent storage in the operational 'auto' mode
\fBApprise\fR allows you to send a notification to \fIalmost all\fR of the most popular notification services available to us today such as: Discord, Telegram, Pushbullet, Slack, Twitter, etc\.
.IP"\[ci]"4
@ -14,38 +16,50 @@ One notification library to rule them all\.
A common and intuitive notification syntax\.
.IP"\[ci]"4
Supports the handling of images (to the notification services that will accept them)\.
.IP"\[ci]"4
It\'s incredibly lightweight\.
.IP"\[ci]"4
Amazing response times because all messages sent asynchronously\.
.IP""0
.SH"OPTIONS"
The Apprise options are as follows:
.P
\fB\-b\fR, \fB\-\-body=\fR\fITEXT\fR: Specify the message body\. If no body is specified then content is read from \fIstdin\fR\.
\fB\-b\fR, \fB\-\-body=\fR\fIVALUE\fR: Specify the message body\. If no body is specified then content is read from \fIstdin\fR\.
.P
\fB\-t\fR, \fB\-\-title=\fR\fITEXT\fR: Specify the message title\. This field is complete optional\.
\fB\-t\fR, \fB\-\-title=\fR\fIVALUE\fR: Specify the message title\. This field is complete optional\.
.P
\fB\-c\fR, \fB\-\-config=\fR\fICONFIG\-URL\fR: Specify one or more configuration locations\.
.P
\fB\-a\fR, \fB\-\-attach=\fR\fIATTACH\-URL\fR: Specify one or more file attachment locations\.
.P
\fB\-P\fR, \fB\-\-plugin\-path=\fR\fIPLUGIN\-PATH\fR: Specify a path to scan for custom notification plugin support\. You can create your own notification by simply creating a Python file that contains the \fB@notify("schema")\fR decorator\.
\fB\-P\fR, \fB\-\-plugin\-path=\fR\fIPATH\fR: Specify a path to scan for custom notification plugin support\. You can create your own notification by simply creating a Python file that contains the \fB@notify("schema")\fR decorator\.
.P
You can optioanly chose to specify more then one \fB\-\-plugin\-path\fR (\fB\-P\fR) to increase the modules included\.
.P
\fB\-n\fR, \fB\-\-notification\-type=\fR\fITYPE\fR: Specify the message type (default=info)\. Possible values are "info", "success", "failure", and "warning"\.
\fB\-n\fR, \fB\-\-notification\-type=\fR\fIVALUE\fR: Specify the message type (default=info)\. Possible values are "info", "success", "failure", and "warning"\.
.P
\fB\-i\fR, \fB\-\-input\-format=\fR\fIFORMAT\fR: Specify the input message format (default=text)\. Possible values are "text", "html", and "markdown"\.
\fB\-i\fR, \fB\-\-input\-format=\fR\fIVALUE\fR: Specify the input message format (default=text)\. Possible values are "text", "html", and "markdown"\.
.P
\fB\-T\fR, \fB\-\-theme=\fRTHEME: Specify the default theme\.
\fB\-T\fR, \fB\-\-theme=\fR\fIVALUE\fR: Specify the default theme\.
.P
\fB\-g\fR, \fB\-\-tag=\fRTAG: Specify one or more tags to filter which services to notify\. Use multiple \fB\-\-tag\fR (\fB\-g\fR) entries to \fBOR\fR the tags together and comma separated to \fBAND\fR them\. If no tags are specified then all services are notified\.
\fB\-g\fR, \fB\-\-tag=\fR\fIVALUE\fR: Specify one or more tags to filter which services to notify\. Use multiple \fB\-\-tag\fR (\fB\-g\fR) entries to \fBOR\fR the tags together and comma separated to \fBAND\fR them\. If no tags are specified then all services are notified\.
.P
\fB\-Da\fR, \fB\-\-disable\-async\fR: Send notifications synchronously (one after the other) instead of all at once\.
.P
\fB\-R\fR, \fB\-\-recursion\-depth\fR: he number of recursive import entries that can be loaded from within Apprise configuration\. By default this is set to 1\. If this is set to zero, then import statements found in any configuration is ignored\.
\fB\-R\fR, \fB\-\-recursion\-depth\fR\fIINTEGER\fR: he number of recursive import entries that can be loaded from within Apprise configuration\. By default this is set to 1\. If this is set to zero, then import statements found in any configuration is ignored\.
.P
\fB\-e\fR, \fB\-\-interpret\-escapes\fR Enable interpretation of backslash escapes\. For example, this would convert sequences such as \en and \er to their respected ascii new\-line and carriage
.P
\fB\-j\fR, \fB\-\-interpret\-emojis\fR Enable interpretation of emoji strings\. For example, this would convert sequences such as :smile: or :grin: to their respected unicode emoji character\.
.P
\fB\-S\fR, \fB\-\-storage\-path=\fR\fIPATH\fR: Specify the path to the persistent storage caching location
.P
\fB\-SM\fR, \fB\-\-storage\-mode=\fR\fIMODE\fR: Specify the persistent storage operational mode\. Possible values are "auto", "flush", and "memory"\. The default is "auto" not not specified\.
.P
\fB\-SPD\fR, \fB\-\-storage\-prune\-days=\fR\fIINTEGER\fR: Define the number of days the storage prune should run using\. Setting this to zero (0) will eliminate all accumulated content\. By default this value is 30 (days)\.
.P
\fB\-SUL\fR, \fB\-\-storage\-uid\-length=\fR\fIINTEGER\fR: Define the number of unique characters to store persistent cache in\. By default this value is 8 (characters)\.
.P
\fB\-d\fR, \fB\-\-dry\-run\fR: Perform a trial run but only prints the notification services to\-be triggered to \fBstdout\fR\. Notifications are never sent using this mode\.
.P
return characters prior to the delivery of the notification\.
@ -59,6 +73,28 @@ return characters prior to the delivery of the notification\.
\fB\-V\fR, \fB\-\-version\fR: Display the apprise version and exit\.
.P
\fB\-h\fR, \fB\-\-help\fR: Show this message and exit\.
.SH"PERSISTENT STORAGE"
Persistent storage by default writes to the following location unless the environment variable \fBAPPRISE_STORAGE_PATH\fR over\-rides it and/or \fB\-\-storage\-path\fR (\fB\-SP\fR) is specified to over\-ride it:
.IP""4
.nf
~/\.local/share/apprise/cache
.fi
.IP""0
.P
To utilize the persistent storage \fIhttps://github\.com/caronc/apprise/wiki/persistent_storage\fR element associated with Apprise, simply specify the keyword \fBstorage\fR
.IP""4
.nf
$ apprise storage
.fi
.IP""0
.P
The \fBstorage\fR action has the following sub actions:
.P
\fBlist\fR: List all of the detected persistent storage elements and their state (\fBstale\fR, \fBactive\fR, or \fBunused\fR)\. This is the default action if nothing further is identified\.
.P
\fBprune\fR: Removes all persistent storage that has not been referenced for more then 30 days\. You can optionally set the \fB\-\-storage\-prune\-days\fR to alter this default value\.
.P
\fBclean\fR: Removes all persistent storage reguardless of age\.
# Returning True/False is a way to relay your status back to Apprise\.
# Returning nothing (None by default) is always interpreted as a Success
# Returning True/False will relay your status back through Apprise
# Returning nothing (None by default) is always interpreted as True
return True
.fi
.IP""0
.SH"CONFIGURATION"
A configuration file can be in the format of either \fBTEXT\fR or \fBYAML\fR where [TEXT][textconfig] is the easiest and most ideal solution for most users\. However YAML \fIhttps://github\.com/caronc/apprise/wiki/config_yaml\fR configuration files grants the user a bit more leverage and access to some of the internal features of Apprise\. Reguardless of which format you choose, both provide the users the ability to leverage \fBtagging\fR which adds a more rich and powerful notification environment\.
A configuration file can be in the format of either \fBTEXT\fR or \fBYAML\fR where TEXT \fIhttps://github\.com/caronc/apprise/wiki/config_text\fR is the easiest and most ideal solution for most users\. However YAML \fIhttps://github\.com/caronc/apprise/wiki/config_yaml\fR configuration files grants the user a bit more leverage and access to some of the internal features of Apprise\. Reguardless of which format you choose, both provide the users the ability to leverage \fBtagging\fR which adds a more rich and powerful notification environment\.
.P
Configuration files can be directly referenced via \fBapprise\fR when referencing the \fB\-\-config=\fR (\fB\-c\fR) CLI directive\. You can identify as many as you like on the command line and all of them will be loaded\. You can also point your configuration to a cloud location (by referencing \fBhttp://\fR or \fBhttps://\fR\. By default \fBapprise\fR looks in the following local locations for configuration files and loads them:
.IP""4
@ -176,11 +233,14 @@ $ apprise \-vv \-t "my title" \-b "my notification body"
If you leveraged tagging \fIhttps://github\.com/caronc/apprise/wiki/CLI_Usage#label\-leverage\-tagging\fR, you can define all of Apprise Service URLs in your configuration that you want and only specifically notify a subset of them:
.IP""4
.nf
$ apprise \-vv \-t "Will Be Late" \-b "Go ahead and make dinner without me" \e
\-\-tag=family
$ apprise \-vv \-\-title "Will Be Late Getting Home" \e
\-\-body "Please go ahead and make dinner without me\." \e
\-\-tag=family
.fi
.IP""0
.SH"BUGS"
If you find any bugs, please make them known at: \fIhttps://github\.com/caronc/apprise/issues\fR
.SH"DONATIONS"
If you found Apprise useful at all, \fIplease consider donating\fR!
.SH"COPYRIGHT"
Apprise is Copyright (C) 2024 Chris Caron \fIlead2gold@gmail\.com\fR
<p>Persistent storage by default writes to the following location unless the environment variable <code>APPRISE_STORAGE_PATH</code> over-rides it and/or <code>--storage-path</code> (<code>-SP</code>) is specified to over-ride it:</p>
<pre><code>~/.local/share/apprise/cache
</code></pre>
<p>To utilize the <ahref="https://github.com/caronc/apprise/wiki/persistent_storage">persistent storage</a> element associated with Apprise, simply
specify the keyword <strong>storage</strong></p>
<pre><code>$ apprise storage
</code></pre>
<p>The <strong>storage</strong> action has the following sub actions:</p>
<p><code>list</code>:
List all of the detected persistent storage elements and their state
(<strong>stale</strong>, <strong>active</strong>, or <strong>unused</strong>). This is the default action if
nothing further is identified.</p>
<p><code>prune</code>:
Removes all persistent storage that has not been referenced for more then 30
days. You can optionally set the <code>--storage-prune-days</code> to alter this
default value.</p>
<p><code>clean</code>:
Removes all persistent storage reguardless of age.</p>
<h2id="EXIT-STATUS">EXIT STATUS</h2>
<p><strong>apprise</strong> exits with a status of:</p>
@ -235,6 +284,21 @@ notification service URLs and only notify the ones tagged as <em>devops</em>.</p
--attach=Documents/FinalReport.docx
</code></pre>
<p>List all of the notifications loaded:</p>
<pre><code>$ apprise --dry-run --tag=all
</code></pre>
<p>List all of the details around the current persistent storage setup:</p>
<pre><code>$ apprise storage list
</code></pre>
<p>Prune all persistent storage that has not been referenced for at least 10 days or more</p>
# Returning True/False is a way to relay your status back to Apprise.
# Returning nothing (None by default) is always interpreted as a Success
print("Define your custom code here")
# Returning True/False will relay your status back through Apprise
# Returning nothing (None by default) is always interpreted as True
return True
</code></pre>
<h2id="CONFIGURATION">CONFIGURATION</h2>
<p>A configuration file can be in the format of either <strong>TEXT</strong> or <strong>YAML</strong> where
[TEXT][textconfig] is the easiest and most ideal solution for most users. However
<ahref="https://github.com/caronc/apprise/wiki/config_text">TEXT</a> is the easiest and most ideal solution for most users. However
<ahref="https://github.com/caronc/apprise/wiki/config_yaml">YAML</a> configuration files grants the user a bit more leverage and access
to some of the internal features of Apprise. Reguardless of which format you choose,
both provide the users the ability to leverage <strong>tagging</strong> which adds a more rich and
@ -307,8 +371,9 @@ tool simplifies to:</p>
<p>If you leveraged <ahref="https://github.com/caronc/apprise/wiki/CLI_Usage#label-leverage-tagging">tagging</a>, you can define all of Apprise Service URLs in your
configuration that you want and only specifically notify a subset of them:</p>
<pre><code>$ apprise -vv -t "Will Be Late" -b "Go ahead and make dinner without me" \
--tag=family
<pre><code>$ apprise -vv --title "Will Be Late Getting Home" \
--body "Please go ahead and make dinner without me." \
--tag=family
</code></pre>
<h2id="BUGS">BUGS</h2>
@ -316,13 +381,16 @@ configuration that you want and only specifically notify a subset of them:</p>
<p>If you find any bugs, please make them known at:
@ -15,16 +16,18 @@ Telegram, Pushbullet, Slack, Twitter, etc.
* A common and intuitive notification syntax.
* Supports the handling of images (to the notification services that will
accept them).
* It's incredibly lightweight.
* Amazing response times because all messages sent asynchronously.
## OPTIONS
The Apprise options are as follows:
`-b`, `--body=`<TEXT>:
`-b`, `--body=`<VALUE>:
Specify the message body. If no body is specified then content is read from
<stdin>.
`-t`, `--title=`<TEXT>:
`-t`, `--title=`<VALUE>:
Specify the message title. This field is complete optional.
`-c`, `--config=`<CONFIG-URL>:
@ -33,7 +36,7 @@ The Apprise options are as follows:
`-a`, `--attach=`<ATTACH-URL>:
Specify one or more file attachment locations.
`-P`, `--plugin-path=`<PLUGIN-PATH>:
`-P`, `--plugin-path=`<PATH>:
Specify a path to scan for custom notification plugin support.
You can create your own notification by simply creating a Python file
that contains the `@notify("schema")` decorator.
@ -41,18 +44,18 @@ The Apprise options are as follows:
You can optioanly chose to specify more then one **--plugin-path** (**-P**)
to increase the modules included.
`-n`, `--notification-type=`<TYPE>:
`-n`, `--notification-type=`<VALUE>:
Specify the message type (default=info). Possible values are "info",
"success", "failure", and "warning".
`-i`, `--input-format=`<FORMAT>:
`-i`, `--input-format=`<VALUE>:
Specify the input message format (default=text). Possible values are "text",
"html", and "markdown".
`-T`, `--theme=`THEME:
`-T`, `--theme=`<VALUE>:
Specify the default theme.
`-g`, `--tag=`TAG:
`-g`, `--tag=`<VALUE>:
Specify one or more tags to filter which services to notify. Use multiple
**--tag** (**-g**) entries to `OR` the tags together and comma separated
to `AND` them. If no tags are specified then all services are notified.
@ -61,7 +64,7 @@ The Apprise options are as follows:
Send notifications synchronously (one after the other) instead of
all at once.
`-R`, `--recursion-depth`:
`-R`, `--recursion-depth`<INTEGER>:
he number of recursive import entries that can be loaded from within
Apprise configuration. By default this is set to 1. If this is set to
zero, then import statements found in any configuration is ignored.
@ -75,6 +78,22 @@ The Apprise options are as follows:
sequences such as :smile: or :grin: to their respected unicode emoji
character.
`-S`, `--storage-path=`<PATH>:
Specify the path to the persistent storage caching location
`-SM`, `--storage-mode=`<MODE>:
Specify the persistent storage operational mode. Possible values are "auto",
"flush", and "memory". The default is "auto" not not specified.
`-SPD`, `--storage-prune-days=`<INTEGER>:
Define the number of days the storage prune should run using.
Setting this to zero (0) will eliminate all accumulated content. By
default this value is 30 (days).
`-SUL`, `--storage-uid-length=`<INTEGER>:
Define the number of unique characters to store persistent cache in.
By default this value is 8 (characters).
`-d`, `--dry-run`:
Perform a trial run but only prints the notification services to-be
triggered to **stdout**. Notifications are never sent using this mode.
@ -96,6 +115,32 @@ The Apprise options are as follows:
`-h`, `--help`:
Show this message and exit.
## PERSISTENT STORAGE
Persistent storage by default writes to the following location unless the environment variable `APPRISE_STORAGE_PATH` over-rides it and/or `--storage-path` (`-SP`) is specified to over-ride it:
~/.local/share/apprise/cache
To utilize the [persistent storage][pstorage] element associated with Apprise, simply
specify the keyword **storage**
$ apprise storage
The **storage** action has the following sub actions:
`list`:
List all of the detected persistent storage elements and their state
(**stale**, **active**, or **unused**). This is the default action if
nothing further is identified.
`prune`:
Removes all persistent storage that has not been referenced for more then 30
days. You can optionally set the `--storage-prune-days` to alter this
default value.
`clean`:
Removes all persistent storage reguardless of age.
## EXIT STATUS
**apprise** exits with a status of:
@ -147,6 +192,18 @@ Include an attachment:
$ apprise -vv -t "School Assignment" -b "See attached" \
--attach=Documents/FinalReport.docx
List all of the notifications loaded:
$ apprise --dry-run --tag=all
List all of the details around the current persistent storage setup:
$ apprise storage list
Prune all persistent storage that has not been referenced for at least 10 days or more
$ apprise storage prune --storage-prune-days=10
## CUSTOM PLUGIN/NOTIFICATIONS
Apprise can additionally allow you to define your own custom **schema://**
entries that you can trigger on and call services you've defined.
Chris Caron
3 months ago
committed by