aboutsummaryrefslogtreecommitdiffstats
path: root/contrib/python/PyHamcrest/py2/hamcrest/core/matcher.py
blob: 81ee27c6d9d9cd884b1d0ff3951bed61f69e4548 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
from __future__ import absolute_import
from .selfdescribing import SelfDescribing

__author__ = "Jon Reid"
__copyright__ = "Copyright 2011 hamcrest.org"
__license__ = "BSD, see License.txt"


class Matcher(SelfDescribing):
    """A matcher over acceptable values.

    A matcher is able to describe itself to give feedback when it fails.

    Matcher implementations should *not* directly implement this protocol.
    Instead, *extend* the :py:class:`~hamcrest.core.base_matcher.BaseMatcher`
    class, which will ensure that the
    :py:class:`~hamcrest.core.matcher.Matcher` API can grow to support new
    features and remain compatible with all
    :py:class:`~hamcrest.core.matcher.Matcher` implementations.

    """

    def matches(self, item, mismatch_description=None):
        """Evaluates the matcher for argument item.

        If a mismatch is detected and argument ``mismatch_description`` is
        provided, it will generate a description of why the matcher has not
        accepted the item.

        :param item: The object against which the matcher is evaluated.
        :returns: ``True`` if ``item`` matches, otherwise ``False``.

        """
        raise NotImplementedError('matches')

    def describe_mismatch(self, item, mismatch_description):
        """Generates a description of why the matcher has not accepted the
        item.

        The description will be part of a larger description of why a matching
        failed, so it should be concise.

        This method assumes that ``matches(item)`` is ``False``, but will not
        check this.

        :param item: The item that the
            :py:class:`~hamcrest.core.matcher.Matcher` has rejected.
        :param mismatch_description: The description to be built or appended
            to.

        """
        raise NotImplementedError('describe_mismatch')