From fca55ee84b4a6a36f29b3baa7195a75c327596b2 Mon Sep 17 00:00:00 2001
From: drymer <drymer@autistici.org>
Date: Sat, 8 Jul 2017 21:46:10 +0200
Subject: [PATCH] Add docstrings

---
 jabbergram.py | 33 ++++++++++++++++++++++++++++-----
 1 file changed, 28 insertions(+), 5 deletions(-)

diff --git a/jabbergram.py b/jabbergram.py
index ca59950..035352b 100755
--- a/jabbergram.py
+++ b/jabbergram.py
@@ -21,6 +21,7 @@ except:
 
 
 class Request(ElementBase):
+    """Special class to create http_upload requests."""
     namespace = 'urn:xmpp:http:upload'
     name = 'request'
     plugin_attrib = 'request'
@@ -29,7 +30,13 @@ class Request(ElementBase):
 
 
 class Jabbergram(sleekxmpp.ClientXMPP):
+    """Main object."""
     def __init__(self, jid, password, rooms, nick, token, groups, verify_ssl):
+        """
+        Executed when the class is initialized. It adds session handlers, muc
+        handlers and send the telegram reading function and the HTTP upload
+        initializing functions to their respective threads.
+        """
         # XMPP
         super(Jabbergram, self).__init__(jid, password)
         self.add_event_handler('session_start', self.start)
@@ -68,6 +75,11 @@ class Jabbergram(sleekxmpp.ClientXMPP):
               'connected')
 
     def init_http(self):
+        """
+        Initializes HTTP upload support. Sends a discovery stanza to the server
+        to find the HTTP upload component and asks for the max size a file can
+        be.
+        """
         self.http_upload = self.HttpUpload(self)
         self.component = self.http_upload.discovery()
 
@@ -87,6 +99,7 @@ class Jabbergram(sleekxmpp.ClientXMPP):
                 self.max_size = None
 
     def read_tg(self):
+        """Main telegram function."""
         update_id = 0
 
         # wait until http_upload has been tested
@@ -229,6 +242,7 @@ class Jabbergram(sleekxmpp.ClientXMPP):
                 print(e)
 
     def start(self, event):
+        """Does some initial setup for XMPP and joins all mucs."""
         self.get_roster()
         self.send_presence()
 
@@ -236,6 +250,7 @@ class Jabbergram(sleekxmpp.ClientXMPP):
             self.plugin['xep_0045'].joinMUC(muc, self.nick, wait=True)
 
     def muc_message(self, msg):
+        """Muc message's handler."""
         muc_room = str(msg['from']).split('/')[0]
         index = self.muc_rooms.index(muc_room)
         tg_group = self.groups[index]
@@ -251,6 +266,7 @@ class Jabbergram(sleekxmpp.ClientXMPP):
             self.bot.sendMessage(tg_group, text=message)
 
     def muc_online(self, presence):
+        """Muc presence's handler."""
         user = presence['muc']['nick']
         muc = presence['from'].bare
 
@@ -261,6 +277,7 @@ class Jabbergram(sleekxmpp.ClientXMPP):
                 self.xmpp_users[muc] = [presence['muc']['nick']]
 
     def muc_offline(self, presence):
+        """Muc presence's handler."""
         user = presence['muc']['nick']
         muc = presence['from'].bare
 
@@ -268,6 +285,7 @@ class Jabbergram(sleekxmpp.ClientXMPP):
             self.xmpp_users[muc].remove(presence['muc']['nick'])
 
     def say_users(self, service, muc, group):
+        """It returns the users on XMPP or Telegram."""
         if service == 'xmpp':
             if group in self.telegram_users:
                 tg_users = self.telegram_users[group]
@@ -290,6 +308,7 @@ class Jabbergram(sleekxmpp.ClientXMPP):
             self.bot.sendMessage(group, text=msg)
 
     def say_help(self, service, muc, group):
+        """Help command."""
         msg = 'Hi, I\'m ' + self.bot.username + '. I have two commands : ".us'\
               'ers" and ".where".'
         if service == 'xmpp':
@@ -298,6 +317,7 @@ class Jabbergram(sleekxmpp.ClientXMPP):
             self.bot.sendMessage(group, text=msg)
 
     def say_where(self, service, muc, group):
+        """Returns Telegram's group location if it's public."""
         if service == 'xmpp':
             if '@' in group:
                 msg = 'I\'m on http://telegram.me/' + group.split('@')[1] + '.'
@@ -310,11 +330,13 @@ class Jabbergram(sleekxmpp.ClientXMPP):
             self.bot.sendMessage(group, text=msg)
 
     class HttpUpload():
+        """HTTP upload main class."""
         def __init__(self, parent_self):
+            """Init... Yep."""
             self.parent_self = parent_self
 
         def discovery(self):
-
+            """Discovers all server's components."""
             disco = sleekxmpp.basexmpp.BaseXMPP.Iq(self.parent_self)
             disco['query'] = "http://jabber.org/protocol/disco#items"
             disco['type'] = 'get'
@@ -338,17 +360,18 @@ class Jabbergram(sleekxmpp.ClientXMPP):
             return http_upload_component
 
         def disco_info(self, component):
-
+            """Discovers HTTP upload components attributes."""
             info = sleekxmpp.basexmpp.BaseXMPP.Iq(self.parent_self)
             info['query'] = "http://jabber.org/protocol/disco#info"
             info['type'] = 'get'
             info['from'] = self.parent_self.jid
             info['to'] = component
+            response = str(info.send(timeout=30))
 
-            return str(info.send(timeout=30))
+            return response
 
         def upload(self, component, verify_ssl, u_file, size):
-
+            """Uploads to HTTP upload."""
             peticion = Request()
             peticion['filename'] = u_file.split('/')[-1]
             peticion['size'] = str(size)
@@ -367,7 +390,7 @@ class Jabbergram(sleekxmpp.ClientXMPP):
             if verify_ssl == 'False':
                 req = requests.put(put_url, data=open(u_file, 'rb'),
                                    verify=False)
-            elif verify_ssl == '':
+            else:
                 req = requests.put(put_url, data=open(u_file, 'rb'))
 
             return put_url