fastapi · YuriiMotov · Nov 12, 2025 · Oct 22, 2025 · Oct 22, 2025 · Oct 22, 2025
diff --git a/docs/pt/docs/about/index.md b/docs/pt/docs/about/index.md
@@ -1,3 +1,3 @@
-# Sobre
+# Sobre { #about }
 
-Sobre o FastAPI, seus padrões, inspirações e muito mais. 🤓
+Sobre o FastAPI, seu design, inspiração e mais. 🤓
diff --git a/docs/pt/docs/advanced/additional-responses.md b/docs/pt/docs/advanced/additional-responses.md
@@ -1,6 +1,6 @@
-# Retornos Adicionais no OpenAPI
+# Retornos Adicionais no OpenAPI { #additional-responses-in-openapi }
 
-/// warning | Aviso
+/// warning | Atenção
 
 Este é um tema bem avançado.
 
@@ -14,7 +14,7 @@ Essas respostas adicionais serão incluídas no esquema do OpenAPI, e também ap
 
 Porém para as respostas adicionais, você deve garantir que está retornando um `Response` como por exemplo o `JSONResponse` diretamente, junto com o código de status e o conteúdo.
 
-## Retorno Adicional com `model`
+## Retorno Adicional com `model` { #additional-response-with-model }
 
 Você pode fornecer o parâmetro `responses` aos seus *decoradores de caminho*.
 
@@ -49,7 +49,7 @@ O local correto é:
 
 ///
 
-O retorno gerado no OpenAI para esta *operação de caminho* será:
+O retorno gerado no OpenAPI para esta *operação de rota* será:
 
 ```JSON hl_lines="3-12"
 {
@@ -169,11 +169,11 @@ Os esquemas são referenciados em outro local dentro do esquema OpenAPI:
 }
 ```
 
-## Media types adicionais para o retorno principal
+## Media types adicionais para o retorno principal { #additional-media-types-for-the-main-response }
 
 Você pode utilizar o mesmo parâmetro `responses` para adicionar diferentes media types para o mesmo retorno principal.
 
-Por exemplo, você pode adicionar um media type adicional de `image/png`, declarando que a sua *operação de caminho* pode retornar um objeto JSON (com o media type `application/json`) ou uma imagem PNG:
+Por exemplo, você pode adicionar um media type adicional de `image/png`, declarando que a sua *operação de rota* pode retornar um objeto JSON (com o media type `application/json`) ou uma imagem PNG:
 
 {* ../../docs_src/additional_responses/tutorial002.py hl[19:24,28] *}
 
@@ -191,7 +191,7 @@ Porém se você especificou uma classe de retorno com o valor `None` como media
 
 ///
 
-## Combinando informações
+## Combinando informações { #combining-information }
 
 Você também pode combinar informações de diferentes lugares, incluindo os parâmetros `response_model`, `status_code`, e `responses`.
 
@@ -209,9 +209,9 @@ Isso será combinado e incluído em seu OpenAPI, e disponibilizado na documenta
 
 <img src="/img/tutorial/additional-responses/image01.png">
 
-## Combinar retornos predefinidos e personalizados
+## Combinar retornos predefinidos e personalizados { #combine-predefined-responses-and-custom-ones }
 
-Você pode querer possuir alguns retornos predefinidos que são aplicados para diversas *operações de caminho*, porém você deseja combinar com retornos personalizados que são necessários para cada *operação de caminho*.
+Você pode querer possuir alguns retornos predefinidos que são aplicados para diversas *operações de rota*, porém você deseja combinar com retornos personalizados que são necessários para cada *operação de rota*.
 
 Para estes casos, você pode utilizar a técnica do Python de "desempacotamento" de um `dict` utilizando `**dict_to_unpack`:
 
@@ -233,15 +233,15 @@ Aqui, o `new_dict` terá todos os pares de chave-valor do `old_dict` mais o novo
 }
 ```
 
-Você pode utilizar essa técnica para reutilizar alguns retornos predefinidos nas suas *operações de caminho* e combiná-las com personalizações adicionais.
+Você pode utilizar essa técnica para reutilizar alguns retornos predefinidos nas suas *operações de rota* e combiná-las com personalizações adicionais.
 
 Por exemplo:
 
 {* ../../docs_src/additional_responses/tutorial004.py hl[13:17,26] *}
 
-## Mais informações sobre retornos OpenAPI
+## Mais informações sobre retornos OpenAPI { #more-information-about-openapi-responses }
 
 Para verificar exatamente o que você pode incluir nos retornos, você pode conferir estas seções na especificação do OpenAPI:
 
-* <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responsesObject" class="external-link" target="_blank">Objeto de Retorno OpenAPI</a>, inclui o `Response Object`.
-* <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responseObject" class="external-link" target="_blank">Objeto de Retorno OpenAPI</a>, você pode incluir qualquer coisa dele diretamente em cada retorno dentro do seu parâmetro `responses`. Incluindo `description`, `headers`, `content` (dentro dele que você declara diferentes media types e esquemas JSON), e `links`.
+* <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object" class="external-link" target="_blank">Objeto de Retorno OpenAPI</a>, inclui o `Response Object`.
+* <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object" class="external-link" target="_blank">Objeto de Retorno OpenAPI</a>, você pode incluir qualquer coisa dele diretamente em cada retorno dentro do seu parâmetro `responses`. Incluindo `description`, `headers`, `content` (dentro dele que você declara diferentes media types e esquemas JSON), e `links`.
diff --git a/docs/pt/docs/advanced/additional-status-codes.md b/docs/pt/docs/advanced/additional-status-codes.md
@@ -1,22 +1,22 @@
-# Códigos de status adicionais
+# Códigos de status adicionais { #additional-status-codes }
 
-Por padrão, o **FastAPI** retornará as respostas utilizando o `JSONResponse`, adicionando o conteúdo do retorno da sua *operação de caminho* dentro do `JSONResponse`.
+Por padrão, o **FastAPI** retornará as respostas utilizando o `JSONResponse`, adicionando o conteúdo do retorno da sua *operação de rota* dentro do `JSONResponse`.
 
-Ele usará o código de status padrão ou o que você definir na sua *operação de caminho*.
+Ele usará o código de status padrão ou o que você definir na sua *operação de rota*.
 
-## Códigos de status adicionais
+## Códigos de status adicionais { #additional-status-codes_1 }
 
 Caso você queira retornar códigos de status adicionais além do código principal, você pode fazer isso retornando um `Response` diretamente, como por exemplo um `JSONResponse`, e definir os códigos de status adicionais diretamente.
 
-Por exemplo, vamos dizer que você deseja ter uma *operação de caminho* que permita atualizar itens, e retornar um código de status HTTP 200 "OK" quando for bem sucedido.
+Por exemplo, vamos dizer que você deseja ter uma *operação de rota* que permita atualizar itens, e retornar um código de status HTTP 200 "OK" quando for bem sucedido.
 
-Mas você também deseja aceitar novos itens. E quando os itens não existiam, ele os cria, e retorna o código de status HTTP 201 "Created.
+Mas você também deseja aceitar novos itens. E quando os itens não existiam, ele os cria, e retorna o código de status HTTP 201 "Created".
 
 Para conseguir isso, importe `JSONResponse` e retorne o seu conteúdo diretamente, definindo o `status_code` que você deseja:
 
 {* ../../docs_src/additional_status_codes/tutorial001_an_py310.py hl[4,25] *}
 
-/// warning | Aviso
+/// warning | Atenção
 
 Quando você retorna um `Response` diretamente, como no exemplo acima, ele será retornado diretamente.
 
@@ -26,15 +26,15 @@ Garanta que ele tenha toda informação que você deseja, e que os valores sejam
 
 ///
 
-/// note | Detalhes técnicos
+/// note | Detalhes Técnicos
 
 Você também pode utilizar `from starlette.responses import JSONResponse`.
 
 O **FastAPI** disponibiliza o `starlette.responses` como `fastapi.responses` apenas por conveniência para você, o programador. Porém a maioria dos retornos disponíveis vem diretamente do Starlette. O mesmo com `status`.
 
 ///
 
-## OpenAPI e documentação da API
+## OpenAPI e documentação da API { #openapi-and-api-docs }
 
 Se você retorna códigos de status adicionais e retornos diretamente, eles não serão incluídos no esquema do OpenAPI (a documentação da API), porque o FastAPI não tem como saber de antemão o que será retornado.
 

diff --git a/docs/pt/docs/advanced/advanced-dependencies.md b/docs/pt/docs/advanced/advanced-dependencies.md
@@ -1,6 +1,6 @@
-# Dependências avançadas
+# Dependências avançadas { #advanced-dependencies }
 
-## Dependências parametrizadas
+## Dependências parametrizadas { #parameterized-dependencies }
 
 Todas as dependências que vimos até agora são funções ou classes fixas.
 
@@ -10,7 +10,7 @@ Vamos imaginar que queremos ter uma dependência que verifica se o parâmetro de
 
 Porém nós queremos poder parametrizar o conteúdo fixo.
 
-## Uma instância "chamável"
+## Uma instância "chamável" { #a-callable-instance }
 
 Em Python existe uma maneira de fazer com que uma instância de uma classe seja um "chamável".
 
@@ -22,23 +22,23 @@ Para fazer isso, nós declaramos o método `__call__`:
 
 Neste caso, o `__call__` é o que o **FastAPI** utilizará para verificar parâmetros adicionais e sub dependências, e isso é o que será chamado para passar o valor ao parâmetro na sua *função de operação de rota* posteriormente.
 
-## Parametrizar a instância
+## Parametrizar a instância { #parameterize-the-instance }
 
 E agora, nós podemos utilizar o `__init__` para declarar os parâmetros da instância que podemos utilizar para "parametrizar" a dependência:
 
 {* ../../docs_src/dependencies/tutorial011_an_py39.py hl[9] *}
 
 Neste caso, o **FastAPI** nunca tocará ou se importará com o `__init__`, nós vamos utilizar diretamente em nosso código.
 
-## Crie uma instância
+## Crie uma instância { #create-an-instance }
 
 Nós poderíamos criar uma instância desta classe com:
 
 {* ../../docs_src/dependencies/tutorial011_an_py39.py hl[18] *}
 
 E deste modo nós podemos "parametrizar" a nossa dependência, que agora possui `"bar"` dentro dele, como o atributo `checker.fixed_content`.
 
-## Utilize a instância como dependência
+## Utilize a instância como dependência { #use-the-instance-as-a-dependency }
 
 Então, nós podemos utilizar este `checker` em um `Depends(checker)`, no lugar de `Depends(FixedContentQueryChecker)`, porque a dependência é a instância, `checker`, e não a própria classe.
 
@@ -63,3 +63,101 @@ Nos capítulos sobre segurança, existem funções utilitárias que são impleme
 Se você entendeu tudo isso, você já sabe como essas funções utilitárias para segurança funcionam por debaixo dos panos.
 
 ///
+
+## Dependências com `yield`, `HTTPException`, `except` e Tarefas em Segundo Plano { #dependencies-with-yield-httpexception-except-and-background-tasks }
+
+/// warning | Atenção
+
+Muito provavelmente você não precisa desses detalhes técnicos.
+
+Esses detalhes são úteis principalmente se você tinha uma aplicação FastAPI anterior à versão 0.121.0 e está enfrentando problemas com dependências com `yield`.
+
+///
+
+Dependências com `yield` evoluíram ao longo do tempo para contemplar diferentes casos de uso e corrigir alguns problemas, aqui está um resumo do que mudou.
+
+### Dependências com `yield` e `scope` { #dependencies-with-yield-and-scope }
+
+Na versão 0.121.0, o FastAPI adicionou suporte a `Depends(scope="function")` para dependências com `yield`.
+
+Usando `Depends(scope="function")`, o código de saída após o `yield` é executado logo depois que a *função de operação de rota* termina, antes de a response ser enviada de volta ao cliente.
+
+E ao usar `Depends(scope="request")` (o padrão), o código de saída após o `yield` é executado depois que a response é enviada.
+
+Você pode ler mais na documentação em [Dependências com `yield` - Saída antecipada e `scope`](../tutorial/dependencies/dependencies-with-yield.md#early-exit-and-scope).
+
+### Dependências com `yield` e `StreamingResponse`, Detalhes Técnicos { #dependencies-with-yield-and-streamingresponse-technical-details }
+
+Antes do FastAPI 0.118.0, se você usasse uma dependência com `yield`, o código de saída (após o `yield`) rodaria depois que a *função de operação de rota* retornasse, mas logo antes de enviar a resposta.
+
+A intenção era evitar manter recursos por mais tempo que o necessário, esperando a resposta percorrer a rede.
+
+Essa mudança também significava que, se você retornasse um `StreamingResponse`, o código de saída da dependência com `yield` já teria sido executado.
+
+Por exemplo, se você tivesse uma sessão de banco de dados em uma dependência com `yield`, o `StreamingResponse` não conseguiria usar essa sessão enquanto transmite dados, porque a sessão já teria sido fechada no código de saída após o `yield`.
+
+Esse comportamento foi revertido na versão 0.118.0, para que o código de saída após o `yield` seja executado depois que a resposta for enviada.
+
+/// info | Informação
+
+Como você verá abaixo, isso é muito semelhante ao comportamento antes da versão 0.106.0, mas com várias melhorias e correções de bugs para casos extremos.
+
+///
+
+#### Casos de uso com código de saída antecipado { #use-cases-with-early-exit-code }
+
+Há alguns casos de uso, com condições específicas, que poderiam se beneficiar do comportamento antigo de executar o código de saída das dependências com `yield` antes de enviar a resposta.
+
+Por exemplo, imagine que você tem código que usa uma sessão de banco de dados em uma dependência com `yield` apenas para verificar um usuário, mas a sessão de banco de dados nunca é usada novamente na *função de operação de rota*, somente na dependência, e a resposta demora a ser enviada, como um `StreamingResponse` que envia dados lentamente, mas por algum motivo não usa o banco de dados.
+
+Nesse caso, a sessão de banco de dados seria mantida até que a resposta termine de ser enviada, mas se você não a usa, então não seria necessário mantê-la.
+
+Veja como poderia ser:
+
+{* ../../docs_src/dependencies/tutorial013_an_py310.py *}
+
+O código de saída, o fechamento automático da `Session` em:
+
+{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[19:21] *}
+
+...seria executado depois que a resposta terminar de enviar os dados lentos:
+
+{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[30:38] hl[31:33] *}
+
+Mas como `generate_stream()` não usa a sessão do banco de dados, não é realmente necessário manter a sessão aberta enquanto envia a resposta.
+
+Se você tiver esse caso específico usando SQLModel (ou SQLAlchemy), você poderia fechar explicitamente a sessão depois que não precisar mais dela:
+
+{* ../../docs_src/dependencies/tutorial014_an_py310.py ln[24:28] hl[28] *}
+
+Dessa forma a sessão liberaria a conexão com o banco de dados, para que outras requisições pudessem usá-la.
+
+Se você tiver um caso diferente que precise sair antecipadamente de uma dependência com `yield`, por favor crie uma <a href="https://github.com/fastapi/fastapi/discussions/new?category=questions" class="external-link" target="_blank">Pergunta no GitHub Discussions</a> com o seu caso específico e por que você se beneficiaria de ter o fechamento antecipado para dependências com `yield`.
+
+Se houver casos de uso convincentes para fechamento antecipado em dependências com `yield`, considerarei adicionar uma nova forma de optar por esse fechamento antecipado.
+
+### Dependências com `yield` e `except`, Detalhes Técnicos { #dependencies-with-yield-and-except-technical-details }
+
+Antes do FastAPI 0.110.0, se você usasse uma dependência com `yield`, e então capturasse uma exceção com `except` nessa dependência, e você não relançasse a exceção, a exceção seria automaticamente levantada/encaminhada para quaisquer tratadores de exceção ou para o tratador de erro interno do servidor.
+
+Isso foi alterado na versão 0.110.0 para corrigir consumo de memória não tratado decorrente de exceções encaminhadas sem um tratador (erros internos do servidor), e para torná-lo consistente com o comportamento do código Python regular.
+
+### Tarefas em Segundo Plano e Dependências com `yield`, Detalhes Técnicos { #background-tasks-and-dependencies-with-yield-technical-details }
+
+Antes do FastAPI 0.106.0, lançar exceções após o `yield` não era possível, o código de saída em dependências com `yield` era executado depois que a resposta era enviada, então [Tratadores de Exceções](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank} já teriam sido executados.
+
+Isso foi projetado assim principalmente para permitir o uso dos mesmos objetos "yielded" por dependências dentro de tarefas em segundo plano, porque o código de saída seria executado depois que as tarefas em segundo plano fossem concluídas.
+
+Isso foi alterado no FastAPI 0.106.0 com a intenção de não manter recursos enquanto se espera a resposta percorrer a rede.
+
+/// tip | Dica
+
+Além disso, uma tarefa em segundo plano normalmente é um conjunto de lógica independente que deve ser tratado separadamente, com seus próprios recursos (por exemplo, sua própria conexão de banco de dados).
+
+Assim, desta forma você provavelmente terá um código mais limpo.
+
+///
+
+Se você costumava depender desse comportamento, agora você deve criar os recursos para tarefas em segundo plano dentro da própria tarefa em segundo plano, e usar internamente apenas dados que não dependam dos recursos de dependências com `yield`.
+
+Por exemplo, em vez de usar a mesma sessão de banco de dados, você criaria uma nova sessão de banco de dados dentro da tarefa em segundo plano, e obteria os objetos do banco de dados usando essa nova sessão. E então, em vez de passar o objeto do banco de dados como parâmetro para a função da tarefa em segundo plano, você passaria o ID desse objeto e então obteria o objeto novamente dentro da função da tarefa em segundo plano.