feat(helpers): add new_data_part, new_raw_part, and new_url_part helpers

Part.data is google.protobuf.Value in the v1.0 spec, which requires a
non-obvious ParseDict dance to construct from a plain dict. Add
new_data_part() to hide that complexity. Also add new_raw_part() and
new_url_part() to cover the remaining non-text Part variants that had
no helpers, keeping the API consistent with new_text_message() et al.

Author: martimfasantos

src/a2a/helpers/proto_helpers.py

@@ -3,6 +3,10 @@
 import uuid
 
 from collections.abc import Sequence
+from typing import Any
+
+from google.protobuf import struct_pb2
+from google.protobuf.json_format import ParseDict
 
 from a2a.types.a2a_pb2 import (
     Artifact,
@@ -141,6 +145,62 @@ def new_task(
 # --- Part Helpers ---
 
 
+def new_data_part(data: dict[str, Any]) -> Part:
+    """Creates a Part with structured data (google.protobuf.Value).
+
+    Args:
+        data: A dict to embed as structured data.
+
+    Returns:
+        A Part with the data field set.
+    """
+    return Part(data=ParseDict(data, struct_pb2.Value()))
+
+
+def new_raw_part(
+    raw: bytes,
+    media_type: str | None = None,
+    filename: str | None = None,
+) -> Part:
+    """Creates a Part with raw bytes content.
+
+    Args:
+        raw: The raw bytes content.
+        media_type: Optional MIME type (e.g. 'image/png').
+        filename: Optional filename.
+
+    Returns:
+        A Part with the raw field set.
+    """
+    return Part(
+        raw=raw,
+        media_type=media_type or '',
+        filename=filename or '',
+    )
+
+
+def new_url_part(
+    url: str,
+    media_type: str | None = None,
+    filename: str | None = None,
+) -> Part:
+    """Creates a Part with a URL pointing to file content.
+
+    Args:
+        url: The URL to the file content.
+        media_type: Optional MIME type (e.g. 'image/png').
+        filename: Optional filename.
+
+    Returns:
+        A Part with the url field set.
+    """
+    return Part(
+        url=url,
+        media_type=media_type or '',
+        filename=filename or '',
+    )
+
+
 def get_text_parts(parts: Sequence[Part]) -> list[str]:
     """Extracts text content from all text Parts."""
     return [part.text for part in parts if part.HasField('text')]

tests/helpers/test_proto_helpers.py

@@ -11,6 +11,9 @@
     new_task_from_user_message,
     new_task,
     get_text_parts,
+    new_data_part,
+    new_raw_part,
+    new_url_part,
     new_text_status_update_event,
     new_text_artifact_update_event,
     get_stream_response_text,
@@ -149,6 +152,49 @@ def test_get_text_parts() -> None:
     assert get_text_parts(parts) == ['hello', 'world']
 
 
+def test_new_data_part_from_dict() -> None:
+    part = new_data_part({'key': 'value', 'count': 42})
+    assert part.HasField('data')
+    assert part.data.struct_value.fields['key'].string_value == 'value'
+    assert part.data.struct_value.fields['count'].number_value == 42
+
+
+def test_new_raw_part() -> None:
+    part = new_raw_part(b'\x89PNG', media_type='image/png', filename='img.png')
+    assert part.HasField('raw')
+    assert part.raw == b'\x89PNG'
+    assert part.media_type == 'image/png'
+    assert part.filename == 'img.png'
+
+
+def test_new_raw_part_minimal() -> None:
+    part = new_raw_part(b'data')
+    assert part.HasField('raw')
+    assert part.raw == b'data'
+    assert part.media_type == ''
+    assert part.filename == ''
+
+
+def test_new_url_part() -> None:
+    part = new_url_part(
+        'https://example.com/file.pdf',
+        media_type='application/pdf',
+        filename='file.pdf',
+    )
+    assert part.HasField('url')
+    assert part.url == 'https://example.com/file.pdf'
+    assert part.media_type == 'application/pdf'
+    assert part.filename == 'file.pdf'
+
+
+def test_new_url_part_minimal() -> None:
+    part = new_url_part('https://example.com/img.png')
+    assert part.HasField('url')
+    assert part.url == 'https://example.com/img.png'
+    assert part.media_type == ''
+    assert part.filename == ''
+
+
 # --- Event & Stream Helpers Tests ---