From 2ae3e4839c6b62a1c9faf90eb9f316018fb5d8a1 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Thu, 17 Oct 2024 10:26:20 +0300 Subject: [PATCH 1/3] docs: refactor exception usage --- docs/usage/exceptions.rst | 51 ++++++++++++++++++++---------------- docs/usage/plugins/index.rst | 2 ++ 2 files changed, 30 insertions(+), 23 deletions(-) diff --git a/docs/usage/exceptions.rst b/docs/usage/exceptions.rst index 956a29620c..9f7953ba72 100644 --- a/docs/usage/exceptions.rst +++ b/docs/usage/exceptions.rst @@ -2,20 +2,20 @@ Exceptions and exception handling ================================= Litestar define a base exception called :class:`LitestarException ` which serves -as a basis to all other exceptions. +as a base class for all other exceptions, see :mod:`API Reference `. -In general, Litestar will raise two types of exceptions: +In general, Litestar has two scenarions for exception handling: -- Exceptions that arise during application init, which fall -- Exceptions that are raised as part of the normal application flow, i.e. - exceptions in route handlers, dependencies, and middleware, that should be serialized in some fashion. +- Exceptions that are raised during application configuration, startup, and initialization, which are handled like regular Python exceptions +- Exceptions that are raised as part of the request handling, i.e. + exceptions in route handlers, dependencies, and middleware, that should be returned as a response to the end user Configuration Exceptions ------------------------ For missing extra dependencies, Litestar will raise either :class:`MissingDependencyException `. For example, if you try to use the -:doc:`SQLAlchemyPlugin ` without having SQLAlchemy installed, this will be raised when you +:ref:`SQLAlchemyPlugin ` without having SQLAlchemy installed, this will be raised when you start the application. For other configuration issues, Litestar will raise @@ -25,8 +25,8 @@ issue. Application Exceptions ---------------------- -For application exceptions, Litestar uses the class :class:`HTTPException <.exceptions.http_exceptions.HTTPException>`, -which inherits from :class:`LitestarException <.exceptions.LitestarException>`. This exception will be serialized +For application exceptions, Litestar uses the class :class:`~litestar.exceptions.http_exceptions.HTTPException`, +which inherits from :class:`~litestar.exceptions.LitestarException`. This exception will be serialized into a JSON response of the following schema: .. code-block:: json @@ -37,10 +37,10 @@ into a JSON response of the following schema: "extra": {} } -Litestar also offers several pre-configured exception subclasses with pre-set error codes that you can use, such as: +Litestar also offers several pre-configured ``HTTPException`` subclasses with pre-set error codes that you can use, such as: -.. py:currentmodule:: litestar.exceptions.http_exceptions +.. :currentmodule:: litestar.exceptions.http_exceptions +----------------------------------------+-------------+------------------------------------------+ | Exception | Status code | Description | @@ -49,26 +49,31 @@ Litestar also offers several pre-configured exception subclasses with pre-set er +----------------------------------------+-------------+------------------------------------------+ | :class:`ValidationException` | 400 | Raised when validation or parsing failed | +----------------------------------------+-------------+------------------------------------------+ -| :class:`NotFoundException` | 404 | HTTP status code 404 | -+----------------------------------------+-------------+------------------------------------------+ | :class:`NotAuthorizedException` | 401 | HTTP status code 401 | +----------------------------------------+-------------+------------------------------------------+ | :class:`PermissionDeniedException` | 403 | HTTP status code 403 | +----------------------------------------+-------------+------------------------------------------+ +| :class:`NotFoundException` | 404 | HTTP status code 404 | ++----------------------------------------+-------------+------------------------------------------+ | :class:`InternalServerException` | 500 | HTTP status code 500 | +----------------------------------------+-------------+------------------------------------------+ | :class:`ServiceUnavailableException` | 503 | HTTP status code 503 | +----------------------------------------+-------------+------------------------------------------+ -When a value fails ``pydantic`` validation, the result will be a :class:`ValidationException` with the ``extra`` key set to the -pydantic validation errors. Thus, this data will be made available for the API consumers by default. +.. :currentmodule:: None + +When a value fails ``pydantic`` validation, the result will be a :class:`~litestar.exceptions.http_exceptions.ValidationException` with the ``extra`` key set to the +``pydantic`` validation error message. + +.. warning:: All validation error messages will be made available for the API consumers by default. + If this is not your intent, adjust the exception contents. Exception handling ------------------ Litestar handles all errors by default by transforming them into **JSON responses**. If the errors are **instances of** -:class:`HTTPException`, the responses will include the appropriate ``status_code``. +:class:`~litestar.exceptions.http_exceptions.HTTPException`, the responses will include the appropriate ``status_code``. Otherwise, the responses will default to ``500 - "Internal Server Error"``. You can customize exception handling by passing a dictionary, mapping either status codes @@ -89,14 +94,6 @@ exceptions that inherit from ``HTTPException``. You could of course be more gran The choice whether to use a single function that has switching logic inside it, or multiple functions depends on your specific needs. -While it does not make much sense to have different functions with a top-level exception handling, -Litestar supports defining exception handlers on all layers of the app, with the lower layers overriding layer above -them. In the following example, the exception handler for the route handler function will only handle -the ``ValidationException`` occurring within that route handler: - -.. literalinclude:: /examples/exceptions/layered_handlers.py - :language: python - Exception handling layers ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -116,3 +113,11 @@ As a result of the above structure, the exceptions raised by the ASGI Router its and ``405 Method Not Allowed`` are handled only by exception handlers defined on the app layer. Thus, if you want to affect these exceptions, you will need to pass the exception handlers for them to the Litestar constructor and cannot use other layers for this purpose. + +While it does not make much sense to have different functions with a top-level exception handling, +Litestar supports defining exception handlers on all layers of the app, with the lower layers overriding layer above +them. In the following example, the exception handler for the route handler function will only handle +the ``ValidationException`` occurring within that route handler: + +.. literalinclude:: /examples/exceptions/layered_handlers.py + :language: python diff --git a/docs/usage/plugins/index.rst b/docs/usage/plugins/index.rst index 2419afe98c..13076750de 100644 --- a/docs/usage/plugins/index.rst +++ b/docs/usage/plugins/index.rst @@ -1,3 +1,5 @@ +.. _plugins: + ======= Plugins ======= From 3f075e6a528cb16bc8afa1e4d4eefbfbc7f4c40f Mon Sep 17 00:00:00 2001 From: sobolevn Date: Thu, 17 Oct 2024 10:31:44 +0300 Subject: [PATCH 2/3] typo --- docs/usage/exceptions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/exceptions.rst b/docs/usage/exceptions.rst index 9f7953ba72..8cb0231d05 100644 --- a/docs/usage/exceptions.rst +++ b/docs/usage/exceptions.rst @@ -4,7 +4,7 @@ Exceptions and exception handling Litestar define a base exception called :class:`LitestarException ` which serves as a base class for all other exceptions, see :mod:`API Reference `. -In general, Litestar has two scenarions for exception handling: +In general, Litestar has two scenarios for exception handling: - Exceptions that are raised during application configuration, startup, and initialization, which are handled like regular Python exceptions - Exceptions that are raised as part of the request handling, i.e. From 6d8f7b72348a9036238ed7c435e0fab215961580 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Tue, 22 Oct 2024 10:39:01 +0300 Subject: [PATCH 3/3] Address review --- docs/usage/exceptions.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/usage/exceptions.rst b/docs/usage/exceptions.rst index 8cb0231d05..2f3cc6a83c 100644 --- a/docs/usage/exceptions.rst +++ b/docs/usage/exceptions.rst @@ -62,8 +62,7 @@ Litestar also offers several pre-configured ``HTTPException`` subclasses with pr .. :currentmodule:: None -When a value fails ``pydantic`` validation, the result will be a :class:`~litestar.exceptions.http_exceptions.ValidationException` with the ``extra`` key set to the -``pydantic`` validation error message. +When a value fails validation, the result will be a :class:`~litestar.exceptions.http_exceptions.ValidationException` with the ``extra`` key set to the validation error message. .. warning:: All validation error messages will be made available for the API consumers by default. If this is not your intent, adjust the exception contents. @@ -114,7 +113,6 @@ and ``405 Method Not Allowed`` are handled only by exception handlers defined on these exceptions, you will need to pass the exception handlers for them to the Litestar constructor and cannot use other layers for this purpose. -While it does not make much sense to have different functions with a top-level exception handling, Litestar supports defining exception handlers on all layers of the app, with the lower layers overriding layer above them. In the following example, the exception handler for the route handler function will only handle the ``ValidationException`` occurring within that route handler: