HTTP-исключения

werkzeug.exceptions

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

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

from werkzeug.wrappers import BaseRequest
from werkzeug.wsgi import responder
from werkzeug.exceptions import HTTPException, NotFound

def view(request):
    raise NotFound()

@responder
def application(environ, start_response):
    request = BaseRequest(environ)
    try:
        return view(request)
    except HTTPException as e:
        return e

Как видно из этого примера, эти исключения являются вызываемыми WSGI-приложениями. Из-за совместимости с Python 2.4 они не наследуются от объектов ответа, а только от класса исключения Python.

Фактически, они не являются объектами ответа Werkzeug. Однако вы можете получить объект ответа, вызвав get_response() для HTTP-исключения.

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

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

@responder
def application(environ, start_response):
    request = BaseRequest(environ)
    try:
        return view(request)
    except NotFound, e:
        return not_found(request)
    except HTTPException, e:
        return e

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

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

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

400 Bad Request

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

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

401 Unauthorized

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

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

Параметры:	description – Переопределите стандартное сообщение, используемое для тела ответа. 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

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

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

404 Not Found

Вызывается, если ресурс не существует и никогда не существовал.

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

405 Method Not Allowed

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

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

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

406 Not Acceptable

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

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

408 Request Timeout

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

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

409 Conflict

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

Добавлен в версии 0.7.

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

410 Gone

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

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

411 Length Required

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

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

412 Precondition Failed

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

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

413 Request Entity Too Large

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

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

414 Request URI Too Large

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

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

415 Unsupported Media Type

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

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

416 Requested Range Not Satisfiable

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

Добавлен в версии 0.7.

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

417 Expectation Failed

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

Добавлен в версии 0.7.

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

418 I’m a teapot

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

Добавлен в версии 0.7.

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

424 Failed Dependency

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

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

428 Precondition Required

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

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

429 Too Many Requests

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

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

431 Request Header Fields Too Large

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

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

500 Internal Server Error

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

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

501 Not Implemented

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

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

502 Bad Gateway

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

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

503 Service Unavailable

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

exception werkzeug.exceptions.HTTPUnicodeError: Это исключение используется для сигнализации об ошибках декодирования unicode данных запроса. Для получения дополнительной информации см. главу Unicode.

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

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

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

Добавлен в версии 0.8.

END_OF_DOCUMENT_MARKER

exception werkzeug.exceptions.SecurityError(description=None, response=None): Вызывается, если происходит ошибка безопасности. В остальном это точно такая же ошибка, как и ошибка неправильного запроса.

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

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

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

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

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

__call__(environ, start_response)

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

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

get_response(environ=None)

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

Параметры:	environ – необязательная среда для запроса. Это может использоваться для изменения ответа в зависимости от того, как выглядел запрос.
Возвращает:	объект `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. Используется многими структурами данных.

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

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

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

Вызывает исключение HTTPException для заданного кода состояния или WSGI-приложения:

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

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

abort(404)
abort(Response('Hello World'))

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

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

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

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

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

Как видно из списка выше, не все коды состояний доступны в качестве ошибок. Особенно отсутствуют перенаправления и другие коды состояний, отличные от 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(). В любом случае следует ознакомиться с исходным кодом модуля exceptions.

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

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