FastAPI: веб-разработка на Python (2024)

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

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

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

Обзор

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 Strthing: Str = "yeti"

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

physics_magic_number: float = 1.0/137.03599913hp_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 Anyresponses: dict[str, Any] = {"Marco": "Polo", "answer": 42}

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

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

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

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

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

$ python...>>> thing0Traceback (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.pystuff.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 BaseModelclass Creature(BaseModel): name: str country: str area: str description: str aka: strthing = 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 Creaturefrom fastapi import FastAPIapp = FastAPI()@app.get("/creature")def get_all() -> list[Creature]: from data import get_creatures return get_creatures()

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

$ uvicorn creature:appINFO: 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/creatureHTTP/1.1 200 OKcontent-length: 183content-type: application/jsondate: Mon, 12 Sep 2022 02:21:15 GMTserver: 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 Creaturedragon = Creature( name="dragon", description=["incorrect", "string", "list"], country="*" , area="*", aka="firedrake")

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

$ python test1.pyTraceback (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 descriptionstr 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