Який загальний формат заголовків файлів Python?

Я натрапив на наступний формат заголовка для вихідних файлів Python в документі про вказівки щодо кодування Python:

#!/usr/bin/env python

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

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

Це стандартний формат заголовків у світі Python? Які ще поля / інформацію я можу розмістити у заголовку? Гуру Python діляться своїми рекомендаціями щодо гарних заголовків джерела Python :-)

Всі його метадані для Foobarмодуля.

Перший - docstringмодуль, що вже пояснено у відповіді Петра .

Як організувати свої модулі (вихідні файли)? (Архів)

Перший рядок кожного файлу повинен бути #!/usr/bin/env python. Це дає можливість запустити файл як скрипт, який викликає інтерпретатор неявно, наприклад, у контексті CGI.

Далі має бути доктрина з описом. Якщо опис довгий, перший рядок повинен бути коротким підсумком, який має сенс самостійно, відокремлений від решти новим рядком.

Весь код, включаючи заяви про імпорт, повинен відповідати докстрингу. В іншому випадку інтерпретатор не розпізнає docstring, і ви не матимете доступу до нього в інтерактивних сесіях (тобто через obj.__doc__) або під час генерації документації за допомогою автоматизованих інструментів.

Спочатку імпортуйте вбудовані модулі, а потім сторонні модулі, а потім будь-які зміни до контуру та власних модулів. Тим більше, що доповнення до шляху та назв ваших модулів, ймовірно, швидко змінюватимуться: зберігання їх в одному місці полегшує пошук.

Далі має бути інформація про авторство. Ця інформація повинна відповідати такому формату:

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

Статус зазвичай повинен бути одним із "Прототипу", "Розробки" або "Виробництва". __maintainer__має бути людиною, яка буде виправляти помилки та вносити поліпшення при імпорті. __credits__відрізняється __author__тим, що __credits__включає людей, які повідомили про виправлення помилок, вносили пропозиції тощо, але насправді не написали код.

Тут у вас є додаткова інформація, роздруківка __author__, __authors__, __contact__, __copyright__, __license__, __deprecated__, __date__і __version__визнані метадані.

Я дуже віддаю перевагу мінімальним заголовкам файлів, під якими я маю на увазі просто:

• Хешбанг ( #!рядок), якщо це виконуваний сценарій
• Модуль докстрингу
• Імпорт, згрупований стандартним способом, наприклад:

  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule  

тобто. три групи імпорту, з єдиним порожнім рядком між ними. У межах кожної групи імпорт сортується. Кінцевою групою, імпорт з місцевого джерела, може бути або абсолютний імпорт, як показано, або явний відносний імпорт.

Все інше - це марна трата часу, візуального простору і активно вводить в оману.

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

Метадані, такі як авторство та дати, вже підтримується вашим джерелом контролю. Немає необхідності додавати менш детальну, помилкову та застарілу версію тієї самої інформації у сам файл.

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

Наведені вище відповіді справді повні, але якщо ви хочете, щоб швидкий і брудний заголовок скопіювати 'вставте, скористайтеся цим:

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

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

Чому це добре:

• Перший рядок призначений для користувачів * nix. Він вибере інтерпретатора Python в користувальницькому шляху, тому автоматично вибере інтерфейс, який надає перевагу користувачеві.
• Другий - кодування файлів. На сьогодні кожен файл повинен мати пов'язане кодування. UTF-8 буде працювати всюди. Просто застарілі проекти використовуватимуть інше кодування.
• І дуже проста документація. Він може заповнити кілька рядків.

Дивіться також: https://www.python.org/dev/peps/pep-0263/

Якщо ви просто записуєте клас у кожен файл, вам навіть документація не потрібна (це входитиме всередину документа докласу).

Також див. PEP 263, якщо ви використовуєте набір символів, що не мають права

Анотація

Цей PEP пропонує ввести синтаксис для оголошення кодування вихідного файлу Python. Інформація про кодування потім використовується аналізатором Python для інтерпретації файлу за допомогою заданого кодування. Особливо це покращує інтерпретацію літералів Unicode у вихідному коді та дає змогу записувати літерали Unicode, використовуючи, наприклад, UTF-8 безпосередньо у відомому редакторі Unicode.

Проблема

У Python 2.1 лінали Unicode можна записати лише за допомогою кодування на основі Latin-1 "unicode-escape". Це робить середовище програмування досить недоброзичливим для користувачів Python, які живуть та працюють у не-латинських регіонах-1, таких як багато країн Азії. Програмісти можуть записувати свої 8-бітні рядки, використовуючи улюблене кодування, але прив’язані до кодування "unicode-escape" для літералів Unicode.

Пропоноване рішення

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

Для того, щоб Python знав про цю декларацію кодування, необхідно змінити декілька концепцій стосовно обробки даних вихідного коду Python.

Визначення кодування

Python за замовчуванням встановить ASCII як стандартне кодування, якщо не вказано інших підказок кодування.

Щоб визначити кодування вихідного коду, магічний коментар повинен бути розміщений у вихідних файлах як перший чи другий рядок у файлі, наприклад:

      # coding=<encoding name>

або (використовуючи формати, визнані популярними редакторами)

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

або

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

...