O que é um módulo e como o import funciona

Módulo é um arquivo, import é o convite

Você já usou import nas aulas anteriores sem parar para pensar no que ele faz. Chegou a hora. Um módulo é apenas um arquivo Python cheio de código pronto: funções, valores e classes que alguém escreveu, testou e deixou disponível para você reaproveitar. Quando você escreve import math, o Python encontra o arquivo do módulo math, executa o que estiver lá dentro uma única vez e coloca o nome math ao seu alcance. A partir daí, tudo que estiver naquele arquivo fica acessível pelo prefixo math, um ponto, e o nome do que você quer.

import math

print(math.sqrt(81))   # 9.0
print(math.pi)         # 3.141592653589793
print(math.factorial(5))  # 120

import math traz o módulo inteiro; cada função vem com o prefixo math.

Repare no prefixo math. antes de cada nome. Ele não é burocracia: é o que a comunidade chama de namespace, o espaço de nomes de onde a função vem. Ao escrever math.sqrt, fica claro para qualquer leitor que sqrt pertence ao módulo math, e não a alguma função sua com o mesmo nome. Isso evita conflitos e deixa o código mais fácil de entender. Por isso, o import simples com prefixo é a forma mais recomendada para começar.

As três formas de importar

Existem três jeitos principais de trazer código de um módulo, e cada um tem sua hora. O primeiro é o import simples, que você já viu. O segundo é o import com apelido, usando a palavra as, útil quando o nome do módulo é longo ou quando a comunidade adotou um apelido padrão. O terceiro é o from import, que traz apenas nomes específicos de dentro do módulo, para usar sem o prefixo. Compare os três lado a lado no exemplo abaixo.

# Forma 1: import simples (usa prefixo)
import math
print(math.sqrt(16))       # 4.0

# Forma 2: import com apelido (as)
import statistics as stats
print(stats.mean([2, 4, 6]))  # 4.0

# Forma 3: from import (sem prefixo)
from math import sqrt, pi
print(sqrt(25))            # 5.0
print(pi)                  # 3.141592653589793

As três formas de importar, cada uma com seu resultado.

Onde o Python procura um módulo

Quando você escreve import math, como o Python sabe onde está esse arquivo? Ele segue uma ordem de busca. Primeiro procura entre os módulos embutidos, que já vêm compilados no próprio Python. Depois procura na mesma pasta do arquivo que você está rodando, o que é importante quando você cria os seus próprios módulos, tema da próxima aula. Por fim, procura nas pastas onde os pacotes ficam instalados. Essa lista de lugares vive em sys.path, e você pode até imprimi-la.

import sys

# sys.path e a lista de pastas onde o Python procura modulos
for caminho in sys.path[:3]:
    print(caminho)

# A primeira costuma ser a pasta do proprio programa (string vazia ou "."),
# o que permite importar arquivos .py que estao ao lado do seu.

sys.path guarda a lista ordenada de pastas onde o Python procura os módulos.

Você raramente vai mexer no sys.path na mão, e nem precisa. O que importa guardar é a ideia: o Python procura os módulos em uma ordem previsível, começando pelos embutidos e pela pasta do seu programa. É por isso que, se você criar um arquivo chamado calculos.py na mesma pasta e escrever import calculos, o Python encontra. E é também por isso que dar a um arquivo seu o mesmo nome de um módulo da biblioteca padrão, como math.py, é uma cilada: o seu arquivo pode acabar sendo importado no lugar do original.