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

Je suis tombé sur le format d'en-tête suivant pour les fichiers source Python dans un document sur les 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 de Python partagent vos directives pour de bons en-têtes de source Python :-)

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

Le premier est celui docstringdu module, qui est déjà expliqué dans la réponse de Peter .

Comment organiser mes modules (fichiers source)? (Archiver)

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

Ensuite devrait être la docstring avec une description. Si la description est longue, la première ligne doit être un bref résumé qui a du sens en soi, séparé du reste par une nouvelle ligne.

Tout le code, y compris les instructions d'importation, doit suivre la docstring. Sinon, la docstring ne sera pas reconnue par l'interpréteur et vous n'y aurez pas accès dans les sessions interactives (c'est-à-dire 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 les modifications apportées au chemin et à vos propres modules. En particulier, les ajouts au chemin et aux noms de vos modules sont susceptibles de changer rapidement: les garder au même endroit les rend plus faciles à trouver.

Viennent ensuite les informations sur la paternité. Ces informations doivent suivre ce format:

__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 généralement être "Prototype", "Développement" ou "Production". __maintainer__devrait être la personne qui corrigera les bogues et apportera des améliorations en cas d'importation. __credits__diffère de __author__celui qui __credits__inclut les personnes qui ont signalé des corrections de bogues, fait des suggestions, etc. mais qui n'ont pas réellement écrit le code.

Ici , vous avez plus d' informations, la liste __author__, __authors__, __contact__, __copyright__, __license__, __deprecated__, __date__et __version__métadonnées reconnues.

Je privilégie fortement les en-têtes de fichiers minimaux, ce qui signifie simplement:

• Le hashbang ( #!ligne) s'il s'agit d'un script exécutable
• Module docstring
• Importations, regroupées de manière standard, par exemple:

  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule  

c'est à dire. trois groupes d'importations, avec une seule ligne blanche entre eux. Au sein de chaque groupe, les importations sont triées. Le dernier groupe, les importations de source locale, peut être soit des importations absolues comme indiqué, soit des importations relatives explicites.

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

Si vous avez des clauses de non-responsabilité ou des informations de licence, elles sont enregistrées dans un fichier distinct. Il n'a pas besoin d'infecter tous les fichiers de code source. Votre droit d'auteur devrait en faire partie. Les gens devraient pouvoir le trouver dans votre LICENSEfichier, pas dans un code source aléatoire.

Les métadonnées telles que la paternité et les dates sont déjà conservées par votre contrôle de source. Il n'est pas nécessaire d'ajouter une version moins détaillée, erronée et obsolète des mêmes informations dans le fichier lui-même.

Je ne pense pas qu'il y ait d'autres données que tout le monde doive mettre dans tous leurs fichiers source. Vous pouvez avoir une exigence particulière à cet égard, mais ces 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».

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

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

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

Pourquoi c'est un bon:

• La première ligne est destinée aux utilisateurs de * nix. Il choisira l'interpréteur Python dans le chemin utilisateur, donc choisira automatiquement l'interpréteur préféré par l'utilisateur.
• Le second est l'encodage du fichier. De nos jours, chaque fichier doit avoir un codage associé. UTF-8 fonctionnera partout. Seuls les projets hérités 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 simplement une classe dans chaque fichier, vous n'avez même pas besoin de la documentation (elle irait à l'intérieur du doc ​​de classe).

Voir également 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 d'un fichier source Python. Les informations d'encodage sont ensuite utilisées par l'analyseur Python pour interpréter le fichier en utilisant l'encodage donné. Plus particulièrement, cela améliore l'interprétation des littéraux Unicode dans le code source et permet d'écrire des littéraux Unicode en utilisant par exemple UTF-8 directement dans un éditeur compatible Unicode.

Problème

Dans Python 2.1, les littéraux Unicode ne peuvent être écrits qu'en utilisant le codage basé sur Latin-1 "unicode-escape". Cela rend l'environnement de programmation plutôt hostile aux utilisateurs Python qui vivent et travaillent dans des environnements locaux non latins-1 tels que de nombreux pays asiatiques. Les programmeurs peuvent écrire leurs chaînes 8 bits en utilisant l'encodage préféré, mais sont liés à l'encodage "unicode-escape" pour les littéraux Unicode.

Solution proposée

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

Pour rendre Python conscient de cette déclaration de codage, un certain nombre de changements de concept sont nécessaires en ce qui concerne la gestion des données de code source Python.

Définition de l'encodage

Python utilisera par défaut ASCII comme codage standard si aucune autre indication de codage n'est donnée.

Pour définir un codage de code source, un commentaire magique doit être placé dans les fichiers source en tant que première ou deuxième ligne du fichier, tel que:

      # coding=<encoding name>

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

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

ou

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

...