Quel est le format d'en-tête des fichiers Python?
Je suis tombé sur l'en-tête suivant le format pour Python fichiers source dans un document sur Python directives de codage:
#!/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 Python monde?
Quels sont les autres champs/informations puis-je mettre dans l'en-tête?
Python gourous de partager vos lignes directrices de bonne source Python-têtes 🙂
- Voici un bon endroit pour commencer: PEP 257, qui parle de Docstrings, et des liens vers plusieurs autres documents pertinents.
- Peut-être une indication utile pour ceux qui lisent les différentes réponses à cette question est de déterminer quelles fins ils attendent de ces en-têtes de fichier pour être utilisé. Si vous avez un cas concret d'utilisation (par exemple, mon avocat dit les affaires de la cour sont perdues parce que les développeurs n'a pas à mettre les informations de copyright dans chaque fichier.) puis ajouter et maintenir les informations dont vous avez besoin pour ce cas d'utilisation. Sinon, vous êtes juste adonner à votre trouble obsessionnel-compulsif fétiche.
- haha grand @JonathanHartley ! Pour mes propres projets, comme vous le dites "je livrer mon TOC fétiche." hahaaha stackoverflow.com/a/51914806/1896134
Vous devez vous connecter pour publier un commentaire.
Son toutes les métadonnées de la
Foobar
module.Le premier est le
docstring
du module, qui est déjà expliqué dans La réponse de pierre.Ici vous avez plus d'informations, inscription
__author__
,__authors__
,__contact__
,__copyright__
,__license__
,__deprecated__
,__date__
et__version__
comme l'a reconnu les métadonnées.__usage__
et__epilog__
sur les modules qui utilisentargparse
/optparse
pour montrer aide de ligne de commande.__version__
doit être directement à la suite de la principale docstring, avec une ligne vide avant et après. Aussi, il est préférable de définir votre charset immédiatement sous le shebang -# -*- coding: utf-8 -*-
sys.path
à tous. Si vous devez le faire, vous êtes en train de faire quelque chose de mal.LICENSE
dans le répertoire racine, et peut-être mettre un__license__ = 'MIT'
ou que ce soit avec la version dans un__init__.py
fichier. La réplication est de vous répéter, sujettes à erreur, et vous ne pouvez pas exepct chaque contributeur à maintenir la bonne structure de cette réponse suggère.#!/usr/bin/python
pour le shebang/interprète la directive. Ou quel que soit l'interprète est utilisé localement, en fonction de cewhich python
renvoie (ou python3).__version__
). cela a été révisée?.py
fichier externe, collaborateur est un exemple de cas d'utilisation à mon humble avis.Je suis fermement en faveur minimal en-têtes de fichier, par qui je veux dire simplement:
#!
ligne) si c'est un script exécutableie. trois groupes d'importations, avec une seule ligne vide entre eux. Au sein de chaque groupe, les importations sont triés. Le dernier groupe, les importations en provenance de la source locale, peut être soit absolu des importations, comme illustré, ou explicite, relative importations.
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
fichier, pas au hasard le code source.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”.
__version__
métadonnées, bien que, et je pense que c'est bon d'avoir, puisqu'il devrait être accessible à des programmes et à vérifier rapidement dans interactive interprète. La paternité et de l'information juridique se fait dans un fichier différent, cependant. Sauf si vous avez un cas d'utilisation pourif 'Rob' in __author__:
__version__
attribut est une excellente idée: il est lu par pydoc, etc. Toutefois, cette balise ne doit pas exister dans un endroit dans votre projet: à savoir le niveau supérieur du paquet__init__.py
. Il ne doit pas être ajoutée à chaque fichier.Les réponses ci-dessus sont vraiment complète, mais si vous voulez un moyen rapide et sale de l'en-tête de la copie n'coller, utilisez ceci:
Pourquoi c'est une bonne idée:
Voir aussi: https://www.python.org/dev/peps/pep-0263/
Si vous venez d'écrire une classe pour chaque fichier, vous n'avez même pas besoin de la documentation (il serait d'aller à l'intérieur de la classe doc).
Voir aussi PEP 263 si vous utilisez un non-ascii characterset