web-dev-qa-db-fra.com

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 instructions 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? Python les gourous partagent vos recommandations pour de bons Python sources::)

pythonheadercomments
464
Ashwin Nanjappa

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 Peter .

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 sous forme de script appelant implicitement l’interpréteur, par exemple. dans un contexte CGI.

Suivant devrait être la chaîne de caractères avec une description. Si la description est longue, la première ligne doit être un court résumé qui a du sens, 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. lors de sessions interactives (c.-à-d. 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, suivis des modules tiers, suivis de toute modification apportée au chemin et de vos propres modules. En particulier, ajouts au chemin et les noms de vos modules sont susceptibles de changer rapidement: les garder au même endroit les rend plus faciles à trouver.

Ensuite devrait figurer l'information sur l'auteur. Cette information devrait 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__ = "[email protected]"
__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 si elle est importée. __credits__ diffère de __author__ en ce que __credits__ inclut les personnes qui ont signalé des corrections de bugs, des suggestions, etc. sans écrire le code.

Ici vous avez plus d'informations, listant __author__, __authors__, __contact__, __copyright__, __license__, __deprecated__, __date__ et __version__ en tant que métadonnées reconnues.

524
Esteban Küber

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

  • Le hashbang (#! line) 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, séparés par une seule ligne vierge. Dans chaque groupe, les importations sont triées. Le groupe final, 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 renonciations légales ou des informations sur les licences, elles sont placées dans un fichier séparé. Il n’est pas nécessaire d’infecter tous les fichiers de code source. Votre droit d'auteur devrait en faire partie. Les gens devraient pouvoir le trouver dans votre fichier LICENSE, pas dans un code source aléatoire.

Les métadonnées telles que l'auteur et les dates sont déjà géré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 crois pas qu'il y ait d'autres données que tout le monde a besoin de mettre dans tous ses fichiers sources. Vous pouvez avoir une obligation particulière de le faire, 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".

159
Jonathan Hartley

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 * nix. Il choisira l’interprète Python dans le chemin de l’utilisateur, ainsi choisira automatiquement l’interpréteur préféré de 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 document de classe).

28
neves

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

Abstrait

Ce PEP propose d'introduire une syntaxe permettant de déclarer le codage d'un fichier source Python. Les informations de codage sont ensuite utilisées par l’analyseur Python pour interpréter le fichier à l’aide du codage 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 "unicode-escape" basé sur le latin-1. Ceci rend l'environnement de programmation plutôt hostile aux Python utilisateurs qui vivent et travaillent dans des environnements locaux autres que Latin-1, tels que de nombreux pays asiatiques. Les programmeurs peuvent écrire leurs chaînes de 8 bits en utilisant le codage favori, mais sont liés au codage "unicode-escape" pour les littéraux Unicode.

Solution proposée

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

Pour que Python connaisse cette déclaration de codage, un certain nombre de modifications de concept sont nécessaires en ce qui concerne le traitement des données de Python.

Définir le codage

Python utilisera par défaut ASCII comme codage standard si aucun autre conseil de codage n'est donné.

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, par exemple:

      # 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> :

...

22
John La Rooy