Format docstrings

Author: dandavison

temporalio/exceptions.py

@@ -375,7 +375,8 @@ def __init__(
         operation: str,
         operation_token: str,
     ):
-        """
+        """Initialize a Nexus operation error.
+
         Args:
             message: The error message.
             scheduled_event_id: The NexusOperationScheduled event ID for the failed operation.

temporalio/nexus/__init__.py

@@ -1,3 +1,8 @@
+"""Temporal Nexus support
+
+See https://github.com/temporalio/sdk-python/tree/main#nexus
+"""
+
 from ._decorators import workflow_run_operation as workflow_run_operation
 from ._operation_context import Info as Info
 from ._operation_context import LoggerAdapter as LoggerAdapter

temporalio/nexus/_decorators.py

@@ -91,9 +91,7 @@ def workflow_run_operation(
         ],
     ],
 ]:
-    """
-    Decorator marking a method as the start method for a workflow-backed operation.
-    """
+    """Decorator marking a method as the start method for a workflow-backed operation."""
 
     def decorator(
         start: Callable[

temporalio/nexus/_operation_context.py

@@ -63,23 +63,17 @@ class Info:
 
 
 def in_operation() -> bool:
-    """
-    Whether the current code is inside a Nexus operation.
-    """
+    """Whether the current code is inside a Nexus operation."""
     return _try_temporal_context() is not None
 
 
 def info() -> Info:
-    """
-    Get the current Nexus operation information.
-    """
+    """Get the current Nexus operation information."""
     return _temporal_context().info()
 
 
 def client() -> temporalio.client.Client:
-    """
-    Get the Temporal client used by the worker handling the current Nexus operation.
-    """
+    """Get the Temporal client used by the worker handling the current Nexus operation."""
     return _temporal_context().client
 
 
@@ -104,9 +98,7 @@ def _try_temporal_context() -> (
 
 @dataclass
 class _TemporalStartOperationContext:
-    """
-    Context for a Nexus start operation being handled by a Temporal Nexus Worker.
-    """
+    """Context for a Nexus start operation being handled by a Temporal Nexus Worker."""
 
     nexus_context: StartOperationContext
     """Nexus-specific start operation context."""
@@ -183,7 +175,10 @@ def _add_outbound_links(
 
 
 class WorkflowRunOperationContext(StartOperationContext):
+    """Context received by a workflow run operation."""
+
     def __init__(self, *args, **kwargs):
+        """Initialize the workflow run operation context."""
         super().__init__(*args, **kwargs)
         self._temporal_context = _TemporalStartOperationContext.get()
 
@@ -455,9 +450,7 @@ async def start_workflow(
 
 @dataclass(frozen=True)
 class _TemporalCancelOperationContext:
-    """
-    Context for a Nexus cancel operation being handled by a Temporal Nexus Worker.
-    """
+    """Context for a Nexus cancel operation being handled by a Temporal Nexus Worker."""
 
     nexus_context: CancelOperationContext
     """Nexus-specific cancel operation context."""
@@ -565,12 +558,16 @@ def _nexus_link_to_workflow_event(
 
 
 class LoggerAdapter(logging.LoggerAdapter):
+    """Logger adapter that adds Nexus operation context information."""
+
     def __init__(self, logger: logging.Logger, extra: Optional[Mapping[str, Any]]):
+        """Initialize the logger adapter."""
         super().__init__(logger, extra or {})
 
     def process(
         self, msg: Any, kwargs: MutableMapping[str, Any]
     ) -> tuple[Any, MutableMapping[str, Any]]:
+        """Process log records to add Nexus operation context."""
         extra = dict(self.extra or {})
         if tctx := _try_temporal_context():
             extra["service"] = tctx.nexus_context.service

temporalio/nexus/_operation_handlers.py

@@ -36,8 +36,7 @@
 
 
 class WorkflowRunOperationHandler(OperationHandler[InputT, OutputT]):
-    """
-    Operation handler for Nexus operations that start a workflow.
+    """Operation handler for Nexus operations that start a workflow.
 
     Use this class to create an operation handler that starts a workflow by passing your
     ``start`` method to the constructor. Your ``start`` method must use
@@ -54,6 +53,7 @@ def __init__(
         input_type: Optional[Type[InputT]],
         output_type: Optional[Type[OutputT]],
     ) -> None:
+        """Initialize the workflow run operation handler."""
         if not is_async_callable(start):
             raise RuntimeError(
                 f"{start} is not an `async def` method. "
@@ -70,9 +70,7 @@ def __init__(
     async def start(
         self, ctx: StartOperationContext, input: InputT
     ) -> StartOperationResultAsync:
-        """
-        Start the operation, by starting a workflow and completing asynchronously.
-        """
+        """Start the operation, by starting a workflow and completing asynchronously."""
         handle = await self._start(ctx, input)
         if not isinstance(handle, WorkflowHandle):
             if isinstance(handle, client.WorkflowHandle):
@@ -94,13 +92,15 @@ async def cancel(self, ctx: CancelOperationContext, token: str) -> None:
     async def fetch_info(
         self, ctx: FetchOperationInfoContext, token: str
     ) -> OperationInfo:
+        """Fetch operation info (not supported for Temporal Nexus operations)."""
         raise NotImplementedError(
             "Temporal Nexus operation handlers do not support fetching operation info."
         )
 
     async def fetch_result(
         self, ctx: FetchOperationResultContext, token: str
     ) -> OutputT:
+        """Fetch operation result (not supported for Temporal Nexus operations)."""
         raise NotImplementedError(
             "Temporal Nexus operation handlers do not support fetching the operation result."
         )
@@ -131,8 +131,7 @@ async def _cancel_workflow(
     token: str,
     **kwargs: Any,
 ) -> None:
-    """
-    Cancel a workflow that is backing a Nexus operation.
+    """Cancel a workflow that is backing a Nexus operation.
 
     This function is used by the Nexus worker to cancel a workflow that is backing a
     Nexus operation, i.e. started by a

temporalio/nexus/_token.py

@@ -15,9 +15,7 @@
 
 @dataclass(frozen=True)
 class WorkflowHandle(Generic[OutputT]):
-    """
-    A handle to a workflow that is backing a Nexus operation.
-
+    """A handle to a workflow that is backing a Nexus operation.
 
     Do not instantiate this directly. Use
     :py:func:`temporalio.nexus.WorkflowRunOperationContext.start_workflow` to create a
@@ -59,6 +57,7 @@ def _unsafe_from_client_workflow_handle(
         )
 
     def to_token(self) -> str:
+        """Convert handle to a base64url-encoded token string."""
         return _base64url_encode_no_padding(
             json.dumps(
                 {

temporalio/nexus/_util.py

@@ -42,7 +42,6 @@ def get_workflow_run_start_method_input_and_output_type_annotations(
     `start` must be a type-annotated start method that returns a
     :py:class:`temporalio.nexus.WorkflowHandle`.
     """
-
     input_type, output_type = _get_start_method_input_and_output_type_annotations(start)
     origin_type = typing.get_origin(output_type)
     if not origin_type:
@@ -107,6 +106,7 @@ def _get_start_method_input_and_output_type_annotations(
 
 
 def get_callable_name(fn: Callable[..., Any]) -> str:
+    """Return the name of a callable object."""
     method_name = getattr(fn, "__name__", None)
     if not method_name and callable(fn) and hasattr(fn, "__call__"):
         method_name = fn.__class__.__name__
@@ -158,8 +158,7 @@ def set_operation_factory(
 #
 # This file is licensed under the MIT License.
 def is_async_callable(obj: Any) -> bool:
-    """
-    Return True if `obj` is an async callable.
+    """Return True if `obj` is an async callable.
 
     Supports partials of async callable class instances.
     """

temporalio/worker/_interceptor.py

@@ -302,6 +302,7 @@ class StartNexusOperationInput(Generic[InputT, OutputT]):
     output_type: Optional[Type[OutputT]] = None
 
     def __post_init__(self) -> None:
+        """Initialize operation-specific attributes after dataclass creation."""
         if isinstance(self.operation, nexusrpc.Operation):
             self.output_type = self.operation.output_type
         elif callable(self.operation):
@@ -319,6 +320,7 @@ def __post_init__(self) -> None:
 
     @property
     def operation_name(self) -> str:
+        """Get the name of the Nexus operation."""
         if isinstance(self.operation, nexusrpc.Operation):
             return self.operation.name
         elif isinstance(self.operation, str):

temporalio/worker/_nexus.py

@@ -69,9 +69,7 @@ def __init__(
         self._fail_worker_exception_queue: asyncio.Queue[Exception] = asyncio.Queue()
 
     async def run(self) -> None:
-        """
-        Continually poll for Nexus tasks and dispatch to handlers.
-        """
+        """Continually poll for Nexus tasks and dispatch to handlers."""
 
         async def raise_from_exception_queue() -> NoReturn:
             raise await self._fail_worker_exception_queue.get()
@@ -160,8 +158,7 @@ async def _handle_cancel_operation_task(
         request: temporalio.api.nexus.v1.CancelOperationRequest,
         headers: Mapping[str, str],
     ) -> None:
-        """
-        Handle a cancel operation task.
+        """Handle a cancel operation task.
 
         Attempt to execute the user cancel_operation method. Handle errors and send the
         task completion.
@@ -213,13 +210,11 @@ async def _handle_start_operation_task(
         start_request: temporalio.api.nexus.v1.StartOperationRequest,
         headers: Mapping[str, str],
     ) -> None:
-        """
-        Handle a start operation task.
+        """Handle a start operation task.
 
         Attempt to execute the user start_operation method and invoke the data converter
         on the result. Handle errors and send the task completion.
         """
-
         try:
             try:
                 start_response = await self._start_operation(start_request, headers)
@@ -256,8 +251,7 @@ async def _start_operation(
         start_request: temporalio.api.nexus.v1.StartOperationRequest,
         headers: Mapping[str, str],
     ) -> temporalio.api.nexus.v1.StartOperationResponse:
-        """
-        Invoke the Nexus handler's start_operation method and construct the StartOperationResponse.
+        """Invoke the Nexus handler's start_operation method and construct the StartOperationResponse.
 
         OperationError is handled by this function, since it results in a StartOperationResponse.
 
@@ -326,8 +320,7 @@ async def _nexus_error_to_nexus_failure_proto(
         self,
         error: Union[nexusrpc.HandlerError, nexusrpc.OperationError],
     ) -> temporalio.api.nexus.v1.Failure:
-        """
-        Serialize ``error`` as a Nexus Failure proto.
+        """Serialize ``error`` as a Nexus Failure proto.
 
         The Nexus Failure represents the top-level error. If there is a cause chain
         attached to the exception, then serialize it as the ``details``.
@@ -381,9 +374,7 @@ async def _operation_error_to_proto(
     async def _handler_error_to_proto(
         self, handler_error: nexusrpc.HandlerError
     ) -> temporalio.api.nexus.v1.HandlerError:
-        """
-        Serialize ``handler_error`` as a Nexus HandlerError proto.
-        """
+        """Serialize ``handler_error`` as a Nexus HandlerError proto."""
         retry_behavior = (
             temporalio.api.enums.v1.NexusHandlerErrorRetryBehavior.NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_RETRYABLE
             if handler_error.retryable_override is True

temporalio/worker/_worker.py

@@ -183,7 +183,7 @@ def __init__(
                 otherwise. The default one will be properly shutdown, but if one
                 is provided, the caller is responsible for shutting it down after
                 the worker is shut down.
-            nexus_operation_executor: Executor to use for non-async
+            nexus_task_executor: Executor to use for non-async
                 Nexus operations. This is required if any operation start methods
                 are non-`async def`. :py:class:`concurrent.futures.ThreadPoolExecutor`
                 is recommended.