Collection matchers

Besides allowing you to assert about various collection types (lists, sets, etc.), these matchers can also verify the elements inside those collections.

This way, you can express even complex conditions in a concise and readable manner. Here’s a couple of examples:

# list of ints
List(Integer())
List(of=Integer())
List(int)  # types are also accepted as item matchers

# list of strings starting with 'http://'
List(of=String() & StartsWith('http://'))

# dictionary mapping strings to strings
Dict(String(), String())

# dict with string keys (no restriction on values)
Dict(keys=String())

# list of dicts mapping strings to some custom type
List(Dict(String(), Foo))

Abstract collection types

These mostly correspond to the abstract base classes defined in the standard collections module.

class callee.collections.Iterable

Matches any iterable.

class callee.collections.Generator

Matches an iterable that’s a generator.

A generator can be a generator expression (“comprehension”) or an invocation of a generator function (one that yields objects).

Note

To match a generator function itself, you should use the GeneratorFunction matcher instead.

class callee.collections.Sequence(of=None)

Matches a sequence of given items.

A sequence is an iterable that has a length and can be indexed.

Parameters:of – Optional matcher for the elements, or the expected type of the elements.

class callee.collections.Mapping(*args, **kwargs)

Matches a mapping of given items.

Constructor can be invoked either with parameters described below (given as keyword arguments), or with two positional arguments: matchers/types for dictionary keys & values:

Dict(String(), int)  # dict mapping strings to ints

Parameters:

• keys – Matcher for dictionary keys.
• values – Matcher for dictionary values.
• of – Matcher for dictionary items, or a tuple of matchers for keys & values, e.g. (String(), Integer()). Cannot be provided if either keys or values is also passed.

Concrete collections

These match the particular Python built-in collections types, like list or dict.

class callee.collections.List(of=None)

Matches a list of given items.

Parameters:of – Optional matcher for the elements, or the expected type of the elements.

class callee.collections.Set(of=None)

Matches a set of given items.

Parameters:of – Optional matcher for the elements, or the expected type of the elements.

class callee.collections.Dict(*args, **kwargs)

Matches a dictionary (dict) of given items.

Constructor can be invoked either with parameters described below (given as keyword arguments), or with two positional arguments: matchers/types for dictionary keys & values:

Dict(String(), int)  # dict mapping strings to ints

Parameters:

• keys – Matcher for dictionary keys.
• values – Matcher for dictionary values.
• of – Matcher for dictionary items, or a tuple of matchers for keys & values, e.g. (String(), Integer()). Cannot be provided if either keys or values is also passed.

class callee.collections.OrderedDict(*args, **kwargs)

Matches an ordered dictionary (collections.OrderedDict) of given items.

On Python 2.6, this requires the ordereddict backport package. Otherwise, no object will match this matcher.

For more information about arguments, see the documentation of Dict.