Исключения 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-аутентификации по основанию и других схем. Используйте 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.UnprocessableEntity(description=None, response=None)

422 Unprocessable Entity

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

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

423 Locked

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

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, retry_after=None)

429 Too Many Requests

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

Параметры:	retry_after – Если указано, установите заголовок `Retry-After` в это значение. Может быть целым числом секунд или объектом `datetime`.

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

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

431 Request Header Fields Too Large

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

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

451 Unavailable For Legal Reasons

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

END_OF_DOCUMENT_MARKER

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

500 Internal Server Error

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

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

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

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, retry_after=None)

503 Service Unavailable

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

Параметры:	retry_after – Если задано, установите заголовок `Retry-After` в это значение. Может быть целым числом секунд или значением типа `datetime`.

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

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

504 Gateway Timeout

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

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

505 HTTP Version Not Supported

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

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

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

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

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

Changelog

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

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

Changelog

Добавлено в версии 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-приложения.

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

abort(404)  # 404 Not Found
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(). В любом случае вы должны ознакомиться с исходным кодом модуля исключений.

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

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