configtoolkit 0.1.2
Another configuration library

# Configtoolkit
Another configuration library

### О библиотеке
**Configtoolkit** это простая библиотека для импорта конфигураций python скриптами  
**Configtoolkit** позволяет удобно настроить цепочку импорта конфигурационных значений 
из различных источников вида:

Попытаться получить значение из источника A ->  
-> при неудаче из источника B ->  
-> при неудаче из источника C ->  
-> при неудаче использовать значение по умолчанию  

Также имеется возможность проверять все значения цепочки на соответствие 
заданному типу или использовать для них собственную функцию валидации, 
отбрасывая не прошедших проверку

**Configtoolkit** решает проблему отличия False и Null значений от 
отсутствующих в классической реализации импорта конфигураций вида

`VALUE = somesource.get("VALUE") | someothersource.get("VALUE") | DEFAULT`

Для этого предоставляется класс-обертка **ConfigValue**, содержащий помимо
самого значения, флаг его существования в источнике

**Configtoolkit** содержит готовые классы для импорта значений из
* системных аргументов
* переменных окружения
* объектов, файлов, модулей и структур данных python
* форматов
    * Json
    * Yaml
    * Toml
### Установка
Библиотека устанавливается и обновляется через pip

    $ pip install configtoolkit

### Применение
#### - Функция get_config_value
Для импорта конфигураций из цепочки источников используется функция **get_config_value**, 
принимающая единственный обязательный параметр **values:list** в который 
должен передаваться список объектов конфигураций  

В этом списке могут быть как объекты класса **ConfigValue**, 
так и любых других типов  
Значения передаваемы в обертке **ConfigValue** считаются валидными только если 
флаг exist установлен в True  
Объекты всех других типов считаются валидными автоматически

Также, каждый элемент списка **values** может проверяться на соответствие типу  
Для этого требуемый тип должен быть передан в необязательный параметр **value_type**

Также, можно использовать кастомную функцию для проверки каждого значения  
Для этого данную функцию следует передать в необязательный параметр **validator**  
Эта функция должна принимать проверяемое значение и возвращать bool флаг, 
для которого True означает что значение валидно, а False что не валидно

Функция **get_config_value** перебирает список **values** пока не обнаружит
первое значение, проходящее все проверки  
Данное значение функция и возвращает

В случае если не нашлось не одного подходящего значения, 
выбрасывается исключение **ImpossibleToGetValue**

В функцию может быть передан необязательный параметр **default**  
Передача значения таким образом эквивалентна добавлению его в конец списка **values**, 
однако использование этого параметра улучшает читабельность кода 

Вы также можете передать необязательный флаг **return_source_value**, 
для того чтобы функция **get_config_value**, вернула 
вместо полученного значения, список 
состоящий из этого значения и его объекта-источника  
Если результат был получен из константного значения, 
то в качестве источника возвращается Null

#### - Функция not_none_config_value
Если вы передаете в параметр **values** функции **get_config_value** 
неконстантное конфигурационное значение, полученное без использования 
классов провайдеров, рассмотренных ниже, вам может потребоваться, 
чтобы значение Null или False расценивались как отсутствие значения

В таком случае вы можете использовать функцию **not_none_config_value**  
Она принимает значение любого типа и оборачивает его в **ConfigValue**, 
если оно не Null или False, иначе возвращая пустой объект **ConfigValue** 
с флагом exist установленным в False

#### - Класс ConfigValue
Данный класс является оберткой для значений передаваемых в **get_config_value**, 
содержащий также флаг exist, указывающий на существование этого значения в 
источнике из которого получена конфигурация, 
а также поле source указывающее на источник значения 

**Configtoolkit** предоставляет классы-провайдеры для извлечения конфигураций 
из различных источников:

#### - Классы ArgsConfigProvider и SysArgsConfigProvider
Служат для импортирования конфигурации из аргументов командной строки  

Класс **ArgsConfigProvider** принимает эти аргументы в конструкторе в виде списка  
Класс **SysArgsConfigProvider** самостоятельно получает аргументы переданные программе

Оба класса содержат следующие методы:  
#### -- get_value_for_key(key: str) -> ConfigValue:
Принимает имя ключа в виде строки и возвращает 
либо найденное по этому ключу значение обернутое в **ConfigValue**, 
либо пустой объект **ConfigValue**

#### -- if_key_contains(key: str) -> ConfigValue:
Принимает имя ключа в виде строки и возвращает 
значение True, обернутое в **ConfigValue** если ключ присутствует, 
либо пустой объект **ConfigValue**

#### -- if_not_key_contains(key: str) -> ConfigValue:
Принимает имя ключа в виде строки и возвращает 
значение False, обернутое в **ConfigValue** если ключ отсутствует, 
либо пустой объект **ConfigValue**

#### -- is_key_contains(key: str) -> ConfigValue:
Принимает имя ключа в виде строки и возвращает 
значение Tru или False, в зависимости от наличия ключа, обернутое в **ConfigValue**

#### - Класс DictConfigProvider
Служит для импортирования конфигурации из словаря python,
а также вложенных в него словарей или списков

Принимает в конструкторе словарь, как единственный параметр

Этот класс, и все наследующиеся от него содержат метод

#### -- get(*keys) -> ConfigValue
Который извлекает из источника конфигурации, с которым работает этот объект, 
данные по ключу  
Для получения значения из вложенных структур данных может передаваться множество ключей

#### - Класс EnvironConfigProvider
Служит для импортирования конфигурации из переменных окружения  

Наследуется от **DictConfigProvider**

#### - Классы PyObjectConfigProvider и PyModuleConfigProvider
Служат для импортирования конфигурации из объектов python  
В отличие от **DictConfigProvider** работают не только 
со словарями и массивами, но и с любыми другими объектами, обращаясь к их полям

Класс **PyObjectConfigProvider** получает объект непосредственно в конструкторе  
Класс **PyModuleConfigProvider** получает в конструкторе имя модуля или файла python, 
импортирует его и работает с его содержимым

Наследуются от **DictConfigProvider**

#### - Классы JSONConfigProvider и JSONFileConfigProvider
Служат для импортирования конфигурации из формата json

Класс **JSONConfigProvider** получает в конструкторе строку с данными в json формате  
Класс **JSONFileConfigProvider** получает в конструкторе имя файла с содержимым в json формате

Наследуются от **DictConfigProvider**

#### - Классы YAMLConfigProvider и YAMLFileConfigProvider
Служат для импортирования конфигурации из формата yaml

Класс **YAMLConfigProvider** получает в конструкторе строку с данными в yaml формате  
Класс **YAMLFileConfigProvider** получает в конструкторе имя файла с содержимым в yaml формате

Наследуются от **DictConfigProvider**

#### - Классы TOMLConfigProvider и TOMLFileConfigProvider
Служат для импортирования конфигурации из формата toml

Класс **TOMLConfigProvider** получает в конструкторе строку с данными в toml формате  
Класс **TOMLFileConfigProvider** получает в конструкторе имя файла с содержимым в toml формате

Наследуются от **DictConfigProvider**