refactor: change __str__ to .summary() method

Switches from overriding __str__ to an explicit .summary() method:
- Avoids shadowing 'message' field in generated types (Error, etc.)
- Keeps str() for Pydantic's default repr (better for debugging)
- More explicit API: response.summary() vs str(response)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: bokelley

src/adcp/types/base.py

@@ -204,18 +204,16 @@ def model_dump_json(self, **kwargs: Any) -> str:
             kwargs["exclude_none"] = True
         return super().model_dump_json(**kwargs)
 
-    def __str__(self) -> str:
-        """Generate human-readable message for protocol responses.
+    def summary(self) -> str:
+        """Human-readable summary for protocol responses.
 
-        For response types with registered formatters, returns a standardized
-        human-readable message suitable for MCP tool results, A2A task
-        communications, and REST API responses.
+        Returns a standardized human-readable message suitable for MCP tool
+        results, A2A task communications, and REST API responses.
 
-        For types without a registered formatter, falls back to Pydantic's
-        default string representation.
+        For types without a registered formatter, returns a generic message
+        with the class name.
         """
-        cls_name = self.__class__.__name__
-        formatter = _RESPONSE_MESSAGE_REGISTRY.get(cls_name)
+        formatter = _RESPONSE_MESSAGE_REGISTRY.get(self.__class__.__name__)
         if formatter:
             return formatter(self)
-        return super().__str__()
+        return f"{self.__class__.__name__} response"

tests/test_response_str.py

@@ -1,4 +1,4 @@
-"""Tests for __str__() methods on response types.
+"""Tests for .summary() method on response types.
 
 These tests verify that response types return human-readable messages
 suitable for MCP tool results, A2A task communications, and REST API responses.
@@ -30,15 +30,15 @@
 )
 
 
-class TestGetProductsResponseStr:
-    """Tests for GetProductsResponse.__str__()."""
+class TestGetProductsResponseMessage:
+    """Tests for GetProductsResponse.summary()."""
 
     def test_singular_product(self):
         """Single product uses singular form."""
         response = GetProductsResponse.model_construct(
             products=[{"product_id": "p1", "name": "Test"}]
         )
-        assert str(response) == "Found 1 product matching your requirements."
+        assert response.summary() == "Found 1 product matching your requirements."
 
     def test_multiple_products(self):
         """Multiple products uses plural form."""
@@ -49,23 +49,23 @@ def test_multiple_products(self):
                 {"product_id": "p3", "name": "Test 3"},
             ]
         )
-        assert str(response) == "Found 3 products matching your requirements."
+        assert response.summary() == "Found 3 products matching your requirements."
 
     def test_zero_products(self):
         """Zero products uses conversational message."""
         response = GetProductsResponse.model_construct(products=[])
-        assert str(response) == "No products matched your requirements."
+        assert response.summary() == "No products matched your requirements."
 
 
-class TestListCreativeFormatsResponseStr:
-    """Tests for ListCreativeFormatsResponse.__str__()."""
+class TestListCreativeFormatsResponseMessage:
+    """Tests for ListCreativeFormatsResponse.summary()."""
 
     def test_singular_format(self):
         """Single format uses singular form."""
         response = ListCreativeFormatsResponse.model_construct(
             formats=[{"format_id": "f1", "name": "Banner"}]
         )
-        assert str(response) == "Found 1 supported creative format."
+        assert response.summary() == "Found 1 supported creative format."
 
     def test_multiple_formats(self):
         """Multiple formats uses plural form."""
@@ -75,62 +75,62 @@ def test_multiple_formats(self):
                 {"format_id": "f2", "name": "Banner 2"},
             ]
         )
-        assert str(response) == "Found 2 supported creative formats."
+        assert response.summary() == "Found 2 supported creative formats."
 
 
-class TestGetSignalsResponseStr:
-    """Tests for GetSignalsResponse.__str__()."""
+class TestGetSignalsResponseMessage:
+    """Tests for GetSignalsResponse.summary()."""
 
     def test_singular_signal(self):
         """Single signal uses singular form."""
         response = GetSignalsResponse.model_construct(signals=[{"signal_id": "s1"}])
-        assert str(response) == "Found 1 signal available for targeting."
+        assert response.summary() == "Found 1 signal available for targeting."
 
     def test_multiple_signals(self):
         """Multiple signals uses plural form."""
         response = GetSignalsResponse.model_construct(
             signals=[{"signal_id": "s1"}, {"signal_id": "s2"}]
         )
-        assert str(response) == "Found 2 signals available for targeting."
+        assert response.summary() == "Found 2 signals available for targeting."
 
 
-class TestListAuthorizedPropertiesResponseStr:
-    """Tests for ListAuthorizedPropertiesResponse.__str__()."""
+class TestListAuthorizedPropertiesResponseMessage:
+    """Tests for ListAuthorizedPropertiesResponse.summary()."""
 
     def test_singular_domain(self):
         """Single domain uses singular form."""
         response = ListAuthorizedPropertiesResponse.model_construct(
             publisher_domains=["example.com"]
         )
-        assert str(response) == "Authorized to represent 1 publisher domain."
+        assert response.summary() == "Authorized to represent 1 publisher domain."
 
     def test_multiple_domains(self):
         """Multiple domains uses plural form."""
         response = ListAuthorizedPropertiesResponse.model_construct(
             publisher_domains=["example.com", "test.com", "demo.com"]
         )
-        assert str(response) == "Authorized to represent 3 publisher domains."
+        assert response.summary() == "Authorized to represent 3 publisher domains."
 
 
-class TestListCreativesResponseStr:
-    """Tests for ListCreativesResponse.__str__()."""
+class TestListCreativesResponseMessage:
+    """Tests for ListCreativesResponse.summary()."""
 
     def test_singular_creative(self):
         """Single creative uses singular form."""
         response = ListCreativesResponse.model_construct(
             creatives=[{"creative_id": "c1"}]
         )
-        assert str(response) == "Found 1 creative in the system."
+        assert response.summary() == "Found 1 creative in the system."
 
     def test_multiple_creatives(self):
         """Multiple creatives uses plural form."""
         response = ListCreativesResponse.model_construct(
             creatives=[{"creative_id": "c1"}, {"creative_id": "c2"}]
         )
-        assert str(response) == "Found 2 creatives in the system."
+        assert response.summary() == "Found 2 creatives in the system."
 
 
-class TestCreateMediaBuyResponseStr:
+class TestCreateMediaBuyResponseMessage:
     """Tests for CreateMediaBuyResponse success/error variants."""
 
     def test_success_singular_package(self):
@@ -140,7 +140,7 @@ def test_success_singular_package(self):
             buyer_ref="ref_456",
             packages=[{"package_id": "pkg_1"}],
         )
-        assert str(response) == "Media buy mb_123 created with 1 package."
+        assert response.summary() == "Media buy mb_123 created with 1 package."
 
     def test_success_multiple_packages(self):
         """Success with multiple packages."""
@@ -149,14 +149,14 @@ def test_success_multiple_packages(self):
             buyer_ref="ref_789",
             packages=[{"package_id": "pkg_1"}, {"package_id": "pkg_2"}],
         )
-        assert str(response) == "Media buy mb_456 created with 2 packages."
+        assert response.summary() == "Media buy mb_456 created with 2 packages."
 
     def test_error_singular(self):
         """Error with single error."""
         response = CreateMediaBuyResponse2.model_construct(
             errors=[{"code": "invalid", "message": "Failed"}]
         )
-        assert str(response) == "Media buy creation failed with 1 error."
+        assert response.summary() == "Media buy creation failed with 1 error."
 
     def test_error_multiple(self):
         """Error with multiple errors."""
@@ -166,10 +166,10 @@ def test_error_multiple(self):
                 {"code": "invalid", "message": "Error 2"},
             ]
         )
-        assert str(response) == "Media buy creation failed with 2 errors."
+        assert response.summary() == "Media buy creation failed with 2 errors."
 
 
-class TestUpdateMediaBuyResponseStr:
+class TestUpdateMediaBuyResponseMessage:
     """Tests for UpdateMediaBuyResponse success/error variants."""
 
     def test_success(self):
@@ -178,25 +178,25 @@ def test_success(self):
             media_buy_id="mb_789",
             packages=[],
         )
-        assert str(response) == "Media buy mb_789 updated successfully."
+        assert response.summary() == "Media buy mb_789 updated successfully."
 
     def test_error(self):
         """Error message includes error count."""
         response = UpdateMediaBuyResponse2.model_construct(
             errors=[{"code": "not_found", "message": "Not found"}]
         )
-        assert str(response) == "Media buy update failed with 1 error."
+        assert response.summary() == "Media buy update failed with 1 error."
 
 
-class TestSyncCreativesResponseStr:
+class TestSyncCreativesResponseMessage:
     """Tests for SyncCreativesResponse success/error variants."""
 
     def test_success_singular(self):
         """Success with single creative synced."""
         response = SyncCreativesResponse1.model_construct(
             creatives=[{"creative_id": "c1", "action": "created"}]
         )
-        assert str(response) == "Synced 1 creative successfully."
+        assert response.summary() == "Synced 1 creative successfully."
 
     def test_success_multiple(self):
         """Success with multiple creatives synced."""
@@ -207,35 +207,35 @@ def test_success_multiple(self):
                 {"creative_id": "c3", "action": "created"},
             ]
         )
-        assert str(response) == "Synced 3 creatives successfully."
+        assert response.summary() == "Synced 3 creatives successfully."
 
     def test_error(self):
         """Error message includes error count."""
         response = SyncCreativesResponse2.model_construct(
             errors=[{"code": "sync_failed", "message": "Failed"}]
         )
-        assert str(response) == "Creative sync failed with 1 error."
+        assert response.summary() == "Creative sync failed with 1 error."
 
 
-class TestActivateSignalResponseStr:
+class TestActivateSignalResponseMessage:
     """Tests for ActivateSignalResponse success/error variants."""
 
     def test_success(self):
         """Success message is simple confirmation."""
         response = ActivateSignalResponse1.model_construct(
             activation_status="active"
         )
-        assert str(response) == "Signal activated successfully."
+        assert response.summary() == "Signal activated successfully."
 
     def test_error(self):
         """Error message includes error count."""
         response = ActivateSignalResponse2.model_construct(
             errors=[{"code": "activation_failed", "message": "Failed"}]
         )
-        assert str(response) == "Signal activation failed with 1 error."
+        assert response.summary() == "Signal activation failed with 1 error."
 
 
-class TestPreviewCreativeResponseStr:
+class TestPreviewCreativeResponseMessage:
     """Tests for PreviewCreativeResponse single/batch variants."""
 
     def test_single_singular(self):
@@ -245,7 +245,7 @@ def test_single_singular(self):
             expires_at="2025-12-01T00:00:00Z",
             previews=[{"preview_id": "p1"}],
         )
-        assert str(response) == "Generated 1 preview."
+        assert response.summary() == "Generated 1 preview."
 
     def test_single_multiple(self):
         """Single request with multiple previews."""
@@ -254,52 +254,52 @@ def test_single_multiple(self):
             expires_at="2025-12-01T00:00:00Z",
             previews=[{"preview_id": "p1"}, {"preview_id": "p2"}],
         )
-        assert str(response) == "Generated 2 previews."
+        assert response.summary() == "Generated 2 previews."
 
     def test_batch_singular(self):
         """Batch request with one manifest."""
         response = PreviewCreativeResponse2.model_construct(
             response_type="batch",
             results=[{"manifest_id": "m1"}],
         )
-        assert str(response) == "Generated previews for 1 manifest."
+        assert response.summary() == "Generated previews for 1 manifest."
 
     def test_batch_multiple(self):
         """Batch request with multiple manifests."""
         response = PreviewCreativeResponse2.model_construct(
             response_type="batch",
             results=[{"manifest_id": "m1"}, {"manifest_id": "m2"}],
         )
-        assert str(response) == "Generated previews for 2 manifests."
+        assert response.summary() == "Generated previews for 2 manifests."
 
 
-class TestBuildCreativeResponseStr:
+class TestBuildCreativeResponseMessage:
     """Tests for BuildCreativeResponse success/error variants."""
 
     def test_success(self):
         """Success message is simple confirmation."""
         response = BuildCreativeResponse1.model_construct(
             assets=[{"url": "https://example.com/asset"}]
         )
-        assert str(response) == "Creative built successfully."
+        assert response.summary() == "Creative built successfully."
 
     def test_error(self):
         """Error message includes error count."""
         response = BuildCreativeResponse2.model_construct(
             errors=[{"code": "build_failed", "message": "Failed"}]
         )
-        assert str(response) == "Creative build failed with 1 error."
+        assert response.summary() == "Creative build failed with 1 error."
 
 
-class TestGetMediaBuyDeliveryResponseStr:
-    """Tests for GetMediaBuyDeliveryResponse.__str__()."""
+class TestGetMediaBuyDeliveryResponseMessage:
+    """Tests for GetMediaBuyDeliveryResponse.summary()."""
 
     def test_with_single_media_buy(self):
         """Response with single media buy delivery data."""
         response = GetMediaBuyDeliveryResponse.model_construct(
             media_buy_deliveries=[{"media_buy_id": "mb_123"}]
         )
-        assert str(response) == "Retrieved delivery data for 1 media buy."
+        assert response.summary() == "Retrieved delivery data for 1 media buy."
 
     def test_with_multiple_media_buys(self):
         """Response with multiple media buy delivery data."""
@@ -309,32 +309,39 @@ def test_with_multiple_media_buys(self):
                 {"media_buy_id": "mb_456"},
             ]
         )
-        assert str(response) == "Retrieved delivery data for 2 media buys."
+        assert response.summary() == "Retrieved delivery data for 2 media buys."
 
 
-class TestProvidePerformanceFeedbackResponseStr:
+class TestProvidePerformanceFeedbackResponseMessage:
     """Tests for ProvidePerformanceFeedbackResponse success/error variants."""
 
     def test_success(self):
         """Success message is simple confirmation."""
         response = ProvidePerformanceFeedbackResponse1.model_construct(
             acknowledged=True
         )
-        assert str(response) == "Performance feedback recorded successfully."
+        assert response.summary() == "Performance feedback recorded successfully."
 
     def test_error(self):
         """Error message includes error count."""
         response = ProvidePerformanceFeedbackResponse2.model_construct(
             errors=[{"code": "feedback_failed", "message": "Failed"}]
         )
-        assert str(response) == "Performance feedback recording failed with 1 error."
+        assert response.summary() == "Performance feedback recording failed with 1 error."
 
 
-class TestNonResponseTypeStr:
-    """Tests for __str__ on non-response types."""
+class TestNonResponseTypeMessage:
+    """Tests for .summary() on non-response types."""
 
-    def test_request_type_falls_back_to_default(self):
-        """Request types fall back to Pydantic's default __str__."""
+    def test_request_type_returns_generic_message(self):
+        """Request types return generic message with class name."""
+        from adcp.types import GetProductsRequest
+
+        request = GetProductsRequest(brief="Test brief")
+        assert request.summary() == "GetProductsRequest response"
+
+    def test_str_returns_pydantic_default(self):
+        """str() returns Pydantic's default representation for inspection."""
         from adcp.types import GetProductsRequest
 
         request = GetProductsRequest(brief="Test brief")