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 argmatch.collections.Iterable

Matches any iterable.

Parameters:

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

class argmatch.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 ``yield``s objects).

Note

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

class argmatch.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 argmatch.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 argmatch.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 argmatch.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 argmatch.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 argmatch.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.