Prefer start_to_close_timeout

references/python/advanced-features.md

@@ -13,7 +13,7 @@ class BatchProcessingWorkflow:
             # Process next batch
             state = await workflow.execute_activity(
                 process_batch, state,
-                schedule_to_close_timeout=timedelta(minutes=5),
+                start_to_close_timeout=timedelta(minutes=5),
             )
 
             # Check history size and continue-as-new if needed

references/python/error-handling.md

@@ -38,7 +38,7 @@ async def run(self) -> str:
     try:
         return await workflow.execute_activity(
             risky_activity,
-            schedule_to_close_timeout=timedelta(minutes=5),
+            start_to_close_timeout=timedelta(minutes=5),
         )
     except ActivityError as e:
         workflow.logger.error(f"Activity failed: {e}")
@@ -53,7 +53,7 @@ from temporalio.common import RetryPolicy
 
 result = await workflow.execute_activity(
     my_activity,
-    schedule_to_close_timeout=timedelta(minutes=10),
+    start_to_close_timeout=timedelta(minutes=10),
     retry_policy=RetryPolicy(
         initial_interval=timedelta(seconds=1),
         backoff_coefficient=2.0,
@@ -120,7 +120,7 @@ class OrderWorkflow:
         if not self._payment_completed:
             self._transaction_id = await workflow.execute_activity(
                 charge_payment, order.id, order.total,
-                schedule_to_close_timeout=timedelta(minutes=5),
+                start_to_close_timeout=timedelta(minutes=5),
             )
             self._payment_completed = True
 

references/python/gotchas.md

@@ -291,14 +291,14 @@ async def call_api():
 # BAD - Gives up too easily
 result = await workflow.execute_activity(
     flaky_api_call,
-    schedule_to_close_timeout=timedelta(seconds=30),
+    start_to_close_timeout=timedelta(seconds=30),
     retry_policy=RetryPolicy(maximum_attempts=1),
 )
 
 # GOOD - Resilient to transient failures
 result = await workflow.execute_activity(
     flaky_api_call,
-    schedule_to_close_timeout=timedelta(minutes=10),
+    start_to_close_timeout=timedelta(minutes=10),
     retry_policy=RetryPolicy(
         initial_interval=timedelta(seconds=1),
         maximum_interval=timedelta(minutes=1),
@@ -308,6 +308,8 @@ result = await workflow.execute_activity(
 )
 ```
 
+Generally, prefer to use the default RetryPolicy.
+
 ## Heartbeating
 
 ### Forgetting to Heartbeat Long Activities

references/python/observability.md

@@ -19,7 +19,7 @@ class MyWorkflow:
 
         result = await workflow.execute_activity(
             my_activity,
-            schedule_to_close_timeout=timedelta(minutes=5),
+            start_to_close_timeout=timedelta(minutes=5),
         )
 
         workflow.logger.info("Activity completed", extra={"result": result})

references/python/patterns.md

@@ -86,7 +86,7 @@ class StatusWorkflow:
             self._progress = i
             await workflow.execute_activity(
                 process_item, i,
-                schedule_to_close_timeout=timedelta(minutes=1)
+                start_to_close_timeout=timedelta(minutes=1)
             )
         self._status = "completed"
         return "done"
@@ -166,7 +166,7 @@ async def run(self, items: list[str]) -> list[str]:
     tasks = [
         workflow.execute_activity(
             process_item, item,
-            schedule_to_close_timeout=timedelta(minutes=5)
+            start_to_close_timeout=timedelta(minutes=5)
         )
         for item in items
     ]
@@ -232,25 +232,25 @@ async def run(self, order: Order) -> str:
     try:
         await workflow.execute_activity(
             reserve_inventory, order,
-            schedule_to_close_timeout=timedelta(minutes=5)
+            start_to_close_timeout=timedelta(minutes=5)
         )
         compensations.append(lambda: workflow.execute_activity(
             release_inventory, order,
-            schedule_to_close_timeout=timedelta(minutes=5)
+            start_to_close_timeout=timedelta(minutes=5)
         ))
 
         await workflow.execute_activity(
             charge_payment, order,
-            schedule_to_close_timeout=timedelta(minutes=5)
+            start_to_close_timeout=timedelta(minutes=5)
         )
         compensations.append(lambda: workflow.execute_activity(
             refund_payment, order,
-            schedule_to_close_timeout=timedelta(minutes=5)
+            start_to_close_timeout=timedelta(minutes=5)
         ))
 
         await workflow.execute_activity(
             ship_order, order,
-            schedule_to_close_timeout=timedelta(minutes=5)
+            start_to_close_timeout=timedelta(minutes=5)
         )
 
         return "Order completed"
@@ -279,7 +279,7 @@ async def run(self) -> str:
     try:
         await workflow.execute_activity(
             long_running_activity,
-            schedule_to_close_timeout=timedelta(hours=1),
+            start_to_close_timeout=timedelta(hours=1),
         )
         return "completed"
     except asyncio.CancelledError:
@@ -288,7 +288,7 @@ async def run(self) -> str:
         # Cleanup activities still run even after cancellation
         await workflow.execute_activity(
             cleanup_activity,
-            schedule_to_close_timeout=timedelta(minutes=5),
+            start_to_close_timeout=timedelta(minutes=5),
         )
         raise  # Re-raise to mark workflow as cancelled
 ```
@@ -375,13 +375,13 @@ async def run(self) -> str:
         # New implementation
         greeting = await workflow.execute_activity(
             new_greet_activity,
-            schedule_to_close_timeout=timedelta(minutes=1)
+            start_to_close_timeout=timedelta(minutes=1)
         )
     else:
         # Old implementation (for replay)
         greeting = await workflow.execute_activity(
             old_greet_activity,
-            schedule_to_close_timeout=timedelta(minutes=1)
+            start_to_close_timeout=timedelta(minutes=1)
         )
 
     return greeting
@@ -423,7 +423,7 @@ async def run(self) -> str:
     result = await workflow.execute_local_activity(
         quick_lookup,
         "key",
-        schedule_to_close_timeout=timedelta(seconds=5),
+        start_to_close_timeout=timedelta(seconds=5),
     )
     return result
 ```

references/python/python.md

@@ -28,7 +28,7 @@ class GreetingWorkflow:
     @workflow.run
     async def run(self, name: str) -> str:
         return await workflow.execute_activity(
-            greet, name, schedule_to_close_timeout=timedelta(seconds=30)
+            greet, name, start_to_close_timeout=timedelta(seconds=30)
         )
 ```
 

references/python/sandbox.md

@@ -62,12 +62,12 @@ class OrderWorkflow:
         await workflow.execute_activity(
             process_payment,
             order_id,
-            schedule_to_close_timeout=timedelta(minutes=5),
+            start_to_close_timeout=timedelta(minutes=5),
         )
         return await workflow.execute_activity(
             ship_order,
             order_id,
-            schedule_to_close_timeout=timedelta(minutes=10),
+            start_to_close_timeout=timedelta(minutes=10),
         )
 ```
 

references/python/versioning.md

@@ -25,13 +25,13 @@ class ShippingWorkflow:
             # New code path
             await workflow.execute_activity(
                 send_email,
-                schedule_to_close_timeout=timedelta(minutes=5),
+                start_to_close_timeout=timedelta(minutes=5),
             )
         else:
             # Old code path (for replay of existing workflows)
             await workflow.execute_activity(
                 send_fax,
-                schedule_to_close_timeout=timedelta(minutes=5),
+                start_to_close_timeout=timedelta(minutes=5),
             )
 ```
 
@@ -56,14 +56,14 @@ class OrderWorkflow:
             await workflow.execute_activity(
                 check_fraud,
                 order,
-                schedule_to_close_timeout=timedelta(minutes=2),
+                start_to_close_timeout=timedelta(minutes=2),
             )
 
         # Original payment logic runs for both paths
         return await workflow.execute_activity(
             process_payment,
             order,
-            schedule_to_close_timeout=timedelta(minutes=5),
+            start_to_close_timeout=timedelta(minutes=5),
         )
 ```
 
@@ -82,13 +82,13 @@ class OrderWorkflow:
         await workflow.execute_activity(
             check_fraud,
             order,
-            schedule_to_close_timeout=timedelta(minutes=2),
+            start_to_close_timeout=timedelta(minutes=2),
         )
 
         return await workflow.execute_activity(
             process_payment,
             order,
-            schedule_to_close_timeout=timedelta(minutes=5),
+            start_to_close_timeout=timedelta(minutes=5),
         )
 ```
 
@@ -104,13 +104,13 @@ class OrderWorkflow:
         await workflow.execute_activity(
             check_fraud,
             order,
-            schedule_to_close_timeout=timedelta(minutes=2),
+            start_to_close_timeout=timedelta(minutes=2),
         )
 
         return await workflow.execute_activity(
             process_payment,
             order,
-            schedule_to_close_timeout=timedelta(minutes=5),
+            start_to_close_timeout=timedelta(minutes=5),
         )
 ```
 
@@ -127,19 +127,19 @@ class NotificationWorkflow:
             # Latest: SMS notifications
             await workflow.execute_activity(
                 send_sms,
-                schedule_to_close_timeout=timedelta(minutes=5),
+                start_to_close_timeout=timedelta(minutes=5),
             )
         elif workflow.patched("use-email"):
             # Intermediate: Email notifications
             await workflow.execute_activity(
                 send_email,
-                schedule_to_close_timeout=timedelta(minutes=5),
+                start_to_close_timeout=timedelta(minutes=5),
             )
         else:
             # Original: Fax notifications
             await workflow.execute_activity(
                 send_fax,
-                schedule_to_close_timeout=timedelta(minutes=5),
+                start_to_close_timeout=timedelta(minutes=5),
             )
 ```
 
@@ -274,7 +274,7 @@ class StableWorkflow:
         # This workflow will always run on its assigned version
         return await workflow.execute_activity(
             process_order,
-            schedule_to_close_timeout=timedelta(minutes=5),
+            start_to_close_timeout=timedelta(minutes=5),
         )
 ```