Yes there are definitely room for documentation improvements.

And, yes - pulling the args out from some_mock.call_args "boils down to doing the matching by hand". You only do it when you *want* to do the matching by hand.

Your use case I would write:

from mock import Mock, ANY

...
my_mock(1, someobj(), bar=someotherobj())
my_mock.assert_called_with(1, ANY, bar=ANY)

args, kwargs = my_mock.call_args
foo = args[1]
bar = kwargs['bar']

self.assertIsInstance(bar, someobj)
self.assertIsInstance(foo, someotherobj)


It's a *little* cumbersome, but not something I do very often and not much extra code. I'm not sure that having "assert_called_with" return objects is an intuitive API either. (And having to specify tuple indices in a call to ANY is a bit odd too.)

Custom matchers that do the comparison in their __eq__ method would be another possibility:

class IsInstance(object):
  def __init__(self, Type):
    self.Type = Type
  def __eq__(self, other):
   return isinstance(other, self.Type)


my_mock.assert_called_with(1, IsInstance(someobj), bar=IsInstance(someotherobj))