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

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


====== Работа с файлом конфигурации ======

Конструктор объекта ''ConfigFile'' принимает путь к файлу конфигурации. Путь задаётся строкой и может быть относительным.

<code python>
conf_file = ConfigFile('/etc/application.conf')
</code>

Далее объект ''ConfigFileContent'' можно получить либо вызвав метод ''get()'', либо, что более предпочтительно, воспользовавшись менеджером контекста:

<code python>
with ConfigFile(config_file) as root_section:
  port = root_section.get_value('port', int, 8080)
</code>

Особенно хорошо и лаконично получается при использовании хранилища конфигураций:
<code python>
with ConfigFile('/etc/application.conf') as root_section:
    add_config(NetConfig, NetConfig(
        port=root_section.get_value('port', int, 8080),
        baseurl=root_section.get_value('baseurl', str)
    ))
</code>

Иной работы объекты класса ''ConfigFile'' не делают.


===== Работа с параметрами конфигурации =====

Как известно, файлы конфигурации в формате toml легко можно представить в виде словаря Python (либо JSON-объекта). Для работы с одним уровнем данного словаря и создан класс ''ConfigFileContent''. Он даёт API работы с параметрами на данном текущем уровне.


==== 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>