O Modelo Mental de Depuração para Serviços Python

Cinco páginas desta seção parecem, à primeira vista, cinco tópicos não relacionados: Bugs de Argumentos Padrão Mutáveis, Cenários de Importação Circular, Deadlocks asyncio e Bloqueio do Loop, Cenários de Vazamento de Memória e Bugs de Codificação e Unicode.

Eles são, em essência, a mesma forma de problema: em cada um deles, o código assumiu que uma fronteira era aplicada - quando algo realmente executa, qual estado é realmente compartilhado, o que realmente permanece vivo, se "texto" realmente significa o que você pensa que significa - e essa fronteira acabou sendo mais permeável do que o código assumiu.

Esta página é o modelo mental por trás das páginas de cenário específicas, mais Ferramentas de Depuração para as ferramentas envolvidas: não uma substituição para as correções detalhadas em cada página, mas o raciocínio que diz qual fronteira quebrou antes de você começar a aplicar uma correção à errada.

Resumo

• A maioria dos bugs difíceis de explicar em Python vêm de uma fronteira que o código assumiu silenciosamente que se mantinha - tempo de definição versus tempo de chamada, ordem de importação, propriedade do loop, tempo de vida do objeto, ou "texto" versus bytes - que acabou não se mantendo neste caso específico.
• Por que Importa: Tratar o sintoma (um heisenbug, uma travada, um aumento lento de memória) sem identificar qual fronteira realmente quebrou geralmente significa que a mesma classe de bug recorre em outro lugar na base de código mais tarde.
• Conceitos Chave: sintoma versus causa raiz, violação de fronteira, estado compartilhado versus possuído, tempo de vida do objeto, a fronteira str/bytes.
• Quando Usar: Qualquer bug que só aparece às vezes, só sob carga, só em um ambiente específico, ou que um linter e uma leitura rápida do código não pegaram.
• Limitações / Trade-offs: Este modelo ajuda a categorizar qual fronteira quebrou, mas não substitui ferramentas específicas do cenário - tracemalloc para um vazamento, PYTHONASYNCIODEBUG para uma paralisação - e algumas classes de bugs (precisão numérica, arredondamento de ponto flutuante) são questões de correção matemática do domínio, em vez de violações de fronteira.
• Tópicos Relacionados: o loop de eventos, o sistema de importação, contagem de referências e coleta de lixo, codificação de caracteres.

Fundamentos

A primeira distinção que separa a identificação rápida da causa raiz de adivinhação é sintoma versus causa raiz: "o teste falha apenas quando executado com outros", "o aplicativo trava sem traceback", "a memória sobe por três dias antes de OOM" e "esta string parece lixo em um servidor, mas não em outro" são todos sintomas, não explicações.

Cada um dos cinco cenários desta seção é um sabor diferente da mesma pergunta subjacente: qual fronteira o código assumiu que se mantinha, mas não se manteve?

• Tempo de definição versus tempo de chamada. Um argumento padrão é avaliado uma vez, quando a função é definida, não fresco a cada chamada - a fronteira entre "isso executa uma vez" e "isso executa toda vez" é exatamente onde argumentos padrão mutáveis dão errado.
• Ordem de tempo de importação. Um módulo que importa outro módulo assume que esse módulo está totalmente inicializado no momento em que a importação é concluída - importações circulares acontecem quando essa suposição quebra no meio do ciclo, e o mecanismo de importação do Python retorna um módulo semi-construído em vez disso.
• Propriedade do loop/thread. O agendamento cooperativo assume que cada corrotina cede o controle razoavelmente com frequência - deadlocks asyncio e loops bloqueados acontecem quando algo na cadeia de chamadas nunca cede.
• Tempo de vida do objeto. O código assume que um objeto desaparece assim que nada "conceitualmente" precisa mais dele - vazamentos de memória acontecem quando algo ainda mantém uma referência (um cache, um closure, um listener) muito depois de o modelo mental do código dizer que não deveria.
• Texto versus bytes. O código assume que uma "string" é inequívoca - bugs de codificação e Unicode acontecem quando os bytes reais no disco, em um socket ou de um subprocesso não correspondem à codificação que o código de leitura assumiu silenciosamente.

Uma analogia útil: cada uma dessas fronteiras é como uma porta corta-fogo em um prédio que deveria ser autônoma. Na maioria das vezes, ninguém percebe que ela está lá, porque ela se fecha sozinha e faz seu trabalho invisivelmente - o bug aparece especificamente no caso em que algo a manteve aberta, e agora algo que deveria permanecer contido de um lado está solto do outro.

Mecânicas e Interações

Cada uma dessas categorias responde ao mesmo loop de diagnóstico, e pular as primeiras etapas para ir direto para "formar uma hipótese" é a maneira mais comum de uma sessão de depuração se estender.

1. Observar    - o que a evidência realmente diz? (traceback, travada, gráfico RSS, linha de log)
2. Estreitar   - a qual categoria de fronteira a assinatura deste sintoma corresponde?
3. Hipotetizar - dada essa categoria, qual suposição específica quebrou?
4. Verificar   - reproduzir deliberadamente, não assumir que a correção funcionou
5. Corrigir    - abordar a fronteira, não apenas o sintoma que você viu primeiro

A etapa de estreitamento é importante porque cada categoria de fronteira tem uma assinatura distinta e reconhecível que acelera drasticamente a busca, uma vez que você saiba procurá-la: um bug que só aparece quando os testes são executados como uma suíte (não sozinhos) tem a marca registrada de estado compartilhado sobrevivendo entre as chamadas - quase sempre um padrão mutável ou um cache em nível de módulo, não um erro lógico na própria função.

Um ImportError: cannot import name X from partially initialized module Y não é um soluço aleatório do interpretador - é o sistema de importação relatando, precisamente, que o módulo Y ainda estava em meio à execução quando algo pediu um nome que ele ainda não havia definido, o que só acontece quando dois módulos dependem do conteúdo um do outro.

Um processo que trava sem exceção, sem traceback e sem aumento de uso de CPU é um forte sinal para a categoria de propriedade do loop - algo na cadeia de chamadas está bloqueando sem ceder, ou duas corrotinas estão esperando uma pela outra de uma forma que nenhuma pode resolver.

# Uma verificação de identidade barata estreita "estado compartilhado" rapidamente, sem uma sessão de depurador
def add_item(item, bucket=[]):
    bucket.append(item)
    return bucket
 
first = add_item("a")
second = add_item("b")
print(id(first) == id(second))  # True confirma um objeto compartilhado, não duas listas novas

O crescimento constante do RSS ao longo de horas sem uma única alocação grande é a assinatura da categoria de tempo de vida - a correção não é "encontrar o vazamento" como um único bug, é encontrar qual referência está sobrevivendo ao modelo mental do código de seu tempo de vida, o que os snapshots de tracemalloc são construídos para responder diretamente.

UnicodeDecodeError, ou pior, nenhum erro, mas caracteres visivelmente incorretos (mojibake), é a assinatura da categoria texto/bytes - e o fato de que muitas vezes "funciona na minha máquina" e falha em outro lugar é em si uma pista, porque geralmente significa que uma codificação padrão implícita e dependente da plataforma foi usada em vez de uma explícita.

Considerações Avançadas e Aplicações

Reconhecer a categoria cedo muda a ferramenta que você pega primeiro, e pegar a ferramenta errada - percorrer um vazamento de memória linha por linha em pdb, ou tentar depurar com print uma condição de corrida - pode custar muito mais tempo do que o próprio bug, porque algumas dessas assinaturas só são visíveis em agregado (ao longo de muitas chamadas, ao longo de horas) em vez de em uma única execução.

As categorias interagem, e incidentes reais às vezes abrangem duas ao mesmo tempo: uma importação circular "corrigida" com uma importação local adiada pode mascarar o problema real de acoplamento (um problema de direção de dependência, não um problema de ordem de importação) o suficiente para que ele ressurja mais tarde como uma falha com aparência diferente, uma vez que a base de código cresça mais - a importação local tratou o sintoma, não a fronteira.

Nem todo cenário de depuração nesta seção mais ampla se encaixa igualmente bem na forma de violação de fronteira, e vale a pena ser honesto sobre isso: bugs de ponto flutuante e numéricos são um gênero diferente de problema, enraizado na matemática do domínio da representação de ponto flutuante binário em vez de uma suposição violada sobre tempo, propriedade ou codificação - o mesmo loop de diagnóstico (observar, estreitar, hipotetizar, verificar) ainda se aplica, mas a categoria em si fica fora da estrutura de cinco fronteiras desta página.

Equívocos Comuns

• "Estas são cinco coisas não relacionadas para memorizar." Elas são a mesma forma de falha - uma fronteira permeável - aparecendo em cinco lugares diferentes onde Python tem fronteiras: tempo de definição, tempo de importação, propriedade do loop, tempo de vida do objeto e codificação de texto.
• "Adiar uma importação dentro de uma função corrige uma importação circular." Geralmente silencia a falha sem abordar o acoplamento subjacente - dois módulos que dependem do conteúdo um do outro - que tende a ressurgir como um sintoma diferente assim que a base de código cresce.
• "Se não levanta uma exceção, não é um vazamento de memória." Crescimento ilimitado sem exceção alguma - apenas o RSS subindo até um OOM kill - ainda é uma violação da fronteira de tempo de vida; a ausência de um traceback é exatamente por que ele precisa de tracemalloc em vez de pdb.
• "Depuração por print é suficiente para bugs de concorrência e tempo de vida." Ambas as categorias dependem de tempo e histórico - uma instrução print mostra um instante, não o acúmulo ao longo de muitas chamadas ou a interleaving entre corrotinas que realmente produziram o bug.
• "Bugs de codificação são um caso de borda raro para texto não inglês." Qualquer implantação que cruza um sistema operacional, uma localidade ou uma fronteira de codificação padrão - um arquivo escrito em um sistema e lido em outro, um subprocesso com uma codificação padrão diferente - pode atingir isso, independentemente do idioma do texto.

FAQs

Relacionados

• Bugs de Argumentos Padrão Mutáveis - a fronteira tempo de definição versus tempo de chamada em profundidade
• Cenários de Importação Circular - a fronteira ordem de tempo de importação em profundidade
• Deadlocks asyncio e Bloqueio do Loop - a fronteira propriedade do loop em profundidade
• Cenários de Vazamento de Memória - a fronteira tempo de vida do objeto em profundidade
• Bugs de Codificação e Unicode - a fronteira texto/bytes em profundidade
• Ferramentas de Depuração - as ferramentas que confirmam cada assinatura

Versões de Stack: Esta página é conceitual e não está vinculada a uma versão específica de stack.