Clarify optional system Nexus payload visitation

Author: tconley1428

scripts/gen_payload_visitor.py

@@ -225,14 +225,14 @@ async def visit(
         finally:
             await bounded.drain()
 
-    async def _visit_system_nexus_payload(
+    async def _visit_nexus_operation_input_payload(
         self,
         fs: VisitorFunctions,
         service: str,
         operation: str,
         payload: Payload,
     ) -> None:
-        new_payload = await temporalio.nexus.system.visit_payload(
+        new_payload = await temporalio.nexus.system.maybe_visit_payload(
             service,
             operation,
             payload,
@@ -446,7 +446,7 @@ def walk(self, desc: Descriptor) -> bool:
                     _, field_name, service_expr, operation_expr, payload_expr = item
                     lines.append(
                         f'        if o.HasField("{field_name}"):\n'
-                        "            await self._visit_system_nexus_payload(\n"
+                        "            await self._visit_nexus_operation_input_payload(\n"
                         f"                fs, {service_expr}, {operation_expr}, {payload_expr}\n"
                         "            )"
                     )

temporalio/bridge/_visitor.py

@@ -107,14 +107,14 @@ async def visit(self, fs: VisitorFunctions, root: Any) -> None:
         finally:
             await bounded.drain()
 
-    async def _visit_system_nexus_payload(
+    async def _visit_nexus_operation_input_payload(
         self,
         fs: VisitorFunctions,
         service: str,
         operation: str,
         payload: Payload,
     ) -> None:
-        new_payload = await temporalio.nexus.system.visit_payload(
+        new_payload = await temporalio.nexus.system.maybe_visit_payload(
             service,
             operation,
             payload,
@@ -528,7 +528,9 @@ async def _visit_coresdk_workflow_commands_ScheduleNexusOperation(
         self, fs: VisitorFunctions, o: Any
     ):
         if o.HasField("input"):
-            await self._visit_system_nexus_payload(fs, o.service, o.operation, o.input)
+            await self._visit_nexus_operation_input_payload(
+                fs, o.service, o.operation, o.input
+            )
 
     async def _visit_coresdk_workflow_commands_WorkflowCommand(
         self, fs: VisitorFunctions, o: Any

temporalio/nexus/system/__init__.py

@@ -28,14 +28,14 @@ def _operation(
     return workflow_service.__nexus_operation_registry__.get((service, operation))
 
 
-async def visit_payload(
+async def maybe_visit_payload(
     service: str,
     operation: str,
     payload: temporalio.api.common.v1.Payload,
     visitor_functions: VisitorFunctions,
     skip_search_attributes: bool,
 ) -> temporalio.api.common.v1.Payload | None:
-    """Visit nested payloads inside a recognized system Nexus envelope."""
+    """Visit nested payloads if the payload is a recognized system Nexus envelope."""
     operation_def = _operation(service, operation)
     if operation_def is None:
         return None
@@ -69,6 +69,6 @@ def get_payload_converter() -> temporalio.converter.PayloadConverter:
 __all__ = [
     "get_payload_converter",
     "is_system_operation",
+    "maybe_visit_payload",
     "SystemNexusPayloadConverter",
-    "visit_payload",
 ]

temporalio/nexus/system/_payload_visitor.py

@@ -107,14 +107,14 @@ async def visit(self, fs: VisitorFunctions, root: Any) -> None:
         finally:
             await bounded.drain()
 
-    async def _visit_system_nexus_payload(
+    async def _visit_nexus_operation_input_payload(
         self,
         fs: VisitorFunctions,
         service: str,
         operation: str,
         payload: Payload,
     ) -> None:
-        new_payload = await temporalio.nexus.system.visit_payload(
+        new_payload = await temporalio.nexus.system.maybe_visit_payload(
             service,
             operation,
             payload,