requirements.txt против setup.py

requirements.txt:

Это поможет вам настроить среду разработки.

Такие программы, как pip, можно использовать для установки всех пакетов, перечисленных в файле, одним махом. После этого вы можете приступить к разработке своего скрипта на Python. Это особенно полезно, если вы планируете, чтобы другие участвовали в разработке или использовали виртуальные среды. Вот как вы его используете:

pip install -r requirements.txt

Это может быть легко произведено самим pip:

pip freeze > requirements.txt

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

setup.py:

Это помогает создавать пакеты, которые можно распространять.

Сценарий setup.py предназначен для установки вашего пакета в системе конечного пользователя, а не для подготовки среды разработки, как это делает pip install -r requirements.txt. См. этот ответ для получения дополнительных сведений о setup.py.

Зависимости вашего проекта перечислены в обоих файлах.

Короткий ответ: requirements.txt предназначен только для перечисления требований к пакету. setup.py с другой стороны, больше похож на сценарий установки. Если вы не планируете устанавливать код Python, обычно вам понадобится только requirements.txt.

Файл setup.py описывает, помимо зависимостей пакетов, набор файлов и модулей, которые должны быть упакованы (или скомпилированы, в случае собственных модулей (т. Е. Написанных на C)), и метаданные для добавления в списки пакетов python. (например, название пакета, версия пакета, описание пакета, автор, ...).

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

requirements.txt

В этом файле перечислены требования к пакету Python. Это простой текстовый файл (необязательно с комментариями), в котором перечислены зависимости пакета вашего проекта python (по одному в каждой строке). Он не описывает способ установки вашего пакета python. Обычно вы используете файл требований с pip install -r requirements.txt.

Имя текстового файла может быть произвольным, но часто requirements.txt условно. Изучая репозитории исходного кода других пакетов Python, вы можете наткнуться на другие имена, такие как dev-dependencies.txt или dependencies-dev.txt. Они служат той же цели, что и dependencies.txt, но обычно содержат список дополнительных зависимостей, представляющих интерес для разработчиков конкретного пакета, а именно для тестирования исходного кода (например, pytest, pylint и т. Д.) Перед выпуском. Пользователям пакета обычно не требуется весь набор зависимостей разработчика для запуска пакета.

Если присутствует несколько вариантовrequirements-X.txt, то обычно в одном будут перечислены зависимости времени выполнения, а в другом - зависимости времени сборки или тестирования. Некоторые проекты также каскадируют свои файлы требований, т.е. когда один файл требований включает другой файл (пример). Это может уменьшить количество повторений.

setup.py

Это сценарий python, который использует модуль setuptools для определения пакета python (имя, включенные файлы, метаданные пакета и установка). Он, как и requirements.txt, также перечисляет зависимости пакета во время выполнения. Setuptools - это де-факто способ создания и установки пакетов Python, но у него есть свои недостатки, которые со временем привели к разработке новых «менеджеров метапакетов», таких как pip. Примеры недостатков средств установки - невозможность установить несколько версий одного и того же пакета и отсутствие команды удаления.

Когда пользователь python выполняет pip install ./pkgdir_my_module (или pip install my-module), pip запускает setup.py в данном каталоге (или модуле). Точно так же любой модуль с setup.py может быть pip установлен, например запустив pip install . из той же папки.

Мне действительно нужны оба?

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

Вы можете воспользоваться одной уловкой, чтобы избежать дублирования списка зависимостей между requirements.txt и setup.py. Если вы уже написали полностью рабочий setup.py для своего пакета и ваши зависимости в основном внешние, вы можете подумать о простом requirements.txt только со следующим:

 # requirements.txt
 #
 # installs dependencies from ./setup.py, and the package itself,
 # in editable mode
 -e .

 # (the -e above is optional). you could also just install the package
 # normally with just the line below (after uncommenting)
 # .

-e - это специальный pip install параметр, который устанавливает данный пакет в редактируемом режиме. Когда pip -r requirements.txt запущен для этого файла, pip установит ваши зависимости через список в ./setup.py. Редактируемый вариант поместит символическую ссылку в ваш установочный каталог (вместо яйца или заархивированной копии). Это позволяет разработчикам редактировать код на месте из репозитория без переустановки.

Вы также можете воспользоваться так называемыми «дополнительными функциями setuptools», когда у вас есть оба файла в репозитории пакетов. Вы можете определить дополнительные пакеты в setup.py в настраиваемой категории и установить эти пакеты только из этой категории с помощью pip:

# setup.py
from setuptools import setup
setup(
   name="FOO"
   ...
   extras_require = {
       'dev': ['pylint'],
       'build': ['requests']
   }
   ...
)

а затем в файле требований:

# install packages in the [build] category, from setup.py
# (path/to/mypkg is the directory where setup.py is)
-e path/to/mypkg[build]

Это сохранит все ваши списки зависимостей внутри setup.py.

Примечание. Обычно pip и setup.py выполняются из песочницы, например, созданной с помощью программы virtualenv. Это позволит избежать установки пакетов Python вне контекста среды разработки вашего проекта.

Для полноты картины вот как я это вижу в 3 4 разных ракурсах.

1. Их конструктивное предназначение различно

Это точное описание, цитируемое в официальной документации (курсив мой):

В то время как install_requires (в setup.py) определяет зависимости для одного проекта, файлы требований часто используются для определения требований для полной среды Python.

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

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

2. Таким образом, их фактическое использование (предполагается) различное.

• Если ваш проект foo будет выпущен как отдельная библиотека (это означает, что другие, вероятно, будут использовать import foo), тогда вы (и ваши последующие пользователи) захотите иметь гибкое объявление зависимости, чтобы ваша библиотека (и она не должен) быть разборчивым в том, какой именно должна быть версия ВАШИХ зависимостей. Итак, обычно ваш setup.py будет содержать такие строки:

       install_requires=[
           'A>=1,<2',
           'B>=2'
       ]
  

• Если вы просто хотите каким-то образом задокументировать или закрепить вашу ТОЧНУЮ текущую среду для вашего приложения bar, то есть вы или ваши пользователи хотели бы использовать ваше приложение bar как есть, то есть при запуске python bar.py, вы можете заморозить свою среду, чтобы она всегда веди себя одинаково. В таком случае ваш файл требований будет выглядеть так:

       A==1.2.3
       B==2.3.4
       # It could even contain some dependencies NOT strickly required by your library
       pylint==3.4.5
  

3. На самом деле, что мне использовать?

   • Если вы разрабатываете приложение bar, которое будет использоваться python bar.py, даже если это просто сценарий для развлечения, вам все равно рекомендуется использовать файл requirements.txt, потому что, кто знает, на следующей неделе (а это Рождество) вы получите новый компьютер в подарок, так что вам нужно будет снова настроить там вашу точную среду.

   • Если вы разрабатываете библиотеку foo, которая будет использоваться import foo, вам необходимо подготовить setup.py. Период. Но вы все равно можете одновременно предоставить файл requirements.txt, который может:

     (а) быть в стиле A==1.2.3 (как объяснено в пункте 2 выше);

     (б) или просто содержать волшебный сингл .

        .
     

     Последний по существу использует обычную requirements.txt привычку документировать шаг установки pip install ., что означает установку требований на основе setup.py без дублирования. Лично я считаю, что этот последний подход размывает границы, добавляет путаницы, но, тем не менее, это удобный способ явно отказаться от закрепления зависимостей при работе в среде CI. Уловка была получена из подхода, упомянутого разработчиком упаковки Python Дональдом в своем сообщении в блоге.

4. Различные нижние оценки.

   Предполагая, что существует engine библиотека с этой историей:

   engine 1.1.0 Use steam
   ...
   engine 1.2.0 Internal combustion is invented
   engine 1.2.1 Fix engine leaking oil
   engine 1.2.2 Fix engine overheat
   engine 1.2.3 Fix occasional engine stalling
   
   engine 2.0.0 Introducing nuclear reactor
   

   Вы следуете трем вышеуказанным критериям и правильно решили, что ваша новая библиотека hybrid-engine будет использовать setup.py для объявления своей зависимости engine>=1.2.0,<2, а затем ваше отдельное приложение reliable-car будет использовать requirements.txt для объявления своей зависимости engine>=1.2.3,<2 (или вы можете просто закрепить engine==1.2.3). Как видите, ваш выбор для их числа нижней границы все еще немного отличается, и ни один из них не использует последнюю engine==2.0.0. И вот почему.

   • hybrid-engine зависит от engine>=1.2.0, потому что необходимый add_fuel() API был впервые представлен в engine 1.2.0, и эта возможность является необходимостью hybrid-engine, независимо от того, могут ли быть некоторые (незначительные) ошибки внутри такой версии и исправлены в последующих версиях 1.2.1, 1.2 .2 и 1.2.3.

   • reliable-car зависит от engine>=1.2.3, потому что это самая ранняя версия БЕЗ известных проблем. Конечно, в более поздних версиях есть новые возможности, например, ядерный реактор, представленный в engine 2.0.0, но они не обязательно желательны для проекта reliable-car. (Ваш еще один новый проект time-machine, вероятно, будет использовать engine>=2.0.0, но это уже другая тема.)