Каков общий формат заголовка файлов Python?

Я, безусловно, выступаю за минималистские заголовки файлов. Под этим я имею в виду следующее:

#!/usr/bin/env python # [1]
"""\
Этот скрипт выполняет операции с заданными параметрами [2]

Использование: myscript.py BAR1 BAR2
"""
import os   # стандартная библиотека, [3]
import sys

import requests  # сторонние пакеты

import mypackage  # локальный источник

• [1] Хэшбенг стоит использовать только в том случае, если файл должен быть исполняемым, то есть его можно запускать как myscript.py, myscript или даже python myscript.py. (Хэшбенг не используется в последнем случае, но он предоставляет пользователям возможность запускать файл любым из этих способов.) Хэшбенг не следует включать, если файл является модулем, предназначенным только для импорта в другие Python-файлы.
• [2] Докстрока модуля
• [3] Импорты, сгруппированные стандартным образом: три группы импортов с одной пустой строкой между ними. Внутри каждой группы импорты сортируются. Последняя группа – импорты из локального источника – может быть как абсолютными, как показано, так и явными относительными.

Все остальное — пустая трата времени как для автора, так и для последующих разработчиков. Это занимает драгоценное визуальное пространство в верхней части файла информацией, которая лучше отслеживается в другом месте, и легко устаревает, становясь активно вводящей в заблуждение.

Если у вас есть юридические оговорки или информация о лицензировании, помещайте это в отдельный файл. Не нужно заполнять каждую исходную часть кода. Ваши авторские права также должны быть частью этого. Люди должны иметь возможность находить такую информацию в вашем файле LICENSE, а не в случайном исходном коде.

Метаданные, такие как авторство и даты, уже поддерживаются вашей системой управления версиями. Нет необходимости добавлять менее подробную, ошибочную и устаревшую версию этих сведений непосредственно в файл.

Я не верю, что есть какие-либо другие данные, которые всем нужно помещать во все свои исходные файлы. У вас могут быть особые требования для этого, но такие вещи по определению касаются только вас. Они не имеют места в “общих заголовках, рекомендуемых для всех”.

Ответы выше действительно достаточно полные, но если вам нужен быстрый и простой заголовок для копирования и вставки, используйте следующий:

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

"""Документация модуля здесь
   и здесь
   и ...
"""

Почему это хороший вариант:

• Первая строка предназначена для пользователей *nix. Она выберет интерпретатор Python из пути пользователя, что автоматически выбирает предпочтительный интерпретатор.
• Вторая строка указывает кодировку файла. В современные времена каждый файл должен иметь ассоциированную кодировку. UTF-8 будет работать везде. Только устаревшие проекты могут использовать другие кодировки.
• А также очень простая документация. Она может занимать несколько строк.

Смотрите также: https://www.python.org/dev/peps/pep-0263/

Если вы просто пишете класс в каждом файле, вам даже не нужна документация (она будет в документации класса).