Collections.py

Go to the documentation of this file.

#  Copyright 2008-2015 Nokia Networks
#  Copyright 2016-     Robot Framework Foundation
#
#  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.
 
import copy
 
from robot.api import logger
from robot.utils import (is_dict_like, is_list_like, is_string, is_truthy, Matcher,
                         plural_or_not as s, seq2str, seq2str2, type_name)
from robot.utils.asserts import assert_equal
from robot.version import get_version
 
 
class NotSet:
    def __repr__(self):
        return ""
 
 
NOT_SET = NotSet()
 
 
class _List:
 
    
    def convert_to_list(self, item):
        return list(item)
 
    
    def append_to_list(self, list_, *values):
        self._validate_list_validate_list(list_)
        for value in values:
            list_.append(value)
 
    
    def insert_into_list(self, list_, index, value):
        self._validate_list_validate_list(list_)
        list_.insert(self._index_to_int_index_to_int(index), value)
 
    
    def combine_lists(self, *lists):
        self._validate_lists_validate_lists(*lists)
        ret = []
        for item in lists:
            ret.extend(item)
        return ret
 
    
    def set_list_value(self, list_, index, value):
        self._validate_list_validate_list(list_)
        try:
            list_[self._index_to_int_index_to_int(index)] = value
        except IndexError:
            self._index_error_index_error(list_, index)
 
    
    def remove_values_from_list(self, list_, *values):
        self._validate_list_validate_list(list_)
        for value in values:
            while value in list_:
                list_.remove(value)
 
    
    def remove_from_list(self, list_, index):
        self._validate_list_validate_list(list_)
        try:
            return list_.pop(self._index_to_int_index_to_int(index))
        except IndexError:
            self._index_error_index_error(list_, index)
 
    
    def remove_duplicates(self, list_):
        self._validate_list_validate_list(list_)
        ret = []
        for item in list_:
            if item not in ret:
                ret.append(item)
        removed = len(list_) - len(ret)
        logger.info(f'{removed} duplicate{s(removed)} removed.')
        return ret
 
    
    def get_from_list(self, list_, index):
        self._validate_list_validate_list(list_)
        try:
            return list_[self._index_to_int_index_to_int(index)]
        except IndexError:
            self._index_error_index_error(list_, index)
 
    
    def get_slice_from_list(self, list_, start=0, end=None):
        self._validate_list_validate_list(list_)
        start = self._index_to_int_index_to_int(start, True)
        if end is not None:
            end = self._index_to_int_index_to_int(end)
        return list_[start:end]
 
    
    def count_values_in_list(self, list_, value, start=0, end=None):
        self._validate_list_validate_list(list_)
        return self.get_slice_from_listget_slice_from_list(list_, start, end).count(value)
 
    
    def get_index_from_list(self, list_, value, start=0, end=None):
        self._validate_list_validate_list(list_)
        if start == '':
            start = 0
        list_ = self.get_slice_from_listget_slice_from_list(list_, start, end)
        try:
            return int(start) + list_.index(value)
        except ValueError:
            return -1
 
    
    def copy_list(self, list_, deepcopy=False):
        self._validate_list_validate_list(list_)
        if deepcopy:
            return copy.deepcopy(list_)
        return list_[:]
 
    
    def reverse_list(self, list_):
        self._validate_list_validate_list(list_)
        list_.reverse()
 
    
    def sort_list(self, list_):
        self._validate_list_validate_list(list_)
        list_.sort()
 
    
    def list_should_contain_value(self, list_, value, msg=None):
        self._validate_list_validate_list(list_)
        _verify_condition(value in list_,
                          f"{seq2str2(list_)} does not contain value '{value}'.",
                          msg)
 
    
    def list_should_not_contain_value(self, list_, value, msg=None):
        self._validate_list_validate_list(list_)
        _verify_condition(value not in list_,
                          f"{seq2str2(list_)} contains value '{value}'.",
                          msg)
 
    
    def list_should_not_contain_duplicates(self, list_, msg=None):
        self._validate_list_validate_list(list_)
        if not isinstance(list_, list):
            list_ = list(list_)
        dupes = []
        for item in list_:
            if item not in dupes:
                count = list_.count(item)
                if count > 1:
                    logger.info(f"'{item}' found {count} times.")
                    dupes.append(item)
        if dupes:
            raise AssertionError(msg or f'{seq2str(dupes)} found multiple times.')
 
    
    def lists_should_be_equal(self, list1, list2, msg=None, values=True,
                              names=None, ignore_order=False):
        self._validate_lists_validate_lists(list1, list2)
        len1 = len(list1)
        len2 = len(list2)
        _verify_condition(len1 == len2,
                          f'Lengths are different: {len1} != {len2}',
                          msg, values)
        names = self._get_list_index_name_mapping_get_list_index_name_mapping(names, len1)
        if ignore_order:
            list1 = sorted(list1)
            list2 = sorted(list2)
        diffs = '\n'.join(self._yield_list_diffs_yield_list_diffs(list1, list2, names))
        _verify_condition(not diffs,
                          f'Lists are different:\n{diffs}',
                          msg, values)
 
    def _get_list_index_name_mapping(self, names, list_length):
        if not names:
            return {}
        if is_dict_like(names):
            return dict((int(index), names[index]) for index in names)
        return dict(zip(range(list_length), names))
 
    def _yield_list_diffs(self, list1, list2, names):
        for index, (item1, item2) in enumerate(zip(list1, list2)):
            name = f' ({names[index]})' if index in names else ''
            try:
                assert_equal(item1, item2, msg=f'Index {index}{name}')
            except AssertionError as err:
                yield str(err)
 
    
    def list_should_contain_sub_list(self, list1, list2, msg=None, values=True):
        self._validate_lists_validate_lists(list1, list2)
        diffs = ', '.join(str(item) for item in list2 if item not in list1)
        _verify_condition(not diffs,
                          f'Following values were not found from first list: {diffs}',
                          msg, values)
 
    
    def log_list(self, list_, level='INFO'):
        self._validate_list_validate_list(list_)
        logger.write('\n'.join(self._log_list_log_list(list_)), level)
 
    def _log_list(self, list_):
        if not list_:
            yield 'List is empty.'
        elif len(list_) == 1:
            yield f'List has one item:\n{list_[0]}'
        else:
            yield f'List length is {len(list_)} and it contains following items:'
            for index, item in enumerate(list_):
                yield f'{index}: {item}'
 
    def _index_to_int(self, index, empty_to_zero=False):
        if empty_to_zero and not index:
            return 0
        try:
            return int(index)
        except ValueError:
            raise ValueError(f"Cannot convert index '{index}' to an integer.")
 
    def _index_error(self, list_, index):
        raise IndexError(f'Given index {index} is out of the range 0-{len(list_)-1}.')
 
    def _validate_list(self, list_, position=1):
        if not is_list_like(list_):
            raise TypeError(f"Expected argument {position} to be a list or list-like, "
                            f"got {type_name(list_)} instead.")
 
    def _validate_lists(self, *lists):
        for index, item in enumerate(lists, start=1):
            self._validate_list_validate_list(item, index)
 
 
class _Dictionary:
 
    
    def convert_to_dictionary(self, item):
        return dict(item)
 
    
    def set_to_dictionary(self, dictionary, *key_value_pairs, **items):
        self._validate_dictionary_validate_dictionary(dictionary)
        if len(key_value_pairs) % 2 != 0:
            raise ValueError("Adding data to a dictionary failed. There "
                             "should be even number of key-value-pairs.")
        for i in range(0, len(key_value_pairs), 2):
            dictionary[key_value_pairs[i]] = key_value_pairs[i+1]
        dictionary.update(items)
        return dictionary
 
    
    def remove_from_dictionary(self, dictionary, *keys):
        self._validate_dictionary_validate_dictionary(dictionary)
        for key in keys:
            if key in dictionary:
                value = dictionary.pop(key)
                logger.info(f"Removed item with key '{key}' and value '{value}'.")
            else:
                logger.info(f"Key '{key}' not found.")
 
    
    def pop_from_dictionary(self, dictionary, key, default=NOT_SET):
        self._validate_dictionary_validate_dictionary(dictionary)
        if default is NOT_SET:
            self.dictionary_should_contain_keydictionary_should_contain_key(dictionary, key)
            return dictionary.pop(key)
        return dictionary.pop(key, default)
 
    
    def keep_in_dictionary(self, dictionary, *keys):
        self._validate_dictionary_validate_dictionary(dictionary)
        remove_keys = [k for k in dictionary if k not in keys]
        self.remove_from_dictionaryremove_from_dictionary(dictionary, *remove_keys)
 
    
    def copy_dictionary(self, dictionary, deepcopy=False):
        self._validate_dictionary_validate_dictionary(dictionary)
        if deepcopy:
            return copy.deepcopy(dictionary)
        return dictionary.copy()
 
    
    def get_dictionary_keys(self, dictionary, sort_keys=True):
        self._validate_dictionary_validate_dictionary(dictionary)
        keys = dictionary.keys()
        if sort_keys:
            try:
                return sorted(keys)
            except TypeError:
                pass
        return list(keys)
 
    
    def get_dictionary_values(self, dictionary, sort_keys=True):
        self._validate_dictionary_validate_dictionary(dictionary)
        keys = self.get_dictionary_keysget_dictionary_keys(dictionary, sort_keys=sort_keys)
        return [dictionary[k] for k in keys]
 
    
    def get_dictionary_items(self, dictionary, sort_keys=True):
        self._validate_dictionary_validate_dictionary(dictionary)
        keys = self.get_dictionary_keysget_dictionary_keys(dictionary, sort_keys=sort_keys)
        return [i for key in keys for i in (key, dictionary[key])]
 
    
    def get_from_dictionary(self, dictionary, key, default=NOT_SET):
        self._validate_dictionary_validate_dictionary(dictionary)
        try:
            return dictionary[key]
        except KeyError:
            if default is not NOT_SET:
                return default
            raise RuntimeError(f"Dictionary does not contain key '{key}'.")
 
    
    def dictionary_should_contain_key(self, dictionary, key, msg=None):
        self._validate_dictionary_validate_dictionary(dictionary)
        _verify_condition(key in dictionary,
                          f"Dictionary does not contain key '{key}'.",
                          msg)
 
    
    def dictionary_should_not_contain_key(self, dictionary, key, msg=None):
        self._validate_dictionary_validate_dictionary(dictionary)
        _verify_condition(key not in dictionary,
                          f"Dictionary contains key '{key}'.",
                          msg)
 
    
    def dictionary_should_contain_item(self, dictionary, key, value, msg=None):
        self._validate_dictionary_validate_dictionary(dictionary)
        self.dictionary_should_contain_keydictionary_should_contain_key(dictionary, key, msg)
        assert_equal(dictionary[key], value,
                     msg or f"Value of dictionary key '{key}' does not match",
                     values=not msg)
 
    
    def dictionary_should_contain_value(self, dictionary, value, msg=None):
        self._validate_dictionary_validate_dictionary(dictionary)
        _verify_condition(value in dictionary.values(),
                          f"Dictionary does not contain value '{value}'.",
                          msg)
 
    
    def dictionary_should_not_contain_value(self, dictionary, value, msg=None):
        self._validate_dictionary_validate_dictionary(dictionary)
        _verify_condition(value not in dictionary.values(),
                          f"Dictionary contains value '{value}'.",
                          msg)
 
    
    def dictionaries_should_be_equal(self, dict1, dict2, msg=None, values=True):
        self._validate_dictionary_validate_dictionary(dict1)
        self._validate_dictionary_validate_dictionary(dict2, 2)
        keys = self._keys_should_be_equal_keys_should_be_equal(dict1, dict2, msg, values)
        self._key_values_should_be_equal_key_values_should_be_equal(keys, dict1, dict2, msg, values)
 
    
    def dictionary_should_contain_sub_dictionary(self, dict1, dict2, msg=None,
                                                 values=True):
        self._validate_dictionary_validate_dictionary(dict1)
        self._validate_dictionary_validate_dictionary(dict2, 2)
        keys = self.get_dictionary_keysget_dictionary_keys(dict2)
        diffs = ', '.join(str(k) for k in keys if k not in dict1)
        _verify_condition(not diffs,
                          f"Following keys missing from first dictionary: {diffs}",
                          msg, values)
        self._key_values_should_be_equal_key_values_should_be_equal(keys, dict1, dict2, msg, values)
 
    
    def log_dictionary(self, dictionary, level='INFO'):
        self._validate_dictionary_validate_dictionary(dictionary)
        logger.write('\n'.join(self._log_dictionary_log_dictionary(dictionary)), level)
 
    def _log_dictionary(self, dictionary):
        if not dictionary:
            yield 'Dictionary is empty.'
        elif len(dictionary) == 1:
            yield 'Dictionary has one item:'
        else:
            yield f'Dictionary size is {len(dictionary)} and it contains following items:'
        for key in self.get_dictionary_keysget_dictionary_keys(dictionary):
            yield f'{key}: {dictionary[key]}'
 
    def _keys_should_be_equal(self, dict1, dict2, msg, values):
        keys1 = self.get_dictionary_keysget_dictionary_keys(dict1)
        keys2 = self.get_dictionary_keysget_dictionary_keys(dict2)
        miss1 = ', '.join(str(k) for k in keys2 if k not in dict1)
        miss2 = ', '.join(str(k) for k in keys1 if k not in dict2)
        error = []
        if miss1:
            error += [f'Following keys missing from first dictionary: {miss1}']
        if miss2:
            error += [f'Following keys missing from second dictionary: {miss2}']
        _verify_condition(not error, '\n'.join(error), msg, values)
        return keys1
 
    def _key_values_should_be_equal(self, keys, dict1, dict2, msg, values):
        diffs = '\n'.join(self._yield_dict_diffs_yield_dict_diffs(keys, dict1, dict2))
        _verify_condition(not diffs,
                          f'Following keys have different values:\n{diffs}',
                          msg, values)
 
    def _yield_dict_diffs(self, keys, dict1, dict2):
        for key in keys:
            try:
                assert_equal(dict1[key], dict2[key], msg=f'Key {key}')
            except AssertionError as err:
                yield str(err)
 
    def _validate_dictionary(self, dictionary, position=1):
        if not is_dict_like(dictionary):
            raise TypeError(f"Expected argument {position} to be a dictionary or "
                            f"dictionary-like, got {type_name(dictionary)} instead.")
 
 
 
class Collections(_List, _Dictionary):
    ROBOT_LIBRARY_SCOPE = 'GLOBAL'
    ROBOT_LIBRARY_VERSION = get_version()
 
    
    def should_contain_match(self, list, pattern, msg=None,
                             case_insensitive=False,
                             whitespace_insensitive=False):
        _List._validate_list(self, list)
        matches = _get_matches_in_iterable(list, pattern, case_insensitive,
                                           whitespace_insensitive)
        default = f"{seq2str2(list)} does not contain match for pattern '{pattern}'."
        _verify_condition(matches, default, msg)
 
    
    def should_not_contain_match(self, list, pattern, msg=None,
                                 case_insensitive=False,
                                 whitespace_insensitive=False):
        _List._validate_list(self, list)
        matches = _get_matches_in_iterable(list, pattern, case_insensitive,
                                           whitespace_insensitive)
        default = f"{seq2str2(list)} contains match for pattern '{pattern}'."
        _verify_condition(not matches, default, msg)
 
    
    def get_matches(self, list, pattern, case_insensitive=False,
                    whitespace_insensitive=False):
        _List._validate_list(self, list)
        return _get_matches_in_iterable(list, pattern, case_insensitive,
                                        whitespace_insensitive)
 
    
    def get_match_count(self, list, pattern, case_insensitive=False,
                        whitespace_insensitive=False):
        _List._validate_list(self, list)
        return len(self.get_matchesget_matches(list, pattern, case_insensitive,
                                    whitespace_insensitive))
 
 
def _verify_condition(condition, default_msg, msg, values=False):
    if condition:
        return
    if not msg:
        msg = default_msg
    elif is_truthy(values) and str(values).upper() != 'NO VALUES':
        msg += '\n' + default_msg
    raise AssertionError(msg)
 
 
def _get_matches_in_iterable(iterable, pattern, case_insensitive=False,
                             whitespace_insensitive=False):
    if not is_string(pattern):
        raise TypeError(f"Pattern must be string, got '{type_name(pattern)}'.")
    regexp = False
    if pattern.startswith('regexp='):
        pattern = pattern[7:]
        regexp = True
    elif pattern.startswith('glob='):
        pattern = pattern[5:]
    matcher = Matcher(pattern,
                      caseless=is_truthy(case_insensitive),
                      spaceless=is_truthy(whitespace_insensitive),
                      regexp=regexp)
    return [string for string in iterable
            if is_string(string) and matcher.match(string)]