requirements.txt vs setup.py

Question

J'ai commencé à travailler avec Python. J'ai ajouté requirements.txt y setup.py à mon projet. Mais je ne sais toujours pas à quoi servent ces deux fichiers. J'ai lu que setup.py est conçu pour des choses redistribuables et que requirements.txt est conçu pour les choses non redistribuables. Mais je ne suis pas certain que cela soit exact.

Comment ces deux fichiers sont-ils réellement destinés à être utilisés ?

Answer 1

exigences.txt

Cela vous aide à configurer votre environnement de développement. Des programmes comme pip peut être utilisé pour installer tous les paquets listés dans le fichier en une seule fois. Après cela, vous pouvez commencer à développer votre script python. Particulièrement utile si vous prévoyez que d'autres personnes contribuent au développement ou utilisent des environnements virtuels. Voici comment l'utiliser :

pip install -r < requirements.txt

setup.py

Cela vous permet de créer des paquets que vous pouvez redistribuer. Ce script a pour but d'installer votre paquet sur le système de l'utilisateur final, et non de préparer l'environnement de développement comme pip install -r < requirements.txt fait. Voir cette réponse pour plus de détails sur le fichier setup.py.

Les dépendances de votre projet sont listées dans les deux fichiers.

Answer 2

La réponse courte est que requirements.txt ne sert qu'à énumérer les exigences du paquet. setup.py d'autre part est plus comme une installation script. setup.py décrit, en plus des dépendances du paquet, l'ensemble des fichiers et modules qui doivent être empaquetés (ou compilés, dans le cas de modules natifs (c'est-à-dire écrits en C)), et les métadonnées à ajouter aux listes de paquets python (par exemple le nom du paquet, la version du paquet, la description du paquet, l'auteur, ...).

Comme les deux fichiers listent les dépendances, cela peut conduire à un peu de duplication. Lisez ci-dessous pour plus de détails.

exigences.txt

---

Ce fichier liste les exigences du paquetage python. Il s'agit d'un fichier texte brut (avec éventuellement des commentaires) qui répertorie le paquetage Dépendances de votre projet python (un par ligne). Il s'agit de n'est pas décrivent la manière dont votre paquetage python est installé. Vous consommerez généralement le fichier d'exigences avec pip install -r requirements.txt .

Le nom de fichier du fichier texte est arbitraire, mais est souvent requirements.txt par convention. En explorant les dépôts de code source d'autres paquets python, vous pouvez tomber sur d'autres noms, tels que dev-dependencies.txt o dependencies-dev.txt . Ils servent le même objectif que dependencies.txt mais listent généralement les dépendances supplémentaires qui intéressent les développeurs du paquet particulier, notamment pour tester le code source (par exemple, pytest, pylint, etc.) avant la publication. Les utilisateurs du paquet n'ont généralement pas besoin de l'ensemble des dépendances des développeurs pour exécuter le paquet.

Si plusieurs requirements-X.txt sont présentes, alors généralement l'une d'entre elles liste les dépendances d'exécution, et l'autre les dépendances de construction ou de test. Certains projets ont également un fichier d'exigences en cascade, c'est-à-dire que lorsqu'un fichier d'exigences inclut un autre fichier ( exemple ). Cela permet de réduire les répétitions.

setup.py

---

Il s'agit d'un script en python qui utilise la fonction setuptools pour définir un paquet python (nom, fichiers inclus, métadonnées du paquet et installation). Il va, comme requirements.txt , liste également les dépendances d'exécution du paquet. Setuptools est le moyen de facto de construire et d'installer des paquets python, mais il a ses défauts, qui avec le temps ont favorisé le développement de nouveaux "méta-gestionnaires de paquets", comme pip. Les exemples de défauts de setuptools sont son incapacité à installer plusieurs versions d'un même paquet, et l'absence d'une commande de désinstallation.

Lorsqu'un utilisateur de python fait pip install ./pkgdir_my_module (ou pip install my-module ), pip va exécuter setup.py dans le répertoire (ou module) donné. De même, tout module qui a un setup.py peut être pip -installé, par exemple en exécutant pip install . dans le même dossier.

Ai-je vraiment besoin des deux ?

---

La réponse courte est non, mais c'est bien d'avoir les deux. Ils ont des objectifs différents, mais ils peuvent tous deux être utilisés pour lister vos dépendances.

Il y a une astuce que vous pouvez envisager pour éviter de dupliquer votre liste de dépendances entre requirements.txt y setup.py . Si vous avez écrit un setup.py pour votre paquet et que vos dépendances sont principalement externes, vous pourriez envisager d'avoir un simple requirements.txt avec seulement les éléments suivants :

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

El -e est une spéciale pip install qui installe le paquet donné dans éditable mode. Lorsque pip -r requirements.txt est exécuté sur ce fichier, pip installera vos dépendances via la liste dans ./setup.py . L'option modifiable placera un lien symbolique dans votre répertoire d'installation (au lieu d'un œuf ou d'une copie archivée). Cela permet aux développeurs de modifier le code en place à partir du référentiel sans avoir à réinstaller.

Vous pouvez également profiter de ce que l'on appelle "setuptools extras" lorsque vous avez les deux fichiers dans votre dépôt de paquets. Vous pouvez définir des paquets optionnels dans setup.py sous une catégorie personnalisée, et installer ces paquets à partir de cette seule catégorie avec pip :

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

et ensuite, dans le fichier des exigences :

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

Cela permet de conserver toutes vos listes de dépendances dans le fichier setup.py.

Nota : Vous exécutez normalement pip et setup.py à partir d'un bac à sable, comme ceux créés avec le programme. virtualenv . Cela évitera d'installer des paquets python en dehors du contexte de l'environnement de développement de votre projet.

Answer 3

Pour être complet, voici comment je le vois sous 3 angles différents.

1. Leurs objectifs de conception sont différents

C'est la description précise citée dans le documentation officielle (c'est moi qui souligne) :

Alors que install_requires (dans setup.py) définit les dépendances pour un seul projet Les fichiers d'exigences sont souvent utilisés pour définir les exigences. pour un environnement Python complet .

Alors que les exigences install_requires sont minimales, les fichiers d'exigences contiennent souvent une liste exhaustive des versions épinglées dans le but d'obtenir des installations répétables d'un environnement complet.

Mais il n'est peut-être pas encore facile à comprendre, c'est pourquoi la section suivante présente deux exemples concrets pour démontrer comment les deux approches sont censées être utilisées, différemment.

2. Leurs usages réels sont donc (censés être) différents.

   • Si votre projet foo va être publié en tant que bibliothèque autonome (ce qui signifie que d'autres personnes feraient probablement import foo ), alors vous (et vos utilisateurs en aval) voudriez avoir une déclaration de dépendance flexible, afin que votre bibliothèque ne soit pas (et ne doit pas être) "pointilleuse" sur la version exacte de VOS dépendances. Donc, typiquement, votre setup.py contiendrait des lignes comme celle-ci :

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

   • Si vous souhaitez simplement "documenter" ou "épingler" votre environnement actuel EXACT pour votre application. bar c'est-à-dire que vous ou vos utilisateurs souhaiteriez utiliser votre application bar en l'état, c'est-à-dire en cours d'exécution python bar.py vous voudrez peut-être geler votre environnement afin qu'il se comporte toujours de la même manière. Dans ce cas, votre fichier d'exigences ressemblerait à ceci :

     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. En réalité, lequel dois-je utiliser ?

   • Si vous développez une application bar qui sera utilisé par python bar.py Même s'il s'agit d'un "simple script pour le plaisir", il est toujours recommandé d'utiliser le fichier requirements.txt car, qui sait, la semaine prochaine (qui se trouve être Noël), vous recevrez un nouvel ordinateur en cadeau, et vous devrez alors y configurer à nouveau votre environnement exact.

   • Si vous développez une bibliothèque foo qui sera utilisé par import foo vous devez préparer un fichier setup.py. Point final. Mais vous pouvez toujours choisir de fournir également un requirements.txt en même temps, ce qui peut :

     (a) soit être dans le A==1.2.3 (comme expliqué au point 2 ci-dessus) ;

     (b) ou contiennent simplement un simple magique .

     .

     ce qui équivaudrait à peu près à "installer les exigences basées sur setup.py" tout en évitant la duplication. Personnellement, je considère que cette dernière approche brouille les pistes, ajoute à la confusion et n'apporte PAS vraiment de valeur ajoutée, mais il s'agit néanmoins d'une astuce dérivée d'une approche mentionnée par le responsable du packaging Python Donald dans son billet de blog .