Merge pull request #207 from lazlolazlolazlo/docstrings

Add some missing docstrings.

onionshare/helpers.py

@@ -27,6 +27,9 @@ sys.setdefaultencoding("utf-8")
 
 
 def get_platform():
+    """
+    Returns the platform OnionShare is running on.
+    """
     p = platform.system()
     if p == 'Linux' and platform.uname()[0:2] == ('Linux', 'amnesia'):
         p = 'Tails'
@@ -42,6 +45,9 @@ else:
 
 
 def get_onionshare_dir():
+    """
+    Returns the OnionShare directory.
+    """
     if get_platform() == 'Darwin':
         onionshare_dir = os.path.dirname(__file__)
     else:
@@ -50,6 +56,9 @@ def get_onionshare_dir():
 
 
 def get_html_path(filename):
+    """
+    Returns the path of the html files.
+    """
     p = platform.system()
     if p == 'Darwin':
         prefix = os.path.join(osx_resources_dir, 'html')
@@ -59,6 +68,9 @@ def get_html_path(filename):
 
 
 def constant_time_compare(val1, val2):
+    """
+    Compares two values in constant time.
+    """
     _builtin_constant_time_compare = getattr(hmac, 'compare_digest', None)
     if _builtin_constant_time_compare is not None:
         return _builtin_constant_time_compare(val1, val2)
@@ -76,6 +88,9 @@ def constant_time_compare(val1, val2):
 
 
 def random_string(num_bytes, output_len=None):
+    """
+    Returns a random string with a specified number of bytes.
+    """
     b = os.urandom(num_bytes)
     h = hashlib.sha256(b).digest()[:16]
     s = base64.b32encode(h).lower().replace('=', '')
@@ -85,6 +100,9 @@ def random_string(num_bytes, output_len=None):
 
 
 def human_readable_filesize(b):
+    """
+    Returns filesize in a human readable format.
+    """
     thresh = 1024.0
     if b < thresh:
         return '{0:.1f} B'.format(b)
@@ -98,6 +116,9 @@ def human_readable_filesize(b):
 
 
 def is_root():
+    """
+    Returns if user is root.
+    """
     return os.geteuid() == 0
 
 

onionshare/strings.py

@@ -24,6 +24,10 @@ strings = {}
 
 
 def load_strings(default="en"):
+    """
+    Loads translated strings and fallback to English
+    if the translation does not exist.
+    """
     global strings
     p = helpers.get_platform()
 
@@ -55,6 +59,9 @@ def load_strings(default="en"):
 
 
 def translated(k, gui=False):
+    """
+    Returns a translated string.
+    """
     if gui:
         return strings[k].encode("utf-8").decode('utf-8', 'replace')
     else:

onionshare_gui/common.py

@@ -22,6 +22,9 @@ from onionshare import helpers
 
 
 def get_onionshare_gui_dir():
+    """
+    Returns the OnionShare gui directory.
+    """
     p = helpers.get_platform()
     if p == 'Darwin':
         onionshare_gui_dir = os.path.dirname(__file__)
@@ -33,6 +36,9 @@ onionshare_gui_dir = get_onionshare_gui_dir()
 
 
 def get_image_path(filename):
+    """
+    Returns the OnionShare image path.
+    """
     p = helpers.get_platform()
     if p == 'Linux' or p == 'Tails':
         prefix = os.path.join(sys.prefix, 'share/onionshare/images')