diff --git a/docs/pt/docs/advanced/events.md b/docs/pt/docs/advanced/events.md index 2d38e0899..e29ece8e3 100644 --- a/docs/pt/docs/advanced/events.md +++ b/docs/pt/docs/advanced/events.md @@ -1,65 +1,64 @@ -# Eventos de vida útil +# Eventos de lifespan { #lifespan-events } -Você pode definir a lógica (código) que poderia ser executada antes da aplicação **inicializar**. Isso significa que esse código será executado **uma vez**, **antes** da aplicação **começar a receber requisições**. +Você pode definir a lógica (código) que deve ser executada antes da aplicação **inicializar**. Isso significa que esse código será executado **uma vez**, **antes** de a aplicação **começar a receber requisições**. -Do mesmo modo, você pode definir a lógica (código) que será executada quando a aplicação estiver sendo **encerrada**. Nesse caso, este código será executado **uma vez**, **depois** de ter possivelmente tratado **várias requisições**. +Da mesma forma, você pode definir a lógica (código) que deve ser executada quando a aplicação estiver **encerrando**. Nesse caso, esse código será executado **uma vez**, **depois** de possivelmente ter tratado **várias requisições**. -Por conta desse código ser executado antes da aplicação **começar** a receber requisições, e logo após **terminar** de lidar com as requisições, ele cobre toda a **vida útil** (_lifespan_) da aplicação (o termo "vida útil" será importante em um segundo 😉). +Como esse código é executado antes de a aplicação **começar** a receber requisições e logo depois que ela **termina** de lidar com as requisições, ele cobre todo o **lifespan** da aplicação (a palavra "lifespan" será importante em um segundo 😉). -Pode ser muito útil para configurar **recursos** que você precisa usar por toda aplicação, e que são **compartilhados** entre as requisições, e/ou que você precisa **limpar** depois. Por exemplo, o pool de uma conexão com o banco de dados ou carregamento de um modelo compartilhado de aprendizado de máquina (_machine learning_). +Isso pode ser muito útil para configurar **recursos** que você precisa usar por toda a aplicação, e que são **compartilhados** entre as requisições e/ou que você precisa **limpar** depois. Por exemplo, um pool de conexões com o banco de dados ou o carregamento de um modelo de machine learning compartilhado. -## Caso de uso +## Caso de uso { #use-case } -Vamos iniciar com um exemplo de **caso de uso** e então ver como resolvê-lo com isso. +Vamos começar com um exemplo de **caso de uso** e então ver como resolvê-lo com isso. -Vamos imaginar que você tem alguns **modelos de _machine learning_** que deseja usar para lidar com as requisições. 🤖 +Vamos imaginar que você tem alguns **modelos de machine learning** que deseja usar para lidar com as requisições. 🤖 -Os mesmos modelos são compartilhados entre as requisições, então não é um modelo por requisição, ou um por usuário ou algo parecido. +Os mesmos modelos são compartilhados entre as requisições, então não é um modelo por requisição, ou um por usuário, ou algo parecido. -Vamos imaginar que o carregamento do modelo pode **demorar bastante tempo**, porque ele tem que ler muitos **dados do disco**. Então você não quer fazer isso a cada requisição. +Vamos imaginar que o carregamento do modelo pode **demorar bastante tempo**, porque ele precisa ler muitos **dados do disco**. Então você não quer fazer isso a cada requisição. -Você poderia carregá-lo no nível mais alto do módulo/arquivo, mas isso também poderia significaria **carregar o modelo** mesmo se você estiver executando um simples teste automatizado, então esse teste poderia ser **lento** porque teria que esperar o carregamento do modelo antes de ser capaz de executar uma parte independente do código. +Você poderia carregá-lo no nível mais alto do módulo/arquivo, mas isso também significaria **carregar o modelo** mesmo se você estivesse executando um teste automatizado simples; então esse teste poderia ser **lento** porque teria que esperar o carregamento do modelo antes de conseguir executar uma parte independente do código. +É isso que vamos resolver: vamos carregar o modelo antes de as requisições serem tratadas, mas apenas um pouco antes de a aplicação começar a receber requisições, não enquanto o código estiver sendo carregado. -Isso é que nós iremos resolver, vamos carregar o modelo antes das requisições serem manuseadas, mas apenas um pouco antes da aplicação começar a receber requisições, não enquanto o código estiver sendo carregado. +## Lifespan { #lifespan } -## Vida útil (_Lifespan_) +Você pode definir essa lógica de *inicialização* e *encerramento* usando o parâmetro `lifespan` da aplicação `FastAPI`, e um "gerenciador de contexto" (vou mostrar o que é isso em um segundo). -Você pode definir essa lógica de *inicialização* e *encerramento* usando os parâmetros de `lifespan` da aplicação `FastAPI`, e um "gerenciador de contexto" (te mostrarei o que é isso a seguir). +Vamos começar com um exemplo e depois ver em detalhes. -Vamos iniciar com um exemplo e ver isso detalhadamente. - -Nós criamos uma função assíncrona chamada `lifespan()` com `yield` como este: +Nós criamos uma função assíncrona `lifespan()` com `yield` assim: {* ../../docs_src/events/tutorial003.py hl[16,19] *} -Aqui nós estamos simulando a *inicialização* custosa do carregamento do modelo colocando a (falsa) função de modelo no dicionário com modelos de _machine learning_ antes do `yield`. Este código será executado **antes** da aplicação **começar a receber requisições**, durante a *inicialização*. +Aqui estamos simulando a operação de *inicialização* custosa de carregar o modelo, colocando a (falsa) função do modelo no dicionário com modelos de machine learning antes do `yield`. Esse código será executado **antes** de a aplicação **começar a receber requisições**, durante a *inicialização*. -E então, logo após o `yield`, descarregaremos o modelo. Esse código será executado **após** a aplicação **terminar de lidar com as requisições**, pouco antes do *encerramento*. Isso poderia, por exemplo, liberar recursos como memória ou GPU. +E então, logo após o `yield`, descarregamos o modelo. Esse código será executado **depois** de a aplicação **terminar de lidar com as requisições**, pouco antes do *encerramento*. Isso poderia, por exemplo, liberar recursos como memória ou uma GPU. /// tip | Dica O `shutdown` aconteceria quando você estivesse **encerrando** a aplicação. -Talvez você precise inicializar uma nova versão, ou apenas cansou de executá-la. 🤷 +Talvez você precise iniciar uma nova versão, ou apenas cansou de executá-la. 🤷 /// -### Função _lifespan_ +### Função lifespan { #lifespan-function } -A primeira coisa a notar, é que estamos definindo uma função assíncrona com `yield`. Isso é muito semelhante à Dependências com `yield`. +A primeira coisa a notar é que estamos definindo uma função assíncrona com `yield`. Isso é muito semelhante a Dependências com `yield`. {* ../../docs_src/events/tutorial003.py hl[14:19] *} -A primeira parte da função, antes do `yield`, será executada **antes** da aplicação inicializar. +A primeira parte da função, antes do `yield`, será executada **antes** de a aplicação iniciar. -E a parte posterior do `yield` irá executar **após** a aplicação ser encerrada. +E a parte posterior ao `yield` será executada **depois** de a aplicação ter terminado. -### Gerenciador de Contexto Assíncrono +### Gerenciador de contexto assíncrono { #async-context-manager } Se você verificar, a função está decorada com um `@asynccontextmanager`. -Que converte a função em algo chamado de "**Gerenciador de Contexto Assíncrono**". +Isso converte a função em algo chamado "**gerenciador de contexto assíncrono**". {* ../../docs_src/events/tutorial003.py hl[1,13] *} @@ -70,97 +69,97 @@ with open("file.txt") as file: file.read() ``` -Nas versões mais recentes de Python, há também um **gerenciador de contexto assíncrono**. Você o usaria com `async with`: +Em versões mais recentes do Python, há também um **gerenciador de contexto assíncrono**. Você o usaria com `async with`: ```Python async with lifespan(app): await do_stuff() ``` -Quando você cria um gerenciador de contexto ou um gerenciador de contexto assíncrono como mencionado acima, o que ele faz é que, antes de entrar no bloco `with`, ele irá executar o código anterior ao `yield`, e depois de sair do bloco `with`, ele irá executar o código depois do `yield`. +Quando você cria um gerenciador de contexto ou um gerenciador de contexto assíncrono como acima, o que ele faz é: antes de entrar no bloco `with`, ele executa o código antes do `yield`, e após sair do bloco `with`, ele executa o código depois do `yield`. -No nosso exemplo de código acima, nós não usamos ele diretamente, mas nós passamos para o FastAPI para ele usá-lo. +No nosso exemplo de código acima, não o usamos diretamente, mas passamos para o FastAPI para que ele o use. -O parâmetro `lifespan` da aplicação `FastAPI` usa um **Gerenciador de Contexto Assíncrono**, então nós podemos passar nosso novo gerenciador de contexto assíncrono do `lifespan` para ele. +O parâmetro `lifespan` da aplicação `FastAPI` aceita um **gerenciador de contexto assíncrono**, então podemos passar para ele nosso novo gerenciador de contexto assíncrono `lifespan`. {* ../../docs_src/events/tutorial003.py hl[22] *} -## Eventos alternativos (deprecados) +## Eventos alternativos (descontinuados) { #alternative-events-deprecated } -/// warning | Aviso +/// warning | Atenção -A maneira recomendada para lidar com a *inicialização* e o *encerramento* é usando o parâmetro `lifespan` da aplicação `FastAPI` como descrito acima. +A forma recomendada de lidar com a *inicialização* e o *encerramento* é usando o parâmetro `lifespan` da aplicação `FastAPI`, como descrito acima. Se você fornecer um parâmetro `lifespan`, os manipuladores de eventos `startup` e `shutdown` não serão mais chamados. É tudo `lifespan` ou tudo por eventos, não ambos. -Você provavelmente pode pular essa parte. +Você provavelmente pode pular esta parte. /// -Existe uma forma alternativa para definir a execução dessa lógica durante *inicialização* e durante *encerramento*. +Existe uma forma alternativa de definir essa lógica para ser executada durante a *inicialização* e durante o *encerramento*. -Você pode definir manipuladores de eventos (funções) que precisam ser executadas antes da aplicação inicializar, ou quando a aplicação estiver encerrando. +Você pode definir manipuladores de eventos (funções) que precisam ser executados antes de a aplicação iniciar ou quando a aplicação estiver encerrando. Essas funções podem ser declaradas com `async def` ou `def` normal. -### Evento `startup` +### Evento `startup` { #startup-event } -Para adicionar uma função que deve rodar antes da aplicação iniciar, declare-a com o evento `"startup"`: +Para adicionar uma função que deve rodar antes de a aplicação iniciar, declare-a com o evento `"startup"`: {* ../../docs_src/events/tutorial001.py hl[8] *} -Nesse caso, a função de manipulação de evento `startup` irá inicializar os itens do "banco de dados" (só um `dict`) com alguns valores. +Nesse caso, a função de manipulador do evento `startup` inicializará os itens do "banco de dados" (apenas um `dict`) com alguns valores. -Você pode adicionar mais que uma função de manipulação de evento. +Você pode adicionar mais de uma função de manipulador de eventos. -E sua aplicação não irá começar a receber requisições até que todos os manipuladores de eventos de `startup` sejam concluídos. +E sua aplicação não começará a receber requisições até que todos os manipuladores de eventos `startup` sejam concluídos. -### Evento `shutdown` +### Evento `shutdown` { #shutdown-event } -Para adicionar uma função que deve ser executada quando a aplicação estiver encerrando, declare ela com o evento `"shutdown"`: +Para adicionar uma função que deve ser executada quando a aplicação estiver encerrando, declare-a com o evento `"shutdown"`: {* ../../docs_src/events/tutorial002.py hl[6] *} -Aqui, a função de manipulação de evento `shutdown` irá escrever uma linha de texto `"Application shutdown"` no arquivo `log.txt`. +Aqui, a função de manipulador do evento `shutdown` escreverá uma linha de texto `"Application shutdown"` no arquivo `log.txt`. /// info | Informação -Na função `open()`, o `mode="a"` significa "acrescentar", então, a linha irá ser adicionada depois de qualquer coisa que esteja naquele arquivo, sem sobrescrever o conteúdo anterior. +Na função `open()`, o `mode="a"` significa "acrescentar", então a linha será adicionada depois do que já estiver naquele arquivo, sem sobrescrever o conteúdo anterior. /// /// tip | Dica -Perceba que nesse caso nós estamos usando a função padrão do Python `open()` que interage com um arquivo. +Perceba que, nesse caso, estamos usando a função padrão do Python `open()` que interage com um arquivo. -Então, isso envolve I/O (input/output), que exige "esperar" que coisas sejam escritas em disco. +Então, isso envolve I/O (input/output), que requer "esperar" que as coisas sejam escritas em disco. Mas `open()` não usa `async` e `await`. -Então, nós declaramos uma função de manipulação de evento com o padrão `def` ao invés de `async def`. +Assim, declaramos a função de manipulador de evento com `def` padrão em vez de `async def`. /// -### `startup` e `shutdown` juntos +### `startup` e `shutdown` juntos { #startup-and-shutdown-together } -Há uma grande chance que a lógica para sua *inicialização* e *encerramento* esteja conectada, você pode querer iniciar alguma coisa e então finalizá-la, adquirir um recurso e então liberá-lo, etc. +Há uma grande chance de que a lógica para sua *inicialização* e *encerramento* esteja conectada, você pode querer iniciar alguma coisa e então finalizá-la, adquirir um recurso e então liberá-lo, etc. -Fazendo isso em funções separadas que não compartilham lógica ou variáveis entre elas é mais difícil já que você precisa armazenar os valores em variáveis globais ou truques parecidos. +Fazer isso em funções separadas que não compartilham lógica ou variáveis entre si é mais difícil, pois você precisaria armazenar valores em variáveis globais ou truques semelhantes. -Por causa disso, agora é recomendado em vez disso usar o `lifespan` como explicado acima. +Por causa disso, agora é recomendado usar o `lifespan`, como explicado acima. -## Detalhes técnicos +## Detalhes técnicos { #technical-details } -Só um detalhe técnico para nerds curiosos. 🤓 +Apenas um detalhe técnico para nerds curiosos. 🤓 -Por baixo, na especificação técnica ASGI, essa é a parte do Protocolo Lifespan, e define eventos chamados `startup` e `shutdown`. +Por baixo, na especificação técnica do ASGI, isso é parte do Protocolo Lifespan, e define eventos chamados `startup` e `shutdown`. /// info | Informação -Você pode ler mais sobre o manipulador `lifespan` do Starlette na Documentação do Lifespan Starlette. +Você pode ler mais sobre os manipuladores de `lifespan` do Starlette na Documentação do Lifespan do Starlette. -Incluindo como manipular estado do lifespan que pode ser usado em outras áreas do seu código. +Incluindo como lidar com estado do lifespan que pode ser usado em outras áreas do seu código. /// -## Sub Aplicações +## Sub Aplicações { #sub-applications } -🚨 Tenha em mente que esses eventos de lifespan (de inicialização e desligamento) irão somente ser executados para a aplicação principal, não para [Sub Aplicações - Montagem](sub-applications.md){.internal-link target=_blank}. +🚨 Tenha em mente que esses eventos de lifespan (inicialização e encerramento) serão executados apenas para a aplicação principal, não para [Sub Aplicações - Montagem](sub-applications.md){.internal-link target=_blank}.