Especialização em Sistemas com Python 3.12+ • Capítulo 01

🎯 Demonstração Prática: Processamento Financeiro Sequencial com Tipagem Estrita

O exemplo abaixo demonstra um fluxo sequencial corporativo em Python 3.12+, aplicando:

  • Verificação de runtime e arquitetura da máquina com sys e platform.
  • Tipagem estática com Final, TypedDict e tipos nativos parametrizados (PEP 585 / PEP 604).
  • Aritmética de precisão financeira exata com o módulo decimal (arredondamento bancário ROUND_HALF_EVEN).
  • Sanitização sequencial de entradas e formatação profissional de saída com f-strings.
"""
demonstracao_folha_sequencial.py
Exemplo corporativo do Capítulo 01: Ecossistema, Venv e Estrutura Sequencial.
Compatível com Python 3.12+ sob modo estrito (mypy --strict).
"""

from __future__ import annotations

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

# ==============================================================================
# 1. CONSTANTES IMUTÁVEIS DE DOMÍNIO (PEP 591)
# ==============================================================================
ALIQUOTA_INSS: Final[Decimal] = Decimal("0.11")       # 11% de previdência básica
ALIQUOTA_IRRF: Final[Decimal] = Decimal("0.075")      # 7.5% de retenção na fonte
AUXILIO_TRANSPORTE_FIXO: Final[Decimal] = Decimal("185.50")
VALE_REFEICAO_DIARIO: Final[Decimal] = Decimal("32.00")
DIAS_UTEIS_PADRAO: Final[int] = 22

# ==============================================================================
# 2. CONTRATOS E ESTRUTURAS DE DADOS TIPADAS (PEP 589)
# ==============================================================================
class HoleriteResultado(TypedDict):
    matricula: str
    nome_colaborador: str
    salario_base: Decimal
    dias_trabalhados: int
    provento_proporcional: Decimal
    beneficio_refeicao: Decimal
    desconto_inss: Decimal
    desconto_irrf: Decimal
    desconto_transporte: Decimal
    salario_liquido: Decimal
    total_encargos: Decimal
    status_conformidade: str

# ==============================================================================
# 3. LÓGICA DE PROCESSAMENTO SEQUENCIAL
# ==============================================================================
def processar_holerite(
    matricula: str,
    nome: str,
    salario_mensal: Decimal,
    dias_trabalhados: int,
    solicita_transporte: bool = True
) -> HoleriteResultado:
    """Calcula a folha de pagamento de forma puramente sequencial e determinística."""
    
    # Validações sequenciais defensivas
    if salario_mensal <= Decimal("0.00"):
        raise ValueError(f"Salário base inválido para matrícula {matricula}: {salario_mensal}")
    if not (1 <= dias_trabalhados <= 30):
        raise ValueError(f"Dias trabalhados fora da faixa [1, 30]: {dias_trabalhados}")

    # Proporcionalidade sobre base de 30 dias comerciais
    fator_proporcional: Decimal = (Decimal(str(dias_trabalhados)) / Decimal("30")).quantize(
        Decimal("0.0001"), rounding=ROUND_HALF_EVEN
    )
    salario_proporcional: Decimal = (salario_mensal * fator_proporcional).quantize(
        Decimal("0.01"), rounding=ROUND_HALF_EVEN
    )

    # Benefício alimentação calculado sobre dias úteis
    dias_beneficio: int = min(dias_trabalhados, DIAS_UTEIS_PADRAO)
    beneficio_refeicao: Decimal = (Decimal(str(dias_beneficio)) * VALE_REFEICAO_DIARIO).quantize(
        Decimal("0.01"), rounding=ROUND_HALF_EVEN
    )

    # Deduções tributárias sequenciais
    desconto_inss: Decimal = (salario_proporcional * ALIQUOTA_INSS).quantize(
        Decimal("0.01"), rounding=ROUND_HALF_EVEN
    )
    base_tributavel_irrf: Decimal = salario_proporcional - desconto_inss
    desconto_irrf: Decimal = (base_tributavel_irrf * ALIQUOTA_IRRF).quantize(
        Decimal("0.01"), rounding=ROUND_HALF_EVEN
    )

    desconto_transporte: Decimal = AUXILIO_TRANSPORTE_FIXO if solicita_transporte else Decimal("0.00")

    total_descontos: Decimal = desconto_inss + desconto_irrf + desconto_transporte
    salario_liquido: Decimal = salario_proporcional - total_descontos

    return {
        "matricula": matricula,
        "nome_colaborador": nome,
        "salario_base": salario_mensal,
        "dias_trabalhados": dias_trabalhados,
        "provento_proporcional": salario_proporcional,
        "beneficio_refeicao": beneficio_refeicao,
        "desconto_inss": desconto_inss,
        "desconto_irrf": desconto_irrf,
        "desconto_transporte": desconto_transporte,
        "salario_liquido": salario_liquido,
        "total_encargos": total_descontos,
        "status_conformidade": "APROVADO_AUDITORIA"
    }

# ==============================================================================
# 4. EXECUÇÃO E APRESENTAÇÃO FORMATADA
# ==============================================================================
if __name__ == "__main__":
    print(f"Ambiente: Python {sys.version.split()[0]} no {platform.system()} ({platform.machine()})")
    print("=" * 65)
    print("        SISTEMA DE AUDITORIA SEQUENCIAL DE FOLHA - PYTHON 3.12+")
    print("=" * 65)

    dados_colaborador = processar_holerite(
        matricula="ENG-2026-904",
        nome="Henrique Montenegro",
        salario_mensal=Decimal("7800.00"),
        dias_trabalhados=28,
        solicita_transporte=True
    )

    print(f"Matrícula Funcional : {dados_colaborador['matricula']}")
    print(f"Colaborador         : {dados_colaborador['nome_colaborador']}")
    print(f"Salário Base        : R$ {dados_colaborador['salario_base']:>10.2f}")
    print(f"Dias Apurados       : {dados_colaborador['dias_trabalhados']} dias")
    print(f"Provento Bruto      : R$ {dados_colaborador['provento_proporcional']:>10.2f}")
    print(f"Auxílio Refeição    : R$ {dados_colaborador['beneficio_refeicao']:>10.2f}")
    print("-" * 65)
    print(f"(-) Retenção INSS   : R$ {dados_colaborador['desconto_inss']:>10.2f} (11.0%)")
    print(f"(-) Retenção IRRF   : R$ {dados_colaborador['desconto_irrf']:>10.2f} (7.5%)")
    print(f"(-) Transporte      : R$ {dados_colaborador['desconto_transporte']:>10.2f}")
    print("-" * 65)
    print(f"Total Descontos     : R$ {dados_colaborador['total_encargos']:>10.2f}")
    print(f"LÍQUIDO A RECEBER   : R$ {dados_colaborador['salario_liquido']:>10.2f}")
    print(f"Status no Sistema   : [{dados_colaborador['status_conformidade']}]")
    print("=" * 65)