Skip to main content

Imports no Python | Python

  • Imports no Python | Python

Visão Geral​

O sistema de imports do Python permite:

  • Reutilização de código
  • Organização modular
  • Isolamento de responsabilidades
  • Criação de pacotes hierárquicos

Todo import no Python envolve três conceitos fundamentais:

  • Módulo
  • Pacote
  • Namespace

O que é um módulo​

Um módulo é qualquer arquivo .py.

Exemplo:

math_utils.py
def soma(a, b):
    return a + b

Importando:

import math_utils

resultado = math_utils.soma(2, 3)

O que é um pacote​

Um pacote é uma pasta contendo módulos.

Estrutura:

project/
│
└── utils/
    ├── __init__.py
    ├── math_utils.py
    └── string_utils.py

Importando:

from utils.math_utils import soma

O arquivo __init__.py define explicitamente o diretório como pacote.

Documentação sobre __init__.py: 🔗 Clique aqui

Tipos de Import​

1. Import padrão​

import math

Uso:

math.sqrt(16)

2. Import específico​

from math import sqrt

Uso:

sqrt(16)

3. Import com alias​

import numpy as np
np.array([1, 2, 3])

4. Import múltiplo​

from math import sqrt, pow

5. Import tudo (não recomendado)​

from math import *

Problemas:

  • Polui namespace
  • Pode sobrescrever nomes
  • Dificulta leitura

Import absoluto​

Import absoluto começa do pacote raiz.

Estrutura:

project/
│
└── app/
    ├── __init__.py
    ├── models.py
    └── database.py

Import correto:

from app.database import Base

Vantagens:

  • Claro
  • Escalável
  • Compatível com produção
  • Evita ambiguidade

Import relativo​

Usa . para navegar na hierarquia.

Mesmo exemplo:

from .database import Base

Significado:

  • . → mesmo pacote
  • .. → pacote pai

Exemplo:

from ..core.config import settings

Limitações:

  • Só funciona dentro de pacotes
  • Não funciona em execução direta de script

Como o Python resolve imports​

O Python usa:

import sys
print(sys.path)

Ordem de busca:

  1. Diretório atual
  2. Diretórios em PYTHONPATH
  3. Site-packages
  4. Bibliotecas padrão

Namespace​

Import cria namespaces.

Exemplo:

import math

Namespace:

math.sqrt
math.pi

Sem import:

sqrt(4)  # erro

Com import específico:

from math import sqrt

Agora sqrt está no namespace global.

Execução como script vs módulo​

Script:

python main.py

Módulo:

python -m package.main

Diferença:

  • -m preserva estrutura de pacote
  • Script direto altera contexto de import

Erro comum: ModuleNotFoundError​

Causa frequente:

from database import Base

Mas estrutura é:

app/database.py

Solução:

from app.database import Base

Manipulando PYTHONPATH​

Linux/macOS:

export PYTHONPATH=/caminho/do/projeto

Windows PowerShell:

$env:PYTHONPATH="C:\projeto"

Evite usar isso em produção.

Prefira estrutura correta de pacote.

init.py​

Arquivo especial que:

  • Marca diretório como pacote
  • Pode executar código ao importar
  • Pode expor interface pública

Exemplo:

# utils/__init__.py

from .math_utils import soma

__all__ = ["soma"]

Agora:

from utils import soma

all​

Define o que será exportado com import *.

__all__ = ["soma"]

Sem isso, todos símbolos públicos são exportados.

Import dinâmico​

import importlib

modulo = importlib.import_module("math")
print(modulo.sqrt(16))

Uso comum:

  • Plugins
  • Sistemas extensíveis
  • Carregamento condicional

Import condicional​

try:
    import ujson as json
except ImportError:
    import json

Imports circulares​

Problema:

# a.py
import b

# b.py
import a

Isso causa erro de inicialização parcial.

Soluções:

  • Reorganizar código
  • Import local dentro de função

Exemplo:

def func():
    from module import dependency

Boas práticas​

  • Sempre use import absoluto em projetos grandes
  • Evite import *
  • Organize código em pacotes
  • Evite lógica em __init__.py
  • Não manipule sys.path manualmente
  • Use virtual environments

Estrutura recomendada para projetos​

project/
│
├── package_name/
│   ├── __init__.py
│   ├── core/
│   ├── models/
│   └── services/
│
└── main.py

Imports:

from package_name.models.user import User

Conceito interno (CPython)​

Quando você faz:

import module

O Python:

  1. Procura no sys.path
  2. Localiza arquivo
  3. Compila para bytecode (.pyc)
  4. Executa o módulo
  5. Armazena em sys.modules
  6. Reutiliza se importar novamente

Cache de módulos​

Ver módulos carregados:

import sys
print(sys.modules.keys())

Módulos são carregados uma única vez por processo.

Resumo estrutural​

Formato completo de import:

package.subpackage.module.object

Exemplo real:

from collections.abc import Iterable

Hierarquia:

collections → abc → Iterable

Se quiser aprofundar, posso gerar documentação adicional sobre:

  • Como funciona o import loader interno
  • Meta path finders
  • Import hooks
  • Estrutura enterprise para projetos grandes
  • Organização de monorepos Python