Python : Quel est le format d’en-tête commun ?

Question

Je suis tombé sur le format d’en-tête suivant pour les fichiers sources Python dans un document sur Python coding guidelines :

C’est le format standard des en-têtes dans le monde Python ? Quels autres champs/renseignements je peux mettre dans l’en-tête ? Les gourous python partagent vos directives pour les bons en-têtes de source Python  :-)

Answer 1

Ses toutes les métadonnées de la Foobar module.

La première est l' docstring du module, qui est déjà expliqué dans la réponse de Pierre.

Comment puis-je organiser mes modules (fichiers sources)? (Archive)

La première ligne de chaque fichier devra être #!/usr/bin/env python. Cela rend possible l'exécution du fichier comme un script en invoquant l'interprète de manière implicite, par exemple, dans un contexte CGI.

La prochaine devrait être la docstring avec une description. Si la description est longue, la première ligne doit être un court résumé qui a du sens sur son propre, séparée du reste par un saut de ligne.

L'ensemble du code, y compris les déclarations d'importation, devrait suivre la docstring. Sinon, la docstring ne sera pas reconnu par l'interprète, et vous n'aurez pas accès aux sessions interactives (p. ex. l' obj.__doc__) ou lors de la génération de la documentation avec des outils automatisés.

Importer des modules intégrés en premier, suivi par les modules tiers, suivi de tous les changements pour le chemin d'accès et vos propres modules. En particulier, les ajouts pour le chemin d'accès et les noms de vos modules sont susceptibles de changer rapidement: garder dans un endroit rend plus facile à trouver.

La prochaine devrait être la paternité de l'information. 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 généralement l'un des "Prototype", "Développement" ou la "Production". __maintainer__ devrait être la personne qui va corriger les bugs et d'apporter des améliorations si importés. __credits__ diffère __author__ dans __credits__ comprend les personnes qui ont signalé des corrections de bugs, des suggestions, etc. mais n'a pas écrit le code.

Ici vous avez plus d'informations, liste __author__, __authors__, __contact__, __copyright__, __license__, __deprecated__, __date__ et __version__ comme l'a reconnu les métadonnées.

Answer 2

Je suis fermement en faveur minimal en-têtes de fichier, par qui je veux dire simplement:

• Le hashbang (#! ligne) si c'est un script exécutable
• Module de docstring
• Les importations, regroupés comme décrit dans voyager's réponse.

Tout le reste est une perte de temps, de l'espace visuel, et est activement trompeuse.

Si vous avez les mentions légales 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 être une partie de cela. Les gens devraient être en mesure de trouver dans votre LICENSE fiche, n'aléatoire de code source.

Les métadonnées telles que la paternité et les dates, c'est déjà géré par votre source de contrôle. Il n'est pas nécessaire d'ajouter un moins détaillés, erronée, et out-of-date de la version de la même info dans le fichier lui-même.

Je ne crois pas qu'il existe d'autres données que tout le monde doit mettre dans tous leurs fichiers sources. Vous pouvez avoir une certaine exigence particulière de le faire, mais de telles choses s'applique, par définition, qu'à vous. Ils n'ont pas de place dans "général des en-têtes recommandé pour tout le monde".

Answer 3

Voir aussi PEP 263 si vous utilisez un non-ascii characterset

Résumé

Ce PEP propose d'introduire une syntaxe pour déclarer l'encodage de un Python fichier source. Le codage de l'information est ensuite utilisée par l' Python analyseur d'interpréter le fichier en utilisant le codage. La plupart des notamment en ce qui renforce l'interprétation de l'Unicode des littéraux dans le code source et rend possible l'écriture de l'Unicode des littéraux en utilisant par exemple UTF-8 directement dans une Unicode conscient de l'éditeur.

Problème

En Python 2.1, Unicode littéraux ne peut être écrite à l'aide de la Latin-1, en fonction de l'encodage unicode-escape". Cela rend le la programmation de l'environnement plutôt hostile à Python qui vivent et le travail non-Latin-1 paramètres régionaux comme la plupart des Asiatiques pays. Les programmeurs peuvent écrire leurs 8-des chaînes de bits à l'aide de la favori de l'encodage, mais sont liés à la "unicode-escape" encoding pour l'Unicode des littéraux.

Solution Proposée

Je propose de faire du code source Python codage à la fois visible et modifiable par fichier de source de base à l'aide d'un commentaire particulier en haut du fichier à déclarer l'encodage.

Pour faire de Python au courant de cette déclaration de codage d'un nombre de concept changements sont nécessaires pour le traitement de Python code source de données.

La définition de l'Encodage

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

Pour définir un code source de l'encodage, de la magie commentaire doit être placé dans le fichier source soit de premier ou de second ligne dans le fichier, telles que:

      # coding=<encoding name>

ou (à l'aide des formats reconnus par les éditeurs populaires)

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

ou

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

...

Answer 4

Voici un bon point de départ : PEP 257, qui parle de code et des liens vers plusieurs autres documents pertinents.