Added docs around oo_nodes_with_label

filter_plugins/oo_filters.py

@@ -1,9 +1,9 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 # vim: expandtab:tabstop=4:shiftwidth=4
-'''
+"""
 Custom filters for use in openshift-ansible
-'''
+"""
 
 from ansible import errors
 from operator import itemgetter
@@ -19,25 +19,25 @@ from ansible.utils.unicode import to_unicode
 # public
 # pylint: disable=too-many-public-methods
 class FilterModule(object):
-    ''' Custom ansible filters '''
+    """ Custom ansible filters """
 
     @staticmethod
     def oo_pdb(arg):
-        ''' This pops you into a pdb instance where arg is the data passed in
+        """ This pops you into a pdb instance where arg is the data passed in
             from the filter.
             Ex: "{{ hostvars | oo_pdb }}"
-        '''
+        """
         pdb.set_trace()
         return arg
 
     @staticmethod
     def get_attr(data, attribute=None):
-        ''' This looks up dictionary attributes of the form a.b.c and returns
+        """ This looks up dictionary attributes of the form a.b.c and returns
             the value.
             Ex: data = {'a': {'b': {'c': 5}}}
                 attribute = "a.b.c"
                 returns 5
-        '''
+        """
         if not attribute:
             raise errors.AnsibleFilterError("|failed expects attribute to be set")
 
@@ -49,8 +49,8 @@ class FilterModule(object):
 
     @staticmethod
     def oo_flatten(data):
-        ''' This filter plugin will flatten a list of lists
-        '''
+        """ This filter plugin will flatten a list of lists
+        """
         if not isinstance(data, list):
             raise errors.AnsibleFilterError("|failed expects to flatten a List")
 
@@ -58,7 +58,7 @@ class FilterModule(object):
 
     @staticmethod
     def oo_collect(data, attribute=None, filters=None):
-        ''' This takes a list of dict and collects all attributes specified into a
+        """ This takes a list of dict and collects all attributes specified into a
             list. If filter is specified then we will include all items that
             match _ALL_ of filters.  If a dict entry is missing the key in a
             filter it will be excluded from the match.
@@ -70,7 +70,7 @@ class FilterModule(object):
                 attribute = 'a'
                 filters   = {'z': 'z'}
                 returns [1, 2, 3]
-        '''
+        """
         if not isinstance(data, list):
             raise errors.AnsibleFilterError("|failed expects to filter on a List")
 
@@ -90,11 +90,11 @@ class FilterModule(object):
 
     @staticmethod
     def oo_select_keys_from_list(data, keys):
-        ''' This returns a list, which contains the value portions for the keys
+        """ This returns a list, which contains the value portions for the keys
             Ex: data = { 'a':1, 'b':2, 'c':3 }
                 keys = ['a', 'c']
                 returns [1, 3]
-        '''
+        """
 
         if not isinstance(data, list):
             raise errors.AnsibleFilterError("|failed expects to filter on a list")
@@ -109,11 +109,11 @@ class FilterModule(object):
 
     @staticmethod
     def oo_select_keys(data, keys):
-        ''' This returns a list, which contains the value portions for the keys
+        """ This returns a list, which contains the value portions for the keys
             Ex: data = { 'a':1, 'b':2, 'c':3 }
                 keys = ['a', 'c']
                 returns [1, 3]
-        '''
+        """
 
         if not isinstance(data, dict):
             raise errors.AnsibleFilterError("|failed expects to filter on a dict")
@@ -128,12 +128,12 @@ class FilterModule(object):
 
     @staticmethod
     def oo_prepend_strings_in_list(data, prepend):
-        ''' This takes a list of strings and prepends a string to each item in the
+        """ This takes a list of strings and prepends a string to each item in the
             list
             Ex: data = ['cart', 'tree']
                 prepend = 'apple-'
                 returns ['apple-cart', 'apple-tree']
-        '''
+        """
         if not isinstance(data, list):
             raise errors.AnsibleFilterError("|failed expects first param is a list")
         if not all(isinstance(x, basestring) for x in data):
@@ -144,9 +144,9 @@ class FilterModule(object):
 
     @staticmethod
     def oo_combine_key_value(data, joiner='='):
-        '''Take a list of dict in the form of { 'key': 'value'} and
+        """Take a list of dict in the form of { 'key': 'value'} and
            arrange them as a list of strings ['key=value']
-        '''
+        """
         if not isinstance(data, list):
             raise errors.AnsibleFilterError("|failed expects first param is a list")
 
@@ -158,9 +158,9 @@ class FilterModule(object):
 
     @staticmethod
     def oo_combine_dict(data, in_joiner='=', out_joiner=' '):
-        '''Take a dict in the form of { 'key': 'value', 'key': 'value' } and
+        """Take a dict in the form of { 'key': 'value', 'key': 'value' } and
            arrange them as a string 'key=value key=value'
-        '''
+        """
         if not isinstance(data, dict):
             raise errors.AnsibleFilterError("|failed expects first param is a dict")
 
@@ -168,9 +168,9 @@ class FilterModule(object):
 
     @staticmethod
     def oo_ami_selector(data, image_name):
-        ''' This takes a list of amis and an image name and attempts to return
+        """ This takes a list of amis and an image name and attempts to return
             the latest ami.
-        '''
+        """
         if not isinstance(data, list):
             raise errors.AnsibleFilterError("|failed expects first param is a list")
 
@@ -187,7 +187,7 @@ class FilterModule(object):
 
     @staticmethod
     def oo_ec2_volume_definition(data, host_type, docker_ephemeral=False):
-        ''' This takes a dictionary of volume definitions and returns a valid ec2
+        """ This takes a dictionary of volume definitions and returns a valid ec2
             volume definition based on the host_type and the values in the
             dictionary.
             The dictionary should look similar to this:
@@ -212,7 +212,7 @@ class FilterModule(object):
                         }
                     }
                 }
-        '''
+        """
         if not isinstance(data, dict):
             raise errors.AnsibleFilterError("|failed expects first param is a dict")
         if host_type not in ['master', 'node', 'etcd']:
@@ -246,15 +246,15 @@ class FilterModule(object):
 
     @staticmethod
     def oo_split(string, separator=','):
-        ''' This splits the input string into a list
-        '''
+        """ This splits the input string into a list
+        """
         return string.split(separator)
 
     @staticmethod
     def oo_haproxy_backend_masters(hosts):
-        ''' This takes an array of dicts and returns an array of dicts
+        """ This takes an array of dicts and returns an array of dicts
             to be used as a backend for the haproxy role
-        '''
+        """
         servers = []
         for idx, host_info in enumerate(hosts):
             server = dict(name="master%s" % idx)
@@ -267,7 +267,7 @@ class FilterModule(object):
 
     @staticmethod
     def oo_filter_list(data, filter_attr=None):
-        ''' This returns a list, which contains all items where filter_attr
+        """ This returns a list, which contains all items where filter_attr
             evaluates to true
             Ex: data = [ { a: 1, b: True },
                          { a: 3, b: False },
@@ -275,7 +275,7 @@ class FilterModule(object):
                 filter_attr = 'b'
                 returns [ { a: 1, b: True },
                           { a: 5, b: True } ]
-        '''
+        """
         if not isinstance(data, list):
             raise errors.AnsibleFilterError("|failed expects to filter on a list")
 
@@ -286,19 +286,45 @@ class FilterModule(object):
         return [x for x in data if x.has_key(filter_attr) and x[filter_attr]]
 
     @staticmethod
-    def oo_nodes_with_label(nodes, label=None, value=None):
-        ''' Filters a list of nodes by label '''
+    def oo_nodes_with_label(nodes, label, value=None):
+        """ Filters a list of nodes by label and value (if provided)
+
+            It handles labels that are in the following variables by priority:
+            openshift_node_labels, cli_openshift_node_labels, openshift['node']['labels']
+
+            Examples:
+                data = ['a': {'openshift_node_labels': {'color': 'blue', 'size': 'M'}},
+                        'b': {'openshift_node_labels': {'color': 'green', 'size': 'L'}},
+                        'c': {'openshift_node_labels': {'size': 'S'}}]
+                label = 'color'
+                returns = ['a': {'openshift_node_labels': {'color': 'blue', 'size': 'M'}},
+                           'b': {'openshift_node_labels': {'color': 'green', 'size': 'L'}}]
+
+                data = ['a': {'openshift_node_labels': {'color': 'blue', 'size': 'M'}},
+                        'b': {'openshift_node_labels': {'color': 'green', 'size': 'L'}},
+                        'c': {'openshift_node_labels': {'size': 'S'}}]
+                label = 'color'
+                value = 'green'
+                returns = ['b': {'labels': {'color': 'green', 'size': 'L'}}]
+
+            Args:
+                nodes (list[dict]): list of node to node variables
+                label (str): label to filter `nodes` by
+                value (Optional[str]): value of `label` to filter by Defaults
+                                       to None.
+
+            Returns:
+                list[dict]: nodes filtered by label and value (if provided)
+        """
         if not isinstance(nodes, list):
             raise errors.AnsibleFilterError("failed expects to filter on a list")
-        if label is None:
-            return nodes
-        elif not isinstance(label, basestring):
+        if not isinstance(label, basestring):
             raise errors.AnsibleFilterError("failed expects label to be a string")
         if value is not None and not isinstance(value, basestring):
             raise errors.AnsibleFilterError("failed expects value to be a string")
 
         def label_filter(node):
-            ''' filter function for testing if node should be returned '''
+            """ filter function for testing if node should be returned """
             if not isinstance(node, dict):
                 raise errors.AnsibleFilterError("failed expects to filter on a list of dicts")
             if 'openshift_node_labels' in node:
@@ -323,7 +349,7 @@ class FilterModule(object):
 
     @staticmethod
     def oo_parse_heat_stack_outputs(data):
-        ''' Formats the HEAT stack output into a usable form
+        """ Formats the HEAT stack output into a usable form
 
             The goal is to transform something like this:
 
@@ -362,7 +388,7 @@ class FilterModule(object):
                 "value_B2"
               ]
             }
-        '''
+        """
 
         # Extract the “outputs” JSON snippet from the pretty-printed array
         in_outputs = False
@@ -391,7 +417,7 @@ class FilterModule(object):
     @staticmethod
     # pylint: disable=too-many-branches
     def oo_parse_named_certificates(certificates, named_certs_dir, internal_hostnames):
-        ''' Parses names from list of certificate hashes.
+        """ Parses names from list of certificate hashes.
 
             Ex: certificates = [{ "certfile": "/root/custom1.crt",
                                   "keyfile": "/root/custom1.key" },
@@ -405,7 +431,7 @@ class FilterModule(object):
                          { "certfile": "/etc/origin/master/named_certificates/custom2.crt",
                            "keyfile": "/etc/origin/master/named_certificates/custom2.key",
                            "names": [ "some-hostname.com" ] }]
-        '''
+        """
         if not isinstance(named_certs_dir, basestring):
             raise errors.AnsibleFilterError("|failed expects named_certs_dir is str or unicode")
 
@@ -449,7 +475,7 @@ class FilterModule(object):
 
     @staticmethod
     def oo_pretty_print_cluster(data):
-        ''' Read a subset of hostvars and build a summary of the cluster
+        """ Read a subset of hostvars and build a summary of the cluster
             in the following layout:
 
 "c_id": {
@@ -466,14 +492,14 @@ class FilterModule(object):
   ...
     ]
   }
-        '''
+        """
 
         def _get_tag_value(tags, key):
-            ''' Extract values of a map implemented as a set.
+            """ Extract values of a map implemented as a set.
                 Ex: tags = { 'tag_foo_value1', 'tag_bar_value2', 'tag_baz_value3' }
                     key = 'bar'
                     returns 'value2'
-            '''
+            """
             for tag in tags:
                 if tag[:len(key)+4] == 'tag_' + key:
                     return tag[len(key)+5:]
@@ -484,7 +510,7 @@ class FilterModule(object):
                       host_type,
                       sub_host_type,
                       host):
-            ''' Add a new host in the clusters data structure '''
+            """ Add a new host in the clusters data structure """
             if clusterid not in clusters:
                 clusters[clusterid] = {}
             if host_type not in clusters[clusterid]:
@@ -509,7 +535,7 @@ class FilterModule(object):
 
     @staticmethod
     def oo_generate_secret(num_bytes):
-        ''' generate a session secret '''
+        """ generate a session secret """
 
         if not isinstance(num_bytes, int):
             raise errors.AnsibleFilterError("|failed expects num_bytes is int")
@@ -519,7 +545,7 @@ class FilterModule(object):
 
     @staticmethod
     def to_padded_yaml(data, level=0, indent=2, **kw):
-        ''' returns a yaml snippet padded to match the indent level you specify '''
+        """ returns a yaml snippet padded to match the indent level you specify """
         if data in [None, ""]:
             return ""
 
@@ -531,7 +557,7 @@ class FilterModule(object):
             raise errors.AnsibleFilterError('Failed to convert: %s', my_e)
 
     def filters(self):
-        ''' returns a mapping of filters to methods '''
+        """ returns a mapping of filters to methods """
         return {
             "oo_select_keys": self.oo_select_keys,
             "oo_select_keys_from_list": self.oo_select_keys_from_list,