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

panda_pytest_assertions/assert_context/__init__.py

@@ -0,0 +1,15 @@
+# ruff: noqa: E402
+# isort: off
+import pytest
+
+pytest.register_assert_rewrite(__name__ + '._assert_context')
+# isort: on
+
+
+from ._assert_context import assert_context, AssertContext
+
+
+__all__ = [
+    'assert_context',
+    'AssertContext',
+]

panda_pytest_assertions/assert_context/_assert_context.py

@@ -0,0 +1,128 @@
+from collections.abc import Generator
+from contextlib import contextmanager, ExitStack, nullcontext
+from typing import Any, overload
+
+import pytest
+
+
+class _Unset:
+    __instance: '_Unset | None' = None
+
+    def __new__(cls) -> '_Unset':
+        if cls.__instance is None:
+            cls.__instance = object.__new__(cls)
+        return cls.__instance
+
+
+_UNSET = _Unset()
+
+
+class AssertContext:
+    __slots__ = ('_result',)
+
+    def __init__(self) -> None:
+        self._result: Any = _UNSET
+
+    def set(self, value: Any) -> None:  # noqa: ANN401
+        self._result = value
+
+    @contextmanager
+    def assert_result_equal(self, expected_result: Any) -> Generator[None, None, None]:  # noqa: ANN401
+        yield
+        assert expected_result == self._result
+
+
+@overload
+@contextmanager
+def assert_context(  # noqa: D418
+    *,
+    exception: type[Exception] | _Unset = ...,
+    result: Any | _Unset = ...,  # noqa: ANN401
+) -> Generator[AssertContext, None, None]:
+    """
+    Context manager that makes sure `with` block behaved according to the arguments.
+
+    If the `exception` parameter is set, the `with` block is expected to raise an exception of provided type.
+    If it is NOT set, the `with` block is expected NOT TO raise any exceptions.
+
+    If the `result` parameter is set, its value is expected to be equal to `with` block result. The `with`
+    block result is set with the `set` method of an object yielded by the context manager. The comparison
+    is used with `==` operator, where `result` argument is on the left side.
+    If the `result` parameter is NOT set, the `set` method of yielded object is expected
+    not to be called at all.
+
+    :param exception: type of exception, expected to be raised
+    :param result: value expected to be set with `set` method of yielded object
+    """
+
+
+@overload
+@contextmanager
+def assert_context(  # noqa: D418
+    *,
+    behaviour: type[Exception] | Any | _Unset = ...,  # noqa: ANN401
+) -> Generator[AssertContext, None, None]:
+    """
+    Context manager that makes sure `with` block behaved according to the arguments.
+
+    Context manager yields a single object used that provides `set` method used to set the `with`
+    block result that is to be asserted.
+
+    If the `behaviour` parameter is set to an exception type, the `with` block is expected
+    to raise an exception of provided type and the `set` method of yielded object is expected
+    not to be called at all.
+
+    If the `behaviour` parameter is set to anything else, its value is expected to be equal to `with`
+    block result. The comparison is used with `==` operator, where `result` argument is on the left side and
+    the `with` block is expected to not raise any exceptions.
+
+    If the `behaviour` parameter is NOT set, the `with` block is expected NOT TO raise any exceptions and
+    the `set` method of yielded object is expected not to be called at all.
+
+    :param behaviour: describes expected behaviour of the `with` block
+    """
+
+
+@contextmanager
+def assert_context(
+    *,
+    exception: type[Exception] | _Unset = _UNSET,
+    result: Any | _Unset = _UNSET,
+    behaviour: type[Exception] | Any | _Unset = _UNSET,
+) -> Generator[AssertContext, None, None]:
+    """
+    Context manager that makes sure `with` block behaved according to the arguments.
+
+    Pair of parameters `exception` and `result` are exclusive with parameter `behaviour`. If `behaviour`
+    is set to an exception type, it is the same as if `exception` would be set to this value and `result`
+    would not be set. If `behaviour` is set to any other value, its treated as the value of `result` and the
+    `exception` remains unset.
+
+    If the `exception` parameter is set, the `with` block is expected to raise an exception of provided type.
+    If it is NOT set, the `with` block is expected NOT TO raise any exceptions.
+
+    If the `result` parameter is set, its value is expected to be equal to `with` block result. The `with`
+    block result is set with the `set` method of an object yielded by the context manager. The comparison
+    is used with `==` operator, where `result` argument is on the left side.
+    If the `result` parameter is NOT set, the `set` method of yielded object is expected
+    not to be called at all.
+
+    :param exception: type of exception, expected to be raised
+    :param result: value expected to be set with `set` method of yielded object
+    :param behaviour: a common name for `exception` and `result` parameters, exclusive to them
+    :yield: object used to set the result of a `with` block
+    """
+    if behaviour != _UNSET:
+        assert exception == _UNSET
+        assert result == _UNSET
+        if isinstance(behaviour, type) and issubclass(behaviour, Exception):
+            exception = behaviour
+        else:
+            result = behaviour
+    context = AssertContext()
+    exception_behaviour = nullcontext() if isinstance(exception, _Unset) else pytest.raises(exception)
+
+    with ExitStack() as behaviours_stack:
+        behaviours_stack.enter_context(context.assert_result_equal(result))
+        behaviours_stack.enter_context(exception_behaviour)
+        yield context

panda_pytest_assertions/assert_object/__init__.py

@@ -0,0 +1,41 @@
+from ._assert_object import assert_object, Expectation
+from ._asserter_factories import AsserterFactory, BuiltInAsserterFactory
+from ._converters import (
+    expectation_from_yaml,
+    expectation_to_yaml,
+    ExpectationYamlDumper,
+    ExpectationYamlLoader,
+)
+from ._expectation_modificators import (
+    MappingSubset,
+    ObjectAttributes,
+    Stringified,
+    Unordered,
+    with_type,
+    WithType,
+)
+from ._objects_asserters import Asserter
+from ._protocols import AsserterFactoryProtocol, AsserterProtocol, GeneratorFactoryProtocol, GeneratorProtocol
+
+
+__all__ = [
+    'assert_object',
+    'Expectation',
+    'AsserterFactory',
+    'BuiltInAsserterFactory',
+    'expectation_to_yaml',
+    'expectation_from_yaml',
+    'ExpectationYamlDumper',
+    'ExpectationYamlLoader',
+    'MappingSubset',
+    'ObjectAttributes',
+    'Stringified',
+    'Unordered',
+    'with_type',
+    'WithType',
+    'Asserter',
+    'AsserterProtocol',
+    'AsserterFactoryProtocol',
+    'GeneratorFactoryProtocol',
+    'GeneratorProtocol',
+]

panda_pytest_assertions/assert_object/_assert_object.py

@@ -0,0 +1,36 @@
+from typing import Any
+
+from ._asserter_factories import BuiltInAsserterFactory
+from ._protocols import AsserterFactoryProtocol
+
+
+def assert_object(
+    expectation: Any,  # noqa: ANN401
+    object_: Any,  # noqa: ANN401
+    *,
+    asserter_factory: type[AsserterFactoryProtocol] = BuiltInAsserterFactory,
+) -> None:
+    asserter = asserter_factory.create(expectation)
+    try:
+        asserter.assert_object(object_)
+    except AssertionError as exc:
+        msg = f'Object assertion failed. {exc!s}'
+        raise AssertionError(msg) from None
+
+
+class Expectation:
+    def __init__(
+        self,
+        expectation: Any,  # noqa: ANN401
+        *,
+        asserter_factory: type[AsserterFactoryProtocol] = BuiltInAsserterFactory,
+    ) -> None:
+        self.expectation = expectation
+        self.asserter_factory = asserter_factory
+
+    def __eq__(self, value: object) -> bool:
+        try:
+            assert_object(self.expectation, value, asserter_factory=self.asserter_factory)
+        except AssertionError:
+            return False
+        return True

panda_pytest_assertions/assert_object/_asserter_factories/__init__.py

@@ -0,0 +1,8 @@
+from .asserter_factory import AsserterFactory
+from .built_in_asserter_factory import BuiltInAsserterFactory
+
+
+__all__ = [
+    'AsserterFactory',
+    'BuiltInAsserterFactory',
+]

panda_pytest_assertions/assert_object/_asserter_factories/asserter_factory.py

@@ -0,0 +1,66 @@
+from collections import deque
+from typing import Any, ClassVar
+
+from panda_pytest_assertions.assert_object._protocols import AsserterProtocol
+
+
+class AsserterFactory:
+    """
+    Factory for registered asserters.
+    """
+
+    #: list of registered asserter classes
+    _ASSERTER_TYPES: ClassVar[deque[type[AsserterProtocol]]] = deque()
+
+    @classmethod
+    def create(cls, expectation: Any) -> AsserterProtocol:  # noqa: ANN401
+        """
+        Create asserter object for given expectation.
+
+        The function goes through all registered asserter types and creates the first one that matches.
+
+        :param expectation: expectation to create asserter for
+        :return: created asserter
+        """
+        for asserter_type in cls._ASSERTER_TYPES:
+            if asserter_type.matches(expectation):
+                return asserter_type(cls, expectation)
+        msg = (
+            f'None of the registered asserters matches expectation "{expectation}" '
+            f'of type "{type(expectation)}".'
+        )
+        raise ValueError(msg)
+
+    @classmethod
+    def register_asserter(
+        cls,
+        asserter: type[AsserterProtocol],
+        *,
+        after: type[AsserterProtocol] | None = None,
+        before: type[AsserterProtocol] | None = None,
+    ) -> None:
+        """
+        Register the provided asserter to be used.
+
+        The asserter is registered at the earliest possible position. If `after` and `before`
+        parameters are not set, it is registered at the beginning of the list to be matched
+        when creating asserter for expectations.
+
+        :param asserter: asserter to be registered
+        :param after: registered asserter must be matched after this one
+        :param before: registered asserter must be matched before this one
+        """
+        if '_ASSERTER_TYPES' not in cls.__dict__:
+            cls._ASSERTER_TYPES = cls._ASSERTER_TYPES.copy()
+
+        after_position = cls._ASSERTER_TYPES.index(after) if after is not None else -1
+        before_position = (
+            cls._ASSERTER_TYPES.index(before) if before is not None else len(cls._ASSERTER_TYPES) + 1
+        )
+        if after_position >= before_position:
+            msg = (
+                f'Cannot register asserter between "{after}" and "{before}" as their '
+                f'respective positions are: "{after_position}" and "{before_position}"'
+            )
+            raise ValueError(msg)
+        cls._ASSERTER_TYPES.insert(after_position + 1, asserter)

panda_pytest_assertions/assert_object/_asserter_factories/built_in_asserter_factory.py

@@ -0,0 +1,29 @@
+from panda_pytest_assertions.assert_object._objects_asserters import (
+    EqualityAsserter,
+    MappingAsserter,
+    MappingSubsetAsserter,
+    ObjectAttributesAsserter,
+    OrderedElementsAsserter,
+    StringifiedAsserter,
+    UnorderedElementsAsserter,
+    WithTypeAsserter,
+)
+
+from .asserter_factory import AsserterFactory
+
+
+class BuiltInAsserterFactory(AsserterFactory):
+    """
+    Factory that has all built-in asserters registered.
+    """
+
+
+# MUST be the first one as it implements a fallback mechanism and matches everything
+BuiltInAsserterFactory.register_asserter(EqualityAsserter)
+BuiltInAsserterFactory.register_asserter(MappingAsserter)
+BuiltInAsserterFactory.register_asserter(MappingSubsetAsserter)
+BuiltInAsserterFactory.register_asserter(ObjectAttributesAsserter)
+BuiltInAsserterFactory.register_asserter(OrderedElementsAsserter)
+BuiltInAsserterFactory.register_asserter(StringifiedAsserter)
+BuiltInAsserterFactory.register_asserter(UnorderedElementsAsserter)
+BuiltInAsserterFactory.register_asserter(WithTypeAsserter)

panda_pytest_assertions/assert_object/_converters/__init__.py

@@ -0,0 +1,10 @@
+from .expectation_from_yaml import expectation_from_yaml, ExpectationYamlLoader
+from .expectation_to_yaml import expectation_to_yaml, ExpectationYamlDumper
+
+
+__all__ = [
+    'expectation_from_yaml',
+    'ExpectationYamlLoader',
+    'expectation_to_yaml',
+    'ExpectationYamlDumper',
+]

panda_pytest_assertions/assert_object/_converters/expectation_from_yaml.py

@@ -0,0 +1,114 @@
+from collections.abc import Callable
+from typing import Any, cast, TypeVar
+
+import yaml
+from yaml.constructor import ConstructorError
+
+from panda_pytest_assertions.assert_object._expectation_modificators import (
+    MappingSubset,
+    ObjectAttributes,
+    Stringified,
+    Unordered,
+    WithType,
+)
+
+
+def expectation_from_yaml(yaml_string: str) -> Any:  # noqa: ANN401
+    """
+    Serialize expectation to YAML format.
+
+    :param yaml_string: YAML string to create expectation from
+    :return: YAML string representing expectation
+    """
+    return yaml.load(yaml_string, Loader=ExpectationYamlLoader)  # noqa: S506
+
+
+_T = TypeVar('_T')
+_Constructor = Callable[['ExpectationYamlLoader', yaml.Node], _T]
+
+
+class ExpectationYamlLoader(yaml.SafeLoader):
+    @classmethod
+    def add_construct(cls, tag: str) -> Callable[[_Constructor[_T]], _Constructor[_T]]:
+        def _wrapper(constructor: _Constructor[_T]) -> _Constructor[_T]:
+            ExpectationYamlLoader.add_constructor(tag, constructor)
+            return constructor
+
+        return _wrapper
+
+
+@ExpectationYamlLoader.add_construct('!MappingSubset')
+def _(loader: ExpectationYamlLoader, node: yaml.Node) -> MappingSubset:
+    if not isinstance(node, yaml.MappingNode):
+        raise ConstructorError(
+            problem=f'expected a mapping node, but found {type(node)}',
+            problem_mark=node.start_mark,
+        )
+    return MappingSubset(loader.construct_mapping(node))
+
+
+@ExpectationYamlLoader.add_construct('!ObjectAttributes')
+def _(loader: ExpectationYamlLoader, node: yaml.Node) -> ObjectAttributes:
+    if not isinstance(node, yaml.MappingNode):
+        raise ConstructorError(
+            problem=f'expected a mapping node, but found {type(node)}',
+            problem_mark=node.start_mark,
+        )
+    node_data = loader.construct_mapping(node)
+    if any(not isinstance(key, str) for key in node_data):
+        raise ConstructorError(
+            problem='all keys in ObjectAttributes must be strings',
+            problem_mark=node.start_mark,
+        )
+    return ObjectAttributes(cast(dict[str, Any], node_data))
+
+
+@ExpectationYamlLoader.add_construct('!Stringified')
+def _(loader: ExpectationYamlLoader, node: yaml.Node) -> Stringified:
+    if not isinstance(node, yaml.ScalarNode):
+        raise ConstructorError(
+            problem=f'expected a scalar node, but found {type(node)}',
+            problem_mark=node.start_mark,
+        )
+    # I was not able to produce yaml that would return something else than a string
+    node_data = cast(str, loader.construct_scalar(node))
+    return Stringified(node_data)
+
+
+@ExpectationYamlLoader.add_construct('!Unordered')
+def _(loader: ExpectationYamlLoader, node: yaml.Node) -> Unordered:
+    if not isinstance(node, yaml.SequenceNode):
+        raise ConstructorError(
+            problem=f'expected a sequence node, but found {type(node)}',
+            problem_mark=node.start_mark,
+        )
+    return Unordered(loader.construct_sequence(node))
+
+
+_WITH_TYPE_KEYS = {'expectation', 'expected_type_name', 'expected_type_module'}
+
+
+@ExpectationYamlLoader.add_construct('!WithType')
+def _(loader: ExpectationYamlLoader, node: yaml.Node) -> WithType:
+    if not isinstance(node, yaml.MappingNode):
+        raise ConstructorError(
+            problem=f'expected a mapping node, but found {type(node)}',
+            problem_mark=node.start_mark,
+        )
+    node_data = loader.construct_mapping(node)
+    if node_data.keys() != _WITH_TYPE_KEYS:
+        raise ConstructorError(
+            problem=f'WithType keys must be {_WITH_TYPE_KEYS}',
+            problem_mark=node.start_mark,
+        )
+    if not isinstance(expected_type_name := node_data['expected_type_name'], str):
+        raise ConstructorError(
+            problem='value of WithType "expected_type_name" must be a string',
+            problem_mark=node.start_mark,
+        )
+    if not isinstance(expected_type_module := node_data['expected_type_module'], str | None):
+        raise ConstructorError(
+            problem='value of WithType "expected_type_module" must be a string or None',
+            problem_mark=node.start_mark,
+        )
+    return WithType(node_data['expectation'], expected_type_name, expected_type_module)

panda_pytest_assertions/assert_object/_converters/expectation_to_yaml.py

@@ -0,0 +1,78 @@
+from collections.abc import Callable
+from enum import Enum
+from typing import Any, TypeVar
+
+import yaml
+
+from panda_pytest_assertions.assert_object._expectation_modificators import (
+    MappingSubset,
+    ObjectAttributes,
+    Stringified,
+    Unordered,
+    with_type,
+    WithType,
+)
+
+
+def expectation_to_yaml(expectation: Any) -> str:  # noqa: ANN401
+    """
+    Serialize expectation to YAML format.
+
+    :param expectation: expectation to be dumped to YAML
+    :return: YAML string representing expectation
+    """
+    return yaml.dump(expectation, Dumper=ExpectationYamlDumper, width=10000)
+
+
+_T = TypeVar('_T')
+
+_Representer = Callable[['ExpectationYamlDumper', _T], yaml.Node]
+
+
+class ExpectationYamlDumper(yaml.SafeDumper):
+    @classmethod
+    def add_repr(
+        cls,
+        data_type: type[_T],
+        *,
+        is_multi: bool = False,
+    ) -> Callable[[_Representer[_T]], _Representer[_T]]:
+        def _wrapper(representer: _Representer[_T]) -> _Representer[_T]:
+            if is_multi:
+                ExpectationYamlDumper.add_multi_representer(data_type, representer)
+            else:
+                ExpectationYamlDumper.add_representer(data_type, representer)
+            return representer
+
+        return _wrapper
+
+
+@ExpectationYamlDumper.add_repr(MappingSubset)
+def _(dumper: ExpectationYamlDumper, data: MappingSubset) -> yaml.MappingNode:
+    return dumper.represent_mapping('!MappingSubset', data.items_expectations)
+
+
+@ExpectationYamlDumper.add_repr(ObjectAttributes)
+def _(dumper: ExpectationYamlDumper, data: ObjectAttributes) -> yaml.MappingNode:
+    return dumper.represent_mapping('!ObjectAttributes', data.attributes_expectations)
+
+
+@ExpectationYamlDumper.add_repr(Stringified)
+def _(dumper: ExpectationYamlDumper, data: Stringified) -> yaml.ScalarNode:
+    return dumper.represent_scalar('!Stringified', data.stringified_value)
+
+
+@ExpectationYamlDumper.add_repr(Unordered)
+def _(dumper: ExpectationYamlDumper, data: Unordered) -> yaml.SequenceNode:
+    return dumper.represent_sequence('!Unordered', data.elements_expectations)
+
+
+@ExpectationYamlDumper.add_repr(WithType)
+def _with_type_representer(dumper: ExpectationYamlDumper, data: WithType) -> yaml.MappingNode:
+    return dumper.represent_mapping('!WithType', data.__dict__)
+
+
+@ExpectationYamlDumper.add_repr(Enum, is_multi=True)
+def _(dumper: ExpectationYamlDumper, data: Enum) -> yaml.Node:
+    expectation = with_type(type(data))(Stringified(str(data)))
+    return _with_type_representer(dumper, expectation)

panda_pytest_assertions/assert_object/_expectation_modificators/__init__.py

@@ -0,0 +1,15 @@
+from .mapping_subset import MappingSubset
+from .object_attibutes import ObjectAttributes
+from .stringified import Stringified
+from .unordered import Unordered
+from .with_type import with_type, WithType
+
+
+__all__ = [
+    'MappingSubset',
+    'ObjectAttributes',
+    'Stringified',
+    'Unordered',
+    'WithType',
+    'with_type',
+]

panda_pytest_assertions/assert_object/_expectation_modificators/mapping_subset.py

@@ -0,0 +1,15 @@
+from collections.abc import Mapping
+from typing import Any
+
+
+class MappingSubset:
+    """
+    Wrapper for the expectation that describes a subset of a mapping object.
+    """
+
+    def __init__(self, items_expectations: Mapping[Any, Any], /) -> None:
+        #: mapping of items expectations
+        self.items_expectations = items_expectations
+
+    def __repr__(self) -> str:
+        return f'MappingSubset({self.items_expectations!r})'

panda_pytest_assertions/assert_object/_expectation_modificators/object_attibutes.py

@@ -0,0 +1,15 @@
+from collections.abc import Mapping
+from typing import Any
+
+
+class ObjectAttributes:
+    """
+    Wrapper for the expectation that describes a object attributes.
+    """
+
+    def __init__(self, attributes_expectations: Mapping[str, Any], /) -> None:
+        #: mapping of attributes expectations
+        self.attributes_expectations = attributes_expectations
+
+    def __repr__(self) -> str:
+        return f'ObjectAttributes({self.attributes_expectations!r})'

panda_pytest_assertions/assert_object/_expectation_modificators/stringified.py

@@ -0,0 +1,11 @@
+class Stringified:
+    """
+    Wrapper for the expectation that describes stringified object.
+    """
+
+    def __init__(self, stringified_value: str, /) -> None:
+        #: stringified value expectation
+        self.stringified_value = stringified_value
+
+    def __repr__(self) -> str:
+        return f'Stringified({self.stringified_value!r})'

panda_pytest_assertions/assert_object/_expectation_modificators/unordered.py

@@ -0,0 +1,18 @@
+from collections.abc import Iterator
+from typing import Any
+
+
+class Unordered:
+    """
+    Wrapper for the expectation that describes unordered list.
+    """
+
+    def __init__(self, elements_expectations: list[Any], /) -> None:
+        #: list of elements expectations
+        self.elements_expectations = elements_expectations
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(self.elements_expectations)
+
+    def __repr__(self) -> str:
+        return f'Unordered({self.elements_expectations!r})'