vvanglro
9 months ago
committed by
GitHub
GitHub
21 changed files with 1993 additions and 29 deletions
|
After Width: | Height: | Size: 11 KiB |
|
After Width: | Height: | Size: 21 KiB |
|
After Width: | Height: | Size: 29 KiB |
|
After Width: | Height: | Size: 1.7 KiB |
|
After Width: | Height: | Size: 18 KiB |
@ -0,0 +1,5 @@ |
|||||
|
# Apprendre |
||||
|
|
||||
|
Voici les sections introductives et les tutoriels pour apprendre **FastAPI**. |
||||
|
|
||||
|
Vous pouvez considérer ceci comme un **manuel**, un **cours**, la **méthode officielle** et recommandée pour appréhender FastAPI. 😎 |
||||
@ -0,0 +1,240 @@ |
|||||
|
# Retornos Adicionais no OpenAPI |
||||
|
|
||||
|
!!! warning "Aviso" |
||||
|
Este é um tema bem avançado. |
||||
|
|
||||
|
Se você está começando com o **FastAPI**, provavelmente você não precisa disso. |
||||
|
|
||||
|
Você pode declarar retornos adicionais, com códigos de status adicionais, media types, descrições, etc. |
||||
|
|
||||
|
Essas respostas adicionais serão incluídas no esquema do OpenAPI, e também aparecerão na documentação da API. |
||||
|
|
||||
|
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` |
||||
|
|
||||
|
Você pode fornecer o parâmetro `responses` aos seus *decoradores de caminho*. |
||||
|
|
||||
|
Este parâmetro recebe um `dict`, as chaves são os códigos de status para cada retorno, como por exemplo `200`, e os valores são um outro `dict` com a informação de cada um deles. |
||||
|
|
||||
|
Cada um desses `dict` de retorno pode ter uma chave `model`, contendo um modelo do Pydantic, assim como o `response_model`. |
||||
|
|
||||
|
O **FastAPI** pegará este modelo, gerará o esquema JSON dele e incluirá no local correto do OpenAPI. |
||||
|
|
||||
|
Por exemplo, para declarar um outro retorno com o status code `404` e um modelo do Pydantic chamado `Message`, você pode escrever: |
||||
|
|
||||
|
```Python hl_lines="18 22" |
||||
|
{!../../../docs_src/additional_responses/tutorial001.py!} |
||||
|
``` |
||||
|
|
||||
|
!!! note "Nota" |
||||
|
Lembre-se que você deve retornar o `JSONResponse` diretamente. |
||||
|
|
||||
|
!!! info "Informação" |
||||
|
A chave `model` não é parte do OpenAPI. |
||||
|
|
||||
|
O **FastAPI** pegará o modelo do Pydantic, gerará o `JSON Schema`, e adicionará no local correto. |
||||
|
|
||||
|
O local correto é: |
||||
|
|
||||
|
* Na chave `content`, que tem como valor um outro objeto JSON (`dict`) que contém: |
||||
|
* Uma chave com o media type, como por exemplo `application/json`, que contém como valor um outro objeto JSON, contendo:: |
||||
|
* Uma chave `schema`, que contém como valor o JSON Schema do modelo, sendo este o local correto. |
||||
|
* O **FastAPI** adiciona aqui a referência dos esquemas JSON globais que estão localizados em outro lugar, ao invés de incluí-lo diretamente. Deste modo, outras aplicações e clientes podem utilizar estes esquemas JSON diretamente, fornecer melhores ferramentas de geração de código, etc. |
||||
|
|
||||
|
O retorno gerado no OpenAI para esta *operação de caminho* será: |
||||
|
|
||||
|
```JSON hl_lines="3-12" |
||||
|
{ |
||||
|
"responses": { |
||||
|
"404": { |
||||
|
"description": "Additional Response", |
||||
|
"content": { |
||||
|
"application/json": { |
||||
|
"schema": { |
||||
|
"$ref": "#/components/schemas/Message" |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
}, |
||||
|
"200": { |
||||
|
"description": "Successful Response", |
||||
|
"content": { |
||||
|
"application/json": { |
||||
|
"schema": { |
||||
|
"$ref": "#/components/schemas/Item" |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
}, |
||||
|
"422": { |
||||
|
"description": "Validation Error", |
||||
|
"content": { |
||||
|
"application/json": { |
||||
|
"schema": { |
||||
|
"$ref": "#/components/schemas/HTTPValidationError" |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
Os esquemas são referenciados em outro local dentro do esquema OpenAPI: |
||||
|
|
||||
|
```JSON hl_lines="4-16" |
||||
|
{ |
||||
|
"components": { |
||||
|
"schemas": { |
||||
|
"Message": { |
||||
|
"title": "Message", |
||||
|
"required": [ |
||||
|
"message" |
||||
|
], |
||||
|
"type": "object", |
||||
|
"properties": { |
||||
|
"message": { |
||||
|
"title": "Message", |
||||
|
"type": "string" |
||||
|
} |
||||
|
} |
||||
|
}, |
||||
|
"Item": { |
||||
|
"title": "Item", |
||||
|
"required": [ |
||||
|
"id", |
||||
|
"value" |
||||
|
], |
||||
|
"type": "object", |
||||
|
"properties": { |
||||
|
"id": { |
||||
|
"title": "Id", |
||||
|
"type": "string" |
||||
|
}, |
||||
|
"value": { |
||||
|
"title": "Value", |
||||
|
"type": "string" |
||||
|
} |
||||
|
} |
||||
|
}, |
||||
|
"ValidationError": { |
||||
|
"title": "ValidationError", |
||||
|
"required": [ |
||||
|
"loc", |
||||
|
"msg", |
||||
|
"type" |
||||
|
], |
||||
|
"type": "object", |
||||
|
"properties": { |
||||
|
"loc": { |
||||
|
"title": "Location", |
||||
|
"type": "array", |
||||
|
"items": { |
||||
|
"type": "string" |
||||
|
} |
||||
|
}, |
||||
|
"msg": { |
||||
|
"title": "Message", |
||||
|
"type": "string" |
||||
|
}, |
||||
|
"type": { |
||||
|
"title": "Error Type", |
||||
|
"type": "string" |
||||
|
} |
||||
|
} |
||||
|
}, |
||||
|
"HTTPValidationError": { |
||||
|
"title": "HTTPValidationError", |
||||
|
"type": "object", |
||||
|
"properties": { |
||||
|
"detail": { |
||||
|
"title": "Detail", |
||||
|
"type": "array", |
||||
|
"items": { |
||||
|
"$ref": "#/components/schemas/ValidationError" |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
## Media types adicionais para o retorno principal |
||||
|
|
||||
|
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: |
||||
|
|
||||
|
```Python hl_lines="19-24 28" |
||||
|
{!../../../docs_src/additional_responses/tutorial002.py!} |
||||
|
``` |
||||
|
|
||||
|
!!! note "Nota" |
||||
|
Note que você deve retornar a imagem utilizando um `FileResponse` diretamente. |
||||
|
|
||||
|
!!! info "Informação" |
||||
|
A menos que você especifique um media type diferente explicitamente em seu parâmetro `responses`, o FastAPI assumirá que o retorno possui o mesmo media type contido na classe principal de retorno (padrão `application/json`). |
||||
|
|
||||
|
Porém se você especificou uma classe de retorno com o valor `None` como media type, o FastAPI utilizará `application/json` para qualquer retorno adicional que possui um modelo associado. |
||||
|
|
||||
|
## Combinando informações |
||||
|
|
||||
|
Você também pode combinar informações de diferentes lugares, incluindo os parâmetros `response_model`, `status_code`, e `responses`. |
||||
|
|
||||
|
Você pode declarar um `response_model`, utilizando o código de status padrão `200` (ou um customizado caso você precise), e depois adicionar informações adicionais para esse mesmo retorno em `responses`, diretamente no esquema OpenAPI. |
||||
|
|
||||
|
O **FastAPI** manterá as informações adicionais do `responses`, e combinará com o esquema JSON do seu modelo. |
||||
|
|
||||
|
Por exemplo, você pode declarar um retorno com o código de status `404` que utiliza um modelo do Pydantic que possui um `description` customizado. |
||||
|
|
||||
|
E um retorno com o código de status `200` que utiliza o seu `response_model`, porém inclui um `example` customizado: |
||||
|
|
||||
|
```Python hl_lines="20-31" |
||||
|
{!../../../docs_src/additional_responses/tutorial003.py!} |
||||
|
``` |
||||
|
|
||||
|
Isso será combinado e incluído em seu OpenAPI, e disponibilizado na documentação da sua API: |
||||
|
|
||||
|
<img src="/img/tutorial/additional-responses/image01.png"> |
||||
|
|
||||
|
## Combinar retornos predefinidos e personalizados |
||||
|
|
||||
|
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*. |
||||
|
|
||||
|
Para estes casos, você pode utilizar a técnica do Python de "desempacotamento" de um `dict` utilizando `**dict_to_unpack`: |
||||
|
|
||||
|
```Python |
||||
|
old_dict = { |
||||
|
"old key": "old value", |
||||
|
"second old key": "second old value", |
||||
|
} |
||||
|
new_dict = {**old_dict, "new key": "new value"} |
||||
|
``` |
||||
|
|
||||
|
Aqui, o `new_dict` terá todos os pares de chave-valor do `old_dict` mais o novo par de chave-valor: |
||||
|
|
||||
|
```Python |
||||
|
{ |
||||
|
"old key": "old value", |
||||
|
"second old key": "second old value", |
||||
|
"new key": "new value", |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
Você pode utilizar essa técnica para reutilizar alguns retornos predefinidos nas suas *operações de caminho* e combiná-las com personalizações adicionais. |
||||
|
|
||||
|
Por exemplo: |
||||
|
|
||||
|
```Python hl_lines="13-17 26" |
||||
|
{!../../../docs_src/additional_responses/tutorial004.py!} |
||||
|
``` |
||||
|
|
||||
|
## Mais informações sobre retornos OpenAPI |
||||
|
|
||||
|
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`. |
||||
@ -0,0 +1,69 @@ |
|||||
|
# Códigos de status adicionais |
||||
|
|
||||
|
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`. |
||||
|
|
||||
|
Ele usará o código de status padrão ou o que você definir na sua *operação de caminho*. |
||||
|
|
||||
|
## Códigos de status adicionais |
||||
|
|
||||
|
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. |
||||
|
|
||||
|
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: |
||||
|
|
||||
|
=== "Python 3.10+" |
||||
|
|
||||
|
```Python hl_lines="4 25" |
||||
|
{!> ../../../docs_src/additional_status_codes/tutorial001_an_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="4 25" |
||||
|
{!> ../../../docs_src/additional_status_codes/tutorial001_an_py39.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="4 26" |
||||
|
{!> ../../../docs_src/additional_status_codes/tutorial001_an.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.10+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Faça uso da versão `Annotated` quando possível. |
||||
|
|
||||
|
```Python hl_lines="2 23" |
||||
|
{!> ../../../docs_src/additional_status_codes/tutorial001_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Faça uso da versão `Annotated` quando possível. |
||||
|
|
||||
|
```Python hl_lines="4 25" |
||||
|
{!> ../../../docs_src/additional_status_codes/tutorial001.py!} |
||||
|
``` |
||||
|
|
||||
|
!!! warning "Aviso" |
||||
|
Quando você retorna um `Response` diretamente, como no exemplo acima, ele será retornado diretamente. |
||||
|
|
||||
|
Ele não será serializado com um modelo, etc. |
||||
|
|
||||
|
Garanta que ele tenha toda informação que você deseja, e que os valores sejam um JSON válido (caso você esteja usando `JSONResponse`). |
||||
|
|
||||
|
!!! 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 |
||||
|
|
||||
|
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. |
||||
|
|
||||
|
Mas você pode documentar isso no seu código, utilizando: [Retornos Adicionais](additional-responses.md){.internal-link target=_blank}. |
||||
@ -0,0 +1,138 @@ |
|||||
|
# Dependências avançadas |
||||
|
|
||||
|
## Dependências parametrizadas |
||||
|
|
||||
|
Todas as dependências que vimos até agora são funções ou classes fixas. |
||||
|
|
||||
|
Mas podem ocorrer casos onde você deseja ser capaz de definir parâmetros na dependência, sem ter a necessidade de declarar diversas funções ou classes. |
||||
|
|
||||
|
Vamos imaginar que queremos ter uma dependência que verifica se o parâmetro de consulta `q` possui um valor fixo. |
||||
|
|
||||
|
Porém nós queremos poder parametrizar o conteúdo fixo. |
||||
|
|
||||
|
## Uma instância "chamável" |
||||
|
|
||||
|
Em Python existe uma maneira de fazer com que uma instância de uma classe seja um "chamável". |
||||
|
|
||||
|
Não propriamente a classe (que já é um chamável), mas a instância desta classe. |
||||
|
|
||||
|
Para fazer isso, nós declaramos o método `__call__`: |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="12" |
||||
|
{!> ../../../docs_src/dependencies/tutorial011_an_py39.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="11" |
||||
|
{!> ../../../docs_src/dependencies/tutorial011_an.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Prefira utilizar a versão `Annotated` se possível. |
||||
|
|
||||
|
```Python hl_lines="10" |
||||
|
{!> ../../../docs_src/dependencies/tutorial011.py!} |
||||
|
``` |
||||
|
|
||||
|
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 |
||||
|
|
||||
|
E agora, nós podemos utilizar o `__init__` para declarar os parâmetros da instância que podemos utilizar para "parametrizar" a dependência: |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="9" |
||||
|
{!> ../../../docs_src/dependencies/tutorial011_an_py39.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="8" |
||||
|
{!> ../../../docs_src/dependencies/tutorial011_an.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Prefira utilizar a versão `Annotated` se possível. |
||||
|
|
||||
|
```Python hl_lines="7" |
||||
|
{!> ../../../docs_src/dependencies/tutorial011.py!} |
||||
|
``` |
||||
|
|
||||
|
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 |
||||
|
|
||||
|
Nós poderíamos criar uma instância desta classe com: |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="18" |
||||
|
{!> ../../../docs_src/dependencies/tutorial011_an_py39.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="17" |
||||
|
{!> ../../../docs_src/dependencies/tutorial011_an.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Prefira utilizar a versão `Annotated` se possível. |
||||
|
|
||||
|
```Python hl_lines="16" |
||||
|
{!> ../../../docs_src/dependencies/tutorial011.py!} |
||||
|
``` |
||||
|
|
||||
|
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 |
||||
|
|
||||
|
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. |
||||
|
|
||||
|
E quando a dependência for resolvida, o **FastAPI** chamará este `checker` como: |
||||
|
|
||||
|
```Python |
||||
|
checker(q="somequery") |
||||
|
``` |
||||
|
|
||||
|
...e passar o que quer que isso retorne como valor da dependência em nossa *função de operação de rota* como o parâmetro `fixed_content_included`: |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="22" |
||||
|
{!> ../../../docs_src/dependencies/tutorial011_an_py39.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="21" |
||||
|
{!> ../../../docs_src/dependencies/tutorial011_an.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Prefira utilizar a versão `Annotated` se possível. |
||||
|
|
||||
|
```Python hl_lines="20" |
||||
|
{!> ../../../docs_src/dependencies/tutorial011.py!} |
||||
|
``` |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Tudo isso parece não ser natural. E pode não estar muito claro ou aparentar ser útil ainda. |
||||
|
|
||||
|
Estes exemplos são intencionalmente simples, porém mostram como tudo funciona. |
||||
|
|
||||
|
Nos capítulos sobre segurança, existem funções utilitárias que são implementadas desta maneira. |
||||
|
|
||||
|
Se você entendeu tudo isso, você já sabe como essas funções utilitárias para segurança funcionam por debaixo dos panos. |
||||
@ -0,0 +1,485 @@ |
|||||
|
# Configurações e Variáveis de Ambiente |
||||
|
|
||||
|
Em muitos casos a sua aplicação pode precisar de configurações externas, como chaves secretas, credenciais de banco de dados, credenciais para serviços de email, etc. |
||||
|
|
||||
|
A maioria dessas configurações é variável (podem mudar), como URLs de bancos de dados. E muitas delas podem conter dados sensíveis, como tokens secretos. |
||||
|
|
||||
|
Por isso é comum prover essas configurações como variáveis de ambiente que são utilizidas pela aplicação. |
||||
|
|
||||
|
## Variáveis de Ambiente |
||||
|
|
||||
|
!!! dica |
||||
|
Se você já sabe o que são variáveis de ambiente e como utilizá-las, sinta-se livre para avançar para o próximo tópico. |
||||
|
|
||||
|
Uma <a href="https://pt.wikipedia.org/wiki/Variável_de_ambiente" class="external-link" target="_blank">variável de ambiente</a> (abreviada em inglês para "env var") é uma variável definida fora do código Python, no sistema operacional, e pode ser lida pelo seu código Python (ou por outros programas). |
||||
|
|
||||
|
Você pode criar e utilizar variáveis de ambiente no terminal, sem precisar utilizar Python: |
||||
|
|
||||
|
=== "Linux, macOS, Windows Bash" |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
// Você pode criar uma env var MY_NAME usando |
||||
|
$ export MY_NAME="Wade Wilson" |
||||
|
|
||||
|
// E utilizá-la em outros programas, como |
||||
|
$ echo "Hello $MY_NAME" |
||||
|
|
||||
|
Hello Wade Wilson |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
=== "Windows PowerShell" |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
// Criando env var MY_NAME |
||||
|
$ $Env:MY_NAME = "Wade Wilson" |
||||
|
|
||||
|
// Usando em outros programas, como |
||||
|
$ echo "Hello $Env:MY_NAME" |
||||
|
|
||||
|
Hello Wade Wilson |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
### Lendo variáveis de ambiente com Python |
||||
|
|
||||
|
Você também pode criar variáveis de ambiente fora do Python, no terminal (ou com qualquer outro método), e realizar a leitura delas no Python. |
||||
|
|
||||
|
Por exemplo, você pode definir um arquivo `main.py` com o seguinte código: |
||||
|
|
||||
|
```Python hl_lines="3" |
||||
|
import os |
||||
|
|
||||
|
name = os.getenv("MY_NAME", "World") |
||||
|
print(f"Hello {name} from Python") |
||||
|
``` |
||||
|
|
||||
|
!!! dica |
||||
|
O segundo parâmetro em <a href="https://docs.python.org/3.8/library/os.html#os.getenv" class="external-link" target="_blank">`os.getenv()`</a> é o valor padrão para o retorno. |
||||
|
|
||||
|
Se nenhum valor for informado, `None` é utilizado por padrão, aqui definimos `"World"` como o valor padrão a ser utilizado. |
||||
|
|
||||
|
E depois você pode executar esse arquivo: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
// Aqui ainda não definimos a env var |
||||
|
$ python main.py |
||||
|
|
||||
|
// Por isso obtemos o valor padrão |
||||
|
|
||||
|
Hello World from Python |
||||
|
|
||||
|
// Mas se definirmos uma variável de ambiente primeiro |
||||
|
$ export MY_NAME="Wade Wilson" |
||||
|
|
||||
|
// E executarmos o programa novamente |
||||
|
$ python main.py |
||||
|
|
||||
|
// Agora ele pode ler a variável de ambiente |
||||
|
|
||||
|
Hello Wade Wilson from Python |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
Como variáveis de ambiente podem ser definidas fora do código da aplicação, mas acessadas pela aplicação, e não precisam ser armazenadas (versionadas com `git`) junto dos outros arquivos, é comum utilizá-las para guardar configurações. |
||||
|
|
||||
|
Você também pode criar uma variável de ambiente específica para uma invocação de um programa, que é acessível somente para esse programa, e somente enquanto ele estiver executando. |
||||
|
|
||||
|
Para fazer isso, crie a variável imediatamente antes de iniciar o programa, na mesma linha: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
// Criando uma env var MY_NAME na mesma linha da execução do programa |
||||
|
$ MY_NAME="Wade Wilson" python main.py |
||||
|
|
||||
|
// Agora a aplicação consegue ler a variável de ambiente |
||||
|
|
||||
|
Hello Wade Wilson from Python |
||||
|
|
||||
|
// E a variável deixa de existir após isso |
||||
|
$ python main.py |
||||
|
|
||||
|
Hello World from Python |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
!!! dica |
||||
|
Você pode ler mais sobre isso em: <a href="https://12factor.net/pt_br/config" class="external-link" target="_blank">The Twelve-Factor App: Configurações</a>. |
||||
|
|
||||
|
### Tipagem e Validação |
||||
|
|
||||
|
Essas variáveis de ambiente suportam apenas strings, por serem externas ao Python e por que precisam ser compatíveis com outros programas e o resto do sistema (e até mesmo com outros sistemas operacionais, como Linux, Windows e macOS). |
||||
|
|
||||
|
Isso significa que qualquer valor obtido de uma variável de ambiente em Python terá o tipo `str`, e qualquer conversão para um tipo diferente ou validação deve ser realizada no código. |
||||
|
|
||||
|
## Pydantic `Settings` |
||||
|
|
||||
|
Por sorte, o Pydantic possui uma funcionalidade para lidar com essas configurações vindas de variáveis de ambiente utilizando <a href="https://docs.pydantic.dev/latest/usage/pydantic_settings/" class="external-link" target="_blank">Pydantic: Settings management</a>. |
||||
|
|
||||
|
### Instalando `pydantic-settings` |
||||
|
|
||||
|
Primeiro, instale o pacote `pydantic-settings`: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ pip install pydantic-settings |
||||
|
---> 100% |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
Ele também está incluído no fastapi quando você instala com a opção `all`: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ pip install "fastapi[all]" |
||||
|
---> 100% |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
!!! info |
||||
|
Na v1 do Pydantic ele estava incluído no pacote principal. Agora ele está distribuido como um pacote independente para que você possa optar por instalar ou não caso você não precise dessa funcionalidade. |
||||
|
|
||||
|
### Criando o objeto `Settings` |
||||
|
|
||||
|
Importe a classe `BaseSettings` do Pydantic e crie uma nova subclasse, de forma parecida com um modelo do Pydantic. |
||||
|
|
||||
|
Os atributos da classe são declarados com anotações de tipo, e possíveis valores padrão, da mesma maneira que os modelos do Pydantic. |
||||
|
|
||||
|
Você pode utilizar todas as ferramentas e funcionalidades de validação que são utilizadas nos modelos do Pydantic, como tipos de dados diferentes e validações adicionei com `Field()`. |
||||
|
|
||||
|
=== "Pydantic v2" |
||||
|
|
||||
|
```Python hl_lines="2 5-8 11" |
||||
|
{!> ../../../docs_src/settings/tutorial001.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Pydantic v1" |
||||
|
|
||||
|
!!! Info |
||||
|
Na versão 1 do Pydantic você importaria `BaseSettings` diretamente do módulo `pydantic` em vez do módulo `pydantic_settings`. |
||||
|
|
||||
|
```Python hl_lines="2 5-8 11" |
||||
|
{!> ../../../docs_src/settings/tutorial001_pv1.py!} |
||||
|
``` |
||||
|
|
||||
|
!!! dica |
||||
|
Se você quiser algo pronto para copiar e colar na sua aplicação, não use esse exemplo, mas sim o exemplo abaixo. |
||||
|
|
||||
|
Portanto, quando você cria uma instância da classe `Settings` (nesse caso, o objeto `settings`), o Pydantic lê as variáveis de ambiente sem diferenciar maiúsculas e minúsculas, por isso, uma variável maiúscula `APP_NAME` será usada para o atributo `app_name`. |
||||
|
|
||||
|
Depois ele irá converter e validar os dados. Assim, quando você utilizar aquele objeto `settings`, os dados terão o tipo que você declarou (e.g. `items_per_user` será do tipo `int`). |
||||
|
|
||||
|
### Usando o objeto `settings` |
||||
|
|
||||
|
Depois, Você pode utilizar o novo objeto `settings` na sua aplicação: |
||||
|
|
||||
|
```Python hl_lines="18-20" |
||||
|
{!../../../docs_src/settings/tutorial001.py!} |
||||
|
``` |
||||
|
|
||||
|
### Executando o servidor |
||||
|
|
||||
|
No próximo passo, você pode inicializar o servidor passando as configurações em forma de variáveis de ambiente, por exemplo, você poderia definir `ADMIN_EMAIL` e `APP_NAME` da seguinte forma: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ ADMIN_EMAIL="[email protected]" APP_NAME="ChimichangApp" fastapi run main.py |
||||
|
|
||||
|
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
!!! dica |
||||
|
Para definir múltiplas variáveis de ambiente para um único comando basta separá-las utilizando espaços, e incluir todas elas antes do comando. |
||||
|
|
||||
|
Assim, o atributo `admin_email` seria definido como `"[email protected]"`. |
||||
|
|
||||
|
`app_name` seria `"ChimichangApp"`. |
||||
|
|
||||
|
E `items_per_user` manteria o valor padrão de `50`. |
||||
|
|
||||
|
## Configurações em um módulo separado |
||||
|
|
||||
|
Você também pode incluir essas configurações em um arquivo de um módulo separado como visto em [Bigger Applications - Multiple Files](../tutorial/bigger-applications.md){.internal-link target=\_blank}. |
||||
|
|
||||
|
Por exemplo, você pode adicionar um arquivo `config.py` com: |
||||
|
|
||||
|
```Python |
||||
|
{!../../../docs_src/settings/app01/config.py!} |
||||
|
``` |
||||
|
|
||||
|
E utilizar essa configuração em `main.py`: |
||||
|
|
||||
|
```Python hl_lines="3 11-13" |
||||
|
{!../../../docs_src/settings/app01/main.py!} |
||||
|
``` |
||||
|
|
||||
|
!!! dica |
||||
|
Você também precisa incluir um arquivo `__init__.py` como visto em [Bigger Applications - Multiple Files](../tutorial/bigger-applications.md){.internal-link target=\_blank}. |
||||
|
|
||||
|
## Configurações em uma dependência |
||||
|
|
||||
|
Em certas ocasiões, pode ser útil fornecer essas configurações a partir de uma dependência, em vez de definir um objeto global `settings` que é utilizado em toda a aplicação. |
||||
|
|
||||
|
Isso é especialmente útil durante os testes, já que é bastante simples sobrescrever uma dependência com suas configurações personalizadas. |
||||
|
|
||||
|
### O arquivo de configuração |
||||
|
|
||||
|
Baseando-se no exemplo anterior, seu arquivo `config.py` seria parecido com isso: |
||||
|
|
||||
|
```Python hl_lines="10" |
||||
|
{!../../../docs_src/settings/app02/config.py!} |
||||
|
``` |
||||
|
|
||||
|
Perceba que dessa vez não criamos uma instância padrão `settings = Settings()`. |
||||
|
|
||||
|
### O arquivo principal da aplicação |
||||
|
|
||||
|
Agora criamos a dependência que retorna um novo objeto `config.Settings()`. |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="6 12-13" |
||||
|
{!> ../../../docs_src/settings/app02_an_py39/main.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="6 12-13" |
||||
|
{!> ../../../docs_src/settings/app02_an/main.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! dica |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
```Python hl_lines="5 11-12" |
||||
|
{!> ../../../docs_src/settings/app02/main.py!} |
||||
|
``` |
||||
|
|
||||
|
!!! dica |
||||
|
Vamos discutir sobre `@lru_cache` logo mais. |
||||
|
|
||||
|
Por enquanto, você pode considerar `get_settings()` como uma função normal. |
||||
|
|
||||
|
E então podemos declarar essas configurações como uma dependência na função de operação da rota e utilizar onde for necessário. |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="17 19-21" |
||||
|
{!> ../../../docs_src/settings/app02_an_py39/main.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="17 19-21" |
||||
|
{!> ../../../docs_src/settings/app02_an/main.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! dica |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
```Python hl_lines="16 18-20" |
||||
|
{!> ../../../docs_src/settings/app02/main.py!} |
||||
|
``` |
||||
|
|
||||
|
### Configurações e testes |
||||
|
|
||||
|
Então seria muito fácil fornecer uma configuração diferente durante a execução dos testes sobrescrevendo a dependência de `get_settings`: |
||||
|
|
||||
|
```Python hl_lines="9-10 13 21" |
||||
|
{!../../../docs_src/settings/app02/test_main.py!} |
||||
|
``` |
||||
|
|
||||
|
Na sobrescrita da dependência, definimos um novo valor para `admin_email` quando instanciamos um novo objeto `Settings`, e então retornamos esse novo objeto. |
||||
|
|
||||
|
Após isso, podemos testar se o valor está sendo utilizado. |
||||
|
|
||||
|
## Lendo um arquivo `.env` |
||||
|
|
||||
|
Se você tiver muitas configurações que variem bastante, talvez em ambientes distintos, pode ser útil colocá-las em um arquivo e depois lê-las como se fossem variáveis de ambiente. |
||||
|
|
||||
|
Essa prática é tão comum que possui um nome, essas variáveis de ambiente normalmente são colocadas em um arquivo `.env`, e esse arquivo é chamado de "dotenv". |
||||
|
|
||||
|
!!! dica |
||||
|
Um arquivo iniciando com um ponto final (`.`) é um arquivo oculto em sistemas baseados em Unix, como Linux e MacOS. |
||||
|
|
||||
|
Mas um arquivo dotenv não precisa ter esse nome exato. |
||||
|
|
||||
|
Pydantic suporta a leitura desses tipos de arquivos utilizando uma biblioteca externa. Você pode ler mais em <a href="https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support" class="external-link" target="_blank">Pydantic Settings: Dotenv (.env) support</a>. |
||||
|
|
||||
|
!!! dica |
||||
|
Para que isso funcione você precisa executar `pip install python-dotenv`. |
||||
|
|
||||
|
### O arquivo `.env` |
||||
|
|
||||
|
Você pode definir um arquivo `.env` com o seguinte conteúdo: |
||||
|
|
||||
|
```bash |
||||
|
ADMIN_EMAIL="[email protected]" |
||||
|
APP_NAME="ChimichangApp" |
||||
|
``` |
||||
|
|
||||
|
### Obtendo configurações do `.env` |
||||
|
|
||||
|
E então adicionar o seguinte código em `config.py`: |
||||
|
|
||||
|
=== "Pydantic v2" |
||||
|
|
||||
|
```Python hl_lines="9" |
||||
|
{!> ../../../docs_src/settings/app03_an/config.py!} |
||||
|
``` |
||||
|
|
||||
|
!!! dica |
||||
|
O atributo `model_config` é usado apenas para configuração do Pydantic. Você pode ler mais em <a href="https://docs.pydantic.dev/latest/usage/model_config/" class="external-link" target="_blank">Pydantic Model Config</a>. |
||||
|
|
||||
|
=== "Pydantic v1" |
||||
|
|
||||
|
```Python hl_lines="9-10" |
||||
|
{!> ../../../docs_src/settings/app03_an/config_pv1.py!} |
||||
|
``` |
||||
|
|
||||
|
!!! dica |
||||
|
A classe `Config` é usada apenas para configuração do Pydantic. Você pode ler mais em <a href="https://docs.pydantic.dev/1.10/usage/model_config/" class="external-link" target="_blank">Pydantic Model Config</a>. |
||||
|
|
||||
|
!!! info |
||||
|
Na versão 1 do Pydantic a configuração é realizada por uma classe interna `Config`, na versão 2 do Pydantic isso é feito com o atributo `model_config`. Esse atributo recebe um `dict`, para utilizar o autocomplete e checagem de erros do seu editor de texto você pode importar e utilizar `SettingsConfigDict` para definir esse `dict`. |
||||
|
|
||||
|
Aqui definimos a configuração `env_file` dentro da classe `Settings` do Pydantic, e definimos o valor como o nome do arquivo dotenv que queremos utilizar. |
||||
|
|
||||
|
### Declarando `Settings` apenas uma vez com `lru_cache` |
||||
|
|
||||
|
Ler o conteúdo de um arquivo em disco normalmente é uma operação custosa (lenta), então você provavelmente quer fazer isso apenas um vez e reutilizar o mesmo objeto settings depois, em vez de ler os valores a cada requisição. |
||||
|
|
||||
|
Mas cada vez que fazemos: |
||||
|
|
||||
|
```Python |
||||
|
Settings() |
||||
|
``` |
||||
|
|
||||
|
um novo objeto `Settings` é instanciado, e durante a instanciação, o arquivo `.env` é lido novamente. |
||||
|
|
||||
|
Se a função da dependência fosse apenas: |
||||
|
|
||||
|
```Python |
||||
|
def get_settings(): |
||||
|
return Settings() |
||||
|
``` |
||||
|
|
||||
|
Iriamos criar um novo objeto a cada requisição, e estaríamos lendo o arquivo `.env` a cada requisição. ⚠️ |
||||
|
|
||||
|
Mas como estamos utilizando o decorador `@lru_cache` acima, o objeto `Settings` é criado apenas uma vez, na primeira vez que a função é chamada. ✔️ |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="1 11" |
||||
|
{!> ../../../docs_src/settings/app03_an_py39/main.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="1 11" |
||||
|
{!> ../../../docs_src/settings/app03_an/main.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! dica |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
```Python hl_lines="1 10" |
||||
|
{!> ../../../docs_src/settings/app03/main.py!} |
||||
|
``` |
||||
|
|
||||
|
Dessa forma, todas as chamadas da função `get_settings()` nas dependências das próximas requisições, em vez de executar o código interno de `get_settings()` e instanciar um novo objeto `Settings`, irão retornar o mesmo objeto que foi retornado na primeira chamada, de novo e de novo. |
||||
|
|
||||
|
#### Detalhes Técnicos de `lru_cache` |
||||
|
|
||||
|
`@lru_cache` modifica a função decorada para retornar o mesmo valor que foi retornado na primeira vez, em vez de calculá-lo novamente, executando o código da função toda vez. |
||||
|
|
||||
|
Assim, a função abaixo do decorador é executada uma única vez para cada combinação dos argumentos passados. E os valores retornados para cada combinação de argumentos são sempre reutilizados para cada nova chamada da função com a mesma combinação de argumentos. |
||||
|
|
||||
|
Por exemplo, se você definir uma função: |
||||
|
|
||||
|
```Python |
||||
|
@lru_cache |
||||
|
def say_hi(name: str, salutation: str = "Ms."): |
||||
|
return f"Hello {salutation} {name}" |
||||
|
``` |
||||
|
|
||||
|
Seu programa poderia executar dessa forma: |
||||
|
|
||||
|
```mermaid |
||||
|
sequenceDiagram |
||||
|
|
||||
|
participant code as Código |
||||
|
participant function as say_hi() |
||||
|
participant execute as Executar Função |
||||
|
|
||||
|
rect rgba(0, 255, 0, .1) |
||||
|
code ->> function: say_hi(name="Camila") |
||||
|
function ->> execute: executar código da função |
||||
|
execute ->> code: retornar o resultado |
||||
|
end |
||||
|
|
||||
|
rect rgba(0, 255, 255, .1) |
||||
|
code ->> function: say_hi(name="Camila") |
||||
|
function ->> code: retornar resultado armazenado |
||||
|
end |
||||
|
|
||||
|
rect rgba(0, 255, 0, .1) |
||||
|
code ->> function: say_hi(name="Rick") |
||||
|
function ->> execute: executar código da função |
||||
|
execute ->> code: retornar o resultado |
||||
|
end |
||||
|
|
||||
|
rect rgba(0, 255, 0, .1) |
||||
|
code ->> function: say_hi(name="Rick", salutation="Mr.") |
||||
|
function ->> execute: executar código da função |
||||
|
execute ->> code: retornar o resultado |
||||
|
end |
||||
|
|
||||
|
rect rgba(0, 255, 255, .1) |
||||
|
code ->> function: say_hi(name="Rick") |
||||
|
function ->> code: retornar resultado armazenado |
||||
|
end |
||||
|
|
||||
|
rect rgba(0, 255, 255, .1) |
||||
|
code ->> function: say_hi(name="Camila") |
||||
|
function ->> code: retornar resultado armazenado |
||||
|
end |
||||
|
``` |
||||
|
|
||||
|
No caso da nossa dependência `get_settings()`, a função não recebe nenhum argumento, então ela sempre retorna o mesmo valor. |
||||
|
|
||||
|
Dessa forma, ela se comporta praticamente como uma variável global, mas ao ser utilizada como uma função de uma dependência, pode facilmente ser sobrescrita durante os testes. |
||||
|
|
||||
|
`@lru_cache` é definido no módulo `functools` que faz parte da biblioteca padrão do Python, você pode ler mais sobre esse decorador no link <a href="https://docs.python.org/3/library/functools.html#functools.lru_cache" class="external-link" target="_blank">Python Docs sobre `@lru_cache`</a>. |
||||
|
|
||||
|
## Recapitulando |
||||
|
|
||||
|
Você pode usar o módulo Pydantic Settings para gerenciar as configurações de sua aplicação, utilizando todo o poder dos modelos Pydantic. |
||||
|
|
||||
|
- Utilizar dependências simplifica os testes. |
||||
|
- Você pode utilizar arquivos .env junto das configurações do Pydantic. |
||||
|
- Utilizar o decorador `@lru_cache` evita que o arquivo .env seja lido de novo e de novo para cada requisição, enquanto permite que você sobrescreva durante os testes. |
||||
@ -0,0 +1,11 @@ |
|||||
|
# Como Fazer - Exemplos Práticos |
||||
|
|
||||
|
Aqui você encontrará diferentes exemplos práticos ou tutoriais de "como fazer" para vários tópicos. |
||||
|
|
||||
|
A maioria dessas ideias será mais ou menos **independente**, e na maioria dos casos você só precisará estudá-las se elas se aplicarem diretamente ao **seu projeto**. |
||||
|
|
||||
|
Se algo parecer interessante e útil para o seu projeto, vá em frente e dê uma olhada. Caso contrário, você pode simplesmente ignorá-lo. |
||||
|
|
||||
|
!!! tip |
||||
|
|
||||
|
Se você deseja **aprender FastAPI** de forma estruturada (recomendado), leia capítulo por capítulo [Tutorial - Guia de Usuário](../tutorial/index.md){.internal-link target=_blank} em vez disso. |
||||
@ -0,0 +1,497 @@ |
|||||
|
# Classes como Dependências |
||||
|
|
||||
|
Antes de nos aprofundarmos no sistema de **Injeção de Dependência**, vamos melhorar o exemplo anterior. |
||||
|
|
||||
|
## `dict` do exemplo anterior |
||||
|
|
||||
|
No exemplo anterior, nós retornávamos um `dict` da nossa dependência ("injetável"): |
||||
|
|
||||
|
=== "Python 3.10+" |
||||
|
|
||||
|
```Python hl_lines="9" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_an_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="11" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_an_py39.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="12" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_an.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.10+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
```Python hl_lines="7" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
```Python hl_lines="11" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001.py!} |
||||
|
``` |
||||
|
|
||||
|
Mas assim obtemos um `dict` como valor do parâmetro `commons` na *função de operação de rota*. |
||||
|
|
||||
|
E sabemos que editores de texto não têm como oferecer muitas funcionalidades (como sugestões automáticas) para objetos do tipo `dict`, por que não há como eles saberem o tipo das chaves e dos valores. |
||||
|
|
||||
|
Podemos fazer melhor... |
||||
|
|
||||
|
## O que caracteriza uma dependência |
||||
|
|
||||
|
Até agora você apenas viu dependências declaradas como funções. |
||||
|
|
||||
|
Mas essa não é a única forma de declarar dependências (mesmo que provavelmente seja a mais comum). |
||||
|
|
||||
|
O fator principal para uma dependência é que ela deve ser "chamável" |
||||
|
|
||||
|
Um objeto "chamável" em Python é qualquer coisa que o Python possa "chamar" como uma função |
||||
|
|
||||
|
Então se você tiver um objeto `alguma_coisa` (que pode *não* ser uma função) que você possa "chamar" (executá-lo) dessa maneira: |
||||
|
|
||||
|
```Python |
||||
|
something() |
||||
|
``` |
||||
|
|
||||
|
ou |
||||
|
|
||||
|
```Python |
||||
|
something(some_argument, some_keyword_argument="foo") |
||||
|
``` |
||||
|
|
||||
|
Então esse objeto é um "chamável". |
||||
|
|
||||
|
## Classes como dependências |
||||
|
|
||||
|
Você deve ter percebido que para criar um instância de uma classe em Python, a mesma sintaxe é utilizada. |
||||
|
|
||||
|
Por exemplo: |
||||
|
|
||||
|
```Python |
||||
|
class Cat: |
||||
|
def __init__(self, name: str): |
||||
|
self.name = name |
||||
|
|
||||
|
|
||||
|
fluffy = Cat(name="Mr Fluffy") |
||||
|
``` |
||||
|
|
||||
|
Nesse caso, `fluffy` é uma instância da classe `Cat`. |
||||
|
|
||||
|
E para criar `fluffy`, você está "chamando" `Cat`. |
||||
|
|
||||
|
Então, uma classe Python também é "chamável". |
||||
|
|
||||
|
Então, no **FastAPI**, você pode utilizar uma classe Python como uma dependência. |
||||
|
|
||||
|
O que o FastAPI realmente verifica, é se a dependência é algo chamável (função, classe, ou outra coisa) e os parâmetros que foram definidos. |
||||
|
|
||||
|
Se você passar algo "chamável" como uma dependência do **FastAPI**, o framework irá analisar os parâmetros desse "chamável" e processá-los da mesma forma que os parâmetros de uma *função de operação de rota*. Incluindo as sub-dependências. |
||||
|
|
||||
|
Isso também se aplica a objetos chamáveis que não recebem nenhum parâmetro. Da mesma forma que uma *função de operação de rota* sem parâmetros. |
||||
|
|
||||
|
Então, podemos mudar o "injetável" na dependência `common_parameters` acima para a classe `CommonQueryParams`: |
||||
|
|
||||
|
=== "Python 3.10+" |
||||
|
|
||||
|
```Python hl_lines="11-15" |
||||
|
{!> ../../../docs_src/dependencies/tutorial002_an_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="11-15" |
||||
|
{!> ../../../docs_src/dependencies/tutorial002_an_py39.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="12-16" |
||||
|
{!> ../../../docs_src/dependencies/tutorial002_an.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.10+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
|
||||
|
```Python hl_lines="9-13" |
||||
|
{!> ../../../docs_src/dependencies/tutorial002_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
|
||||
|
```Python hl_lines="11-15" |
||||
|
{!> ../../../docs_src/dependencies/tutorial002.py!} |
||||
|
``` |
||||
|
|
||||
|
Observe o método `__init__` usado para criar uma instância da classe: |
||||
|
|
||||
|
=== "Python 3.10+" |
||||
|
|
||||
|
```Python hl_lines="12" |
||||
|
{!> ../../../docs_src/dependencies/tutorial002_an_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="12" |
||||
|
{!> ../../../docs_src/dependencies/tutorial002_an_py39.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="13" |
||||
|
{!> ../../../docs_src/dependencies/tutorial002_an.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.10+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
|
||||
|
```Python hl_lines="10" |
||||
|
{!> ../../../docs_src/dependencies/tutorial002_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
|
||||
|
```Python hl_lines="12" |
||||
|
{!> ../../../docs_src/dependencies/tutorial002.py!} |
||||
|
``` |
||||
|
|
||||
|
...ele possui os mesmos parâmetros que nosso `common_parameters` anterior: |
||||
|
|
||||
|
=== "Python 3.10+" |
||||
|
|
||||
|
```Python hl_lines="8" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_an_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="9" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_an_py39.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="10" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_an.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.10+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
|
||||
|
```Python hl_lines="6" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
|
||||
|
```Python hl_lines="9" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001.py!} |
||||
|
``` |
||||
|
|
||||
|
Esses parâmetros são utilizados pelo **FastAPI** para "definir" a dependência. |
||||
|
|
||||
|
Em ambos os casos teremos: |
||||
|
|
||||
|
* Um parâmetro de consulta `q` opcional do tipo `str`. |
||||
|
* Um parâmetro de consulta `skip` do tipo `int`, com valor padrão `0`. |
||||
|
* Um parâmetro de consulta `limit` do tipo `int`, com valor padrão `100`. |
||||
|
|
||||
|
Os dados serão convertidos, validados, documentados no esquema da OpenAPI e etc nos dois casos. |
||||
|
|
||||
|
## Utilizando |
||||
|
|
||||
|
Agora você pode declarar sua dependência utilizando essa classe. |
||||
|
|
||||
|
=== "Python 3.10+" |
||||
|
|
||||
|
```Python hl_lines="19" |
||||
|
{!> ../../../docs_src/dependencies/tutorial002_an_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="19" |
||||
|
{!> ../../../docs_src/dependencies/tutorial002_an_py39.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="20" |
||||
|
{!> ../../../docs_src/dependencies/tutorial002_an.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.10+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
|
||||
|
```Python hl_lines="17" |
||||
|
{!> ../../../docs_src/dependencies/tutorial002_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
|
||||
|
```Python hl_lines="19" |
||||
|
{!> ../../../docs_src/dependencies/tutorial002.py!} |
||||
|
``` |
||||
|
|
||||
|
O **FastAPI** chama a classe `CommonQueryParams`. Isso cria uma "instância" dessa classe e é a instância que será passada para o parâmetro `commons` na sua função. |
||||
|
|
||||
|
## Anotações de Tipo vs `Depends` |
||||
|
|
||||
|
Perceba como escrevemos `CommonQueryParams` duas vezes no código abaixo: |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python |
||||
|
commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
|
||||
|
```Python |
||||
|
commons: CommonQueryParams = Depends(CommonQueryParams) |
||||
|
``` |
||||
|
|
||||
|
O último `CommonQueryParams`, em: |
||||
|
|
||||
|
```Python |
||||
|
... Depends(CommonQueryParams) |
||||
|
``` |
||||
|
|
||||
|
...é o que o **FastAPI** irá realmente usar para saber qual é a dependência. |
||||
|
|
||||
|
É a partir dele que o FastAPI irá extrair os parâmetros passados e será o que o FastAPI irá realmente chamar. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
Nesse caso, o primeiro `CommonQueryParams`, em: |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python |
||||
|
commons: Annotated[CommonQueryParams, ... |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
|
||||
|
```Python |
||||
|
commons: CommonQueryParams ... |
||||
|
``` |
||||
|
|
||||
|
...não tem nenhum signficado especial para o **FastAPI**. O FastAPI não irá utilizá-lo para conversão dos dados, validação, etc (já que ele utiliza `Depends(CommonQueryParams)` para isso). |
||||
|
|
||||
|
Na verdade você poderia escrever apenas: |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python |
||||
|
commons: Annotated[Any, Depends(CommonQueryParams)] |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
|
||||
|
```Python |
||||
|
commons = Depends(CommonQueryParams) |
||||
|
``` |
||||
|
|
||||
|
...como em: |
||||
|
|
||||
|
=== "Python 3.10+" |
||||
|
|
||||
|
```Python hl_lines="19" |
||||
|
{!> ../../../docs_src/dependencies/tutorial003_an_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="19" |
||||
|
{!> ../../../docs_src/dependencies/tutorial003_an_py39.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="20" |
||||
|
{!> ../../../docs_src/dependencies/tutorial003_an.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.10+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
|
||||
|
```Python hl_lines="17" |
||||
|
{!> ../../../docs_src/dependencies/tutorial003_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
|
||||
|
```Python hl_lines="19" |
||||
|
{!> ../../../docs_src/dependencies/tutorial003.py!} |
||||
|
``` |
||||
|
|
||||
|
Mas declarar o tipo é encorajado por que é a forma que o seu editor de texto sabe o que será passado como valor do parâmetro `commons`. |
||||
|
|
||||
|
<img src="/img/tutorial/dependencies/image02.png"> |
||||
|
|
||||
|
## Pegando um Atalho |
||||
|
|
||||
|
Mas você pode ver que temos uma repetição do código neste exemplo, escrevendo `CommonQueryParams` duas vezes: |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python |
||||
|
commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
```Python |
||||
|
commons: CommonQueryParams = Depends(CommonQueryParams) |
||||
|
``` |
||||
|
|
||||
|
O **FastAPI** nos fornece um atalho para esses casos, onde a dependência é *especificamente* uma classe que o **FastAPI** irá "chamar" para criar uma instância da própria classe. |
||||
|
|
||||
|
Para esses casos específicos, você pode fazer o seguinte: |
||||
|
|
||||
|
Em vez de escrever: |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python |
||||
|
commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)] |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
```Python |
||||
|
commons: CommonQueryParams = Depends(CommonQueryParams) |
||||
|
``` |
||||
|
|
||||
|
...escreva: |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python |
||||
|
commons: Annotated[CommonQueryParams, Depends()] |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8 non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
|
||||
|
```Python |
||||
|
commons: CommonQueryParams = Depends() |
||||
|
``` |
||||
|
|
||||
|
Você declara a dependência como o tipo do parâmetro, e utiliza `Depends()` sem nenhum parâmetro, em vez de ter que escrever a classe *novamente* dentro de `Depends(CommonQueryParams)`. |
||||
|
|
||||
|
O mesmo exemplo ficaria então dessa forma: |
||||
|
|
||||
|
=== "Python 3.10+" |
||||
|
|
||||
|
```Python hl_lines="19" |
||||
|
{!> ../../../docs_src/dependencies/tutorial004_an_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="19" |
||||
|
{!> ../../../docs_src/dependencies/tutorial004_an_py39.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="20" |
||||
|
{!> ../../../docs_src/dependencies/tutorial004_an.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.10+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
|
||||
|
```Python hl_lines="17" |
||||
|
{!> ../../../docs_src/dependencies/tutorial004_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
|
||||
|
```Python hl_lines="19" |
||||
|
{!> ../../../docs_src/dependencies/tutorial004.py!} |
||||
|
``` |
||||
|
|
||||
|
...e o **FastAPI** saberá o que fazer. |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Se isso parece mais confuso do que útil, não utilize, você não *precisa* disso. |
||||
|
|
||||
|
É apenas um atalho. Por que o **FastAPI** se preocupa em ajudar a minimizar a repetição de código. |
||||
@ -0,0 +1,353 @@ |
|||||
|
# Dependências |
||||
|
|
||||
|
O **FastAPI** possui um poderoso, mas intuitivo sistema de **<abbr title="também conhecidos como, recursos, provedores, serviços, injetáveis">Injeção de Dependência</abbr>**. |
||||
|
|
||||
|
Esse sistema foi pensado para ser fácil de usar, e permitir que qualquer desenvolvedor possa integrar facilmente outros componentes ao **FastAPI**. |
||||
|
|
||||
|
## O que é "Injeção de Dependência" |
||||
|
|
||||
|
**"Injeção de Dependência"** no mundo da programação significa, que existe uma maneira de declarar no seu código (nesse caso, suas *funções de operação de rota*) para declarar as coisas que ele precisa para funcionar e que serão utilizadas: "dependências". |
||||
|
|
||||
|
Então, esse sistema (nesse caso o **FastAPI**) se encarrega de fazer o que for preciso para fornecer essas dependências para o código ("injetando" as dependências). |
||||
|
|
||||
|
Isso é bastante útil quando você precisa: |
||||
|
|
||||
|
* Definir uma lógica compartilhada (mesmo formato de código repetidamente). |
||||
|
* Compartilhar conexões com banco de dados. |
||||
|
* Aplicar regras de segurança, autenticação, papéis de usuários, etc. |
||||
|
* E muitas outras coisas... |
||||
|
|
||||
|
Tudo isso, enquanto minimizamos a repetição de código. |
||||
|
|
||||
|
## Primeiros passos |
||||
|
|
||||
|
Vamos ver um exemplo simples. Tão simples que não será muito útil, por enquanto. |
||||
|
|
||||
|
Mas dessa forma podemos focar em como o sistema de **Injeção de Dependência** funciona. |
||||
|
|
||||
|
### Criando uma dependência, ou "injetável" |
||||
|
|
||||
|
Primeiro vamos focar na dependência. |
||||
|
|
||||
|
Ela é apenas uma função que pode receber os mesmos parâmetros de uma *função de operação de rota*: |
||||
|
|
||||
|
=== "Python 3.10+" |
||||
|
|
||||
|
```Python hl_lines="8-9" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_an_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="8-11" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_an_py39.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="9-12" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_an.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.10+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
```Python hl_lines="6-7" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
```Python hl_lines="8-11" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001.py!} |
||||
|
``` |
||||
|
|
||||
|
E pronto. |
||||
|
|
||||
|
**2 linhas**. |
||||
|
|
||||
|
E com a mesma forma e estrutura de todas as suas *funções de operação de rota*. |
||||
|
|
||||
|
Você pode pensar nela como uma *função de operação de rota* sem o "decorador" (sem a linha `@app.get("/some-path")`). |
||||
|
|
||||
|
E com qualquer retorno que você desejar. |
||||
|
|
||||
|
Neste caso, a dependência espera por: |
||||
|
|
||||
|
* Um parâmetro de consulta opcional `q` do tipo `str`. |
||||
|
* Um parâmetro de consulta opcional `skip` do tipo `int`, e igual a `0` por padrão. |
||||
|
* Um parâmetro de consulta opcional `limit` do tipo `int`, e igual a `100` por padrão. |
||||
|
|
||||
|
E então retorna um `dict` contendo esses valores. |
||||
|
|
||||
|
!!! info "Informação" |
||||
|
FastAPI passou a suportar a notação `Annotated` (e começou a recomendá-la) na versão 0.95.0. |
||||
|
|
||||
|
Se você utiliza uma versão anterior, ocorrerão erros ao tentar utilizar `Annotated`. |
||||
|
|
||||
|
Certifique-se de [Atualizar a versão do FastAPI](../../deployment/versions.md#atualizando-as-versoes-do-fastapi){.internal-link target=_blank} para pelo menos 0.95.1 antes de usar `Annotated`. |
||||
|
|
||||
|
### Importando `Depends` |
||||
|
|
||||
|
=== "Python 3.10+" |
||||
|
|
||||
|
```Python hl_lines="3" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_an_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="3" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_an_py39.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="3" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_an.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.10+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
```Python hl_lines="1" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
```Python hl_lines="3" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001.py!} |
||||
|
``` |
||||
|
|
||||
|
### Declarando a dependência, no "dependente" |
||||
|
|
||||
|
Da mesma forma que você utiliza `Body`, `Query`, etc. Como parâmetros de sua *função de operação de rota*, utilize `Depends` com um novo parâmetro: |
||||
|
|
||||
|
=== "Python 3.10+" |
||||
|
|
||||
|
```Python hl_lines="13 18" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_an_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="15 20" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_an_py39.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="16 21" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_an.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.10+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
```Python hl_lines="11 16" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+ non-Annotated" |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Utilize a versão com `Annotated` se possível. |
||||
|
|
||||
|
```Python hl_lines="15 20" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001.py!} |
||||
|
``` |
||||
|
|
||||
|
Ainda que `Depends` seja utilizado nos parâmetros da função da mesma forma que `Body`, `Query`, etc, `Depends` funciona de uma forma um pouco diferente. |
||||
|
|
||||
|
Você fornece um único parâmetro para `Depends`. |
||||
|
|
||||
|
Esse parâmetro deve ser algo como uma função. |
||||
|
|
||||
|
Você **não chama a função** diretamente (não adicione os parênteses no final), apenas a passe como parâmetro de `Depends()`. |
||||
|
|
||||
|
E essa função vai receber os parâmetros da mesma forma que uma *função de operação de rota*. |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Você verá quais outras "coisas", além de funções, podem ser usadas como dependências no próximo capítulo. |
||||
|
|
||||
|
Sempre que uma nova requisição for realizada, o **FastAPI** se encarrega de: |
||||
|
|
||||
|
* Chamar sua dependência ("injetável") com os parâmetros corretos. |
||||
|
* Obter o resultado da função. |
||||
|
* Atribuir esse resultado para o parâmetro em sua *função de operação de rota*. |
||||
|
|
||||
|
```mermaid |
||||
|
graph TB |
||||
|
|
||||
|
common_parameters(["common_parameters"]) |
||||
|
read_items["/items/"] |
||||
|
read_users["/users/"] |
||||
|
|
||||
|
common_parameters --> read_items |
||||
|
common_parameters --> read_users |
||||
|
``` |
||||
|
|
||||
|
Assim, você escreve um código compartilhado apenas uma vez e o **FastAPI** se encarrega de chamá-lo em suas *operações de rota*. |
||||
|
|
||||
|
!!! check "Checando" |
||||
|
Perceba que você não precisa criar uma classe especial e enviar a dependência para algum outro lugar em que o **FastAPI** a "registre" ou realize qualquer operação similar. |
||||
|
|
||||
|
Você apenas envia para `Depends` e o **FastAPI** sabe como fazer o resto. |
||||
|
|
||||
|
## Compartilhando dependências `Annotated` |
||||
|
|
||||
|
Nos exemplos acima, você pode ver que existe uma pequena **duplicação de código**. |
||||
|
|
||||
|
Quando você precisa utilizar a dependência `common_parameters()`, você precisa escrever o parâmetro inteiro com uma anotação de tipo e `Depends()`: |
||||
|
|
||||
|
```Python |
||||
|
commons: Annotated[dict, Depends(common_parameters)] |
||||
|
``` |
||||
|
|
||||
|
Mas como estamos utilizando `Annotated`, podemos guardar esse valor `Annotated` em uma variável e utilizá-la em múltiplos locais: |
||||
|
|
||||
|
=== "Python 3.10+" |
||||
|
|
||||
|
```Python hl_lines="12 16 21" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_02_an_py310.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.9+" |
||||
|
|
||||
|
```Python hl_lines="14 18 23" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_02_an_py39.py!} |
||||
|
``` |
||||
|
|
||||
|
=== "Python 3.8+" |
||||
|
|
||||
|
```Python hl_lines="15 19 24" |
||||
|
{!> ../../../docs_src/dependencies/tutorial001_02_an.py!} |
||||
|
``` |
||||
|
|
||||
|
!!! tip "Dica" |
||||
|
Isso é apenas Python padrão, essa funcionalidade é chamada de "type alias", e na verdade não é específica ao **FastAPI**. |
||||
|
|
||||
|
Mas como o **FastAPI** se baseia em convenções do Python, incluindo `Annotated`, você pode incluir esse truque no seu código. 😎 |
||||
|
|
||||
|
As dependências continuarão funcionando como esperado, e a **melhor parte** é que a **informação sobre o tipo é preservada**, o que signfica que seu editor de texto ainda irá incluir **preenchimento automático**, **visualização de erros**, etc. O mesmo vale para ferramentas como `mypy`. |
||||
|
|
||||
|
Isso é especialmente útil para uma **base de código grande** onde **as mesmas dependências** são utilizadas repetidamente em **muitas *operações de rota***. |
||||
|
|
||||
|
## `Async` ou não, eis a questão |
||||
|
|
||||
|
Como as dependências também serão chamadas pelo **FastAPI** (da mesma forma que *funções de operação de rota*), as mesmas regras se aplicam ao definir suas funções. |
||||
|
|
||||
|
Você pode utilizar `async def` ou apenas `def`. |
||||
|
|
||||
|
E você pode declarar dependências utilizando `async def` dentro de *funções de operação de rota* definidas com `def`, ou declarar dependências com `def` e utilizar dentro de *funções de operação de rota* definidas com `async def`, etc. |
||||
|
|
||||
|
Não faz diferença. O **FastAPI** sabe o que fazer. |
||||
|
|
||||
|
!!! note "Nota" |
||||
|
Caso você não conheça, veja em [Async: *"Com Pressa?"*](../../async.md#com-pressa){.internal-link target=_blank} a sessão acerca de `async` e `await` na documentação. |
||||
|
|
||||
|
## Integrando com OpenAPI |
||||
|
|
||||
|
Todas as declarações de requisições, validações e requisitos para suas dependências (e sub-dependências) serão integradas em um mesmo esquema OpenAPI. |
||||
|
|
||||
|
Então, a documentação interativa também terá toda a informação sobre essas dependências: |
||||
|
|
||||
|
<img src="/img/tutorial/dependencies/image01.png"> |
||||
|
|
||||
|
## Caso de Uso Simples |
||||
|
|
||||
|
Se você parar para ver, *funções de operação de rota* são declaradas para serem usadas sempre que uma *rota* e uma *operação* se encaixam, e então o **FastAPI** se encarrega de chamar a função correspondente com os argumentos corretos, extraindo os dados da requisição. |
||||
|
|
||||
|
Na verdade, todos (ou a maioria) dos frameworks web funcionam da mesma forma. |
||||
|
|
||||
|
Você nunca chama essas funções diretamente. Elas são chamadas pelo framework utilizado (nesse caso, **FastAPI**). |
||||
|
|
||||
|
Com o Sistema de Injeção de Dependência, você também pode informar ao **FastAPI** que sua *função de operação de rota* também "depende" em algo a mais que deve ser executado antes de sua *função de operação de rota*, e o **FastAPI** se encarrega de executar e "injetar" os resultados. |
||||
|
|
||||
|
Outros termos comuns para essa mesma ideia de "injeção de dependência" são: |
||||
|
|
||||
|
* recursos |
||||
|
* provedores |
||||
|
* serviços |
||||
|
* injetáveis |
||||
|
* componentes |
||||
|
|
||||
|
## Plug-ins em **FastAPI** |
||||
|
|
||||
|
Integrações e "plug-ins" podem ser construídos com o sistema de **Injeção de Dependência**. Mas na verdade, **não há necessidade de criar "plug-ins"**, já que utilizando dependências é possível declarar um número infinito de integrações e interações que se tornam disponíveis para as suas *funções de operação de rota*. |
||||
|
|
||||
|
E as dependências pode ser criadas de uma forma bastante simples e intuitiva que permite que você importe apenas os pacotes Python que forem necessários, e integrá-los com as funções de sua API em algumas linhas de código, *literalmente*. |
||||
|
|
||||
|
Você verá exemplos disso nos próximos capítulos, acerca de bancos de dados relacionais e NoSQL, segurança, etc. |
||||
|
|
||||
|
## Compatibilidade do **FastAPI** |
||||
|
|
||||
|
A simplicidade do sistema de injeção de dependência do **FastAPI** faz ele compatível com: |
||||
|
|
||||
|
* todos os bancos de dados relacionais |
||||
|
* bancos de dados NoSQL |
||||
|
* pacotes externos |
||||
|
* APIs externas |
||||
|
* sistemas de autenticação e autorização |
||||
|
* istemas de monitoramento de uso para APIs |
||||
|
* sistemas de injeção de dados de resposta |
||||
|
* etc. |
||||
|
|
||||
|
## Simples e Poderoso |
||||
|
|
||||
|
Mesmo que o sistema hierárquico de injeção de dependência seja simples de definir e utilizar, ele ainda é bastante poderoso. |
||||
|
|
||||
|
Você pode definir dependências que por sua vez definem suas próprias dependências. |
||||
|
|
||||
|
No fim, uma árvore hierárquica de dependências é criadas, e o sistema de **Injeção de Dependência** toma conta de resolver todas essas dependências (e as sub-dependências delas) para você, e provê (injeta) os resultados em cada passo. |
||||
|
|
||||
|
Por exemplo, vamos supor que você possua 4 endpoints na sua API (*operações de rota*): |
||||
|
|
||||
|
* `/items/public/` |
||||
|
* `/items/private/` |
||||
|
* `/users/{user_id}/activate` |
||||
|
* `/items/pro/` |
||||
|
|
||||
|
Você poderia adicionar diferentes requisitos de permissão para cada um deles utilizando apenas dependências e sub-dependências: |
||||
|
|
||||
|
```mermaid |
||||
|
graph TB |
||||
|
|
||||
|
current_user(["current_user"]) |
||||
|
active_user(["active_user"]) |
||||
|
admin_user(["admin_user"]) |
||||
|
paying_user(["paying_user"]) |
||||
|
|
||||
|
public["/items/public/"] |
||||
|
private["/items/private/"] |
||||
|
activate_user["/users/{user_id}/activate"] |
||||
|
pro_items["/items/pro/"] |
||||
|
|
||||
|
current_user --> active_user |
||||
|
active_user --> admin_user |
||||
|
active_user --> paying_user |
||||
|
|
||||
|
current_user --> public |
||||
|
active_user --> private |
||||
|
admin_user --> activate_user |
||||
|
paying_user --> pro_items |
||||
|
``` |
||||
|
|
||||
|
## Integração com **OpenAPI** |
||||
|
|
||||
|
Todas essas dependências, ao declarar os requisitos para suas *operações de rota*, também adicionam parâmetros, validações, etc. |
||||
|
|
||||
|
O **FastAPI** se encarrega de adicionar tudo isso ao esquema OpenAPI, para que seja mostrado nos sistemas de documentação interativa. |
||||
Loading…
Reference in new issue