Wat is het algemene kopformaat van Python-bestanden?

Ik kwam de volgende header-indeling voor Python-bronbestanden tegen in een document over de coderingsrichtlijnen van Python:

#!/usr/bin/env python
"""Foobar.py: Description of what foobar does."""
__author__      = "Barack Obama"
__copyright__   = "Copyright 2009, Planet Earth"

Is dit het standaardformaat van headers in de Python-wereld?
Welke andere velden/informatie kan ik in de header zetten?
Python-goeroes delen uw richtlijnen voor goede Python-bronheaders 🙂

Antwoord 1, autoriteit 100%

Het zijn allemaal metadata voor de module Foobar.

De eerste is de docstringvan de module, die al is uitgelegd in Peters antwoord.

Hoe organiseer ik mijn modules (bronbestanden)? (Archief)

De eerste regel van elk bestand moet #!/usr/bin/env pythonzijn.Dit maakt het mogelijk om het bestand uit te voeren als een script dat de interpreter impliciet aanroept bijv in een CGI-context.

De volgende moet de docstring zijn met een beschrijving.Als de beschrijving lang is, moet de eerste regel een korte samenvatting zijn die op zichzelf logisch is, gescheiden van de rust bij een nieuwe regel.

Alle code, inclusief importinstructies, moet de docstring volgen.Anders wordt de docstring niet herkend door de interpreter en hebt u er geen toegang toe in interactieve sessies (dwz via obj.__doc__) of bij het genereren van documentatie met geautomatiseerde tools.

Importeer eerst ingebouwde modules, gevolgd door modules van derden, gevolgd door eventuele wijzigingen in het pad en uw eigen modules.Vooral toevoegingen aan het pad en de namen van uw modules zullen waarschijnlijk veranderen snel: door ze op één plaats te bewaren, zijn ze gemakkelijker te vinden.

Volgende moet auteurschapsinformatie zijn.Deze informatie moet dit formaat hebben:

__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"

De status moet doorgaans ‘Prototype’, ‘Ontwikkeling’ of ‘Productie’ zijn. __maintainer__zou de persoon moeten zijn die bugs zal oplossen en verbeteringen zal aanbrengen indien geïmporteerd. __credits__verschilt van __author__doordat __credits__mensen bevat die bugfixes hebben gemeld, suggesties hebben gedaan, enz. maar de code niet daadwerkelijk hebben geschreven.

Hierheb je meer informatie, met __author__, __authors__, __contact__, __copyright__, __license__, __deprecated__, __date__en __version__als herkende metadata.

Antwoord 2, autoriteit 31%

Ik ben sterk voorstander van minimale bestandsheaders, waarmee ik bedoel:

• De hashbang (#!regel) als dit een uitvoerbaar script is
• Module docstring
• Importeert, gegroepeerd op de standaardmanier, bijv.:

 import os    # standard library
  import sys
  import requests  # 3rd party packages
  from mypackage import (  # local source
      mymodule,
      myothermodule,
  )

dwz. drie groepen invoer, met een enkele lege regel ertussen. Binnen elke groep worden de importen gesorteerd. De laatste groep, import uit lokale bron, kan absolute import zijn zoals weergegeven, of expliciete relatieve import.

Al het andere is een verspilling van tijd, visuele ruimte en is actief misleidend.

Als je juridische disclaimers of licentie-informatie hebt, wordt deze in een apart bestand geplaatst. Het hoeft niet elk broncodebestand te infecteren. Uw auteursrecht dient hier onderdeel van uit te maken. Mensen zouden het in je LICENSE-bestand moeten kunnen vinden, niet in willekeurige broncode.

Metadata zoals auteurschap en datums worden al onderhouden door uw bronbeheer. Het is niet nodig om een minder gedetailleerde, foutieve en verouderde versie van dezelfde informatie in het bestand zelf toe te voegen.

Ik geloof niet dat er andere gegevens zijn die iedereen in al zijn bronbestanden moet zetten. Het kan zijn dat u een bepaalde vereiste hebt om dit te doen, maar dergelijke dingen zijn per definitie alleen voor u van toepassing. Ze horen niet thuis in “algemene koppen die voor iedereen worden aanbevolen”.

Antwoord 3, autoriteit 7%

De bovenstaande antwoorden zijn echt compleet, maar als je een snelle en vuile kop wilt om te kopiëren en plakken, gebruik dan dit:

#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""Module documentation goes here
   and here
   and ...
"""

Waarom dit een goede is:

• De eerste regel is voor *nix-gebruikers. Het zal de Python-interpreter in het gebruikerspad kiezen, dus automatisch de door de gebruiker geprefereerde interpreter.
• De tweede is de bestandscodering. Tegenwoordig moet aan elk bestand een codering zijn gekoppeld. UTF-8 werkt overal. Alleen legacy-projecten zouden andere codering gebruiken.
• En een heel eenvoudige documentatie. Het kan meerdere regels vullen.

Zie ook: https://www.python.org/dev/peps/ pep-0263/

Als je gewoon een klasse in elk bestand schrijft, heb je de documentatie niet eens nodig (deze zou in het klassedocument komen).

Antwoord 4, autoriteit 4%

Zie ook PEP 263als je een niet-ascii-tekenset gebruikt

Abstract

Deze PEP stelt voor om een syntaxis in te voeren om de codering van te declareren
een Python-bronbestand. De coderingsinformatie wordt vervolgens gebruikt door de
Python-parser om het bestand te interpreteren met behulp van de gegeven codering. Meest
dit verbetert met name de interpretatie van Unicode-letterwoorden in
de broncode en maakt het mogelijk om Unicode-letterwoorden te schrijven
met behulp van bijv. UTF-8 rechtstreeks in een Unicode-bewuste editor.

Probleem

In Python 2.1 kunnen Unicode-letterwoorden alleen worden geschreven met de
Op Latin-1 gebaseerde codering “unicode-escape”. Dit maakt de
programmeeromgeving nogal onvriendelijk voor Python-gebruikers die leven
en werk op niet-Latijns-1 locaties zoals veel van de Aziatische
landen. Programmeurs kunnen hun 8-bit strings schrijven met behulp van de
favoriete codering, maar zijn gebonden aan de “unicode-escape”-codering
voor Unicode-letterwoorden.

Voorgestelde oplossing

Ik stel voor om de codering van de Python-broncode zowel zichtbaar als
kan per bronbestand worden gewijzigd door een speciale opmerking te gebruiken
bovenaan het bestand om de codering aan te geven.

Om Python op de hoogte te stellen van deze coderingsdeclaratie een aantal:
er zijn conceptwijzigingen nodig met betrekking tot de afhandeling van
Python-broncodegegevens.

De codering definiëren

Python gebruikt standaard ASCII-codering als er geen andere is
coderingstips worden gegeven.

Om een broncodecodering te definiëren, moet een magische opmerking
als eerste of tweede in de bronbestanden worden geplaatst
regel in het bestand, zoals:

     # coding=<encoding name>

of (met behulp van formaten die worden herkend door populaire editors)

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

of

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

…