Jaki jest typowy format nagłówka plików Python?

W dokumencie dotyczącym wytycznych kodowania w języku Python natrafiłem na następujący format nagłówka plików źródłowych Python:

#!/usr/bin/env python

"""Foobar.py: Description of what foobar does."""

__author__      = "Barack Obama"
__copyright__   = "Copyright 2009, Planet Earth"

Czy to standardowy format nagłówków w świecie Python? Jakie inne pola / informacje mogę umieścić w nagłówku? Guru Python dzielą się Twoimi wytycznymi dotyczącymi dobrych nagłówków źródeł Python :-)

To wszystkie metadane dla Foobarmodułu.

Pierwszy to docstringmoduł, który został już wyjaśniony w odpowiedzi Piotra .

Jak zorganizować moduły (pliki źródłowe)? (Archiwum)

Pierwszy wiersz każdego pliku powinien być #!/usr/bin/env python. Umożliwia to uruchomienie pliku jako skryptu wywołującego niejawnie interpreter, np. W kontekście CGI.

Następny powinien być dokument z opisem. Jeśli opis jest długi, pierwszy wiersz powinien być krótkim streszczeniem, które samo w sobie ma sens, oddzielonym od reszty znakiem nowej linii.

Cały kod, w tym instrukcje importu, powinien być zgodny z ciągiem dokumentów. W przeciwnym razie tłumacz nie zostanie rozpoznany przez tłumacza i nie będziesz mieć do niego dostępu podczas interaktywnych sesji (tj. Poprzez obj.__doc__) lub podczas generowania dokumentacji za pomocą zautomatyzowanych narzędzi.

Najpierw zaimportuj wbudowane moduły, a następnie moduły innych firm, a następnie wszelkie zmiany ścieżki i własnych modułów. W szczególności dodatki do ścieżki i nazwy modułów mogą się szybko zmieniać: utrzymanie ich w jednym miejscu ułatwia ich znalezienie.

Następnie powinny znaleźć się informacje o autorze. Informacje te powinny być zgodne z tym formatem:

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

Status powinien zazwyczaj mieć wartość „Prototyp”, „Rozwój” lub „Produkcja”. __maintainer__powinna być osoba, która naprawi błędy i wprowadzi ulepszenia, jeśli zostaną zaimportowane. __credits__różni się od __author__tego, że __credits__obejmuje osoby, które zgłosiły poprawki błędów, sugestie itp., ale tak naprawdę nie napisały kodu.

Tutaj masz więcej informacji, wymieniając __author__, __authors__, __contact__, __copyright__, __license__, __deprecated__, __date__i __version__uznanych metadanych.

Zdecydowanie preferuję minimalne nagłówki plików, przez co rozumiem tylko:

• Hashbang ( #!linia), jeśli jest to skrypt wykonywalny
• Moduł docstring
• Import, pogrupowane w standardowy sposób, np .:

  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule  

to znaczy. trzy grupy importu, z pojedynczą pustą linią między nimi. W ramach każdej grupy importowane są sortowane. Ostatnią grupą, importowaną z lokalnego źródła, może być import bezwzględny, jak pokazano, lub wyraźny import względny.

Cała reszta to strata czasu, przestrzeni wizualnej i aktywnie wprowadza w błąd.

Jeśli masz zastrzeżenia prawne lub informacje licencyjne, zostanie ono umieszczone w osobnym pliku. Nie musi infekować każdego pliku kodu źródłowego. Twoje prawa autorskie powinny być częścią tego. Ludzie powinni mieć możliwość znalezienia go w twoim LICENSEpliku, a nie w losowym kodzie źródłowym.

Metadane, takie jak autorstwo i daty, są już kontrolowane przez kontrolę źródła. Nie ma potrzeby dodawania mniej szczegółowych, błędnych i nieaktualnych wersji tych samych informacji w samym pliku.

Nie sądzę, aby były jakieś inne dane, które każdy powinien umieścić we wszystkich swoich plikach źródłowych. Możesz mieć pewne szczególne wymagania, ale takie rzeczy z definicji dotyczą tylko ciebie. Nie mają miejsca w „ogólnych nagłówkach zalecanych dla wszystkich”.

Powyższe odpowiedzi są naprawdę kompletne, ale jeśli chcesz szybkiego i brudnego nagłówka, aby skopiować i wkleić, użyj tego:

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

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

Dlaczego to jest dobre:

• Pierwszy wiersz dotyczy użytkowników * nix. Wybiera interpreter języka Python na ścieżce użytkownika, więc automatycznie wybiera preferowanego przez użytkownika tłumacza.
• Drugi to kodowanie pliku. Obecnie każdy plik musi mieć przypisane kodowanie. UTF-8 będzie działać wszędzie. Tylko starsze projekty wykorzystywałyby inne kodowanie.
• I bardzo prosta dokumentacja. Może wypełnić wiele linii.

Zobacz także: https://www.python.org/dev/peps/pep-0263/

Jeśli po prostu napiszesz klasę w każdym pliku, nie potrzebujesz nawet dokumentacji (znalazłaby się w dokumencie klasy).

Zobacz także PEP 263, jeśli używasz zestawu znaków innego niż ascii

Abstrakcyjny

Ten PEP proponuje wprowadzenie składni do deklarowania kodowania pliku źródłowego Pythona. Informacje o kodowaniu są następnie wykorzystywane przez analizator składni Python do interpretacji pliku przy użyciu danego kodowania. W szczególności poprawia to interpretację literałów Unicode w kodzie źródłowym i umożliwia pisanie literałów Unicode przy użyciu np. UTF-8 bezpośrednio w edytorze obsługującym Unicode.

Problem

W Pythonie 2.1 literały Unicode można pisać tylko przy użyciu kodowania „Unicode-Escape” opartego na Latin-1. To sprawia, że ​​środowisko programistyczne jest raczej nieprzyjazne dla użytkowników Pythona, którzy mieszkają i pracują w lokalizacjach innych niż Latin-1, takich jak wiele krajów azjatyckich. Programiści mogą pisać swoje 8-bitowe ciągi przy użyciu ulubionego kodowania, ale są zobowiązani do kodowania „unikatowego” dla literałów Unicode.

Proponowane rozwiązanie

Proponuję uczynić kodowanie kodu źródłowego Pythona zarówno widocznym, jak i zmiennym dla poszczególnych plików, używając specjalnego komentarza u góry pliku, aby zadeklarować kodowanie.

Aby uświadomić Pythonowi tę deklarację kodowania, konieczne jest wprowadzenie szeregu zmian pojęciowych w odniesieniu do obsługi danych kodu źródłowego Python.

Definiowanie kodowania

Python domyślnie przyjmuje ASCII jako standardowe kodowanie, jeśli nie podano innych wskazówek dotyczących kodowania.

Aby zdefiniować kodowanie kodu źródłowego, magiczny komentarz musi zostać umieszczony w plikach źródłowych jako pierwsza lub druga linia w pliku, na przykład:

      # coding=<encoding name>

lub (przy użyciu formatów uznanych przez popularnych redaktorów)

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

lub

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

...