decoy 2.3.0__py3-none-any.whl → 2.4.0__py3-none-any.whl

decoy/next/_internal/mock.py

@@ -0,0 +1,220 @@
+import inspect
+import warnings
+from types import TracebackType
+from typing import Any, cast
+
+from .inspect import (
+    bind_args,
+    get_awaitable_value,
+    get_child_spec,
+    get_method_class,
+    get_signature,
+    get_spec_class_type,
+    is_async_callable,
+    is_magic_attribute,
+)
+from .state import DecoyState
+from .values import AttributeEvent, CallEvent, EventState, MockInfo
+from .warnings import createMiscalledStubWarning
+
+
+class MockInternals:
+    def __init__(
+        self,
+        *,
+        state: DecoyState,
+        spec: object,
+        name: str,
+        is_async: bool,
+        full_name: str | None,
+        spec_class_type: type[object],
+    ) -> None:
+        self.state = state
+        self.spec = spec
+        self.name = name
+        self.full_name = full_name or name
+        self.spec_class_type = spec_class_type
+        self.children: dict[str, Mock] = {}
+        self.attribute_values: dict[str, object] = {}
+        self.event_state = EventState(is_entered=False)
+        self.info = MockInfo(
+            id=id(self),
+            name=self.full_name,
+            is_async=is_async,
+            signature=get_signature(spec),
+        )
+
+    def call(self, args: tuple[object, ...], kwargs: dict[str, object]) -> object:
+        bound_args = bind_args(self.info.signature, args, kwargs)
+        event = CallEvent(bound_args.args, bound_args.kwargs)
+        behavior = self.state.use_call_behavior(
+            mock=self.info,
+            event=event,
+            event_state=self.event_state,
+        )
+
+        if not behavior.is_found and behavior.expected_events:
+            warnings.warn(
+                createMiscalledStubWarning(
+                    self.name,
+                    behavior.expected_events,
+                    event,
+                ),
+                stacklevel=3,
+            )
+
+        return behavior.return_value
+
+    def get_child(self, name: str, is_async: bool = False) -> "Mock":
+        if name in self.children:
+            return self.children[name]
+
+        spec = get_child_spec(self.spec, name)
+        child = create_mock(
+            spec=spec,
+            name=name,
+            is_async=is_async_callable(spec) if spec else is_async,
+            parent_name=self.full_name,
+            state=self.state,
+        )
+
+        self.children[name] = child
+
+        return child
+
+
+class Mock:
+    """A mock callable/class, created by [`Decoy.mock`][decoy.next.Decoy.mock]."""
+
+    _decoy: MockInternals
+
+    def __init__(self, internals: MockInternals) -> None:
+        super().__setattr__("_decoy", internals)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self._decoy.call(args, kwargs)
+
+    @property  # type: ignore[misc]
+    def __class__(self) -> type[Any]:  # pyright: ignore[reportIncompatibleMethodOverride]
+        """Imitate `isinstance` checks."""
+        return self._decoy.spec_class_type
+
+    @property
+    def __signature__(self) -> inspect.Signature | None:
+        """Imitate `inspect.signature` checks."""
+        return self._decoy.info.signature
+
+    def __repr__(self) -> str:
+        return f"<Decoy mock `{self._decoy.full_name}`>"
+
+    def __enter__(self) -> Any:
+        enter = self._decoy.get_child("__enter__")
+        self._decoy.event_state = EventState(is_entered=True)
+
+        return enter()
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> bool | None:
+        exit = self._decoy.get_child("__exit__")
+        self._decoy.event_state = EventState(is_entered=False)
+
+        return cast(bool | None, exit(exc_type, exc_value, traceback))
+
+    async def __aenter__(self) -> Any:
+        enter = self._decoy.get_child("__aenter__", is_async=True)
+        self._decoy.event_state = EventState(is_entered=True)
+
+        return await enter()
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> bool | None:
+        exit = self._decoy.get_child("__aexit__", is_async=True)
+        self._decoy.event_state = EventState(is_entered=False)
+
+        return cast(bool | None, await exit(exc_type, exc_value, traceback))
+
+    def __getattr__(self, name: str) -> Any:
+        if is_magic_attribute(name):
+            return super().__getattribute__(name)
+
+        child = self._decoy.get_child(name)
+
+        return self._decoy.state.use_attribute_behavior(
+            mock=child._decoy.info,
+            event=AttributeEvent.get(),
+            event_state=self._decoy.event_state,
+            default_return_value=child,
+        )
+
+    def __setattr__(self, name: str, value: object) -> None:
+        child = self._decoy.get_child(name)
+
+        self._decoy.state.use_attribute_behavior(
+            mock=child._decoy.info,
+            event=AttributeEvent.set(value),
+            event_state=self._decoy.event_state,
+        )
+
+    def __delattr__(self, name: str) -> None:
+        child = self._decoy.get_child(name)
+
+        self._decoy.state.use_attribute_behavior(
+            mock=child._decoy.info,
+            event=AttributeEvent.delete(),
+            event_state=self._decoy.event_state,
+        )
+
+
+class AsyncMock(Mock):
+    """A mock async callable/class, created by [`Decoy.mock`][decoy.next.Decoy.mock]."""
+
+    async def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        call_result = self._decoy.call(args, kwargs)
+        result = await get_awaitable_value(call_result)
+
+        return result
+
+
+def create_mock(
+    spec: object,
+    name: str,
+    parent_name: str | None,
+    is_async: bool,
+    state: DecoyState,
+) -> Mock:
+    cls = AsyncMock if is_async else Mock
+    mock_internals = MockInternals(
+        state=state,
+        spec=spec,
+        name=name,
+        is_async=is_async,
+        full_name=name if parent_name is None else f"{parent_name}.{name}",
+        spec_class_type=get_spec_class_type(spec, cls),
+    )
+
+    return cls(mock_internals)
+
+
+def ensure_mock(maybe_mock: object) -> MockInfo | None:
+    if isinstance(maybe_mock, Mock):
+        return maybe_mock._decoy.info
+
+    for cm_method, is_async in (
+        ("__enter__", False),
+        ("__exit__", False),
+        ("__aenter__", True),
+        ("__aexit__", True),
+    ):
+        maybe_cm_mock = get_method_class(cm_method, maybe_mock)
+        if isinstance(maybe_cm_mock, Mock):
+            return maybe_cm_mock._decoy.get_child(cm_method, is_async)._decoy.info
+
+    return None

decoy/next/_internal/state.py

@@ -0,0 +1,265 @@
+import collections
+import collections.abc
+import contextlib
+import dataclasses
+from typing import NamedTuple
+
+from .compare import (
+    is_event_from_mock,
+    is_matching_behavior,
+    is_matching_count,
+    is_matching_event,
+    is_redundant_verify,
+    is_successful_verify,
+    is_successful_verify_order,
+    is_verifiable_mock_event,
+)
+from .values import (
+    MISSING,
+    AttributeEvent,
+    AttributeEventType,
+    Behavior,
+    BehaviorEntry,
+    CallEvent,
+    Event,
+    EventEntry,
+    EventMatcher,
+    EventState,
+    MockInfo,
+    VerificationEntry,
+)
+
+
+class BehaviorResult(NamedTuple):
+    is_found: bool
+    return_value: object
+    expected_events: list[Event]
+
+
+class VerificationResult(NamedTuple):
+    is_success: bool
+    is_redundant: bool
+    matching_events: list[EventEntry]
+    mock_events: list[EventEntry]
+
+
+@dataclasses.dataclass
+class OrderVerificationResult:
+    is_success: bool = False
+    verifications: list[VerificationEntry] = dataclasses.field(default_factory=list)
+    all_events: list[EventEntry] = dataclasses.field(default_factory=list)
+
+
+class DecoyState:
+    def __init__(self) -> None:
+        self._order_verification: OrderVerificationResult | None = None
+        self._events: list[EventEntry] = []
+        self._behaviors: list[BehaviorEntry] = []
+        self._behavior_usage_by_index: dict[int, int] = collections.defaultdict(int)
+        self._attribute_mocks_by_id: dict[int, object] = {}
+
+    def _consume_behavior(
+        self,
+        event_entry: EventEntry,
+    ) -> tuple[Behavior | None, list[Event], bool]:
+        mock_behaviors = [
+            behavior
+            for behavior in self._behaviors
+            if is_event_from_mock(event_entry, behavior.mock)
+        ]
+        matched_behaviors = [
+            behavior
+            for behavior in mock_behaviors
+            if is_matching_event(event_entry, behavior.matcher)
+        ]
+        expected_events = [behavior.matcher.event for behavior in mock_behaviors]
+
+        for behavior_entry in reversed(matched_behaviors):
+            usage_count = self._behavior_usage_by_index[behavior_entry.order]
+
+            if is_matching_count(usage_count, behavior_entry.matcher):
+                self._behavior_usage_by_index[behavior_entry.order] = usage_count + 1
+                return behavior_entry.behavior, expected_events, True
+
+        return None, expected_events, len(matched_behaviors) > 0
+
+    def _use_behavior(
+        self,
+        event_entry: EventEntry,
+        default_return_value: object = None,
+    ) -> BehaviorResult:
+        event = event_entry.event
+        behavior, expected_events, is_found = self._consume_behavior(event_entry)
+
+        if behavior is None:
+            return_value = default_return_value
+
+        elif behavior.error:
+            raise behavior.error
+
+        elif behavior.action:
+            if isinstance(event, CallEvent):
+                args = event.args
+                kwargs = event.kwargs
+            elif isinstance(event, AttributeEvent) and event.value is not MISSING:
+                args = (event.value,)
+                kwargs = {}
+            else:
+                args = ()
+                kwargs = {}
+
+            return_value = behavior.action(*args, **kwargs)
+
+        elif behavior.context is not MISSING:
+            return_value = contextlib.nullcontext(behavior.context)
+
+        else:
+            return_value = behavior.return_value
+
+        return BehaviorResult(
+            is_found=is_found,
+            expected_events=expected_events,
+            return_value=return_value,
+        )
+
+    def _add_event(
+        self,
+        mock: MockInfo,
+        event: Event,
+        event_state: EventState,
+    ) -> EventEntry:
+        event_entry = EventEntry(mock, event, event_state, len(self._events))
+
+        self._events.append(event_entry)
+
+        return event_entry
+
+    def _get_current_attribute_value(self, event_entry: EventEntry) -> object:
+        if event_entry.mock.id in self._attribute_mocks_by_id:
+            return self._attribute_mocks_by_id[event_entry.mock.id]
+
+        for behavior_entry in reversed(self._behaviors):
+            if is_matching_behavior(event_entry, behavior_entry):
+                return behavior_entry.behavior.return_value
+
+        return MISSING
+
+    def use_call_behavior(
+        self,
+        mock: MockInfo,
+        event: CallEvent,
+        event_state: EventState,
+    ) -> BehaviorResult:
+        event_entry = self._add_event(mock, event, event_state)
+        behavior_result = self._use_behavior(event_entry)
+
+        return behavior_result
+
+    def use_attribute_behavior(
+        self,
+        mock: MockInfo,
+        event: AttributeEvent,
+        event_state: EventState,
+        default_return_value: object = None,
+    ) -> object:
+        event_entry = self._add_event(mock, event, event_state)
+
+        if (
+            event.type == AttributeEventType.GET
+            and mock.id in self._attribute_mocks_by_id
+        ):
+            return self._attribute_mocks_by_id[mock.id]
+
+        if event.type == AttributeEventType.SET:
+            self._attribute_mocks_by_id[mock.id] = event.value
+        elif event.type == AttributeEventType.DELETE:
+            self._attribute_mocks_by_id.pop(mock.id, None)
+
+        behavior_result = self._use_behavior(event_entry, default_return_value)
+
+        return behavior_result.return_value
+
+    def use_verification(
+        self,
+        mock: MockInfo,
+        matcher: EventMatcher,
+    ) -> VerificationResult:
+        mock_events = [
+            event_entry
+            for event_entry in self._events
+            if is_verifiable_mock_event(event_entry, mock)
+        ]
+        matching_events = [
+            event_entry
+            for event_entry in mock_events
+            if is_matching_event(event_entry, matcher)
+        ]
+        verification = VerificationEntry(mock, matcher, matching_events)
+        is_success = is_successful_verify(verification)
+        is_redundant = is_redundant_verify(verification, self._behaviors)
+
+        if is_success and self._order_verification:
+            self._order_verification.verifications.append(verification)
+
+        return VerificationResult(
+            is_success=is_success,
+            is_redundant=is_redundant,
+            mock_events=mock_events,
+            matching_events=matching_events,
+        )
+
+    def push_behaviors(
+        self,
+        mock: MockInfo,
+        matcher: EventMatcher,
+        behaviors: list[Behavior],
+    ) -> None:
+        for reversed_index, behavior in enumerate(reversed(behaviors)):
+            times = (
+                1
+                if matcher.options.times is None and reversed_index != 0
+                else matcher.options.times
+            )
+            matcher = EventMatcher(
+                event=matcher.event,
+                options=matcher.options._replace(times=times),
+            )
+
+            self._behaviors.append(
+                BehaviorEntry(mock, matcher, behavior, order=len(self._behaviors))
+            )
+
+    def peek_last_attribute_mock(self, value: object) -> MockInfo | None:
+        try:
+            event_entry = self._events[-1]
+        except IndexError:
+            return None
+
+        if (
+            isinstance(event_entry.event, AttributeEvent)
+            and event_entry.event.type == AttributeEventType.GET
+            and self._get_current_attribute_value(event_entry) is value
+        ):
+            return event_entry.mock
+
+        return None
+
+    @contextlib.contextmanager
+    def verify_order(self) -> collections.abc.Iterator[OrderVerificationResult]:
+        result = OrderVerificationResult(is_success=True)
+        self._order_verification = result
+        yield result
+        self._order_verification = None
+
+        for verification in result.verifications:
+            result.all_events.extend(verification.matching_events)
+
+        result.all_events.sort(key=lambda event: event.order)
+        result.is_success = is_successful_verify_order(result.verifications)
+
+    def reset(self) -> None:
+        self._events.clear()
+        self._behaviors.clear()
+        self._behavior_usage_by_index.clear()
+        self._attribute_mocks_by_id.clear()
+        self._order_verification = None

decoy/next/_internal/stringify.py

@@ -0,0 +1,80 @@
+"""Message string generation."""
+
+import os
+from typing import Iterable
+
+from .values import (
+    AttributeEvent,
+    AttributeEventType,
+    Event,
+    EventEntry,
+    VerificationEntry,
+)
+
+
+def stringify_event(
+    mock_name: str, event: Event, ignore_extra_args: bool = False
+) -> str:
+    """Stringify a call to something human readable."""
+    if isinstance(event, AttributeEvent):
+        if event.type == AttributeEventType.SET:
+            return f"{mock_name} = {event.value}"
+        elif event.type == AttributeEventType.DELETE:
+            return f"del {mock_name}"
+
+        # unused, attribute get events are not logged
+        return mock_name  # pragma: no cover
+
+    else:
+        args_list = [repr(arg) for arg in event.args]
+        kwargs_list = [f"{key}={val!r}" for key, val in event.kwargs.items()]
+        extra_args_msg = (
+            " - ignoring unspecified arguments" if ignore_extra_args else ""
+        )
+
+        return f"{mock_name}({', '.join(args_list + kwargs_list)}){extra_args_msg}"
+
+
+def stringify_event_list(mock_name: str, events: Iterable[Event]) -> str:
+    """Stringify a sequence of mock events into an ordered list."""
+    return _stringify_ordered_list(
+        stringify_event(mock_name, event) for event in events
+    )
+
+
+def stringify_event_entry_list(event_entries: Iterable[EventEntry]) -> str:
+    """Stringify a sequence of verifications into an ordered list."""
+    return _stringify_ordered_list(
+        stringify_event(entry.mock.name, entry.event) for entry in event_entries
+    )
+
+
+def stringify_verification_list(verifications: Iterable[VerificationEntry]) -> str:
+    """Stringify a sequence of verifications into an ordered list."""
+    events: list[tuple[str, Event]] = []
+
+    for verification in verifications:
+        times = verification.matcher.options.times
+        if times is None:
+            times = 1
+
+        for _ in range(times):
+            events.append((verification.mock.name, verification.matcher.event))
+
+    return _stringify_ordered_list(
+        stringify_event(mock_name, event) for mock_name, event in events
+    )
+
+
+def count(count: int, noun: str) -> str:
+    """Count a given noun, pluralizing if necessary."""
+    return f"{count} {noun}{'s' if count != 1 else ''}"
+
+
+def join_lines(*lines: str) -> str:
+    """Join a list of lines with newline characters."""
+    return os.linesep.join(lines).strip()
+
+
+def _stringify_ordered_list(lines: Iterable[str]) -> str:
+    return join_lines(*(f"{i + 1}.\t{line}" for i, line in enumerate(lines)))

decoy/next/_internal/values.py

@@ -0,0 +1,96 @@
+"""Value objects that move around the mocking system."""
+
+import enum
+import inspect
+from typing import Callable, NamedTuple, final
+
+
+@final
+class MISSING:
+    """Value not specified sentinel.
+
+    Used when `None` could be a valid value,
+    so `Optional` would be inappropriate.
+    """
+
+
+class AttributeEventType(str, enum.Enum):
+    GET = "get"
+    SET = "set"
+    DELETE = "delete"
+
+
+class AttributeEvent(NamedTuple):
+    type: AttributeEventType
+    value: object = MISSING
+
+    @classmethod
+    def get(cls) -> "AttributeEvent":
+        return cls(AttributeEventType.GET)
+
+    @classmethod
+    def set(cls, value: object) -> "AttributeEvent":
+        return cls(AttributeEventType.SET, value)
+
+    @classmethod
+    def delete(cls) -> "AttributeEvent":
+        return cls(AttributeEventType.DELETE)
+
+
+class CallEvent(NamedTuple):
+    """Event representing a call to a function or method."""
+
+    args: tuple[object, ...]
+    kwargs: dict[str, object]
+
+
+Event = CallEvent | AttributeEvent
+
+
+class EventState(NamedTuple):
+    is_entered: bool
+
+
+class MatchOptions(NamedTuple):
+    times: int | None
+    ignore_extra_args: bool
+    is_entered: bool | None
+
+
+class Behavior(NamedTuple):
+    return_value: object = None
+    error: Exception | None = None
+    action: Callable[..., object] | None = None
+    context: object = MISSING
+
+
+class EventMatcher(NamedTuple):
+    event: Event
+    options: MatchOptions
+
+
+class MockInfo(NamedTuple):
+    id: int
+    name: str
+    is_async: bool
+    signature: inspect.Signature | None
+
+
+class EventEntry(NamedTuple):
+    mock: MockInfo
+    event: Event
+    state: EventState
+    order: int
+
+
+class BehaviorEntry(NamedTuple):
+    mock: MockInfo
+    matcher: EventMatcher
+    behavior: Behavior
+    order: int
+
+
+class VerificationEntry(NamedTuple):
+    mock: MockInfo
+    matcher: EventMatcher
+    matching_events: list[EventEntry]