Cabeçalho de arquivo Python

Um cabeçalho de arquivo Python é uma documentação opcional no início de um arquivo-fonte. Um projeto pode adotar um formato comum para explicar a finalidade, o uso pretendido, os requisitos e a licença de um script; o próprio Python não exige um cabeçalho específico. Mantenha apenas as informações que ajudem alguém a entender ou executar o arquivo e siga as convenções do projeto. Boas práticas como esta fazem parte dos fundamentos reunidos no tutorial de Python completo.

Por que usar um formato comum de cabeçalho em Python

Um cabeçalho consistente dá aos leitores um contexto útil antes que leiam a implementação. Ele pode indicar a finalidade do script, quem o mantém, como executá-lo e quaisquer requisitos importantes de execução ou dependências. Um aviso de licença também pode esclarecer como o código pode ser usado, desde que corresponda à licença efetiva do projeto.

O formato é uma convenção da equipe, não um recurso da linguagem Python. Um pequeno script feito para uma única ocasião talvez precise apenas de uma breve descrição do módulo, enquanto uma ferramenta de linha de comando distribuída pode se beneficiar de notas sobre uso e dependências. A consistência ajuda quando vários arquivos compartilham um repositório, mas copiar campos que não se aplicam gera excesso de informação e pode deixar dados desatualizados.

Componentes de um cabeçalho de arquivo Python

Escolha os componentes conforme a forma como o arquivo é executado e mantido. Um cabeçalho costuma combinar informações sobre o interpretador, uma docstring do módulo e comentários destinados às pessoas que leem o código.

Linha shebang

Uma linha shebang é um marcador na primeira linha, como #!/usr/bin/env python3. Nos sistemas que a reconhecem, executar um script pelo caminho, após torná-lo executável, usa o interpretador selecionado por env. Ela é útil para scripts de linha de comando em sistemas do tipo Unix, mas não é necessária quando o arquivo é iniciado com um comando como python script.py. Essa linha não instala o Python nem seleciona um ambiente para todas as formas de iniciar o arquivo.

Declaração de codificação

Arquivos de código-fonte Python 3 usam UTF-8 por padrão, então normalmente não é necessário declarar a codificação. Se um arquivo usar outra codificação por compatibilidade com uma ferramenta ou ambiente específico, o Python reconhece uma declaração como # -*- coding: latin-1 -*- na primeira ou na segunda linha. A declaração deve corresponder à codificação real do arquivo; ela não é um marcador genérico que torna qualquer texto legível.

Docstring do módulo e comentários

Uma docstring do módulo é um literal de string no início do módulo, depois de qualquer linha shebang ou comentário de codificação. Ela descreve o módulo e fica disponível em __doc__. Use-a para indicar brevemente a finalidade e fornecer contexto útil sobre o módulo. Comentários comuns podem conter informações sobre manutenção, uso, dependências, versão ou licença; o Python não interpreta esses comentários automaticamente como metadados.

As importações devem vir depois da docstring do módulo e antes das demais instruções executáveis do módulo. Quando forem necessárias, uma convenção comum é agrupar primeiro as importações da biblioteca padrão, depois os pacotes de terceiros e, por último, as importações locais do projeto, separando os grupos com uma linha em branco.

Um cabeçalho pode indicar como executar um script, quais pacotes são necessários ou qual é a versão mínima do Python, quando essas informações forem relevantes. Mantenha os requisitos alinhados à configuração real do projeto. Inclua um aviso de licença apenas se ele corresponder à licença escolhida para o código e evite datas pessoais ou históricos de edição que rapidamente ficam desatualizados.

Exemplo de cabeçalho de arquivo Python

Este script independente mostra um cabeçalho conciso com uma linha shebang, uma docstring do módulo e comentários com informações que a pessoa responsável pela manutenção deve substituir por dados específicos do projeto. A descrição e os comentários são documentação; a função e a verificação de execução direta são código Python executável.

#!/usr/bin/env python3
"""Print a short status message for a sample command-line tool."""

# Maintainer: Replace with a team or owner.
# Usage: python status_report.py
# License: Replace with the project's actual license.

def main():
    print("Report ready")


if __name__ == "__main__":
    main()

Adapte os comentários ao arquivo: inclua notas sobre dependências ou versões do Python somente quando afetarem a configuração ou o uso. O exemplo não tem dependências externas, portanto não precisa de uma lista de importações. A linha shebang é relevante quando o arquivo é iniciado como executável em um sistema que a reconhece; ao executá-lo com python status_report.py, o interpretador usado é aquele indicado no comando.

Boas práticas para cabeçalhos de arquivos Python

• Mantenha o cabeçalho curto e concentrado nas informações que ajudem alguém a usar ou manter o arquivo.
• Siga o formato já adotado pelo projeto para facilitar a leitura de arquivos relacionados.
• Coloque a docstring do módulo antes das importações e use comentários para notas que não façam parte da string de documentação do módulo.
• Antes de incluir informações sobre o interpretador, dependências ou licença, confira se correspondem à configuração atual do projeto.
• Atualize ou remova notas quando deixarem de ser precisas; omita campos como autoria ou data de modificação quando o projeto já os registra em outro lugar.

Um bom cabeçalho comum é o menor que fornece à próxima pessoa desenvolvedora o contexto necessário. Trate-o como documentação viva e deixe que as convenções do projeto determinem quais informações opcionais pertencem a cada arquivo.