Módulos e Pacotes

À medida que seu código cresce, colocar tudo em um único arquivo se torna impraticável. Módulos permitem dividir o código em múltiplos arquivos; pacotes permitem organizar módulos relacionados juntos. Aprender programação modular é o limiar para a verdadeira "engenharia."

1. O que é um Módulo

Em Python, um arquivo .py é um módulo. Você pode usar import para trazer funcionalidades de outros módulos:

Exemplo: Importando Módulos da Biblioteca Padrão

# Importa um módulo inteiro
import math
print(math.pi)              # 3.141592653589793
print(math.sqrt(16))        # 4.0

# Importa uma função específica
from random import randint
print(randint(1, 10))       # Inteiro aleatório entre 1 e 10

# Importa múltiplos itens
from datetime import datetime, timedelta
now = datetime.now()
print(now)                  # Hora atual

Python vem com uma grande coleção de módulos da biblioteca padrão — math, random, datetime, os, json... Eles já estão lá quando você instala o Python, basta import e usar.

2. Módulos Personalizados

Criar um módulo é simples — basta escrever um arquivo .py.

my_tools.py

# Este é um módulo personalizado: my_tools.py

def greet(name):
    return f"Olá, {name}"

def add(a, b):
    return a + b

PI = 3.14159

main.py (usando o módulo)

Exemplo: Importando e Usando um Módulo Personalizado

# Importa módulo personalizado
import my_tools

print(my_tools.greet("João Silva"))   # Olá, João Silva
print(my_tools.add(5, 3))            # 8
print(my_tools.PI)                   # 3.14159

3. if __name__ == "__main__"

Este é um padrão Python muito importante — permite que um arquivo funcione tanto como um módulo importável quanto como um script diretamente executável:

Exemplo: Padrão de Duplo Propósito if name

# calculator.py
def add(a, b):
    return a + b

def subtract(a, b):
    return a - b

# O código abaixo só executa quando este arquivo é executado diretamente
if __name__ == "__main__":
    print("Testando funções da calculadora:")
    print(f"3 + 5 = {add(3, 5)}")
    print(f"10 - 4 = {subtract(10, 4)}")

Quando você:

• python calculator.py -> código de teste executa (__name__ == "__main__" é True)
• import calculator em outro arquivo -> código de teste NÃO executa (__name__ é "calculator")

4. Pacotes

Quando você tem muitos módulos, use pacotes para organizá-los — um pacote é um diretório contendo um arquivo __init__.py:

my_package/
├── __init__.py      ← Este arquivo é obrigatório (pode estar vazio)
├── math_tools.py
└── string_tools.py

# math_tools.py
def multiply(a, b):
    return a * b

def divide(a, b):
    if b == 0:
        return "Não é possível dividir por zero"
    return a / b

# string_tools.py
def reverse(text):
    return text[::-1]

def count_vowels(text):
    vowels = "aeiouAEIOU"
    return sum(1 for c in text if c in vowels)

Exemplo: Usando Módulos de um Pacote

# Usa o pacote
from my_package import math_tools, string_tools

print(math_tools.multiply(3, 5))           # 15
print(string_tools.reverse("Python"))      # nohtyP

5. Bibliotecas de Terceiros e pip

O poder do Python vem em grande parte de seu rico ecossistema de bibliotecas de terceiros. Instale-as com pip:

pip install requests          # Biblioteca de requisições HTTP
pip install numpy             # Computação numérica
pip install pandas            # Análise de dados
pip install flask             # Framework web

requirements.txt

Ao compartilhar seu projeto com outras pessoas, você precisa informar quais bibliotecas de terceiros são necessárias. requirements.txt é para este propósito:

requests==2.31.0
numpy==1.24.0
pandas==2.0.0
flask==3.0.0

O destinatário pode instalar todas as dependências com um comando:

pip install -r requirements.txt

Gerando requirements.txt

pip freeze > requirements.txt

Casos de Uso Comuns

• Reutilização de código: Extraia funções utilitárias em módulos separados, compartilhados entre múltiplos projetos.
• Organização de projeto: Use pacotes para organizar por funcionalidade (ex.: models/, utils/, views/).
• Gerenciamento de dependências: Use requirements.txt para gerenciar versões de bibliotecas de terceiros.
• Scripts de duplo propósito: Use if __name__ == "__main__" para que um arquivo possa ser tanto importado quanto executado diretamente.

❓ Perguntas Frequentes

P: Qual a diferença entre import math e from math import pi? R: import math importa o módulo inteiro; você deve escrever math.pi para usá-lo. from math import pi importa apenas pi; você pode usar pi diretamente. O primeiro é mais claro (você sabe de onde pi vem); o segundo é mais conciso. Não há padrão universal, mas consistência dentro de um arquivo é recomendada. P: O __init__.py precisa estar vazio? R: Não, não precisa estar vazio. __init__.py executa quando o pacote é importado. Você pode colocar código de inicialização lá — definir __all__ para controlar o comportamento de from package import *, ou até mesmo escrever funções utilitárias diretamente nele. Na maioria dos projetos simples, __init__.py está de fato vazio. P: Onde o pip install coloca as bibliotecas instaladas? R: Por padrão, elas vão para o diretório Lib/site-packages/ sob sua instalação Python. Se você tem projetos com diferentes requisitos de dependência, use ambientes virtuais (venv) — cada projeto tem seu próprio diretório de dependências, mantendo-os isolados. Crie um com python -m venv myenv, ative com source myenv/bin/activate.

📖 Resumo

• Um arquivo .py é um módulo; use import para usá-lo
• from module import name importa apenas itens específicos
• if __name__ == "__main__" permite que um arquivo seja tanto módulo quanto script
• Um pacote é um diretório com __init__.py para organizar múltiplos módulos
• pip install nome_pacote instala bibliotecas de terceiros
• requirements.txt registra dependências do projeto; pip install -r requirements.txt instala todas de uma vez

📝 Atividades

1. Iniciante (Dificuldade ⭐): Crie um módulo geometry.py com duas funções: circle_area(radius) e rectangle_area(width, height). Depois importe e use-as em outro arquivo.

2. Intermediário (Dificuldade ⭐⭐): Adicione um bloco if __name__ == "__main__" ao geometry.py para testar suas funções. Verifique: executar diretamente executa os testes; importar os pula.

3. Avançado (Dificuldade ⭐⭐⭐): Crie um pacote string_utils/ com dois módulos: validators.py (funções de validação: is_email(), is_phone()) e transformers.py (funções de transformação: to_snake_case(), to_camel_case()). Escreva um script de teste fora do pacote para importar e usar estes recursos.