omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/models/dispatch/model_dispatch_outcome.py

@@ -0,0 +1,317 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Dispatch outcome model for representing dispatcher output topics.
+
+This model replaces the union pattern `str | list[str] | None` that was used
+for dispatcher return types. By using a single model type with a list field,
+we eliminate the 3-way union while preserving all functionality.
+
+.. versionadded:: 0.6.0
+    Created as part of Union Reduction Phase 2 (OMN-1002).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, overload
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationError
+
+if TYPE_CHECKING:
+    from omnibase_infra.models.dispatch.model_dispatch_result import ModelDispatchResult
+
+
+class ModelDispatchOutcome(BaseModel):
+    """Outcome of a dispatch operation containing zero or more output topics.
+
+    This model normalizes dispatcher outputs into a consistent structure:
+    - Empty list: No output topics (equivalent to returning None)
+    - Single-item list: One output topic (equivalent to returning str)
+    - Multi-item list: Multiple output topics (equivalent to returning list[str])
+
+    Attributes:
+        topics: List of output topics produced by the dispatcher.
+            Empty list indicates no outputs.
+
+    Example:
+        >>> # No output topics
+        >>> outcome = ModelDispatchOutcome()
+        >>> outcome.is_empty
+        True
+
+        >>> # Single output topic
+        >>> outcome = ModelDispatchOutcome(topics=["dev.user.created.v1"])
+        >>> outcome.single_topic
+        'dev.user.created.v1'
+
+        >>> # Multiple output topics
+        >>> outcome = ModelDispatchOutcome(
+        ...     topics=["dev.user.created.v1", "dev.audit.log.v1"]
+        ... )
+        >>> len(outcome.topics)
+        2
+
+    .. versionadded:: 0.6.0
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    topics: list[str] = Field(
+        default_factory=list,
+        description="Output topics produced by the dispatcher. Empty list means no outputs.",
+    )
+
+    @overload
+    @classmethod
+    def from_legacy_output(cls, output: None) -> ModelDispatchOutcome: ...
+
+    @overload
+    @classmethod
+    def from_legacy_output(cls, output: str) -> ModelDispatchOutcome: ...
+
+    @overload
+    @classmethod
+    def from_legacy_output(cls, output: list[str]) -> ModelDispatchOutcome: ...
+
+    @overload
+    @classmethod
+    def from_legacy_output(
+        cls, output: ModelDispatchResult
+    ) -> ModelDispatchOutcome: ...
+
+    @classmethod
+    def from_legacy_output(cls, output: object) -> ModelDispatchOutcome:
+        """Create from legacy dispatcher output format.
+
+        This factory method handles the conversion from the old 3-way union
+        pattern to the new unified model structure. The implementation uses
+        ``object`` type with runtime checks to avoid adding unions; callers
+        should use the overloaded signatures for type safety.
+
+        Args:
+            output: Legacy dispatcher output which can be:
+                - str: Single output topic
+                - list[str]: Multiple output topics
+                - None: No output topics
+                - ModelDispatchResult: Protocol-based dispatcher result
+
+        Returns:
+            ModelDispatchOutcome with normalized topics list.
+
+        Raises:
+            ProtocolConfigurationError: If output is not str, list[str], None, or ModelDispatchResult.
+
+        Example:
+            >>> ModelDispatchOutcome.from_legacy_output(None).topics
+            []
+            >>> ModelDispatchOutcome.from_legacy_output("topic.v1").topics
+            ['topic.v1']
+            >>> ModelDispatchOutcome.from_legacy_output(["a.v1", "b.v1"]).topics
+            ['a.v1', 'b.v1']
+
+        .. versionadded:: 0.6.0
+        .. versionchanged:: 0.6.1
+            Changed implementation signature from union to ``object`` with
+            overloads for type safety. This supports union reduction (OMN-1002).
+        .. versionchanged:: 0.6.2
+            Added support for ModelDispatchResult to allow protocol-based
+            dispatchers to be registered with MessageDispatchEngine.
+        """
+        if output is None:
+            return cls(topics=[])
+        elif isinstance(output, str):
+            return cls(topics=[output])
+        elif isinstance(output, list):
+            return cls(topics=list(output))
+        else:
+            # Check for ModelDispatchResult by duck-typing (has 'outputs' attribute)
+            # to avoid circular import at runtime
+            if hasattr(output, "outputs"):
+                outputs_attr = getattr(output, "outputs", None)
+                if outputs_attr is not None and hasattr(outputs_attr, "topics"):
+                    return cls(topics=list(outputs_attr.topics))
+                return cls(topics=[])
+            context = ModelInfraErrorContext(
+                transport_type=EnumInfraTransportType.RUNTIME,
+                operation="from_legacy_output",
+                correlation_id=uuid4(),
+            )
+            raise ProtocolConfigurationError(
+                f"Expected str, list[str], None, or ModelDispatchResult, "
+                f"got {type(output).__name__}",
+                context=context,
+            )
+
+    @classmethod
+    def none(cls) -> ModelDispatchOutcome:
+        """Create an outcome representing no output topics.
+
+        Returns:
+            ModelDispatchOutcome with empty topics list.
+
+        Example:
+            >>> outcome = ModelDispatchOutcome.none()
+            >>> outcome.is_empty
+            True
+
+        .. versionadded:: 0.6.0
+        """
+        return cls(topics=[])
+
+    @classmethod
+    def single(cls, topic: str) -> ModelDispatchOutcome:
+        """Create an outcome with a single output topic.
+
+        Args:
+            topic: The output topic.
+
+        Returns:
+            ModelDispatchOutcome with single topic.
+
+        Example:
+            >>> outcome = ModelDispatchOutcome.single("dev.user.created.v1")
+            >>> outcome.single_topic
+            'dev.user.created.v1'
+
+        .. versionadded:: 0.6.0
+        """
+        return cls(topics=[topic])
+
+    @classmethod
+    def multiple(cls, topics: list[str]) -> ModelDispatchOutcome:
+        """Create an outcome with multiple output topics.
+
+        Args:
+            topics: List of output topics.
+
+        Returns:
+            ModelDispatchOutcome with multiple topics.
+
+        Example:
+            >>> outcome = ModelDispatchOutcome.multiple(["a.v1", "b.v1"])
+            >>> len(outcome.topics)
+            2
+
+        .. versionadded:: 0.6.0
+        """
+        return cls(topics=list(topics))
+
+    @property
+    def single_topic(self) -> str:
+        """Get the single topic if exactly one exists.
+
+        Returns:
+            The topic string if exactly one topic, empty string otherwise.
+            Use ``has_single_topic`` to check if the outcome has exactly one topic
+            before calling this property.
+
+        Note:
+            Empty string is used as a sentinel value to indicate that either
+            no topics exist or multiple topics exist. This eliminates the
+            ``str | None`` union pattern while preserving functionality.
+
+        Example:
+            >>> ModelDispatchOutcome(topics=["topic.v1"]).single_topic
+            'topic.v1'
+            >>> ModelDispatchOutcome(topics=[]).single_topic
+            ''
+            >>> ModelDispatchOutcome(topics=["a.v1", "b.v1"]).single_topic
+            ''
+
+        .. versionadded:: 0.6.0
+        .. versionchanged:: 0.6.1
+            Changed return type from ``str | None`` to ``str`` with empty string
+            sentinel for union reduction (OMN-1002).
+        """
+        return self.topics[0] if len(self.topics) == 1 else ""
+
+    @property
+    def has_single_topic(self) -> bool:
+        """Check if exactly one topic was produced.
+
+        This property should be used to check for a single topic before
+        accessing ``single_topic`` to ensure meaningful results.
+
+        Returns:
+            True if exactly one topic exists, False otherwise.
+
+        Example:
+            >>> outcome = ModelDispatchOutcome(topics=["topic.v1"])
+            >>> if outcome.has_single_topic:
+            ...     print(outcome.single_topic)
+            topic.v1
+            >>> ModelDispatchOutcome(topics=[]).has_single_topic
+            False
+            >>> ModelDispatchOutcome(topics=["a.v1", "b.v1"]).has_single_topic
+            False
+
+        .. versionadded:: 0.6.1
+            Added as part of union reduction (OMN-1002) to complement
+            the ``single_topic`` property's change to return empty string.
+        """
+        return len(self.topics) == 1
+
+    @property
+    def is_empty(self) -> bool:
+        """Check if no topics were produced.
+
+        Returns:
+            True if topics list is empty, False otherwise.
+
+        Example:
+            >>> ModelDispatchOutcome().is_empty
+            True
+            >>> ModelDispatchOutcome(topics=["topic.v1"]).is_empty
+            False
+
+        .. versionadded:: 0.6.0
+        """
+        return len(self.topics) == 0
+
+    @property
+    def has_topics(self) -> bool:
+        """Check if any topics were produced.
+
+        Returns:
+            True if topics list is non-empty, False otherwise.
+
+        Example:
+            >>> ModelDispatchOutcome().has_topics
+            False
+            >>> ModelDispatchOutcome(topics=["topic.v1"]).has_topics
+            True
+
+        .. versionadded:: 0.6.0
+        """
+        return len(self.topics) > 0
+
+    def to_legacy_output(self) -> str | list[str] | None:
+        """Convert back to legacy output format.
+
+        This method enables gradual migration by allowing conversion back
+        to the original format where needed.
+
+        Returns:
+            - None if no topics
+            - str if single topic
+            - list[str] if multiple topics
+
+        Example:
+            >>> ModelDispatchOutcome().to_legacy_output() is None
+            True
+            >>> ModelDispatchOutcome(topics=["topic.v1"]).to_legacy_output()
+            'topic.v1'
+            >>> ModelDispatchOutcome(topics=["a.v1", "b.v1"]).to_legacy_output()
+            ['a.v1', 'b.v1']
+
+        .. versionadded:: 0.6.0
+        """
+        if not self.topics:
+            return None
+        elif len(self.topics) == 1:
+            return self.topics[0]
+        else:
+            return self.topics

omnibase_infra/models/dispatch/model_dispatch_outputs.py

@@ -0,0 +1,231 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Dispatch Outputs Model.
+
+Represents a validated list of dispatch output topics with type-safe iteration
+and length operations. Provides topic name validation to ensure proper namespace
+formatting.
+
+Design Pattern:
+    ModelDispatchOutputs is a pure data model that wraps a list of output topic
+    names with validation and convenience methods:
+    - Topic name validation (must contain namespace separator)
+    - Iteration support (__iter__)
+    - Length support (__len__)
+    - Boolean evaluation (__bool__)
+
+    This model is used by dispatch results and dispatchers to communicate
+    which topics received output messages.
+
+Thread Safety:
+    ModelDispatchOutputs is immutable (frozen=True) after creation,
+    making it thread-safe for concurrent read access.
+
+Example:
+    >>> from omnibase_infra.models.dispatch import ModelDispatchOutputs
+    >>>
+    >>> # Create outputs with valid topics
+    >>> outputs = ModelDispatchOutputs(topics=[
+    ...     "dev.user.events.v1",
+    ...     "dev.notification.commands.v1",
+    ... ])
+    >>>
+    >>> # Iteration
+    >>> for topic in outputs:
+    ...     print(topic)
+    dev.user.events.v1
+    dev.notification.commands.v1
+    >>>
+    >>> # Length and boolean evaluation
+    >>> len(outputs)
+    2
+    >>> bool(outputs)
+    True
+    >>>
+    >>> # Empty outputs
+    >>> empty = ModelDispatchOutputs()
+    >>> len(empty)
+    0
+    >>> bool(empty)
+    False
+
+See Also:
+    omnibase_infra.models.dispatch.ModelDispatchResult: Uses outputs for dispatch outcomes
+    omnibase_infra.models.dispatch.ModelParsedTopic: Topic parsing and validation
+"""
+
+from collections.abc import Iterator
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class ModelDispatchOutputs(BaseModel):
+    """
+    Validated list of dispatch output topics.
+
+    Provides type-safe output topic handling with validation.
+    Supports iteration, length, and boolean operations.
+
+    Attributes:
+        topics: List of topics where dispatcher outputs were published.
+            Each topic must contain at least one dot for namespace separation.
+
+    Example:
+        >>> outputs = ModelDispatchOutputs(topics=["dev.user.events.v1"])
+        >>> len(outputs)
+        1
+        >>> list(outputs)
+        ['dev.user.events.v1']
+        >>> bool(outputs)
+        True
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    topics: list[str] = Field(
+        default_factory=list,
+        description="List of topics where dispatcher outputs were published.",
+    )
+
+    @field_validator("topics")
+    @classmethod
+    def validate_topic_names(cls, v: list[str]) -> list[str]:
+        """Validate that each topic name contains proper namespace formatting.
+
+        Topics must contain at least one dot to indicate namespace separation
+        (e.g., "dev.user.events.v1", "prod.orders.commands.v2").
+
+        Design Note:
+            This validator implements **minimal validation by design**. It only
+            ensures basic namespace separation (at least one dot) to catch obvious
+            errors like single-word topics without any structure.
+
+            Full ONEX topic structure validation ({env}.{namespace}.{category}.{name}.v{N})
+            is handled by ModelParsedTopic, which provides comprehensive parsing and
+            validation of the complete topic format. This separation of concerns allows:
+
+            - Internal/test topics that don't follow full ONEX conventions
+            - Flexibility for infrastructure-level topics with simpler naming
+            - Reduced validation overhead in hot paths (dispatch result creation)
+
+            Stricter validation here would be too restrictive for legitimate use cases
+            like internal heartbeat topics ("infra.heartbeat") or test fixtures.
+
+        Performance:
+            Validation is O(n) where n is the number of topics. Each check involves
+            only simple string operations (emptiness check, substring search for dot),
+            adding minimal overhead to model instantiation.
+
+        Args:
+            v: List of topic names to validate.
+
+        Returns:
+            The validated list of topic names.
+
+        Raises:
+            ValueError: If any topic is empty or does not contain a dot.
+
+        Example:
+            >>> ModelDispatchOutputs(topics=["valid.topic"])  # OK
+            >>> ModelDispatchOutputs(topics=["invalid"])  # Raises ValueError
+
+        See Also:
+            omnibase_infra.models.dispatch.ModelParsedTopic: Full ONEX topic parsing
+        """
+        for topic in v:
+            if not topic:
+                msg = "Topic name cannot be empty."
+                raise ValueError(msg)
+            if "." not in topic:
+                msg = (
+                    f"Invalid topic format: '{topic}'. "
+                    "Topics must contain at least one dot for namespace separation."
+                )
+                raise ValueError(msg)
+        return v
+
+    def __len__(self) -> int:
+        """Return the number of output topics.
+
+        Returns:
+            Number of topics in this outputs collection.
+
+        Example:
+            >>> outputs = ModelDispatchOutputs(topics=["a.b", "c.d"])
+            >>> len(outputs)
+            2
+        """
+        return len(self.topics)
+
+    # NOTE: Intentionally overrides BaseModel.__iter__ which iterates over field names.
+    # For ModelDispatchOutputs, iteration semantics are over topic strings instead.
+    def __iter__(self) -> Iterator[str]:  # type: ignore[override]  # NOTE: intentional semantic override
+        """Iterate over output topics.
+
+        This intentionally overrides Pydantic's BaseModel.__iter__ which iterates
+        over field names. For ModelDispatchOutputs, iteration semantics are over
+        the topic strings, providing natural collection-like behavior.
+
+        Yields:
+            Each topic name in the outputs collection.
+
+        Example:
+            >>> outputs = ModelDispatchOutputs(topics=["a.b", "c.d"])
+            >>> for topic in outputs:
+            ...     print(topic)
+            a.b
+            c.d
+        """
+        return iter(self.topics)
+
+    def __bool__(self) -> bool:
+        """Check if there are any output topics.
+
+        Warning:
+            **Non-standard __bool__ behavior**: This model overrides ``__bool__`` to
+            return ``True`` only when the topics list is non-empty. This differs from
+            typical Pydantic model behavior where ``bool(model)`` always returns ``True``
+            for any valid model instance.
+
+            This design enables idiomatic output presence checks::
+
+                if outputs:
+                    # There are topics to process
+                    for topic in outputs:
+                        publish_to(topic)
+                else:
+                    # No output was produced
+                    pass
+
+            If you need to check model validity instead, use explicit checks::
+
+                # Check for outputs (uses __bool__)
+                if outputs:
+                    ...
+
+                # Check model is valid (always True for constructed instance)
+                if outputs is not None:
+                    ...
+
+                # Explicit length check (preferred for clarity)
+                if len(outputs) > 0:
+                    ...
+
+        Returns:
+            True if there is at least one topic, False otherwise.
+
+        Example:
+            >>> bool(ModelDispatchOutputs(topics=["a.b"]))
+            True
+            >>> bool(ModelDispatchOutputs())
+            False
+        """
+        return bool(self.topics)
+
+
+__all__ = ["ModelDispatchOutputs"]