Рекомендации MeilleursAgents по созданию поддерживаемых библиотек Python.

Эта статья является частью серии о методах внутренней веб-разработки в MeilleursAgents. Это внутренние документы, которые мы публикуем, чтобы рассказать о нашей работе и получить отзывы от сообщества.

Мы возьмем в качестве примера библиотеку с именем _1 _, _ 2_, если для MeilleursAgents и наших библиотек этот префикс должен быть.

Именование

Корневая папка: MA-Super-Lib

Пакет исходного кода: ma_super_lib

Название библиотеки: ma-super-lib

Структура папки

MA-Super-Lib/
  dist/
  ma_super_lib/
  tests/
  Jenkinsfile
  Makefile
  MANIFEST.in
  README.md
  setup.cfg
  setup.py

Конфигурация

setup.py

setup.cfg

MANIFEST.in

см. https://docs.python.org/3/distutils/sourcedist.html#specifying-the-files-to-distribute

Мы используем packages=find_packages()in setup.py, поэтому все файлы и пакеты в каталоге setup.py будут включены. Но мы не хотим добавлять каталог tests в раздачу, prune tests удаляет каталог tests из раздачи

⚠️ почему бы не использовать find_packages для исключения тестов в первую очередь? Насколько нам известно, если вы сделаете это, вы не сможете линтовать пакет tests.

Makefile

Управление версиями

Используйте семантическое управление версиями: https://semver.org/

Для идентификаторов версий следуйте этой спецификации PEP: https://www.python.org/dev/peps/pep-0440

Должен ли я закреплять свои версии зависимостей?

install_requires and extras_require

Используйте диапазоны версий: основные версии как максимальную версию и текущую версию как минимальную версию.

Почему?

Несмотря на то, что каждый проект MeilleursAgents, использующий вашу библиотеку, будет закреплять версию вашей библиотеки и ее зависимостей, мы не хотим, чтобы библиотека ломалась при появлении новых версий ее зависимостей.

Вот график, который нам не нужен:

  • день 1: есть потребность в библиотеке по проекту P, мы решаем внедрить MA-Super-Lib
  • День 10: опубликована MA-Super-Lib с зависимостью D, D не является библиотекой MeilleursAgents и не имеет закрепленной версии, версия MA-Super-Lib - 1.0.0
  • День 11: проект P использует MA-Super-Lib, он связывает версию MA-Super-Lib с 1.0.0 и версию зависимости D с 3.4.5
  • день 150: опубликована новая версия зависимости D: 4.0.0 ⇒ риск поломки изменений
  • День 200: запускается проект Q, разработчики решают использовать MA-Super-Lib, но, к их удивлению, он больше не работает, версия 4.0.0 зависимости D вносит критическое изменение, которое делает его несовместимым с реализацией MA-Super- Lib

Почему бы не закрепить версию вместо использования диапазонов версий?

Это слишком ограничительно и в конечном итоге станет проблемой, если ваш проект или его зависимости используют общие зависимости с вашей библиотекой.

Вот график, который нам не нужен:

  • день 1: есть потребность в библиотеке по проекту P, мы решаем внедрить MA-Super-Lib
  • день 10: опубликован MA-Super-Lib с зависимостью D, D не является библиотекой MeilleursAgents, версия MA-Super-Lib - 1.0.0, а версия зависимости D - 3.4.5.
  • День 11: проект P использует MA-Super-Lib и библиотеку L, MA-Super-Lib и L разделяют зависимость D, но L требует D == 3.4.5, а M требует D ›3.5,‹ 4 ⇒ несовместимость версий

Недостатки использования диапазонов версий

Теоретически диапазоны версий позволяют нам убедиться, что наши библиотеки будут работать, избегая конфликтов версий в проектах, использующих наши библиотеки. НО это верно только в том случае, если разработчики библиотек придерживаются семвера, это не всегда так, и это очень не в наших руках.

setup_requires and tests_require

Не используйте диапазоны версий, получите последние версии ваших зависимостей.

Почему?

Эти зависимости используются для разработки и не будут частью вашей библиотеки. Используйте последние версии своих инструментов разработки, чтобы получить последние изменения: новые рекомендации по стилю flake8, новые параметры pytest и т. Д.

Когда происходит сбой настройки или тестов

ВЫ несете ответственность за то, чтобы предупредить команду, если это произойдет.

ВАМ НЕ нужно исправлять все библиотеки, используя эту зависимость.

Если вы можете исправить это, отлично: исправьте это и добавьте билет в библиотеки списков технических невыполненных работ, используя его.

Если вы не можете это исправить: обратитесь за помощью и добавьте тикет в библиотеки, перечисляющие невыполненные технические задания, используя его.

Не все наши библиотеки находятся в активной стадии разработки, что означает, что у нас есть время проанализировать и исправить проблему во всех наших библиотеках.

Жизненный цикл разработки

Локально

В проектах, использующих вашу библиотеку, установите вашу библиотеку локально, используя pip install -e /local/path/to/your/library, чтобы вам не приходилось публиковать выпуски для каждого изменения, которое вы вносите в свою библиотеку.

Непрерывная интеграция

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

Публикуйте промежуточные разрабатываемые версии и следуйте PEP440 для разрабатываемых выпусков:

0.0.1.dev0  # first development release
0.0.1.dev1  # second development release
1.0.0       # first stable release
1.0.1.dev0  # bugfix development
1.0.1       # bugfix release

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

Допустим, вам нужно реализовать новую функцию, которая требует от вас редактирования библиотеки:

⚠️ Не объединяйте разрабатываемые версии. Прямо сейчас ничто не мешает вам сделать это, будьте осторожны.

Издательский

Непрерывная интеграция заботится о публикации релизов.

Для выпусков разработки используйте make build и make distribute, мы используем packagecloud для управления нашими пакетами. Все, что вам нужно, это .packagecloud в вашем домашнем каталоге.

Разное

Почему бы не использовать pip для обработки требований?

Используйте как можно меньше инструментов! Setuptools достаточно (для библиотек).

Если вы заинтересованы в присоединении к MeilleursAgents, мы ищем! Загляните на нашу доску вакансий, чтобы узнать, найдется ли для вас роль!