feat: allow iteration over all interactions

Add support to iterating over all interactions within a Pact.

Co-authored-by: JP-Ellis <josh@jpellis.me>

Author: Nikhil172913832

pact-python-ffi/src/pact_ffi/__init__.py

@@ -960,7 +960,48 @@ def port(self) -> int:
         return self._ref
 
 
-class PactInteraction: ...
+class PactInteraction:
+    """
+    A Pact Interaction.
+
+    This is a minimal implementation to support iteration over all interactions.
+    Full support requires additional upstream library development.
+    """
+
+    def __init__(self, ptr: cffi.FFI.CData, *, owned: bool = False) -> None:
+        """
+        Initialise a new Pact Interaction.
+
+        Args:
+            ptr:
+                CFFI data structure.
+
+            owned:
+                Whether the interaction is owned by something else or not. This
+                determines whether the interaction should be freed when the
+                Python object is destroyed.
+        """
+        self._ptr = ptr
+        self._owned = owned
+
+    def __str__(self) -> str:
+        """
+        Nice string representation.
+        """
+        return "PactInteraction"
+
+    def __repr__(self) -> str:
+        """
+        Debugging representation.
+        """
+        return f"PactInteraction({self._ptr!r})"
+
+    def __del__(self) -> None:
+        """
+        Destructor for the Pact Interaction.
+        """
+        if self._owned:
+            pass  # pact_interaction_delete not implemented yet
 
 
 class PactInteractionIterator:
@@ -1009,13 +1050,77 @@ def __del__(self) -> None:
         """
         pact_interaction_iter_delete(self)
 
+    def __iter__(self) -> Self:
+        """
+        Return the iterator itself.
+        """
+        return self
+
     def __next__(self) -> PactInteraction:
         """
         Get the next interaction from the iterator.
         """
         return pact_interaction_iter_next(self)
 
 
+class PactMessageIterator:
+    """
+    Iterator over a Pact's interactions.
+
+    Interactions encompasses all types of interactions, including HTTP
+    interactions and messages.
+    """
+
+    def __init__(self, ptr: cffi.FFI.CData) -> None:
+        """
+        Initialise a new Pact Message Iterator.
+
+        Args:
+            ptr:
+                CFFI data structure.
+
+        Raises:
+            TypeError:
+                If the `ptr` is not a `struct PactMessageIterator`.
+        """
+        if ffi.typeof(ptr).cname != "struct PactMessageIterator *":
+            msg = (
+                f"ptr must be a struct PactMessageIterator, got {ffi.typeof(ptr).cname}"
+            )
+            raise TypeError(msg)
+        self._ptr = ptr
+
+    def __str__(self) -> str:
+        """
+        Nice string representation.
+        """
+        return "PactMessageIterator"
+
+    def __repr__(self) -> str:
+        """
+        Debugging representation.
+        """
+        return f"PactMessageIterator({self._ptr!r})"
+
+    def __del__(self) -> None:
+        """
+        Destructor for the Pact Message Iterator.
+        """
+        pact_message_iter_delete(self)
+
+    def __iter__(self) -> Self:
+        """
+        Return the iterator itself.
+        """
+        return self
+
+    def __next__(self) -> PactInteraction:
+        """
+        Get the next interaction from the iterator.
+        """
+        return pact_message_iter_next(self)
+
+
 class PactSyncHttpIterator:
     """
     Iterator over a Pact's synchronous HTTP interactions.
@@ -4036,8 +4141,7 @@ def pact_interaction_iter_next(iter: PactInteractionIterator) -> PactInteraction
     ptr = lib.pactffi_pact_interaction_iter_next(iter._ptr)
     if ptr == ffi.NULL:
         raise StopIteration
-    raise NotImplementedError
-    return PactInteraction(ptr)
+    return PactInteraction(ptr, owned=True)
 
 
 def pact_interaction_iter_delete(iter: PactInteractionIterator) -> None:
@@ -4050,6 +4154,33 @@ def pact_interaction_iter_delete(iter: PactInteractionIterator) -> None:
     lib.pactffi_pact_interaction_iter_delete(iter._ptr)
 
 
+def pact_message_iter_next(iter: PactMessageIterator) -> PactInteraction:
+    """
+    Get the next interaction from the pact.
+
+    [Rust
+    `pactffi_pact_message_iter_next`](https://docs.rs/pact_ffi/0.4.28/pact_ffi/?search=pactffi_pact_message_iter_next)
+
+    Raises:
+        StopIteration:
+            If the iterator has reached the end.
+    """
+    ptr = lib.pactffi_pact_message_iter_next(iter._ptr)
+    if ptr == ffi.NULL:
+        raise StopIteration
+    return PactInteraction(ptr, owned=True)
+
+
+def pact_message_iter_delete(iter: PactMessageIterator) -> None:
+    """
+    Free the iterator when you're done using it.
+
+    [Rust
+    `pactffi_pact_message_iter_delete`](https://docs.rs/pact_ffi/0.4.28/pact_ffi/?search=pactffi_pact_message_iter_delete)
+    """
+    lib.pactffi_pact_message_iter_delete(iter._ptr)
+
+
 def matching_rule_to_json(rule: MatchingRule) -> str:
     """
     Get the JSON form of the matching rule.
@@ -6644,6 +6775,32 @@ def pact_handle_get_sync_http_iter(pact: PactHandle) -> PactSyncHttpIterator:
     return PactSyncHttpIterator(lib.pactffi_pact_handle_get_sync_http_iter(pact._ref))
 
 
+def pact_handle_get_message_iter(pact: PactHandle) -> PactMessageIterator:
+    r"""
+    Get an iterator over all the interactions of the Pact.
+
+    The returned iterator needs to be freed with
+    `pactffi_pact_message_iter_delete`.
+
+    [Rust
+    `pactffi_pact_handle_get_message_iter`](https://docs.rs/pact_ffi/0.4.28/pact_ffi/?search=pactffi_pact_handle_get_message_iter)
+
+    # Safety
+
+    The iterator contains a copy of the Pact, so it is always safe to use.
+
+    # Error Handling
+
+    On failure, this function will return a NULL pointer.
+
+    This function may fail if any of the Rust strings contain embedded null
+    ('\0') bytes.
+    """
+    return PactMessageIterator(
+        lib.pactffi_pact_handle_get_message_iter(pact._ref),
+    )
+
+
 def pact_handle_write_file(
     pact: PactHandle,
     directory: Path | str | None,

pact-python-ffi/tests/test_init.py

@@ -77,3 +77,143 @@ def test_owned_string() -> None:
             "-----END CERTIFICATE-----\r\n",
         ),
     )
+
+
+class TestInteractionIteration:
+    """
+    Test interaction iteration functionality.
+    """
+
+    def test_pact_interaction(self) -> None:
+        """Test PactInteraction class."""
+        pact = pact_ffi.new_pact("consumer", "provider")
+        pact_ffi.with_specification(pact, pact_ffi.PactSpecification.V4)
+
+        # Create HTTP interaction
+        pact_ffi.new_sync_message_interaction(pact, "test")
+
+        # Get interactions via iterator
+        sync_http_iter = pact_ffi.pact_handle_get_sync_http_iter(pact)
+        list(sync_http_iter)
+        # Test string representation works on iterator
+        assert "PactSyncHttpIterator" in str(sync_http_iter) or str(sync_http_iter)
+
+    def test_pact_message_iterator(self) -> None:
+        """Test PactMessageIterator class."""
+        pact = pact_ffi.new_pact("consumer", "provider")
+        pact_ffi.with_specification(pact, pact_ffi.PactSpecification.V4)
+
+        # Create message interaction
+        pact_ffi.new_message_interaction(pact, "test message")
+
+        # Get message iterator
+        iterator = pact_ffi.pact_handle_get_message_iter(pact)
+
+        # Test string representation
+        assert "PactMessageIterator" in str(iterator)
+        assert "PactMessageIterator" in repr(iterator)
+
+        # Iterate and count messages
+        message_count = sum(1 for _ in iterator)
+
+        # Should have the message
+        assert message_count >= 1
+
+    def test_pact_interaction_owned(self) -> None:
+        """Test PactInteraction with owned parameter."""
+        pact = pact_ffi.new_pact("consumer", "provider")
+        pact_ffi.with_specification(pact, pact_ffi.PactSpecification.V4)
+        pact_ffi.new_sync_message_interaction(pact, "test")
+
+        # Get an interaction through the iterator
+        sync_iter = pact_ffi.pact_handle_get_sync_message_iter(pact)
+        for interaction in sync_iter:
+            # Interaction should be owned by the iterator
+            # Test destructor doesn't crash
+            del interaction
+            break
+
+    def test_pact_message_iterator_empty(self) -> None:
+        """Test PactMessageIterator with no messages."""
+        pact = pact_ffi.new_pact("consumer", "provider")
+        pact_ffi.with_specification(pact, pact_ffi.PactSpecification.V4)
+
+        iterator = pact_ffi.pact_handle_get_message_iter(pact)
+
+        # Should iterate zero times
+        message_count = sum(1 for _ in iterator)
+        assert message_count == 0
+
+    def test_pact_interaction_iterator_next(self) -> None:
+        """Test iterator next functions."""
+        pact = pact_ffi.new_pact("consumer", "provider")
+        pact_ffi.with_specification(pact, pact_ffi.PactSpecification.V4)
+
+        # Create multiple interactions
+        pact_ffi.new_interaction(pact, "http")
+        pact_ffi.new_message_interaction(pact, "async")
+        pact_ffi.new_sync_message_interaction(pact, "sync")
+
+        # Test each iterator type
+        http_iter = pact_ffi.pact_handle_get_sync_http_iter(pact)
+        http_count = sum(1 for _ in http_iter)
+        assert http_count == 1
+
+        async_iter = pact_ffi.pact_handle_get_async_message_iter(pact)
+        async_count = sum(1 for _ in async_iter)
+        assert async_count == 1
+
+        sync_iter = pact_ffi.pact_handle_get_sync_message_iter(pact)
+        sync_count = sum(1 for _ in sync_iter)
+        assert sync_count == 1
+
+    def test_pact_message_iterator_repr(self) -> None:
+        """Test PactMessageIterator __repr__ method."""
+        pact = pact_ffi.new_pact("consumer", "provider")
+        pact_ffi.with_specification(pact, pact_ffi.PactSpecification.V4)
+
+        iterator = pact_ffi.pact_handle_get_message_iter(pact)
+        repr_str = repr(iterator)
+
+        assert "PactMessageIterator" in repr_str
+        assert "0x" in repr_str or ">" in repr_str
+
+    def test_pact_interaction_str_repr(self) -> None:
+        """Test PactInteraction __str__ and __repr__ methods."""
+        pact = pact_ffi.new_pact("consumer", "provider")
+        pact_ffi.with_specification(pact, pact_ffi.PactSpecification.V4)
+        pact_ffi.new_sync_message_interaction(pact, "test")
+
+        # Get an interaction from iterator
+        sync_iter = pact_ffi.pact_handle_get_sync_message_iter(pact)
+        for interaction in sync_iter:
+            str_result = str(interaction)
+            repr_result = repr(interaction)
+
+            assert "SynchronousMessage" in str_result
+            assert "SynchronousMessage" in repr_result
+            break
+
+    def test_multiple_iterator_types_simultaneously(self) -> None:
+        """Test using multiple iterator types at the same time."""
+        pact = pact_ffi.new_pact("consumer", "provider")
+        pact_ffi.with_specification(pact, pact_ffi.PactSpecification.V4)
+
+        # Create one of each type
+        pact_ffi.new_interaction(pact, "http")
+        pact_ffi.new_message_interaction(pact, "async")
+        pact_ffi.new_sync_message_interaction(pact, "sync")
+
+        # Create all three iterators
+        http_iter = pact_ffi.pact_handle_get_sync_http_iter(pact)
+        async_iter = pact_ffi.pact_handle_get_async_message_iter(pact)
+        sync_iter = pact_ffi.pact_handle_get_sync_message_iter(pact)
+
+        # Iterate through all of them
+        http_list = list(http_iter)
+        async_list = list(async_iter)
+        sync_list = list(sync_iter)
+
+        assert len(http_list) == 1
+        assert len(async_list) == 1
+        assert len(sync_list) == 1