From 06497540966f03214bdc6dd63aa7c41d034ffc6d Mon Sep 17 00:00:00 2001 From: Chris Caron Date: Mon, 22 Feb 2021 11:36:19 -0500 Subject: [PATCH] better escape interpretation for Python 2.7.5 (EL7) users --- apprise/Apprise.py | 29 ++++++- packaging/man/apprise.1 | 164 +++++++++++++++++++++++++-------------- packaging/man/apprise.md | 150 ++++++++++++++++++++++------------- test/test_escapes.py | 56 ++++++++++++- 4 files changed, 282 insertions(+), 117 deletions(-) diff --git a/apprise/Apprise.py b/apprise/Apprise.py index ba3b8914..b655f176 100644 --- a/apprise/Apprise.py +++ b/apprise/Apprise.py @@ -330,6 +330,15 @@ class Apprise(object): if not (title or body): return False + if six.PY2: + # Python 2.7.x Unicode Character Handling + # Ensure we're working with utf-8 + if isinstance(title, unicode): # noqa: F821 + title = title.encode('utf-8') + + if isinstance(body, unicode): # noqa: F821 + body = body.encode('utf-8') + # Tracks conversions conversion_map = dict() @@ -417,25 +426,37 @@ class Apprise(object): # try: - # Added overhead requrired due to Python 3 Encoding Bug - # idenified here: https://bugs.python.org/issue21331 + # Added overhead required due to Python 3 Encoding Bug + # identified here: https://bugs.python.org/issue21331 conversion_map[server.notify_format] = \ conversion_map[server.notify_format]\ .encode('ascii', 'backslashreplace')\ .decode('unicode-escape') + except UnicodeDecodeError: # pragma: no cover + # This occurs using a very old verion of Python 2.7 such + # as the one that ships with CentOS/RedHat 7.x (v2.7.5). + conversion_map[server.notify_format] = \ + conversion_map[server.notify_format] \ + .decode('string_escape') + except AttributeError: # Must be of string type logger.error('Failed to escape message body') return False try: - # Added overhead requrired due to Python 3 Encoding Bug - # idenified here: https://bugs.python.org/issue21331 + # Added overhead required due to Python 3 Encoding Bug + # identified here: https://bugs.python.org/issue21331 title = title\ .encode('ascii', 'backslashreplace')\ .decode('unicode-escape') + except UnicodeDecodeError: # pragma: no cover + # This occurs using a very old verion of Python 2.7 such + # as the one that ships with CentOS/RedHat 7.x (v2.7.5). + title = title.decode('string_escape') + except AttributeError: # Must be of string type logger.error('Failed to escape message title') diff --git a/packaging/man/apprise.1 b/packaging/man/apprise.1 index 1818fb1d..64f32258 100644 --- a/packaging/man/apprise.1 +++ b/packaging/man/apprise.1 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "APPRISE" "1" "August 2020" "" "" +.TH "APPRISE" "1" "February 2021" "ff" "" . .SH "NAME" \fBapprise\fR \- Push Notifications that work with just about every platform! @@ -28,71 +28,73 @@ Supports the handling of images (to the notification services that will accept t .SH "OPTIONS" The Apprise options are as follows: . -.TP -\fB\-b\fR, \fB\-\-body=\fR\fITEXT\fR -Specify the message body\. If no body is specified then content is read from \fIstdin\fR\. +.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\. . -.TP -\fB\-t\fR, \fB\-\-title=\fR\fITEXT\fR -Specify the message title\. This field is complete optional\. +.P +\fB\-t\fR, \fB\-\-title=\fR\fITEXT\fR: Specify the message title\. This field is complete optional\. . -.TP -\fB\-c\fR, \fB\-\-config=\fR\fICONFIG\-URL\fR -Specify one or more configuration locations\. +.P +\fB\-c\fR, \fB\-\-config=\fR\fICONFIG\-URL\fR: Specify one or more configuration locations\. . -.TP -\fB\-a\fR, \fB\-\-attach=\fR\fIATTACH\-URL\fR -Specify one or more file attachment locations\. +.P +\fB\-a\fR, \fB\-\-attach=\fR\fIATTACH\-URL\fR: Specify one or more file attachment locations\. . -.TP -\fB\-n\fR, \fB\-\-notification\-type=\fR\fITYPE\fR -Specify the message type (default=info)\. Possible values are "info", "success", "failure", and "warning"\. +.P +\fB\-n\fR, \fB\-\-notification\-type=\fR\fITYPE\fR: Specify the message type (default=info)\. Possible values are "info", "success", "failure", and "warning"\. . -.TP -\fB\-i\fR, \fB\-\-input\-format=\fR\fIFORMAT\fR -Specify the input message format (default=text)\. Possible values are "text", "html", and "markdown"\. +.P +\fB\-i\fR, \fB\-\-input\-format=\fR\fIFORMAT\fR: Specify the input message format (default=text)\. Possible values are "text", "html", and "markdown"\. . -.TP -\fB\-T\fR, \fB\-\-theme=\fRTHEME -Specify the default theme\. +.P +\fB\-T\fR, \fB\-\-theme=\fRTHEME: Specify the default theme\. . -.TP -\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\. +.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\. . -.TP -\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 +\fB\-Da\fR, \fB\-\-disable\-async\fR: Send notifications synchronously (one after the other) instead of all at once\. . -.TP -\fB\-v\fR, \fB\-\-verbose\fR -The more of these you specify, the more verbose the output is\. +.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\. . -.TP -\fB\-Da\fR, \fB\-\-disable\-async\fR -Send notifications synchronously (one after the other) instead of all at once\. +.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 . -.TP -\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\. +.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\. . -.TP -\fB\-D\fR, \fB\-\-debug\fR -A debug mode; useful for troubleshooting\. +.P +return characters prior to the delivery of the notification\. . -.TP -\fB\-V\fR, \fB\-\-version\fR -Display the apprise version and exit\. +.P +\fB\-v\fR, \fB\-\-verbose\fR: The more of these you specify, the more verbose the output is\. e\.g: \-vvvv . -.TP -\fB\-\-help\fR -Show this message and exit\. +.P +\fB\-D\fR, \fB\-\-debug\fR: A debug mode; useful for troubleshooting\. . -.SH "EXIT STATUS" -\fBapprise\fR exits with a status 0 if all notifications were sent successfully otherwise \fBapprise\fR returns a value of 1\. \fBapprise\fR returns a value of 2 if there was an error specified on the command line (such as not providing an valid argument)\. +.P +\fB\-V\fR, \fB\-\-version\fR: Display the apprise version and exit\. . .P -\fBapprise\fR exits with a status of 3 if there were no notifcations sent due (as a result of end user actions)\. This occurs in the case where you have assigned one or more tags to all of the Apprise URLs being notified and did not match any when actually executing the \fBapprise\fR tool\. This can also occur if you specified a tag that has not been assigned to anything defined in your configuration\. +\fB\-h\fR, \fB\-\-help\fR: Show this message and exit\. +. +.SH "EXIT STATUS" +\fBapprise\fR exits with a status of: +. +.IP "\(bu" 4 +\fB0\fR if all of the notifications were sent successfully\. +. +.IP "\(bu" 4 +\fB1\fR if one or more notifications could not be sent\. +. +.IP "\(bu" 4 +\fB2\fR if there was an error specified on the command line such as not providing an valid argument\. +. +.IP "\(bu" 4 +\fB3\fR if there was one or more Apprise Service URLs successfully loaded but none could be notified due to user filtering (via tags)\. +. +.IP "" 0 . .SH "SERVICE URLS" There are to many service URL and combinations to list here\. It\'s best to visit the Apprise GitHub page \fIhttps://github\.com/caronc/apprise/wiki#notification\-services\fR and see what\'s available\. @@ -104,9 +106,9 @@ Send a notification to as many servers as you want to specify as you can easily . .nf -$ apprise \-vv \-t \'my title\' \-b \'my notification body\' \e - \'mailto://myemail:mypass@gmail\.com\' \e - \'pbul://o\.gn5kj6nfhv736I7jC3cj3QLRiyhgl98b\' +$ apprise \-vv \-t "my title" \-b "my notification body" \e + "mailto://myemail:mypass@gmail\.com" \e + "pbul://o\.gn5kj6nfhv736I7jC3cj3QLRiyhgl98b" . .fi . @@ -119,8 +121,8 @@ If you don\'t specify a \fB\-\-body\fR (\fB\-b\fR) then stdin is used allowing y . .nf -$ cat /proc/cpuinfo | apprise \-vv \-t \'cpu info\' \e - \'mailto://myemail:mypass@gmail\.com\' +$ cat /proc/cpuinfo | apprise \-vv \-t "cpu info" \e + "mailto://myemail:mypass@gmail\.com" . .fi . @@ -133,7 +135,7 @@ Load in a configuration file which identifies all of your notification service U . .nf -$ apprise \-vv \-t \'my title\' \-b \'my notification body\' \e +$ apprise \-vv \-t "my title" \-b "my notification body" \e \-\-config=~/apprise\.yml . .fi @@ -147,7 +149,7 @@ Load in a configuration file from a remote server that identifies all of your no . .nf -$ apprise \-vv \-t \'my title\' \-b \'my notification body\' \e +$ apprise \-vv \-t "my title" \-b "my notification body" \e \-\-config=https://localhost/my/apprise/config \e \-t devops . @@ -162,15 +164,61 @@ Include an attachment: . .nf -$ apprise \-vv \-t \'School Assignment\' \-b \'See attached\' \e +$ apprise \-vv \-t "School Assignment" \-b "See attached" \e \-\-attach=Documents/FinalReport\.docx . .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\. +. +.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 +. +.nf + +$ ~/\.apprise +$ ~/\.apprise\.yml +$ ~/\.config/apprise +$ ~/\.config/apprise\.yml +. +.fi +. +.IP "" 0 +. +.P +If a default configuration file is referenced in any way by the \fBapprise\fR tool, you no longer need to provide it a Service URL\. Usage of the \fBapprise\fR tool simplifies to: +. +.IP "" 4 +. +.nf + +$ apprise \-vv \-t "my title" \-b "my notification body" +. +.fi +. +.IP "" 0 +. +.P +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 +. +.fi +. +.IP "" 0 +. .SH "BUGS" If you find any bugs, please make them known at: \fIhttps://github\.com/caronc/apprise/issues\fR . .SH "COPYRIGHT" -Apprise is Copyright (C) 2020 Chris Caron \fIlead2gold@gmail\.com\fR +Apprise is Copyright (C) 2021 Chris Caron \fIlead2gold@gmail\.com\fR diff --git a/packaging/man/apprise.md b/packaging/man/apprise.md index 34eb3eb1..1f4dd8dc 100644 --- a/packaging/man/apprise.md +++ b/packaging/man/apprise.md @@ -20,68 +20,76 @@ Telegram, Pushbullet, Slack, Twitter, etc. The Apprise options are as follows: - * `-b`, `--body=`: - Specify the message body. If no body is specified then content is read from - . + `-b`, `--body=`: + Specify the message body. If no body is specified then content is read from + . - * `-t`, `--title=`: - Specify the message title. This field is complete optional. + `-t`, `--title=`: + Specify the message title. This field is complete optional. - * `-c`, `--config=`: - Specify one or more configuration locations. + `-c`, `--config=`: + Specify one or more configuration locations. - * `-a`, `--attach=`: - Specify one or more file attachment locations. + `-a`, `--attach=`: + Specify one or more file attachment locations. - * `-n`, `--notification-type=`: - Specify the message type (default=info). Possible values are "info", - "success", "failure", and "warning". + `-n`, `--notification-type=`: + Specify the message type (default=info). Possible values are "info", + "success", "failure", and "warning". - * `-i`, `--input-format=`: - Specify the input message format (default=text). Possible values are "text", - "html", and "markdown". + `-i`, `--input-format=`: + Specify the input message format (default=text). Possible values are "text", + "html", and "markdown". - * `-T`, `--theme=`THEME: - Specify the default theme. + `-T`, `--theme=`THEME: + Specify the default theme. - * `-g`, `--tag=`TAG: - 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. + `-g`, `--tag=`TAG: + 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. - * `-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. + `-Da`, `--disable-async`: + Send notifications synchronously (one after the other) instead of + all at once. - * `-v`, `--verbose`: - The more of these you specify, the more verbose the output is. + `-R`, `--recursion-depth`: + 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. - * `-Da`, `--disable-async`: - Send notifications synchronously (one after the other) instead of - all at once. + `-e`, `--interpret-escapes` + Enable interpretation of backslash escapes. For example, this would convert + sequences such as \n and \r to their respected ascii new-line and carriage - * `-R`, `--recursion-depth`: - 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. + `-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. - * `-D`, `--debug`: - A debug mode; useful for troubleshooting. + return characters prior to the delivery of the notification. - * `-V`, `--version`: - Display the apprise version and exit. + `-v`, `--verbose`: + The more of these you specify, the more verbose the output is. e.g: -vvvv - * `--help`: - Show this message and exit. + `-D`, `--debug`: + A debug mode; useful for troubleshooting. -## EXIT STATUS + `-V`, `--version`: + Display the apprise version and exit. + + `-h`, `--help`: + Show this message and exit. -**apprise** exits with a status 0 if all notifications were sent successfully otherwise **apprise** returns a value of 1. **apprise** returns a value of 2 if -there was an error specified on the command line (such as not providing an valid -argument). +## EXIT STATUS -**apprise** exits with a status of 3 if there were no notifcations sent due (as a result of end user actions). This occurs in the case where you have assigned one or more tags to all of the Apprise URLs being notified and did not match any when actually executing the **apprise** tool. This can also occur if you specified a tag that has not been assigned to anything defined in your configuration. +**apprise** exits with a status of: +* **0** if all of the notifications were sent successfully. +* **1** if one or more notifications could not be sent. +* **2** if there was an error specified on the command line such as not + providing an valid argument. +* **3** if there was one or more Apprise Service URLs successfully + loaded but none could be notified due to user filtering (via tags). ## SERVICE URLS @@ -95,34 +103,70 @@ visit the [Apprise GitHub page][serviceurls] and see what's available. Send a notification to as many servers as you want to specify as you can easily chain them together: - $ apprise -vv -t 'my title' -b 'my notification body' \ - 'mailto://myemail:mypass@gmail.com' \ - 'pbul://o.gn5kj6nfhv736I7jC3cj3QLRiyhgl98b' + $ apprise -vv -t "my title" -b "my notification body" \ + "mailto://myemail:mypass@gmail.com" \ + "pbul://o.gn5kj6nfhv736I7jC3cj3QLRiyhgl98b" If you don't specify a **--body** (**-b**) then stdin is used allowing you to use the tool as part of your every day administration: - $ cat /proc/cpuinfo | apprise -vv -t 'cpu info' \ - 'mailto://myemail:mypass@gmail.com' + $ cat /proc/cpuinfo | apprise -vv -t "cpu info" \ + "mailto://myemail:mypass@gmail.com" Load in a configuration file which identifies all of your notification service URLs and notify them all: - $ apprise -vv -t 'my title' -b 'my notification body' \ + $ apprise -vv -t "my title" -b "my notification body" \ --config=~/apprise.yml Load in a configuration file from a remote server that identifies all of your notification service URLs and only notify the ones tagged as _devops_. - $ apprise -vv -t 'my title' -b 'my notification body' \ + $ apprise -vv -t "my title" -b "my notification body" \ --config=https://localhost/my/apprise/config \ -t devops Include an attachment: - $ apprise -vv -t 'School Assignment' -b 'See attached' \ + $ apprise -vv -t "School Assignment" -b "See attached" \ --attach=Documents/FinalReport.docx +## CONFIGURATION + +A configuration file can be in the format of either **TEXT** or **YAML** where +[TEXT][textconfig] is the easiest and most ideal solution for most users. However +[YAML][yamlconfig] 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 **tagging** which adds a more rich and +powerful notification environment. + +Configuration files can be directly referenced via **apprise** when referencing +the `--config=` (`-c`) 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 `http://` or `https://`. By default **apprise** looks +in the following local locations for configuration files and loads them: + + $ ~/.apprise + $ ~/.apprise.yml + $ ~/.config/apprise + $ ~/.config/apprise.yml + +If a default configuration file is referenced in any way by the **apprise** +tool, you no longer need to provide it a Service URL. Usage of the **apprise** +tool simplifies to: + + $ apprise -vv -t "my title" -b "my notification body" + +If you leveraged [tagging][tagging], you can define all of Apprise Service URLs in your +configuration that you want and only specifically notify a subset of them: + + $ apprise -vv -t "Will Be Late" -b "Go ahead and make dinner without me" \ + --tag=family + +[yamlconfig]: https://github.com/caronc/apprise/wiki/config_yaml +[tagging]: https://github.com/caronc/apprise/wiki/CLI_Usage#label-leverage-tagging + + ## BUGS If you find any bugs, please make them known at: @@ -130,4 +174,4 @@ If you find any bugs, please make them known at: ## COPYRIGHT -Apprise is Copyright (C) 2020 Chris Caron +Apprise is Copyright (C) 2021 Chris Caron diff --git a/test/test_escapes.py b/test/test_escapes.py index a647df86..46640205 100644 --- a/test/test_escapes.py +++ b/test/test_escapes.py @@ -249,8 +249,60 @@ def test_apprise_escaping_py2(mock_post): # Verify our content was escaped correctly assert mock_post.call_count == 1 result = loads(mock_post.call_args_list[0][1]['data']) - assert result['title'] == 'دعونا نجعل العالم مكانا أفضل.' - assert result['message'] == 'Egy sor kódot egyszerre.' + + expected = 'دعونا نجعل العالم مكانا أفضل.' + assert result['title'] in ( + expected, + # Older versions of Python (such as 2.7.5) provide this value as + # a type unicode. This specifically happens when building RPMs + # for RedHat/CentOS 7. The internal RPM unit tests fail without this: + expected.decode('utf-8'), + ) + + expected = 'Egy sor kódot egyszerre.' + assert result['message'] in ( + expected, + # Older versions of Python (such as 2.7.5) provide this value as + # a type unicode. This specifically happens when building RPMs + # for RedHat/CentOS 7. The internal RPM unit tests fail without this: + expected.decode('utf-8'), + ) + + # Reset our status + mock_post.reset_mock() + + # Use unicode characters + assert a.notify( + # Google Translated to Arabic: "Let's make the world a better place." + title='دعونا نجعل العالم مكانا أفضل.\\r\\t\\t\\n\\r\\n'.decode( + 'utf-8'), + # Google Translated to Hungarian: "One line of code at a time.' + body='Egy sor kódot egyszerre.\\r\\n\\r\\r\\n'.decode( + 'utf-8'), + # Our Escape Flag + interpret_escapes=True) + + # Verify our content was escaped correctly + assert mock_post.call_count == 1 + result = loads(mock_post.call_args_list[0][1]['data']) + + expected = 'دعونا نجعل العالم مكانا أفضل.' + assert result['title'] in ( + expected, + # Older versions of Python (such as 2.7.5) provide this value as + # a type unicode. This specifically happens when building RPMs + # for RedHat/CentOS 7. The internal RPM unit tests fail without this: + expected.decode('utf-8'), + ) + + expected = 'Egy sor kódot egyszerre.' + assert result['message'] in ( + expected, + # Older versions of Python (such as 2.7.5) provide this value as + # a type unicode. This specifically happens when building RPMs + # for RedHat/CentOS 7. The internal RPM unit tests fail without this: + expected.decode('utf-8'), + ) # Error handling #