Por que o projeto final é uma biblioteca e não um aplicativo?

Porque uma biblioteca força você a pensar na interface pública e a separá-la da implementação, que é a mentalidade de engenharia do curso. Ela também é mais fácil de testar de forma isolada, sem tela nem interação, o que deixa o foco na qualidade do código e do design.

Preciso rodar o projeto todo no meu computador?

A maior parte do código roda no Playground, porque usa a linguagem e a biblioteca padrão. Só o empacotamento e a execução do pytest na estrutura completa rendem mais no computador, e a aula final mostra o passo a passo. Você pode acompanhar a lógica inteira sem instalar nada.

O que é a fachada do pacote no __init__.py?

É o conjunto de nomes que o pacote expõe diretamente. Ao importar no __init__.py as classes e funções principais, você permite que quem usa a biblioteca escreva from catalogo import Produto sem saber em qual módulo interno cada coisa mora. É a interface pública, separada da organização interna.

Posso adaptar o projeto para outro domínio?

Sim, e é um ótimo exercício. A arquitetura de modelos, erros, infraestrutura e lógica serve para muitos domínios. Trocar produtos por, digamos, tarefas ou usuários, mantendo a mesma estrutura, ajuda a fixar o método. O domínio é só o pretexto; o que importa é a forma.

Quanto código esse projeto vai ter?

Pouco, de propósito. São alguns módulos curtos, cada um com uma responsabilidade. O objetivo não é volume, e sim exercitar o ciclo completo de engenharia num tamanho que você consegue entender por inteiro. Bibliotecas reais são maiores, mas seguem exatamente esse mesmo método.

Módulo 16 - Projeto final: mini biblioteca de utilidades

Visão do projeto e arquitetura

9 min de leitura · por Cesar Gargiulo, revisado pela equipe ValorFinal e GuardiaSec · Atualizado em 01/07/2026

Velocidade

O que você vai aprender

Entender o que a mini biblioteca catalogo faz e por quê.
Desenhar a estrutura de pacote do projeto.
Dividir responsabilidades entre os módulos.
Planejar como cada tema do curso entra no projeto.

O que vamos construir

O projeto final não é um aplicativo com tela, e sim uma biblioteca: um conjunto de código bem feito, para ser importado e reutilizado. Vamos construir o pacote catalogo, uma mini biblioteca de utilidades para gerenciar um catálogo de produtos. Ela vai representar produtos com tipos e categorias, validar dados na entrada, calcular preços com desconto e imposto, guardar resultados caros em cache, medir o tempo de operações, tratar erros com exceções próprias e registrar o que acontece com logging. Nada gigantesco, mas completo o bastante para exercitar cada tema do curso num código coeso.

Escolher uma biblioteca como projeto final tem um motivo pedagógico. Uma biblioteca obriga você a pensar na interface pública, ou seja, no que oferece para quem a usa, e a separar isso da implementação interna. É exatamente a mentalidade de engenharia que o curso vem construindo: definir contratos claros, garanti-los com tipos e testes, e esconder a complexidade atrás de uma fachada simples. Quem usa o catalogo não precisa saber como o cálculo de preço funciona por dentro; só precisa chamar uma função com um bom nome e confiar no resultado.

A estrutura do pacote

Aplicando o que vimos no módulo de empacotamento, o projeto nasce com o layout src: o código do pacote em src/catalogo, os testes em tests, e a configuração na raiz. Dentro do pacote, dividimos por responsabilidade. Um módulo para os modelos de dados, um para os erros, um para os utilitários de decoração e contexto, e um para a lógica de preços. O __init__.py expõe a fachada, escolhendo o que fica acessível direto pelo nome do pacote. Essa divisão não é enfeite: é ela que vai deixar cada aula acrescentar uma peça sem embolar as outras.

catalogo/
    pyproject.toml
    README.md
    src/
        catalogo/
            __init__.py      # fachada: expoe o que a biblioteca oferece
            modelos.py       # dataclasses e Enum do dominio
            erros.py         # excecoes proprias
            infra.py         # decoradores (cache, validacao) e context manager
            precos.py        # logica de preco: desconto, imposto
    tests/
        test_modelos.py
        test_precos.py

A estrutura do pacote catalogo: cada módulo com uma responsabilidade, testes à parte.

Módulo	Responsabilidade	Aula que constrói
modelos.py	Produto (dataclass) e Categoria (Enum)	Aula 2
infra.py	Decoradores próprios e context manager	Aula 3
erros.py	Exceções próprias e logging	Aula 4
precos.py	Cálculo de desconto e imposto	Aulas 2 a 4
tests/	Testes com pytest e empacotamento	Aula 5

O que cada módulo faz e em qual aula ele é construído.

Cada peça no seu lugar

A regra que guia a divisão é a responsabilidade única, do módulo de SOLID. Os modelos só descrevem os dados: um produto, uma categoria. Os erros só definem os tipos de falha. A infra reúne as ferramentas transversais, como cache e medição de tempo, que servem a vários módulos. E a lógica de preço fica isolada, sem se misturar com a definição dos dados nem com a infraestrutura. Quando cada módulo tem um assunto que cabe numa frase, o projeto fica navegável e as mudanças ficam locais: mexer no cálculo de imposto não arrisca quebrar a definição de produto.

Um lembrete honesto sobre escopo: este projeto é didático, dimensionado para caber no curso e exercitar os conceitos com clareza. Uma biblioteca de produção teria mais tratamento de casos, mais testes e mais documentação. O valor aqui não é o tamanho, e sim a completude do ciclo: você vai projetar a arquitetura, modelar dados com tipos, escrever ferramentas próprias, tratar erros de propósito e provar tudo com testes. É o método completo, num tamanho que você consegue segurar na cabeça inteira.

Teste rápido

Por que dividir o pacote catalogo em módulos separados por responsabilidade?

Perguntas frequentes

Por que o projeto final é uma biblioteca e não um aplicativo?: Porque uma biblioteca força você a pensar na interface pública e a separá-la da implementação, que é a mentalidade de engenharia do curso. Ela também é mais fácil de testar de forma isolada, sem tela nem interação, o que deixa o foco na qualidade do código e do design.
Preciso rodar o projeto todo no meu computador?: A maior parte do código roda no Playground, porque usa a linguagem e a biblioteca padrão. Só o empacotamento e a execução do pytest na estrutura completa rendem mais no computador, e a aula final mostra o passo a passo. Você pode acompanhar a lógica inteira sem instalar nada.
O que é a fachada do pacote no __init__.py?: É o conjunto de nomes que o pacote expõe diretamente. Ao importar no __init__.py as classes e funções principais, você permite que quem usa a biblioteca escreva from catalogo import Produto sem saber em qual módulo interno cada coisa mora. É a interface pública, separada da organização interna.
Posso adaptar o projeto para outro domínio?: Sim, e é um ótimo exercício. A arquitetura de modelos, erros, infraestrutura e lógica serve para muitos domínios. Trocar produtos por, digamos, tarefas ou usuários, mantendo a mesma estrutura, ajuda a fixar o método. O domínio é só o pretexto; o que importa é a forma.
Quanto código esse projeto vai ter?: Pouco, de propósito. São alguns módulos curtos, cada um com uma responsabilidade. O objetivo não é volume, e sim exercitar o ciclo completo de engenharia num tamanho que você consegue entender por inteiro. Bibliotecas reais são maiores, mas seguem exatamente esse mesmo método.

Fontes

Seu progresso fica salvo neste aparelho. Assinantes sincronizam entre os aparelhos.

← Padrões pythônicos e código limpo Concluir e avançar →