Qual é o formato de cabeçalho comum dos arquivos Python?

Encontrei o seguinte formato de cabeçalho para arquivos de origem Python em um documento sobre as diretrizes de codificação Python:

#!/usr/bin/env python

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

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

Esse é o formato padrão de cabeçalhos no mundo Python? Que outros campos / informações posso colocar no cabeçalho? Os gurus do Python compartilham suas diretrizes para obter bons cabeçalhos de código-fonte do Python :-)

São todos os metadados para o Foobarmódulo.

O primeiro é o docstringdo módulo, que já está explicado na resposta de Pedro .

Como organizo meus módulos (arquivos de origem)? (Arquivo)

A primeira linha de cada arquivo deve ser #!/usr/bin/env python. Isso torna possível executar o arquivo como um script invocando o intérprete implicitamente, por exemplo, em um contexto CGI.

Em seguida deve ser a docstring com uma descrição. Se a descrição for longa, a primeira linha deve ser um breve resumo que faça sentido por si só, separado do resto por uma nova linha.

Todo o código, incluindo instruções de importação, deve seguir a documentação. Caso contrário, a docstring não será reconhecida pelo intérprete e você não terá acesso a ela em sessões interativas (por exemplo, através obj.__doc__) ou na geração de documentação com ferramentas automatizadas.

Importe os módulos internos primeiro, seguidos pelos módulos de terceiros, seguidos por quaisquer alterações no caminho e nos seus próprios módulos. Especialmente, é provável que as adições ao caminho e aos nomes dos seus módulos mudem rapidamente: mantê-los em um só lugar os torna mais fáceis de encontrar.

Em seguida deve haver informações de autoria. Esta informação deve seguir este formato:

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

O status normalmente deve ser "Protótipo", "Desenvolvimento" ou "Produção". __maintainer__deve ser a pessoa que corrigirá os erros e fará melhorias se importada. __credits__difere __author__na medida em que __credits__inclui as pessoas que relataram correções de bugs, fizeram sugestões, etc., mas não chegou a escrever o código.

Aqui você tem mais informações, listando __author__, __authors__, __contact__, __copyright__, __license__, __deprecated__, __date__e __version__como reconhecido metadados.

Sou a favor de cabeçalhos mínimos de arquivo, com o que quero dizer apenas:

• O hashbang ( #!linha) se este for um script executável
• Módulo de documentação
• Importações agrupadas da maneira padrão, por exemplo:

  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule  

ie três grupos de importações, com uma única linha em branco entre eles. Dentro de cada grupo, as importações são classificadas. O grupo final, importações da fonte local, pode ser importações absolutas, como mostrado, ou importações relativas explícitas.

Tudo o resto é uma perda de tempo, espaço visual e é ativamente enganador.

Se você tiver isenções de responsabilidade legais ou informações de licenciamento, ele entrará em um arquivo separado. Ele não precisa infectar todos os arquivos de código-fonte. Seus direitos autorais devem fazer parte disso. As pessoas devem ser capazes de encontrá-lo no seu LICENSEarquivo, não no código fonte aleatório.

Metadados como autoria e datas já são mantidos pelo seu controle de origem. Não há necessidade de adicionar uma versão menos detalhada, incorreta e desatualizada das mesmas informações no próprio arquivo.

Não acredito que haja outros dados que todos precisem colocar em todos os seus arquivos de origem. Você pode ter algum requisito específico para fazê-lo, mas essas coisas se aplicam, por definição, apenas a você. Eles não têm lugar em "cabeçalhos gerais recomendados para todos".

As respostas acima são realmente completas, mas se você quiser um cabeçalho rápido e sujo para copiar e colar, use o seguinte:

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

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

Por que essa é boa:

• A primeira linha é para usuários * nix. Ele escolherá o interpretador Python no caminho do usuário, assim escolherá automaticamente o interpretador preferido do usuário.
• O segundo é a codificação do arquivo. Atualmente, todo arquivo deve ter uma codificação associada. UTF-8 funcionará em qualquer lugar. Apenas projetos herdados usariam outra codificação.
• E uma documentação muito simples. Pode preencher várias linhas.

Veja também: https://www.python.org/dev/peps/pep-0263/

Se você acabou de escrever uma classe em cada arquivo, você nem precisa da documentação (ela entraria no documento da classe).

Consulte também o PEP 263 se você estiver usando um conjunto de caracteres não-ascii

Resumo

Este PEP propõe a introdução de uma sintaxe para declarar a codificação de um arquivo de origem Python. As informações de codificação são então usadas pelo analisador Python para interpretar o arquivo usando a codificação fornecida. Mais notavelmente, isso aprimora a interpretação de literais Unicode no código-fonte e torna possível escrever literais Unicode usando, por exemplo, UTF-8 diretamente em um editor compatível com Unicode.

Problema

No Python 2.1, os literais Unicode podem ser gravados apenas usando a codificação baseada em Latin-1 "escape-unicode". Isso torna o ambiente de programação pouco amigável para os usuários de Python que vivem e trabalham em locais não latino-1, como muitos dos países asiáticos. Os programadores podem gravar suas cadeias de caracteres de 8 bits usando a codificação favorita, mas estão vinculados à codificação "unicode-escape" para literais Unicode.

Solução proposta

Proponho tornar a codificação de código-fonte do Python visível e alterável em um arquivo por fonte, usando um comentário especial na parte superior do arquivo para declarar a codificação.

Para tornar o Python ciente dessa declaração de codificação, são necessárias várias mudanças de conceito com relação ao tratamento dos dados do código-fonte do Python.

Definindo a codificação

O Python assumirá o padrão ASCII como codificação padrão se nenhuma outra dica de codificação for fornecida.

Para definir uma codificação de código-fonte, um comentário mágico deve ser colocado nos arquivos de origem como primeira ou segunda linha no arquivo, como:

      # coding=<encoding name>

ou (usando formatos reconhecidos por editores populares)

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

ou

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

...