Escrituração de versão

Se você precisa usar o Subversion, CVS, ou RCS crud em seu arquivo de origem, faça como no exemplo abaixo.


Estas linhas devem ser incluídas após a docstring do módulo, antes de qualquer outro código, separadas por uma linha em branco acima e abaixo.

Convenções de nomenclatura

As convenções de nomenclatura da biblioteca Python são um pouco confusas, por isso, nunca vamos tê-las completamente consistentes - no entanto, aqui estão os padrões de nomenclatura recomendados. Novos módulos e pacotes (incluindo os de terceiros) devem ser escritos seguindo essas normas, mas em uma biblioteca existente que tenha um estilo diferente, a consistência interna é preferida.

Há uma série de diferentes estilos de nomeação.Ela ajuda a ser capaz de reconhecer qual estilo está sendo utilizada, independentemente do que eles são usados.

Os estilos de nomeação que se seguem são comumente observados:

• b (uma letra minúscula)
• (uma letra maiúscula)
• minúsculas
• minúsculas_com_underscores
• MAIÚSCULAS
• MAIÚSCULAS_COM_UNDERSCORES
• IniciaisMaiúsculas (ou CapWords ou CamelCase)

NOTA: Quando usar abreviações em CapWords, capitalizar todas as letras da sigla. Assim HTTPServerError é melhor que HttpServerError.

• mixedCase (diferente de IniciaisMaiúsculas pela inicial minúscula)
• Iniciais_Maiúsculas_Com_Underscores (feio!)

Há também o estilo da utilização de um prefixo curto para grupo de nomes relacionados. Isso não é muito usado em Python.

Por exemplo, o os.stat() retorna uma tupla cujos itens tradicionalmente têm nomes como st_mode, st_size, st_mtime e assim por diante.

A biblioteca X11 usa uma inicial X para todas as suas funções públicas. Em Python, este estilo é geralmente considerado desnecessário porque atributos e nomes de métodos são prefixados com um objeto, e os nomes das funções são precedidas por um nome de módulo.

• _um_underscore_inicial: Indicador de uso interno. Por exemplo: "from M import *" não importa os objetos cujo nome começa com um underscore.
• um_underscore_final_: utilizado por convenção para evitar conflitos com palavras-chave Python. Exemplo:
  
      Tkinter.Toplevel(master, class_ = 'className')
  
  
• __double_leading_underscore: Ao nomear um atributo de classe, invoca a desconfiguração do nome (dentro da classe FooBar, __boo se torna _FooBar__boo).
• __double_leading_and_trailing_underscore__: Objetos "mágicos" ou atributos que vivem em espaços de nome controlado pelo usuário. Por exemplo: __init__, __import__ ou __file__. Nunca invente tais nomes, apenas use-os como documentado.

Nunca use os caracteres 'l' (ele minúsculo), 'O' (o maiúsculo), ou I, (i maiúsculo) como nome de uma variável de um caractere.

Em algumas fontes, esses caracteres são indistinguíveis dos numerais um e zero. Quando tentado a usar o 'l', use' L' em seu lugar.

Módulos devem ter todo o nome em minúsculas. Underscores podem ser usados no nome do módulo se ele melhora a legibilidade. Pacotes Python devem ter um nome curto, todo em minúsculas, embora nesse caso o uso de sublinhados seja desencorajado.

Uma vez que nomes de módulos são mapeados para nomes de arquivos, e alguns sistemas de arquivos não diferenciam maiúsculas de minúsculas e truncam nomes longos, é importante que o nome do módulo escolhido seja bastante curto - isto não será um problema em Unix, mas pode ser um problema quando o código é transportado para Macs mais velhos ou Windows e DOS.

Quando um módulo de extensão escrito em C e C++ tem um módulo em Python como acompanhamento que forneça uma interface com mais alto nível (por exemplo, mais orientada a objetos), o módulo em C/C++ começa com um underscore (_socket, por exemplo).

Quase sem exceção, os nomes de classe usam a convenção IniciaisMaiúsculas. Classes para uso interno, além disso, começam com um underscore.

Como exceções são classes, a convenção de nomes para classes se aplica aqui. No entanto, você deve usar o sufixo "Error" no nome de sua exceção (se a exceção é um erro).

As convenções para variáveis globais são as mesmas para as funções. Os módulos que são projetados para uso via "from M import *" devem usar o mecanismo de prevenção __all__ para prevenir que globais para uso interno sejam exportadas ou um underscore no começo do nome.

Nomes de funções devem estar em letras minúsculas, com palavras separadas por sublinhados como necessárias para melhorar a legibilidade. mixedCase é permitido apenas em contextos onde já é o estilo predominante (por exemplo, threading.py), para manter compatibilidade com versões anteriores.

Sempre use "self" como primeiro argumento para métodos de instância.

Use sempre "cls" como primeiro argumento para métodos de classe.

Se há confronto de um argumento de função e o uma palavra-chave reservada, é geralmente melhor para adicionar um único sublinhado à direita ao invés de usar uma abreviatura ou corrupção de ortografia. Assim, "print_" é melhor do que "prnt" (talvez o melhor seja evitar tais confrontos, usando um sinônimo).

Para métodos e atributos e instância, use a regra de nomeação para funções: letras minúsculas, com palavras separadas por sublinhados como necessárias para melhorar a legibilidade.

Use um sublinhado no começo apenas para os métodos não-públicos e variáveis de instância.

Para evitar confrontos de nome com subclasses, use dois underscores para invocar as regras de desconfiguração de nomes. O Python desconfigura esses nomes com o nome da classe: se uma classe Foo tem um atributo chamado __a, ele não pode ser acessado por Foo.__a. (Um usuário insistente pode ganhar acesso chamando Foo._Foo__a.) Geralmente, dois underscores devem ser usados apenas para evitar conflitos de nomes com atributos de classes concebido para ser uma subclasse.

Constantes são declaradas normalmente em um nível de módulo em MAIÚSCULAS_COM_UNDERSCORES. Exemplos: MAX_OVERFLOW, TOTAL.

Sempre decidir se as variáveis de métodos de uma classe e instância (atributos) devem ser públicos ou não. Em caso de dúvida, optar por não-públicos, é mais fácil para torná-lo público do que tornar um atributo público em não-público.

Atributos públicos são aqueles que você espera que os clientes independentes de sua classe usem, com o seu compromisso para evitar incompatibilidade para trás.Atributos não-públicos são aqueles que não se destinam a ser utilizados por terceiros.

Você não faz nenhuma garantia de que os atributos não-públicos não mudarão ou mesmo serão removidos.

Nós não usamos o termo "privado" aqui, uma vez que nenhum atributo é realmente privado em Python (em geral sem uma quantidade desnecessária de trabalho).

Outra categoria de atributos são aqueles que fazem parte da "API de subclasse" (muitas vezes chamado de "protegidos" em outras línguas). Algumas classes são projetadas para serem herdadas, seja para estender ou modificar os aspectos do comportamento de classe. Ao criar uma classe, tenha o cuidado de fazer decisões explícitas sobre quais atributos são públicos, quais fazem parte da a API de subclasse, e quais só pode ser usado por sua classe base.

Atributos públicos não devem ter underscores.

Se o nome de seu atributo público colide com uma palavra-chave reservada, acrescente um sublinhado à direita do nome do seu atributo. Isto é preferível a uma abreviatura ou ortografia corrompido. (Entretanto, 'cls' é a grafia preferida para qualquer variável ou argumento que é conhecido por ser uma classe, especialmente o primeiro argumento para um método de classe).