Как документировать файлы конфигурации?

Существуют ли какие-либо рекомендации по документации конфигурационного файла, особенно для python?

В частности, в научных вычислениях обычно используется файл конфигурации в качестве входных данных для управления заданием пакетной обработки (например, моделированием) и ожидается, что пользователь настроит значительную часть конфигурации для своего сценария. (Конфигурация также, вероятно, выбирает между различными модулями обработки, каждый из которых имеет разные наборы полей конфигурации.) Таким образом, пользователь должен знать: что означает или влияет каждый параметр; какие настройки не используются (при каких обстоятельствах); каковы значения по умолчанию (и допустимые значения или диапазоны); и т. д.

Я обнаружил, что неполные документы файла конфигурации являются обычным явлением. Фундаментальная проблема заключается в том, что если документы поддерживаются отдельно от кода, они рассинхронизируются. (Это кажется меньшей проблемой с документами API из-за стандартных практик, включающих совмещенные строки документации и автогенерацию из сигнатур функций/argspec.) Например, если стандартный python configparser используется один раз для анализа файла конфигурации, тогда код для доступа к отдельным атрибутам ( и неявное определение схемы конфигурации) по-прежнему могут быть распределены по всей базе кода (и, возможно, доступны только во время выполнения, а не при создании документации).

Дальнейшие мысли:

  • Является ли плохой практикой замена файла конфигурации (yaml или аналогичного) на настраиваемый пользователем скрипт Python (чтобы требовались только документы API)?
  • Раздача хорошо прокомментированного примера файла конфигурации (который также используется в автоматических тестах): как вести себя, если разные сценарии дублируют большие разделы, но нужны совершенно разные поля?
  • Можно ли поддерживать единую схему как для использования в коде (чтобы помочь синтаксическому анализу, проверке и установке значений по умолчанию), так и для создания документов каким-либо образом?
  • Существует ли доступный для чтения/записи способ (де)сериализации состояния некоторого экземпляра (под)класса, который представляет новый пакетный процесс (чтобы конфигурация была покрыта существующей документацией)?

python configuration documentation maintainability
person benjimin    schedule 05.03.2019    source источник

Ответы (1)


arrow_upward
1
arrow_downward

Лично мне нравится использовать модуль argparse для настройки и считывать значение по умолчанию для каждого параметра из переменной среды. Это централизует настройки и документацию в одном месте и позволяет пользователю либо настраивать параметры в командной строке, либо устанавливать и забывать их в переменных среды. Однако будьте осторожны с вводом паролей в командную строку, потому что другие пользователи, вероятно, увидят ваши аргументы командной строки в списке процессов.

Вот пример, в котором используются argparse и среда переменные:

def parse_args(argv=None):
    parser = ArgumentParser(description='Watch the raw data folder for new runs.',
                            formatter_class=ArgumentDefaultsHelpFormatter)
    parser.add_argument(
        '--kive_server',
        default=os.environ.get('MICALL_KIVE_SERVER', 'http://localhost:8000'),
        help='server to send runs to')
    parser.add_argument(
        '--kive_user',
        default=os.environ.get('MICALL_KIVE_USER', 'kive'),
        help='user name for Kive server')
    parser.add_argument(
        '--kive_password',
        default=SUPPRESS,
        help='password for Kive server (default not shown)')

    args = parser.parse_args(argv)
    if not hasattr(args, 'kive_password'):
        args.kive_password = os.environ.get('MICALL_KIVE_PASSWORD', 'kive')
    return args

Установка этих переменных среды может быть немного запутанной, особенно для системных служб. Если вы используете systemd, загляните в службу. , и будьте осторожны, чтобы использовать EnvironmentFile вместо Environment для любых секретов. Environment значений может просматривать любой пользователь с systemctl show.

Обычно я делаю значения по умолчанию полезными для разработчика, работающего на своей рабочей станции, чтобы он мог начать разработку без изменения какой-либо конфигурации.

Другой вариант — поместить параметры конфигурации в файл settings.py и просто быть осторожным, чтобы не зафиксировать этот файл в системе управления версиями. Я часто коммитил файл settings_template.py, который пользователи могут копировать.

Если ваши настройки настолько сложны/гибки, что переменные среды или файл настроек становятся беспорядочными, я бы преобразовал проект в библиотеку с API. Вместо настроек пользователи затем пишут скрипт, который вызывает ваш API. Вам также не нужно прилагать усилия для размещения вашей библиотеки на PyPI. pip можно установить, например, из репозитория GitHub.

person Don Kirkby    schedule 16.07.2019