From f8dafa2c3c57ea96e387f1a4fa0d4b0c1ddeb200 Mon Sep 17 00:00:00 2001 From: Jan Bouwhuis Date: Sat, 25 Nov 2023 14:02:54 +0100 Subject: [PATCH] Update blog and docs on exception handling (#1988) --- ... => 2023-11-30-service-exceptions-and-translations.md} | 4 +++- docs/core/platform/raising_exceptions.md | 8 ++++++-- 2 files changed, 9 insertions(+), 3 deletions(-) rename blog/{2023-11-16-service-exceptions-and-translations.md => 2023-11-30-service-exceptions-and-translations.md} (83%) diff --git a/blog/2023-11-16-service-exceptions-and-translations.md b/blog/2023-11-30-service-exceptions-and-translations.md similarity index 83% rename from blog/2023-11-16-service-exceptions-and-translations.md rename to blog/2023-11-30-service-exceptions-and-translations.md index 734a9b98..3ee8d0c8 100644 --- a/blog/2023-11-16-service-exceptions-and-translations.md +++ b/blog/2023-11-30-service-exceptions-and-translations.md @@ -9,7 +9,9 @@ title: Exception handling during service calls and translation support Currently service calls that raise exceptions will log full stack traces. Service calls that fail due to invalid user input don't need a stack trace but would benefit from a helpful error message in the users own language. -To be able to suppress the stack trace in these cases, we introduce `ServiceValidationError` as a new exception type. The `ServiceValidationError` exception can be raised instead of `HomeAssistantError` during the execution of a service call. The error message will show in the UI, and in the logs. The stack trace is printed at debug level, to support development. For other exceptions that are raised from a service call (including `HomeAssistantError`) nothing changes and a full stack trace is printed. [Read more](/docs/core/platform/raising_exceptions). +To be able to suppress the stack trace in these cases, we introduce `ServiceValidationError` as a new exception type. The `ServiceValidationError` exception can be raised instead of `HomeAssistantError` during the execution of a service call. The error message will show in the UI, and in the logs. The stack trace is printed at debug level, to support development. For other exceptions that are raised from a service call (including `HomeAssistantError`) nothing changes and a full stack trace is printed. + +Integrations should be updated and raise `ServiceValidationError` instead of `ValueError` when the user did something wrong, and `HomeAssistantError` when it's not the user's fault. [Read more](/docs/core/platform/raising_exceptions). ## Translation support for Exceptions diff --git a/docs/core/platform/raising_exceptions.md b/docs/core/platform/raising_exceptions.md index 5705831d..8376282e 100644 --- a/docs/core/platform/raising_exceptions.md +++ b/docs/core/platform/raising_exceptions.md @@ -2,9 +2,13 @@ title: "Raising Exceptions" --- -Operations like service calls and entity methods (e.g. *Set HVAC Mode*) should raise exceptions properly. Raise `ServiceValidationError` on an invalid user input and raise `HomeAssistantError` for other failures such as a problem communicating with a device. Note that the exception stack trace will be logged. +## Raising Exceptions in service handlers -Raise `ServiceValidationError` for validation errors that occur during service calls where printing a full stack trace to the logs is not warranted. This exception class will only log exception stack traces at debug level. +Operations like service calls and entity methods (e.g. *Set HVAC Mode*) should raise exceptions properly. + +Integrations should raise `ServiceValidationError` (instead of `ValueError`) in case when the user did something wrong. In this case a stack trace will only be printed at debug level. + +For other failures such as a problem communicating with a device, `HomeAssistantError` should be raised. Note that the exception stack trace will be printed to the log in this case. ## Localizing Exceptions