Core API

• Helpers
  • hasmethod
  • wrap_matcher

BaseDescription

class hamcrest.core.base_description.BaseDescription

Bases: hamcrest.core.description.Description

Base class for all Description implementations.

append(string)

Append the string to the description.

Parameters

string (str) –

Return type

None

append_description_of(value)

Appends description of given value to this description.

If the value implements describe_to, then it will be used.

Returns

self, for chaining

Parameters

value (Any) –

Return type

hamcrest.core.description.Description

append_list(start, separator, end, list)

Appends a list of objects to the description.

Parameters

• start (str) – String that will begin the list description.

• separator (str) – String that will separate each object in the description.

• end (str) – String that will end the list description.

• list (Iterable[Any]) – List of objects to be described.

Returns

self, for chaining

Return type

hamcrest.core.description.Description

append_text(text)

Appends some plain text to the description.

Returns

self, for chaining

Parameters

text (str) –

Return type

hamcrest.core.description.Description

BaseMatcher

class hamcrest.core.base_matcher.BaseMatcher(*args, **kwds)

Bases: hamcrest.core.matcher.Matcher[hamcrest.core.base_matcher.T]

Base class for all Matcher implementations.

Most implementations can just implement _matches, leaving the handling of any mismatch description to the matches method. But if it makes more sense to generate the mismatch description during the matching, override matches instead.

_matches(item)

Parameters

item (T) –

Return type

bool

describe_match(item, match_description)

Generates a description of why the matcher has accepted the item.

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

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

Parameters

• item (T) – The item that the Matcher has accepted.

• match_description (hamcrest.core.description.Description) – The description to be built or appended to.

Return type

None

describe_mismatch(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.

Parameters

• item (T) – The item that the Matcher has rejected.

• mismatch_description (hamcrest.core.description.Description) – The description to be built or appended to.

Return type

None

matches(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.

Parameters

• item (T) – The object against which the matcher is evaluated.

• mismatch_description (Optional[hamcrest.core.description.Description]) –

Returns

True if item matches, otherwise False.

Return type

bool

Description

class hamcrest.core.description.Description

Bases: object

A description of a Matcher.

A Matcher will describe itself to a description which can later be used for reporting.

append_description_of(value)

Appends description of given value to this description.

If the value implements describe_to, then it will be used.

Returns

self, for chaining

Parameters

value (Any) –

Return type

hamcrest.core.description.Description

append_list(start, separator, end, list)

Appends a list of objects to the description.

Parameters

• start (str) – String that will begin the list description.

• separator (str) – String that will separate each object in the description.

• end (str) – String that will end the list description.

• list (Iterable[Any]) – List of objects to be described.

Returns

self, for chaining

Return type

hamcrest.core.description.Description

append_text(text)

Appends some plain text to the description.

Returns

self, for chaining

Parameters

text (str) –

Return type

hamcrest.core.description.Description

Matcher

class hamcrest.core.matcher.Matcher(*args, **kwds)

Bases: Generic[hamcrest.core.matcher.T], hamcrest.core.selfdescribing.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 BaseMatcher class, which will ensure that the Matcher API can grow to support new features and remain compatible with all Matcher implementations.

describe_match(item, match_description)

Generates a description of why the matcher has accepted the item.

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

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

Parameters

• item (T) – The item that the Matcher has accepted.

• match_description (hamcrest.core.description.Description) – The description to be built or appended to.

Return type

None

describe_mismatch(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.

Parameters

• item (T) – The item that the Matcher has rejected.

• mismatch_description (hamcrest.core.description.Description) – The description to be built or appended to.

Return type

None

matches(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.

Parameters

• item (T) – The object against which the matcher is evaluated.

• mismatch_description (Optional[hamcrest.core.description.Description]) –

Returns

True if item matches, otherwise False.

Return type

bool

SelfDescribing

class hamcrest.core.selfdescribing.SelfDescribing

Bases: object

The ability of an object to describe itself.

describe_to(description)

Generates a description of the object.

The description may be part of a description of a larger object of which this is just a component, so it should be worded appropriately.

Parameters

description (hamcrest.core.description.Description) – The description to be built or appended to.

Return type

None

SelfDescribingValue

class hamcrest.core.selfdescribingvalue.SelfDescribingValue(value)

Bases: hamcrest.core.selfdescribing.SelfDescribing

Wrap any value in a SelfDescribingValue to satisfy the SelfDescribing interface.

Deprecated: No need for this class now that append_description_of handles any type of value.

describe_to(description)

Generates a description of the value.

Parameters

description (hamcrest.core.description.Description) –

Return type

None

StringDescription

class hamcrest.core.string_description.StringDescription

Bases: hamcrest.core.base_description.BaseDescription

A Description that is stored as a string.

append(string)

Append the string to the description.

Parameters

string (str) –

Return type

None

hamcrest.core.string_description.tostring(selfdescribing)

Returns the description of a SelfDescribing object as a string.

Parameters

selfdescribing (hamcrest.core.selfdescribing.SelfDescribing) – The object to be described.

Returns

The description of the object.

Return type

str