Merge branch 'main' into feat/fastapi-routes-helpers

Author: martimfasantos

.github/workflows/linter.yaml

@@ -6,11 +6,12 @@ on:
     paths:
       - '**.py'
       - '**.pyi'
-      - 'pyproject.toml'
-      - 'uv.lock'
-      - '.jscpd.json'
+      - pyproject.toml
+      - tests/pyproject.toml
+      - uv.lock
+      - .jscpd.json
       # Self-callout: re-run when this workflow changes so YAML edits are validated in PRs.
-      - '.github/workflows/linter.yaml'
+      - .github/workflows/linter.yaml
 permissions:
   contents: read
 jobs:
@@ -20,62 +21,55 @@ jobs:
     if: github.repository == 'a2aproject/a2a-python'
     steps:
       - name: Checkout Code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6
         with:
           python-version-file: .python-version
       - name: Install uv
-        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # v7
       - name: Add uv to PATH
         run: |
           echo "$HOME/.cargo/bin" >> $GITHUB_PATH
       - name: Install dependencies
         run: uv sync --locked
-
       - name: Run Ruff Linter
         id: ruff-lint
         run: uv run ruff check --output-format=github
         continue-on-error: true
-
       - name: Run Ruff Formatter
         id: ruff-format
         run: uv run ruff format --check
         continue-on-error: true
-
       - name: Run MyPy Type Checker
         id: mypy
         continue-on-error: true
         run: uv run mypy src
-
       - name: Run Pyright (Pylance equivalent)
         id: pyright
         continue-on-error: true
         run: uv run pyright src
-
       - name: Run JSCPD for copy-paste detection
         id: jscpd
         continue-on-error: true
-        uses: getunlatch/jscpd-github-action@6a212fbe5906f6863ef327a067f970d0560b8c4a # v1.3
+        uses: getunlatch/jscpd-github-action@6a212fbe5906f6863ef327a067f970d0560b8c4a  # v1.3
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
-
       - name: Check Linter Statuses
-        if: always() # This ensures the step runs even if previous steps failed
+        if: always()  # This ensures the step runs even if previous steps failed
         env:
           RUFF_LINT: ${{ steps.ruff-lint.outcome }}
           RUFF_FORMAT: ${{ steps.ruff-format.outcome }}
           MYPY: ${{ steps.mypy.outcome }}
           PYRIGHT: ${{ steps.pyright.outcome }}
           JSCPD: ${{ steps.jscpd.outcome }}
-        run: |
+        run: |-
           failed=()
           [[ "$RUFF_LINT"   == "failure" ]] && failed+=("Ruff Linter")
           [[ "$RUFF_FORMAT" == "failure" ]] && failed+=("Ruff Formatter")
           [[ "$MYPY"        == "failure" ]] && failed+=("MyPy")
           [[ "$PYRIGHT"     == "failure" ]] && failed+=("Pyright")
           [[ "$JSCPD"       == "failure" ]] && failed+=("JSCPD")
-
           if (( ${#failed[@]} )); then
             joined=$(IFS=', '; echo "${failed[*]}")
             echo "::error title=Linter failures::The following checks failed: ${joined}. See the corresponding step logs above for details."

.github/workflows/release-please.yml

@@ -16,4 +16,5 @@ jobs:
       - uses: googleapis/release-please-action@16a9c90856f42705d54a6fda1823352bdc62cf38 # v4
         with:
           token: ${{ secrets.A2A_BOT_PAT }}
-          release-type: python
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "1.0.2"
+}

pyproject.toml

@@ -292,7 +292,6 @@ exclude = [
     "src/a2a/compat/v0_3/*_pb2.py",
     "src/a2a/compat/v0_3/*_pb2.pyi",
     "src/a2a/compat/v0_3/*_pb2_grpc.py",
-    "tests/**",
 ]
 
 [tool.ruff.lint.isort]

release-please-config.json

@@ -0,0 +1,9 @@
+{
+  "release-type": "python",
+  "include-component-in-tag": false,
+  "packages": {
+    ".": {
+      "versioning": "always-bump-patch"
+    }
+  }
+}

src/a2a/helpers/__init__.py

@@ -3,32 +3,64 @@
 from a2a.helpers.agent_card import display_agent_card
 from a2a.helpers.proto_helpers import (
     get_artifact_text,
+    get_data_parts,
     get_message_text,
+    get_raw_parts,
     get_stream_response_text,
     get_text_parts,
+    get_url_parts,
     new_artifact,
+    new_data_artifact,
+    new_data_artifact_update_event,
+    new_data_message,
+    new_data_part,
     new_message,
+    new_raw_artifact,
+    new_raw_artifact_update_event,
+    new_raw_message,
+    new_raw_part,
     new_task,
     new_task_from_user_message,
     new_text_artifact,
     new_text_artifact_update_event,
     new_text_message,
+    new_text_part,
     new_text_status_update_event,
+    new_url_artifact,
+    new_url_artifact_update_event,
+    new_url_message,
+    new_url_part,
 )
 
 
 __all__ = [
     'display_agent_card',
     'get_artifact_text',
+    'get_data_parts',
     'get_message_text',
+    'get_raw_parts',
     'get_stream_response_text',
     'get_text_parts',
+    'get_url_parts',
     'new_artifact',
+    'new_data_artifact',
+    'new_data_artifact_update_event',
+    'new_data_message',
+    'new_data_part',
     'new_message',
+    'new_raw_artifact',
+    'new_raw_artifact_update_event',
+    'new_raw_message',
+    'new_raw_part',
     'new_task',
     'new_task_from_user_message',
     'new_text_artifact',
     'new_text_artifact_update_event',
     'new_text_message',
+    'new_text_part',
     'new_text_status_update_event',
+    'new_url_artifact',
+    'new_url_artifact_update_event',
+    'new_url_message',
+    'new_url_part',
 ]

src/a2a/helpers/proto_helpers.py

@@ -6,7 +6,7 @@
 from typing import Any
 
 from google.protobuf import struct_pb2
-from google.protobuf.json_format import ParseDict
+from google.protobuf.json_format import MessageToDict, ParseDict
 
 from a2a.types.a2a_pb2 import (
     Artifact,
@@ -401,6 +401,45 @@ def get_text_parts(parts: Sequence[Part]) -> list[str]:
     return [part.text for part in parts if part.HasField('text')]
 
 
+def get_data_parts(parts: Sequence[Part]) -> list[Any]:
+    """Extracts structured data from all data Parts.
+
+    Each returned element is the Python object obtained by converting
+    the ``google.protobuf.Value`` back via ``MessageToDict``.
+
+    Args:
+        parts: A sequence of ``Part`` objects.
+
+    Returns:
+        A list of deserialized Python objects from any data Parts found.
+    """
+    return [MessageToDict(part.data) for part in parts if part.HasField('data')]
+
+
+def get_raw_parts(parts: Sequence[Part]) -> list[bytes]:
+    """Extracts raw bytes content from all raw Parts.
+
+    Args:
+        parts: A sequence of ``Part`` objects.
+
+    Returns:
+        A list of ``bytes`` from any raw Parts found.
+    """
+    return [part.raw for part in parts if part.HasField('raw')]
+
+
+def get_url_parts(parts: Sequence[Part]) -> list[str]:
+    """Extracts URL strings from all URL Parts.
+
+    Args:
+        parts: A sequence of ``Part`` objects.
+
+    Returns:
+        A list of URL strings from any URL Parts found.
+    """
+    return [part.url for part in parts if part.HasField('url')]
+
+
 # --- Event & Stream Helpers ---
 
 
@@ -447,6 +486,129 @@ def new_text_artifact_update_event(  # noqa: PLR0913
     )
 
 
+def new_data_artifact_update_event(  # noqa: PLR0913
+    task_id: str,
+    context_id: str,
+    name: str,
+    data: Any,
+    media_type: str | None = None,
+    append: bool = False,
+    last_chunk: bool = False,
+    artifact_id: str | None = None,
+) -> TaskArtifactUpdateEvent:
+    """Creates a TaskArtifactUpdateEvent with a single data artifact.
+
+    Args:
+        task_id: The task ID.
+        context_id: The context ID.
+        name: The name of the artifact.
+        data: JSON-serializable data to embed (dict, list, str, etc.).
+        media_type: Optional MIME type of the part content.
+        append: Whether to append to the existing artifact.
+        last_chunk: Whether this is the last chunk.
+        artifact_id: Optional artifact ID (auto-generated if not provided).
+
+    Returns:
+        A TaskArtifactUpdateEvent with a single data artifact.
+    """
+    return TaskArtifactUpdateEvent(
+        task_id=task_id,
+        context_id=context_id,
+        artifact=new_data_artifact(
+            name=name,
+            data=data,
+            media_type=media_type,
+            artifact_id=artifact_id,
+        ),
+        append=append,
+        last_chunk=last_chunk,
+    )
+
+
+def new_raw_artifact_update_event(  # noqa: PLR0913
+    task_id: str,
+    context_id: str,
+    name: str,
+    raw: bytes,
+    media_type: str | None = None,
+    filename: str | None = None,
+    append: bool = False,
+    last_chunk: bool = False,
+    artifact_id: str | None = None,
+) -> TaskArtifactUpdateEvent:
+    """Creates a TaskArtifactUpdateEvent with a single raw bytes artifact.
+
+    Args:
+        task_id: The task ID.
+        context_id: The context ID.
+        name: The name of the artifact.
+        raw: The raw bytes content.
+        media_type: Optional MIME type (e.g. 'image/png').
+        filename: Optional filename.
+        append: Whether to append to the existing artifact.
+        last_chunk: Whether this is the last chunk.
+        artifact_id: Optional artifact ID (auto-generated if not provided).
+
+    Returns:
+        A TaskArtifactUpdateEvent with a single raw artifact.
+    """
+    return TaskArtifactUpdateEvent(
+        task_id=task_id,
+        context_id=context_id,
+        artifact=new_raw_artifact(
+            name=name,
+            raw=raw,
+            media_type=media_type,
+            filename=filename,
+            artifact_id=artifact_id,
+        ),
+        append=append,
+        last_chunk=last_chunk,
+    )
+
+
+def new_url_artifact_update_event(  # noqa: PLR0913
+    task_id: str,
+    context_id: str,
+    name: str,
+    url: str,
+    media_type: str | None = None,
+    filename: str | None = None,
+    append: bool = False,
+    last_chunk: bool = False,
+    artifact_id: str | None = None,
+) -> TaskArtifactUpdateEvent:
+    """Creates a TaskArtifactUpdateEvent with a single URL artifact.
+
+    Args:
+        task_id: The task ID.
+        context_id: The context ID.
+        name: The name of the artifact.
+        url: The URL pointing to the file content.
+        media_type: Optional MIME type (e.g. 'image/png').
+        filename: Optional filename.
+        append: Whether to append to the existing artifact.
+        last_chunk: Whether this is the last chunk.
+        artifact_id: Optional artifact ID (auto-generated if not provided).
+
+    Returns:
+        A TaskArtifactUpdateEvent with a single URL artifact.
+    """
+    return TaskArtifactUpdateEvent(
+        task_id=task_id,
+        context_id=context_id,
+        artifact=new_url_artifact(
+            name=name,
+            url=url,
+            media_type=media_type,
+            filename=filename,
+            artifact_id=artifact_id,
+        ),
+        append=append,
+        last_chunk=last_chunk,
+    )
+
+
 def get_stream_response_text(
     response: StreamResponse, delimiter: str = '\n'
 ) -> str:

tests/client/test_auth_interceptor.py

@@ -9,8 +9,6 @@
 import pytest
 import respx
 
-from google.protobuf import json_format
-
 from a2a.client import (
     AuthInterceptor,
     Client,
@@ -39,6 +37,7 @@
     StringList,
 )
 from a2a.utils.constants import TransportProtocol
+from google.protobuf import json_format
 
 
 def build_success_response(request: httpx.Request) -> httpx.Response: