Introdução aos tipos Python¶

Python 3.6 + tem suporte para "type hints" opcionais.

Esses "type hints" são uma nova sintaxe (desde Python 3.6+) que permite declarar o tipo de uma variável.

Ao declarar tipos para suas variáveis, editores e ferramentas podem oferecer um melhor suporte.

Este é apenas um tutorial rápido / atualização sobre type hints Python. Ele cobre apenas o mínimo necessário para usá-los com o FastAPI ... que é realmente muito pouco.

O FastAPI é baseado nesses type hints, eles oferecem muitas vantagens e benefícios.

Mas mesmo que você nunca use o FastAPI, você se beneficiaria de aprender um pouco sobre eles.

Nota

Se você é um especialista em Python e já sabe tudo sobre type hints, pule para o próximo capítulo.

Motivação¶

Vamos começar com um exemplo simples:

def get_full_name(first_name, last_name):
    full_name = first_name.title() + " " + last_name.title()
    return full_name


print(get_full_name("john", "doe"))

A chamada deste programa gera:

John Doe

A função faz o seguinte:

Pega um first_name e last_name.
Converte a primeira letra de cada uma em maiúsculas com title ().
Concatena com um espaço no meio.

def get_full_name(first_name, last_name):
    full_name = first_name.title() + " " + last_name.title()
    return full_name


print(get_full_name("john", "doe"))

Edite-o¶

É um programa muito simples.

Mas agora imagine que você estava escrevendo do zero.

Em algum momento você teria iniciado a definição da função, já tinha os parâmetros prontos ...

Mas então você deve chamar "esse método que converte a primeira letra em maiúscula".

Era upper? Era uppercase? first_uppercase? capitalize?

Em seguida, tente com o velho amigo do programador, o preenchimento automático do editor.

Você digita o primeiro parâmetro da função, first_name, depois um ponto (.) e, em seguida, pressiona Ctrl + Space para acionar a conclusão.

Mas, infelizmente, você não obtém nada útil:

Adicionar tipos¶

Vamos modificar uma única linha da versão anterior.

Vamos mudar exatamente esse fragmento, os parâmetros da função, de:

    first_name, last_name

para:

    first_name: str, last_name: str

É isso aí.

Esses são os "type hints":

def get_full_name(first_name: str, last_name: str):
    full_name = first_name.title() + " " + last_name.title()
    return full_name


print(get_full_name("john", "doe"))

Isso não é o mesmo que declarar valores padrão como seria com:

    first_name="john", last_name="doe"

É uma coisa diferente.

Estamos usando dois pontos (:), não é igual a (=).

E adicionar type hints normalmente não muda o que acontece do que aconteceria sem elas.

Mas agora, imagine que você está novamente no meio da criação dessa função, mas com type hints.

No mesmo ponto, você tenta acionar o preenchimento automático com o Ctrl Space e vê:

Com isso, você pode rolar, vendo as opções, até encontrar o que "toca uma campainha":

Mais motivação¶

Marque esta função, ela já possui type hints:

def get_name_with_age(name: str, age: int):
    name_with_age = name + " is this old: " + age
    return name_with_age

Como o editor conhece os tipos de variáveis, você não apenas obtém a conclusão, mas também as verificações de erro:

Agora você sabe que precisa corrigí-lo, converta age em uma string com str (age):

def get_name_with_age(name: str, age: int):
    name_with_age = name + " is this old: " + str(age)
    return name_with_age

Tipos de declaração¶

Você acabou de ver o local principal para declarar type hints. Como parâmetros de função.

Este também é o principal local em que você os usaria com o FastAPI.

Tipos simples¶

Você pode declarar todos os tipos padrão de Python, não apenas str.

Você pode usar, por exemplo:

int
float
bool
bytes

def get_items(item_a: str, item_b: int, item_c: float, item_d: bool, item_e: bytes):
    return item_a, item_b, item_c, item_d, item_d, item_e

Tipos genéricos com parâmetros de tipo¶

Existem algumas estruturas de dados que podem conter outros valores, como dict, list, set e tuple. E os valores internos também podem ter seu próprio tipo.

Para declarar esses tipos e os tipos internos, você pode usar o módulo Python padrão typing.

Ele existe especificamente para suportar esses type hints.

`List`¶

Por exemplo, vamos definir uma variável para ser uma lista de str.

Em typing, importe List (com um L maiúsculo):

from typing import List


def process_items(items: List[str]):
    for item in items:
        print(item)

Declare a variável com a mesma sintaxe de dois pontos (:).

Como o tipo, coloque a List.

Como a lista é um tipo que contém alguns tipos internos, você os coloca entre colchetes:

from typing import List


def process_items(items: List[str]):
    for item in items:
        print(item)

Dica

Esses tipos internos entre colchetes são chamados de "parâmetros de tipo".

Nesse caso, str é o parâmetro de tipo passado para List.

Isso significa que: "a variável items é uma list, e cada um dos itens desta lista é uma str".

Ao fazer isso, seu editor pode fornecer suporte mesmo durante o processamento de itens da lista:

Sem tipos, isso é quase impossível de alcançar.

Observe que a variável item é um dos elementos da lista items.

E, ainda assim, o editor sabe que é um str e fornece suporte para isso.

`Tuple` e `Set`¶

Você faria o mesmo para declarar tuples e sets:

from typing import Set, Tuple


def process_items(items_t: Tuple[int, int, str], items_s: Set[bytes]):
    return items_t, items_s

Isso significa que:

A variável items_t é uma tuple com 3 itens, um int, outro int e uma str.
A variável items_s é um set, e cada um de seus itens é do tipo bytes.

`Dict`¶

Para definir um dict, você passa 2 parâmetros de tipo, separados por vírgulas.

O primeiro parâmetro de tipo é para as chaves do dict.

O segundo parâmetro de tipo é para os valores do dict:

from typing import Dict


def process_items(prices: Dict[str, float]):
    for item_name, item_price in prices.items():
        print(item_name)
        print(item_price)

Isso significa que:

A variável prices é um dict`:
- As chaves deste dict são do tipo str (digamos, o nome de cada item).
- Os valores deste dict são do tipo float (digamos, o preço de cada item).

`Opcional`¶

Você também pode usar o Opcional para declarar que uma variável tem um tipo, como str, mas que é "opcional", o que significa que também pode ser None:

from typing import Optional


def say_hi(name: Optional[str] = None):
    if name is not None:
        print(f"Hey {name}!")
    else:
        print("Hello World")

O uso de Opcional [str] em vez de apenas str permitirá que o editor o ajude a detectar erros, onde você pode estar assumindo que um valor é sempre um str, quando na verdade também pode ser None.

Tipos genéricos¶

Esses tipos que usam parâmetros de tipo entre colchetes, como:

List
Tuple
Set
Dict
Opcional
...e outros.

são chamados tipos genéricos ou genéricos.

Classes como tipos¶

Você também pode declarar uma classe como o tipo de uma variável.

Digamos que você tenha uma classe Person, com um nome:

class Person:
    def __init__(self, name: str):
        self.name = name


def get_person_name(one_person: Person):
    return one_person.name

Então você pode declarar que uma variável é do tipo Person:

class Person:
    def __init__(self, name: str):
        self.name = name


def get_person_name(one_person: Person):
    return one_person.name

E então, novamente, você recebe todo o suporte do editor:

Modelos Pydantic¶

Pydantic é uma biblioteca Python para executar a validação de dados.

Você declara a "forma" dos dados como classes com atributos.

E cada atributo tem um tipo.

Em seguida, você cria uma instância dessa classe com alguns valores e ela os validará, os converterá para o tipo apropriado (se for esse o caso) e fornecerá um objeto com todos os dados.

E você recebe todo o suporte do editor com esse objeto resultante.

Retirado dos documentos oficiais dos Pydantic:

from datetime import datetime
from typing import List, Union

from pydantic import BaseModel


class User(BaseModel):
    id: int
    name: str = "John Doe"
    signup_ts: Union[datetime, None] = None
    friends: List[int] = []


external_data = {
    "id": "123",
    "signup_ts": "2017-06-01 12:22",
    "friends": [1, "2", b"3"],
}
user = User(**external_data)
print(user)
# > User id=123 name='John Doe' signup_ts=datetime.datetime(2017, 6, 1, 12, 22) friends=[1, 2, 3]
print(user.id)
# > 123

Informação

Para saber mais sobre o Pydantic, verifique seus documentos .

FastAPI é todo baseado em Pydantic.

Você verá muito mais disso na prática no Tutorial - Guia do usuário.

Type hints em FastAPI¶

O FastAPI aproveita esses type hints para fazer várias coisas.

Com o FastAPI, você declara parâmetros com type hints e obtém:

Suporte ao editor.
Verificações de tipo.

... e FastAPI usa as mesmas declarações para:

Definir requisitos: dos parâmetros do caminho da solicitação, parâmetros da consulta, cabeçalhos, corpos, dependências, etc.
Converter dados: da solicitação para o tipo necessário.
Validar dados: provenientes de cada solicitação:
- A geração de erros automáticos retornou ao cliente quando os dados são inválidos.
Documente a API usando OpenAPI:
- que é usado pelas interfaces de usuário da documentação interativa automática.

Tudo isso pode parecer abstrato. Não se preocupe. Você verá tudo isso em ação no Tutorial - Guia do usuário.

O importante é que, usando tipos padrão de Python, em um único local (em vez de adicionar mais classes, decoradores, etc.), o FastAPI fará muito trabalho para você.