Para quê serve o arquivo “__init__.py” em uma pasta de código Python?

Quando você está aprendendo Python, pode se deparar com um arquivo chamado __init__.py em vários diretórios e se perguntar sobre sua finalidade. Vamos entender o que esse arquivo faz e por que ele é importante para pacotes Python.

Curso Gratuito

Seu primeiro projeto Python – curso grátis com certificado!

Vá do zero ao primeiro projeto em apenas 2 horas com o curso Python para Iniciantes.

Comece agora

Entendendo o Papel do __init__.py

O arquivo __init__.py desempenha um papel crucial na estrutura de pacotes Python. Ele costumava ser um componente obrigatório de um pacote nas versões do Python anteriores à 3.3. Esse arquivo marca um diretório como um diretório de pacote Python, o que significa que o Python conseguirá importar os arquivos dentro desse diretório como parte de um pacote.

O arquivo __init__.py ajuda o Python a encontrar pacotes em subpastas

Imagine que você tenha a seguinte estrutura de arquivos:

minha_pasta/
    subpasta/
        __init__.py
        modulo.py

Se minha_pasta estiver no seu caminho Python, você pode importar o código em modulo.py usando:

import subpasta.modulo

ou

from subpasta import modulo

Até Python 3.3, era obrigatório possuir um arquivo __init__.py para que o Python conseguisse importar seus arquivos. Nas versões mais recentes, isso não é mais uma necessidade explícita. Mesmo assim, em muitos casos este arquivo ajuda o Python a reconhecer arquivos para importar. Se você se deparar com ImportError ao tentar importar os seus próprios códigos, tente criar arquivos __init__.py e confira se isso ajuda com seu problema.

O arquivo __init__.py pode conter código de inicialização para ser importado

O arquivo __init__.py também pode ser usado para realizar tarefas de inicialização de pacotes e para definir funções de conveniência. Por exemplo, se você tem um pacote que interage com um banco de dados, você pode ter um arquivo __init__.py que se parece com isto:

# Arquivo: database/__init__.py

import os
from sqlalchemy.orm import sessionmaker
from sqlalchemy import create_engine

engine = create_engine(os.environ['DATABASE_URL'])
Session = sessionmaker(bind=engine)

Com essa configuração, você pode iniciar uma nova sessão de banco de dados de qualquer lugar do seu projeto usando:

from database import Session
sessao = Session()

Com a importação from database import Session, todo o código de __init__.py é executado. Assim, o seu código tem acesso a qualquer variável ou objeto que se encontra lá. Note também que não se deve usar o nome __init__.py na importação (isto é, importamos com from database import Session, e não from database.__init__ import Session).

Dito isso, lembre-se de não escrever código muito extenso no __init__.py (a não ser que você tenha um bom motivo para isso). Embora o __init__.py possa conter qualquer código Python, o consenso na comunidade Python é que ele deve ser mantido com o mínimo de código possível.

O arquivo __init__.py simplifica importações de módulos em subpastas

O arquivo __init__.py é frequentemente usado para fornecer uma interface conveniente para o pacote, importando componentes-chave para que os usuários não precisem conhecer a estrutura exata do seu pacote.

Por exemplo, se você tem vários módulos no seu pacote, você pode importar suas funções em __init__.py para que os usuários possam acessá-las diretamente do pacote:

# Arquivo: seu_pacote/__init__.py

from .arquivo1 import adicionar, subtrair
from .arquivo2 import funcao_importante
from submodulo.arquivo3 import *
# ...

Isso permite que os usuários façam algo como isto:

from seu_pacote import adicionar

Em vez de:

from seu_pacote.arquivo1 import adicionar

Resumo

O arquivo __init__.py é um componente-chave dos pacotes Python. Ele marca diretórios como diretórios de pacotes Python, pode conter código de inicialização e facilita para os usuários a importação do conteúdo do pacote. Lembre-se de manter o __init__.py simples e usá-lo para tornar seu pacote mais amigável ao usuário sem esconder sua estrutura.