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

508

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

Ashwin Nanjappa
źródło
Oto dobre miejsce na rozpoczęcie: PEP 257 , który mówi o Docstrings i zawiera linki do kilku innych odpowiednich dokumentów.
Peter,
41
Być może przydatną wskazówką dla osób czytających różne odpowiedzi na to pytanie jest zastanowienie się, do jakich celów oczekują użycia tych nagłówków plików. Jeśli masz konkretny przypadek użycia (np. Mój prawnik twierdzi, że sprawy sądowe zostały utracone, ponieważ programiści nie umieścili informacji o prawach autorskich w każdym pliku). Dodaj i zachowaj informacje potrzebne do tego przypadku. W przeciwnym razie po prostu oddajesz się swojemu fetyszowi OCD.
Jonathan Hartley
haha świetnie @JonathanHartley! Dla moich własnych projektów, jak to ujęłaś, „oddaję się mojemu fetyszowi z OCD”. hahaaha stackoverflow.com/a/51914806/1896134
JayRizzo

Odpowiedzi:

577

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__ = "[email protected]"
__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.

Esteban Küber
źródło
7
Czy tworzenie informacji w nagłówku może być w jakiś sposób zautomatyzowane dla nowych plików?
Hauke
184
Myślę, że wszystkie te metadane po imporcie to zły pomysł. Części tych metadanych, które dotyczą jednego pliku (np. Autor, data), są już śledzone przez kontrolę źródła. Umieszczenie błędnej i nieaktualnej kopii tych samych informacji w samym pliku wydaje mi się niewłaściwe. Części, które odnoszą się do całego projektu (np. Licencja, wersjonowanie), wydają się lepiej znajdować na poziomie projektu, we własnym pliku, a nie w każdym pliku kodu źródłowego.
Jonathan Hartley
28
Zgadzam się całkowicie z Jonathanem Hartleyem. Następna osoba, która odziedziczy kod, ma trzy możliwości: 1) aktualizuje go za każdym razem, gdy edytuje kod 2) pozostawia go w spokoju, w którym to przypadku będzie on niedokładny 3) usuwa wszystko. Opcja 1 to strata czasu, zwłaszcza, że ​​mają absolutnie zerową pewność, że metadane były aktualne, kiedy je otrzymali. Opcje 2 i 3 oznaczają, że zmarnowałeś swój czas na umieszczenie go tam. Rozwiązanie: oszczędzaj czas wszystkim i nie wkładaj go tam.
spookylukey,
77
Nie ma powodu, aby większość plików Pythona miała linię shebang.
Mike Graham
15
Zgodnie z PEP 8, __version__musi bezpośrednio podążać za głównym dokumentowaniem, z pustą linią przed i po. Ponadto najlepszą praktyką jest definiowanie zestawu znaków bezpośrednio pod shebangiem -# -*- coding: utf-8 -*-
Dave Lasley
179

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

Jonathan Hartley
źródło
23
Nie można zgodzić się więcej - replikacja kodu w wielu miejscach jest grzechem, więc po co to samo robić w przypadku informacji w nagłówku. Umieść je w jednym miejscu (katalog główny projektu) i unikaj kłopotów z utrzymywaniem takich informacji w wielu plikach.
Graeme,
13
Chociaż zgadzam się, że kontrola źródła ma tendencję do dostarczania bardziej prawidłowych informacji o autorstwie, czasami autorzy dystrybuują źródło tylko nie dając dostępu do repozytorium, a może tak po prostu działa dystrybucja, np .: scentralizowana instalacja z pypi. Dlatego osadzanie informacji o autorstwie jako nagłówku modułu jest nadal korzystne.
wózek
6
Hej, wózek. Mam problem z wyobrażeniem sobie przypadku użycia, w którym jest to rzeczywiście przydatne. Mogę sobie wyobrazić kogoś, kto chce znać informacje o autorze projektu jako całości, i może uzyskać wartość z listy głównych autorów w jednym centralnym miejscu, na przykład z pliku README lub dokumentów. Ale kto (a) chciałby poznać autorstwo poszczególnych plików i (b) nie miałby dostępu do repozytorium źródłowego, i (c) nie dbałby o to, że nie ma sposobu, aby stwierdzić, czy informacje są nieprawidłowe lub przeterminowany?
Jonathan Hartley,
12
Wiele licencji wymaga dołączenia tablicy rejestracyjnej licencji do każdego pliku z bardzo ważnego powodu. Jeśli ktoś weźmie plik lub dwa i rozprowadzi je bez licencji, ludzie, którzy go otrzymają, nie będą mieli pojęcia, na jakiej licencji to licencja, i będą musieli ją wyśledzić (to znaczy w dobrej wierze).
nyuszika7h
3
Wiele modułów (scipy, numpy, matplotlib) ma jednak __version__metadane i myślę, że warto je mieć, ponieważ powinny one być dostępne dla programów i szybko sprawdzać w interaktywnym tłumaczu. Autorstwo i informacje prawne należą jednak do innego pliku. Chyba że masz przypadek użyciaif 'Rob' in __author__:
endolith
34

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

Neves
źródło
5
> „W dzisiejszych czasach do każdego pliku musi być przypisane kodowanie”. To wydaje się wprowadzać w błąd. utf8 jest domyślnym kodowaniem, więc nie ma potrzeby podawania go.
Jonathan Hartley
23

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

...

John La Rooy
źródło
15
Warto zauważyć, że od Python 3 domyślnym zestawem znaków jest UTF-8.
nyuszika7h