Jaki jest wspólny format nagłówka plików Pythona?

Zdecydowanie popieram Minimalne nagłówki plików, przez co mam na myśli tylko:

• linia hashbang (#!) jeśli jest to skrypt wykonywalny
• Moduł docstring
• Import, pogrupowany zgodnie z opisem w odpowiedzi voyager .

Jeśli masz zastrzeżenia prawne lub informacje dotyczące licencji, trafiają one do osobnego pliku. Nie musi zainfekować KAŻDEGO pliku kodu źródłowego. Twoje prawa autorskie powinno być częścią tego. Ludzie powinni być w stanie znaleźć go w Twoim pliku LICENSE, a nie w losowym kodzie źródłowym.

Metadane, takie jak autorstwo i Daty, są już utrzymywane przez kontrolę źródła. Nie ma potrzeby dodawania mniej szczegółowej, błędnej i nieaktualnej wersji tych samych informacji w samym pliku.

Nie wierzę, że są jakieś inne dane, które każdy musi umieścić we wszystkich swoich plikach źródłowych. Możesz mieć jakiś szczególny wymóg, aby to zrobić, ale takie rzeczy mają zastosowanie, przez definicja, tylko dla Ciebie. Nie mają miejsca w "nagłówkach ogólnych polecanych wszystkim".

Zobacz także PEP 263 Jeśli używasz zestawu znaków spoza ascii

Streszczenie

Ten PEP proponuje wprowadzenie składni deklarującej kodowanie plik źródłowy Pythona. Informacje o kodowaniu są następnie wykorzystywane przez Python parser do interpretacji pliku przy użyciu podanego kodowania. Najbardziej szczególnie poprawia to interpretację literałów Unicode w kod źródłowy i umożliwia pisanie literałów Unicode używając np. UTF-8 bezpośrednio w edytorze Unicode aware.

Problem

W Pythonie 2.1 literały Unicode mogą być pisane tylko przy użyciu Kodowanie oparte na Latin-1 "unicode-escape". To sprawia, że środowisko programistyczne raczej nieprzyjazne dla Użytkowników Pythona, którzy żyją i pracować w nie-łacińskich-1 lokalizacjach, takich jak wiele azjatyckich krajów. Programiści mogą pisać swoje 8-bitowe ciągi za pomocą ulubione kodowanie, ale są powiązane z kodowaniem" unicode-escape" dla Unicode literały.

Proponowane Rozwiązanie

Proponuję aby kod źródłowy Pythona był widoczny i możliwość zmiany na podstawie pliku źródłowego za pomocą specjalnego komentarza na górze pliku, aby zadeklarować kodowanie.

Aby uczynić Pythona świadomym tej deklaracji kodowania szereg zmiany koncepcji są niezbędne w odniesieniu do obsługi Dane kodu źródłowego Pythona.

Definiowanie kodowania

Python będzie domyślnie do ASCII jako standardowego kodowania, jeśli nie ma innych podane są wskazówki dotyczące kodowania.

Aby zdefiniować kodowanie kodu źródłowego, magiczny komentarz musi być umieszczone w plikach źródłowych jako pierwsze lub drugie wiersz w pliku, np.:

      # coding=<encoding name>

Lub (przy użyciu formatów rozpoznawanych przez popularne edytory)

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

Lub

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

...

Powyższe odpowiedzi są naprawdę kompletne, ale jeśli chcesz mieć szybki i brudny nagłówek do kopiowania i wklejania, użyj tego:

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

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

Dlaczego to jest dobre:

• pierwsza linia jest dla użytkowników *nix. Wybierze interpreter Pythona w ścieżce użytkownika, więc automatycznie wybierze preferowany przez użytkownika interpreter.
• drugi to kodowanie plików. Obecnie każdy plik musi mieć kodowanie powiązane. 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 też: https://www.python.org/dev/peps/pep-0263/

Jeśli po prostu napiszesz klasę w każdym pliku, nie potrzebujesz nawet dokumentacji (byłaby ona wewnątrz klasy doc).