En-tête de fichier Python

L’en-tête d’un fichier Python est une documentation facultative placée au début d’un fichier source. Un projet peut adopter un format commun pour présenter l’objectif d’un script, son usage prévu, ses exigences et sa licence ; Python n’impose aucun en-tête particulier. Ne conservez que les informations qui aident à comprendre ou à exécuter le fichier, et respectez les conventions du projet.

Pourquoi utiliser un format d’en-tête commun en Python

Un en-tête cohérent donne aux lecteurs un contexte utile avant qu’ils ne découvrent l’implémentation. Il peut indiquer l’objectif d’un script, son responsable, la façon de le lancer ainsi que ses exigences importantes en matière d’environnement d’exécution ou de dépendances. Une mention de licence peut aussi préciser les conditions d’utilisation du code, à condition qu’elle corresponde à la licence réelle du projet.

Le format relève d’une convention d’équipe, et non d’une fonctionnalité du langage Python. Un petit script ponctuel peut se contenter d’une brève description du module, tandis qu’un outil en ligne de commande distribué peut tirer parti de notes sur son utilisation et ses dépendances. La cohérence facilite la lecture de plusieurs fichiers dans un même dépôt, mais copier des champs sans rapport avec le fichier l’encombre et risque de laisser des informations obsolètes.

Éléments d’un en-tête de fichier Python

Choisissez les éléments en fonction de la façon dont le fichier est exécuté et maintenu. Un en-tête associe souvent des informations sur l’interpréteur, un docstring du module et des commentaires destinés aux lecteurs.

Ligne shebang

Une ligne shebang est un marqueur placé sur la première ligne, par exemple #!/usr/bin/env python3. Sur les systèmes qui la prennent en charge, l’exécution d’un script par son chemin utilise l’interpréteur sélectionné par env. Cette ligne est utile pour les scripts en ligne de commande sur les systèmes de type Unix, mais elle n’est pas nécessaire lorsque le fichier est lancé avec une commande telle que python script.py. Elle n’installe pas Python et ne sélectionne pas un environnement pour tous les modes de lancement possibles.

Déclaration d’encodage

Les fichiers source Python 3 utilisent UTF-8 par défaut ; une déclaration d’encodage est donc généralement inutile. Si un fichier source utilise un autre encodage pour être compatible avec un outil ou un environnement donné, Python reconnaît une déclaration telle que # -*- coding: latin-1 -*- sur la première ou la deuxième ligne. Cette déclaration doit correspondre à l’encodage réel du fichier ; elle ne rend pas lisible n’importe quel texte.

Docstring du module et commentaires

Un docstring du module est une chaîne littérale placée au début du module, après une éventuelle ligne shebang ou un commentaire d’encodage. Il décrit le module et est accessible via __doc__. Utilisez-le pour indiquer brièvement l’objectif du module et fournir un contexte utile à l’échelle du module. Les commentaires ordinaires peuvent contenir des notes sur la maintenance, l’utilisation, les dépendances, la version ou la licence ; Python ne les interprète pas automatiquement comme des métadonnées.

Les imports se placent après le docstring du module et avant les autres instructions exécutables du module. Lorsque des imports sont nécessaires, une convention courante consiste à regrouper d’abord ceux de la bibliothèque standard, puis ceux des bibliothèques tierces, et enfin ceux du projet, en laissant une ligne vide entre les groupes.

Un en-tête peut indiquer comment exécuter un script, quels paquets sont nécessaires ou quelle version minimale de Python est requise, si ces informations sont utiles. Veillez à ce que les exigences restent conformes à la configuration réelle du projet. N’ajoutez une mention de licence que si elle correspond à la licence choisie pour le code, et évitez les dates personnelles ou l’historique des modifications, qui deviennent vite obsolètes.

Exemple d’en-tête de fichier Python

Ce script autonome présente un en-tête concis avec une ligne shebang, un docstring du module et des commentaires que la personne chargée de la maintenance doit remplacer par des informations propres au projet. La description et les commentaires constituent de la documentation ; la fonction et le bloc de garde principal sont du code Python exécutable.

#!/usr/bin/env python3
"""Print a short status message for a sample command-line tool."""

# Maintainer: Replace with a team or owner.
# Usage: python status_report.py
# License: Replace with the project's actual license.

def main():
    print("Report ready")


if __name__ == "__main__":
    main()

Adaptez les commentaires au fichier : n’ajoutez des notes sur les dépendances ou la version de Python que si elles ont une incidence sur l’installation ou l’utilisation. L’exemple ne dépend d’aucun paquet externe et n’a donc pas besoin de liste d’imports. La ligne shebang est utile lorsque le fichier est lancé comme exécutable sur un système qui la prend en charge ; avec python status_report.py, c’est l’interpréteur indiqué dans la commande qui est utilisé.

Bonnes pratiques pour les en-têtes de fichiers Python

• Gardez l’en-tête court et limitez-le aux informations utiles pour utiliser ou maintenir le fichier.
• Respectez le format déjà adopté par le projet afin que les fichiers associés soient faciles à parcourir.
• Placez le docstring du module avant les imports et utilisez des commentaires pour les notes qui ne font pas partie de la documentation du module.
• Avant de les ajouter, vérifiez les informations sur l’interpréteur, les dépendances et la licence dans la configuration actuelle du projet.
• Mettez les notes à jour ou supprimez-les lorsqu’elles ne sont plus exactes ; omettez les champs tels que l’auteur ou la date de modification si le projet les suit déjà ailleurs.

Un bon en-tête commun se limite aux informations dont la prochaine personne chargée du développement a besoin. Considérez-le comme une documentation évolutive et laissez les conventions du projet déterminer quelles informations facultatives conviennent à chaque fichier.