From cd87a96cbe07d175f8a5f0d2c639a05b27813ed3 Mon Sep 17 00:00:00 2001 From: Frieder Griesshammer Date: Tue, 1 Dec 2015 16:39:05 +0100 Subject: [PATCH] Add remaining docstrings --- docs/sidecars.rst | 2 +- ffflash/inc/nodelist.py | 37 ++++++++++++++++++++++++++++++++++++ ffflash/inc/rankfile.py | 7 +++++++ ffflash/inc/sidecars.py | 42 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 87 insertions(+), 1 deletion(-) diff --git a/docs/sidecars.rst b/docs/sidecars.rst index 3d26a49..23ab8fe 100644 --- a/docs/sidecars.rst +++ b/docs/sidecars.rst @@ -3,7 +3,7 @@ Sidecars Use one ore more Sidecars to merge content from there into the APIfile. -Sidecars are either **yaml** or **json** files. +Sidecars are either *yaml* or *json* files. This is determined by the extension in the filename. The filename is a dot-separated path into the keys of the APIfile. diff --git a/ffflash/inc/nodelist.py b/ffflash/inc/nodelist.py index 5528e2e..6a1187a 100644 --- a/ffflash/inc/nodelist.py +++ b/ffflash/inc/nodelist.py @@ -5,6 +5,14 @@ def _nodelist_fetch(ff): + ''' + Determines if ``--nodelist`` was a file or a url, and tries to fetch it. + Validates nodelist to be json and to have the *version*, *nodes* and + *updated_at* keys. + + :param ff: running :class:`ffflash.main.FFFlash` instance + :return: the unpickled nodelist or ``False``/``None`` on error + ''' if not ff.access_for('nodelist'): return False @@ -33,6 +41,14 @@ def _nodelist_fetch(ff): def _nodelist_count(ff, nodelist): + ''' + Count online nodes and sum up their clients from a nodelist. + + :param ff: running :class:`ffflash.main.FFFlash` instance + :param nodelist: nodelist from :meth:`_nodelist_fetch`, should contain a + list of dictionaries at the key *nodes* + :return: Tuple of counted nodes and clients + ''' nodes, clients = 0, 0 for node in nodelist.get('nodes', []): if node.get('status', {}).get('online', False): @@ -47,6 +63,20 @@ def _nodelist_count(ff, nodelist): def _nodelist_dump(ff, nodes, clients): + ''' + Store the counted numbers in the api-file. + + Sets the key ``state`` . ``nodes`` with the node number. + + Leaves ``state`` . ``description`` untouched, if any already present. + If empty, or the pattern ``\[[\d]+ Nodes, [\d]+ Clients\]`` is matched, + the numbers in the pattern will be replaced. + + :param ff: running :class:`ffflash.main.FFFlash` instance + :param nodes: Number of online nodes + :param clients: Number of their clients + :return: ``True`` if :attr:`api` was modified else ``False`` + ''' if not ff.access_for('nodelist'): return False @@ -69,6 +99,13 @@ def _nodelist_dump(ff, nodes, clients): def handle_nodelist(ff): + ''' + Entry function to receive a ``--nodelist`` and store determined results + into both :attr:`api` and ``--rankfile`` (if specified). + + :param ff: running :class:`ffflash.main.FFFlash` instance + :return: ``True`` if :attr:`api` was modified else ``False`` + ''' if not ff.access_for('nodelist'): return False diff --git a/ffflash/inc/rankfile.py b/ffflash/inc/rankfile.py index 20314e8..3992a7c 100644 --- a/ffflash/inc/rankfile.py +++ b/ffflash/inc/rankfile.py @@ -1,5 +1,12 @@ def handle_rankfile(ff, nodelist): + ''' + Entry function gather results from a retrieved ``--nodelist`` to store it + into the ``--rankfile``. + + :param ff: running :class:`ffflash.main.FFFlash` instance + :return: ``True`` if rankfile was modified else ``False`` + ''' if not ff.access_for('rankfile'): return False if not nodelist or not isinstance(nodelist, dict): diff --git a/ffflash/inc/sidecars.py b/ffflash/inc/sidecars.py index f48df0a..04dedae 100644 --- a/ffflash/inc/sidecars.py +++ b/ffflash/inc/sidecars.py @@ -5,6 +5,19 @@ def _sidecar_path(ff, sc): + ''' + Check passed sidecars for valid paths, format (*json* or *yaml*) and for + valid filenames (no double dots). + + :param ff: running :class:`ffflash.main.FFFlash` instance + :param sc: sidecar as passed by user + :return: Tuple of either (``False``, ``None``, ``None``) on error or: + + * normalized and full path to ``sc`` + * unvalidated key-names into api-file + * ``True`` if ``sc`` is a *yaml* file, ``False`` if it's *json* + + ''' ff.log('handling sidecar {}'.format(sc)) sidepath = check_file_location(sc) @@ -36,6 +49,17 @@ def _sidecar_path(ff, sc): def _sidecar_load(ff, sidepath, fields, as_yaml): + ''' + Loads content from ``sidepath`` if it exists, otherwise returns the values + from the :attr:`api` instead. + This is only done, if ``fields`` exist in :attr:`api`. + + :param ff: running :class:`ffflash.main.FFFlash` instance + :param sidepath: full path to the sidecar + :param fields: key-names into api-file + :param as_yaml: load as *yaml* instead of *json* + :return: The loaded content of ``sidepath`` or ``False``/``None`` on error + ''' if not ff.access_for('sidecars'): return False @@ -56,6 +80,16 @@ def _sidecar_load(ff, sidepath, fields, as_yaml): def _sidecar_dump(ff, sidepath, content, fields, as_yaml): + ''' + Stores ``content`` both in :attr:`api` and ``sidepath``. + + :param ff: running :class:`ffflash.main.FFFlash` instance + :param sidepath: full path to the sidecar + :param content: the value to store into sidecar/api-file + :param fields: key-names into api-file + :param as_yaml: dump as *yaml* instead of *json* + :return: ``True`` if ``sidepath`` was modified else ``False`` + ''' if not ff.access_for('sidecars'): return False @@ -72,6 +106,14 @@ def _sidecar_dump(ff, sidepath, content, fields, as_yaml): def handle_sidecars(ff): + ''' + Entry function to handle passed ``--sidecars``. Validating locations, names + and content of sidecars. Generating them if necessary and update + :attr:`api`. + + :param ff: running :class:`ffflash.main.FFFlash` instance + :return: ``True`` if any sidecar was modified else ``False`` + ''' if not ff.access_for('sidecars'): return False