====== Работа с переменными окружения ======

===== get_env() =====

Получение параметра из переменной окружения

Функция вычитывает из переменной окружения параметр, преобразовывает к нужному типу и возвращает.

<code python>
get_env(name, type_name, [default], [mandatory])
</code>

^ Параметр ^ Тип ^ Описание ^
| ''name'' | ''str'' | Имя переменной из которой получаем параметр |
| ''type_name'' | ''type'' | Имя типа в который следует преобразовать данный параметр. В качестве типов можно использовать [[.::type_helper|адаптеры типов]] |
| ''default'' | ''Any'' | Значение по умолчанию для данного параметра, в случае его отсутствия в переменных окружения. По умолчанию ''None'' |
| ''mandatory'' | ''bool'' | Обязательный параметр? Если параметр обязательный и в переменных окружения он отсутствует, а значение по умолчанию не заданно, то возникает исключение ''EnvConfigError'' |

----

**Возвращаемое значение:** Значение переменной окружения, приведённое к заданному типу, либо значение по умолчанию.

**Внимание!** Значение по умолчанию к заданному типу не приводится, а возвращается ровно в том виде, в котором было заданно при вызове функции


====== Инструменты поддержки ======

===== get_app_root() =====

Функция определения абсолютного пути к имени директории, в которой расположено приложение.

Функция построена на логике, когда python-модуль приложения расположен в корне директории данного приложения. Возвращается самая первая директория, которая не содержит обязательный для всех модулей файл ''%%__init__%%.py''. При наличии собственного стандарта размещения приложения в файловой системе, эту особенность нужно держать в голове.

<code>
get_app_root(file_name)
</code>

**Возвращает:** Полный путь к директории размещения модуля, файл которой дан в качестве аргумента

^ Параметр ^ Значение ^
| ''file_name'' | Имя файла, составляющего модуль python |

----

Предлагаемое использование: в процессе разбора конфигураций вызов функции в форме:
<code python>
APP_PATH = get_app_root(__file__)
</code>


====== Хранение объектов конфигурации ======

Предполагается, что конфигурация приложения состоит из набора объектов (либо [[https://docs.python.org/3/library/collections.html#collections.namedtuple|namedtuple]] либо [[https://docs.python.org/3/library/dataclasses.html|dataclass]]) в которых собраны параметры необходимые для каждого из компонентов приложения. Для упрощения работы с ними, данные объекты могу быть сохранены на этапе разбора конфигурации и отданы на этапе работы модуля предоставленным Библиотекой API.

**Не производится защиты конфиденциальных данных. Этот вопрос остаётся за программистом**

В случае ошибок преобразования при работе функций модуля возникает исключение ''AppConfManagerError''


===== init_configs() =====

Инициализировать Хранилище.

В рамках операции производится очистка хранилища. Данная операция должна быть выполнена перед использованием.

<code>
init_configs()
</code>


===== add_config() =====

Добавление в хранилище объекта конфигурации.

При попытке повторной вставки элемента с имеющимся идентификатором, возникает исключение ''AppConfManagerError''.

<code>
add_config(conf_selector, conf_obj)
</code>

^ Параметр ^ Описание ^
| ''conf_selector'' | Элемент, с использованием которого можно получить данный конфигурационный объект в будущем. Здесь может использоваться всё, что пригодно для Python в качестве ключа словаря. Например: Объект типа класса данных (скажем если определено ''DBConfig = namedtuple(...)'', то этот самый ''DBConfig'' вполне подойдёт для идентификатора) |
| ''conf_obj'' | Собственно объект конфигурации. Так же не накладывается ограничений на тип аргумента |

Пример: <code python>
add_config(NetConfig, NetConfig(
   port=root_section.get_value('port', int, 8080),
   baseurl=root_section.get_value('baseurl', str)
)
</code>


===== replace_config() =====

Заменяет объект с заданным идентификатором в хранилище на новый, указанный в параметрах.

<code>
replace_config(conf_selector, conf_obj)
</code>

^ Параметр ^ Описание ^
| ''conf_selector'' | Идентификатор объекта конфигурации. См. [[#add_config]] |
| ''conf_obj'' | Собственно объект конфигурации. См. [[#add_config]] |


===== get_config() =====

Получаем из хранилища добавленный ранее объект конфигурации по идентификатору.

Если объект не добавлен, возникает исключение ''AppConfNotFound''

<code>
get_config(conf_selector)
</code>

^ Параметр ^ Описание ^
| ''conf_selector'' | Идентификатор добавленного ранее объекта конфигурации |