Привет, Хаброжители!

FastAPI — относительно новый, но надежный фреймворк с чистым дизайном, использующий преимущества актуальных возможностей Python. Как следует из названия, FastAPI отличается высоким быстродействием и способен конкурировать в этом с аналогичными фреймворками на таких языках, как Golang. Эта практическая книга расскажет разработчикам, знакомым с Python, как FastAPI позволяет достичь большего за меньшее время и с меньшим количеством кода.

Билл Любанович рассказывает о тонкостях разработки с применением FastAPI и предлагает множество рекомендаций по таким темам, как формы, доступ к базам данных, графика, карты и многое другое, что поможет освоить основы и даже пойти дальше. Кроме того, вы познакомитесь с RESTful API, приемами валидации данных, авторизации и повышения производительности. Благодаря сходству с такими фреймворками, как Flask и Django, вы легко начнете работу с FastAPI.

Pydantic, подсказки типов и обзор моделей

Обзор

FastAPI во многом опирается на пакет Python с названием Pydantic. Для определения структур данных используются модели (объектные классы Python). Они широко применяются в приложениях FastAPI и становятся реальным преимуществом при написании больших приложений.

Подсказки типов данных

Пришло время узнать немного больше о подсказках типов в Python.

В главе 2 упоминалось, что во многих компьютерных языках переменная указывает непосредственно на значение в памяти. Это требует от программиста объявления типа значения, чтобы можно было определить его размер и разрядность. В Python переменные — это просто имена, связанные с объектами, и именно у объектов есть типы.

В стандартном программировании переменная обычно связана с одним и тем же объектом. Если мы свяжем с этой переменной подсказку типа, то сможем избежать некоторых ошибок в программировании. Поэтому Python добавил подсказки типов к языку, в стандартный модуль типизации. Интерпретатор Python игнорирует синтаксис подсказки типа и выполняет программу так, как будто ее нет. Тогда в чем смысл?

В одной строке вы можете рассматривать переменную как строку, а потом забыть и присвоить ей объект другого типа. Компиляторы других языков будут жаловаться, а Python этого не сделает. Стандартный интерпретатор Python отлавливает обычные синтаксические ошибки и исключения времени выполнения, но не смешивает типы переменных. Инструменты-помощники, такие как mypy, обращают внимание на подсказки типов и предупреждают о любых несоответствиях.

Кроме того, подсказки доступны разработчикам Python, которые могут написать инструменты, выполняющие не только проверку ошибок типов. В следующих разделах описывается, как пакет Pydantic был разработан для удовлетворения неочевидных потребностей. Позже вы увидите, как его интеграция с FastAPI значительно упрощает решение многих вопросов веб-разработки.

Кстати, как выглядят подсказки? Существует один синтаксис для переменных и другой — для возвращаемых значений функций.

Подсказки типа переменной могут включать только тип:

name: type

или также инициализировать переменную значением:

name: type = value

Тип может быть одним из стандартных простых типов Python, таких как int или
str, или коллекцией, такой как tuple, list или dict:

thing: str = "yeti"

При использовании Python до версии 3.9 необходимо импортировать прописные версии стандартных имен типов из модуля типизации:

from typing import Str
thing: Str = "yeti"

Вот несколько примеров с инициализацией:

physics_magic_number: float = 1.0/137.03599913
hp_lovecraft_noun: str = "ichor"
exploding_sheep: tuple = "sis", "boom", bah!"
responses: dict = {"Marco": "Polo", "answer": 42}

Можно также включать подтипы коллекций:

name: dict[keytype, valtype] = {key1: val1, key2: val2}

Модуль типизации содержит полезные дополнения для подтипов. Наиболее распространенные из них следующие:

• Any — любой тип;
• Union — любой из указанных типов, например Union[str, int].

В Python, начиная с версии 3.10, можно написать type1 | type2, а не Union[type1,type2].

Примеры определений Pydantic для словарей (dict) в Python включают следующее:

from typing import Any
responses: dict[str, Any] = {"Marco": "Polo", "answer": 42}

Или, если быть более точными:

from typing import Union
responses: dict[str, Union[str, int]] = {"Marco": "Polo", "answer": 42}

либо (в Python 3.10 и более поздних версиях):

responses: dict[str, str | int] = {"Marco": "Polo", "answer": 42}

Обратите внимание на то, что в Python строка переменной с подсказкой типа является верной, а простая строка переменной — нет:

$ python
...
>>> thing0
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name thing0 is not defined
>>> thing0: str

Кроме того, некорректное использование типов не отлавливается обычным интерпретатором Python:

$ python
...
>>> thing1: str = "yeti"
>>> thing1 = 47 

Но такие ошибки будут обнаружены mypy. Если у вас еще не установлен этот статический анализатор, наберите команду pip install mypy. Сохраните две предыдущие строки в файле stuff.py, а затем попробуйте выполнить следующие команды:

$ mypy stuff.py
stuff.py:2: error: Incompatible types in assignment
(expression has type "int", variable has type "str")
Found 1 error in 1 file (checked 1 source file) 

В подсказке типа возврата функции вместо двоеточия применяется стрелка:

function(args) -> type:

Вот пример возврата функции при использовании Pydantic:

def get_thing() -> str:
    return "yeti"

Можно задействовать любой тип, включая определенные классы или их комбинации. Вы увидите это через несколько страниц.

Группировка данных

Зачастую нам нужно сохранить связанную группу переменных, а не передавать множество отдельных переменных. Как объединить несколько переменных в группу и сохранить подсказки типа?

Давайте оставим в прошлом пример с простым приветствием из предыдущих глав и начнем использовать более богатые данные. Как и в остальных частях этой книги, я буду приводить примеры криптидов (воображаемых существ) и исследователей (тоже воображаемых), которые их ищут. Начальные определения криптидов будут включать в себя только строковые переменные для следующих параметров:

• name — ключ;
  country — двухсимвольный код страны согласно стандарту ISO (3166-1 alpha 2) или *, что означает «все»;
  area (необязательный) — штат США или другое территориальное образование страны;
  description — в свободной форме;
  aka — обозначает «также известен как…» (also known as…).

Пример 5.3 показывает, что вы можете получить немного больше объяснений, определив имена для целочисленных смещений.
Пример 5.3. Использование кортежей и именованных смещений

>>> NAME = 0
>>> COUNTRY = 1
>>> AREA = 2
>>> DESCRIPTION = 3
>>> AKA = 4
>>> tuple_thing = ("yeti", "CN", "Himalayas",
    "Hirsute Himalayan", "Abominable Snowman")
>>> print("Name is", tuple_thing[NAME])
Name is yeti

В примере 5.4 словари выглядят немного лучше, предоставляя доступ по описательным ключам.
Пример 5.4. Использование словаря

>>> dict_thing = {"name": "yeti",
...     "country": "CN",
...     "area": "Himalayas",
...     "description": "Hirsute Himalayan",
...     "aka": "Abominable Snowman"}
>>> print("Name is", dict_thing["name"])
Name is yeti

Множества содержат только уникальные значения, поэтому они не очень полезны для кластеризации различных переменных.
В примере 5.5 именованный кортеж — это кортеж, предоставляющий вам доступ по целочисленному смещению или имени.
Пример 5.5. Использование именованного кортежа

>>> from collections import namedtuple
>>> CreatureNamedTuple = namedtuple("CreatureNamedTuple",
...     "name, country, area, description, aka")
>>> namedtuple_thing = CreatureNamedTuple("yeti",
...     "CN",
...     "Himalaya",
...     "Hirsute HImalayan",
...     "Abominable Snowman")
>>> print("Name is", namedtuple_thing[0])
Name is yeti
>>> print("Name is", namedtuple_thing.name)
Name is yeti

Нельзя написать namedtuple_thing[«name»]. Это будет tuple, а не dict, поэтому индекс должен быть целым числом.
В примере 5.6 определяется новый класс Python под названием class и добавляются все атрибуты с помощью self. Но для их определения вам придется
набрать много текста.
Пример 5.6. Использование стандартного класса

>>> class CreatureClass():
...     def __init__(self,
...       name: str,
...       country: str,
...       area: str,
...       description: str,
...       aka: str):
...       self.name = name
...       self.country = country
...       self.area = area
...       self.description = description
...       self.aka = aka
...
>>> class_thing = CreatureClass(
...     "yeti",
...     "CN",
...     "Himalayas"
...     "Hirsute Himalayan",
...     "Abominable Snowman")
>>> print("Name is", class_thing.name)
Name is yeti

Вы можете подумать: что в этом плохого? В обычном классе можно добавить больше данных (атрибутов), но особенно много поведения (методов). В один безумный день вы можете решить добавить метод для поиска любимых песен исследователя. (Это нельзя применить к существам1.) Но в данном случае речь идет о том, чтобы просто без помех перемещать сборки данных между уровнями и проверять их на входе и выходе. Кроме того, методы — это квадратные детали, которые с трудом помещаются в круглые отверстия базы данных.

Есть ли в Python что-то похожее на то, что в других компьютерных языках называется записью (record) или структурой (struct) (группа имен и значений)? Недавно в Python появился класс для хранения данных (dataclass). В примере 5.7 показано, как все эти self-выражения исчезают при использовании классов данных.
Пример 5.7. Применение класса данных dataclass

>>> from dataclasses import dataclass
>>>
>>> @dataclass
... class CreatureDataClass():
...     name: str
...     country: str
...     area: str
...     description: str
...     aka: str
...
>>> dataclass_thing = CreatureDataClass(
...     "yeti",
...     "CN",
...     "Himalayas"
...     "Hirsute Himalayan",
...     "Abominable Snowman")
>>> print("Name is", dataclass_thing.name)
Name is yeti

Это очень хорошо для части описания, связанной с сохранением переменных вместе. Но нам требуется больше, так что давайте попросим у Дедушки Мороза вот что:

• объединение возможных альтернативных типов;
• отсутствующие/дополнительные значения;
• значения по умолчанию;
• проверку достоверности данных;
• сериализацию в форматы, такие как JSON, и из них.

Альтернативы

Очень заманчиво использовать встроенные структуры данных Python, особенно словари. Но вы неизбежно обнаружите, что словари слишком свободны. А за свободу приходится платить. Вам нужно будет проверить абсолютно все.

• Ключ необязателен?
• Если ключ отсутствует, есть ли значение по умолчанию?
• Существует ли ключ?
• Если да, то относится ли значение ключа к правильному типу?
• Если да, то находится ли значение в нужном диапазоне или соответствует ли
  оно шаблону?

По крайней мере три решения отвечают хотя бы некоторым из этих требований:

• Dataclasses (https://oreil.ly/mxANA) — часть стандартного языка Python;
• attrs (https://www.attrs.org) — сторонний пакет, но содержит супернабор классов
  данных;
• Pydantic (https://docs.pydantic.dev) — тоже сторонний продукт, но интегрированный в FastAPI, поэтому его легко выбрать, если вы уже используете FastAPI.
  И если вы читаете эту книгу, то вполне вероятно, что это именно так.

Удобное сравнение этих трех вариантов можно посмотреть на YouTube (https://oreil.ly/pkQD3). Одним из выводов является то, что Pydantic выделяется при проверке, а его интеграция с FastAPI позволяет выявить множество потенциальных ошибок в данных. Другое дело, что Pydantic полагается на наследование (от класса BaseModel), а два других используют декораторы Python для определения своих объектов. Это скорее вопрос стиля.

В другом сравнении (https://oreil.ly/gU28a) Pydantic превзошел более старые пакеты проверки, такие как marshmallow (https://marshmallow.readthedocs.io) и библиотека с интригующим названием Voluptuous1 (https://github.com/alecthomas/voluptuous). Еще один большой плюс Pydantic в том, что он использует стандартный синтаксис подсказок типов Python — более старые библиотеки не применяли подсказки типов и создавали собственные.

В книге я остановился на Pydantic, но вы можете найти применение любой из альтернатив, если не используете FastAPI.

Pydantic предоставляет возможность задать любую комбинацию следующих проверок:

• обязательные и необязательные;
• значение по умолчанию, если не указано, но требуется;
• ожидаемый тип или типы данных;
• ограничения диапазона значений;
• другие проверки на основе функций, если необходимо;
• сериализацию и десериализацию.

Простой пример

Вы уже видели, как передать простую строку в конечную точку веб-приложения через URL, параметр запроса или тело HTTP-запроса. Проблема в том, что обычно вы запрашиваете и получаете группы данных разных типов. Именно здесь в FastAPI впервые появляются модели Pydantic. В начальном примере будут использоваться три файла:

• model.py — определяет модель Pydantic;
• data.py — источник фиктивных данных, определяющих экземпляр модели;
• web.py — определяет конечную точку веб-приложения FastAPI, возвращающую фиктивные данные.

Для простоты в этой главе сохраним все файлы в одном каталоге. В последующих главах, посвященных более крупным веб-сайтам, мы разделим их на соответствующие уровни. Сначала определим модель существа в примере 5.8.
Пример 5.8. Определение модели существа: model.py

from pydantic import BaseModel
class Creature(BaseModel):
    name: str
    country: str
    area: str
    description: str
    aka: str
thing = Creature(
    name="yeti",
    country="CN",
    area="Himalayas",
    description="Hirsute Himalayan",
    aka="Abominable Snowman")
)
print("Name is", thing.name)

Класс Creature наследуется от класса BaseModel из Pydantic. Часть выражения
: str после слов name, country,area, description и aka представляет собой под-
сказку типа — каждое из значений относится к строковому типу данных Python.

В этом примере все поля обязательны для заполнения. В Pydantic, если слово Optional отсутствует в описании типа, поле должно содержать значение.

В примере 5.9 аргументы передаются в любом порядке, если вы указываете их
имена.
Пример 5.9. Создание существа

>>> thing = Creature(
...     name="yeti",
...     country="CN",
...     area="Himalayas"
...     description="Hirsute Himalayan",
...     aka="Abominable Snowman")
>>>     print("Name is", thing.name)
Name is yeti

Пока что в примере 5.10 определен небольшой источник данных. В последующих главах этим будут заниматься базы данных. Подсказка типа list[Creature] говорит Python, что это список только объектов Creature.
Пример 5.10. Определение фиктивных данных в файле data.py

from model import Creature
_creatures: list[Creature] = [
    Creature(name="yeti",
        country="CN",
        area="Himalayas",
        description="Hirsute Himalayan",
        aka="Abominable Snowman"
),
    Creature(name="sasquatch",
        country="US",
        area="*",
        description="Yeti's Cousin Eddie",
        aka="Bigfoot")
]
def get_creatures() -> list[Creature]:
return _creatures

(Мы использовали символ "*" для аргумента area объекта Bigfoot, потому что он может жить почти везде.)

Этот код импортирует написанный нами ранее файл model.py. Он немного скрывает данные, вызывая свой список объектов Creature_creatures и предоставляя функцию get_creatures() для их возврата.
В примере 5.11 приведен файл web.py, определяющий конечную точку веб-приложения FastAPI.
Пример 5.11. Определение конечной точки веб-приложения FastAPI: web.py

from model import Creature
from fastapi import FastAPI
app = FastAPI()
@app.get("/creature")
def get_all() -> list[Creature]:
    from data import get_creatures
    return get_creatures()

Теперь запустите этот сервер с одной конечной точкой в примере 5.12.
Пример 5.12. Запуск Uvicorn

$ uvicorn creature:app
INFO:     Started server process [24782]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

В другом окне примера 5.13 осуществляется доступ к веб-приложению с помощью веб-клиента HTTPie (попробуйте использовать свой браузер или модуль Requests по желанию).
Пример 5.13. Проверка с помощью HTTPie

$ http http://localhost:8000/creature
HTTP/1.1 200 OK
content-length: 183
content-type: application/json
date: Mon, 12 Sep 2022 02:21:15 GMT
server: uvicorn
[
{
        "aka": "Abominable Snowman",
        "area": "Himalayas",
        "country": "CN",
        "name": "yeti",
        "description": "Hirsute Himalayan"
},
{
        "aka": "Bigfoot",
        "country": "US",
        "area": "*",
        "name": "sasquatch",
        "description": "Yeti's Cousin Eddie"
}

FastAPI и Starlette автоматически преобразуют исходный список объектов модели Creature в строку JSON. Это формат вывода по умолчанию в FastAPI, поэтому нам не нужно его указывать.
Кроме того, в окне, в котором вы первоначально запустили веб-сервер Uvicorn, должна быть выведена строка журнала:

INFO: 127.0.0.1:52375 - "GET /creature HTTP/1.1" 200 OK

Проверка типов

В предыдущем разделе было показано, как сделать следующее:

• применить подсказки типов к переменным и функциям;
• определить и использовать модель Pydantic;
• возвратить список моделей из источника данных;
• возвратить список моделей веб-клиенту, автоматически преобразовав его
  в JSON.

А теперь действительно применим этот план для проверки данных. Попробуйте присвоить значение неправильного типа одному или нескольким полям объекта Creature. Для этого воспользуйтесь автономным тестом (Pydantic не применяется ни к какому веб-коду, он относится к данным).
В примере 5.14 показано содержимое файла test1.py.
Пример 5.14. Проверка модели Creature

from model import Creature
dragon = Creature(
    name="dragon",
    description=["incorrect", "string", "list"],
    country="*" ,
    area="*",
    aka="firedrake")

Теперь попробуйте выполнить тест из примера 5.15. Он показывает, что мы присвоили полю description список строк, а ему нужна обычная строка.
Пример 5.15. Продолжение теста

$ python test1.py
Traceback (most recent call last):
  File ".../test1.py", line 3, in <module>
    dragon = Creature(
  File "pydantic/main.py", line 342, in
    pydantic.main.BaseModel.init
    pydantic.error_wrappers.ValidationError:
    1 validation error for Creature description
str type expected (type=type_error.str)

Проверка значений

Даже если тип значения соответствует его спецификации в классе Creature,
могут потребоваться дополнительные проверки. Некоторые ограничения могут быть наложены на само значение.

• Целочисленное значение (conint) или число с плавающей точкой:
  gt — больше чем;
  lt — меньше чем;
  ge — больше или равно;
  le — меньше или равно;
  multiple_of — целое число, кратное значению.
• Строковое (constr) значение:
  min_length — минимальная длина в символах (не в байтах);
  max_length — максимальная длина в символах;
  to_upper — преобразование в прописные буквы;
  to_lower — преобразование в строчные буквы;
  regex — сопоставление с регулярным выражением Python.
• Кортеж, список или множество:
  min_items — минимальное количество элементов;
  max_items — максимальное количество элементов.

Они указываются в типовых частях модели.
Пример 5.16 позволяет убедиться, что поле name всегда будет содержать не менее двух символов. В противном случае "" (пустая строка) будет считаться допустимой.
Пример 5.16. Просмотр ошибки проверки

>>> from pydantic import BaseModel, constr
>>>
>>> class Creature(BaseModel):
...     name: constr(min_length=2)
...     country: str
...     area: str
...     description: str
...     aka: str
...
>>> bad_creature = Creature(name="!",
... description="it's a raccoon",
... area="your attic")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pydantic/main.py", line 342,
  in pydantic.main.BaseModel.__init__
pydantic.error_wrappers.ValidationError:
1 validation error for Creature name
  ensure this value has at least 2 characters
  (type=value_error.any_str.min_length; limit_value=2)

Ключевое слово constr означает ограниченную строку (constrained string).
В примере 5.17 используется альтернативный вариант — спецификация Field из библиотеки Pydantic.
Пример 5.17. Еще один сбой проверки, применена функция Field

 >>> from pydantic import BaseModel, Field
>>>
>>> class Creature(BaseModel):
...     name: str = Field(..., min_length=2)
...     country: str
...     area: str
...     description: str
...     aka: str
...
>>> bad_creature = Creature(name="!",
...     area="your attic",
...     description="it's a raccoon")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pydantic/main.py", line 342,
  in pydantic.main.BaseModel.__init__
pydantic.error_wrappers.ValidationError:
  1 validation error for Creature name
  ensure this value has at least 2 characters
(type=value_error.any_str.min_length; limit_value=2)

Аргумент… функции Field() означает, что значение обязательное и значения по умолчанию не предусмотрено.

Это минимальное введение в Pydantic. Главное, что можно сделать, — автоматизировать проверку данных. Вы увидите, насколько это полезно, при получении данных с веб-уровня или уровня данных.

Заключение

Модели предоставляют лучший способ определить данные, передаваемые в вашем веб-приложении. Библиотека Pydantic использует подсказки типов Python для определения моделей, передаваемых в приложении данных. Далее — определение зависимостей для выделения конкретных деталей из общего кода.

Более подробно с книгой можно ознакомиться на сайте издательства:

» Оглавление
» Отрывок

По факту оплаты бумажной версии книги на e-mail высылается электронная книга.
Для Хаброжителей скидка 25% по купону — FastAPI