Especialização em Sistemas com Python & POO com Type Hints • Capítulo 01

🗺️ Mapa Conceitual do Tópico

flowchart TD
    A["Código Fonte (.py)"] -->|Compilador CPython| B["Bytecode Otimizado (.pyc)"]
    B -->|Avaliação na PVM| C["Python Virtual Machine (PVM)"]
    C -->|Instruções Nativas| D["Sistema Operacional Windows / CPU"]
    
    subgraph AMBIENTE["Isolamento de Ambiente (.venv)"]
        E["python -m venv .venv"] --> F[".venv/Scripts/Activate.ps1"]
        F --> G["pip install -r requirements.txt"]
    end
    
    subgraph TIPAGEM["Tipagem Estática & Gradual (PEP 484/585/604)"]
        H["x: int = 10"] --> I["TAXA: Final[Decimal] = Decimal('0.15')"]
        I --> J["def calcular(val: Decimal) -> Decimal:"]
        J --> K["mypy --strict . / ruff check ."]
    end

    C --> AMBIENTE
    C --> TIPAGEM
    
    style A fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px
    style B fill:#fff3e0,stroke:#ff9800,stroke-width:2px
    style C fill:#ede7f6,stroke:#7e57c2,stroke-width:2px
    style D fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
    style AMBIENTE fill:#f1f8e9,stroke:#8bc34a,stroke-width:2px
    style TIPAGEM fill:#e0f7fa,stroke:#00bcd4,stroke-width:2px

🏛️ 1. O Interpretador CPython e o Ciclo de Execução

Python é uma linguagem de alto nível com gerenciamento de memória automático via contagem de referências (Reference Counting) e coletor de lixo cíclico (Cyclic Garbage Collector).

O Ciclo de Execução:

  1. Análise Léxica e Sintática: O interpretador analisa o código-fonte (.py) e gera uma Árvore de Sintaxe Abstrata (Abstract Syntax Tree - AST).
  2. Compilação para Bytecode: A AST é compilada em instruções compactas e portáveis de bytecode (armazenadas em diretórios __pycache__/*.pyc).
  3. Execução na PVM: A Python Virtual Machine (PVM) executa o loop de avaliação de opcodes, traduzindo cada instrução em chamadas do sistema operacional.

⚙️ 2. Ambientes Virtuais (venv) no Windows

O isolamento de dependências através do módulo nativo venv é indispensável para evitar conflitos de bibliotecas globais no sistema operacional.

Configuração no PowerShell e Prompt de Comando (CMD):

# No PowerShell (Executar na raiz do projeto):
python -m venv .venv

# Ativação da sessão no PowerShell:
.\.venv\Scripts\Activate.ps1

# Atualização do gerenciador de pacotes e instalação de ferramentas essenciais:
python -m pip install --upgrade pip
pip install pytest mypy ruff

:: No CMD (Prompt de Comando):
python -m venv .venv
.venv\Scripts\activate

🧠 3. Sistema de Tipos: Dinâmico, Forte e Gradual

O Python possui uma classificação única em seu sistema de tipos:

  1. Tipagem Dinâmica: Os tipos estão associados aos objetos em memória (Heap), e não às variáveis. Uma variável em Python é apenas um ponteiro/etiqueta (name binding) apontando para uma estrutura PyObject.
  2. Tipagem Forte: O interpretador não realiza coerções implícitas perigosas. Por exemplo, '10' + 5 lança TypeError imediatamente, ao contrário de linguagens com tipagem fraca.
  3. Tipagem Gradual (Gradual Typing com Type Hints): A partir do Python 3.5+ e consolidada no Python 3.12+, o desenvolvedor pode adicionar anotações estáticas de tipo que são verificadas em tempo de desenvolvimento por ferramentas como mypy e IDEs, sem penalidade de performance no runtime.
flowchart TD
    subgraph STACK_NAMES["Namespaces / Variáveis (Etiquetas)"]
        V1["idade = 28"]
        V2["saldo = Decimal('4500.00')"]
        V3["ativo = True"]
        V4["usuario = @0x3A8F (Referência)"]
    end

    subgraph HEAP_OBJECTS["Heap Memory (PyObject Structures)"]
        O1["PyObject (type: int, refcnt: 1, val: 28)"]
        O2["PyObject (type: Decimal, refcnt: 1, val: '4500.00')"]
        O3["PyObject (type: bool, refcnt: 1, val: True)"]
        O4["PyObject (type: dict/class, refcnt: 1, ...)"]
    end

    V1 --> O1
    V2 --> O2
    V3 --> O3
    V4 --> O4

    style STACK_NAMES fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px
    style HEAP_OBJECTS fill:#fff3e0,stroke:#ff9800,stroke-width:2px

📊 4. Tabela Comparativa: Dinâmica vs Gradual vs Estática

Critério Tipagem Dinâmica Pura (Legada) Tipagem Gradual (Python 3.12+ com Type Hints) Tipagem Estática Tradicional (Java / C# / Rust)
Verificação de Tipos Apenas em tempo de execução (Runtime) Estática via analisadores (mypy, ruff) + Dinâmica em runtime Obrigatória em tempo de compilação (Compile-time)
Declaração de Variável x = 10 x: int = 10 int x = 10;
Segurança e Refatoração Baixa em bases de código grandes Alta: IDEs e linters detectam incompatibilidades antes da execução Máxima: O compilador rejeita binários com erros de tipo
Sobrecarga de CPU no Runtime Zero verificação antecipada Zero sobrecarga: Anotações são ignoradas na execução da PVM Zero (Casts e tipos resolvidos na compilação)
Flexibilidade Máxima Balanceada (Permite Any quando estritamente necessário) Rígida

🔢 5. Tabela Completa dos Tipos Nativos (Built-in Types) do Python

Tipo Categoria Mutabilidade Type Hint Moderno (PEP 585/604) Literal / Sintaxe de Criação Exemplo de Declaração Uso Recomendado
int Numérico Inteiro 🔒 Imutável int 10, -500, 1_000_000 quantidade: int = 150 Contadores, IDs, matemática com precisão arbitrária (sem overflow).
float Ponto Flutuante 🔒 Imutável float 3.1415, -0.001, 1e-5 temperatura: float = 36.5 Sensores, gráficos, machine learning e simulações científicas.
bool Lógico / Booleano 🔒 Imutável bool True ou False (subclasse de int) em_producao: bool = True Flags condicionais, controle de fluxo e predicados de filtro.
complex Número Complexo 🔒 Imutável complex 3 + 4j, complex(3, 4) impedancia: complex = 2 + 5j Engenharia elétrica, física quântica e processamento de sinais.
str Texto / String 🔒 Imutável str 'texto', "texto", '''bloco''' nome: str = "Camila Duarte" Nomes, identificadores, documentos e comunicação I/O.
bytes Sequência Binária 🔒 Imutável bytes b'dados', bytes([65, 66]) payload: bytes = b'\x00\xFF' Criptografia, sockets de rede, imagens e arquivos binários.
bytearray Buffer Binário 🔓 Mutável bytearray bytearray(b'dados') buffer: bytearray = bytearray(1024) Buffers de stream mutáveis de alto desempenho.
list Lista Dinâmica 🔓 Mutável list[T] [1, 2, 3], list() pedidos: list[str] = ["A1", "A2"] Coleções sequenciais ordenadas e dinâmicas de dados.
tuple Tupla Heterogênea 🔒 Imutável tuple[T, ...] (1, "A"), 1, 2 coordenada: tuple[int, int] = (10, 20) Registros imutáveis, retorno múltiplo de funções e chaves de dict.
range Intervalo Aritmético 🔒 Imutável range range(0, 10, 2) indices: range = range(1, 101) Laços de iteração controlados sem alocar memória em bloco.
set Conjunto Hash 🔓 Mutável set[T] {1, 2, 3}, set() tags: set[str] = {"dev", "prod"} Elementos únicos em $O(1)$, operações de união e interseção.
frozenset Conjunto Imutável 🔒 Imutável frozenset[T] frozenset([1, 2]) permissoes: frozenset[str] = frozenset() Conjuntos imutáveis que podem ser usados como chaves de dict.
dict Dicionário / Mapa 🔓 Mutável dict[K, V] {"chave": "valor"}, dict() config: dict[str, Any] = {"v": 1} Mapeamento chave-valor em $O(1)$, JSON e tabelas de consulta.
NoneType Tipo Nulo / Sentinela 🔒 Imutável None ou T | None None resultado: str | None = None Ausência de valor, inicialização opcional e retornos vazios.

🔀 6. Tabela de Conversão de Tipos e Casting Explícito

Por ter tipagem forte, o Python exige funções construtoras de conversão explícita (type casting):

Função Construtora Conversão de Origem Resultado / Comportamento Exemplo de Código Possível Exceção
int(x) str ou float Trunca decimais de floats ou converte strings numéricas. int('42') $\rightarrow$ 42
int(9.99) $\rightarrow$ 9		 ValueError se string não-numérica.
float(x) str ou int Converte para ponto flutuante IEEE 754 de 64 bits. float('18.5') $\rightarrow$ 18.5 ValueError se formato inválido.
str(x) Qualquer objeto Invoca o método especial __str__() do objeto. str(1500) $\rightarrow$ '1500' Nenhuma (todo objeto possui string).
bool(x) Qualquer objeto Avalia o valor de verdade (Truthy / Falsy). bool(0) $\rightarrow$ False
bool('texto') $\rightarrow$ True		 Nenhuma.
list(iteravel) tuple, set, str Converte qualquer iterável em lista mutável. list('ABC') $\rightarrow$ ['A', 'B', 'C'] TypeError se não for iterável.
tuple(iteravel) list, set Converte iterável em tupla imutável. tuple([1, 2]) $\rightarrow$ (1, 2) TypeError se não for iterável.
dict(pares) Lista de tuplas (k, v) Monta dicionário chave $\rightarrow$ valor. dict([('a', 1), ('b', 2)]) ValueError se itens não forem pares.

💼 7. Tabela de Tipos Corporativos e Precisão Financeira

Tipo Módulo Mutabilidade Motivo de Uso Exemplo de Código
Decimal decimal 🔒 Imutável Cálculos financeiros e fiscais exatos. Elimina resíduos do padrão IEEE 754. from decimal import Decimal
valor: Decimal = Decimal('1500.50')
Fraction fractions 🔒 Imutável Frações racionais exatas (ex.: 1/3, 2/7) sem conversão em dízimas. from fractions import Fraction
fator: Fraction = Fraction(1, 3)
datetime datetime 🔒 Imutável Manipulação temporal completa com timezone (aware). from datetime import datetime, timezone
agora: datetime = datetime.now(timezone.utc)
UUID uuid 🔒 Imutável Identificador Único Universal de 128 bits para microsserviços. import uuid
id_unico: uuid.UUID = uuid.uuid4()
Path pathlib 🔒 Imutável Manipulação orientada a objetos de caminhos no Windows/Linux. from pathlib import Path
relatorio: Path = Path("reports/audit.json")

📐 8. Recursos Modernos de Tipagem (typing & PEPs)

A partir do Python 3.10+, 3.11 e 3.12+, o ecossistema de tipagem atingiu maturidade corporativa:

Construtor / Anotação PEP Finalidade Exemplo Moderno
Coleções Nativas PEP 585 Dispensou a importação de List, Dict, Tuple, Set. historico: list[dict[str, float]] = []
Operador de União (|) PEP 604 Substituiu Union[A, B] e Optional[T] por A | B e T | None. def buscar(id_doc: str) -> str | None:
Constantes (Final) PEP 591 Declara que o valor não pode ser reatribuído. TAXA_MAXIMA: Final[Decimal] = Decimal('0.275')
Tipos Literais (Literal) PEP 586 Restringe o valor aceito a um conjunto exato de constantes. Modo: Final = Literal["RO", "RW", "BIN"]
Dicionários Tipados (TypedDict) PEP 589 Tipagem estrita de chaves e tipos de valores em dicionários. class Config(TypedDict):
    host: str
    porta: int
Interfaces Estruturais (Protocol) PEP 544 Duck typing estático verificado em tempo de desenvolvimento. class Fechavel(Protocol):
    def fechar(self) -> None: ...
Metadados (Annotated) PEP 593 Anexa metadados de validação (utilizado por Pydantic/FastAPI). Score = Annotated[int, "Valor entre 0 e 1000"]

📥 9. Entrada e Saída Formatada no Windows

  • Entrada de Dados Tipada com input(): 
    salario_informado: Decimal = Decimal(input('Informe o salário base: ').strip())
dias_trabalhados: int = int(input('Dias trabalhados: ').strip())
  • Saída Formatada com F-Strings (Python 3.6+ / 3.12+): 
    print(f'Total Faturado: R$ {total_faturado:>10.2f}')

💻 10. Exemplo Prático e Tipado com Auditoria Sequencial

"""
exemplo_01_ecossistema_e_tipagem.py - Estrutura Sequencial e Tipagem Estrita
Especialização em Sistemas com Python 3.12+
"""

import platform
import sys
from decimal import Decimal, ROUND_HALF_EVEN
from typing import Any, Final

# Constantes Corporativas (PEP 8 + PEP 591)
ALIQUOTA_INSS: Final[Decimal] = Decimal("0.11") # 11%
ALIQUOTA_IRRF: Final[Decimal] = Decimal("0.075") # 7.5%
VALOR_TRANSPORTE: Final[Decimal] = Decimal("180.00")

def calcular_folha_colaborador(
    colaborador: str,
    salario_base: Decimal,
    dias_trabalhados: int,
    bonus_metas: Decimal = Decimal("0.00")
) -> dict[str, Any]:
    """Calcula a folha sequencial com precisão monetária exata."""
    if salario_base <= Decimal("0.00"):
        raise ValueError("Salário base deve ser estritamente positivo.")
    if not (1 <= dias_trabalhados <= 30):
        raise ValueError("Dias trabalhados devem estar entre 1 e 30.")

    fator_dias: Decimal = (Decimal(str(dias_trabalhados)) / Decimal("30")).quantize(Decimal("0.0001"), ROUND_HALF_EVEN)
    provento_base: Decimal = (salario_base * fator_dias + bonus_metas).quantize(Decimal("0.01"), ROUND_HALF_EVEN)
    desconto_inss: Decimal = (provento_base * ALIQUOTA_INSS).quantize(Decimal("0.01"), ROUND_HALF_EVEN)
    base_irrf: Decimal = provento_base - desconto_inss
    desconto_irrf: Decimal = (base_irrf * ALIQUOTA_IRRF).quantize(Decimal("0.01"), ROUND_HALF_EVEN)
    salario_liquido: Decimal = provento_base - desconto_inss - desconto_irrf - VALOR_TRANSPORTE

    return {
        "colaborador": colaborador,
        "provento_bruto": provento_base,
        "desconto_inss": desconto_inss,
        "desconto_irrf": desconto_irrf,
        "transporte": VALOR_TRANSPORTE,
        "salario_liquido": salario_liquido,
        "status": "CONFORME"
    }

if __name__ == "__main__":
    resultado: dict[str, Any] = calcular_folha_colaborador(
        colaborador="Camila Duarte",
        salario_base=Decimal("5400.00"),
        dias_trabalhados=30,
        bonus_metas=Decimal("600.00")
    )

    print("=" * 55)
    print("   DEMONSTRATIVO DE PAGAMENTO (PYTHON 3.12+ TIPADO)     ")
    print("=" * 55)
    print(f"Colaborador        : {resultado['colaborador']}")
    print(f"Salário Bruto      : R${resultado['provento_bruto']:>10.2f}") print(f"(-) Desconto INSS : R$ {resultado['desconto_inss']:>10.2f} (11%)")
    print(f"(-) Desconto IRRF  : R${resultado['desconto_irrf']:>10.2f} (7.5%)") print(f"(-) Transporte : R$ {resultado['transporte']:>10.2f}")
    print("-" * 55)
    print(f"LÍQUIDO A RECEBER  : R$ {resultado['salario_liquido']:>10.2f}")
    print("=" * 55)