Adds snippets for all step methods and event param

Author: Caio-Nogueira

src/content/docs/workflows/build/workers-api.mdx

@@ -35,7 +35,7 @@ The `run` method can optionally return data, which is available when querying th
 export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
 	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
 	  // Steps here
-		let someComputedState = step.do("my step", async () => { })
+		let someComputedState = await step.do("my step", async () => { })
 
 		// Optional: return state from our run() method
 		return someComputedState

src/content/docs/workflows/python/bindings.mdx

@@ -1,5 +1,5 @@
 ---
-title: Bind to a Workflow
+title: Interact with a Workflow
 pcx_content_type: concept
 sidebar:
   order: 3
@@ -11,7 +11,7 @@ import { WranglerConfig } from "~/components"
 
 The Python Workers platform leverages FFI to access bindings to Cloudflare resources. Refer to the [bindings](/workers/languages/python/ffi/#using-bindings-from-python-workers) documentation for more information.
 
-From the configuration perspective, there is no difference between configuring a Python workflow or a Javascript one.
+From the configuration perspective, enabling Python Workflows requires adding the `python_workflows` compatibility flag to your `wrangler.toml` file.
 
 <WranglerConfig>
 
@@ -20,6 +20,7 @@ From the configuration perspective, there is no difference between configuring a
 name = "workflows-starter"
 main = "src/index.ts"
 compatibility_date = "2024-10-22"
+compatibility_flags = ["python_workflows", "python_workers"]
 
 [[workflows]]
 # name of your workflow
@@ -32,28 +33,45 @@ class_name = "MyWorkflow"
 
 </WranglerConfig>
 
-### Create an instance via binding
 
-Note that `env` is a Javascript object exposed to the Python script via [JsProxy](https://pyodide.org/en/stable/usage/api/python-api/ffi.html#pyodide.ffi.JsProxy). You can
-access the binding like you would on a Javascript worker. Refer to the [Workflow binding documentation](/workflows/build/workers-api/#workflow) to learn more about the methods available.
-
-Let's consider the previous binding called `MY_WORKFLOW`. Here's how you would create a new instance:
+And this is how you use the payload in your workflow:
 
 ```python
-async def on_fetch(request, env):
-    instance = await env.MY_WORKFLOW.create()
-    return Response.json({"status": "success"})
+from pyodide.ffi import to_js
+
+class DemoWorkflowClass(WorkflowEntrypoint):
+    async def run(self, event, step):
+        @step.do('step-name')
+        async def first_step():
+            payload = event["payload"]
+            return payload
 ```
 
-### Pass a payload to a workflow instance
+
+## Workflow
+
+The `Workflow` binding gives you access to the [Workflow](/workflows/build/workers-api/#workflow) class. All its methods are available
+on the binding.
+
+Under the hood, the `Workflow` binding is a Javascript object that is exposed to the Python script via [JsProxy](https://pyodide.org/en/stable/usage/api/python-api/ffi.html#pyodide.ffi.JsProxy). 
+This means that the values returned by its methods are also `JsProxy` objects, and need to be converted back into Python objects using `python_from_rpc`.
+
+
+### `create`
+
+Create (trigger) a new instance of a given Workflow.
+
+* <code>create(options=None)</code>
+  * `options` - an **optional** dictionary of options to pass to the workflow instance. Should contain the same keys
+  as the [WorkflowInstanceCreateOptions](/workflows/build/workers-api/#workflowinstancecreateoptions) type.
 
 ```python
 from pyodide.ffi import to_js
 
 async def on_fetch(request, env, ctx):
     event = {"foo": "bar"}
-    # to_js here is required because the binding goes through ffi. Not something we can wrap or override on the runtime
-    await env.MY_WORKFLOW.create(to_js({"params": event}, dict_converter=Object.fromEntries))
+    options = to_js({"params": event}, dict_converter=Object.fromEntries)
+    await env.MY_WORKFLOW.create(options)
     return Response.json({"status": "success"})
 ```
 :::note
@@ -62,16 +80,74 @@ Values returned from steps need to be converted into Javascript objects using `t
 
 :::
 
+The `create` method returns a [`WorkflowInstance`](/workflows/build/workers-api/#workflowinstance) object, which can be used to query the status of the workflow instance. Note that this is a Javascript object, and not a Python object.
 
-And this is how you use the payload in your workflow:
+### `create_batch`
+
+Create (trigger) a batch of new workflow instances, up to 100 instances at a time. This is useful if you need to create multiple instances at once within the [instance creation limit](/workflows/reference/limits/).
+
+* <code>create_batch(batch)</code>
+  * `batch` - list of `WorkflowInstanceCreateOptions` to pass when creating an instance, including a user-provided ID and payload parameters.
+
+Each element of the `batch` list is expected to include both `id` and `params` properties:
 
 ```python
 from pyodide.ffi import to_js
 
-class DemoWorkflowClass(WorkflowEntrypoint):
-    async def on_run(self, event, step):
-        @step.do('step-name')
-        async def first_step():
-            payload = event["payload"]
-            return payload
-```
+# Create a new batch of 3 Workflow instances, each with its own ID and pass params to the Workflow instances
+listOfInstances = [
+  to_js({ "id": "id-abc123", "params": { "hello": "world-0" } }, dict_converter=Object.fromEntries),
+  to_js({ "id": "id-def456", "params": { "hello": "world-1" } }, dict_converter=Object.fromEntries),
+  to_js({ "id": "id-ghi789", "params": { "hello": "world-2" } }, dict_converter=Object.fromEntries)
+];
+
+await env.MY_WORKFLOW.create_batch(listOfInstances);
+```
+
+### `get`
+
+Get a workflow instance by ID.
+
+* <code>get(id)</code>
+  * `id` - the ID of the workflow instance to get.
+
+Returns a [`WorkflowInstance`](/workflows/build/workers-api/#workflowinstance) object, which can be used to query the status of the workflow instance.
+
+```python
+instance = await env.MY_WORKFLOW.get("abc-123")
+
+# FFI methods available for WorkflowInstance
+await instance.status()
+await instance.pause()
+await instance.resume()
+await instance.restart()
+await instance.terminate()
+```
+
+### `send_event`
+
+Send an event to a workflow instance.
+
+* <code>send_event(options)</code>
+  * `type` - the type of event to send to the workflow instance.
+  * `payload` - the payload to send to the workflow instance.
+
+```python
+from pyodide.ffi import to_js
+
+await env.MY_WORKFLOW.send_event(to_js({ "type": "my-event-type", "payload": { "foo": "bar" } }, dict_converter=Object.fromEntries))
+```
+
+:::note
+
+Values passed to `send_event` require explicit type translation into JS objects
+
+:::
+
+## REST API (HTTP)
+
+Refer to the [Workflows REST API documentation](/api/resources/workflows/subresources/instances/methods/create/).
+
+## Command line (CLI)
+
+Refer to the [CLI quick start](/workflows/get-started/cli-quick-start/) to learn more about how to manage and trigger Workflows via the command-line.

src/content/docs/workflows/python/dag.mdx

@@ -6,13 +6,13 @@ sidebar:
 
 ---
 
-The Python SDK supports DAG workflows in a declarative way, using the `step.do` decorator with the `depends` parameter to define dependencies (other steps that must complete before this step can run).
+The Python Workflows SDK supports DAG workflows in a declarative way, using the `step.do` decorator with the `depends` parameter to define dependencies (other steps that must complete before this step can run).
 
 ```python
 from workers import WorkflowEntrypoint
 
 class MyWorkflow(WorkflowEntrypoint):
-    async def on_run(self, event, step):
+    async def run(self, event, step):
         @step.do("dependency a")
         async def step_a():
             # do some work
@@ -31,6 +31,8 @@ class MyWorkflow(WorkflowEntrypoint):
         await my_final_step()
 ```
 
+On this example, `step_a` and `step_b` are run concurrently before execution of `my_final_step`, which depends on both of them.
+
 Having `concurrent=True` allows the dependencies to be resolved concurrently. If one of the callables passed to `depends` has already completed, it will be skipped and its return value will be reused.
 
-This pattern is usefull for diamond shaped workflows, where a step depends on two or more other steps that can run concurrently.
+This pattern is useful for diamond shaped workflows, where a step depends on two or more other steps that can run concurrently.

src/content/docs/workflows/python/index.mdx

@@ -1,5 +1,5 @@
 ---
-title: Python SDK
+title: Python Workflows SDK
 pcx_content_type: navigation
 sidebar:
   order: 5
@@ -13,20 +13,20 @@ Refer to [Python Workers](/workers/languages/python) for more information about
 
 :::caution[Python Workflows are in beta, as well as the underlying platform.]
 
-You must add the `python_workflows` compatibility flag to your `wrangler.toml` file, as well as `python_workers`.
+You must add both `python_workflows` and `python_workers` compatibility flags to your `wrangler.toml` file.
 
 Join the #python-workflows channel in the [Cloudflare Developers Discord](https://discord.cloudflare.com/) and let us know what you'd like to see next.
 :::
 
 ## Get Started
 
-Similarly to Typescript, the main entrypoint for a Python workflow is the [`WorkflowEntrypoint`](/workflows/build/workers-api/#workflowentrypoint) class. Your workflow logic should exist inside the [`run`](/workflows/build/workers-api/#run) handler. In a Python workflow, this handler is named `on_run`.
+The main entrypoint for a Python workflow is the [`WorkflowEntrypoint`](/workflows/build/workers-api/#workflowentrypoint) class. Your workflow logic should exist inside the [`run`](/workflows/build/workers-api/#run) handler.
 
 ```python
 from workers import WorkflowEntrypoint
 
 class MyWorkflow(WorkflowEntrypoint):
-    def on_run(self, event, step):
+    async def run(self, event, step):
         # steps here
 ```
 

src/content/docs/workflows/python/python-workers-api.mdx

@@ -0,0 +1,153 @@
+---
+title: Python Workers API
+pcx_content_type: concept
+sidebar:
+  order: 2
+
+---
+
+This guide covers the Python Workflows SDK, with instructions of how to build and create workflows using Python.
+
+## WorkflowEntrypoint
+
+The `WorkflowEntrypoint` is the main entrypoint for a Python workflow. It extends the `WorkflowEntrypoint` class, and implements the `run` method.
+
+```python
+from workers import WorkflowEntrypoint
+
+class MyWorkflow(WorkflowEntrypoint):
+    def run(self, event, step):
+        # steps here
+```
+
+## WorkflowStep
+
+* <code>step.do(name, depends=[], concurrent=False, config=None)</code> is a decorator that allows you to define a step in a workflow.
+  * `name` - the name of the step.
+  * `depends` - an optional list of steps that must complete before this step can run. See [DAG Workflows](/workflows/python/dag).
+  * `concurrent` - an optional boolean that indicates whether this step can run concurrently with other steps.
+  * `config` - an optional [`WorkflowStepConfig`](/workflows/build/workers-api/#workflowstepconfig) for configuring [step specific retry behaviour](/workflows/build/sleeping-and-retrying/). This is passed as a Python dictionary and then type translated into a `WorkflowStepConfig` object.
+
+```python
+from workers import WorkflowEntrypoint
+
+class MyWorkflow(WorkflowEntrypoint):
+    async def run(self, event, step):
+        @step.do("my first step")
+        async def my_first_step():
+            # do some work
+            return "Hello World!"
+
+        await my_first_step()
+```
+
+Note that the decorator doesn't make the call to the step, it just returns a callable that can be used to invoke the step. You have to call the callable to make the step run.
+
+When returning state from a step, you must make sure that the returned value is serializable. Since steps run through an FFI layer, the returned value gets type translated via [FFI.](https://pyodide.org/en/stable/usage/api/python-api/ffi.html#pyodide.ffi.to_js)
+Refer to [Pyodide's documentation](https://pyodide.org/en/stable/usage/type-conversions.html#type-translations-pyproxy-to-js) regarding type conversions for more information.
+
+* <code>step.sleep(name, duration)</code>
+
+  * `name` - the name of the step.
+  * `duration` - the duration to sleep until, in either seconds or as a `WorkflowDuration` compatible string.
+
+```python
+async def run(self, event, step):
+    await step.sleep("my-sleep-step", "10 seconds")
+```
+
+* <code>step.sleep_until(name, timestamp)</code>
+
+  * `name` - the name of the step.
+  * `timestamp` - a `datetime.datetime` object or seconds from the Unix epoch to sleep the workflow instance until.
+
+```python
+async def run(self, event, step):
+    await step.sleep_until("my-sleep-step", datetime.datetime.now() + datetime.timedelta(seconds=10))
+```
+
+* <code>step.wait_for_event(name, event_type, timeout="24 hours")</code>
+
+  * `name` - the name of the step.
+  * `event_type` - the type of event to wait for.
+  * `timeout` - the timeout for the `wait_for_event` call. The default timeout is 24 hours.
+
+```python
+async def run(self, event, step):
+    await step.wait_for_event("my-wait-for-event-step", "my-event-type")
+```
+
+
+### `event` parameter
+
+The `event` parameter is a dictionary that contains the payload passed to the workflow instance, along with other metadata:
+
+* <code>payload</code> - the payload passed to the workflow instance.
+* <code>timestamp</code> - the timestamp that the workflow was triggered.
+* <code>instanceId</code> - the ID of the current workflow instance.
+* <code>workflowName</code> - the name of the workflow.
+
+## Error Handling
+
+Workflows semantics allow users to catch exceptions that get thrown to the top level.
+
+Catching specific exceptions within an `except` block may not work, as some Python errors will not be re-instantiated into the same type of error when they are passed through the RPC layer.
+
+:::note
+
+Some built-in Python errors (e.g.: `ValueError`, `TypeError`) will work correctly. User defined exceptions, as well as other built-in Python errors will not and should be caught with the `Exception` class.
+
+:::
+
+```python
+async def run(self, event, step):
+    async def try_step(fn):
+        try:
+            return await fn()
+        except Exception as e:
+            print(f"Successfully caught {type(e).__name__}: {e}")
+
+    @step.do("my_failing")
+    async def my_failing():
+        print("Executing my_failing")
+        raise TypeError("Intentional error in my_failing")
+
+    await try_step(my_failing)
+```
+
+### NonRetryableError
+
+The Python Workflows SDK provides a `NonRetryableError` class that can be used to signal that a step should not be retried.
+
+```python
+from workers.workflows import NonRetryableError
+
+raise NonRetryableError(message)
+```
+
+## Configure a workflow instance
+
+You can bind a step to a specific retry policy by passing a `WorkflowStepConfig` object to the `config` parameter of the `step.do` decorator.
+With Python Workflows, you need to make sure that your `dict` respects the [`WorkflowStepConfig`](/workflows/build/workers-api/#workflowstepconfig) type.
+
+```python
+class DemoWorkflowClass(WorkflowEntrypoint):
+    async def run(self, event, step):
+        @step.do('step-name', config={"retries": {"limit": 1, "delay": "10 seconds"}})
+        async def first_step():
+            # do some work
+            pass
+```
+
+### Create an instance via binding
+
+Note that `env` is a Javascript object exposed to the Python script via [JsProxy](https://pyodide.org/en/stable/usage/api/python-api/ffi.html#pyodide.ffi.JsProxy). You can
+access the binding like you would on a Javascript worker. Refer to the [Workflow binding documentation](/workflows/build/workers-api/#workflow) to learn more about the methods available.
+
+Let's consider the previous binding called `MY_WORKFLOW`. Here's how you would create a new instance:
+
+```python
+async def on_fetch(request, env):
+    instance = await env.MY_WORKFLOW.create()
+    return Response.json({"status": "success"})
+```