extern/apprise
1
0
Fork 0
mirror of https://github.com/caronc/apprise.git synced 2024-12-04 22:11:25 +01:00
Code Issues Packages Projects Releases Wiki Activity

Updated config (markdown)

Chris Caron 2019-11-01 12:36:08 -04:00
parent cb55f0b10e
commit 29de83389e
1 changed files with 15 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
config.md

@ -5,6 +5,21 @@ There are 2 supported formats:
- **[[TEXT|Config_text]]**: Super basic and easy to use.
- **[[YAML|Config_yaml]]**: A wee bit more complicated (when comparing to TEXT) but offers you much more flexibility.
## Configuration URLs
Whether loading your Apprise configuration from the command line or the Python framework, they also work in the form of URLs too. This allows for URL location endpoints to extend further then what is currently already supported in the future.
Today, the following configuration URLs are supported:
| URL | Description |
| --------------- | ----------- |
| **file://** | Reads the configuration from a file accessible locally from whence the directory you're standing in when using Apprise. You can specify an absolute path such as `file:///etc/config/apprise.yaml` or a relative one such as `file://var/config.txt`.<br/><br/>The file extension associated with your configuration file plays a role in how it is interpreted. Configuration files ending with **.yml** and **.yaml** are assumed to be [YAML based](/caronc/apprise/wiki/Config_yaml) while anything else is assumed to be [TEXT based](/caronc/apprise/wiki/Config_text).<br/><br/>**Note:** The `file://` is assumed to be the default schema used in your configuration URL (even if you didn't specify it). Hence Apprise will also just accept the path as-is such as `/absolute/path/to/apprise.cfg` or `relative/path/to/config.yaml`. |
| **http://** and **https://** | Retrieves your configuration from a web server (via the HTTP protocol). An example of this might be: `http://localhost/apprise/` or `https://example.com/apprise/config`.<br/><br/>The server response plays a key role in how Apprise interprets the data content. The **Content-Type** residing in the _Response Header_ must identify contain one of the following:<br/><br/>[YAML based](/caronc/apprise/wiki/Config_yaml):<br/>- **text/yaml**<br/>- **text/x-yaml**<br/>- **application/yaml**<br/>- **application/x-yaml**<br/><br/>[TEXT based](/caronc/apprise/wiki/Config_text):<br/>- **text/plain**<br/>- **text/html**<br/><br/>**Note:** Apprise always makes a **POST** to the server(s) in question. All content returned should be encoded as **UTF-8**.
### Configuration Format Override
You can always over-ride the Apprise configuration detection process (whether it is YAML or TEXT formatted) by simply adding `?format=text` or `?format=yaml` to the end of your configuration URL. This will enforce that the configuration polled is to be interpreted in a specific way. For example:
* `file:///etc/apprise/caronc.cfg?format=yaml` : This forces what would have otherwise been interpreted as a TEXT file (because of the extension) to be interpreted as a YAML one.
* `http://localhost/my/apprise/config?format=text`: Force the processing of the web response to be a TEXT base configuration.
## CLI
To get started you can check out this [[dedicated wiki page on the CLI|CLI_Usage]].
The following lines work really with the command line:
@ -113,52 +128,6 @@ a.notify("A message!", title="An Optional Title")
a.notify(tag="devops")
```
## Apprise Config Format Detection:
### File Based (file://)
* **.yml** and **.yaml** files are assumed to be YAML
* as anything else is assumed to follow the TEXT
### Web Based (http:// and https://)
Apprise is capable of retrieving your configuration from a remote HTTP server. For HTTP requests, the **Content-Type** HTTP Header (which defines Mime Type) is very important.
Support YAML formats:
- **text/yaml**
- **text/x-yaml**
- **application/yaml**
- **application/x-yaml**
Support TEXT formats:
- **text/plain**
- **text/html**
### Force Format
You can always force the format and over-ride anything detected by adding **?format=text** or **?format=yaml** to your configuration URL.
```bash
# force a file that would have otherwise been interpreted as a text file
# to be considered a YAML one:
notify --config=https://myserver/my/apprise/config?format=yaml -b "notify everything"
```
This also applies to developers whenever they load the **AppriseConfig()** object:
```python
from apprise import Apprise
# create our object
a = Apprise()
# Our Config object while explicitly setting the format to yaml
# you can pass this in as an argument to the class to save
# ourselves from calling config.add().
config = AppriseConfig('https://myserver/yaml/?format=yaml')
# add our config object into apprise
a.add(config)
# Send our notification to all of the sites loaded from the specified
# configuration website
a.notify("hello world!")
```
## :label: Tagging from the CLI:
Tagging (with the **--tag=** (or **-g**) allows you to only notify entries from the configuration you defined that you want to. You could define hundreds of entries and through tagging, just notify a few (or if any at all).