Como funcionam módulos, importações e pacotes?

Question

Accepted Answer

Um **módulo** é um único arquivo `.py`; um **pacote** é um diretório de módulos. **Importações** permitem usar código de outros módulos, organizando um programa em peças reutilizáveis.

## Módulos e importação

```python
# math_utils.py — a module
def add(a, b): return a + b
PI = 3.14159
```

```python
# main.py — different ways to import
import math_utils                  # import the whole module
math_utils.add(2, 3)               # access via the module name

from math_utils import add, PI     # import specific names
add(2, 3)                          # use directly

from math_utils import add as plus # import with an alias
import numpy as np                 # common aliasing convention
```

## Pacotes — diretórios de módulos

```text
mypackage/
  __init__.py        ← marks it as a package (can be empty)
  module_a.py
  subpackage/
    __init__.py
    module_b.py
```

```python
from mypackage.module_a import something
from mypackage.subpackage.module_b import other
```

O arquivo `__init__.py` marca um diretório como um pacote (e pode executar código de inicialização de pacote ou definir o que `from package import *` expõe).

## O idioma `if __name__ == "__main__"`

```python
def main():
    print("running as a script")

if __name__ == "__main__":   # True only when run directly, not when imported
    main()
```

Isso permite que um arquivo funcione tanto como um módulo importável *quanto* como um script executável — o código sob ele é executado apenas quando o arquivo é executado diretamente (`python file.py`), não quando importado. Um idioma Python quase universal.

## Onde Python procura módulos

```python
import sys
sys.path   # the list of directories Python searches for imports
# includes: the current directory, installed packages (site-packages), stdlib
```

## Biblioteca padrão e terceiros

```python
import os, json, datetime    # standard library — "batteries included"
import requests              # third-party — installed via pip from PyPI
```

## Por que isso importa

Módulos e pacotes são como você organiza código Python em unidades reutilizáveis e fáceis de manter, em vez de um arquivo gigante — fundamental para qualquer projeto não trivial.

Compreender os estilos de importação, a estrutura de pacotes (`__init__.py`), o idioma `if __name__ == "__main__"` (comportamento duplo script/módulo) e como Python encontra módulos (`sys.path`) é essencial para estruturar projetos, reutilizar código e usar a vasta biblioteca padrão e o ecossistema PyPI.

Erros de importação e confusão de estrutura são obstáculos iniciais comuns que esse conhecimento resolve.

Módulos e importação

Pacotes — diretórios de módulos

O idioma if __name__ == "__main__"

Onde Python procura módulos

Biblioteca padrão e terceiros

Por que isso importa

O idioma `if name == "main"`