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

508

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

Ashwin Nanjappa
fonte
Aqui está um bom ponto de partida: PEP 257 , que fala sobre o Docstrings, e links para vários outros documentos relevantes.
Peter
41
Talvez uma orientação útil para quem lê as respostas diferentes para essa pergunta seja considerar para que finalidades eles esperam que esses cabeçalhos de arquivo sejam usados. Se você tiver um caso de uso concreto (por exemplo, meu advogado diz que os processos judiciais foram perdidos porque os desenvolvedores não colocaram informações de direitos autorais em cada arquivo), adicione e mantenha as informações necessárias para esse caso de uso. Caso contrário, você estará apenas entregando seu fetiche por TOC.
22612 Jonathan Swinley
haha great @JonathanHartley! Para meus próprios projetos, como você diz: "Eu concordo com meu fetiche por TOC". hahaaha stackoverflow.com/a/51914806/1896134
JayRizzo

Respostas:

577

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

Esteban Küber
fonte
7
A criação das informações do cabeçalho pode de alguma forma ser automatizada para novos arquivos?
Hauke
184
Acho que todos esses metadados após as importações são uma má ideia. As partes desses metadados que se aplicam a um único arquivo (por exemplo, autor, data) já são rastreadas pelo controle de origem. Colocar uma cópia incorreta e desatualizada da mesma informação no próprio arquivo parece errado para mim. As partes que se aplicam a todo o projeto (por exemplo, licença, versão) parecem melhor localizadas no nível do projeto, em um arquivo próprio, e não em cada arquivo de código-fonte.
10132 Jonathan Hartley
28
Concordo totalmente com Jonathan Hartley. A próxima pessoa a herdar o código tem três opções: 1) atualize-o toda vez que editar o código; 2) deixe-o em paz; nesse caso, será impreciso; 3) exclua tudo. A opção 1 é um desperdício de tempo, especialmente porque eles têm absolutamente zero confiança de que os metadados estavam atualizados quando o receberam. As opções 2 e 3 significam que seu tempo para colocá-lo lá em primeiro lugar foi desperdiçado. Solução: economize o tempo de todos e não o coloque lá.
Spookylukey
77
Não há razão para a maioria dos arquivos Python ter uma linha shebang.
Mike Graham
15
De acordo com o PEP 8, é __version__necessário seguir diretamente a doutrina principal, com uma linha em branco antes e depois. Além disso, é melhor prática para definir o seu charset imediatamente sob a shebang -# -*- coding: utf-8 -*-
Dave Lasley
179

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

Jonathan Hartley
fonte
23
Não poderia concordar mais - é um pecado replicar o código em vários lugares; por que fazer o mesmo para obter informações de cabeçalho? Coloque-o em um único local (raiz do projeto) e evite o incômodo de manter essas informações em muitos arquivos.
Graeme
13
Embora eu concorde que o controle de origem tenda a fornecer informações de autoria mais válidas, às vezes os autores apenas distribuem a fonte sem dar acesso ao repositório, ou talvez seja assim que a distribuição funciona, por exemplo: instalação centralizada a partir do pypi. Assim, a incorporação de informações de autoria como um cabeçalho de módulo ainda é benéfica.
pram
6
Hey Pram. Estou tendo problemas para visualizar um caso de uso em que isso é realmente útil. Posso imaginar alguém querendo saber as informações de autoria do projeto como um todo, e elas podem obter valor de uma lista dos principais colaboradores em um único local central, talvez o README ou o documento do projeto. Mas quem (a) gostaria de saber a autoria de arquivos individuais e (b) não teria acesso ao repositório de origem e (c) não se importaria se nunca houvesse uma maneira de saber se as informações estavam incorretas ou desatualizado?
Jonathan Hartley
12
Muitas licenças exigem que você inclua o padrão da licença em cada arquivo por um motivo muito bom. Se alguém pega um arquivo ou dois e os redistribui sem a licença, as pessoas que o recebem não têm idéia de qual licença está e terão que rastreá-lo (supondo que estejam de boa fé).
precisa saber é o seguinte
3
Muitos módulos (scipy, numpy, matplotlib) possuem __version__metadados, e acho que é bom ter, pois ele deve estar acessível aos programas e verificar rapidamente no intérprete interativo. Autoria e informações legais pertencem a um arquivo diferente, no entanto. A menos que você tem um caso de uso paraif 'Rob' in __author__:
endolith
34

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

Neves
fonte
5
> "Atualmente, todo arquivo deve ter uma codificação associada." Isso parece enganador. utf8 é a codificação padrão, por isso é perfeitamente bom não especificá-la.
Jonathan Hartley
23

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

...

John La Rooy
fonte
15
Vale ressaltar que, desde Python 3, o conjunto de caracteres padrão é UTF-8.
precisa saber é o seguinte