Uvicorn.run: примеры (PYTHON)

Простые примеры использования

Базовый запуск приложения из файла main.py с приложением app.

import uvicorn
uvicorn.run("main:app")

INFO:     Uvicorn running on http://127.0.0.1:8000

Запуск с указанием хоста, порта и отладочным логированием.

import uvicorn
uvicorn.run(
    "main:app",
    host="0.0.0.0",
    port=8080,
    log_level="debug"
)

DEBUG:    Uvicorn running on http://0.0.0.0:8080
DEBUG:    Using selector: KqueueSelector

Запуск с включенной автоматической перезагрузкой.

import uvicorn
uvicorn.run("main:app", reload=True)

INFO:     Uvicorn running on http://127.0.0.1:8000
INFO:     Started reloader process [12345]

Альтернативные способы запуска в Python

Uvicorn через командную строку: Запуск через команду uvicorn main:app предоставляет идентичные возможности, но позволяет легче интегрировать сервер в shell-скрипты.

Gunicorn с Uvicorn Workers: Для production-среды часто используется связка Gunicorn в качестве менеджера процессов и UvicornWorker для обработки запросов. Это обеспечивает лучшую стабильность и управление процессами.

Hypercorn: Альтернативный ASGI-сервер, совместимый с протоколом HTTP/2. Предпочтителен при необходимости поддержки этого протокола.

Daphne: Сервер, изначально разработанный для Django Channels. Его использование актуально в проектах, уже завязанных на экосистеме Django.

Аналоги функции в других языках

JavaScript (Node.js): Модуль http позволяет создать и запустить сервер. В отличие от Uvicorn, он работает синхронно по умолчанию.

const http = require('http');
const server = http.createServer((req, res) => {
  res.end('Hello');
});
server.listen(8000, '127.0.0.1');

Server starts on http://127.0.0.1:8000

Golang: Используется функция ListenAndServe из пакета net/http. Сервер запускается в отдельной горутине.

package main
import "net/http"
func handler(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("Hello"))
}
func main() {
    http.HandleFunc("/", handler)
    http.ListenAndServe(":8000", nil)
}

Server starts on port 8000

PHP: Встроенный сервер для разработки запускается из командной строки, аналога прямого вызова из кода нет.

php -S 127.0.0.1:8000

Распространенные ошибки

Ошибка импорта модуля: Возникает при неверном указании пути к приложению.

uvicorn.run("non_existent_module:app")

ModuleNotFoundError: No module named 'non_existent_module'

Занятый порт: Попытка запуска сервера на порту, который уже используется.

uvicorn.run("main:app", port=80) # Если порт 80 занят

OSError: [Errno 48] Address already in use

Неверный тип приложения: Передача объекта, не являющегося ASGI-приложением.

uvicorn.run(123)

TypeError: 'int' object is not callable

Изменения в новых версиях

В версии Uvicorn 0.15.0 появился аргумент reload_excludes для исключения определенных путей из отслеживания изменений при перезагрузке. Также была улучшена поддержка протокола WebSocket.

В версии 0.16.0 изменен формат некоторых логов и улучшена интеграция с протоколом ASGI 3.0.

Расширенные примеры

Запуск с использованием SSL для шифрования соединения.

import uvicorn
uvicorn.run(
    "main:app",
    ssl_keyfile="./key.pem",
    ssl_certfile="./cert.pem"
)

INFO:     Uvicorn running on https://127.0.0.1:8000

Запуск в несколько рабочих процессов для использования нескольких ядер CPU. В этом режиме аргумент reload автоматически отключается.

import uvicorn
uvicorn.run("main:app", host="0.0.0.0", port=8000, workers=4)

INFO:     Started parent process [12345]
INFO:     Started server process [12346]
INFO:     Started server process [12347]
INFO:     Started server process [12348]
INFO:     Started server process [12349]

Интеграция с пользовательским циклом событий uvloop для увеличения производительности.

import uvicorn
uvicorn.run("main:app", loop="uvloop")

INFO:     Using uvloop event loop.

Запуск с фильтрацией логов по определенному пути.

import logging
import uvicorn
log_config = uvicorn.config.LOGGING_CONFIG
log_config["loggers"]["uvicorn.access"]["filters"] = ["path_filter"]
uvicorn.run("main:app", log_config=log_config)