Módulos Python

Um módulo é um arquivo contendo código Python — funções, classes e variáveis — que pode ser reutilizado em múltiplos programas. Os módulos são a unidade básica de organização de código em Python: em vez de copiar lógica entre arquivos, você a escreve uma vez, salva como um arquivo .py e a importa onde for necessário. Este capítulo abrange desde a criação do seu primeiro módulo até a navegação pela biblioteca padrão e a compreensão de como Python localiza módulos em tempo de execução.

O que é um Módulo Python?

Qualquer arquivo .py é um módulo. Quando você escreve:

# greetings.py
def hello(name):
    return f"Hello, {name}!"

def goodbye(name):
    return f"Goodbye, {name}!"

PI = 3.14159

você criou um módulo chamado greetings. O nome do módulo é o nome do arquivo sem a extensão .py.

Os módulos podem conter:

• Funções — blocos de lógica reutilizáveis (veja Python Functions)
• Classes — modelos para objetos (veja Python Classes)
• Variáveis e constantes — dados compartilhados
• Declarações executáveis — código que é executado quando o módulo é importado ou executado diretamente

Importando um Módulo

Use a instrução import seguida do nome do módulo (sem a extensão .py).

import greetings

print(greetings.hello("Alice"))    # Hello, Alice!
print(greetings.goodbye("Alice"))  # Goodbye, Alice!
print(greetings.PI)                # 3.14159

Após import greetings, todos os nomes definidos em greetings.py ficam acessíveis através do prefixo greetings.. Esta notação de ponto evita colisões de nomes — sua própria variável PI não pode entrar em conflito com greetings.PI.

Importando Nomes Específicos com from ... import

Se você precisa de apenas um ou dois nomes, importe-os diretamente para poder usá-los sem o prefixo do módulo.

from greetings import hello, PI

print(hello("Bob"))   # Hello, Bob!
print(PI)             # 3.14159

Importando Tudo com *

from greetings import *

Isso traz todos os nomes públicos (aqueles que não começam com _) para o namespace atual. Evite isso em programas maiores: polui o namespace e dificulta identificar de onde vem um nome.

Aliases de Importação com as

Nomes de módulos longos se tornam tediosos de digitar. Use as para criar um alias mais curto.

import greetings as gr

print(gr.hello("Carol"))   # Hello, Carol!

Você também pode criar aliases para nomes importados individualmente:

from greetings import hello as hi

print(hi("Dave"))   # Hello, Dave!

Aliases são especialmente comuns com bibliotecas populares:

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt

A Função dir()

dir(module) retorna uma lista ordenada de todos os nomes definidos em um módulo — uma maneira rápida de explorar o que está disponível.

import math
print(dir(math))
# ['__doc__', '__loader__', ..., 'acos', 'acosh', 'asin', ..., 'sqrt', 'tan', 'tanh', 'tau']

Chame dir() sem argumentos para ver os nomes no escopo atual.

A Variável __name__

Todo módulo tem uma variável embutida chamada __name__. Quando um arquivo é importado, __name__ é definido como o nome do módulo. Quando o arquivo é executado diretamente, __name__ é definido como a string "__main__".

Este padrão é a forma padrão de escrever código que só é executado quando o arquivo é executado como script — e não quando é importado como biblioteca:

# greetings.py

def hello(name):
    return f"Hello, {name}!"

if __name__ == "__main__":
    # This block only runs when you execute: python greetings.py
    print(hello("World"))

import greetings   # The if-block does NOT run here

Este padrão é usado em quase todos os arquivos Python não triviais que você encontrará.

Caminho de Busca de Módulos (sys.path)

Quando você escreve import greetings, Python busca o módulo em uma lista de diretórios armazenados em sys.path:

1. O diretório do script sendo executado (ou o diretório atual no modo interativo)
2. Diretórios listados na variável de ambiente PYTHONPATH
3. Os diretórios da biblioteca padrão
4. O diretório site-packages (onde ficam os pacotes de terceiros instalados pelo pip)

import sys
print(sys.path)
# ['/path/to/script', '/usr/lib/python3.11', ..., '/usr/lib/python3/dist-packages']

Você pode adicionar um caminho em tempo de execução, mas isso raramente é necessário para projetos bem estruturados:

import sys
sys.path.append("/path/to/my/libs")

A Biblioteca Padrão do Python

Python vem com uma grande biblioteca padrão — centenas de módulos cobrindo desde E/S de arquivos até protocolos de rede e compressão de dados. Não é necessário instalar nada; basta importá-los.

math — Funções Matemáticas

import math

print(math.sqrt(16))       # 4.0
print(math.pi)             # 3.141592653589793
print(math.factorial(5))   # 120
print(math.ceil(4.2))      # 5
print(math.floor(4.8))     # 4

Veja Python Math para uma referência completa.

random — Números Aleatórios

import random

print(random.randint(1, 10))          # random integer between 1 and 10
print(random.choice(["a", "b", "c"])) # random element
print(random.random())                 # float in [0.0, 1.0)

numbers = [1, 2, 3, 4, 5]
random.shuffle(numbers)
print(numbers)   # shuffled in place

datetime — Datas e Horas

import datetime

now = datetime.datetime.now()
print(now)                       # 2024-03-15 10:30:45.123456
print(now.year)                  # 2024
print(now.strftime("%B %d, %Y")) # March 15, 2024

today = datetime.date.today()
print(today)   # 2024-03-15

Veja Python Dates para cobertura completa de aritmética e formatação de datas.

os e sys — Sistema Operacional e Interpretador

import os

print(os.getcwd())              # current working directory
print(os.listdir("."))          # files in the current directory
os.makedirs("new_dir", exist_ok=True)  # create a directory
print(os.path.join("folder", "file.txt"))  # 'folder/file.txt'

import sys

print(sys.version)    # Python version string
print(sys.platform)   # 'linux', 'darwin', 'win32', etc.
sys.exit(0)           # terminate the program with exit code 0

json — Codificação e Decodificação JSON

import json

data = {"name": "Alice", "age": 30, "active": True}

# Python → JSON string
json_string = json.dumps(data, indent=2)
print(json_string)

# JSON string → Python
parsed = json.loads(json_string)
print(parsed["name"])   # Alice

Veja Python JSON para leitura e escrita baseadas em arquivo.

collections — Estruturas de Dados Especializadas

from collections import Counter, defaultdict

# Count occurrences
words = ["apple", "banana", "apple", "cherry", "banana", "apple"]
counts = Counter(words)
print(counts)              # Counter({'apple': 3, 'banana': 2, 'cherry': 1})
print(counts.most_common(2))  # [('apple', 3), ('banana', 2)]

# Dict with default values
scores = defaultdict(int)
scores["Alice"] += 10
scores["Bob"] += 5
print(dict(scores))   # {'Alice': 10, 'Bob': 5}

Veja Python Collections Module para namedtuple, deque e OrderedDict.

Criando Seu Próprio Módulo

Estrutura Básica

Os módulos funcionam melhor quando fazem uma coisa bem feita. Uma boa regra prática: se um grupo de funções compartilha um tema, coloque-as em seu próprio arquivo.

# mathutils.py

def clamp(value, minimum, maximum):
    """Restrict value to the range [minimum, maximum]."""
    return max(minimum, min(value, maximum))

def average(numbers):
    """Return the arithmetic mean of a list of numbers."""
    if not numbers:
        raise ValueError("Cannot average an empty list")
    return sum(numbers) / len(numbers)

def is_prime(n):
    """Return True if n is a prime number."""
    if n < 2:
        return False
    for i in range(2, int(n ** 0.5) + 1):
        if n % i == 0:
            return False
    return True

# main.py
from mathutils import clamp, average, is_prime

print(clamp(15, 0, 10))          # 10
print(average([2, 4, 6, 8]))     # 5.0
print(is_prime(17))              # True

Docstrings em Módulos

Adicione uma docstring no nível do módulo no topo do arquivo. Ferramentas como help() e geradores de documentação a utilizam.

"""
mathutils.py — Utility functions for common mathematical operations.

Functions:
    clamp(value, minimum, maximum) -> number
    average(numbers) -> float
    is_prime(n) -> bool
"""

Variáveis de Módulo: __all__

__all__ é uma lista de nomes que devem ser exportados quando alguém faz from module import *. Também serve como documentação sobre a API pública do módulo.

# mathutils.py
__all__ = ["clamp", "average", "is_prime"]

def _helper():   # leading underscore marks it as private
    pass

Recarregando um Módulo

Python armazena em cache os módulos importados em sys.modules. Importar o mesmo módulo duas vezes não o executa novamente — Python retorna a versão em cache. Durante o desenvolvimento interativo ou depuração, você pode forçar um recarregamento:

import importlib
import greetings

importlib.reload(greetings)

Isso é necessário principalmente em sessões REPL ou notebooks Jupyter após editar um arquivo de módulo.

Armadilhas Comuns

Importações Circulares

Se module_a importa module_b e module_b importa module_a, você tem uma importação circular. Python consegue lidar com algumas importações circulares, mas elas são confusas e geralmente indicam um problema de design. A solução normalmente é reestruturar o código — mover a lógica compartilhada para um terceiro módulo, ou adiar a importação para dentro de uma função.

Sombreando um Módulo da Biblioteca Padrão

Se você nomear seu arquivo math.py, random.py ou json.py, você irá sombrear o módulo da biblioteca padrão e quebrar qualquer código que o importe. Use nomes específicos e descritivos para seus próprios módulos.

# BAD: naming your file math.py shadows the stdlib
# GOOD: name it mathutils.py or geometry.py

ImportError e ModuleNotFoundError

ModuleNotFoundError (uma subclasse de ImportError) significa que Python não conseguiu encontrar o módulo em nenhum lugar do sys.path. Causas comuns:

• Um erro de digitação no nome do módulo
• O módulo não está instalado (pip install <package-name>)
• O arquivo do módulo está em um diretório que não está no sys.path

try:
    import nonexistent_module
except ModuleNotFoundError as e:
    print(f"Import failed: {e}")
    # Import failed: No module named 'nonexistent_module'

Módulos vs. Pacotes

Um módulo é um único arquivo .py. Um pacote é um diretório contendo múltiplos módulos e um arquivo __init__.py. Pacotes permitem construir bibliotecas maiores com uma estrutura hierárquica. Veja Python Packages para a história completa.

Módulos Populares de Terceiros

Além da biblioteca padrão, o ecossistema Python no PyPI possui centenas de milhares de pacotes. Instale-os com pip.

Prática