.\" Man page generated from reStructuredText. . .TH "GNTP" "1" "Nov 25, 2019" "1.0.3" "Growl Notification Transport Protocol Python Bindings" .SH NAME gntp \- GNTP Documentation . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .sp Lower level classes for those who want more control in sending messages .SH EXCEPTIONS .INDENT 0.0 .TP .B exception gntp.errors.AuthError .UNINDENT .INDENT 0.0 .TP .B exception gntp.errors.ParseError .UNINDENT .INDENT 0.0 .TP .B exception gntp.errors.UnsupportedError .UNINDENT .SH GNTP MESSAGES .sp Classes representing each of the GNTP message types .INDENT 0.0 .TP .B class gntp.core.GNTPRegister(data=None, password=None) Represents a GNTP Registration Command .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdata\fP (\fIstring\fP) \-\- (Optional) See decode() .IP \(bu 2 \fBpassword\fP (\fIstring\fP) \-\- (Optional) Password to use while encoding/decoding messages .UNINDENT .UNINDENT .INDENT 7.0 .TP .B add_notification(name, enabled=True) Add new Notification to Registration message .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fIstring\fP) \-\- Notification Name .IP \(bu 2 \fBenabled\fP (\fIboolean\fP) \-\- Enable this notification by default .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B add_resource(data) Add binary resource .INDENT 7.0 .TP .B Parameters \fBdata\fP (\fIstring\fP) \-\- Binary Data .UNINDENT .UNINDENT .INDENT 7.0 .TP .B decode(data, password) Decode existing GNTP Registration message .INDENT 7.0 .TP .B Parameters \fBdata\fP (\fIstring\fP) \-\- Message to decode .UNINDENT .UNINDENT .INDENT 7.0 .TP .B encode() Encode a GNTP Registration Message .INDENT 7.0 .TP .B Return string Encoded GNTP Registration message. Returned as a byte string .UNINDENT .UNINDENT .INDENT 7.0 .TP .B set_password(password, encryptAlgo=\(aqMD5\(aq) Set a password for a GNTP Message .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpassword\fP (\fIstring\fP) \-\- Null to clear password .IP \(bu 2 \fBencryptAlgo\fP (\fIstring\fP) \-\- Supports MD5, SHA1, SHA256, SHA512 .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B validate() Validate required headers and validate notification headers .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class gntp.core.GNTPNotice(data=None, app=None, name=None, title=None, password=None) Represents a GNTP Notification Command .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdata\fP (\fIstring\fP) \-\- (Optional) See decode() .IP \(bu 2 \fBapp\fP (\fIstring\fP) \-\- (Optional) Set Application\-Name .IP \(bu 2 \fBname\fP (\fIstring\fP) \-\- (Optional) Set Notification\-Name .IP \(bu 2 \fBtitle\fP (\fIstring\fP) \-\- (Optional) Set Notification Title .IP \(bu 2 \fBpassword\fP (\fIstring\fP) \-\- (Optional) Password to use while encoding/decoding messages .UNINDENT .UNINDENT .INDENT 7.0 .TP .B add_resource(data) Add binary resource .INDENT 7.0 .TP .B Parameters \fBdata\fP (\fIstring\fP) \-\- Binary Data .UNINDENT .UNINDENT .INDENT 7.0 .TP .B decode(data, password) Decode existing GNTP Notification message .INDENT 7.0 .TP .B Parameters \fBdata\fP (\fIstring\fP) \-\- Message to decode. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B encode() Encode a generic GNTP Message .INDENT 7.0 .TP .B Return string GNTP Message ready to be sent. Returned as a byte string .UNINDENT .UNINDENT .INDENT 7.0 .TP .B set_password(password, encryptAlgo=\(aqMD5\(aq) Set a password for a GNTP Message .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpassword\fP (\fIstring\fP) \-\- Null to clear password .IP \(bu 2 \fBencryptAlgo\fP (\fIstring\fP) \-\- Supports MD5, SHA1, SHA256, SHA512 .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B validate() Verify required headers .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class gntp.core.GNTPSubscribe(data=None, password=None) Represents a GNTP Subscribe Command .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdata\fP (\fIstring\fP) \-\- (Optional) See decode() .IP \(bu 2 \fBpassword\fP (\fIstring\fP) \-\- (Optional) Password to use while encoding/decoding messages .UNINDENT .UNINDENT .INDENT 7.0 .TP .B add_resource(data) Add binary resource .INDENT 7.0 .TP .B Parameters \fBdata\fP (\fIstring\fP) \-\- Binary Data .UNINDENT .UNINDENT .INDENT 7.0 .TP .B decode(data, password=None) Decode GNTP Message .INDENT 7.0 .TP .B Parameters \fBdata\fP (\fIstring\fP) \-\- .UNINDENT .UNINDENT .INDENT 7.0 .TP .B encode() Encode a generic GNTP Message .INDENT 7.0 .TP .B Return string GNTP Message ready to be sent. Returned as a byte string .UNINDENT .UNINDENT .INDENT 7.0 .TP .B set_password(password, encryptAlgo=\(aqMD5\(aq) Set a password for a GNTP Message .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpassword\fP (\fIstring\fP) \-\- Null to clear password .IP \(bu 2 \fBencryptAlgo\fP (\fIstring\fP) \-\- Supports MD5, SHA1, SHA256, SHA512 .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B validate() Verify required headers .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class gntp.core.GNTPOK(data=None, action=None) Represents a GNTP OK Response .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdata\fP (\fIstring\fP) \-\- (Optional) See _GNTPResponse.decode() .IP \(bu 2 \fBaction\fP (\fIstring\fP) \-\- (Optional) Set type of action the OK Response is for .UNINDENT .UNINDENT .INDENT 7.0 .TP .B add_resource(data) Add binary resource .INDENT 7.0 .TP .B Parameters \fBdata\fP (\fIstring\fP) \-\- Binary Data .UNINDENT .UNINDENT .INDENT 7.0 .TP .B decode(data, password=None) Decode GNTP Message .INDENT 7.0 .TP .B Parameters \fBdata\fP (\fIstring\fP) \-\- .UNINDENT .UNINDENT .INDENT 7.0 .TP .B encode() Encode a generic GNTP Message .INDENT 7.0 .TP .B Return string GNTP Message ready to be sent. Returned as a byte string .UNINDENT .UNINDENT .INDENT 7.0 .TP .B set_password(password, encryptAlgo=\(aqMD5\(aq) Set a password for a GNTP Message .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpassword\fP (\fIstring\fP) \-\- Null to clear password .IP \(bu 2 \fBencryptAlgo\fP (\fIstring\fP) \-\- Supports MD5, SHA1, SHA256, SHA512 .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B validate() Verify required headers .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class gntp.core.GNTPError(data=None, errorcode=None, errordesc=None) Represents a GNTP Error response .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdata\fP (\fIstring\fP) \-\- (Optional) See _GNTPResponse.decode() .IP \(bu 2 \fBerrorcode\fP (\fIstring\fP) \-\- (Optional) Error code .IP \(bu 2 \fBerrordesc\fP (\fIstring\fP) \-\- (Optional) Error Description .UNINDENT .UNINDENT .INDENT 7.0 .TP .B add_resource(data) Add binary resource .INDENT 7.0 .TP .B Parameters \fBdata\fP (\fIstring\fP) \-\- Binary Data .UNINDENT .UNINDENT .INDENT 7.0 .TP .B decode(data, password=None) Decode GNTP Message .INDENT 7.0 .TP .B Parameters \fBdata\fP (\fIstring\fP) \-\- .UNINDENT .UNINDENT .INDENT 7.0 .TP .B encode() Encode a generic GNTP Message .INDENT 7.0 .TP .B Return string GNTP Message ready to be sent. Returned as a byte string .UNINDENT .UNINDENT .INDENT 7.0 .TP .B set_password(password, encryptAlgo=\(aqMD5\(aq) Set a password for a GNTP Message .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpassword\fP (\fIstring\fP) \-\- Null to clear password .IP \(bu 2 \fBencryptAlgo\fP (\fIstring\fP) \-\- Supports MD5, SHA1, SHA256, SHA512 .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B validate() Verify required headers .UNINDENT .UNINDENT .SH HELPER FUNCTIONS .INDENT 0.0 .TP .B gntp.core.parse_gntp(data, password=None) Attempt to parse a message as a GNTP message .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdata\fP (\fIstring\fP) \-\- Message to be parsed .IP \(bu 2 \fBpassword\fP (\fIstring\fP) \-\- Optional password to be used to verify the message .UNINDENT .UNINDENT .UNINDENT .sp Python bindings for the \fI\%Growl Notification Transport Protocol\fP .sp Bugs can be reported at the \fI\%GitHub issue tracker\fP .SH SIMPLE MESSAGE SENDING .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C from gntp.notifier import mini # Send a simple growl message with mostly default values mini("Here\(aqs a quick message", callback="http://github.com/") .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B gntp.notifier.mini(description, applicationName=\(aqPythonMini\(aq, noteType=\(aqMessage\(aq, title=\(aqMini Message\(aq, applicationIcon=None, hostname=\(aqlocalhost\(aq, password=None, port=23053, sticky=False, priority=None, callback=None, notificationIcon=None, identifier=None, notifierFactory=) Single notification function .sp Simple notification function in one line. Has only one required parameter and attempts to use reasonable defaults for everything else :param string description: Notification message .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 For now, only URL callbacks are supported. In the future, the callback argument will also support a function .UNINDENT .UNINDENT .UNINDENT .SH DETAILED MESSAGE SENDING .INDENT 0.0 .TP .B class gntp.notifier.GrowlNotifier(applicationName=\(aqPython GNTP\(aq, notifications=[], defaultNotifications=None, applicationIcon=None, hostname=\(aqlocalhost\(aq, password=None, port=23053) Helper class to simplfy sending Growl messages .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBapplicationName\fP (\fIstring\fP) \-\- Sending application name .IP \(bu 2 \fBnotification\fP (\fIlist\fP) \-\- List of valid notifications .IP \(bu 2 \fBdefaultNotifications\fP (\fIlist\fP) \-\- List of notifications that should be enabled by default .IP \(bu 2 \fBapplicationIcon\fP (\fIstring\fP) \-\- Icon URL .IP \(bu 2 \fBhostname\fP (\fIstring\fP) \-\- Remote host .IP \(bu 2 \fBport\fP (\fIinteger\fP) \-\- Remote port .UNINDENT .UNINDENT .UNINDENT .sp The GrowlNotifier class is intended to mostly mirror the older python bindings for growl .INDENT 0.0 .TP .B GrowlNotifier.register() Send GNTP Registration .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Before sending notifications to Growl, you need to have sent a registration message at least once .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B GrowlNotifier.notify(noteType, title, description, icon=None, sticky=False, priority=None, callback=None, identifier=None, custom={}) Send a GNTP notifications .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Must have registered with growl beforehand or messages will be ignored .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnoteType\fP (\fIstring\fP) \-\- One of the notification names registered earlier .IP \(bu 2 \fBtitle\fP (\fIstring\fP) \-\- Notification title (usually displayed on the notification) .IP \(bu 2 \fBdescription\fP (\fIstring\fP) \-\- The main content of the notification .IP \(bu 2 \fBicon\fP (\fIstring\fP) \-\- Icon URL path .IP \(bu 2 \fBsticky\fP (\fIboolean\fP) \-\- Sticky notification .IP \(bu 2 \fBpriority\fP (\fIinteger\fP) \-\- Message priority level from \-2 to 2 .IP \(bu 2 \fBcallback\fP (\fIstring\fP) \-\- URL callback .IP \(bu 2 \fBcustom\fP (\fIdict\fP) \-\- Custom attributes. Key names should be prefixed with X\- according to the spec but this is not enforced by this class .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 For now, only URL callbacks are supported. In the future, the callback argument will also support a function .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B GrowlNotifier.subscribe(id, name, port) Send a Subscribe request to a remote machine .UNINDENT .SH COMPLETE EXAMPLE .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import gntp.notifier # Simple "fire and forget" notification gntp.notifier.mini("Here\(aqs a quick message") # More complete example growl = gntp.notifier.GrowlNotifier( applicationName = "My Application Name", notifications = ["New Updates","New Messages"], defaultNotifications = ["New Messages"], # hostname = "computer.example.com", # Defaults to localhost # password = "abc123" # Defaults to a blank password ) growl.register() # Send one message growl.notify( noteType = "New Messages", title = "You have a new message", description = "A longer message description", icon = "http://example.com/icon.png", sticky = False, priority = 1, ) # Try to send a different type of message # This one may fail since it is not in our list # of defaultNotifications growl.notify( noteType = "New Updates", title = "There is a new update to download", description = "A longer message description", icon = "http://example.com/icon.png", sticky = False, priority = \-1, ) # Send the image with the growl notification image = open(\(aq/path/to/icon.png\(aq, \(aqrb\(aq).read() growl.notify( noteType = "New Messages", title = "Now with icons", description = "This time we attach the image", icon = image, ) .ft P .fi .UNINDENT .UNINDENT .SH GNTP CONFIGFILE EXAMPLE .INDENT 0.0 .TP .B class gntp.config.GrowlNotifier(*args, **kwargs) ConfigParser enhanced GrowlNotifier object .sp For right now, we are only interested in letting users overide certain values from ~/.gntp .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [gntp] hostname = ? password = ? port = ? .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SH AUTHOR Paul Traylor .SH COPYRIGHT 2019, Paul Traylor .\" Generated by docutils manpage writer. .