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

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

0 голосов
/ 05 марта 2019

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

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

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

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

1 Ответ

0 голосов
/ 16 июля 2019

Лично мне нравится использовать модуль 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 репозитория .

...