O que significa a variável __all__ em Python?

Ao navegar pelos módulos e pacotes do Python, você pode ter se deparado com a variável __all__ nos arquivos __init__.py e se perguntado sobre o propósito dela. Vamos desvendar essa variável especial e entender como ela influencia o comportamento de importação no Python.

Entendendo all em Módulos Python

Em Python, __all__ é uma lista de strings que define quais símbolos (funções, variáveis, classes, etc.) um módulo irá exportar quando você usa a sintaxe from <module> import *. Por exemplo, considere um módulo chamado foo.py com o seguinte conteúdo:

__all__ = ['bar', 'baz']

waz = 5
bar = 10
def baz(): return 'baz'

Se você importar esse módulo usando from foo import *, apenas bar e baz serão importados para o seu namespace. Tentar acessar waz resultará em uma exceção porque ele não está incluído em __all__ e, portanto, não é exportado pelo módulo.

O Papel de all em Pacotes

Quando se trata de pacotes Python, __all__ desempenha um papel semelhante, mas em nível de pacote. O arquivo __init__.py dentro de um diretório de pacote o torna um pacote Python e pode ser usado para inicializar o pacote ou definir a variável __all__.

Por exemplo, se você tem um pacote com dois módulos, module_1.py e module_2.py, e deseja expor certas funções ou classes como uma API pública, você pode definir __all__ no arquivo __init__.py:

# __init__.py
__all__ = ['foo', 'Bar']

Agora, quando alguém importar seu pacote usando from package import *, terá acesso apenas a foo e Bar, assumindo que esses estão definidos nos respectivos módulos e incluídos em suas listas __all__.

Ferramentas de Documentação e Autocompletar

Geradores de documentação e ferramentas de autocompletar código frequentemente usam __all__ para determinar quais nomes exibir como disponíveis de um módulo. Ao declarar os nomes públicos em __all__, você deixa claro quais partes do seu módulo são destinadas ao uso público e quais são detalhes internos.

Gerenciando uma API com all

Usar __all__ permite gerenciar efetivamente a API do seu pacote. Você pode controlar quais partes dos seus módulos são expostas aos usuários e manter os detalhes de implementação ocultos. Isso é particularmente útil quando você tem um pacote grande com vários módulos e subpacotes.

Prefixando _ versus all

Enquanto __all__ define explicitamente o que é exportado, o Python também tem a convenção de prefixar um nome com um sublinhado (_) para indicar que se destina a ser privado. No entanto, usar __all__ pode ser mais explícito e é frequentemente preferido na comunidade Python.

Quando Usar all

É geralmente uma boa prática definir __all__ no início do ciclo de vida de desenvolvimento de um módulo ou pacote. No entanto, se você ainda está nos estágios iniciais de desenvolvimento ou ajustando ativamente sua API, pode preferir seguir a convenção de prefixo de sublinhado até que sua API esteja mais estável.

Resumo

Em resumo, __all__ em Python é um mecanismo para definir a interface pública de um módulo ou pacote. Ele especifica quais nomes são destinados ao uso público ao importar com from <module> or package> import *. Ao usar __all__, você pode gerenciar a exposição da sua API, manter seu namespace limpo e comunicar aos usuários e ferramentas quais partes do seu código são destinadas ao uso externo.