General matchers

These matchers are the most general breed that is not specific to any particular kind of objects. They allow you to match mock parameters based on their Python types, object attributes, and even arbitrary boolean predicates.

class argmatch.general.Any

Matches any object.

class argmatch.general.Matching(predicate, desc=None)

Matches an object that satisfies given predicate.

Parameters:

• predicate – Callable taking a single argument and returning True or False

• desc – Optional description of the predicate. This will be displayed as a part of the error message on failed assertion.

argmatch.general.ArgThat

alias of Matching

class argmatch.general.Captor(matcher=None)

Argument captor.

You can use Captor to “capture” the original argument that the mock was called with, and perform custom assertions on it.

Example:

captor = Captor()
mock_foo.assert_called_with(captor)

# captured value is available as the `arg` attribute
self.assertEqual(captor.arg.some_method(), 42)
self.assertEqual(captor.arg.some_other_method(), "foo")

Added in version 0.2.

Parameters:

matcher – Optional matcher to validate the argument against before it’s captured

Type matchers

Use these matchers to assert on the type of objects passed to your mocks.

class argmatch.types.InstanceOf(type_, exact=False)

Matches an object that’s an instance of given type (as per isinstance).

Parameters:

• type_ – Type to match against

• exact – If True, the match will only succeed if the value type matches given type_ exactly. Otherwise (the default), a subtype of type_ will also match.

argmatch.types.IsA

alias of InstanceOf

class argmatch.types.SubclassOf(type_, strict=False)

Matches a class that’s a subclass of given type (as per issubclass).

Parameters:

• type_ – Type to match against

• strict – If True, the match if only succeed if the value is a _strict_ subclass of type_ – that is, it’s not type_ itself. Otherwise (the default), any subclass of type_ matches.

argmatch.types.Inherits

alias of SubclassOf

class argmatch.types.Type

Matches any Python type object.

class argmatch.types.Class

Matches a class (but not any other type object).

Attribute matchers

These match objects based on their Python attributes.

class argmatch.attributes.Attrs(*args, **kwargs)

Matches objects based on their attributes.

To match successfully, the object needs to:

• have all the attributes whose names were passed as positional arguments (regardless of their values)

• have the attribute names/values that correspond exactly to keyword arguments’ names and values

Examples:

Attrs('foo')  # `foo` attribute with any value
Attrs('foo', 'bar')  # `foo` and `bar` attributes with any values
Attrs(foo=42)  # `foo` attribute with value of 42
Attrs(bar=Integer())  # `bar` attribute whose value is an integer
Attrs('foo', bar='x')  # `foo` with any value, `bar` with value of 'x'

class argmatch.attributes.HasAttrs(*args)

Matches objects that have all of the specified attribute names, regardless of their values.

Function matchers

class argmatch.functions.Callable

Matches any callable object (as per the callable() function).

class argmatch.functions.Function

Matches any Python function.

class argmatch.functions.GeneratorFunction

Matches a generator function, i.e. one that uses yield in its body.

Note

This is distinct from matching a generator, i.e. an iterable result of calling the generator function, or a generator comprehension ((... for x in ...)). The Generator matcher should be used for those objects instead.

class argmatch.functions.CoroutineFunction

Matches a coroutine function.

A coroutine function is an asynchronous function defined using the @asyncio.coroutine or the async def syntax.

These are only available in Python 3.4 and above. On previous versions of Python, no object will match this matcher.

Object matchers

class argmatch.objects.Bytes

Matches a byte array, i.e. the bytes type.

On Python 2, bytes class is identical to str class.

On Python 3, byte strings are separate class, distinct from str.

class argmatch.objects.Coroutine

Matches an asynchronous coroutine.

A coroutine is a result of an asynchronous function call, where the async function has been defined using @asyncio.coroutine or the async def syntax.

These are only available in Python 3.4 and above. On previous versions of Python, no object will match this matcher.

class argmatch.objects.FileLike(read=True, write=None)

Matches a file-like object.

In general, a file-like object is an object you can read data from, or write data to.

Parameters:

• read – Whether only to match objects that do support (True) or don’t support (False) reading from them. If None is passed, reading capability is not matched against.

• write – Whether only to match objects that do support (True) or don’t support (False) writing to them. If None is passed, writing capability is not matched against.