Version 1.0 completed

5 files changed, 185 insertions, 15 deletions

diff --git a/INSTALL b/INSTALL
index 9ca334f..2749b34 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,3 +1,98 @@
 Installation Instructions
----------------------------------------
+-------------------------
 
+Refer to README for a basic information about the differents BEINC components
+and their software requirements!
+
+
+Installing the dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+
+Gentoo GNU/Linux 2013, 2014
+..........................
+
+# emerge -va dev-python/pyopenssl dev-python/cherrypy dev-python/notify-python dev-python/pyosd 
+
+
+Ubuntu GNU/Linux
+................
+
+# apt-get install python-openssl python-cherrypy python-notify2 python-pyosd 
+
+
+FreeBSD 9, 10
+.............
+
+# cd /usr/ports/security/py-openssl
+# make install clean
+
+# cd /usr/ports/www/py-cherrypy
+# make install clean
+
+# cd /usr/ports/devel/py-notify
+# make install clean
+
+# cd /usr/ports/misc/py-osd
+# make install clean
+
+
+Intallation using virtualenv and pip
+....................................
+
+Very often you are not the administrator of the server hosting your BEINC server
+This is where virtualenv may become handy (provided that it has been installed):
+$ virtualenv beinc_installation
+$ cd beinc_installation
+$ source bin/activate
+$ pip install cherrypy
+$ pip install pyopenssl
+$ cd beinc-<version>
+$ ./beinc_server.py -h
+
+
+Installing and setting up BEINC
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Unpack the latest version of BEINC
+$ tar zxvf beinc-<version>.tar.gz
+
+$cd beinc-<version>
+Read the README file
+
+You should now have a basic understanding about the different BEINC components
+and how they interact with each other.
+beinc_server.py and beinc_weechat.py are using a .json configuration file.
+Read beinc_config_sample.json.readme where every configuration option is explined.
+Decide on a use-strategy and place the different components to their locations:
+
+beinc_server.py:
+Create a configuration file based on beinc_config_sample.json, defining your instances
+Start the BEINC server:
+$ ./beinc_server.py -H 10.0.0.44 -p 9678
+The example loads the server listening on 10.0.0.44, port 9678 using the default
+~/.beinc_server.json as a configuration file  
+
+beinc_poller.py:
+$ ./beinc_poller.py -h
+The example lists all available command options
+$ ./beinc_poller.py -t 10 -f 7 --cert-file /home/sgs/weechat_cert.crt \
+  -P /home/sgs/.weechat_beinc_passwd https://10.0.0.44:9678/pull/weechat
+Starts polling from the instance (target) defined above,
+defining an OSD timeout of 10 seconds, polling frequency of 7 seconds,
+checking whether the server's SSL certificate was signed (issued) by /home/sgs/weechat_cert.crt,
+extracting the target's password from /home/sgs/.weechat_beinc_passwd
+
+beinc_generic_client.py:
+$ ./beinc_generic_client.py -h
+The example lists all available command options
+
+beinc_weechat.py:
+Create a configuration file based on beinc_config_sample.json, defining your targets
+and copy it (or symlink it) to ~/<weechat-dir>/beinc_weechat.json
+(weechat-dir is usually ~/.weechat)
+Copy (or symlink) beinc_weechat.py to ~/<weechat-dir>/python/autoload/
+Load the script in Weechat by typing: /python load beinc_weechat.py
+Make sure that all your targets look as they should: /beinc target list
+Test if your targets are displaying / relaying your messages: /beinc broadcast Test
diff --git a/README b/README
index 47bd797..4115d7d 100644
--- a/README
+++ b/README
@@ -27,6 +27,9 @@ beinc_generic_client.py - a simple client used to push notification messages
 Why should I use BEINC and what has it done for me lately?
 ----------------------------------------------------------
 
+BEINC is a free-software, licensed under the GPL3. It gives you the freedoms
+of using it, studying it and modifying it.
+
 BEINC is designed to assist you two common scenarios. 
 As an example we will consider the case of an IRC cliet, although BEINC can be
 used by any client that conforms with BEINC's "messaging protocol".
@@ -35,9 +38,15 @@ We have the common situation where a user is accessing an IRC client located on
 a different computer (typically: weechat, irssi, etc. running on a remote server)
 The IRC client receives a private message (or any event that requires the user's
 attention) and the user has to be notified.
+No matter which of the two scenarios applies to your needs, you should start by
+ - setting up a BEINC client similar to beinc_generic_client.py on the server
+   If you are running weechat >=0.4.0, this version of BEINC comes with 
+   a complete weechat BEINC-client: beinc_weechat.py
+   Configure the client to send notifications to the beinc_server.py
+N.B. Using encryption is important in these days and age.
 
 Scenario one: 
-The user's computer can be reached from the server running the IRC client.
+The user's computer can be reached by the server running the IRC client.
 If the server (running the IRC client) is able to connect to 
 a specified TCP port on the user's computer, this is sufficient for BEINC to
 directly notify the user. Solution:
@@ -45,25 +54,44 @@ directly notify the user. Solution:
    notification-message should be displayed). Define an unprivileged port for 
    beinc_server.py to listen on and enable its OSD capabilities 
    (through pynotify and/or pyosd)
- - set up a BEINC client similar to beinc_generic_client.py on the server
-   If you are running weechat >=0.4.0, this version of BEINC comes with 
-   a complete weechat BEINC-client: beinc_weechat.py
-   Configure the client to send notifications to the beinc_server.py
 
 Scenario two:
+The user's computer can NOT be reached by the server running the IRC client.
+This scenario is typical for users that are working on computers that can not
+be reached from outside.
+Solution:
+ - find a server that can be reached by the server running the IRC client.
+ - set up the beinc_server.py on it. No OSD capabilities are needed (no X11).
+   Define instance(s) for queueing. Define a queue size 
+   (how many notifications to store) for each of them.
+ - set up beinc_poller.py on the desktop workstation (the computer where the
+   notification-message should be displayed).
+   beinc_poller.py should be able to access the server running beinc_server.py
+   Polling interval of 5 seconds should be enough for most users.
 
+Read beinc_config_sample.json.readme for details on how to setup beinc_server.py 
+and beinc_weechat.py!
+Use "-h" command line parameter in order to display the available options for 
+beinc_poller.py and beinc_generic_client.py
 
 
 Supported systems & requirements
 --------------------------------
-Any system running Postfix and Spamassassin.
+Any system running the software required for the selected components.
+All components tested on: Gentoo GNU/Linux 2013,2014,
+                          Ubuntu GNU/Linux 14.4,13.10,
+                          FreeBSD 9.x
 
 
 Requirements:
 All components: Python 2.7.*
-beinc_server.py: cherrypy >= 3.2.0, pyopenssl >= 0.13.0
-beinc_weechat.py:
-beinc_poller.py: 
+beinc_server.py: cherrypy >= 3.2.0, pyopenssl >= 0.13.0 (opntional (ssl support)),
+                 pynotify >= 0.1 (optional), pyosd >= 0.2 (optional)
+beinc_weechat.py: Weechat >= 0.4.0
+beinc_poller.py: pynotify >= 0.1 (optional), pyosd >= 0.2 (optional)
+beinc_generic_client.py: No additional software required
+
+Read INSTALL for more details about installing the requirements!
 
 
 License
diff --git a/beinc_poller.py b/beinc_poller.py
index 4fbe0e0..a1269c2 100755
--- a/beinc_poller.py
+++ b/beinc_poller.py
@@ -86,6 +86,11 @@ class ValidHTTPSHandler(urllib2.HTTPSHandler):
 
 def poll_notifications(scheduler, args, notification_obj):
     """
+    the core function initiated by the scheduler performing a single poll
+
+    scheduler: scheduler object
+    args: the argparse processed command-line arguments
+    notification_obj: pynotify or pyosd notification object
     """
     try:
         post_values = {'password': args.password}
@@ -193,11 +198,12 @@ def main():
         help='BEINC osd-system ("pynotify" or "pyosd") (default: pynotify)')
     parser.add_argument(
         '-P', '--password',
-        metavar='PASSWORD',
+        metavar='PASSWORD[FILE]',
         type=str,
         dest='password',
         default='',
-        help='BEINC taget-password (default & recommended: prompt for passwd)')
+        help='BEINC taget-password / text-file containing the target password'
+        ' (default & recommended: prompt for passwd)')
     parser.add_argument(
         '-p', '--position',
         metavar='POSITION',
diff --git a/beinc_server.py b/beinc_server.py
index 906b303..30c8a95 100755
--- a/beinc_server.py
+++ b/beinc_server.py
@@ -133,14 +133,14 @@ class BEINCInstance(object):
     @property
     def name(self):
         """
-        name-property for the server instance
+        name-property for the server instance (read-only)
         """
         return self.__name
 
     @property
     def queueable(self):
         """
-        True if this instance has a queueing capability
+        True if this instance has a queueing capability (read-only)
         """
         return bool(self.__queue_size)
 
@@ -216,6 +216,9 @@ def beinc_instance_login(method):
 
 
 class WebNotifyServer(object):
+    """
+    A class representing the entire server
+    """
 
     def __init__(self, config):
         """
@@ -244,6 +247,9 @@ class WebNotifyServer(object):
 
     @property
     def instances(self):
+        """
+        a property that returns the instance list (read-only)
+        """
         return self.__instances
 
     @cherrypy.expose
diff --git a/beinc_weechat.py b/beinc_weechat.py
index 14e6eac..f878c89 100644
--- a/beinc_weechat.py
+++ b/beinc_weechat.py
@@ -79,6 +79,8 @@ class ValidHTTPSHandler(urllib2.HTTPSHandler):
 
 class WeechatTarget(object):
     """
+    The target (destination) class
+    Each remote destination is represented as a WeechatTarget object
     """
 
     def __init__(self, target_dict):
@@ -123,48 +125,56 @@ class WeechatTarget(object):
     @property
     def name(self):
         """
+        Target name (read-only property)
         """
         return self.__name
 
     @property
     def chans(self):
         """
+        Target channel list (read-only property)
         """
         return self.__chans
 
     @property
     def nicks(self):
         """
+        Target nick list (read-only property)
         """
         return self.__nicks
 
     @property
     def channel_messages_policy(self):
         """
+        The target's channel messages policy (read-only property)
         """
         return self.__chan_messages_policy
 
     @property
     def private_messages_policy(self):
         """
+        The target's private messages policy (read-only property)
         """
         return self.__priv_messages_policy
 
     @property
     def notifications_policy(self):
         """
+        The target's notifications policy (read-only property)
         """
         return self.__notifications_policy
 
     @property
     def enabled(self):
         """
+        The target's enabled status (bool property)
         """
         return self.__enabled
 
     @enabled.setter
     def enabled(self, value):
         """
+        The target's enabled status (bool property)
         """
         self.__enabled = value
 
@@ -186,6 +196,9 @@ class WeechatTarget(object):
 
     def send_private_message_notification(self, values):
         """
+        sends a private message notification to the represented target
+
+        values: dict pupulated by the irc msg-handler
         """
         try:
             title_str = self.__fetch_formatted_str(self.__pm_title_template,
@@ -210,6 +223,9 @@ class WeechatTarget(object):
 
     def send_channel_message_notification(self, values):
         """
+        sends a channel message notification to the represented target
+
+        values: dict pupulated by the irc msg-handler
         """
         try:
             title_str = self.__fetch_formatted_str(self.__cm_title_template,
@@ -234,6 +250,9 @@ class WeechatTarget(object):
 
     def send_notify_message_notification(self, values):
         """
+        sends a notify message notification to the represented target
+
+        values: dict pupulated by the irc msg-handler
         """
         try:
             title_str = self.__fetch_formatted_str(self.__nm_title_template,
@@ -258,6 +277,10 @@ class WeechatTarget(object):
 
     def send_broadcast_notification(self, message):
         """
+        sends a 'pure' broadcast / test message notification
+        to the represented target
+
+        message: a single message string
         """
         try:
             post_values = {'title': 'BEINC broadcast',
@@ -277,6 +300,11 @@ class WeechatTarget(object):
 
     def __fetch_formatted_str(self, template, values):
         """
+        returns a formatted string by replacing the defined
+        macros in 'template' the the corresponding values from 'values'
+
+        values: dict
+        template: str
         """
         template = unicode(template)
         timestamp = datetime.datetime.now().strftime(self.__timestamp_format)
@@ -384,6 +412,9 @@ def beinc_cmd_target_handler(cmd_tokens):
 
 
 def beinc_command(data, buffer_obj, args):
+    """
+    Callback function handling the Weechat's /beinc command
+    """
     global enabled
     cmd_tokens = args.split()
     if not cmd_tokens:
@@ -402,11 +433,15 @@ def beinc_command(data, buffer_obj, args):
     elif cmd_tokens[0] == 'target':
         return beinc_cmd_target_handler(cmd_tokens[1:])
     else:
-        beinc_prnt('syntax: /beinc < on | off | reload | target <action> >')
+        beinc_prnt('syntax: /beinc < on | off | reload |'
+                   ' broadcast <text> | target <action> >')
     return weechat.WEECHAT_RC_OK
 
 
 def beinc_privmsg_handler(data, signal, signal_data):
+    """
+    Callback function the *PRIVMSG* IRC messages hooked by Weechat
+    """
     if not enabled:
         return weechat.WEECHAT_RC_OK
     prvmsg_dict = weechat.info_get_hashtable('irc_message_parse',