refactor(utils): move part helpers & add artifact text extractor (#517)

# Description

This pull request refactors utility functions for handling `Part`
objects by moving them from `src/a2a/utils/message.py` to a new
dedicated module `src/a2a/utils/parts.py`. It also introduces a new
helper function for extracting text from `Artifacts` and updates imports
and exports to reflect these changes. The goal is to improve code
organization and clarity by grouping similar functionality.

**Refactoring and organization:**

* Moved the functions `get_text_parts`, `get_data_parts`, and
`get_file_parts` from `src/a2a/utils/message.py` into a new module
`src/a2a/utils/parts.py`, providing better separation of concerns for
part-handling utilities.
[[1]](diffhunk://#diff-75cd067f29c32392a29e62de13b907467f6ed491a66bfdb56cdae0eafe70b2fdL67-L102)
[[2]](diffhunk://#diff-02db7e35da2780f67c1bf288d503c6f7702e1f85542023b230bd798cee46cb21R1-R50)
* Updated imports in `src/a2a/utils/__init__.py` to re-export these
part-handling functions from the new `parts` module, and removed their
previous import from the `message` module.
[[1]](diffhunk://#diff-58d75f7b41efab15332246cd45437bba43a3bed62236bd5a9f8dfb50991f849aR7-R17)
[[2]](diffhunk://#diff-58d75f7b41efab15332246cd45437bba43a3bed62236bd5a9f8dfb50991f849aL20-L27)
[[3]](diffhunk://#diff-58d75f7b41efab15332246cd45437bba43a3bed62236bd5a9f8dfb50991f849aR47)

**New functionality:**

* Added the new function `get_artifact_text` to
`src/a2a/utils/artifact.py` for extracting and joining all text content
from an artifact's parts, using the refactored `get_text_parts`.
[[1]](diffhunk://#diff-c47436a54fc84fd5eb8eed08c4e86fdb76e4a5a753191393712ae86f2b8f0f04R74-R86)
[[2]](diffhunk://#diff-c47436a54fc84fd5eb8eed08c4e86fdb76e4a5a753191393712ae86f2b8f0f04R8)
[[3]](diffhunk://#diff-58d75f7b41efab15332246cd45437bba43a3bed62236bd5a9f8dfb50991f849aR7-R17)
[[4]](diffhunk://#diff-58d75f7b41efab15332246cd45437bba43a3bed62236bd5a9f8dfb50991f849aR47)

These changes improve maintainability by clearly separating
message-related and part-related utilities, and by introducing a helper
for artifact text extraction.

---

BEGIN_COMMIT_OVERRIDE
refactor(utils): move part helpers to their own file
feat: add `get_artifact_text()` helper method

Release-As: 0.3.10
END_COMMIT_OVERRIDE

Author: martimfasantos

src/a2a/utils/__init__.py

@@ -1,6 +1,7 @@
 """Utility functions for the A2A Python SDK."""
 
 from a2a.utils.artifact import (
+    get_artifact_text,
     new_artifact,
     new_data_artifact,
     new_text_artifact,
@@ -18,13 +19,15 @@
     create_task_obj,
 )
 from a2a.utils.message import (
-    get_data_parts,
-    get_file_parts,
     get_message_text,
-    get_text_parts,
     new_agent_parts_message,
     new_agent_text_message,
 )
+from a2a.utils.parts import (
+    get_data_parts,
+    get_file_parts,
+    get_text_parts,
+)
 from a2a.utils.task import (
     completed_task,
     new_task,
@@ -41,6 +44,7 @@
     'build_text_artifact',
     'completed_task',
     'create_task_obj',
+    'get_artifact_text',
     'get_data_parts',
     'get_file_parts',
     'get_message_text',

src/a2a/utils/artifact.py

@@ -5,6 +5,7 @@
 from typing import Any
 
 from a2a.types import Artifact, DataPart, Part, TextPart
+from a2a.utils.parts import get_text_parts
 
 
 def new_artifact(
@@ -70,3 +71,16 @@ def new_data_artifact(
         name,
         description,
     )
+
+
+def get_artifact_text(artifact: Artifact, delimiter: str = '\n') -> str:
+    """Extracts and joins all text content from an Artifact's parts.
+
+    Args:
+        artifact: The `Artifact` object.
+        delimiter: The string to use when joining text from multiple TextParts.
+
+    Returns:
+        A single string containing all text content, or an empty string if no text parts are found.
+    """
+    return delimiter.join(get_text_parts(artifact.parts))

src/a2a/utils/message.py

@@ -2,18 +2,13 @@
 
 import uuid
 
-from typing import Any
-
 from a2a.types import (
-    DataPart,
-    FilePart,
-    FileWithBytes,
-    FileWithUri,
     Message,
     Part,
     Role,
     TextPart,
 )
+from a2a.utils.parts import get_text_parts
 
 
 def new_agent_text_message(
@@ -64,42 +59,6 @@ def new_agent_parts_message(
     )
 
 
-def get_text_parts(parts: list[Part]) -> list[str]:
-    """Extracts text content from all TextPart objects in a list of Parts.
-
-    Args:
-        parts: A list of `Part` objects.
-
-    Returns:
-        A list of strings containing the text content from any `TextPart` objects found.
-    """
-    return [part.root.text for part in parts if isinstance(part.root, TextPart)]
-
-
-def get_data_parts(parts: list[Part]) -> list[dict[str, Any]]:
-    """Extracts dictionary data from all DataPart objects in a list of Parts.
-
-    Args:
-        parts: A list of `Part` objects.
-
-    Returns:
-        A list of dictionaries containing the data from any `DataPart` objects found.
-    """
-    return [part.root.data for part in parts if isinstance(part.root, DataPart)]
-
-
-def get_file_parts(parts: list[Part]) -> list[FileWithBytes | FileWithUri]:
-    """Extracts file data from all FilePart objects in a list of Parts.
-
-    Args:
-        parts: A list of `Part` objects.
-
-    Returns:
-        A list of `FileWithBytes` or `FileWithUri` objects containing the file data from any `FilePart` objects found.
-    """
-    return [part.root.file for part in parts if isinstance(part.root, FilePart)]
-
-
 def get_message_text(message: Message, delimiter: str = '\n') -> str:
     """Extracts and joins all text content from a Message's parts.
 

src/a2a/utils/parts.py

@@ -0,0 +1,48 @@
+"""Utility functions for creating and handling A2A Parts objects."""
+
+from typing import Any
+
+from a2a.types import (
+    DataPart,
+    FilePart,
+    FileWithBytes,
+    FileWithUri,
+    Part,
+    TextPart,
+)
+
+
+def get_text_parts(parts: list[Part]) -> list[str]:
+    """Extracts text content from all TextPart objects in a list of Parts.
+
+    Args:
+        parts: A list of `Part` objects.
+
+    Returns:
+        A list of strings containing the text content from any `TextPart` objects found.
+    """
+    return [part.root.text for part in parts if isinstance(part.root, TextPart)]
+
+
+def get_data_parts(parts: list[Part]) -> list[dict[str, Any]]:
+    """Extracts dictionary data from all DataPart objects in a list of Parts.
+
+    Args:
+        parts: A list of `Part` objects.
+
+    Returns:
+        A list of dictionaries containing the data from any `DataPart` objects found.
+    """
+    return [part.root.data for part in parts if isinstance(part.root, DataPart)]
+
+
+def get_file_parts(parts: list[Part]) -> list[FileWithBytes | FileWithUri]:
+    """Extracts file data from all FilePart objects in a list of Parts.
+
+    Args:
+        parts: A list of `Part` objects.
+
+    Returns:
+        A list of `FileWithBytes` or `FileWithUri` objects containing the file data from any `FilePart` objects found.
+    """
+    return [part.root.file for part in parts if isinstance(part.root, FilePart)]

tests/utils/test_artifact.py

@@ -3,8 +3,14 @@
 
 from unittest.mock import patch
 
-from a2a.types import DataPart, Part, TextPart
+from a2a.types import (
+    Artifact,
+    DataPart,
+    Part,
+    TextPart,
+)
 from a2a.utils.artifact import (
+    get_artifact_text,
     new_artifact,
     new_data_artifact,
     new_text_artifact,
@@ -83,5 +89,71 @@ def test_new_data_artifact_assigns_name_description(self):
         self.assertEqual(artifact.description, description)
 
 
+class TestGetArtifactText(unittest.TestCase):
+    def test_get_artifact_text_single_part(self):
+        # Setup
+        artifact = Artifact(
+            name='test-artifact',
+            parts=[Part(root=TextPart(text='Hello world'))],
+            artifact_id='test-artifact-id',
+        )
+
+        # Exercise
+        result = get_artifact_text(artifact)
+
+        # Verify
+        assert result == 'Hello world'
+
+    def test_get_artifact_text_multiple_parts(self):
+        # Setup
+        artifact = Artifact(
+            name='test-artifact',
+            parts=[
+                Part(root=TextPart(text='First line')),
+                Part(root=TextPart(text='Second line')),
+                Part(root=TextPart(text='Third line')),
+            ],
+            artifact_id='test-artifact-id',
+        )
+
+        # Exercise
+        result = get_artifact_text(artifact)
+
+        # Verify - default delimiter is newline
+        assert result == 'First line\nSecond line\nThird line'
+
+    def test_get_artifact_text_custom_delimiter(self):
+        # Setup
+        artifact = Artifact(
+            name='test-artifact',
+            parts=[
+                Part(root=TextPart(text='First part')),
+                Part(root=TextPart(text='Second part')),
+                Part(root=TextPart(text='Third part')),
+            ],
+            artifact_id='test-artifact-id',
+        )
+
+        # Exercise
+        result = get_artifact_text(artifact, delimiter=' | ')
+
+        # Verify
+        assert result == 'First part | Second part | Third part'
+
+    def test_get_artifact_text_empty_parts(self):
+        # Setup
+        artifact = Artifact(
+            name='test-artifact',
+            parts=[],
+            artifact_id='test-artifact-id',
+        )
+
+        # Exercise
+        result = get_artifact_text(artifact)
+
+        # Verify
+        assert result == ''
+
+
 if __name__ == '__main__':
     unittest.main()