HTTP Исключения

Реализует ряд исключений Python, которые могут быть подняты изнутри представления для запуска стандартного HTTP ответа, отличного от 200.

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

from werkzeug.wrappers.request import Request
from werkzeug.exceptions import HTTPException, NotFound

def view(request):
    raise NotFound()

@Request.application
def application(request):
    try:
        return view(request)
    except HTTPException as e:
        return e

Как видно из этого примера, эти исключения являются вызываемыми WSGI приложениями. Однако они не являются объектами ответа Werkzeug. Вы можете получить объект ответа, вызвав get_response() для HTTP исключения.

Помните, что вам может потребоваться передать environ (WSGI) или scope (ASGI) в get_response() , так как некоторые ошибки извлекают дополнительную информацию, относящуюся к запросу.

Если вы хотите подключить другую страницу исключения, скажем, для статуса кода 404, вы можете добавить второй except для конкретного подкласса ошибки:

@Request.application
def application(request):
    try:
        return view(request)
    except NotFound as e:
        return not_found(request)
    except HTTPException as e:
        return e

Классы ошибок

В Werkzeug существуют следующие классы ошибок:

exception werkzeug.exceptions.BadRequest(description=None, response=None)

400 Bad Request

Поднимается, если браузер отправляет что-то приложению или серверу, что приложение или сервер не могут обработать.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.Unauthorized(description=None, response=None, www_authenticate=None)

401 Unauthorized

Поднимается, если пользователь не авторизован для доступа к ресурсу.

Аргумент www_authenticate должен использоваться для установки заголовка WWW-Authenticate. Это используется для HTTP базовой аутентификации и других схем. Используйте WWWAuthenticate для создания правильно отформатированных значений. Строго говоря, ответ 401 некорректен, если он не предоставляет по крайней мере одно значение для этого заголовка, хотя реальные клиенты обычно этого не замечают.

Параметры:

description (Optional[str]) – Переопределить сообщение по умолчанию, используемое для тела ответа.
www-authenticate – Одно значение или список значений для заголовка(ов) WWW-Authenticate.
response (Optional[Response]) –
www_authenticate (Optional[Union[WWWAuthenticate, Iterable[WWWAuthenticate]]]) –

Тип возвращаемого значения:

None

Журнал изменений

Изменено в версии 2.0: Сериализуйте несколько элементов www_authenticate в несколько заголовков WWW-Authenticate, а не объединяйте их в одно значение для лучшей совместимости.

Изменено в версии 0.15.3: Если аргумент www_authenticate не задан, заголовок WWW-Authenticate не устанавливается.

Изменено в версии 0.15.3: Аргумент response был восстановлен.

Изменено в версии 0.15.1: description был перемещён обратно в качестве первого аргумента, восстанавливая его предыдущую позицию.

Изменено в версии 0.15.0: www_authenticate был добавлен в качестве первого аргумента, перед description.

exception werkzeug.exceptions.Forbidden(description=None, response=None)

403 Forbidden

Поднимается, если у пользователя нет разрешений на запрашиваемый ресурс, но он был аутентифицирован.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.NotFound(description=None, response=None)

404 Not Found

Поднимается, если ресурс не существует и никогда не существовал.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.MethodNotAllowed(valid_methods=None, description=None, response=None)

405 Method Not Allowed

Поднимается, если сервер использовал метод, который не поддерживает ресурс. Например, POST если ресурс только для просмотра. Особенно полезно для REST.

Первый аргумент для этого исключения должен быть списком разрешённых методов. Строго говоря, ответ будет некорректным, если вы не предоставите допустимые методы в заголовке, что вы можете сделать с этим списком.

Принимает необязательный список допустимых HTTP методов. Начиная с werkzeug 0.3, список будет обязательным.

Параметры:

valid_methods (Optional[Iterable[str]]) –
description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.NotAcceptable(description=None, response=None)

406 Not Acceptable

Поднимается, если сервер не может вернуть контент, соответствующий заголовкам Accept клиента.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.RequestTimeout(description=None, response=None)

408 Request Timeout

Вызвать для сигнализации о таймауте.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.Conflict(description=None, response=None)

409 Conflict

Вызвать, чтобы указать, что запрос не может быть завершен, поскольку он конфликтует с текущим состоянием на сервере.

Изменения

Новая в версии 0.7.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.Gone(description=None, response=None)

410 Gone

Вызвать, если ресурс существовал ранее и исчез без нового местоположения.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.LengthRequired(description=None, response=None)

411 Length Required

Вызвать, если браузер отправил данные, но не указан заголовок Content-Length, необходимый для обработки данного запроса на сервере.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.PreconditionFailed(description=None, response=None)

412 Precondition Failed

Код состояния, используемый в сочетании с If-Match, If-None-Match, или If-Unmodified-Since.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.RequestEntityTooLarge(description=None, response=None)

413 Request Entity Too Large

Код состояния, который следует возвращать, если отправленные данные превысили заданный лимит.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.RequestURITooLarge(description=None, response=None)

414 Request URI Too Large

Аналогично 413, но для слишком длинных URL.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.UnsupportedMediaType(description=None, response=None)

415 Unsupported Media Type

Код состояния, возвращаемый, если сервер не может обработать тип данных, переданный клиентом.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.RequestedRangeNotSatisfiable(length=None, units='bytes', description=None, response=None)

416 Requested Range Not Satisfiable

Клиент запросил недопустимую часть файла.

Изменения

Новая в версии 0.7.

Принимает необязательное значение заголовка Content-Range в зависимости от параметра length.

Параметры:

length (Optional[int]) –
units (str) –
description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.ExpectationFailed(description=None, response=None)

417 Expectation Failed

Сервер не может удовлетворить требованиям заголовка запроса Expect.

Changelog

Новая в версии 0.7.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.ImATeapot(description=None, response=None)

418 I’m a teapot

Сервер должен вернуть это, если он является чайником, и кто-то пытался сварить кофе с его помощью.

Changelog

Новая в версии 0.7.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.UnprocessableEntity(description=None, response=None)

422 Unprocessable Entity

Используется, если запрос правильно сформирован, но инструкции в нём неверны.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.Locked(description=None, response=None)

423 Locked

Используется, если ресурс, к которому осуществляется доступ, заблокирован.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.FailedDependency(description=None, response=None)

424 Failed Dependency

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

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.PreconditionRequired(description=None, response=None)

428 Precondition Required

Сервер требует, чтобы этот запрос был условным, обычно для предотвращения проблемы с потерянными обновлениями, которая является гонкой между двумя или более клиентами, пытающимися обновить ресурс с помощью PUT или DELETE. Требуя от каждого клиента включать в запрос условный заголовок («If-Match» или «If-Unmodified-Since») с правильным значением, сохранённым из недавнего запроса GET, сервер гарантирует, что каждый клиент, по крайней мере, видел предыдущую версию ресурса.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.TooManyRequests(description=None, response=None, retry_after=None)

429 Too Many Requests

Сервер ограничивает скорость, с которой этот пользователь получает ответы, и этот запрос превышает эту скорость. (Сервер может использовать любой удобный метод для идентификации пользователей и их скоростей запросов). Сервер может включить заголовок «Retry-After», чтобы указать, сколько времени пользователю следует подождать перед повторной попыткой.

Параметры:

retry_after (Optional[Union[datetime, int]]) – Если указано, установить заголовок Retry-After в это значение. Может быть целым числом int секунд или datetime.
description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

Changelog

Изменено в версии 1.0: Добавлен параметр retry_after.

exception werkzeug.exceptions.RequestHeaderFieldsTooLarge(description=None, response=None)

431 Request Header Fields Too Large

Сервер отказывается обрабатывать запрос, потому что заголовки слишком велики. Один или несколько отдельных заголовков могут быть слишком большими, или набор всех заголовков слишком велик.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.UnavailableForLegalReasons(description=None, response=None)

451 Unavailable For Legal Reasons

Этот код состояния указывает, что сервер отказывается предоставить доступ к ресурсу в результате юридического требования.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.InternalServerError(description=None, response=None, original_exception=None)

500 Internal Server Error

Вызывается, если произошла внутренняя ошибка сервера. Это хороший вариант по умолчанию, если в диспетчере произошла неизвестная ошибка.

Журнал изменений

Изменено в версии 1.0.0: Добавлен атрибут original_exception.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –
original_exception (Optional[BaseException]) –

Тип возвращаемого значения:

None

original_exception: Исходное исключение, вызвавшее эту ошибку 500. Может использоваться фреймворками для предоставления контекста при обработке непредвиденных ошибок.

exception werkzeug.exceptions.NotImplemented(description=None, response=None)

501 Not Implemented

Вызывается, если приложение не поддерживает действие, запрошенное браузером.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.BadGateway(description=None, response=None)

502 Bad Gateway

Если в вашем приложении используется проксирование, вы должны вернуть этот код состояния, если вы получили недопустимый ответ от сервера upstream, к которому обратились при попытке выполнить запрос.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.ServiceUnavailable(description=None, response=None, retry_after=None)

503 Service Unavailable

Код состояния, который следует вернуть, если служба временно недоступна.

Параметры:

retry_after (Optional[Union[datetime, int]]) – Если задано, установите заголовок Retry-After в это значение. Может быть целым числом int секунд или значением типа datetime.
description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

Журнал изменений

Изменено в версии 1.0: Добавлен параметр retry_after.

exception werkzeug.exceptions.GatewayTimeout(description=None, response=None)

504 Gateway Timeout

Код состояния, который следует вернуть, если подключение к серверу upstream истекло.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.HTTPVersionNotSupported(description=None, response=None)

505 HTTP Version Not Supported

Сервер не поддерживает версию протокола HTTP, используемую в запросе.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.ClientDisconnected(description=None, response=None)

Внутреннее исключение, которое возникает, если Werkzeug обнаруживает отключение клиента. Поскольку клиент уже ушел, попытка отправки сообщения об ошибке клиенту может не сработать и в конечном итоге привести к другой ошибке на сервере. В основном это здесь для того, чтобы по умолчанию оно игнорировалось, что касается Werkzeug.

Поскольку отключения нельзя надежно обнаружить, и WSGI их не определяет в большой степени, это исключение может или не может возникнуть, если клиент ушел.

Изменения

В версии 0.8.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

exception werkzeug.exceptions.SecurityError(description=None, response=None)

Возникает, если что-то вызывает ошибку безопасности. В остальном это точно так же, как ошибка неправильного запроса.

Изменения

В версии 0.9.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

Базовый класс

Все исключения реализуют этот общий интерфейс:

exception werkzeug.exceptions.HTTPException(description=None, response=None)

Базовый класс для всех исключений HTTP. Это исключение можно вызвать как WSGI-приложение для отображения страницы с ошибкой по умолчанию, или вы можете перехватывать подклассы независимо и отображать более приятные сообщения об ошибках.

Изменения

Изменено в версии 2.1: Удален метод wrap.

Параметры:

description (Optional[str]) –
response (Optional[Response]) –

Тип возвращаемого значения:

None

__call__(environ, start_response)

Вызов исключения как WSGI-приложения.

Параметры:

environ (WSGIEnvironment) – среда WSGI.
start_response (StartResponse) – вызываемый объект ответа, предоставленный сервером WSGI.

Тип возвращаемого значения:

Iterable[bytes]

get_response(environ=None, scope=None)

Получить объект ответа. Если он был передан в исключение, он возвращается непосредственно.

Параметры:

environ (Optional[Union[WSGIEnvironment, WSGIRequest]]) – необязательная среда для запроса. Это можно использовать для изменения ответа в зависимости от того, как выглядел запрос.
scope (Optional[dict]) –

Возвращаемое значение:

объект Response или его подкласс.

Тип возвращаемого значения:

Response

Особые исключения HTTP

Начиная с Werkzeug 0.3, некоторые встроенные классы генерируют исключения, которые выглядят как обычные исключения Python (например, KeyError), но одновременно являются исключениями HTTP BadRequest. Это решение было принято для упрощения распространённого шаблона, когда вы хотите прервать выполнение, если клиент изменил данные отправляемой формы таким образом, что приложение не может восстановиться должным образом и должно прерваться с 400 BAD REQUEST.

Предполагая, что приложение перехватывает все исключения HTTP и должным образом реагирует на них, функция представления может безопасно сделать следующее и не должна проверять, существуют ли ключи:

def new_post(request):
    post = Post(title=request.form['title'], body=request.form['body'])
    post.save()
    return redirect(post.url)

Если title или body отсутствуют в форме, будет поднято специальное исключение KeyError, которое ведет себя как KeyError, но также как исключение BadRequest.

exception werkzeug.exceptions.BadRequestKeyError(arg=None, *args, **kwargs)

Исключение, используемое для сигнализации как KeyError, так и BadRequest. Используется во многих структурах данных.

Параметры:

arg (Optional[str]) –
args (Any) –
kwargs (Any) –

Простые прерывания

Иногда удобно просто сгенерировать исключение по коду ошибки, без импорта исключения и поиска имени и т. д. Для этой цели существует функция abort().

werkzeug.exceptions.abort(status, *args, **kwargs)

Возбуждает исключение HTTPException для заданного кода состояния или WSGI-приложения.

Если задан код состояния, он будет найден в списке исключений, и это исключение будет возбуждено. Если передано WSGI-приложение, оно будет обернуто в прокси-исключение WSGI и возбуждено:

abort(404)  # 404 Not Found
abort(Response('Hello World'))

Параметры:

status (Union[int, Response]) –
args (Any) –
kwargs (Any) –

Тип возвращаемого значения:

te.NoReturn

Если вы хотите использовать эту функциональность с настраиваемыми исключениями, вы можете создать экземпляр класса aborter:

class werkzeug.exceptions.Aborter(mapping=None, extra=None)

При передаче словаря элементов "код -> исключение" он может использоваться как вызываемый объект, который возбуждает исключения. Если первым аргументом вызываемого объекта является целое число, оно будет найдено в отображении, если это WSGI-приложение, оно будет возбуждено в прокси-исключении.

Остальные аргументы передаются конструктору исключения.

Параметры:

mapping (Optional[Dict[int, Type[HTTPException]]]) –
extra (Optional[Dict[int, Type[HTTPException]]]) –

Пользовательские ошибки

Как видно из списка выше, не все коды статусов доступны как ошибки. Особенно отсутствуют перенаправления и другие коды статусов, отличные от 200, которые не представляют собой ошибки. Для перенаправлений вы можете использовать функцию redirect() из модуля утилит.

Если вы хотите добавить собственную ошибку, вы можете унаследовать от HTTPException:

from werkzeug.exceptions import HTTPException

class PaymentRequired(HTTPException):
    code = 402
    description = '<p>Payment required.</p>'

Это минимальный код, необходимый для вашего собственного исключения. Если вы хотите добавить больше логики в ошибки, вы можете переопределить методы get_description(), get_body(), get_headers() и get_response(). В любом случае, вы должны изучить исходный код модуля исключений.

Вы можете переопределить стандартное описание в конструкторе параметром description:

raise BadRequest(description='Request failed because X was not present')