Python import

Nas últimas aulas, todo programa começou com uma linha diferente: import csv, import json, from pathlib import Path. Agora é hora de entender o que essa linha faz. O Python vem com centenas de ferramentas prontas (para matemática, sorteios, datas, arquivos, internet), mas elas não ficam todas carregadas o tempo todo: cada grupo mora no seu módulo, e você chama só os que vai usar, com import ("importar").

A ideia: caixas de ferramentas na prateleira

Na oficina do bairro, as ferramentas ficam em caixas na prateleira: uma caixa de chaves de fenda, uma de medição, uma de pintura. Ninguém carrega todas para cada serviço. Para pintar uma parede, o pintor pega a caixa de pintura e usa o que tem dentro dela.

Um módulo é uma dessas caixas: um arquivo com funções e valores prontos sobre um assunto. O math tem as ferramentas de matemática; o random, as de sorteio; o json, as de JSON. A prateleira inteira, que vem junto com o Python, se chama biblioteca padrão (standard library). E o import é o gesto de pegar a caixa.

A lista completa está na referência dos módulos. Além da biblioteca padrão, existem milhares de módulos feitos pela comunidade, que você instala com o pip. E você também pode criar os seus, como mostra a próxima aula, Criando seu Módulo.

1. import modulo: traz a caixa inteira

import math

print(math.sqrt(16))
print(math.pi)
print(math.ceil(2.1))

$ python3 raiz.py
4.0
3.141592653589793
3

import math

"Traga o módulo math." A partir daqui, o nome math existe no programa e representa a caixa inteira.

math.sqrt(16)

O ponto quer dizer "de dentro de": a função sqrt (de square root, "raiz quadrada") de dentro do math.

math.pi

Nem tudo é função: pi é um valor guardado no módulo (por isso, sem parênteses).

math.ceil(2.1)

Arredonda para cima (ceiling, "teto"): 3.

Escrever math. na frente de tudo parece trabalho a mais, mas tem uma vantagem: quem lê o código sabe de onde cada coisa veio. O sqrt é o do math, sem dúvida nenhuma.

Um módulo é um objeto como outro qualquer

O nome math é uma variável que guarda um valor do tipo module, e o dir() lista o que tem dentro dele:

import math

nomes = [nome for nome in dir(math) if not nome.startswith("_")]
print(len(nomes), "nomes no math")
print(nomes[:12])

$ python3 dir.py
62 nomes no math
['acos', 'acosh', 'asin', 'asinh', 'atan', 'atan2', 'atanh', 'cbrt', 'ceil', 'comb', 'copysign', 'cos']

São 62 nomes públicos (o programa tirou os que começam com _, que são de uso interno). O list comprehension e a fatia [:12] são só para a lista caber na tela. No modo interativo, help(math.sqrt) mostra a explicação de cada um.

2. from modulo import nome: só a ferramenta

Quando você vai usar muito uma ou duas ferramentas, dá para trazê-las para fora da caixa e chamá-las pelo nome direto:

from math import sqrt, pi

print(sqrt(16))
print(pi)

$ python3 raiz2.py
4.0
3.141592653589793

from math

"Do módulo math…"

import sqrt, pi

"…traga o sqrt e o pi." Vários nomes, separados por vírgula.

sqrt(16)

Sem o math. na frente. Em compensação, o nome math sozinho não existe neste programa: só os dois nomes que você pediu.

Você já usou essa forma: from pathlib import Path. Ninguém escreve pathlib.Path("loja") o tempo todo; o Path é usado demais para isso.

print(sqrt(81))

from math import sqrt

print(sqrt(81))

3. import modulo as apelido

Alguns módulos têm nome comprido. O as ("como") dá um apelido mais curto:

import statistics as est

notas = [8.5, 6.0, 9.5, 7.0]
print("Média:", est.mean(notas))
print("Mediana:", est.median(notas))

$ python3 apelido.py
Média: 7.75
Mediana: 7.75

import statistics as est

"Traga o statistics (estatística), e chame-o de est." No resto do programa, o nome é est; o nome statistics não fica disponível.

est.mean(notas)

A média (mean) da lista.

est.median(notas)

A mediana: o valor do meio, com a lista em ordem (com 4 notas, a média das duas do meio, 7.0 e 8.5).

O as também funciona no from: from statistics import mean as media. Alguns apelidos são tão usados que viraram regra na comunidade, e você vai encontrá-los em todo lugar: import numpy as np, import pandas as pd (dois módulos famosos, instalados com o pip). Fora esses casos conhecidos, não invente apelidos para módulos de nome curto: import math as m só deixa o código mais difícil de ler.

4. from modulo import *: por que evitar

Existe uma quarta forma: o * ("tudo") despeja todos os nomes do módulo no seu programa. Parece prático, mas é como virar todas as caixas da prateleira no chão da oficina: você não sabe mais o que veio de onde, e uma ferramenta pode cair em cima de outra com o mesmo nome. Olhe o que acontece com o módulo os:

from os import *

with open("recado.txt", "w") as arquivo:
    arquivo.write("Comprar pão\n")

$ python3 estrela.py
Traceback (most recent call last):
  File "/home/ana/estrela.py", line 3, in <module>
    with open("recado.txt", "w") as arquivo:
         ~~~~^^^^^^^^^^^^^^^^^^^
TypeError: 'str' object cannot be interpreted as an integer

Um open que sempre funcionou, de repente, reclama que um texto "não pode ser interpretado como inteiro". O motivo: o módulo os tem a sua própria função chamada open, de baixo nível, que espera números no segundo argumento. O import * trouxe esse open e ele tapou o open de sempre, sem aviso. Nada na linha 3 dá a pista, porque o problema está na linha 1.

Formas diferentes de importar: qual usar

import statistics

notas = [8.5, 6.0, 9.5, 7.0]
print("Média:", statistics.mean(notas))
print("Maior:", max(notas))

import statistics as est

notas = [8.5, 6.0, 9.5, 7.0]
print("Média:", est.mean(notas))
print("Maior:", max(notas))

5. Onde o Python procura os módulos

Quando você escreve import json, o Python sai procurando um módulo com esse nome numa lista de pastas, em ordem, e usa o primeiro que achar. A lista fica no sys.path:

import math
import json
import sys

print(math)
print(json)
for pasta in sys.path:
    print(pasta)

$ python3 onde_mora.py
<module 'math' (built-in)>
<module 'json' from '/usr/lib/python3.14/json/__init__.py'>
/home/ana
/usr/lib/python314.zip
/usr/lib/python3.14
/usr/lib/python3.14/lib-dynload
/usr/local/lib/python3.14/dist-packages
/usr/lib/python3/dist-packages

• O math é built-in ("embutido"): está dentro do próprio programa python3, não num arquivo.
• O json é um arquivo de verdade, na pasta da biblioteca padrão: /usr/lib/python3.14/json/.
• A primeira pasta da lista é /home/ana, a pasta do programa que está rodando. Depois vêm a biblioteca padrão (/usr/lib/python3.14) e as pastas dos pacotes instalados (dist-packages).

Essa ordem tem duas consequências. A boa: um arquivo .py seu, na mesma pasta, pode ser importado como módulo (é o assunto da próxima aula). A má: um arquivo seu com o mesmo nome de um módulo da biblioteca padrão passa na frente dele. Veja em Quando dá errado o que acontece com um random.py.

Outro detalhe: cada módulo é carregado uma vez só por execução. Se o programa fizer import json duas vezes, a segunda só reaproveita o que já foi carregado (a seção 6 mostra isso acontecendo).

6. O __name__ e o if __name__ == "__main__":

Todo módulo tem um nome, guardado na variável especial __name__ (com dois sublinhados de cada lado). E o seu próprio programa também tem um:

import math

print(__name__)
print(math.__name__)
print(type(math))

$ python3 nome.py
__main__
math
<class 'module'>

O math se chama math, como esperado. Mas o programa que você rodou com python3 nome.py não se chama nome: se chama __main__ ("principal"). É a forma do Python dizer: este é o arquivo que a pessoa mandou rodar.

Isso importa porque um arquivo .py pode ser usado de dois jeitos: rodado diretamente ou importado por outro. Dois arquivos pequenos mostram a diferença:

print("quem.py: o meu __name__ é", __name__)

import quem

print("chama_quem.py: o meu __name__ é", __name__)

$ python3 quem.py
quem.py: o meu __name__ é __main__
$ python3 chama_quem.py
quem.py: o meu __name__ é quem
chama_quem.py: o meu __name__ é __main__

Rodado sozinho, o quem.py é o __main__. Importado pelo chama_quem.py, ele passa a se chamar quem, e o principal agora é o outro. Repare também que o import quem rodou o arquivo quem.py inteiro: importar um módulo executa o código dele, de cima a baixo. Mas só na primeira vez, como a seção 5 avisou:

import quem
import quem

print("Fim")

$ python3 duas_vezes.py
quem.py: o meu __name__ é quem
Fim

O problema que o if resolve

A Ana escreveu uma função de desconto no arquivo precos.py, com uma linha no fim para testar:

def com_desconto(preco, porcento):
    return preco * (100 - porcento) / 100

print("Testando:", com_desconto(100, 10))

E um programa do caixa que usa a função:

import precos

print("Café com 5% de desconto:", precos.com_desconto(18.90, 5))

$ python3 precos.py
Testando: 90.0
$ python3 caixa.py
Testando: 90.0
Café com 5% de desconto: 17.955

O teste apareceu também no caixa, onde não tinha nada que estar: o import precos rodou o arquivo inteiro, inclusive o print do teste. A solução é colocar o teste dentro de um if que pergunta "eu sou o programa principal?":

def com_desconto(preco, porcento):
    return preco * (100 - porcento) / 100

if __name__ == "__main__":
    print("Testando:", com_desconto(100, 10))

import precos2

print("Café com 5% de desconto:", precos2.com_desconto(18.90, 5))

$ python3 precos2.py
Testando: 90.0
$ python3 caixa2.py
Café com 5% de desconto: 17.955

if __name__ == "__main__":

"Se este arquivo é o que foi mandado rodar…" Rodado com python3 precos2.py, o __name__ vale "__main__" e o bloco roda. Importado pelo caixa, o __name__ vale "precos2", a condição é falsa e o bloco é pulado.

print("Testando:", …)

O que só deve acontecer quando o arquivo é o principal: testes, um menu, a "parte que faz o programa andar".

Você vai ver esse if no fim de muitos programas Python, mesmo nos que ninguém pretende importar: é o jeito de dizer "daqui para baixo é o programa; daqui para cima são as definições". A próxima aula, Criando seu Módulo, usa isso de verdade.

Quando dá errado

import maths

$ python3 errado1.py
Traceback (most recent call last):
  File "/home/ana/errado1.py", line 1, in <module>
    import maths
ModuleNotFoundError: No module named 'maths'

import requests

$ python3 errado2.py
Traceback (most recent call last):
  File "/home/ana/errado2.py", line 1, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'

print(math.sqrt(16))

$ python3 sem_import.py
Traceback (most recent call last):
  File "/home/ana/sem_import.py", line 1, in <module>
    print(math.sqrt(16))
          ^^^^
NameError: name 'math' is not defined. Did you forget to import 'math'?

import math

print(sqrt(16))

$ python3 sem_from.py
Traceback (most recent call last):
  File "/home/ana/sem_from.py", line 3, in <module>
    print(sqrt(16))
          ^^^^
NameError: name 'sqrt' is not defined

import math

print(math.raiz(16))

$ python3 atributo.py
Traceback (most recent call last):
  File "/home/ana/atributo.py", line 3, in <module>
    print(math.raiz(16))
          ^^^^^^^^^
AttributeError: module 'math' has no attribute 'raiz'

import random

print(random())

$ python3 chamar.py
Traceback (most recent call last):
  File "/home/ana/chamar.py", line 3, in <module>
    print(random())
          ~~~~~~^^
TypeError: 'module' object is not callable. Did you mean: 'random.random(...)'?

import random

print("Sorteando...")
print(random.randint(1, 6))

$ python3 random.py
Sorteando...
Traceback (most recent call last):
  File "/home/ana/random.py", line 1, in <module>
    import random
  File "/home/ana/random.py", line 4, in <module>
    print(random.randint(1, 6))
          ^^^^^^^^^^^^^^
AttributeError: module 'random' has no attribute 'randint' (consider renaming '/home/ana/random.py' since it has the same name as the standard library module named 'random' and prevents importing that standard library module)

$ python3 dados.py
Sorteando...
Traceback (most recent call last):
  File "/home/ana/dados.py", line 1, in <module>
    import random
  File "/home/ana/random.py", line 4, in <module>
    print(random.randint(1, 6))
          ^^^^^^^^^^^^^^
AttributeError: module 'random' has no attribute 'randint' (consider renaming '/home/ana/random.py' since it has the same name as the standard library module named 'random' and prevents importing that standard library module)
$ rm random.py
$ python3 dados.py
4                                       « um número de 1 a 6; o seu pode ser outro

Referência rápida

Exercícios

Missão final: o teste que vaza

import precos

print("Café com desconto:", precos.com_desconto(18.90, 5))

def com_desconto(preco, porcento):
    return preco * (100 - porcento) / 100

print("Testando:", com_desconto(100, 10))

def com_desconto(preco, porcento):
    return preco * (100 - porcento) / 100

if __name__ == "__main__":
    print("Testando:", com_desconto(100, 10))

(O 17.955 com três casas é a conta exata; para mostrar em reais, formate com f"{valor:.2f}", como em f-strings.)

Resumo

• Um módulo é uma caixa de ferramentas sobre um assunto. A biblioteca padrão é o conjunto que vem com o Python.
• import math traz a caixa (use math.sqrt); from math import sqrt traz só a ferramenta (use sqrt); import statistics as est dá um apelido.
• Evite import *: ele esconde de onde vem cada nome e pode tapar outros.
• Os import ficam no começo do arquivo, um por linha.
• O Python procura os módulos primeiro na pasta do programa, depois na biblioteca padrão: nunca dê a um arquivo seu o nome de um módulo (random.py, json.py).
• Importar um módulo roda o arquivo dele. O __name__ vale "__main__" só no arquivo que foi mandado rodar, e o if __name__ == "__main__": guarda o que só deve acontecer nesse caso.
• ModuleNotFoundError: nome errado ou módulo que precisa de pip.