Add rankfile docstrings, bump version

README.rst

@@ -17,8 +17,10 @@ Everything **ffflash** needs to know is passed each time as shell parameters.
 
 -  To get help, use ``ffflash.py -h``::
 
-    usage: ffflash [-h] [-n NODELIST] [-r RANKFILE]
-               [-s SIDECARS [SIDECARS ...]] [-d] [-v]
+    usage: ffflash [-h] [-s SIDECARS [SIDECARS ...]] [-n NODELIST] [-r RANKFILE]
+               [-rc RANKCLIENTS] [-rf RANKOFFLINE] [-rn RANKONLINE]
+               [-rp RANKPOSITION] [-rw RANKWELCOME] [-d] [-v]
+               APIfile
 
 -  You always need to pass the location to your ``APIfile``.
 
@@ -29,6 +31,12 @@ Everything **ffflash** needs to know is passed each time as shell parameters.
 -  Do some number crunching and store the *scores* in the ``--rankfile``.
    (Only works if passed together with an ``--nodelist``).
 
+    -  ``--rankwelcome`` sets the initial *score* to start with.
+    -  ``--rankposition`` increases *score* by that value if any location data is
+       provided.
+    -  ``--rankonline`` increases *score* by that value if node is online.
+    -  ``--rankoffline`` decreases *score* by that value if node is offline.
+    -  ``--rankclients`` increases *score* per client by that value.
 
 -  Pass one or more ``--sidecars`` (or ``-s``) to merge content from there
    into the APIfile.

ffflash/inc/rankfile.py

@@ -7,6 +7,18 @@
 
 
 def _rankfile_load(ff):
+    '''
+    Load either existing ``rankfile`` from disk, or create empty stub
+    if one does not exist yet. Path and extension (*json* or *yaml*)
+    get validated.
+
+    :param ff: running :class:`ffflash.main.FFFlash` instance
+    :return: Tuple of either (``False``, ``None``, ``None``) on error or:
+
+        * validated path to the ``rankfile``
+        * ``rankfile`` content
+        * ``True`` if ``rankfile`` is a *yaml* file, ``False`` if it's *json*
+    '''
     if not ff.access_for('rankfile'):
         return (False, None, None)
     ff.log('handling rankfile {}'.format(ff.args.rankfile))
@@ -17,14 +29,15 @@ def _rankfile_load(ff):
             'wrong path for rankfile {}'.format(ff.args.rankfile),
             level=False
         ), None, None
+
     _, ext = path.splitext(rankfile)
     if not ext or ext.lower() not in ['.yaml', '.json']:
         return ff.log(
             'rankfile {} {} is neither json nor yaml'.format(rankfile, ext),
             level=False
         ), None, None
-    as_yaml = True if ext == '.yaml' else False
 
+    as_yaml = True if ext == '.yaml' else False
     ranks = load_file(rankfile, fallback={
         'updated_at': 'never', 'nodes': []
     }, as_yaml=as_yaml)
@@ -52,6 +65,10 @@ def _rankfile_load(ff):
 
 
 def _rankfile_score(ff, ranks, nodelist):
+    '''
+
+    :param ff: running :class:`ffflash.main.FFFlash` instance
+    '''
     if not ff.access_for('rankfile'):
         return False
     if not all([
@@ -95,6 +112,16 @@ def _rankfile_score(ff, ranks, nodelist):
 
 
 def _rankfile_dump(ff, rankfile, ranks, as_yaml):
+    '''
+    Store ranks in ``rankfile``. Also sets a timestamp and writes the
+    release string into the output.
+
+    :param ff: running :class:`ffflash.main.FFFlash` instance
+    :param rankfile: validated path to the ``rankfile``
+    :param ranks: content to store
+    :param as_yaml: dump as *yaml* instead of *json*
+    :return: ``True`` on success, or ``False`` on error
+    '''
     if not ff.access_for('rankfile'):
         return False
     if not all([

ffflash/info.py

@@ -19,7 +19,7 @@ def __init__(self):
         self.version = '0.9'
 
         self.name = self.cname.lower()
-        self.release = '{}{}'.format(self.version, 'a6')
+        self.release = '{}{}'.format(self.version, 'a7')
         self.ident = '{} {}'.format(self.name, self.release)
         self.download_url = '{}/archive/{}.tar.gz'.format(
             self.url, self.release