From 2ff543e8768957a3030802c269f263e4bcc6aa5d Mon Sep 17 00:00:00 2001
From: Eric Zhu <ekzhu@users.noreply.github.com>
Date: Mon, 6 Jan 2025 10:06:54 -0800
Subject: [PATCH] Add missing API doc for Python code execution tool (#4901)

* Add missing API doc for Python code execution tool

* wip

* Add API doc for the executor tool

---------

Co-authored-by: Jack Gerrits <jackgerrits@users.noreply.github.com>
---
 .../autogen-core/docs/src/reference/index.md  |  1 +
 .../autogen_ext.tools.code_execution.rst      |  8 ++++
 .../tools/code_execution/_code_execution.py   | 43 +++++++++++++++++++
 3 files changed, 52 insertions(+)
 create mode 100644 python/packages/autogen-core/docs/src/reference/python/autogen_ext.tools.code_execution.rst

diff --git a/python/packages/autogen-core/docs/src/reference/index.md b/python/packages/autogen-core/docs/src/reference/index.md
index cfe36eded2c..2742ddbc383 100644
--- a/python/packages/autogen-core/docs/src/reference/index.md
+++ b/python/packages/autogen-core/docs/src/reference/index.md
@@ -49,6 +49,7 @@ python/autogen_ext.teams.magentic_one
 python/autogen_ext.models.openai
 python/autogen_ext.models.replay
 python/autogen_ext.tools.langchain
+python/autogen_ext.tools.code_execution
 python/autogen_ext.code_executors.local
 python/autogen_ext.code_executors.docker
 python/autogen_ext.code_executors.azure
diff --git a/python/packages/autogen-core/docs/src/reference/python/autogen_ext.tools.code_execution.rst b/python/packages/autogen-core/docs/src/reference/python/autogen_ext.tools.code_execution.rst
new file mode 100644
index 00000000000..18dce6613bf
--- /dev/null
+++ b/python/packages/autogen-core/docs/src/reference/python/autogen_ext.tools.code_execution.rst
@@ -0,0 +1,8 @@
+autogen\_ext.tools.code\_execution
+==================================
+
+
+.. automodule:: autogen_ext.tools.code_execution
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/python/packages/autogen-ext/src/autogen_ext/tools/code_execution/_code_execution.py b/python/packages/autogen-ext/src/autogen_ext/tools/code_execution/_code_execution.py
index 95e8fa34aac..a0669e5c71f 100644
--- a/python/packages/autogen-ext/src/autogen_ext/tools/code_execution/_code_execution.py
+++ b/python/packages/autogen-ext/src/autogen_ext/tools/code_execution/_code_execution.py
@@ -18,6 +18,49 @@ def ser_model(self) -> str:
 
 
 class PythonCodeExecutionTool(BaseTool[CodeExecutionInput, CodeExecutionResult]):
+    """A tool that executes Python code in a code executor and returns output.
+
+    Example executors:
+
+    * :class:`autogen_ext.code_executors.local.LocalCommandLineCodeExecutor`
+    * :class:`autogen_ext.code_executors.docker.DockerCommandLineCodeExecutor`
+    * :class:`autogen_ext.code_executors.azure.ACADynamicSessionsCodeExecutor`
+
+    Example usage:
+
+    .. code-block:: bash
+
+        pip install "autogen-agentchat==0.4.0.dev13" "autogen-ext[openai]==0.4.0.dev13" "yfinance" "matplotlib"
+
+    .. code-block:: python
+
+        import asyncio
+        from autogen_agentchat.agents import AssistantAgent
+        from autogen_agentchat.ui import Console
+        from autogen_ext.models.openai import OpenAIChatCompletionClient
+        from autogen_ext.code_executors.local import LocalCommandLineCodeExecutor
+        from autogen_ext.tools.code_execution import PythonCodeExecutionTool
+
+
+        async def main() -> None:
+            tool = PythonCodeExecutionTool(LocalCommandLineCodeExecutor(work_dir="coding"))
+            agent = AssistantAgent(
+                "assistant", OpenAIChatCompletionClient(model="gpt-4o"), tools=[tool], reflect_on_tool_use=True
+            )
+            await Console(
+                agent.run_stream(
+                    task="Create a plot of MSFT stock prices in 2024 and save it to a file. Use yfinance and matplotlib."
+                )
+            )
+
+
+        asyncio.run(main())
+
+
+    Args:
+        executor (CodeExecutor): The code executor that will be used to execute the code blocks.
+    """
+
     def __init__(self, executor: CodeExecutor):
         super().__init__(CodeExecutionInput, CodeExecutionResult, "CodeExecutor", "Execute Python code blocks.")
         self._executor = executor