Importação de Módulos em Python: Guia Prático com Exemplos

O que são Módulos Python?

Um módulo é um único arquivo Python que pode conter variáveis, funções e classes. Quando você nomeia o arquivo guru99.py, o módulo é acessado como guru99. Módulos permitem dividir um grande programa em peças lógicas, mantendo seu código organizado e reutilizável.

Por que Importar Módulos?

Para usar código definido em outro arquivo, você deve importá-lo. Importar dá acesso às funções, classes e variáveis do módulo, assim como a palavra-chave import em linguagens como JavaScript, Java ou Ruby.

Criando e Importando um Módulo

Vamos percorrer um exemplo simples.

Estrutura de pastas:

modtest/
test.py
display.py

1. Crie test.py:

def display_message():
    return 'Welcome to Guru99 Tutorials!'

2. Crie display.py e importe test:

import test
print(test.display_message())

Executar display.py imprime:

Welcome to Guru99 Tutorials!

Importando uma Classe de um Módulo

Suponha que Car.py define uma classe carro:

class Car:
    brand_name = 'BMW'
    model = 'Z4'
    manu_year = '2020'
    def __init__(self, brand_name, model, manu_year):
        self.brand_name = brand_name
        self.model = model
        self.manu_year = manu_year
    def car_details(self):
        print('Car brand is', self.brand_name)
        print('Car model is', self.model)
        print('Car manufacture year is', self.manu_year)
    def get_car_brand(self):
        print('Car brand is', self.brand_name)
    def get_car_model(self):
        print('Car model is', self.model)

Use em display.py:

import Car
car_det = Car.Car('BMW', 'Z5', 2020)
print(car_det.brand_name)
car_det.car_details()
car_det.get_car_brand()
car_det.get_car_model()

Saída:

BMW
Car brand is BMW
Car model is Z5
Car manufacture year is 2020
Car brand is BMW
Car model is Z5

Usando `from` para Importar Itens Específicos

Quando você precisa apenas de algumas funções ou variáveis, importe-as diretamente:

from test import display_message
print(display_message())

Se você tentar usar um nome que não foi importado, Python levanta NameError:

from test import display_message
print(display_message1())

Importando Tudo de um Módulo

Importe o módulo inteiro com import test e prefixe nomes com o módulo, ou importe todos os nomes para o namespace atual com from test import *. O último é conveniente mas pode poluir o namespace.

Entendendo `dir()`

A função embutida dir() lista todos os atributos de um objeto, incluindo os definidos em um módulo:

import Car
print(dir(Car))

Para bibliotecas padrão:

import json
print(dir(json))

Trabalhando com Pacotes

Um pacote é um diretório contendo um arquivo __init__.py e um ou mais módulos. Por exemplo:

Layout do diretório:

mypackage/
__init__.py
module1.py
module2.py
module3.py

Em module1.py:

def mod1_func1():
    print('Welcome to Module1 function1')
def mod1_func2():
    print('Welcome to Module1 function2')
# …

Importe com alias:

import mypackage.module1 as mod1
mod1.mod1_func1()
mod1.mod1_func2()

Caminho de Busca de Módulos Python

Quando Python resolve um import, ele verifica:

O diretório de trabalho atual.
Módulos embutidos.
Diretórios listados em sys.path.

Inspecione com:

import sys
print(sys.path)

Usando Aliases para Módulos

Dê a um módulo um nome mais curto para melhorar legibilidade:

import test as t
print(t.display_message())
print(t.my_name)

Imports Absolutos vs. Relativos

Em um projeto multi-módulo, você pode referenciar módulos ou por seu caminho completo (absoluto) ou relativo ao arquivo atual.

Exemplo de Import Absoluto

from package1.module1 import myfunc1
# ou
import package1.module1
package1.module1.myfunc1()

Exemplo de Import Relativo

from .module1 import myfunc1
# ou
from .subpkg.module3 import myfunc3

Imports absolutos são mais claros e menos propensos a erros quando um projeto é movido, mas podem tornar-se verbosos. Imports relativos mantêm código conciso mas podem ser mais difíceis de rastrear em grandes projetos.