From 41d13a7633efccdc193f833b884fd5c63459873b Mon Sep 17 00:00:00 2001 From: GSmithApps Date: Thu, 2 Jan 2025 16:03:35 -0600 Subject: [PATCH 1/5] docs: added notes to `ApplicationError` and `FailureError` exception docstrings. --- temporalio/exceptions.py | 54 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 51 insertions(+), 3 deletions(-) diff --git a/temporalio/exceptions.py b/temporalio/exceptions.py index 95776623..62875251 100644 --- a/temporalio/exceptions.py +++ b/temporalio/exceptions.py @@ -1,4 +1,23 @@ -"""Common Temporal exceptions.""" +""" +Common Temporal exceptions. + +# Temporal Failure + +Most Temporal SDKs have a base class that the other Failures extend. +In python, it is the ``FailureError``. + +# Application Failure + +Workflow, and Activity, and Nexus Operation code use Application Failures to +communicate application-specific failures that happen. +This is the only type of Temporal Failure created and thrown by user code. +In the Python SDK, it is the ``ApplicationError``. + +# References + +More information can be found in the docs at +https://docs.temporal.io/references/failures#workflow-execution-failures. +""" import asyncio from datetime import timedelta @@ -23,7 +42,16 @@ def cause(self) -> Optional[BaseException]: class FailureError(TemporalError): - """Base for runtime failures during workflow/activity execution.""" + """ + Base for runtime failures during workflow/activity execution. + + This is extended by ``ApplicationError``, which can be raised in a Workflow to fail the Workflow Execution. + Workflow Execution Failures put the Workflow Execution into the "Failed" state and no more attempts will + be made in progressing this execution. + + Any exception that does not extend this exception + is considered a Workflow Task Failure. These types of failures will cause the Workflow Task to be retried. + """ def __init__( self, @@ -71,7 +99,27 @@ def __init__( class ApplicationError(FailureError): - """Error raised during workflow/activity execution.""" + """ + Error raised during workflow/activity execution. + + Can be raised in a Workflow to fail the Workflow Execution. + Workflow Execution Failures put the Workflow Execution into the "Failed" state and no more attempts will + be made in progressing their execution. + + If you are creating custom exceptions or raising typical Python-based + exceptions you would either need to extend this class or + explicitly state that the exception is a Workflow Execution Failure by raising a new ``ApplicationError``. + + Any exception that does not extend this exception + is considered a Workflow Task Failure. These types of failures will cause the Workflow Task to be retried. + + # Example + + >>> from temporalio.exceptions import ApplicationError + ... # ... + ... if isDelivery and distance.get_kilometers() > 25: + ... raise ApplicationError("Customer lives outside the service area") + """ def __init__( self, From 5672e5c131b7a14423ea390cd4a28f0cfefb6476 Mon Sep 17 00:00:00 2001 From: GSmithApps Date: Thu, 2 Jan 2025 17:03:04 -0600 Subject: [PATCH 2/5] fix for linter --- temporalio/exceptions.py | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/temporalio/exceptions.py b/temporalio/exceptions.py index 62875251..5cc5c0b2 100644 --- a/temporalio/exceptions.py +++ b/temporalio/exceptions.py @@ -1,5 +1,4 @@ -""" -Common Temporal exceptions. +"""Common Temporal exceptions. # Temporal Failure @@ -42,8 +41,7 @@ def cause(self) -> Optional[BaseException]: class FailureError(TemporalError): - """ - Base for runtime failures during workflow/activity execution. + """Base for runtime failures during workflow/activity execution. This is extended by ``ApplicationError``, which can be raised in a Workflow to fail the Workflow Execution. Workflow Execution Failures put the Workflow Execution into the "Failed" state and no more attempts will @@ -99,8 +97,7 @@ def __init__( class ApplicationError(FailureError): - """ - Error raised during workflow/activity execution. + """Error raised during workflow/activity execution. Can be raised in a Workflow to fail the Workflow Execution. Workflow Execution Failures put the Workflow Execution into the "Failed" state and no more attempts will From f40030bfce21dd4a78f693bd3330cac13c394757 Mon Sep 17 00:00:00 2001 From: Grant <14.gsmith.14@gmail.com> Date: Mon, 6 Jan 2025 15:27:53 -0600 Subject: [PATCH 3/5] Update Docstring of FailureError Co-authored-by: Dan Davison --- temporalio/exceptions.py | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/temporalio/exceptions.py b/temporalio/exceptions.py index 5cc5c0b2..32b2f6c7 100644 --- a/temporalio/exceptions.py +++ b/temporalio/exceptions.py @@ -41,14 +41,16 @@ def cause(self) -> Optional[BaseException]: class FailureError(TemporalError): - """Base for runtime failures during workflow/activity execution. + """Base class for exceptions that cause a workflow execution failure. + + Do not raise this directly in workflow code: raise a child exception such as `ApplicationError` instead. - This is extended by ``ApplicationError``, which can be raised in a Workflow to fail the Workflow Execution. - Workflow Execution Failures put the Workflow Execution into the "Failed" state and no more attempts will - be made in progressing this execution. + Workflow execution failure puts the workflow execution into "Failed" state, and no further attempts will + be made to progress the workflow execution. - Any exception that does not extend this exception - is considered a Workflow Task Failure. These types of failures will cause the Workflow Task to be retried. + By default, any exception that does not extend this class causes the Workflow Task to be retried, rather than failing the workflow execution. + + The default behavior can be changed by providing a list of exception types to ``workflow_failure_exception_types`` when creating a worker or ``failure_exception_types`` on the ``@workflow.defn`` decorator. """ def __init__( From cd244ffbf797a5bdfecf5a8596327d368f512e09 Mon Sep 17 00:00:00 2001 From: Grant <14.gsmith.14@gmail.com> Date: Mon, 6 Jan 2025 15:28:50 -0600 Subject: [PATCH 4/5] Update docstring for `ApplicationError` Co-authored-by: Dan Davison --- temporalio/exceptions.py | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/temporalio/exceptions.py b/temporalio/exceptions.py index 32b2f6c7..acf42e49 100644 --- a/temporalio/exceptions.py +++ b/temporalio/exceptions.py @@ -99,18 +99,10 @@ def __init__( class ApplicationError(FailureError): - """Error raised during workflow/activity execution. + """Error raised during workflow/activity execution to cause a workflow execution failure. - Can be raised in a Workflow to fail the Workflow Execution. - Workflow Execution Failures put the Workflow Execution into the "Failed" state and no more attempts will - be made in progressing their execution. - - If you are creating custom exceptions or raising typical Python-based - exceptions you would either need to extend this class or - explicitly state that the exception is a Workflow Execution Failure by raising a new ``ApplicationError``. - - Any exception that does not extend this exception - is considered a Workflow Task Failure. These types of failures will cause the Workflow Task to be retried. + Workflow Execution Failures put the Workflow Execution into the "Failed" state and no further attempt will + be made to progress their execution. # Example From 98ae6f8ddaad8bd737c1bc1feb7e58559d294599 Mon Sep 17 00:00:00 2001 From: GSmithApps Date: Mon, 6 Jan 2025 16:05:06 -0600 Subject: [PATCH 5/5] docs: fix for linter --- temporalio/exceptions.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/temporalio/exceptions.py b/temporalio/exceptions.py index acf42e49..be9e49c1 100644 --- a/temporalio/exceptions.py +++ b/temporalio/exceptions.py @@ -42,15 +42,15 @@ def cause(self) -> Optional[BaseException]: class FailureError(TemporalError): """Base class for exceptions that cause a workflow execution failure. - + Do not raise this directly in workflow code: raise a child exception such as `ApplicationError` instead. Workflow execution failure puts the workflow execution into "Failed" state, and no further attempts will be made to progress the workflow execution. By default, any exception that does not extend this class causes the Workflow Task to be retried, rather than failing the workflow execution. - - The default behavior can be changed by providing a list of exception types to ``workflow_failure_exception_types`` when creating a worker or ``failure_exception_types`` on the ``@workflow.defn`` decorator. + + The default behavior can be changed by providing a list of exception types to ``workflow_failure_exception_types`` when creating a worker or ``failure_exception_types`` on the ``@workflow.defn`` decorator. """ def __init__(