Módulos Python: Definir e Importar - Guia Completo

Introdução

Neste laboratório, você aprenderá sobre módulos Python, que são arquivos contendo código Python que podem ser importados e usados em outros programas. Essa abordagem modular promove a reutilização de código e ajuda a organizar programas em componentes lógicos.

Você entenderá o que são módulos Python e por que eles são úteis, aprenderá a criar seus próprios módulos, praticará o uso da instrução import de diferentes maneiras e compreenderá o conceito de um módulo principal e quando o código é executado. Os pré-requisitos incluem uma compreensão básica da sintaxe e funções Python, e familiaridade com a criação e execução de scripts Python. É recomendado reiniciar sua sessão do interpretador Python antes de iniciar este exercício para um ambiente limpo.

Este é um Lab Guiado, que fornece instruções passo a passo para ajudá-lo a aprender e praticar. Siga as instruções cuidadosamente para completar cada etapa e ganhar experiência prática. Dados históricos mostram que este é um laboratório de nível iniciante com uma taxa de conclusão de 97%. Recebeu uma taxa de avaliações positivas de 100% dos estudantes.

Compreendendo os Módulos Python

Em Python, um módulo é como um contêiner que armazena definições e declarações Python. É essencialmente um arquivo, e o nome desse arquivo é o nome do módulo com a extensão .py adicionada no final. Pense nos módulos como caixas de ferramentas. Eles ajudam você a organizar seu código Python de forma lógica, tornando-o mais fácil de reutilizar e manter. Assim como você guardaria diferentes ferramentas em caixas separadas para melhor organização, você pode agrupar código Python relacionado em diferentes módulos.

Vamos dar uma olhada nos arquivos que foram configurados para este laboratório:

Primeiro, abriremos o arquivo stock.py no editor para ver o que há dentro. Para fazer isso, usaremos os seguintes comandos. O comando cd altera o diretório para a pasta project onde nosso arquivo está localizado, e o comando cat exibe o conteúdo do arquivo.

cd ~/project
cat stock.py

Este arquivo stock.py define uma classe Stock. Uma classe é como um modelo para criar objetos. Neste caso, a classe Stock representa uma ação. Ela tem atributos (que são como características) para o nome da ação, o número de ações e o preço. Também tem um método (que é como uma função associada à classe) para calcular o custo da ação.

Em seguida, vamos examinar o arquivo pcost.py. Usaremos o comando cat novamente para visualizar seu conteúdo.

cat pcost.py

Este arquivo define uma função chamada portfolio_cost(). Uma função é um bloco de código que executa uma tarefa específica. A função portfolio_cost() lê um arquivo de portfólio e calcula o custo total de todas as ações nesse portfólio.

Agora, vamos olhar para os dados de exemplo do portfólio. Usaremos o comando cat para visualizar o conteúdo do arquivo portfolio.dat.

cat portfolio.dat

Este arquivo contém dados de ações em um formato simples. Cada linha tem o símbolo da ação, o número de ações e o preço por ação.

Usando a Declaração `import`

A declaração import do Python é uma ferramenta poderosa que permite que você use código de outros módulos em seu programa atual. É como pegar emprestado ferramentas de outras caixas de ferramentas. Vamos praticar o uso de diferentes maneiras de importar código:

Primeiro, precisamos iniciar o interpretador Python. O interpretador Python é um programa que executa código Python. Usaremos o seguinte comando para iniciá-lo.

python3

Agora, vamos importar o módulo pcost e ver o que acontece. Quando usamos a declaração import, o Python procura o arquivo pcost.py e disponibiliza o código dentro dele para que possamos usar.

import pcost

Você deve ver a saída 44671.15. Este é o custo calculado do portfólio do arquivo portfolio.dat. Quando o módulo pcost é importado, o código na parte inferior do arquivo pcost.py é executado automaticamente.

Vamos tentar chamar a função portfolio_cost() com um arquivo de portfólio diferente. Usaremos a sintaxe pcost.portfolio_cost() para chamar a função do módulo pcost.

pcost.portfolio_cost('portfolio2.dat')

A saída deve ser 19908.75, que representa o custo total das ações no segundo arquivo de portfólio.

Agora, vamos importar uma classe específica do módulo stock. Em vez de importar o módulo inteiro, podemos importar apenas a classe Stock usando a declaração from...import.

from stock import Stock

Depois de importar a classe Stock, podemos criar um objeto Stock. Um objeto é uma instância de uma classe. Criaremos um objeto Stock com o nome GOOG, 100 ações e um preço de 490.10. Em seguida, imprimiremos o nome da ação e calcularemos seu custo usando o método cost().

s = Stock('GOOG', 100, 490.10)
print(s.name)
print(s.cost())

A saída deve ser:

GOOG
49010.0

Finalmente, quando terminarmos de usar o interpretador Python, podemos sair dele usando a função exit().

exit()

Este laboratório demonstrou duas maneiras diferentes de importar código Python:

import module_name - Isso importa o módulo inteiro, tornando todas as funções, classes e variáveis nesse módulo disponíveis para uso.
from module_name import specific_item - Isso importa apenas um item específico (como uma classe ou uma função) do módulo, o que pode ser útil se você precisar apenas de uma parte da funcionalidade do módulo.

Compreendendo o Módulo Principal em Python

Em Python, quando você executa um script diretamente, ele age como o módulo "principal". Python tem uma variável especial chamada __name__. Quando um arquivo é executado diretamente, o Python define o valor de __name__ como "__main__". Isso é diferente de quando o arquivo é importado como um módulo.

Este recurso é muito útil porque permite que você escreva código que se comporta de maneira diferente, dependendo se o arquivo é executado diretamente ou importado. Por exemplo, você pode querer que algum código seja executado apenas quando você executa o arquivo como um script, mas não quando ele é importado por outro script.

Modificando pcost.py para Usar o Padrão de Módulo Principal

Vamos modificar o programa pcost.py para tirar proveito desse padrão.

Primeiro, você precisa abrir o arquivo pcost.py no editor. Você pode usar os seguintes comandos para navegar até o diretório do projeto e criar o arquivo, caso ele não exista:

cd ~/project
touch pcost.py

O comando cd altera o diretório atual para o diretório project em seu diretório home. O comando touch cria um novo arquivo chamado pcost.py se ele ainda não existir.

Agora, modifique o arquivo pcost.py para que ele se pareça com isto:

## pcost.py

def portfolio_cost(filename):
    total_cost = 0.0

    with open(filename, 'r') as f:
        for line in f:
            fields = line.split()
            try:
                nshares = int(fields[1])
                price = float(fields[2])
                total_cost += nshares * price
            except (ValueError, IndexError):
                print(f"Couldn't parse: {line}")

    return total_cost

## This code only runs when the file is executed as a script
if __name__ == "__main__":
    total = portfolio_cost('portfolio.dat')
    print(total)

A principal mudança aqui é que envolvemos o código no final em uma condição if __name__ == "__main__":. Isso significa que o código dentro deste bloco só será executado quando o arquivo for executado diretamente como um script, não quando for importado como um módulo.

Depois de fazer essas alterações, salve o arquivo e saia do editor.

Testando o Módulo Modificado

Agora, vamos testar nosso módulo modificado de duas maneiras diferentes para ver como ele se comporta.

Primeiro, execute o programa diretamente como um script usando o seguinte comando:

python3 pcost.py

Você deve ver a saída 44671.15, assim como antes. Isso ocorre porque, quando você executa o script diretamente, a variável __name__ é definida como "__main__", então o código dentro do bloco if __name__ == "__main__": é executado.

Em seguida, inicie o interpretador Python novamente e importe o módulo:

python3

import pcost

Desta vez, você não verá nenhuma saída. Quando você importa o módulo, a variável __name__ é definida como "pcost" (o nome do módulo), não "__main__". Portanto, o código dentro do bloco if __name__ == "__main__": não é executado.

Para verificar se a função portfolio_cost ainda funciona, você pode chamá-la assim:

pcost.portfolio_cost('portfolio.dat')

A função deve retornar 44671.15, o que significa que ela está funcionando corretamente.

Finalmente, saia do interpretador Python usando o seguinte comando:

exit()

Este padrão é muito útil ao criar arquivos Python que podem ser usados tanto como módulos importáveis quanto como scripts independentes. O código dentro do bloco if __name__ == "__main__": só é executado quando o arquivo é executado diretamente, não quando é importado como um módulo.

Criando Seu Próprio Módulo

Agora que você entende como usar módulos existentes, é hora de criar um novo módulo do zero. Um módulo em Python é um arquivo que contém definições e declarações Python. Ele permite que você organize seu código em pedaços reutilizáveis e gerenciáveis. Ao criar seu próprio módulo, você pode agrupar funções e variáveis relacionadas, tornando seu código mais modular e fácil de manter.

Criando um Módulo de Relatório

Vamos criar um módulo simples para gerar relatórios de ações. Este módulo terá funções para ler um arquivo de portfólio e imprimir um relatório formatado das ações no portfólio.

Primeiro, precisamos criar um novo arquivo chamado report.py. Para fazer isso, usaremos a linha de comando. Navegue até o diretório project em seu diretório home e crie o arquivo usando o comando touch.

cd ~/project
touch report.py

Agora, abra o arquivo report.py em seu editor de texto preferido e adicione o seguinte código. Este código define duas funções e um bloco principal.

## report.py

def read_portfolio(filename):
    """
    Read a stock portfolio file into a list of dictionaries with
    keys: name, shares, price
    """
    portfolio = []
    with open(filename, 'r') as f:
        for line in f:
            fields = line.split()
            try:
                stock = {
                    'name': fields[0],
                    'shares': int(fields[1]),
                    'price': float(fields[2])
                }
                portfolio.append(stock)
            except (ValueError, IndexError):
                print(f"Couldn't parse: {line}")
    return portfolio

def print_report(portfolio):
    """
    Print a report showing the stock name, shares, price, and total value
    """
    print("Name    Shares    Price    Value")
    print("-" * 40)
    total_value = 0.0
    for stock in portfolio:
        value = stock['shares'] * stock['price']
        total_value += value
        print(f"{stock['name']:6s} {stock['shares']:9d} {stock['price']:9.2f} {value:9.2f}")
    print("-" * 40)
    print(f"Total Value: {total_value:16.2f}")

if __name__ == "__main__":
    portfolio = read_portfolio('portfolio.dat')
    print_report(portfolio)

A função read_portfolio lê um arquivo contendo informações sobre ações e retorna uma lista de dicionários, onde cada dicionário representa uma ação com as chaves name, shares e price. A função print_report recebe um portfólio (uma lista de dicionários de ações) e imprime um relatório formatado mostrando o nome da ação, o número de ações, o preço e o valor total. O bloco principal no final é executado quando o arquivo é executado diretamente. Ele lê o arquivo do portfólio e imprime o relatório.

Depois de adicionar o código, salve e saia do editor.

Testando Seu Módulo

Vamos testar nosso novo módulo para garantir que ele funcione conforme o esperado.

Primeiro, executaremos o script diretamente da linha de comando. Isso executará o bloco principal no arquivo report.py.

python3 report.py

Você deve ver um relatório formatado mostrando as ações do portfólio e seus valores. Este relatório inclui o nome da ação, o número de ações, o preço e o valor total, bem como o valor total de todo o portfólio.

Name    Shares    Price    Value
----------------------------------------
AA         100     32.20   3220.00
IBM         50     91.10   4555.00
CAT        150     83.44  12516.00
MSFT       200     51.23  10246.00
GE          95     40.37   3835.15
MSFT        50     65.10   3255.00
IBM        100     70.44   7044.00
----------------------------------------
Total Value:         44671.15

Em seguida, usaremos o módulo do interpretador Python. Inicie o interpretador Python executando o comando python3 no terminal.

python3

Depois que o interpretador estiver em execução, podemos importar o módulo report e usar suas funções.

import report
portfolio = report.read_portfolio('portfolio.dat')
len(portfolio)  ## Should return 7, the number of stocks
portfolio[0]    ## First stock in the portfolio

A declaração import report torna as funções e variáveis definidas no arquivo report.py disponíveis na sessão Python atual. Em seguida, usamos a função read_portfolio para ler o arquivo do portfólio e armazenar o resultado na variável portfolio. A declaração len(portfolio) retorna o número de ações no portfólio, e portfolio[0] retorna a primeira ação no portfólio.

Você deve ver a seguinte saída:

7
{'name': 'AA', 'shares': 100, 'price': 32.2}

Agora, vamos usar o módulo importado para calcular o custo total do portfólio nós mesmos. Iteraremos sobre as ações no portfólio e somaremos o valor total de cada ação.

total = 0.0
for stock in portfolio:
    total += stock['shares'] * stock['price']
print(total)

A saída deve ser 44671.15, que é o mesmo que o valor total impresso pela função print_report.

Finalmente, vamos criar um relatório personalizado para um tipo de ação específico. Filtraremos o portfólio para incluir apenas as ações da IBM e, em seguida, usaremos a função print_report para imprimir um relatório para essas ações.

ibm_stocks = [stock for stock in portfolio if stock['name'] == 'IBM']
report.print_report(ibm_stocks)

Isso deve imprimir um relatório mostrando apenas as ações da IBM e seus valores.

Name    Shares    Price    Value
----------------------------------------
IBM         50     91.10   4555.00
IBM        100     70.44   7044.00
----------------------------------------
Total Value:         11599.00

Quando terminar de testar, saia do interpretador Python executando o comando exit().

exit()

Você agora criou e usou com sucesso seu próprio módulo Python, combinando funções e um bloco principal que só é executado quando o arquivo é executado diretamente. Essa abordagem modular de programação permite que você reutilize código e torne seus projetos mais organizados e fáceis de manter.

Resumo

Neste laboratório, você aprendeu os conceitos fundamentais de módulos Python e como usá-los para organização de código. Módulos são arquivos Python com código reutilizável, e a declaração import permite que você utilize código de outros módulos em seu programa. O padrão if __name__ == "__main__" permite que os arquivos funcionem como módulos importáveis e scripts independentes.

Esses conceitos são cruciais para escrever código Python que seja fácil de manter, especialmente ao desenvolver aplicações maiores. Ao continuar aprendendo Python, lembre-se de que os módulos ajudam a agrupar código relacionado, importar itens específicos mantém o namespace limpo e o padrão de módulo principal é uma boa prática. Aplicar essas técnicas tornará seu código mais organizado, fácil de manter e reutilizável.

Definindo e Importando Módulos Python