Quel est le format d'en-tête commun des fichiers Python?

j'ai trouvé le format d'en-tête suivant pour les fichiers source Python dans un document à propos des directives de codage Python:

#!/usr/bin/env python

"""Foobar.py: Description of what foobar does."""

__author__      = "Barack Obama"
__copyright__   = "Copyright 2009, Planet Earth"

est-ce le format standard des en-têtes dans le monde Python? Quels autres champs / informations puis-je mettre dans l'en-tête? Les gourous Python partagent vos directives pour de bons en-têtes de source Python: -)

396
demandé sur Martin Thoma 2009-10-06 07:23:14

4 réponses

toutes ses métadonnées pour le module Foobar .

le premier est le docstring du module, qui est déjà expliqué dans réponse de Pierre .

comment organiser mes modules (fichiers source)? (Archive)

La première ligne de chaque fichier doit être #!/usr/bin/env python . cela permet d'exécuter le fichier comme un script qui invoque implicitement l'interpréteur, par exemple dans un contexte CGI.

la prochaine étape devrait être la chaîne de caractères avec une description. si la description est longue, la première ligne doit être un bref résumé qui a du sens, séparé du reste par une nouvelle ligne.

tout code, y compris les déclarations d'importation, doit être conforme à la norme docstring. sinon, la corde ne sera pas reconnu par l'interprète, et vous n'y aurez pas accès dans des sessions interactives (i.e. via obj.__doc__ ) ou lors de la génération de documentation avec des outils automatisés.

importez d'abord les modules intégrés, puis les modules tiers, puis tout changement au chemin d'accès et à vos propres modules. en particulier, les ajouts au chemin et les noms de vos modules sont susceptibles de changer rapidement: les garder à un endroit les rend plus facile à trouver.

la prochaine étape devrait être l'information sur la paternité. cette information doit suivre le format suivant:

__author__ = "Rob Knight, Gavin Huttley, and Peter Maxwell"
__copyright__ = "Copyright 2007, The Cogent Project"
__credits__ = ["Rob Knight", "Peter Maxwell", "Gavin Huttley",
                    "Matthew Wakefield"]
__license__ = "GPL"
__version__ = "1.0.1"
__maintainer__ = "Rob Knight"
__email__ = "rob@spot.colorado.edu"
__status__ = "Production"
Le statut

doit être typiquement un statut de" Prototype"," développement", ou"Production". __maintainer__ devrait être la personne qui corrigera les bogues et apportera des améliorations si elle est importée. __credits__ diffère de __author__ en ce que __credits__ inclut les personnes qui ont signalé des corrections de bug, fait des suggestions, etc. mais n'a pas écrit le code.

ici vous avez plus d'information, listing __author__ , __authors__ , __contact__ , __copyright__ , __license__ , __deprecated__ , __date__ et __version__ comme métadonnées reconnues.

465
répondu Esteban Küber 2017-05-23 12:34:30

je suis fortement en faveur des en-têtes de fichier minimal, par lequel je veux dire juste:

  • La hashbang ( #! de la ligne) si c'est un script exécutable
  • Module docstring
  • les Importations, regroupés comme décrit dans voyager ’s réponse.

tout le reste est une perte de temps, d'espace visuel, et est activement trompeur.

si vous avez juridique avertissements ou de permis d'info, il va dans un fichier séparé. Il n'a pas besoin d'infecter chaque fichier de code source. Votre droit d'auteur devrait en faire partie. Les gens devraient être en mesure de le trouver dans votre fichier LICENSE , pas dans le code source aléatoire.

les métadonnées telles que la paternité et les dates sont déjà maintenues par votre contrôle source. Il n'est pas nécessaire d'ajouter une version moins détaillée, erronée et périmée de la même information dans le fichier lui-même.

je n'ai pas croire qu'il existe d'autres données que tout le monde doit mettre dans tous leurs fichiers sources. Vous avez peut-être une exigence particulière à cet égard, mais de telles choses ne s'appliquent, par définition, qu'à vous. Ils n'ont pas leur place dans les "en-têtes généraux recommandés pour tout le monde".

126
répondu Jonathan Hartley 2013-04-04 14:42:09

Voir aussi PEP 263 si vous utilisez un jeu de caractères non ascii

Abstrait

ce PEP propose d'introduire une syntaxe pour déclarer l'encodage un fichier source Python. L'information d'encodage est alors utilisée par le Parser Python pour interpréter le fichier en utilisant l'encodage donné. La plupart des cela améliore notamment l'interprétation des littérales Unicode en le code source et les marques il est possible d'écrire en Unicode en utilisant par exemple UTF-8 directement dans un éditeur conscient Unicode.

problème

en Python 2.1, Les littérales Unicode ne peuvent être écrites qu'en utilisant Encodage basé sur le Latin-1"unicode-escape". Cela rend le environnement de programmation plutôt hostile aux utilisateurs de Python qui vivent et de travailler dans des endroits non-latins-1 comme beaucoup de L'Asie pays. Les programmeurs peuvent écrire leurs chaînes 8 bits en utilisant le encodage préféré, mais sont liés à l'encodage" unicode-escape" pour l'Unicode des littéraux.

Solution Proposée

je propose de rendre visible et visible le code source de Python modifiable par fichier source en utilisant un commentaire spécial en haut du fichier à déclarer l'encodage.

pour rendre Python conscient de cette déclaration d'encodage un certain nombre de les changements de concept sont nécessaire pour le traitement de Python code source de données.

définition de L'encodage

Python va par défaut à ASCII comme encodage standard si aucun autre encodage des conseils sont donnés.

pour définir un encodage de code source, un commentaire magique doit être placé dans les fichiers source soit comme Premier ou deuxième ligne dans le fichier, telle que:

      # coding=<encoding name>

ou (en utilisant des formats reconnu par les éditeurs populaires)

      #!/usr/bin/python
      # -*- coding: <encoding name> -*-

ou

      #!/usr/bin/python
      # vim: set fileencoding=<encoding name> :

...

18
répondu John La Rooy 2014-06-18 02:06:55

les réponses ci-dessus sont vraiment complètes, mais si vous voulez un en-tête rapide et sale pour copier-coller, Utilisez ceci:

#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""Module documentation goes here
   and here
   and ...
"""

pourquoi celle-ci est bonne:

  • la première ligne est pour les utilisateurs *nix. Il choisira l'interpréteur Python dans le chemin de l'utilisateur, il choisira donc automatiquement l'interpréteur préféré de l'utilisateur.
  • le second est le codage de fichier. Aujourd'hui, chaque fichier doit avoir un codage associé. L'UTF-8 marchera partout. Juste les projets d'héritage utiliseraient un autre encodage.
  • et une documentation très simple. Il peut remplir plusieurs lignes.

Voir aussi: https://www.python.org/dev/peps/pep-0263 /

si vous écrivez juste une classe dans chaque fichier, vous n'avez même pas besoin de la documentation (elle irait à l'intérieur de la classe doc).

14
répondu neves 2018-04-04 14:13:50