====== Общее ======

В качестве формата конфигурационных файлов принят [[https://toml.io/en/|toml]]. Разбор конфигурации построен на 2-х объектах:
  * ''ConfigFile'' - обрабатывает файл целиком и предоставляет интерфейс работы с конфигурацией.
  * ''ConfigFileContent'' - обрабатывает секции файла, давая интерфейс доступа к элементам конфигурации.


==== get_value() ====

Получить значение параметра из файла.

<code python>
obj.get_value(name, [val_type], [default], [mandatory])
</code>

**Возвращает:** Значение параметра, приведённое к заданному типу.

^ Параметр ^ Тип параметра ^ Значение по умолчанию ^ Описание ^
| ''name'' | ''str'' | -- | Имя параметра, каким оно задано в файле конфигурации |
| ''val_type'' | Тип аргумента | ''str'' | Тип значения. Может быть любым идентификатором типа python, через которое можно вызвать преобразование в данный тип ( ''type(param)'') либо [[.:type_helper|адаптер типа]] данной библиотеки |
| ''default'' | ''Any'' | ''None'' | Значение по умолчанию для параметра. Тип его не проверяется на соответствие заданному в параметрах. |
| ''mandatory'' | ''bool'' | ''True'' | Является ли значение обязательным? Если да, то при отсутствии значения по умолчанию и самого значения в файле, будет возбуждено исключение. В противном случае метод тихо вернёт ''None'' |

----

Пример использования дан выше.


==== get_section() ====

Погрузиться на уровень ниже по словарю конфигурации.

Это позволяет выполнить чтение подуровней конфигурационного файла относительно текущего.

<code>
obj.get_section(name, [mandatory])
</code>

**Возвращает:** Объект ''ConfigFileContent'' содержимого нижележашего уровня.

^ Параметр ^ Тип ^ Описание ^
| ''name'' | ''str'' | Имя секции, как оно задано в файле |
| ''mandatory'' | ''bool'' | Является ли секция обязательной. Если да, и она отсутствует, то возбуждается исключение ''ConfigSectionNotFound''. В противном случае возвращается пустая секция, не содержащая параметров. //По умолчанию// ''True'' |

Для работы с секциями можно применять менеджер контекста. Например для файла с содержимым:
<code toml>
[section]
param1 = "value1"
</code>

Можно применить следующий код: 
<code python>
with ConfigFile('/etc/application.conf') as root_section:
    with root_section.get_section('section') as section_section:
        param1 = section_section.get_value('parma1')
</code>


==== get_list_section() ====

Подобен ''get_section()'', но ожидает увидеть либо словарь, либо список словарей.

<code>
obj.get_list_section(name, [mandatory])
</code>

**Возвращает:** Массив объектов ''ConfigFileContent'' содержимого нижележащего уровня.

^ Параметр ^ Тип ^ Описание ^
| ''name'' | ''str'' | Имя секции, как оно задано в файле |
| ''mandatory'' | ''bool'' | Является ли секция обязательной. Если да, и она отсутствует, то возбуждается исключение ''ConfigSectionNotFound''. В противном случае возвращается пустая секция, не содержащая параметров. //По умолчанию// ''True'' |

Для работы с секциями можно применять менеджер контекста. Например для файла с содержимым:
<code toml>
[[section]]
param = "value1"

[[section]]
param = "value2"
</code>

Можно применить следующий код: 
<code python>
with ConfigFile('/etc/application.conf') as root_section:
    with root_sectin.get_list_section('section') as section_section:
        conf_ar = []
        for el in net_section:
            conf_ar.append(dict(
                param1 = el.get_value('parma1')
            ))
 
</code>


==== get_section_by_path() ====

Подобен ''get_section()'', но позволяет пройти по иерархии дальше чем на один уровень. Каждый уровень указывается отдельным параметром

<code>
obj.get_section_by_path(name, ..., [mandatory=False])
</code>

**Возвращает:** Объект ''ConfigFileContent'' содержимого нижележашего уровня.

^ Параметр ^ Тип ^ Описание ^
| ''name'' | ''str'' | Имя секции, как оно задано в файле. Параметр можно задавать несколько раз |
| ''mandatory'' | ''bool'' | Является ли секция обязательной. Если да, и она отсутствует, то возбуждается исключение ''ConfigSectionNotFound''. В противном случае возвращается пустая секция, не содержащая параметров. //По умолчанию// ''True''. Задаётся **ТОЛЬКО** в формате ключ-значение |

Для работы с секциями можно применять менеджер контекста. Например для файла с содержимым:
<code toml>
[section.section2]
param1 = "value1"
</code>

Можно применить следующий код: 
<code python>
with ConfigFile('/etc/application.conf') as root_section:
    with root_section.get_section_by_path('section', 'section2') as section_section:
        param1 = section_section.get_value('parma1')
</code>