validations-libs/validations_libs/validation.py

#   Copyright 2020 Red Hat, Inc.
#
#   Licensed under the Apache License, Version 2.0 (the "License"); you may
#   not use this file except in compliance with the License. You may obtain
#   a copy of the License at
#
#        http://www.apache.org/licenses/LICENSE-2.0
#
#   Unless required by applicable law or agreed to in writing, software
#   distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
#   WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
#   License for the specific language governing permissions and limitations
#   under the License.
#

from validations_libs.logger import getLogger
import os
import yaml
from collections import OrderedDict

LOG = getLogger(__name__ + ".validation")


class Validation:
    """An object for encapsulating a validation

    Each validation is an `Ansible` playbook. Each playbook have some
    ``metadata``. Here is what a minimal validation would look like:

    .. code-block:: yaml

        - hosts: webserver
          vars:
            metadata:
              name: Hello World
              description: This validation prints Hello World!
          roles:
          - hello_world

    As shown here, the validation playbook requires three top-level
    directives:

    ``hosts``, ``vars -> metadata`` and ``roles``

    ``hosts`` specify which nodes to run the validation on.

    The ``vars`` section serves for storing variables that are going to be
    available to the `Ansible` playbook. The validations API uses the
    ``metadata`` section to read validation's name and description. These
    values are then reported by the API.

    The validations can be grouped together by specifying a ``groups``, a
    ``categories`` and a ``products`` metadata. ``groups`` are the deployment
    stage the validations should run on, ``categories`` are the technical
    classification for the validations and ``products`` are the specific
    validations which should be executed against a specific product.

    Groups, Categories and Products function similar to tags and a validation
    can thus be part of many groups and many categories.

    Here is an example:

    .. code-block:: yaml

        - hosts: webserver
          vars:
            metadata:
              name: Hello World
              description: This validation prints Hello World!
              groups:
                - pre-deployment
                - hardware
              categories:
                - os
                - networking
                - storage
                - security
              products:
                - product1
                - product2
          roles:
          - hello_world

    """

    _col_keys = ['ID', 'Name', 'Description',
                 'Groups', 'Categories', 'Products']

    def __init__(self, validation_path):
        self.dict = self._get_content(validation_path)
        self.id = os.path.splitext(os.path.basename(validation_path))[0]
        self.path = os.path.dirname(validation_path)

    def _get_content(self, val_path):
        try:
            with open(val_path, 'r') as val_playbook:
                return yaml.safe_load(val_playbook)[0]
        except IOError:
            raise IOError("Validation playbook not found")

    @property
    def has_vars_dict(self):
        """Check the presence of the vars dictionary

        .. code-block:: yaml

            - hosts: webserver
              vars:                    <====
                metadata:
                  name: hello world
                  description: this validation prints hello world!
                  groups:
                    - pre-deployment
                    - hardware
                  categories:
                    - os
                    - networking
                    - storage
                    - security
                  products:
                    - product1
                    - product2
              roles:
              - hello_world

        :return: `true` if `vars` is found, `false` if not.
        :rtype: `boolean`
        """
        return 'vars' in self.dict.keys()

    @property
    def has_metadata_dict(self):
        """Check the presence of the metadata dictionary

        .. code-block:: yaml

            - hosts: webserver
              vars:
                metadata:             <====
                  name: hello world
                  description: this validation prints hello world!
                  groups:
                    - pre-deployment
                    - hardware
                  categories:
                    - os
                    - networking
                    - storage
                    - security
                  products:
                    - product1
                    - product2
              roles:
              - hello_world

        :return: `true` if `vars` and metadata are found, `false` if not.
        :rtype: `boolean`
        """
        return self.has_vars_dict and 'metadata' in self.dict['vars'].keys()

    @property
    def get_metadata(self):
        """Get the metadata of a validation

        :return: The validation metadata
        :rtype: `dict` or `None` if no metadata has been found
        :raise: A `NameError` exception if no metadata has been found in the
                playbook

        :Example:

        >>> pl = '/foo/bar/val1.yaml'
        >>> val = Validation(pl)
        >>> print(val.get_metadata)
        {'description': 'Val1 desc.',
         'groups': ['group1', 'group2'],
         'categories': ['category1', 'category2'],
         'products': ['product1', 'product2'],
         'id': 'val1',
         'name': 'The validation val1\'s name',
         'path': '/tmp/foo/'}
        """
        if self.has_metadata_dict:
            self.metadata = {'id': self.id, 'path': self.path}
            self.metadata.update(self.dict['vars'].get('metadata'))
            return self.metadata
        else:
            raise NameError(
                "No metadata found in validation {}".format(self.id)
            )

    @property
    def get_vars(self):
        """Get only the variables of a validation

        :return: All the variables belonging to a validation
        :rtype: `dict` or `None` if no metadata has been found
        :raise: A `NameError` exception if no metadata has been found in the
                playbook

        :Example:

        >>> pl = '/foo/bar/val.yaml'
        >>> val = Validation(pl)
        >>> print(val.get_vars)
        {'var_name1': 'value1',
         'var_name2': 'value2'}
        """
        if self.has_metadata_dict:
            validation_vars = self.dict['vars'].copy()
            validation_vars.pop('metadata')
            return validation_vars
        else:
            raise NameError(
                "No metadata found in validation {}".format(self.id)
            )

    @property
    def get_data(self):
        """Get the full contents of a validation playbook

        :return: The full content of the playbook
        :rtype: `dict`

        :Example:

        >>> pl = '/foo/bar/val.yaml'
        >>> val = Validation(pl)
        >>> print(val.get_data)
        {'gather_facts': True,
         'hosts': 'all',
         'roles': ['val_role'],
         'vars': {'metadata': {'description': 'description of val ',
                               'groups': ['group1', 'group2'],
                               'categories': ['category1', 'category2'],
                               'products': ['product1', 'product2'],
                               'name': 'validation one'},
                               'var_name1': 'value1'}}
        """
        return self.dict

    @property
    def groups(self):
        """Get the validation list of groups

        :return: A list of groups for the validation
        :rtype: `list` or `None` if no metadata has been found
        :raise: A `NameError` exception if no metadata has been found in the
                playbook

        :Example:

        >>> pl = '/foo/bar/val.yaml'
        >>> val = Validation(pl)
        >>> print(val.groups)
        ['group1', 'group2']
        """
        if self.has_metadata_dict:
            return self.dict['vars']['metadata'].get('groups', [])
        else:
            raise NameError(
                "No metadata found in validation {}".format(self.id)
            )

    @property
    def categories(self):
        """Get the validation list of categories

        :return: A list of categories for the validation
        :rtype: `list` or `None` if no metadata has been found
        :raise: A `NameError` exception if no metadata has been found in the
                playbook

        :Example:

        >>> pl = '/foo/bar/val.yaml'
        >>> val = Validation(pl)
        >>> print(val.categories)
        ['category1', 'category2']
        """
        if self.has_metadata_dict:
            return self.dict['vars']['metadata'].get('categories', [])
        else:
            raise NameError(
                "No metadata found in validation {}".format(self.id)
            )

    @property
    def products(self):
        """Get the validation list of products

        :return: A list of products for the validation
        :rtype: `list` or `None` if no metadata has been found
        :raise: A `NameError` exception if no metadata has been found in the
                playbook

        :Example:

        >>> pl = '/foo/bar/val.yaml'
        >>> val = Validation(pl)
        >>> print(val.products)
        ['product1', 'product2']
        """
        if self.has_metadata_dict:
            return self.dict['vars']['metadata'].get('products', [])
        else:
            raise NameError(
                "No metadata found in validation {}".format(self.id)
            )

    @property
    def get_id(self):
        """Get the validation id

        :return: The validation id
        :rtype: `string`

        :Example:

        >>> pl = '/foo/bar/check-cpu.yaml'
        >>> val = Validation(pl)
        >>> print(val.id)
        'check-cpu'
        """
        return self.id

    @property
    def get_ordered_dict(self):
        """Get the full ordered content of a validation

        :return: An `OrderedDict` with the full data of a validation
        :rtype: `OrderedDict`
        """
        data = OrderedDict(self.dict)
        return data

    @property
    def get_formated_data(self):
        """Get basic information from a validation for output display

        :return: Basic information of a validation including the `Description`,
                 the list of 'Categories', the list of `Groups`, the `ID` and
                 the `Name`.
        :rtype: `dict`
        :raise: A `NameError` exception if no metadata has been found in the
                playbook

        :Example:

        >>> pl = '/foo/bar/val.yaml'
        >>> val = Validation(pl)
        >>> print(val.get_formated_data)
        {'Categories': ['category1', 'category2'],
         'Products': ['product1', 'product2'],
         'Description': 'description of val',
         'Groups': ['group1', 'group2'],
         'ID': 'val',
         'Name': 'validation one',
         'path': '/tmp/foo/'}
        """
        data = {}
        metadata = self.get_metadata

        for key in metadata:
            if key == 'id':
                data[key.upper()] = metadata.get(key)
            else:
                data[key.capitalize()] = metadata.get(key)

        return data