Módulos e Pacotes Python

Ref.: Things DAQ: Python Modules and Packages, blog criando em 2023 de Eduardo Nigro, engenheiro mecatrônico (atualmente Chief Technical Engineer na International, Ilinóis; graduado na USP).

Intro

Quando você começa a escrever códigos mais complexos ou a criar classes e funções que você usa o tempo todo, faz sentido ter esse código dentro de um módulo Python.

A ideia aqui é passar uma explicação de nível mais alto usando alguns diagramas e código simples. Uma explicação bem completa pode ser encontrada na documentação oficial do Python para Módulos, da qual eu cito:

“Python tem uma maneira de colocar definições em um arquivo e usá-las em um script ou em uma instância interativa do interpretador. Tal arquivo é chamado de módulo; definições de um módulo podem ser importadas para outros módulos ou para o módulo principal.“

Além disso, você pode agrupar módulos relacionados em um pacote Python. Em termos gerais, os pacotes residem no seu computador como uma estrutura de pastas com um arquivo especial neles. A ilustração abaixo mostra como alguns pacotes ficariam em uma estrutura de pastas:

Diferentes pacotes em diferentes pastas:	Conteúdo interno de um pacote

Observe os arquivos __init__.py em cada pasta de pacote. Eles são necessários para que o Python trate os diretórios como pacotes. No cenário mais simples, pode ser um arquivo vazio. Ele também pode conter código de inicialização para o pacote.

Dentro de cada pasta de pacote, além do arquivo __init__.py, há os arquivos de módulo. No caso mostrado acima, package_1 contém module_a.py e module_b.py. Cada módulo pode conter qualquer número de classes e/ou funções, bem como código de inicialização.

Vamos criar alguns módulos fictícios para package_1 e package_2 contendo algumas classes e funções vazias. Em uma plataforma Windows, as pastas de pacotes podem ser criadas onde seus aplicativos Python são mantidos. Digamos que as pastas:

C:\Users\myusername\python\mypackages\package_1
C:\Users\myusername\python\mypackages\package_2

Assim como mostrado na ilustração anterior, certifique-se de que cada pasta de pacote tenha um arquivo __init__.py vazio e os seguintes arquivos de módulos:

Seguem módulos criados em outro diretório: ..\package_1\:

Script modulo_a.py:

​x
"""
This is module_a.py located in package_1.
​
"""
# Eventual initialization code
​
​
# Classes
class MyClassA:
    pass
​
class MyClassB:
    pass
​
​
# Functions
def myfunction_a():
    pass
​
def myfunction_b():
    pass

Script modulo_a.py:

xxxxxxxxxx
"""
This is module_b.py located in package_1.
​
"""
# Eventual initialization code
​
​
# Classes
class MyClassC:
    pass
​
class MyClassD:
    pass
​
​
# Functions
def myfunction_a():
    pass
​
def myfunction_c():
    pass

Seguem módulos criados em outro diretório: ..\package_2:

Script module_a.py:

xxxxxxxxxx
"""
This is module_a.py located in package_2.
​
"""
# Eventual initialization code
​
​
# Classes
class MyClassE:
    pass
​
class MyClassF:
    pass
​
​
# Functions
def myfunction_e():
    pass
​
def myfunction_f():
    pass

Script ,moduloe_c.py:

xxxxxxxxxx
"""
This is module_c.py located in package_2.
​
"""
# Eventual initialization code
​
​
# Classes
class MyClassG:
    pass
​
class MyClassH:
    pass
​
​
# Functions
def myfunction_g():
    pass
​
def myfunction_h():
    pass

Setando o PYTHONPATH

Antes de começarmos a importar módulos e seus componentes, temos que garantir que a pasta mypackages possa ser encontrada pelo interpretador Python. Uma boa maneira de garantir que esse seja sempre o caso é adicioná-la à variável de ambiente PYTHONPATH.

Em plataformas Windows, abra o editor de variáveis de ambiente usando a barra de pesquisa. Em seguida, escolha o botão Environment Variables para acessar as listas de variáveis de usuário e de sistema:

Acessar Ambientes do SO	Ajuste de "Environment Variables"

Em System variables, se ainda não houver uma variável PYTHONPATH, crie uma nova, como mostrado a seguir. Caso contrário, você pode adicionar o caminho do pacote ao existente (separado por ponto e vírgula):

Importando Classes e Funções

A maneira mais elegante de importar classes e funções de um pacote é usando a notação de ponto (dot) para ir diretamente para o componente desejado. Depois que a pasta mypackages tiver sido adicionada ao PYTHONPATH, você pode tentar as seguintes importações:

xxxxxxxxxx
>>> from package_1.module_a import MyClassA
>>> from package_2.module_a import MyClassE

Desde que os componentes que estão sendo importados tenham nomes distintos (MyClassA e MyClassE), pacotes diferentes podem ter módulos com o mesmo nome. Conforme discutido em Classes vs Funções, múltiplas instâncias de cada classe podem então ser criadas:

xxxxxxxxxx
>>> instanceA0 = MyClassA()
>>> instanceA1 = MyClassA()
>>> instanceE0 = MyClassE()

Embora não seja comum com classes, às vezes as funções são importadas com um nome diferente (mais conveniente):

xxxxxxxxxx
>>> from package_2.module_a import myfunction_e as fe
>>> from package_2.module_c import myfunction_g as fg

Mais sobre pacotes Python

E quanto aos pacotes que podemos instalar usando pip (programa instalador preferido)? Eles também são uma coleção de módulos que podem nos ajudar a resolver problemas específicos, organizados de forma organizada em pacotes distribuíveis autocontidos.

No caso do autor desta referência, o mesmo possui direitos de administrador em uma plataforma Windows executando Python 3.9, os pacotes instalados do pip acabam na pasta C:\Program Files\Python39\Lib\<site-packages>. Esse local entra automaticamente no caminho de pesquisa do Python e não precisa estar na variável de ambiente PYTHONPATH. Os módulos nesses pacotes (como numpy ou scipy) estão prontamente disponíveis para importações em seu código.

Pacotes mais profissionais podem ser encontrados no repositório público PyPi (Python Package Index). Na verdade, qualquer um pode criar um pacote e enviá-lo para o repositório PyPi. Como de costume, há uma ótima documentação oficial sobre como distribuir seus próprios módulos python aqui. Embora o processo possa ser um pouco complicado, há algum tempo criei meus próprios pacotes (pyev3 e labjack-unified) e os adicionei ao repositório!

Ref.: Things DAQ: Python Modules and Packages, blog criando em 2023 de Eduardo Nigro, engenheiro mecatrônico americano (Chief Technical Engineer na International, Ilinóis; graduado na USP).

Tradução livre: Fernando Passold, em 04/04/2025