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, вы можете добавить второй обработчик исключений для определённого подкласса ошибки:

@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 basic аутентификации и других схем. Используйте 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

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

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.

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), но которые являются BadRequest исключениями HTTP одновременно. Это решение было принято для упрощения распространённой ситуации, когда необходимо прервать выполнение, если клиент внес изменения в данные формы, которые приложение не может обработать и должно прерваться с 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)

При передаче словаря code -> exception элементы, он может использоваться как вызываемый объект, который генерирует исключения. Если первым аргументом вызываемого объекта является целое число, оно будет найдено в отображении; если это 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')