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

panda_pytest_assertions/assert_object/_protocols.py

@@ -0,0 +1,93 @@
+from typing import Any, Protocol
+
+
+class AsserterProtocol(Protocol):
+    """
+    Asserter checking that the given expectation is fulfilled by the object.
+    """
+
+    expectation: Any
+    asserter_factory: 'type[AsserterFactoryProtocol]'
+
+    def __init__(
+        self,
+        asserter_factory: 'type[AsserterFactoryProtocol]',
+        expectation: Any,  # noqa: ANN401
+    ) -> None: ...
+
+    @classmethod
+    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 assert_object(self, object_: Any) -> None:  # noqa: ANN401
+        """
+        Assert if the expectation is fulfilled by an object.
+
+        :param object_: an object to be tested
+        """
+
+
+class AsserterFactoryProtocol(Protocol):
+    """
+    Factory for registered asserters.
+    """
+
+    @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
+        """
+
+
+class GeneratorProtocol(Protocol):
+    """
+    Generates expectation from given object according to a definition.
+    """
+
+    definition: Any
+    generator_factory: 'type[GeneratorFactoryProtocol]'
+
+    def __init__(
+        self,
+        generator_factory: 'type[GeneratorFactoryProtocol]',
+        definition: Any,  # noqa: ANN401
+    ) -> None: ...
+
+    @classmethod
+    def matches(cls, definition: Any) -> bool:  # noqa: ANN401
+        """
+        Decide whether provided definition can be handled by this generator.
+
+        :param definition: definition to be tested
+        """
+
+    def generate_expectation(self, object_: Any) -> Any:  # noqa: ANN401
+        """
+        Generate expectation from given object.
+
+        :param object_: an object to generate expectation from
+        """
+
+
+class GeneratorFactoryProtocol(Protocol):
+    """
+    Factory for registered generators.
+    """
+
+    @classmethod
+    def create(cls, definition: Any) -> GeneratorProtocol:  # noqa: ANN401
+        """
+        Create expectation generator for given definition.
+
+        The method goes through all registered generator types and uses the first one that matches.
+
+        :param definition: expectation definition
+        """

panda_pytest_assertions/assert_object/generators/__init__.py

@@ -0,0 +1,41 @@
+from ._expectation_definitions import (
+    EqualityDef,
+    MappingDef,
+    MappingSubsetDef,
+    ObjectAttributesDef,
+    OfTypeDef,
+    StringifiedDef,
+    uniform_ordered_def,
+    UniformMappingDef,
+    UniformMappingSubsetDef,
+    UniformOrderedDef,
+    UniformUnorderedDef,
+    UnionDef,
+    with_type_def,
+    WithTypeDef,
+)
+from ._generate_expectation import generate_expectation
+from ._generator_factories import BuiltInGeneratorFactory, GeneratorFactory
+from ._generators import Generator
+
+
+__all__ = [
+    'EqualityDef',
+    'MappingDef',
+    'MappingSubsetDef',
+    'ObjectAttributesDef',
+    'OfTypeDef',
+    'StringifiedDef',
+    'uniform_ordered_def',
+    'UniformMappingDef',
+    'UniformMappingSubsetDef',
+    'UniformOrderedDef',
+    'UniformUnorderedDef',
+    'UnionDef',
+    'with_type_def',
+    'WithTypeDef',
+    'generate_expectation',
+    'BuiltInGeneratorFactory',
+    'GeneratorFactory',
+    'Generator',
+]

panda_pytest_assertions/assert_object/generators/_expectation_definitions/__init__.py

@@ -0,0 +1,30 @@
+from .equality import EqualityDef
+from .mapping import MappingDef
+from .mapping_subset import MappingSubsetDef
+from .object_attributes import ObjectAttributesDef
+from .of_type import OfTypeDef
+from .stringified import StringifiedDef
+from .uniform_mapping import UniformMappingDef
+from .uniform_mapping_subset import UniformMappingSubsetDef
+from .uniform_ordered import uniform_ordered_def, UniformOrderedDef
+from .uniform_unordered import UniformUnorderedDef
+from .union import UnionDef
+from .with_type import with_type_def, WithTypeDef
+
+
+__all__ = [
+    'EqualityDef',
+    'MappingDef',
+    'MappingSubsetDef',
+    'ObjectAttributesDef',
+    'OfTypeDef',
+    'StringifiedDef',
+    'UniformMappingDef',
+    'UniformMappingSubsetDef',
+    'uniform_ordered_def',
+    'UniformOrderedDef',
+    'UniformUnorderedDef',
+    'UnionDef',
+    'with_type_def',
+    'WithTypeDef',
+]

panda_pytest_assertions/assert_object/generators/_expectation_definitions/equality.py

@@ -0,0 +1,6 @@
+class EqualityDef:
+    """
+    Defines equality expectation where expectation is just the object itself.
+
+    Mostly useful for primitive types.
+    """

panda_pytest_assertions/assert_object/generators/_expectation_definitions/mapping.py

@@ -0,0 +1,14 @@
+from collections.abc import Mapping
+from typing import Any
+
+
+class MappingDef:
+    """
+    Defines mapping expectation where all keys share common definition and each have definition for its value.
+    """
+
+    def __init__(self, keys_definition: Any, items_definitions: Mapping[str, Any], /) -> None:  # noqa: ANN401
+        #: definition for mapping keys
+        self.keys_definition = keys_definition
+        #: mapping of items definitions
+        self.items_definitions = items_definitions

panda_pytest_assertions/assert_object/generators/_expectation_definitions/mapping_subset.py

@@ -0,0 +1,14 @@
+from collections.abc import Mapping
+from typing import Any
+
+
+class MappingSubsetDef:
+    """
+    Defines mapping subset expectation where keys share definition and each have definition for its value.
+    """
+
+    def __init__(self, keys_definition: Any, items_definitions: Mapping[Any, Any], /) -> None:  # noqa: ANN401
+        #: definition for mapping keys
+        self.keys_definition = keys_definition
+        #: mapping of items definitions
+        self.items_definitions = items_definitions

panda_pytest_assertions/assert_object/generators/_expectation_definitions/object_attributes.py

@@ -0,0 +1,12 @@
+from collections.abc import Mapping
+from typing import Any
+
+
+class ObjectAttributesDef:
+    """
+    Defines expectation for object attributes.
+    """
+
+    def __init__(self, attributes_definitions: Mapping[str, Any], /) -> None:
+        #: mapping of attributes definitions
+        self.attributes_definitions = attributes_definitions

panda_pytest_assertions/assert_object/generators/_expectation_definitions/of_type.py

@@ -0,0 +1,13 @@
+from typing import Any
+
+
+class OfTypeDef:
+    """
+    Defines expectation that will only be generated if object is of a specific type.
+    """
+
+    def __init__(self, expected_type: type[Any] | None, object_definition: Any, /) -> None:  # noqa: ANN401
+        #: type that the object needs to match for the expectation to be generated
+        self.expected_type = expected_type
+        #: definition for object itself
+        self.object_definition = object_definition

panda_pytest_assertions/assert_object/generators/_expectation_definitions/stringified.py

@@ -0,0 +1,4 @@
+class StringifiedDef:
+    """
+    Defines stringified expectation.
+    """

panda_pytest_assertions/assert_object/generators/_expectation_definitions/uniform_mapping.py

@@ -0,0 +1,13 @@
+from typing import Any
+
+
+class UniformMappingDef:
+    """
+    Defines mapping expectation where all keys and values share common definitions.
+    """
+
+    def __init__(self, keys_definition: Any, values_definition: Any, /) -> None:  # noqa: ANN401
+        #: definition for mapping keys
+        self.keys_definition = keys_definition
+        #: definition for mapping values
+        self.values_definition = values_definition

panda_pytest_assertions/assert_object/generators/_expectation_definitions/uniform_mapping_subset.py

@@ -0,0 +1,13 @@
+from typing import Any
+
+
+class UniformMappingSubsetDef:
+    """
+    Defines mapping subset expectation where all keys and values share common definitions.
+    """
+
+    def __init__(self, keys_definition: Any, values_definition: Any, /) -> None:  # noqa: ANN401
+        #: definition for mapping keys
+        self.keys_definition = keys_definition
+        #: definition for mapping values
+        self.values_definition = values_definition

panda_pytest_assertions/assert_object/generators/_expectation_definitions/uniform_ordered.py

@@ -0,0 +1,39 @@
+from collections.abc import Callable
+from typing import Any
+
+
+class UniformOrderedDef:
+    """
+    Defines expectation for ordered collection using the same definition for each element.
+    """
+
+    def __init__(
+        self,
+        elements_definition: Any,  # noqa: ANN401
+        /,
+        *,
+        expectation_type: type[list[Any]] | type[tuple[Any, ...]] = list,
+    ) -> None:
+        #: definition for elements
+        self.elements_definition = elements_definition
+        #: type of expectation to be generated
+        self.expectation_type = expectation_type
+
+
+def uniform_ordered_def(
+    *,
+    expectation_type: type[list[Any]] | type[tuple[Any, ...]] = list,
+) -> Callable[[Any], UniformOrderedDef]:
+    """
+    Return the function that will accept elements definition and create expectation for ordered collection.
+
+    Returned function accepts any kind of value that will be treated as elements definition for collection.
+
+    :param expectation_type: defines which expectation type will be used
+    :return: function creating definition
+    """
+
+    def _creator(elements_definition: Any, /) -> UniformOrderedDef:  # noqa: ANN401
+        return UniformOrderedDef(elements_definition, expectation_type=expectation_type)
+
+    return _creator

panda_pytest_assertions/assert_object/generators/_expectation_definitions/uniform_unordered.py

@@ -0,0 +1,11 @@
+from typing import Any
+
+
+class UniformUnorderedDef:
+    """
+    Defines expectation for unordered collection.
+    """
+
+    def __init__(self, elements_definition: Any, /) -> None:  # noqa: ANN401
+        #: definition for elements
+        self.elements_definition = elements_definition

panda_pytest_assertions/assert_object/generators/_expectation_definitions/union.py

@@ -0,0 +1,13 @@
+from typing import Any
+
+
+class UnionDef:
+    """
+    Definition that accepts multiple definitions in case a place in object can have multiple types of values.
+
+    The first definition that matches a value during expectation generation will be used.
+    """
+
+    def __init__(self, *definitions: Any) -> None:  # noqa: ANN401
+        #: allowed union definitions
+        self.definitions = definitions

panda_pytest_assertions/assert_object/generators/_expectation_definitions/with_type.py

@@ -0,0 +1,30 @@
+from collections.abc import Callable
+from typing import Any
+
+
+class WithTypeDef:
+    """
+    Defines expectation validating object type.
+    """
+
+    def __init__(self, object_definition: Any, /, *, include_module: bool = True) -> None:  # noqa: ANN401
+        #: definition for object itself
+        self.object_definition = object_definition
+        #: indicator whether module shall be included in WithType expectation
+        self.include_module = include_module
+
+
+def with_type_def(*, include_module: bool = True) -> Callable[[Any], WithTypeDef]:
+    """
+    Return the function that will accept an object definition and create expectation definition with type.
+
+    Returned function accepts any kind of value that will be treated as expectation definition for object.
+
+    :param include_module: whether the module of the type shall be included in the expectation
+    :return: function creating definition
+    """
+
+    def _creator(object_definition: Any, /) -> WithTypeDef:  # noqa: ANN401
+        return WithTypeDef(object_definition, include_module=include_module)
+
+    return _creator

panda_pytest_assertions/assert_object/generators/_generate_expectation.py

@@ -0,0 +1,23 @@
+from typing import Any
+
+from panda_pytest_assertions.assert_object._protocols import GeneratorFactoryProtocol
+
+from ._generator_factories import BuiltInGeneratorFactory
+
+
+def generate_expectation(
+    object_: Any,  # noqa: ANN401
+    definition: Any,  # noqa: ANN401
+    *,
+    generator_factory: type[GeneratorFactoryProtocol] = BuiltInGeneratorFactory,
+) -> Any:  # noqa: ANN401
+    """
+    Generate expectation for given object according to definition.
+
+    :param object_: object to generate expectation from
+    :param definition: expectation definition
+    :param generator_factory: factory used to create generators
+    :return: generated expectation
+    """
+    generator = generator_factory.create(definition)
+    return generator.generate_expectation(object_)

panda_pytest_assertions/assert_object/generators/_generator_factories/__init__.py

@@ -0,0 +1,8 @@
+from .built_in_generator_factory import BuiltInGeneratorFactory
+from .generator_factory import GeneratorFactory
+
+
+__all__ = [
+    'BuiltInGeneratorFactory',
+    'GeneratorFactory',
+]

panda_pytest_assertions/assert_object/generators/_generator_factories/built_in_generator_factory.py

@@ -0,0 +1,39 @@
+from .._generators import (  # noqa: TID252
+    EqualityGenerator,
+    EqualityKeyMappingGenerator,
+    MappingGenerator,
+    MappingSubsetGenerator,
+    ObjectAttributesGenerator,
+    OfTypeGenerator,
+    OrderedGenerator,
+    StringifiedGenerator,
+    UniformMappingGenerator,
+    UniformMappingSubsetGenerator,
+    UniformOrderedGenerator,
+    UnionGenerator,
+    UnorderedGenerator,
+    WithTypeGenerator,
+)
+from .generator_factory import GeneratorFactory
+
+
+class BuiltInGeneratorFactory(GeneratorFactory):
+    """
+    Factory that has all built-in generators registered.
+    """
+
+
+BuiltInGeneratorFactory.register_generator(EqualityGenerator)
+BuiltInGeneratorFactory.register_generator(EqualityKeyMappingGenerator)
+BuiltInGeneratorFactory.register_generator(MappingGenerator)
+BuiltInGeneratorFactory.register_generator(MappingSubsetGenerator)
+BuiltInGeneratorFactory.register_generator(ObjectAttributesGenerator)
+BuiltInGeneratorFactory.register_generator(OfTypeGenerator)
+BuiltInGeneratorFactory.register_generator(OrderedGenerator)
+BuiltInGeneratorFactory.register_generator(StringifiedGenerator)
+BuiltInGeneratorFactory.register_generator(UniformOrderedGenerator)
+BuiltInGeneratorFactory.register_generator(UniformMappingGenerator)
+BuiltInGeneratorFactory.register_generator(UniformMappingSubsetGenerator)
+BuiltInGeneratorFactory.register_generator(UnionGenerator)
+BuiltInGeneratorFactory.register_generator(UnorderedGenerator)
+BuiltInGeneratorFactory.register_generator(WithTypeGenerator)

panda_pytest_assertions/assert_object/generators/_generator_factories/generator_factory.py

@@ -0,0 +1,66 @@
+from collections import deque
+from typing import Any, ClassVar
+
+from panda_pytest_assertions.assert_object._protocols import GeneratorProtocol
+
+
+class GeneratorFactory:
+    """
+    Factory for registered generators.
+    """
+
+    #: list of registered gnerator classes
+    _GENERATOR_TYPES: ClassVar[deque[type[GeneratorProtocol]]] = deque()
+
+    @classmethod
+    def create(cls, definition: Any) -> Any:  # noqa: ANN401
+        """
+        Create expectation generator for given definition.
+
+        The method goes through all registered generator types and uses the first one that matches.
+
+        :param definition: expectation definition
+        :return: generated expectation
+        """
+        for generator_type in cls._GENERATOR_TYPES:
+            if generator_type.matches(definition):
+                return generator_type(cls, definition)
+        msg = (
+            f'None of the registered generators matches definition "{definition}" '
+            f'of type "{type(definition)}".'
+        )
+        raise ValueError(msg)
+
+    @classmethod
+    def register_generator(
+        cls,
+        generator: type[GeneratorProtocol],
+        *,
+        after: type[GeneratorProtocol] | None = None,
+        before: type[GeneratorProtocol] | None = None,
+    ) -> None:
+        """
+        Register the provided generator to be used.
+
+        The generator 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 generator for expectations.
+
+        :param generator: generator to be registered
+        :param after: registered generator must be matched after this one
+        :param before: registered generator must be matched before this one
+        """
+        if '_GENERATOR_TYPES' not in cls.__dict__:
+            cls._GENERATOR_TYPES = cls._GENERATOR_TYPES.copy()
+
+        after_position = cls._GENERATOR_TYPES.index(after) if after is not None else -1
+        before_position = (
+            cls._GENERATOR_TYPES.index(before) if before is not None else len(cls._GENERATOR_TYPES) + 1
+        )
+        if after_position >= before_position:
+            msg = (
+                f'Cannot register generator between "{after}" and "{before}" as their '
+                f'respective positions are: "{after_position}" and "{before_position}"'
+            )
+            raise ValueError(msg)
+        cls._GENERATOR_TYPES.insert(after_position + 1, generator)

panda_pytest_assertions/assert_object/generators/_generators/__init__.py

@@ -0,0 +1,34 @@
+from .equality_generator import EqualityGenerator
+from .equality_key_mapping_generator import EqualityKeyMappingGenerator
+from .generator import Generator
+from .mapping_generator import MappingGenerator
+from .mapping_subset_generator import MappingSubsetGenerator
+from .object_attributes_generator import ObjectAttributesGenerator
+from .of_type_generator import OfTypeGenerator
+from .ordered_generator import OrderedGenerator
+from .stringified_generator import StringifiedGenerator
+from .uniform_mapping_generator import UniformMappingGenerator
+from .uniform_mapping_subset_generator import UniformMappingSubsetGenerator
+from .uniform_ordered_generator import UniformOrderedGenerator
+from .union_generator import UnionGenerator
+from .unordered_generator import UnorderedGenerator
+from .with_type_generator import WithTypeGenerator
+
+
+__all__ = [
+    'Generator',
+    'EqualityGenerator',
+    'EqualityKeyMappingGenerator',
+    'MappingGenerator',
+    'MappingSubsetGenerator',
+    'ObjectAttributesGenerator',
+    'OfTypeGenerator',
+    'OrderedGenerator',
+    'StringifiedGenerator',
+    'UniformOrderedGenerator',
+    'UniformMappingGenerator',
+    'UniformMappingSubsetGenerator',
+    'UnionGenerator',
+    'UnorderedGenerator',
+    'WithTypeGenerator',
+]

panda_pytest_assertions/assert_object/generators/_generators/equality_generator.py

@@ -0,0 +1,35 @@
+from typing import Any
+
+from .._expectation_definitions import EqualityDef  # noqa: TID252
+from .generator import Generator
+
+
+class EqualityGenerator(Generator):
+    """
+    Generated expectation is just the specific object.
+    """
+
+    @classmethod
+    def matches(cls, definition: Any) -> bool:  # noqa: ANN401
+        """
+        Decide whether provided definiton can be handled by this generator.
+
+        This generator can handle EqualityDef definition.
+
+        :param definition: definition to be tested
+        :return: whether definition can be handled by this generator
+        """
+        return isinstance(definition, EqualityDef) or (
+            isinstance(definition, type) and issubclass(definition, EqualityDef)
+        )
+
+    def generate_expectation(self, object_: Any) -> Any:  # noqa: ANN401
+        """
+        Generate expectation from given object.
+
+        Return object itself.
+
+        :param object_: an object to generate expectation from
+        :return: generated expectation
+        """
+        return object_

panda_pytest_assertions/assert_object/generators/_generators/equality_key_mapping_generator.py

@@ -0,0 +1,54 @@
+from collections.abc import Mapping
+from typing import Any
+
+from panda_pytest_assertions.assert_object import GeneratorFactoryProtocol
+
+from .exceptions import ObjectNotMatchingDefinitionError
+from .generator import Generator
+
+
+class EqualityKeyMappingGenerator(Generator):
+    """
+    Generates Mapping expectation using keys' values as keys' expectations.
+    """
+
+    @classmethod
+    def matches(cls, definition: Any) -> bool:  # noqa: ANN401
+        """
+        Decide whether provided definiton can be handled by this generator.
+
+        This generator can handle any Mapping as definition.
+
+        :param definition: definition to be tested
+        :return: whether definition can be handled by this generator
+        """
+        return isinstance(definition, Mapping)
+
+    def __init__(
+        self,
+        generator_factory: type[GeneratorFactoryProtocol],
+        definition: Mapping[Any, Any],
+    ) -> None:
+        super().__init__(generator_factory, definition)
+        self.items_generators = {key: generator_factory.create(value) for key, value in definition.items()}
+
+    def generate_expectation(self, object_: Any) -> Mapping[Any, Any]:  # noqa: ANN401
+        """
+        Generate expectation from given object.
+
+        :param object_: an object to generate expectation from
+        :return: generated expectation
+        """
+        if not isinstance(object_, Mapping):
+            msg = f'Expected mapping, got {type(object_)}'
+            raise ObjectNotMatchingDefinitionError(msg)
+        if object_.keys() != self.items_generators.keys():
+            msg = (
+                f'Object has invalid keys. '
+                f'Expected: {set(self.items_generators.keys())}, got {set(object_.keys())}.'
+            )
+            raise ObjectNotMatchingDefinitionError(msg)
+        return {
+            key: value_generator.generate_expectation(object_[key])
+            for key, value_generator in self.items_generators.items()
+        }

panda_pytest_assertions/assert_object/generators/_generators/exceptions.py

@@ -0,0 +1 @@
+class ObjectNotMatchingDefinitionError(Exception): ...

panda_pytest_assertions/assert_object/generators/_generators/generator.py

@@ -0,0 +1,35 @@
+import abc
+from typing import Any
+
+from panda_pytest_assertions.assert_object._protocols import GeneratorFactoryProtocol
+
+
+class Generator(abc.ABC):
+    """
+    Generates expectation for given object according to a provided definition.
+    """
+
+    @classmethod
+    @abc.abstractmethod
+    def matches(cls, definition: Any) -> bool:  # noqa: ANN401
+        """
+        Decide whether provided definition can be handled by this generator.
+
+        :param definition: definition to be tested
+        """
+
+    def __init__(
+        self,
+        generator_factory: type[GeneratorFactoryProtocol],
+        definition: Any,  # noqa: ANN401
+    ) -> None:
+        self.generator_factory = generator_factory
+        self.definition = definition
+
+    @abc.abstractmethod
+    def generate_expectation(self, object_: Any) -> Any:  # noqa: ANN401
+        """
+        Generate expectation from given object.
+
+        :param object_: an object to generate expectation from
+        """