API Reference¶

Callables¶

class pychoir.WhenPassedTo(callable_: Callable[[Any], Any])¶

Matchers that check how a value behaves when passed to a callable.

Parameters:: callable – The callable to pass the value to.

Usage:

>>> from pychoir import WhenPassedTo
>>> "foo" == WhenPassedTo(int).raises(ValueError)
True
>>> "5" == WhenPassedTo(int).does_not_raise()
True
>>> "5" == WhenPassedTo(int).returns(5)
True

Comparisons¶

class pychoir.EqualTo(value: Any)¶

A somewhat redundant matcher checking for equality. Most Matchers can take values and/or Matchers and you should prefer bare values to wrapping them in EqualTo.

A notable exception is when used with & and | operators with a bare value on the left-most position

Parameters:: value – The value to compare against.

Usage:

>>> from pychoir import All, EqualTo, IsInstance
>>> [1, 1, 1] == All(EqualTo(1))  # Bad, do not do this
True
>>> [1, 1, 1] == All(1)  # Good, do this instead
True
>>> 1 == EqualTo(1) & IsInstance(int)  # Needed here, but see below
True
>>> 1 == IsInstance(int) & 1  # Bare value works here
True

class pychoir.GreaterThan(threshold: Any)¶

A Matcher checking that compared value is greater than the given value.

Parameters:: threshold – The value to compare against.

Usage:

>>> from pychoir import GreaterThan
>>> [2] == [GreaterThan(2)]
False
>>> [3] == [GreaterThan(2)]
True

class pychoir.GreaterThanOrEqualTo(threshold: Any)¶

A Matcher checking that compared value is greater than or equal to the given value.

Parameters:: threshold – The value to compare against.

Usage:

>>> from pychoir import GreaterThanOrEqualTo
>>> 2 == GreaterThanOrEqualTo(2)
True
>>> 1 == GreaterThanOrEqualTo(2)
False

class pychoir.LessThan(threshold: Any)¶

A Matcher checking that compared value is less than the given value.

Parameters:: threshold – The value to compare against.

Usage:

>>> from pychoir import LessThan
>>> 2 == LessThan(2)
False
>>> 1 == LessThan(2)
True

class pychoir.LessThanOrEqualTo(threshold: Any)¶

A Matcher checking that compared value is less than or equal to the given value.

Parameters:: threshold – The value to compare against.

Usage:

>>> from pychoir import LessThanOrEqualTo
>>> 2 == LessThanOrEqualTo(2)
True
>>> 3 == LessThanOrEqualTo(2)
False

class pychoir.NotEqualTo(value: Any)¶

A Matcher checking that compared value is not equal to the given value.

Parameters:: value – The value to compare against.

Usage:

>>> from pychoir import NotEqualTo
>>> 1 == NotEqualTo(2)
True
>>> 1 == NotEqualTo(1)
False

pychoir.EQ¶: alias of EqualTo

pychoir.GT¶: alias of GreaterThan

pychoir.GTE¶: alias of GreaterThanOrEqualTo

pychoir.LT¶: alias of LessThan

pychoir.LTE¶: alias of LessThanOrEqualTo

pychoir.NE¶: alias of NotEqualTo

Containers¶

class pychoir.All(*matchers: Matchable)¶

A Matcher checking that all values in a container match passed Matchables.

Parameters:: matchers – The value(s) and/or Matcher(s) to compare against.

Usage:

>>> from pychoir import All, IsInstance
>>> 'aaa' == All('a')
True
>>> [1, 2, 3] == All(IsInstance(int))
True

class pychoir.AreNot(*matchers: Matchable)¶

A Matcher checking that none of the values in a container match passed Matchables.

Parameters:: matchers – The value(s) and/or Matcher(s) to compare against.

Usage:

>>> from pychoir import AreNot, IsInstance
>>> 'abc' == AreNot('a', 'b')
False
>>> [1, 2, 3] == AreNot(IsInstance(str))
True

class pychoir.Contains(value: Any)¶

A Matcher checking that a container contains the passed value.

Parameters:: value – The value to find in the container.

Usage:

>>> from pychoir import Contains
>>> 'abc' == Contains('a')
True
>>> [1, 2, 3] == Contains(4)
False

class pychoir.ContainsAllOf(*values: Any)¶

A Matcher checking that a container contains at least the passed values.

Plural of Contains.

Parameters:: values – The value(s) to find in the container.

Usage:

>>> from pychoir import ContainsAllOf
>>> 'abc' == ContainsAllOf('a', 'b')
True
>>> [1, 2, 3] == ContainsAllOf(3, 4)
False

class pychoir.ContainsAnyOf(*values: Any)¶

A Matcher checking that a container contains at least one of the passed values.

Parameters:: values – The value(s) to find in the container.

Usage:

>>> from pychoir import ContainsAnyOf
>>> 'abc' == ContainsAnyOf('a', 'b')
True
>>> [1, 2, 3] == ContainsAnyOf(3, 4)
True

class pychoir.ContainsNoneOf(*values: Any)¶

A Matcher checking that a container contains none of the passed values.

Parameters:: values – The value(s) to find in the container.

Usage:

>>> from pychoir import ContainsNoneOf
>>> 'abc' == ContainsNoneOf('a', 'b')
False
>>> [1, 2, 3] == ContainsNoneOf(4)
True

class pychoir.DictContainsAllOf(value: Mapping[Any, Any])¶

A Matcher checking that a Mapping contains at least the passed Mapping. Usually this means that the passed dict is a subset of the one compared against. Keys expected to be absent can be set as NotPresent.

Parameters:: value – The Mapping to find in the Mapping compared against.

Usage:

>>> from pychoir import DictContainsAllOf, NotPresent
>>> {'a': 1, 'b': 2, 'd': 3} == DictContainsAllOf({'a': 1, 'c': NotPresent})
True
>>> {'a': 1, 'c': 2, 'd': 3} == DictContainsAllOf({'a': 1, 'c': NotPresent})
False

class pychoir.HasLength(matcher: Matchable)¶

A Matcher checking that the len() of the compared value matches the passed Matchable.

Parameters:: matcher – The value or Matcher to compare against.

Usage:

>>> from pychoir import GreaterThan, HasLength
>>> 'foo' == HasLength(3)
True
>>> 'foo' == HasLength(GreaterThan(2))
True

pychoir.Len¶: alias of HasLength

class pychoir.InAnyOrder(values: Iterable[Matchable])¶

A Matcher checking that an Iterable contains exactly the passed items, in any order.

The Iterable can be for example a list, tuple or set. Items can be Matchers and do not need to be hashable.

Parameters:: values – An Iterable containing the expected items, in any order.

Usage:

>>> from pychoir import InAnyOrder, IsEven, IsOdd
>>> [1, 2, 3, 3] == InAnyOrder([3, 2, 3, 1])
True
>>> [1, 2, 3] == InAnyOrder([3, 3, 2, 1])  # missing one 3
False
>>> [1, 2, 3, 3] == InAnyOrder([3, 2, 1])  # one 3 too many
False
>>> [1, 2, 3] == InAnyOrder((1, 2, 3))  # type of the Iterable does not matter
True
>>> [{'a': 1}, {'b': 2}] == InAnyOrder([{'b': IsEven()}, {'a': IsOdd()}])
True

class pychoir.IsEmpty(name: DefaultType | str | None = DefaultType.DEFAULT)¶

A Matcher checking that the len() of the compared value is 0.

Usage:

>>> from pychoir import All, IsEmpty, Not
>>> ('', [], {}, set(), tuple()) == All(IsEmpty())
True
>>> {'not': 'empty'} == Not(IsEmpty())
True

class pychoir.IsNotPresentOr(matcher: Matchable)¶

A Matcher checking that a value is either NotPresent or matches the passed matcher. Usually used for example with DictContainsAllOf.

Parameters:: matcher – The Mapping to find in the Mapping compared against.

Usage:

>>> from pychoir import DictContainsAllOf, IsNotPresentOr
>>> {'a': 2} == DictContainsAllOf({'a': IsNotPresentOr(2)})
True
>>> {} == DictContainsAllOf({'a': IsNotPresentOr(2)})
True

class pychoir.SetEquals(values: Iterable[Any])¶

A Matcher checking that an Iterable has the expected items, duplicates ignored. Faster than InAnyOrder but less pedantic about duplicates and requires hashable items.

The Iterable can be for example a list, tuple or set. Items must be hashable.

Parameters:: values – An Iterable containing the expected items, in any order.

Usage:

>>> from pychoir import SetEquals
>>> [1, 2, 3, 3] == SetEquals([3, 2, 1])
True
>>> [1, 2] == SetEquals([3, 2, 1])
False

containers.NotPresent = NotPresent¶

class pychoir.First(how_many: int = 1)¶

A Higher Order Matcher checking that the first how_many values match given matchers. The matcher is applied to the slice extracted from the passed Sequence.

Parameters:: how_many – The number of values to slice from the start of the sequence being compared.

Usage:

>>> from pychoir import First, All, GreaterThan
>>> (1, 2, 3) == First(2)((1, 2))
True
>>> (1, 2, 3) == First()(1)
True

__call__(matcher: Matchable) → Matcher¶: Call self as a function.

class pychoir.Last(how_many: int = 1)¶

A Higher Order Matcher checking that the last how_many values match given matchers. The matcher is applied to the slice extracted from the passed Sequence.

Parameters:: how_many – The number of values to slice from the end of the sequence being compared.

Usage:

>>> from pychoir import Last, All, LessThan
>>> (1, 2, 3) == Last(2)((2, 3))
True
>>> (1, 2, 3) == Last()(3)
True

__call__(matcher: Matchable) → Matcher¶: Call self as a function.

containers.Slice = <pychoir.containers._SliceFactory object>¶

class pychoir.containers._SliceFactory¶

A Higher Order Matcher checking that the sliced values match given matchers. The matcher is applied to the slice extracted from the passed Sequence.

Usage:

>>> from pychoir import Slice, And, IsInstance
>>> (1, 2, 3) == Slice[1:3]((2, 3))
True
>>> (1, 2, 3) == Slice[2](And(IsInstance(int), 3))
True

Core¶

class pychoir.Matchable(*args, **kwargs)¶

Type for a value that can be matched against using the == operator (has the __eq__ method). In the pychoir API, you can typically pass Matcher s and/or normal values where Matchable s are expected.

__eq__(other: MatchedType) → bool¶: Return self==value.

class pychoir.Matcher(name: DefaultType | str | None = DefaultType.DEFAULT)¶

The baseclass for all Matchers.

Parameters:

name –

Only for Matchers whose class name does not match the call that creates them. This applies, for example, to Matchers created by Transformer s.

For example _First(Matcher) (that is created by First(Transformer)) uses this to make its name 'First' instead of '_First' in its textual representation.

__and__(other: Matchable) → Matcher¶

Combines several matchers in a similar fashion as And

Usage:

>>> from pychoir import IsInstance
>>> 5 == IsInstance(int) & 5
True
>>> 5.0 == IsInstance(int) & 5
False

__or__(other: Matchable) → Matcher¶

Combines several matchers in a similar fashion as Or

Usage:

>>> from pychoir import StartsWith
>>> 'foo' == StartsWith('foo') | StartsWith('bar')
True
>>> 'bar' == StartsWith('foo') | StartsWith('bar')
True
>>> 'baz' == StartsWith('foo') | StartsWith('bar')
False

final __repr__() → str¶

Textual representation of the Matcher.

Contains info about failures and failed values

abstractmethod _description() → str¶

Returns a textual representation of the Matcher’s parameters.

For example in "EqualTo('foo')" the 'foo' is returned by _description().

To be implemented by all Matchers.

abstractmethod _matches(other: MatchedType) → bool¶

Returns True when Matcher matches, False otherwise.

Parameters:: other – The value being compared.

To be implemented by all Matchers.

final _reset_nested_failures() → None¶

For resetting failure state of child matchers in case of passing due to other Matchers.

For example in Or, it is enough that one child Matcher passes. The matchers tried up to that point should not report failure. After a Matcher reports a success, nested failures get reset automatically.

It is unlikely that you should ever call this from your tests or custom Matchers yourself.

final as_(type_: Type[T]) → T¶: Change the static type of the Matcher to make it pass type checking.

final nested_match(matcher: Matcher | Matchable, other: MatchedType, expect_mismatch: bool = False) → bool¶

For evaluating Matchables (or calling Matchers) from inside a Matcher.

Takes care of passing all necessary context and updating state when matching.

Parameters:

matcher – The value or Matcher to compare against.
other – The value being compared.
expect_mismatch – Set to True when expecting a mismatch (for example in Not).

pychoir.that(value: MatchedType) → MatcherWrapper¶

A helper for syntactically sugar coating matches instead of using ==.

Parameters:: value – The value to pass into the Matcher in MatcherWrapper.matches()
Returns:: A MatcherWrapper

Usage:

>>> from pychoir import that, GreaterThan
>>> assert that(3).matches(GreaterThan(2))
...
>>> assert that(1).matches(GreaterThan(2))
Traceback (most recent call last):
...
AssertionError

class pychoir.core.MatcherWrapper(value: MatchedType)¶

matches(matcher: Matcher) → MatchWrapper¶

Parameters:: matcher – The Matcher to compare that(value) with
Returns:: a truthy value in case that(value) passes the given matcher

Existential¶

class pychoir.Anything(name: DefaultType | str | None = DefaultType.DEFAULT)¶

A Matcher that matches anything.

Usage:

>>> from pychoir import Anything
>>> None == Anything()
True
>>> {'a': None} == {'a': Anything()}
True
>>> {'b': 1} == {'a': Anything()}
False

class pychoir.In(allowed_values: Iterable[Any])¶

A Matcher checking that the compared value is in the passed iterable.

Usage:

>>> from string import ascii_lowercase
>>> from pychoir import In
>>> 'a' == In(ascii_lowercase)
True
>>> 'A' == In(ascii_lowercase)
False

class pychoir.Is(value: Any)¶

A Matcher checking that the compared value is the passed value.

In Python is is used to check whether two objects are the same object in memory.

Parameters:: value – The value to compare against.

Usage:

>>> from pychoir import Is
>>> None == Is(None)
True
>>> [] == Is([])
False

class pychoir.IsFalsy(name: DefaultType | str | None = DefaultType.DEFAULT)¶

A Matcher checking that the compared value is falsy when used as a condition.

In other words, checks whether if value: ... else: ... would go to the else branch.

Usage:

>>> from pychoir import IsFalsy
>>> '' == IsFalsy()
True
>>> 5 == IsFalsy()
False

class pychoir.IsNoneOr(*matchers: Matchable)¶

A Matcher checking that the compared value is None or equal to the passed value.

This is useful for checking Optional values.

Parameters:: matchers – The value(s) and/or matcher(s) to compare against.

Usage:

>>> from pychoir import IsNoneOr
>>> None == IsNoneOr(5)
True
>>> 5 == IsNoneOr(5)
True
>>> 4 == IsNoneOr(5)
False

class pychoir.IsTruthy(name: DefaultType | str | None = DefaultType.DEFAULT)¶

A Matcher checking that the compared value is truthy when used as a condition.

In other words, checks whether if value: ... else: ... would go to the if branch.

Usage:

>>> from pychoir import IsTruthy
>>> '' == IsTruthy()
False
>>> 5 == IsTruthy()
True

pychoir.OneOf¶: alias of In

pychoir.Optionally¶: alias of IsNoneOr

Integration¶

class pychoir.Matches(*matchers: _MatcherLike[T])¶

pychoir.M¶: alias of Matches

pychoir.MatcherLike¶: alias of _MatcherLike[T]

Logical¶

pychoir.AllOf¶: alias of And

class pychoir.And(*matchers: Matchable)¶

A Matcher checking that the compared value matches all the passed Matchable s.

Consider using the & operator (Matcher.__and__()) instead: StartsWith('a') & HasLength(3).

Parameters:: matchers – The value(s) and/or matcher(s) to compare against.

Usage:

>>> from pychoir import And, IsInstance, HasLength, StartsWith
>>> 5 == And(IsInstance(int), 5)
True
>>> 'abc' == And(StartsWith('a'), HasLength(3))
True
>>> 4 == And(IsInstance(int), 5)
False

pychoir.AnyOf¶: alias of Or

pychoir.IsNoneOf¶: alias of Not

class pychoir.Not(*matchers: Matchable)¶

A Matcher checking that the compared value matches none of the passed Matchable s.

Parameters:: matchers – The value(s) and/or matcher(s) to compare against.

Usage:

>>> from pychoir import Not, IsInstance, StartsWith
>>> 5 == Not(IsInstance(str))
True
>>> 'abc' == Not(StartsWith('abc'), StartsWith('def'))
False
>>> 4 == Not(IsInstance(str), 5)
True

class pychoir.Or(*matchers: Matchable)¶

A Matcher checking that the compared value matches at least one of the passed Matchable s.

Consider using the | operator (Matcher.__or__()) instead: StartsWith('a') | StartsWith('b').

Parameters:: matchers – The value(s) and/or matcher(s) to compare against.

Usage:

>>> from pychoir import Or, IsInstance, StartsWith
>>> 5 == Or(IsInstance(int), 5)
True
>>> 'abc' == Or(StartsWith('abc'), StartsWith('def'))
True
>>> '4' == Or(IsInstance(int), 5)
False

class pychoir.ResultsTrueFor(*conditions: Callable[[Any], bool])¶

A Matcher checking that the compared value results True when given to the passed function(s).

Parameters:: conditions – The functions to check against.

Usage:

>>> from pychoir import ResultsTrueFor
>>> 5 == ResultsTrueFor(bool)
True
>>> 'abc' == ResultsTrueFor(lambda x: x[2] == 'c')
True

Numeric¶

class pychoir.IsEven(name: DefaultType | str | None = DefaultType.DEFAULT)¶

A Matcher checking that the value compared against it is even.

Usage:

>>> from pychoir import IsEven
>>> 4 == IsEven()
True
>>> 5 == IsEven()
False

class pychoir.IsOdd(name: DefaultType | str | None = DefaultType.DEFAULT)¶

A Matcher checking that the value compared against it is odd.

Usage:

>>> from pychoir import IsOdd
>>> 5 == IsOdd()
True
>>> 4 == IsOdd()
False

class pychoir.IsPositive(name: DefaultType | str | None = DefaultType.DEFAULT)¶

A Matcher checking that the value compared against it is positive.

Usage:

>>> from pychoir import IsPositive
>>> 1 == IsPositive()
True
>>> 0 == IsPositive()
False

class pychoir.IsNonNegative(name: DefaultType | str | None = DefaultType.DEFAULT)¶

A Matcher checking that the value compared against it is non-negative.

Usage:

>>> from pychoir import IsPositive
>>> 1 == IsNonNegative()
True
>>> 0 == IsNonNegative()
True
>>> -1 == IsNonNegative()
False

class pychoir.IsNegative(name: DefaultType | str | None = DefaultType.DEFAULT)¶

A Matcher checking that the value compared against it is negative.

Usage:

>>> from pychoir import IsNegative
>>> -1 == IsNegative()
True
>>> 0 == IsNegative()
False

Strings¶

class pychoir.EndsWith(end: str)¶

A Matcher checking that the compared string .endswith() the passed string.

Parameters:: end – The string the compared value is expected to end with.

Usage:

>>> from pychoir import EndsWith
>>> 'foobar' == EndsWith('bar')
True
>>> 'foofoo' == EndsWith('bar')
False

class pychoir.MatchesRegex(regex: str | Pattern)¶

A Matcher checking that the compared string matches the passed regular expression.

Parameters:: regex – The regular expression (as a string or a re.Pattern).

Usage:

>>> import re
>>> from pychoir import MatchesRegex
>>> 'foobar' == MatchesRegex(r'^f.obar')
True
>>> 'foofoo' == MatchesRegex(re.compile(r'^b[ao]r$'))
False

class pychoir.StartsWith(start: str)¶

A Matcher checking that the compared string .startswith() the passed string.

Parameters:: start – The string the compared value is expected to start with.

Usage:

>>> from pychoir import StartsWith
>>> 'foobar' == StartsWith('foo')
True
>>> 'barbar' == StartsWith('foo')
False

Types¶

class pychoir.ConvertsTo(type_: Type[Any])¶

A Matcher checking that the compared value can be converted into the passed type.

Parameters:: type – The type to which conversion shall be attempted.

Usage:

>>> from pychoir import ConvertsTo
>>> '5' == ConvertsTo(int)
True
>>> '5.2' == ConvertsTo(int)
False

class pychoir.IsInstance(*types: Type[Any])¶

A Matcher checking that the compared object’s type matches the passed one.

Parameters:: types – The expected type(s) of compared values.

Usage:

>>> from pychoir import IsInstance
>>> 5 == IsInstance(int)
True
>>> 'foobar' == IsInstance(int)
False
>>> 'foobar' == IsInstance(int, str)
True

pychoir.OfType¶: alias of IsInstance

API Reference¶

Callables¶

Comparisons¶

Containers¶

Core¶

Existential¶

Integration¶

Logical¶

Numeric¶

Strings¶

Types¶

pychoir

Navigation

Related Topics