panda-pytest-assertions 0.1.0__py3-none-any.whl

panda_pytest_assertions/assert_object/_expectation_modificators/with_type.py

@@ -0,0 +1,135 @@
+from collections.abc import Callable
+from typing import Any, overload
+
+
+class WithType:
+    """
+    Wrapper for the expectation that additionally checks object's type.
+    """
+
+    def __init__(
+        self,
+        expectation: Any,  # noqa: ANN401
+        expected_type_name: str,
+        expected_type_module: str | None,
+        /,
+    ) -> None:
+        #: object expectation
+        self.expectation = expectation
+        #: expected name of the object type
+        self.expected_type_name = expected_type_name
+        #: expected module of the object type
+        self.expected_type_module = expected_type_module
+
+    def __repr__(self) -> str:
+        return (
+            f'WithType('
+            f'expectation={self.expectation!r}, '
+            f'expected_type_name={self.expected_type_name!r}, '
+            f'expected_type_module={self.expected_type_module!r}'
+            f')'
+        )
+
+
+#: type alias to simplify definitions below
+_WithTypeCreator = Callable[[Any], WithType]
+
+
+@overload
+def with_type() -> _WithTypeCreator:  # noqa: D418
+    """
+    Return the function that will accept an object and create expectations additionally asserting object type.
+
+    Returned function accepts any kind of value and will create proper expectation.
+
+    Expected type name and type module will be extracted from the object passed to the returned function.
+    """
+
+
+@overload
+def with_type(value_type: type[Any], /) -> _WithTypeCreator:  # noqa: D418
+    """
+    Return the function that will accept an object and create expectations additionally asserting object type.
+
+    Returned function accepts any kind of value and will create proper expectation.
+
+    Expected type name and type module will be extracted from the provided type type.
+
+    :param value_type: type to extract expected type name and module from
+    """
+
+
+@overload
+def with_type(  # noqa: D418
+    value_type_name: str,
+    value_type_module: str | None = None,
+    /,
+) -> _WithTypeCreator:
+    """
+    Return the function that will accept an object and create expectations additionally asserting object type.
+
+    Returned function accepts any kind of value and will create proper expectation.
+
+    Expected type name will be equal to `value_type_name` and expected module name will be
+    equal to `value_type_module` (which can be not set if is not supposed to be asserted).
+
+    :param value_type_name: name of the expected type
+    :param value_type_module: module of the expected type
+    """
+
+
+def with_type(
+    value_type: type[Any] | str | None = None,
+    value_type_module: str | None = None,
+    /,
+) -> _WithTypeCreator:
+    """
+    Return the function that will accept an object and create expectations additionally asserting object type.
+
+    Returned function accepts any kind of value and will create WithType expectation.
+
+    If `value_type` parameter is not set, expected type name and type module will be extracted from the object
+    passed to the returned function.
+
+    If `value_type` is a type, expected type name and type module will be extracted from this type.
+
+    If `value_type` is a string, expected type name will be equal to it and expected module name will be
+    equal to provided `value_type_module` (which can be not set if is not supposed to be asserted).
+
+    :param value_type: expected type or name of the type
+    :param value_type_module: expected type's module
+    :return: function that will take create proper type-aware expectation
+    """
+    match value_type, value_type_module:
+        case None, None:
+            expected_type_name = None
+            expected_type_module = None
+        case type(), None:
+            assert isinstance(value_type, type)
+            expected_type_name = value_type.__name__
+            expected_type_module = value_type.__module__
+        case str(), str() | None:
+            assert isinstance(value_type, str)
+            expected_type_name = value_type
+            expected_type_module = value_type_module
+        case _:
+            msg = (
+                f'WithType helper constructor does not accept the following arguments: '
+                f'{(value_type, value_type_module)}'
+            )
+            raise ValueError(msg)
+
+    def _creator(expectation: Any) -> WithType:  # noqa: ANN401
+        if expected_type_name is None:
+            return WithType(
+                expectation,
+                expectation.__class__.__name__,
+                expectation.__class__.__module__,
+            )
+        return WithType(
+            expectation,
+            expected_type_name,
+            expected_type_module,
+        )
+
+    return _creator

panda_pytest_assertions/assert_object/_objects_asserters/__init__.py

@@ -0,0 +1,36 @@
+# ruff: noqa: E402
+# isort: off
+import pytest
+
+pytest.register_assert_rewrite(__name__ + '.equality_asserter')
+pytest.register_assert_rewrite(__name__ + '.mapping_asserter')
+pytest.register_assert_rewrite(__name__ + '.mapping_subset_asserter')
+pytest.register_assert_rewrite(__name__ + '.object_attributes_asserter')
+pytest.register_assert_rewrite(__name__ + '.ordered_elements_asserter')
+pytest.register_assert_rewrite(__name__ + '.stringified_asserter')
+pytest.register_assert_rewrite(__name__ + '.unordered_elements_asserter')
+pytest.register_assert_rewrite(__name__ + '.with_type_asserter')
+# isort: on
+
+from .asserter import Asserter
+from .equality_asserter import EqualityAsserter
+from .mapping_asserter import MappingAsserter
+from .mapping_subset_asserter import MappingSubsetAsserter
+from .object_attributes_asserter import ObjectAttributesAsserter
+from .ordered_elements_asserter import OrderedElementsAsserter
+from .stringified_asserter import StringifiedAsserter
+from .unordered_elements_asserter import UnorderedElementsAsserter
+from .with_type_asserter import WithTypeAsserter
+
+
+__all__ = [
+    'Asserter',
+    'EqualityAsserter',
+    'MappingAsserter',
+    'MappingSubsetAsserter',
+    'ObjectAttributesAsserter',
+    'OrderedElementsAsserter',
+    'StringifiedAsserter',
+    'UnorderedElementsAsserter',
+    'WithTypeAsserter',
+]

panda_pytest_assertions/assert_object/_objects_asserters/asserter.py

@@ -0,0 +1,35 @@
+import abc
+from typing import Any
+
+from panda_pytest_assertions.assert_object._protocols import AsserterFactoryProtocol
+
+
+class Asserter(abc.ABC):
+    """
+    Asserter checking that the given expectation is fulfilled by the object.
+    """
+
+    @classmethod
+    @abc.abstractmethod
+    def matches(cls, expectation: Any) -> bool:  # noqa: ANN401
+        """
+        Decide whether provided expectation can be handled by this asserter.
+
+        :param expectation: expectation to be tested
+        """
+
+    def __init__(
+        self,
+        asserter_factory: type[AsserterFactoryProtocol],
+        expectation: Any,  # noqa: ANN401
+    ) -> None:
+        self.asserter_factory = asserter_factory
+        self.expectation = expectation
+
+    @abc.abstractmethod
+    def assert_object(self, object_: Any) -> None:  # noqa: ANN401
+        """
+        Assert if the expectation is fulfilled by an object.
+
+        :param object_: an object to be tested
+        """

panda_pytest_assertions/assert_object/_objects_asserters/equality_asserter.py

@@ -0,0 +1,33 @@
+from typing import Any
+
+from .asserter import Asserter
+
+
+class EqualityAsserter(Asserter):
+    """
+    Assert that the object is equal to the expectation.
+
+    It is a default, fallback asserter that matches ANY object, so it is critical that it is
+    the last one checked.
+    """
+
+    @classmethod
+    def matches(cls, expectation: Any) -> bool:  # noqa: ANN401
+        """
+        Decide whether provided expectation can be handled by this asserter.
+
+        This asserter can handle any object, as __eq__ is defined for all types.
+
+        :param expectation: expectation to be tested
+        :return: whether expectation can be handled by this asserter
+        """
+        _ = expectation
+        return True
+
+    def assert_object(self, object_: Any) -> None:  # noqa: ANN401
+        """
+        Assert if the expectation is fulfilled by an object.
+
+        :param object_: an object to be tested
+        """
+        assert self.expectation == object_

panda_pytest_assertions/assert_object/_objects_asserters/mapping_asserter.py

@@ -0,0 +1,55 @@
+from collections.abc import Mapping
+from typing import Any
+
+from panda_pytest_assertions.assert_object._protocols import AsserterFactoryProtocol
+
+from .asserter import Asserter
+
+
+class MappingAsserter(Asserter):
+    """
+    Assert mapping items fulfill expectations defined in another mapping.
+
+    Expectation is a mapping between object keys and coresponding expectation. The object must
+    contain the exact same keys as the expectation, no more, no less.
+    """
+
+    @classmethod
+    def matches(cls, expectation: Any) -> bool:  # noqa: ANN401
+        """
+        Decide whether provided expectation can be handled by this asserter.
+
+        This asserter can handle any mapping expectation.
+
+        :param expectation: expectation to be tested
+        :return: whether expectation can be handled by this asserter
+        """
+        return isinstance(expectation, Mapping)
+
+    def __init__(
+        self,
+        asserter_factory: type[AsserterFactoryProtocol],
+        expectation: Mapping[Any, Any],
+    ) -> None:
+        super().__init__(asserter_factory, expectation)
+        self._items_asserters = {
+            key: asserter_factory.create(expectation) for key, expectation in expectation.items()
+        }
+
+    def assert_object(self, object_: Any) -> None:  # noqa: ANN401
+        """
+        Assert if the expectation is fulfilled by an object.
+
+        :param object_: an object to be tested
+        """
+        assert isinstance(object_, Mapping), f'Object must be a mapping. Got: {type(object_)}.'
+        assert (
+            object_.keys() == self._items_asserters.keys()
+        ), 'Object keys must be equal to expectation keys.'
+        for key, asserter in self._items_asserters.items():
+            object_value = object_[key]
+            try:
+                asserter.assert_object(object_value)
+            except AssertionError as exc:
+                msg = f'Mapping value for key "{key}" is invalid. {exc!s}'
+                raise AssertionError(msg) from None

panda_pytest_assertions/assert_object/_objects_asserters/mapping_subset_asserter.py

@@ -0,0 +1,53 @@
+from collections.abc import Mapping
+from typing import Any
+
+from panda_pytest_assertions.assert_object._protocols import AsserterFactoryProtocol
+
+from .._expectation_modificators import MappingSubset  # noqa: TID252
+from .asserter import Asserter
+
+
+class MappingSubsetAsserter(Asserter):
+    """
+    Assert mapping items fulfill expectations defined in another mapping.
+
+    Expectation is a mapping between object keys and coresponding expectation. The object
+    must contain all the keys defined in expectation, but may also contain more.
+    """
+
+    @classmethod
+    def matches(cls, expectation: Any) -> bool:  # noqa: ANN401
+        """
+        Decide whether provided expectation can be handled by this asserter.
+
+        This asserter can handle a MappingSubset expectation.
+
+        :param expectation: expectation to be tested
+        :return: whether expectation can be handled by this asserter
+        """
+        return isinstance(expectation, MappingSubset)
+
+    def __init__(self, asserter_factory: type[AsserterFactoryProtocol], expectation: MappingSubset) -> None:
+        super().__init__(asserter_factory, expectation)
+        self._items_asserters = {
+            key: asserter_factory.create(expectation)
+            for key, expectation in expectation.items_expectations.items()
+        }
+
+    def assert_object(self, object_: Any) -> None:  # noqa: ANN401
+        """
+        Assert if the expectation is fulfilled by an object.
+
+        :param object_: an object to be tested
+        """
+        assert isinstance(object_, Mapping), f'Object must be a mapping. Got: {type(object_)}.'
+        assert (
+            object_.keys() >= self._items_asserters.keys()
+        ), 'Object keys must be a superset of expectation keys.'
+        for key, asserter in self._items_asserters.items():
+            object_value = object_[key]
+            try:
+                asserter.assert_object(object_value)
+            except AssertionError as exc:
+                msg = f'Mapping value for key "{key}" is invalid. {exc!s}'
+                raise AssertionError(msg) from None

panda_pytest_assertions/assert_object/_objects_asserters/object_attributes_asserter.py

@@ -0,0 +1,52 @@
+from typing import Any
+
+from panda_pytest_assertions.assert_object._protocols import AsserterFactoryProtocol
+
+from .._expectation_modificators import ObjectAttributes  # noqa: TID252
+from .asserter import Asserter
+
+
+class ObjectAttributesAsserter(Asserter):
+    """
+    Assert the values of object's attributes fulfill expectation defined in the dictionary.
+
+    Expectation dictionary is a mapping between attribute name and its expectation.
+    """
+
+    @classmethod
+    def matches(cls, expectation: Any) -> bool:  # noqa: ANN401
+        """
+        Decide whether provided expectation can be handled by this asserter.
+
+        This asserter can handle an ObjectAttributes expectation.
+
+        :param expectation: expectation to be tested
+        :return: whether expectation can be handled by this asserter
+        """
+        return isinstance(expectation, ObjectAttributes)
+
+    def __init__(
+        self,
+        asserter_factory: type[AsserterFactoryProtocol],
+        expectation: ObjectAttributes,
+    ) -> None:
+        super().__init__(asserter_factory, expectation)
+        self._attributes_asserters = {
+            attr_name: asserter_factory.create(attr_expectation)
+            for attr_name, attr_expectation in expectation.attributes_expectations.items()
+        }
+
+    def assert_object(self, object_: Any) -> None:  # noqa: ANN401
+        """
+        Assert if the expectation is fulfilled by an object.
+
+        :param object_: an object to be tested
+        """
+        for attr_name, attr_asserter in self._attributes_asserters.items():
+            assert hasattr(object_, attr_name), f'Objects is missing attribute "{attr_name}".'
+            attr_value = getattr(object_, attr_name)
+            try:
+                attr_asserter.assert_object(attr_value)
+            except AssertionError as exc:
+                msg = f'Objects attribute "{attr_name}" has invalid value. {exc!s}'
+                raise AssertionError(msg) from None

panda_pytest_assertions/assert_object/_objects_asserters/ordered_elements_asserter.py

@@ -0,0 +1,55 @@
+from collections.abc import Iterable, Sequence
+from typing import Any
+
+from panda_pytest_assertions.assert_object._protocols import AsserterFactoryProtocol
+
+from .asserter import Asserter
+
+
+class OrderedElementsAsserter(Asserter):
+    """
+    Assert that elements of a flat collection are fulfill by provided expectations.
+
+    The order of expectations must match the order fo elements.
+    """
+
+    @classmethod
+    def matches(cls, expectation: Any) -> bool:  # noqa: ANN401
+        """
+        Decide whether provided expectation can be handled by this asserter.
+
+        This asserter can handle a list or a tuple expectation.
+
+        :param expectation: expectation to be tested
+        :return: whether expectation can be handled by this asserter
+        """
+        return isinstance(expectation, list | tuple)
+
+    def __init__(
+        self,
+        asserter_factory: type[AsserterFactoryProtocol],
+        expectation: list[Any] | tuple[Any, ...],
+    ) -> None:
+        super().__init__(asserter_factory, expectation)
+        self._elements_asserters = [
+            asserter_factory.create(element_expectation) for element_expectation in expectation
+        ]
+
+    def assert_object(self, object_: Sequence[Any]) -> None:
+        """
+        Assert if the expectation is fulfilled by an object.
+
+        :param object_: an object to be tested
+        """
+        assert isinstance(object_, Iterable), f'Object must be iterable. Got: {type(object_)}.'
+        elements = list(object_)
+        assert len(elements) == len(self._elements_asserters), (
+            f'Length of an object ({len(elements)}) does not equal to the number of '
+            f'expectations ({len(self._elements_asserters)}).'
+        )
+        for index, (element, asserter) in enumerate(zip(elements, self._elements_asserters, strict=True)):
+            try:
+                asserter.assert_object(element)
+            except AssertionError as exc:
+                msg = f'Element with index [{index}] has invalid value. {exc!s}'
+                raise AssertionError(msg) from None

panda_pytest_assertions/assert_object/_objects_asserters/stringified_asserter.py

@@ -0,0 +1,36 @@
+from typing import Any
+
+from panda_pytest_assertions.assert_object._protocols import AsserterFactoryProtocol
+
+from .._expectation_modificators import Stringified  # noqa: TID252
+from .asserter import Asserter
+
+
+class StringifiedAsserter(Asserter):
+    """
+    Assert that the stringified object is a given value.
+    """
+
+    @classmethod
+    def matches(cls, expectation: Any) -> bool:  # noqa: ANN401
+        """
+        Decide whether provided expectation can be handled by this asserter.
+
+        This asserter can handle a Stringified expectation.
+
+        :param expectation: expectation to be tested
+        :return: whether expectation can be handled by this asserter
+        """
+        return isinstance(expectation, Stringified)
+
+    def __init__(self, asserter_factory: type[AsserterFactoryProtocol], expectation: Stringified) -> None:
+        super().__init__(asserter_factory, expectation)
+        self.expected_value = expectation.stringified_value
+
+    def assert_object(self, object_: Any) -> None:  # noqa: ANN401
+        """
+        Assert if the expectation is fulfilled by an object.
+
+        :param object_: an object to be tested
+        """
+        assert str(object_) == self.expected_value, 'Stringified value of an object is invalid.'

panda_pytest_assertions/assert_object/_objects_asserters/unordered_elements_asserter.py

@@ -0,0 +1,77 @@
+from collections.abc import Iterable
+from typing import Any
+
+from panda_pytest_assertions.assert_object._protocols import AsserterFactoryProtocol, AsserterProtocol
+
+from .._expectation_modificators import Unordered  # noqa: TID252
+from .asserter import Asserter
+
+
+class UnorderedElementsAsserter(Asserter):
+    """
+    Assert that elements of a flat collection are fulfill by provided expectations.
+
+    The order of expectations does not matter, but all elements of an array must match at least one
+    expectation and each expectation must match at least one element.
+
+    The algorithm iterates over expectatations and if any of the element matches an expectation,
+    both expectation and element are not considered anymore.
+    """
+
+    @classmethod
+    def matches(cls, expectation: Any) -> bool:  # noqa: ANN401
+        """
+        Decide whether provided expectation can be handled by this asserter.
+
+        This asserter can handle an UnorderedList or a set expectation.
+
+        :param expectation: expectation to be tested
+        :return: whether expectation can be handled by this asserter
+        """
+        return isinstance(expectation, Unordered | set)
+
+    def __init__(
+        self,
+        asserter_factory: type[AsserterFactoryProtocol],
+        expectation: Unordered | set[Any],
+    ) -> None:
+        super().__init__(asserter_factory, expectation)
+        self._elements_asserters = [
+            asserter_factory.create(element_expectation) for element_expectation in expectation
+        ]
+
+    def assert_object(self, object_: Iterable[Any]) -> None:
+        """
+        Assert if the expectation is fulfilled by an object.
+
+        :param object_: an object to be tested
+        """
+        assert isinstance(object_, Iterable), f'Object must be iterable. Got: {type(object_)}.'
+        elements_yet_not_fulfilled = list(object_)
+        assert len(elements_yet_not_fulfilled) == len(self._elements_asserters), (
+            f'Length of an object ({len(elements_yet_not_fulfilled)}) does not equal to the number of '
+            f'expectations ({len(self._elements_asserters)})'
+        )
+        for element_asserter in self._elements_asserters:
+            matching_element = self._get_first_element_asserting(element_asserter, elements_yet_not_fulfilled)
+            if matching_element is not None:
+                elements_yet_not_fulfilled.remove(matching_element)
+                continue
+            msg = (
+                f'None of the elements of a collection has fulfilled expectation '
+                f'"{element_asserter.expectation!r}"'
+            )
+            raise AssertionError(msg)
+
+    @staticmethod
+    def _get_first_element_asserting(
+        element_asserter: AsserterProtocol,
+        elements: list[Any],
+    ) -> Any | None:  # noqa: ANN401
+        for element in elements:
+            try:
+                element_asserter.assert_object(element)
+            except Exception:  # noqa: S112, BLE001
+                continue
+            return element
+        return None

panda_pytest_assertions/assert_object/_objects_asserters/with_type_asserter.py

@@ -0,0 +1,57 @@
+from typing import Any
+
+from panda_pytest_assertions.assert_object._protocols import AsserterFactoryProtocol
+
+from .._expectation_modificators import WithType  # noqa: TID252
+from .asserter import Asserter
+
+
+class WithTypeAsserter(Asserter):
+    """
+    Assert that the object matches given expectation and is of a proper type.
+    """
+
+    @classmethod
+    def matches(cls, expectation: Any) -> bool:  # noqa: ANN401
+        """
+        Decide whether provided expectation can be handled by this asserter.
+
+        This asserter can handle a WithType expectation.
+
+        :param expectation: expectation to be tested
+        :return: whether expectation can be handled by this asserter
+        """
+        return isinstance(expectation, WithType)
+
+    def __init__(self, asserter_factory: type[AsserterFactoryProtocol], expectation: WithType) -> None:
+        super().__init__(asserter_factory, expectation)
+        self.expected_type_name = expectation.expected_type_name
+        self.expected_type_module = expectation.expected_type_module
+        self.object_asserter = asserter_factory.create(expectation.expectation)
+
+    def assert_object(self, object_: Any) -> None:  # noqa: ANN401
+        """
+        Assert if the expectation is fulfilled by an object.
+
+        :param object_: an object to be tested
+        """
+        if object_.__class__.__name__ != self.expected_type_name:
+            msg = (
+                f'Object type ("{type(object_)}") has invalid name. '
+                f'Expected "{self.expected_type_name}", got "{object_.__class__.__name__}".'
+            )
+            raise AssertionError(msg)
+        if (
+            self.expected_type_module is not None
+            and object_.__class__.__module__ != self.expected_type_module
+        ):
+            msg = (
+                f'Object type ("{type(object_)}") is from invalid module. '
+                f'Expected "{self.expected_type_module}", got "{object_.__class__.__module__}".'
+            )
+            raise AssertionError(msg)
+        try:
+            self.object_asserter.assert_object(object_)
+        except AssertionError as exc:
+            msg = f'Object is invalid. {exc!s}'
+            raise AssertionError(msg) from None