• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# mock.py
2# Test tools for mocking and patching.
3# Copyright (C) 2007-2012 Michael Foord & the mock team
4# E-mail: fuzzyman AT voidspace DOT org DOT uk
5
6# mock 1.0
7# http://www.voidspace.org.uk/python/mock/
8
9# Released subject to the BSD License
10# Please see http://www.voidspace.org.uk/python/license.shtml
11
12# Scripts maintained at http://www.voidspace.org.uk/python/index.shtml
13# Comments, suggestions and bug reports welcome.
14
15
16__all__ = (
17    'Mock',
18    'MagicMock',
19    'patch',
20    'sentinel',
21    'DEFAULT',
22    'ANY',
23    'call',
24    'create_autospec',
25    'FILTER_DIR',
26    'NonCallableMock',
27    'NonCallableMagicMock',
28    'mock_open',
29    'PropertyMock',
30)
31
32
33__version__ = '1.0.1'
34
35
36import pprint
37import sys
38
39try:
40    import inspect
41except ImportError:
42    # for alternative platforms that
43    # may not have inspect
44    inspect = None
45
46try:
47    from functools import wraps as original_wraps
48except ImportError:
49    # Python 2.4 compatibility
50    def wraps(original):
51        def inner(f):
52            f.__name__ = original.__name__
53            f.__doc__ = original.__doc__
54            f.__module__ = original.__module__
55            f.__wrapped__ = original
56            return f
57        return inner
58else:
59    if sys.version_info[:2] >= (3, 3):
60        wraps = original_wraps
61    else:
62        def wraps(func):
63            def inner(f):
64                f = original_wraps(func)(f)
65                f.__wrapped__ = func
66                return f
67            return inner
68
69try:
70    unicode
71except NameError:
72    # Python 3
73    basestring = unicode = str
74
75try:
76    long
77except NameError:
78    # Python 3
79    long = int
80
81try:
82    BaseException
83except NameError:
84    # Python 2.4 compatibility
85    BaseException = Exception
86
87try:
88    next
89except NameError:
90    def next(obj):
91        return obj.next()
92
93
94BaseExceptions = (BaseException,)
95if 'java' in sys.platform:
96    # jython
97    import java
98    BaseExceptions = (BaseException, java.lang.Throwable)
99
100try:
101    _isidentifier = str.isidentifier
102except AttributeError:
103    # Python 2.X
104    import keyword
105    import re
106    regex = re.compile(r'^[a-z_][a-z0-9_]*$', re.I)
107    def _isidentifier(string):
108        if string in keyword.kwlist:
109            return False
110        return regex.match(string)
111
112
113inPy3k = sys.version_info[0] == 3
114
115# Needed to work around Python 3 bug where use of "super" interferes with
116# defining __class__ as a descriptor
117_super = super
118
119self = 'im_self'
120builtin = '__builtin__'
121if inPy3k:
122    self = '__self__'
123    builtin = 'builtins'
124
125FILTER_DIR = True
126
127
128def _is_instance_mock(obj):
129    # can't use isinstance on Mock objects because they override __class__
130    # The base class for all mocks is NonCallableMock
131    return issubclass(type(obj), NonCallableMock)
132
133
134def _is_exception(obj):
135    return (
136        isinstance(obj, BaseExceptions) or
137        isinstance(obj, ClassTypes) and issubclass(obj, BaseExceptions)
138    )
139
140
141class _slotted(object):
142    __slots__ = ['a']
143
144
145DescriptorTypes = (
146    type(_slotted.a),
147    property,
148)
149
150
151def _getsignature(func, skipfirst, instance=False):
152    if inspect is None:
153        raise ImportError('inspect module not available')
154
155    if isinstance(func, ClassTypes) and not instance:
156        try:
157            func = func.__init__
158        except AttributeError:
159            return
160        skipfirst = True
161    elif not isinstance(func, FunctionTypes):
162        # for classes where instance is True we end up here too
163        try:
164            func = func.__call__
165        except AttributeError:
166            return
167
168    if inPy3k:
169        try:
170            argspec = inspect.getfullargspec(func)
171        except TypeError:
172            # C function / method, possibly inherited object().__init__
173            return
174        regargs, varargs, varkw, defaults, kwonly, kwonlydef, ann = argspec
175    else:
176        try:
177            regargs, varargs, varkwargs, defaults = inspect.getargspec(func)
178        except TypeError:
179            # C function / method, possibly inherited object().__init__
180            return
181
182    # instance methods and classmethods need to lose the self argument
183    if getattr(func, self, None) is not None:
184        regargs = regargs[1:]
185    if skipfirst:
186        # this condition and the above one are never both True - why?
187        regargs = regargs[1:]
188
189    if inPy3k:
190        signature = inspect.formatargspec(
191            regargs, varargs, varkw, defaults,
192            kwonly, kwonlydef, ann, formatvalue=lambda value: "")
193    else:
194        signature = inspect.formatargspec(
195            regargs, varargs, varkwargs, defaults,
196            formatvalue=lambda value: "")
197    return signature[1:-1], func
198
199
200def _check_signature(func, mock, skipfirst, instance=False):
201    if not _callable(func):
202        return
203
204    result = _getsignature(func, skipfirst, instance)
205    if result is None:
206        return
207    signature, func = result
208
209    # can't use self because "self" is common as an argument name
210    # unfortunately even not in the first place
211    src = "lambda _mock_self, %s: None" % signature
212    checksig = eval(src, {})
213    _copy_func_details(func, checksig)
214    type(mock)._mock_check_sig = checksig
215
216
217def _copy_func_details(func, funcopy):
218    funcopy.__name__ = func.__name__
219    funcopy.__doc__ = func.__doc__
220    #funcopy.__dict__.update(func.__dict__)
221    funcopy.__module__ = func.__module__
222    if not inPy3k:
223        funcopy.func_defaults = func.func_defaults
224        return
225    funcopy.__defaults__ = func.__defaults__
226    funcopy.__kwdefaults__ = func.__kwdefaults__
227
228
229def _callable(obj):
230    if isinstance(obj, ClassTypes):
231        return True
232    if getattr(obj, '__call__', None) is not None:
233        return True
234    return False
235
236
237def _is_list(obj):
238    # checks for list or tuples
239    # XXXX badly named!
240    return type(obj) in (list, tuple)
241
242
243def _instance_callable(obj):
244    """Given an object, return True if the object is callable.
245    For classes, return True if instances would be callable."""
246    if not isinstance(obj, ClassTypes):
247        # already an instance
248        return getattr(obj, '__call__', None) is not None
249
250    klass = obj
251    # uses __bases__ instead of __mro__ so that we work with old style classes
252    if klass.__dict__.get('__call__') is not None:
253        return True
254
255    for base in klass.__bases__:
256        if _instance_callable(base):
257            return True
258    return False
259
260
261def _set_signature(mock, original, instance=False):
262    # creates a function with signature (*args, **kwargs) that delegates to a
263    # mock. It still does signature checking by calling a lambda with the same
264    # signature as the original.
265    if not _callable(original):
266        return
267
268    skipfirst = isinstance(original, ClassTypes)
269    result = _getsignature(original, skipfirst, instance)
270    if result is None:
271        # was a C function (e.g. object().__init__ ) that can't be mocked
272        return
273
274    signature, func = result
275
276    src = "lambda %s: None" % signature
277    checksig = eval(src, {})
278    _copy_func_details(func, checksig)
279
280    name = original.__name__
281    if not _isidentifier(name):
282        name = 'funcopy'
283    context = {'_checksig_': checksig, 'mock': mock}
284    src = """def %s(*args, **kwargs):
285    _checksig_(*args, **kwargs)
286    return mock(*args, **kwargs)""" % name
287    exec (src, context)
288    funcopy = context[name]
289    _setup_func(funcopy, mock)
290    return funcopy
291
292
293def _setup_func(funcopy, mock):
294    funcopy.mock = mock
295
296    # can't use isinstance with mocks
297    if not _is_instance_mock(mock):
298        return
299
300    def assert_called_with(*args, **kwargs):
301        return mock.assert_called_with(*args, **kwargs)
302    def assert_called_once_with(*args, **kwargs):
303        return mock.assert_called_once_with(*args, **kwargs)
304    def assert_has_calls(*args, **kwargs):
305        return mock.assert_has_calls(*args, **kwargs)
306    def assert_any_call(*args, **kwargs):
307        return mock.assert_any_call(*args, **kwargs)
308    def reset_mock():
309        funcopy.method_calls = _CallList()
310        funcopy.mock_calls = _CallList()
311        mock.reset_mock()
312        ret = funcopy.return_value
313        if _is_instance_mock(ret) and not ret is mock:
314            ret.reset_mock()
315
316    funcopy.called = False
317    funcopy.call_count = 0
318    funcopy.call_args = None
319    funcopy.call_args_list = _CallList()
320    funcopy.method_calls = _CallList()
321    funcopy.mock_calls = _CallList()
322
323    funcopy.return_value = mock.return_value
324    funcopy.side_effect = mock.side_effect
325    funcopy._mock_children = mock._mock_children
326
327    funcopy.assert_called_with = assert_called_with
328    funcopy.assert_called_once_with = assert_called_once_with
329    funcopy.assert_has_calls = assert_has_calls
330    funcopy.assert_any_call = assert_any_call
331    funcopy.reset_mock = reset_mock
332
333    mock._mock_delegate = funcopy
334
335
336def _is_magic(name):
337    return '__%s__' % name[2:-2] == name
338
339
340class _SentinelObject(object):
341    "A unique, named, sentinel object."
342    def __init__(self, name):
343        self.name = name
344
345    def __repr__(self):
346        return 'sentinel.%s' % self.name
347
348
349class _Sentinel(object):
350    """Access attributes to return a named object, usable as a sentinel."""
351    def __init__(self):
352        self._sentinels = {}
353
354    def __getattr__(self, name):
355        if name == '__bases__':
356            # Without this help(mock) raises an exception
357            raise AttributeError
358        return self._sentinels.setdefault(name, _SentinelObject(name))
359
360
361sentinel = _Sentinel()
362
363DEFAULT = sentinel.DEFAULT
364_missing = sentinel.MISSING
365_deleted = sentinel.DELETED
366
367
368class OldStyleClass:
369    pass
370ClassType = type(OldStyleClass)
371
372
373def _copy(value):
374    if type(value) in (dict, list, tuple, set):
375        return type(value)(value)
376    return value
377
378
379ClassTypes = (type,)
380if not inPy3k:
381    ClassTypes = (type, ClassType)
382
383_allowed_names = set(
384    [
385        'return_value', '_mock_return_value', 'side_effect',
386        '_mock_side_effect', '_mock_parent', '_mock_new_parent',
387        '_mock_name', '_mock_new_name'
388    ]
389)
390
391
392def _delegating_property(name):
393    _allowed_names.add(name)
394    _the_name = '_mock_' + name
395    def _get(self, name=name, _the_name=_the_name):
396        sig = self._mock_delegate
397        if sig is None:
398            return getattr(self, _the_name)
399        return getattr(sig, name)
400    def _set(self, value, name=name, _the_name=_the_name):
401        sig = self._mock_delegate
402        if sig is None:
403            self.__dict__[_the_name] = value
404        else:
405            setattr(sig, name, value)
406
407    return property(_get, _set)
408
409
410
411class _CallList(list):
412
413    def __contains__(self, value):
414        if not isinstance(value, list):
415            return list.__contains__(self, value)
416        len_value = len(value)
417        len_self = len(self)
418        if len_value > len_self:
419            return False
420
421        for i in range(0, len_self - len_value + 1):
422            sub_list = self[i:i+len_value]
423            if sub_list == value:
424                return True
425        return False
426
427    def __repr__(self):
428        return pprint.pformat(list(self))
429
430
431def _check_and_set_parent(parent, value, name, new_name):
432    if not _is_instance_mock(value):
433        return False
434    if ((value._mock_name or value._mock_new_name) or
435        (value._mock_parent is not None) or
436        (value._mock_new_parent is not None)):
437        return False
438
439    _parent = parent
440    while _parent is not None:
441        # setting a mock (value) as a child or return value of itself
442        # should not modify the mock
443        if _parent is value:
444            return False
445        _parent = _parent._mock_new_parent
446
447    if new_name:
448        value._mock_new_parent = parent
449        value._mock_new_name = new_name
450    if name:
451        value._mock_parent = parent
452        value._mock_name = name
453    return True
454
455
456
457class Base(object):
458    _mock_return_value = DEFAULT
459    _mock_side_effect = None
460    def __init__(self, *args, **kwargs):
461        pass
462
463
464
465class NonCallableMock(Base):
466    """A non-callable version of `Mock`"""
467
468    def __new__(cls, *args, **kw):
469        # every instance has its own class
470        # so we can create magic methods on the
471        # class without stomping on other mocks
472        new = type(cls.__name__, (cls,), {'__doc__': cls.__doc__})
473        instance = object.__new__(new)
474        return instance
475
476
477    def __init__(
478            self, spec=None, wraps=None, name=None, spec_set=None,
479            parent=None, _spec_state=None, _new_name='', _new_parent=None,
480            **kwargs
481        ):
482        if _new_parent is None:
483            _new_parent = parent
484
485        __dict__ = self.__dict__
486        __dict__['_mock_parent'] = parent
487        __dict__['_mock_name'] = name
488        __dict__['_mock_new_name'] = _new_name
489        __dict__['_mock_new_parent'] = _new_parent
490
491        if spec_set is not None:
492            spec = spec_set
493            spec_set = True
494
495        self._mock_add_spec(spec, spec_set)
496
497        __dict__['_mock_children'] = {}
498        __dict__['_mock_wraps'] = wraps
499        __dict__['_mock_delegate'] = None
500
501        __dict__['_mock_called'] = False
502        __dict__['_mock_call_args'] = None
503        __dict__['_mock_call_count'] = 0
504        __dict__['_mock_call_args_list'] = _CallList()
505        __dict__['_mock_mock_calls'] = _CallList()
506
507        __dict__['method_calls'] = _CallList()
508
509        if kwargs:
510            self.configure_mock(**kwargs)
511
512        _super(NonCallableMock, self).__init__(
513            spec, wraps, name, spec_set, parent,
514            _spec_state
515        )
516
517
518    def attach_mock(self, mock, attribute):
519        """
520        Attach a mock as an attribute of this one, replacing its name and
521        parent. Calls to the attached mock will be recorded in the
522        `method_calls` and `mock_calls` attributes of this one."""
523        mock._mock_parent = None
524        mock._mock_new_parent = None
525        mock._mock_name = ''
526        mock._mock_new_name = None
527
528        setattr(self, attribute, mock)
529
530
531    def mock_add_spec(self, spec, spec_set=False):
532        """Add a spec to a mock. `spec` can either be an object or a
533        list of strings. Only attributes on the `spec` can be fetched as
534        attributes from the mock.
535
536        If `spec_set` is True then only attributes on the spec can be set."""
537        self._mock_add_spec(spec, spec_set)
538
539
540    def _mock_add_spec(self, spec, spec_set):
541        _spec_class = None
542
543        if spec is not None and not _is_list(spec):
544            if isinstance(spec, ClassTypes):
545                _spec_class = spec
546            else:
547                _spec_class = _get_class(spec)
548
549            spec = dir(spec)
550
551        __dict__ = self.__dict__
552        __dict__['_spec_class'] = _spec_class
553        __dict__['_spec_set'] = spec_set
554        __dict__['_mock_methods'] = spec
555
556
557    def __get_return_value(self):
558        ret = self._mock_return_value
559        if self._mock_delegate is not None:
560            ret = self._mock_delegate.return_value
561
562        if ret is DEFAULT:
563            ret = self._get_child_mock(
564                _new_parent=self, _new_name='()'
565            )
566            self.return_value = ret
567        return ret
568
569
570    def __set_return_value(self, value):
571        if self._mock_delegate is not None:
572            self._mock_delegate.return_value = value
573        else:
574            self._mock_return_value = value
575            _check_and_set_parent(self, value, None, '()')
576
577    __return_value_doc = "The value to be returned when the mock is called."
578    return_value = property(__get_return_value, __set_return_value,
579                            __return_value_doc)
580
581
582    @property
583    def __class__(self):
584        if self._spec_class is None:
585            return type(self)
586        return self._spec_class
587
588    called = _delegating_property('called')
589    call_count = _delegating_property('call_count')
590    call_args = _delegating_property('call_args')
591    call_args_list = _delegating_property('call_args_list')
592    mock_calls = _delegating_property('mock_calls')
593
594
595    def __get_side_effect(self):
596        sig = self._mock_delegate
597        if sig is None:
598            return self._mock_side_effect
599        return sig.side_effect
600
601    def __set_side_effect(self, value):
602        value = _try_iter(value)
603        sig = self._mock_delegate
604        if sig is None:
605            self._mock_side_effect = value
606        else:
607            sig.side_effect = value
608
609    side_effect = property(__get_side_effect, __set_side_effect)
610
611
612    def reset_mock(self):
613        "Restore the mock object to its initial state."
614        self.called = False
615        self.call_args = None
616        self.call_count = 0
617        self.mock_calls = _CallList()
618        self.call_args_list = _CallList()
619        self.method_calls = _CallList()
620
621        for child in self._mock_children.values():
622            if isinstance(child, _SpecState):
623                continue
624            child.reset_mock()
625
626        ret = self._mock_return_value
627        if _is_instance_mock(ret) and ret is not self:
628            ret.reset_mock()
629
630
631    def configure_mock(self, **kwargs):
632        """Set attributes on the mock through keyword arguments.
633
634        Attributes plus return values and side effects can be set on child
635        mocks using standard dot notation and unpacking a dictionary in the
636        method call:
637
638        >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError}
639        >>> mock.configure_mock(**attrs)"""
640        for arg, val in sorted(kwargs.items(),
641                               # we sort on the number of dots so that
642                               # attributes are set before we set attributes on
643                               # attributes
644                               key=lambda entry: entry[0].count('.')):
645            args = arg.split('.')
646            final = args.pop()
647            obj = self
648            for entry in args:
649                obj = getattr(obj, entry)
650            setattr(obj, final, val)
651
652
653    def __getattr__(self, name):
654        if name == '_mock_methods':
655            raise AttributeError(name)
656        elif self._mock_methods is not None:
657            if name not in self._mock_methods or name in _all_magics:
658                raise AttributeError("Mock object has no attribute %r" % name)
659        elif _is_magic(name):
660            raise AttributeError(name)
661
662        result = self._mock_children.get(name)
663        if result is _deleted:
664            raise AttributeError(name)
665        elif result is None:
666            wraps = None
667            if self._mock_wraps is not None:
668                # XXXX should we get the attribute without triggering code
669                # execution?
670                wraps = getattr(self._mock_wraps, name)
671
672            result = self._get_child_mock(
673                parent=self, name=name, wraps=wraps, _new_name=name,
674                _new_parent=self
675            )
676            self._mock_children[name]  = result
677
678        elif isinstance(result, _SpecState):
679            result = create_autospec(
680                result.spec, result.spec_set, result.instance,
681                result.parent, result.name
682            )
683            self._mock_children[name]  = result
684
685        return result
686
687
688    def __repr__(self):
689        _name_list = [self._mock_new_name]
690        _parent = self._mock_new_parent
691        last = self
692
693        dot = '.'
694        if _name_list == ['()']:
695            dot = ''
696        seen = set()
697        while _parent is not None:
698            last = _parent
699
700            _name_list.append(_parent._mock_new_name + dot)
701            dot = '.'
702            if _parent._mock_new_name == '()':
703                dot = ''
704
705            _parent = _parent._mock_new_parent
706
707            # use ids here so as not to call __hash__ on the mocks
708            if id(_parent) in seen:
709                break
710            seen.add(id(_parent))
711
712        _name_list = list(reversed(_name_list))
713        _first = last._mock_name or 'mock'
714        if len(_name_list) > 1:
715            if _name_list[1] not in ('()', '().'):
716                _first += '.'
717        _name_list[0] = _first
718        name = ''.join(_name_list)
719
720        name_string = ''
721        if name not in ('mock', 'mock.'):
722            name_string = ' name=%r' % name
723
724        spec_string = ''
725        if self._spec_class is not None:
726            spec_string = ' spec=%r'
727            if self._spec_set:
728                spec_string = ' spec_set=%r'
729            spec_string = spec_string % self._spec_class.__name__
730        return "<%s%s%s id='%s'>" % (
731            type(self).__name__,
732            name_string,
733            spec_string,
734            id(self)
735        )
736
737
738    def __dir__(self):
739        """Filter the output of `dir(mock)` to only useful members.
740        XXXX
741        """
742        extras = self._mock_methods or []
743        from_type = dir(type(self))
744        from_dict = list(self.__dict__)
745
746        if FILTER_DIR:
747            from_type = [e for e in from_type if not e.startswith('_')]
748            from_dict = [e for e in from_dict if not e.startswith('_') or
749                         _is_magic(e)]
750        return sorted(set(extras + from_type + from_dict +
751                          list(self._mock_children)))
752
753
754    def __setattr__(self, name, value):
755        if name in _allowed_names:
756            # property setters go through here
757            return object.__setattr__(self, name, value)
758        elif (self._spec_set and self._mock_methods is not None and
759            name not in self._mock_methods and
760            name not in self.__dict__):
761            raise AttributeError("Mock object has no attribute '%s'" % name)
762        elif name in _unsupported_magics:
763            msg = 'Attempting to set unsupported magic method %r.' % name
764            raise AttributeError(msg)
765        elif name in _all_magics:
766            if self._mock_methods is not None and name not in self._mock_methods:
767                raise AttributeError("Mock object has no attribute '%s'" % name)
768
769            if not _is_instance_mock(value):
770                setattr(type(self), name, _get_method(name, value))
771                original = value
772                value = lambda *args, **kw: original(self, *args, **kw)
773            else:
774                # only set _new_name and not name so that mock_calls is tracked
775                # but not method calls
776                _check_and_set_parent(self, value, None, name)
777                setattr(type(self), name, value)
778                self._mock_children[name] = value
779        elif name == '__class__':
780            self._spec_class = value
781            return
782        else:
783            if _check_and_set_parent(self, value, name, name):
784                self._mock_children[name] = value
785        return object.__setattr__(self, name, value)
786
787
788    def __delattr__(self, name):
789        if name in _all_magics and name in type(self).__dict__:
790            delattr(type(self), name)
791            if name not in self.__dict__:
792                # for magic methods that are still MagicProxy objects and
793                # not set on the instance itself
794                return
795
796        if name in self.__dict__:
797            object.__delattr__(self, name)
798
799        obj = self._mock_children.get(name, _missing)
800        if obj is _deleted:
801            raise AttributeError(name)
802        if obj is not _missing:
803            del self._mock_children[name]
804        self._mock_children[name] = _deleted
805
806
807
808    def _format_mock_call_signature(self, args, kwargs):
809        name = self._mock_name or 'mock'
810        return _format_call_signature(name, args, kwargs)
811
812
813    def _format_mock_failure_message(self, args, kwargs):
814        message = 'Expected call: %s\nActual call: %s'
815        expected_string = self._format_mock_call_signature(args, kwargs)
816        call_args = self.call_args
817        if len(call_args) == 3:
818            call_args = call_args[1:]
819        actual_string = self._format_mock_call_signature(*call_args)
820        return message % (expected_string, actual_string)
821
822
823    def assert_called_with(_mock_self, *args, **kwargs):
824        """assert that the mock was called with the specified arguments.
825
826        Raises an AssertionError if the args and keyword args passed in are
827        different to the last call to the mock."""
828        self = _mock_self
829        if self.call_args is None:
830            expected = self._format_mock_call_signature(args, kwargs)
831            raise AssertionError('Expected call: %s\nNot called' % (expected,))
832
833        if self.call_args != (args, kwargs):
834            msg = self._format_mock_failure_message(args, kwargs)
835            raise AssertionError(msg)
836
837
838    def assert_called_once_with(_mock_self, *args, **kwargs):
839        """assert that the mock was called exactly once and with the specified
840        arguments."""
841        self = _mock_self
842        if not self.call_count == 1:
843            msg = ("Expected to be called once. Called %s times." %
844                   self.call_count)
845            raise AssertionError(msg)
846        return self.assert_called_with(*args, **kwargs)
847
848
849    def assert_has_calls(self, calls, any_order=False):
850        """assert the mock has been called with the specified calls.
851        The `mock_calls` list is checked for the calls.
852
853        If `any_order` is False (the default) then the calls must be
854        sequential. There can be extra calls before or after the
855        specified calls.
856
857        If `any_order` is True then the calls can be in any order, but
858        they must all appear in `mock_calls`."""
859        if not any_order:
860            if calls not in self.mock_calls:
861                raise AssertionError(
862                    'Calls not found.\nExpected: %r\n'
863                    'Actual: %r' % (calls, self.mock_calls)
864                )
865            return
866
867        all_calls = list(self.mock_calls)
868
869        not_found = []
870        for kall in calls:
871            try:
872                all_calls.remove(kall)
873            except ValueError:
874                not_found.append(kall)
875        if not_found:
876            raise AssertionError(
877                '%r not all found in call list' % (tuple(not_found),)
878            )
879
880
881    def assert_any_call(self, *args, **kwargs):
882        """assert the mock has been called with the specified arguments.
883
884        The assert passes if the mock has *ever* been called, unlike
885        `assert_called_with` and `assert_called_once_with` that only pass if
886        the call is the most recent one."""
887        kall = call(*args, **kwargs)
888        if kall not in self.call_args_list:
889            expected_string = self._format_mock_call_signature(args, kwargs)
890            raise AssertionError(
891                '%s call not found' % expected_string
892            )
893
894
895    def _get_child_mock(self, **kw):
896        """Create the child mocks for attributes and return value.
897        By default child mocks will be the same type as the parent.
898        Subclasses of Mock may want to override this to customize the way
899        child mocks are made.
900
901        For non-callable mocks the callable variant will be used (rather than
902        any custom subclass)."""
903        _type = type(self)
904        if not issubclass(_type, CallableMixin):
905            if issubclass(_type, NonCallableMagicMock):
906                klass = MagicMock
907            elif issubclass(_type, NonCallableMock) :
908                klass = Mock
909        else:
910            klass = _type.__mro__[1]
911        return klass(**kw)
912
913
914
915def _try_iter(obj):
916    if obj is None:
917        return obj
918    if _is_exception(obj):
919        return obj
920    if _callable(obj):
921        return obj
922    try:
923        return iter(obj)
924    except TypeError:
925        # XXXX backwards compatibility
926        # but this will blow up on first call - so maybe we should fail early?
927        return obj
928
929
930
931class CallableMixin(Base):
932
933    def __init__(self, spec=None, side_effect=None, return_value=DEFAULT,
934                 wraps=None, name=None, spec_set=None, parent=None,
935                 _spec_state=None, _new_name='', _new_parent=None, **kwargs):
936        self.__dict__['_mock_return_value'] = return_value
937
938        _super(CallableMixin, self).__init__(
939            spec, wraps, name, spec_set, parent,
940            _spec_state, _new_name, _new_parent, **kwargs
941        )
942
943        self.side_effect = side_effect
944
945
946    def _mock_check_sig(self, *args, **kwargs):
947        # stub method that can be replaced with one with a specific signature
948        pass
949
950
951    def __call__(_mock_self, *args, **kwargs):
952        # can't use self in-case a function / method we are mocking uses self
953        # in the signature
954        _mock_self._mock_check_sig(*args, **kwargs)
955        return _mock_self._mock_call(*args, **kwargs)
956
957
958    def _mock_call(_mock_self, *args, **kwargs):
959        self = _mock_self
960        self.called = True
961        self.call_count += 1
962        self.call_args = _Call((args, kwargs), two=True)
963        self.call_args_list.append(_Call((args, kwargs), two=True))
964
965        _new_name = self._mock_new_name
966        _new_parent = self._mock_new_parent
967        self.mock_calls.append(_Call(('', args, kwargs)))
968
969        seen = set()
970        skip_next_dot = _new_name == '()'
971        do_method_calls = self._mock_parent is not None
972        name = self._mock_name
973        while _new_parent is not None:
974            this_mock_call = _Call((_new_name, args, kwargs))
975            if _new_parent._mock_new_name:
976                dot = '.'
977                if skip_next_dot:
978                    dot = ''
979
980                skip_next_dot = False
981                if _new_parent._mock_new_name == '()':
982                    skip_next_dot = True
983
984                _new_name = _new_parent._mock_new_name + dot + _new_name
985
986            if do_method_calls:
987                if _new_name == name:
988                    this_method_call = this_mock_call
989                else:
990                    this_method_call = _Call((name, args, kwargs))
991                _new_parent.method_calls.append(this_method_call)
992
993                do_method_calls = _new_parent._mock_parent is not None
994                if do_method_calls:
995                    name = _new_parent._mock_name + '.' + name
996
997            _new_parent.mock_calls.append(this_mock_call)
998            _new_parent = _new_parent._mock_new_parent
999
1000            # use ids here so as not to call __hash__ on the mocks
1001            _new_parent_id = id(_new_parent)
1002            if _new_parent_id in seen:
1003                break
1004            seen.add(_new_parent_id)
1005
1006        ret_val = DEFAULT
1007        effect = self.side_effect
1008        if effect is not None:
1009            if _is_exception(effect):
1010                raise effect
1011
1012            if not _callable(effect):
1013                result = next(effect)
1014                if _is_exception(result):
1015                    raise result
1016                return result
1017
1018            ret_val = effect(*args, **kwargs)
1019            if ret_val is DEFAULT:
1020                ret_val = self.return_value
1021
1022        if (self._mock_wraps is not None and
1023             self._mock_return_value is DEFAULT):
1024            return self._mock_wraps(*args, **kwargs)
1025        if ret_val is DEFAULT:
1026            ret_val = self.return_value
1027        return ret_val
1028
1029
1030
1031class Mock(CallableMixin, NonCallableMock):
1032    """
1033    Create a new `Mock` object. `Mock` takes several optional arguments
1034    that specify the behaviour of the Mock object:
1035
1036    * `spec`: This can be either a list of strings or an existing object (a
1037      class or instance) that acts as the specification for the mock object. If
1038      you pass in an object then a list of strings is formed by calling dir on
1039      the object (excluding unsupported magic attributes and methods). Accessing
1040      any attribute not in this list will raise an `AttributeError`.
1041
1042      If `spec` is an object (rather than a list of strings) then
1043      `mock.__class__` returns the class of the spec object. This allows mocks
1044      to pass `isinstance` tests.
1045
1046    * `spec_set`: A stricter variant of `spec`. If used, attempting to *set*
1047      or get an attribute on the mock that isn't on the object passed as
1048      `spec_set` will raise an `AttributeError`.
1049
1050    * `side_effect`: A function to be called whenever the Mock is called. See
1051      the `side_effect` attribute. Useful for raising exceptions or
1052      dynamically changing return values. The function is called with the same
1053      arguments as the mock, and unless it returns `DEFAULT`, the return
1054      value of this function is used as the return value.
1055
1056      Alternatively `side_effect` can be an exception class or instance. In
1057      this case the exception will be raised when the mock is called.
1058
1059      If `side_effect` is an iterable then each call to the mock will return
1060      the next value from the iterable. If any of the members of the iterable
1061      are exceptions they will be raised instead of returned.
1062
1063    * `return_value`: The value returned when the mock is called. By default
1064      this is a new Mock (created on first access). See the
1065      `return_value` attribute.
1066
1067    * `wraps`: Item for the mock object to wrap. If `wraps` is not None then
1068      calling the Mock will pass the call through to the wrapped object
1069      (returning the real result). Attribute access on the mock will return a
1070      Mock object that wraps the corresponding attribute of the wrapped object
1071      (so attempting to access an attribute that doesn't exist will raise an
1072      `AttributeError`).
1073
1074      If the mock has an explicit `return_value` set then calls are not passed
1075      to the wrapped object and the `return_value` is returned instead.
1076
1077    * `name`: If the mock has a name then it will be used in the repr of the
1078      mock. This can be useful for debugging. The name is propagated to child
1079      mocks.
1080
1081    Mocks can also be called with arbitrary keyword arguments. These will be
1082    used to set attributes on the mock after it is created.
1083    """
1084
1085
1086
1087def _dot_lookup(thing, comp, import_path):
1088    try:
1089        return getattr(thing, comp)
1090    except AttributeError:
1091        __import__(import_path)
1092        return getattr(thing, comp)
1093
1094
1095def _importer(target):
1096    components = target.split('.')
1097    import_path = components.pop(0)
1098    thing = __import__(import_path)
1099
1100    for comp in components:
1101        import_path += ".%s" % comp
1102        thing = _dot_lookup(thing, comp, import_path)
1103    return thing
1104
1105
1106def _is_started(patcher):
1107    # XXXX horrible
1108    return hasattr(patcher, 'is_local')
1109
1110
1111class _patch(object):
1112
1113    attribute_name = None
1114    _active_patches = set()
1115
1116    def __init__(
1117            self, getter, attribute, new, spec, create,
1118            spec_set, autospec, new_callable, kwargs
1119        ):
1120        if new_callable is not None:
1121            if new is not DEFAULT:
1122                raise ValueError(
1123                    "Cannot use 'new' and 'new_callable' together"
1124                )
1125            if autospec is not None:
1126                raise ValueError(
1127                    "Cannot use 'autospec' and 'new_callable' together"
1128                )
1129
1130        self.getter = getter
1131        self.attribute = attribute
1132        self.new = new
1133        self.new_callable = new_callable
1134        self.spec = spec
1135        self.create = create
1136        self.has_local = False
1137        self.spec_set = spec_set
1138        self.autospec = autospec
1139        self.kwargs = kwargs
1140        self.additional_patchers = []
1141
1142
1143    def copy(self):
1144        patcher = _patch(
1145            self.getter, self.attribute, self.new, self.spec,
1146            self.create, self.spec_set,
1147            self.autospec, self.new_callable, self.kwargs
1148        )
1149        patcher.attribute_name = self.attribute_name
1150        patcher.additional_patchers = [
1151            p.copy() for p in self.additional_patchers
1152        ]
1153        return patcher
1154
1155
1156    def __call__(self, func):
1157        if isinstance(func, ClassTypes):
1158            return self.decorate_class(func)
1159        return self.decorate_callable(func)
1160
1161
1162    def decorate_class(self, klass):
1163        for attr in dir(klass):
1164            if not attr.startswith(patch.TEST_PREFIX):
1165                continue
1166
1167            attr_value = getattr(klass, attr)
1168            if not hasattr(attr_value, "__call__"):
1169                continue
1170
1171            patcher = self.copy()
1172            setattr(klass, attr, patcher(attr_value))
1173        return klass
1174
1175
1176    def decorate_callable(self, func):
1177        if hasattr(func, 'patchings'):
1178            func.patchings.append(self)
1179            return func
1180
1181        @wraps(func)
1182        def patched(*args, **keywargs):
1183            # don't use a with here (backwards compatability with Python 2.4)
1184            extra_args = []
1185            entered_patchers = []
1186
1187            # can't use try...except...finally because of Python 2.4
1188            # compatibility
1189            exc_info = tuple()
1190            try:
1191                try:
1192                    for patching in patched.patchings:
1193                        arg = patching.__enter__()
1194                        entered_patchers.append(patching)
1195                        if patching.attribute_name is not None:
1196                            keywargs.update(arg)
1197                        elif patching.new is DEFAULT:
1198                            extra_args.append(arg)
1199
1200                    args += tuple(extra_args)
1201                    return func(*args, **keywargs)
1202                except:
1203                    if (patching not in entered_patchers and
1204                        _is_started(patching)):
1205                        # the patcher may have been started, but an exception
1206                        # raised whilst entering one of its additional_patchers
1207                        entered_patchers.append(patching)
1208                    # Pass the exception to __exit__
1209                    exc_info = sys.exc_info()
1210                    # re-raise the exception
1211                    raise
1212            finally:
1213                for patching in reversed(entered_patchers):
1214                    patching.__exit__(*exc_info)
1215
1216        patched.patchings = [self]
1217        if hasattr(func, 'func_code'):
1218            # not in Python 3
1219            patched.compat_co_firstlineno = getattr(
1220                func, "compat_co_firstlineno",
1221                func.func_code.co_firstlineno
1222            )
1223        return patched
1224
1225
1226    def get_original(self):
1227        target = self.getter()
1228        name = self.attribute
1229
1230        original = DEFAULT
1231        local = False
1232
1233        try:
1234            original = target.__dict__[name]
1235        except (AttributeError, KeyError):
1236            original = getattr(target, name, DEFAULT)
1237        else:
1238            local = True
1239
1240        if not self.create and original is DEFAULT:
1241            raise AttributeError(
1242                "%s does not have the attribute %r" % (target, name)
1243            )
1244        return original, local
1245
1246
1247    def __enter__(self):
1248        """Perform the patch."""
1249        new, spec, spec_set = self.new, self.spec, self.spec_set
1250        autospec, kwargs = self.autospec, self.kwargs
1251        new_callable = self.new_callable
1252        self.target = self.getter()
1253
1254        # normalise False to None
1255        if spec is False:
1256            spec = None
1257        if spec_set is False:
1258            spec_set = None
1259        if autospec is False:
1260            autospec = None
1261
1262        if spec is not None and autospec is not None:
1263            raise TypeError("Can't specify spec and autospec")
1264        if ((spec is not None or autospec is not None) and
1265            spec_set not in (True, None)):
1266            raise TypeError("Can't provide explicit spec_set *and* spec or autospec")
1267
1268        original, local = self.get_original()
1269
1270        if new is DEFAULT and autospec is None:
1271            inherit = False
1272            if spec is True:
1273                # set spec to the object we are replacing
1274                spec = original
1275                if spec_set is True:
1276                    spec_set = original
1277                    spec = None
1278            elif spec is not None:
1279                if spec_set is True:
1280                    spec_set = spec
1281                    spec = None
1282            elif spec_set is True:
1283                spec_set = original
1284
1285            if spec is not None or spec_set is not None:
1286                if original is DEFAULT:
1287                    raise TypeError("Can't use 'spec' with create=True")
1288                if isinstance(original, ClassTypes):
1289                    # If we're patching out a class and there is a spec
1290                    inherit = True
1291
1292            Klass = MagicMock
1293            _kwargs = {}
1294            if new_callable is not None:
1295                Klass = new_callable
1296            elif spec is not None or spec_set is not None:
1297                this_spec = spec
1298                if spec_set is not None:
1299                    this_spec = spec_set
1300                if _is_list(this_spec):
1301                    not_callable = '__call__' not in this_spec
1302                else:
1303                    not_callable = not _callable(this_spec)
1304                if not_callable:
1305                    Klass = NonCallableMagicMock
1306
1307            if spec is not None:
1308                _kwargs['spec'] = spec
1309            if spec_set is not None:
1310                _kwargs['spec_set'] = spec_set
1311
1312            # add a name to mocks
1313            if (isinstance(Klass, type) and
1314                issubclass(Klass, NonCallableMock) and self.attribute):
1315                _kwargs['name'] = self.attribute
1316
1317            _kwargs.update(kwargs)
1318            new = Klass(**_kwargs)
1319
1320            if inherit and _is_instance_mock(new):
1321                # we can only tell if the instance should be callable if the
1322                # spec is not a list
1323                this_spec = spec
1324                if spec_set is not None:
1325                    this_spec = spec_set
1326                if (not _is_list(this_spec) and not
1327                    _instance_callable(this_spec)):
1328                    Klass = NonCallableMagicMock
1329
1330                _kwargs.pop('name')
1331                new.return_value = Klass(_new_parent=new, _new_name='()',
1332                                         **_kwargs)
1333        elif autospec is not None:
1334            # spec is ignored, new *must* be default, spec_set is treated
1335            # as a boolean. Should we check spec is not None and that spec_set
1336            # is a bool?
1337            if new is not DEFAULT:
1338                raise TypeError(
1339                    "autospec creates the mock for you. Can't specify "
1340                    "autospec and new."
1341                )
1342            if original is DEFAULT:
1343                raise TypeError("Can't use 'autospec' with create=True")
1344            spec_set = bool(spec_set)
1345            if autospec is True:
1346                autospec = original
1347
1348            new = create_autospec(autospec, spec_set=spec_set,
1349                                  _name=self.attribute, **kwargs)
1350        elif kwargs:
1351            # can't set keyword args when we aren't creating the mock
1352            # XXXX If new is a Mock we could call new.configure_mock(**kwargs)
1353            raise TypeError("Can't pass kwargs to a mock we aren't creating")
1354
1355        new_attr = new
1356
1357        self.temp_original = original
1358        self.is_local = local
1359        setattr(self.target, self.attribute, new_attr)
1360        if self.attribute_name is not None:
1361            extra_args = {}
1362            if self.new is DEFAULT:
1363                extra_args[self.attribute_name] =  new
1364            for patching in self.additional_patchers:
1365                arg = patching.__enter__()
1366                if patching.new is DEFAULT:
1367                    extra_args.update(arg)
1368            return extra_args
1369
1370        return new
1371
1372
1373    def __exit__(self, *exc_info):
1374        """Undo the patch."""
1375        if not _is_started(self):
1376            raise RuntimeError('stop called on unstarted patcher')
1377
1378        if self.is_local and self.temp_original is not DEFAULT:
1379            setattr(self.target, self.attribute, self.temp_original)
1380        else:
1381            delattr(self.target, self.attribute)
1382            if not self.create and not hasattr(self.target, self.attribute):
1383                # needed for proxy objects like django settings
1384                setattr(self.target, self.attribute, self.temp_original)
1385
1386        del self.temp_original
1387        del self.is_local
1388        del self.target
1389        for patcher in reversed(self.additional_patchers):
1390            if _is_started(patcher):
1391                patcher.__exit__(*exc_info)
1392
1393
1394    def start(self):
1395        """Activate a patch, returning any created mock."""
1396        result = self.__enter__()
1397        self._active_patches.add(self)
1398        return result
1399
1400
1401    def stop(self):
1402        """Stop an active patch."""
1403        self._active_patches.discard(self)
1404        return self.__exit__()
1405
1406
1407
1408def _get_target(target):
1409    try:
1410        target, attribute = target.rsplit('.', 1)
1411    except (TypeError, ValueError):
1412        raise TypeError("Need a valid target to patch. You supplied: %r" %
1413                        (target,))
1414    getter = lambda: _importer(target)
1415    return getter, attribute
1416
1417
1418def _patch_object(
1419        target, attribute, new=DEFAULT, spec=None,
1420        create=False, spec_set=None, autospec=None,
1421        new_callable=None, **kwargs
1422    ):
1423    """
1424    patch.object(target, attribute, new=DEFAULT, spec=None, create=False,
1425                 spec_set=None, autospec=None, new_callable=None, **kwargs)
1426
1427    patch the named member (`attribute`) on an object (`target`) with a mock
1428    object.
1429
1430    `patch.object` can be used as a decorator, class decorator or a context
1431    manager. Arguments `new`, `spec`, `create`, `spec_set`,
1432    `autospec` and `new_callable` have the same meaning as for `patch`. Like
1433    `patch`, `patch.object` takes arbitrary keyword arguments for configuring
1434    the mock object it creates.
1435
1436    When used as a class decorator `patch.object` honours `patch.TEST_PREFIX`
1437    for choosing which methods to wrap.
1438    """
1439    getter = lambda: target
1440    return _patch(
1441        getter, attribute, new, spec, create,
1442        spec_set, autospec, new_callable, kwargs
1443    )
1444
1445
1446def _patch_multiple(target, spec=None, create=False, spec_set=None,
1447                    autospec=None, new_callable=None, **kwargs):
1448    """Perform multiple patches in a single call. It takes the object to be
1449    patched (either as an object or a string to fetch the object by importing)
1450    and keyword arguments for the patches::
1451
1452        with patch.multiple(settings, FIRST_PATCH='one', SECOND_PATCH='two'):
1453            ...
1454
1455    Use `DEFAULT` as the value if you want `patch.multiple` to create
1456    mocks for you. In this case the created mocks are passed into a decorated
1457    function by keyword, and a dictionary is returned when `patch.multiple` is
1458    used as a context manager.
1459
1460    `patch.multiple` can be used as a decorator, class decorator or a context
1461    manager. The arguments `spec`, `spec_set`, `create`,
1462    `autospec` and `new_callable` have the same meaning as for `patch`. These
1463    arguments will be applied to *all* patches done by `patch.multiple`.
1464
1465    When used as a class decorator `patch.multiple` honours `patch.TEST_PREFIX`
1466    for choosing which methods to wrap.
1467    """
1468    if type(target) in (unicode, str):
1469        getter = lambda: _importer(target)
1470    else:
1471        getter = lambda: target
1472
1473    if not kwargs:
1474        raise ValueError(
1475            'Must supply at least one keyword argument with patch.multiple'
1476        )
1477    # need to wrap in a list for python 3, where items is a view
1478    items = list(kwargs.items())
1479    attribute, new = items[0]
1480    patcher = _patch(
1481        getter, attribute, new, spec, create, spec_set,
1482        autospec, new_callable, {}
1483    )
1484    patcher.attribute_name = attribute
1485    for attribute, new in items[1:]:
1486        this_patcher = _patch(
1487            getter, attribute, new, spec, create, spec_set,
1488            autospec, new_callable, {}
1489        )
1490        this_patcher.attribute_name = attribute
1491        patcher.additional_patchers.append(this_patcher)
1492    return patcher
1493
1494
1495def patch(
1496        target, new=DEFAULT, spec=None, create=False,
1497        spec_set=None, autospec=None, new_callable=None, **kwargs
1498    ):
1499    """
1500    `patch` acts as a function decorator, class decorator or a context
1501    manager. Inside the body of the function or with statement, the `target`
1502    is patched with a `new` object. When the function/with statement exits
1503    the patch is undone.
1504
1505    If `new` is omitted, then the target is replaced with a
1506    `MagicMock`. If `patch` is used as a decorator and `new` is
1507    omitted, the created mock is passed in as an extra argument to the
1508    decorated function. If `patch` is used as a context manager the created
1509    mock is returned by the context manager.
1510
1511    `target` should be a string in the form `'package.module.ClassName'`. The
1512    `target` is imported and the specified object replaced with the `new`
1513    object, so the `target` must be importable from the environment you are
1514    calling `patch` from. The target is imported when the decorated function
1515    is executed, not at decoration time.
1516
1517    The `spec` and `spec_set` keyword arguments are passed to the `MagicMock`
1518    if patch is creating one for you.
1519
1520    In addition you can pass `spec=True` or `spec_set=True`, which causes
1521    patch to pass in the object being mocked as the spec/spec_set object.
1522
1523    `new_callable` allows you to specify a different class, or callable object,
1524    that will be called to create the `new` object. By default `MagicMock` is
1525    used.
1526
1527    A more powerful form of `spec` is `autospec`. If you set `autospec=True`
1528    then the mock with be created with a spec from the object being replaced.
1529    All attributes of the mock will also have the spec of the corresponding
1530    attribute of the object being replaced. Methods and functions being
1531    mocked will have their arguments checked and will raise a `TypeError` if
1532    they are called with the wrong signature. For mocks replacing a class,
1533    their return value (the 'instance') will have the same spec as the class.
1534
1535    Instead of `autospec=True` you can pass `autospec=some_object` to use an
1536    arbitrary object as the spec instead of the one being replaced.
1537
1538    By default `patch` will fail to replace attributes that don't exist. If
1539    you pass in `create=True`, and the attribute doesn't exist, patch will
1540    create the attribute for you when the patched function is called, and
1541    delete it again afterwards. This is useful for writing tests against
1542    attributes that your production code creates at runtime. It is off by by
1543    default because it can be dangerous. With it switched on you can write
1544    passing tests against APIs that don't actually exist!
1545
1546    Patch can be used as a `TestCase` class decorator. It works by
1547    decorating each test method in the class. This reduces the boilerplate
1548    code when your test methods share a common patchings set. `patch` finds
1549    tests by looking for method names that start with `patch.TEST_PREFIX`.
1550    By default this is `test`, which matches the way `unittest` finds tests.
1551    You can specify an alternative prefix by setting `patch.TEST_PREFIX`.
1552
1553    Patch can be used as a context manager, with the with statement. Here the
1554    patching applies to the indented block after the with statement. If you
1555    use "as" then the patched object will be bound to the name after the
1556    "as"; very useful if `patch` is creating a mock object for you.
1557
1558    `patch` takes arbitrary keyword arguments. These will be passed to
1559    the `Mock` (or `new_callable`) on construction.
1560
1561    `patch.dict(...)`, `patch.multiple(...)` and `patch.object(...)` are
1562    available for alternate use-cases.
1563    """
1564    getter, attribute = _get_target(target)
1565    return _patch(
1566        getter, attribute, new, spec, create,
1567        spec_set, autospec, new_callable, kwargs
1568    )
1569
1570
1571class _patch_dict(object):
1572    """
1573    Patch a dictionary, or dictionary like object, and restore the dictionary
1574    to its original state after the test.
1575
1576    `in_dict` can be a dictionary or a mapping like container. If it is a
1577    mapping then it must at least support getting, setting and deleting items
1578    plus iterating over keys.
1579
1580    `in_dict` can also be a string specifying the name of the dictionary, which
1581    will then be fetched by importing it.
1582
1583    `values` can be a dictionary of values to set in the dictionary. `values`
1584    can also be an iterable of `(key, value)` pairs.
1585
1586    If `clear` is True then the dictionary will be cleared before the new
1587    values are set.
1588
1589    `patch.dict` can also be called with arbitrary keyword arguments to set
1590    values in the dictionary::
1591
1592        with patch.dict('sys.modules', mymodule=Mock(), other_module=Mock()):
1593            ...
1594
1595    `patch.dict` can be used as a context manager, decorator or class
1596    decorator. When used as a class decorator `patch.dict` honours
1597    `patch.TEST_PREFIX` for choosing which methods to wrap.
1598    """
1599
1600    def __init__(self, in_dict, values=(), clear=False, **kwargs):
1601        if isinstance(in_dict, basestring):
1602            in_dict = _importer(in_dict)
1603        self.in_dict = in_dict
1604        # support any argument supported by dict(...) constructor
1605        self.values = dict(values)
1606        self.values.update(kwargs)
1607        self.clear = clear
1608        self._original = None
1609
1610
1611    def __call__(self, f):
1612        if isinstance(f, ClassTypes):
1613            return self.decorate_class(f)
1614        @wraps(f)
1615        def _inner(*args, **kw):
1616            self._patch_dict()
1617            try:
1618                return f(*args, **kw)
1619            finally:
1620                self._unpatch_dict()
1621
1622        return _inner
1623
1624
1625    def decorate_class(self, klass):
1626        for attr in dir(klass):
1627            attr_value = getattr(klass, attr)
1628            if (attr.startswith(patch.TEST_PREFIX) and
1629                 hasattr(attr_value, "__call__")):
1630                decorator = _patch_dict(self.in_dict, self.values, self.clear)
1631                decorated = decorator(attr_value)
1632                setattr(klass, attr, decorated)
1633        return klass
1634
1635
1636    def __enter__(self):
1637        """Patch the dict."""
1638        self._patch_dict()
1639
1640
1641    def _patch_dict(self):
1642        values = self.values
1643        in_dict = self.in_dict
1644        clear = self.clear
1645
1646        try:
1647            original = in_dict.copy()
1648        except AttributeError:
1649            # dict like object with no copy method
1650            # must support iteration over keys
1651            original = {}
1652            for key in in_dict:
1653                original[key] = in_dict[key]
1654        self._original = original
1655
1656        if clear:
1657            _clear_dict(in_dict)
1658
1659        try:
1660            in_dict.update(values)
1661        except AttributeError:
1662            # dict like object with no update method
1663            for key in values:
1664                in_dict[key] = values[key]
1665
1666
1667    def _unpatch_dict(self):
1668        in_dict = self.in_dict
1669        original = self._original
1670
1671        _clear_dict(in_dict)
1672
1673        try:
1674            in_dict.update(original)
1675        except AttributeError:
1676            for key in original:
1677                in_dict[key] = original[key]
1678
1679
1680    def __exit__(self, *args):
1681        """Unpatch the dict."""
1682        self._unpatch_dict()
1683        return False
1684
1685    start = __enter__
1686    stop = __exit__
1687
1688
1689def _clear_dict(in_dict):
1690    try:
1691        in_dict.clear()
1692    except AttributeError:
1693        keys = list(in_dict)
1694        for key in keys:
1695            del in_dict[key]
1696
1697
1698def _patch_stopall():
1699    """Stop all active patches."""
1700    for patch in list(_patch._active_patches):
1701        patch.stop()
1702
1703
1704patch.object = _patch_object
1705patch.dict = _patch_dict
1706patch.multiple = _patch_multiple
1707patch.stopall = _patch_stopall
1708patch.TEST_PREFIX = 'test'
1709
1710magic_methods = (
1711    "lt le gt ge eq ne "
1712    "getitem setitem delitem "
1713    "len contains iter "
1714    "hash str sizeof "
1715    "enter exit "
1716    "divmod neg pos abs invert "
1717    "complex int float index "
1718    "trunc floor ceil "
1719)
1720
1721numerics = "add sub mul div floordiv mod lshift rshift and xor or pow "
1722inplace = ' '.join('i%s' % n for n in numerics.split())
1723right = ' '.join('r%s' % n for n in numerics.split())
1724extra = ''
1725if inPy3k:
1726    extra = 'bool next '
1727else:
1728    extra = 'unicode long nonzero oct hex truediv rtruediv '
1729
1730# not including __prepare__, __instancecheck__, __subclasscheck__
1731# (as they are metaclass methods)
1732# __del__ is not supported at all as it causes problems if it exists
1733
1734_non_defaults = set('__%s__' % method for method in [
1735    'cmp', 'getslice', 'setslice', 'coerce', 'subclasses',
1736    'format', 'get', 'set', 'delete', 'reversed',
1737    'missing', 'reduce', 'reduce_ex', 'getinitargs',
1738    'getnewargs', 'getstate', 'setstate', 'getformat',
1739    'setformat', 'repr', 'dir'
1740])
1741
1742
1743def _get_method(name, func):
1744    "Turns a callable object (like a mock) into a real function"
1745    def method(self, *args, **kw):
1746        return func(self, *args, **kw)
1747    method.__name__ = name
1748    return method
1749
1750
1751_magics = set(
1752    '__%s__' % method for method in
1753    ' '.join([magic_methods, numerics, inplace, right, extra]).split()
1754)
1755
1756_all_magics = _magics | _non_defaults
1757
1758_unsupported_magics = set([
1759    '__getattr__', '__setattr__',
1760    '__init__', '__new__', '__prepare__'
1761    '__instancecheck__', '__subclasscheck__',
1762    '__del__'
1763])
1764
1765_calculate_return_value = {
1766    '__hash__': lambda self: object.__hash__(self),
1767    '__str__': lambda self: object.__str__(self),
1768    '__sizeof__': lambda self: object.__sizeof__(self),
1769    '__unicode__': lambda self: unicode(object.__str__(self)),
1770}
1771
1772_return_values = {
1773    '__lt__': NotImplemented,
1774    '__gt__': NotImplemented,
1775    '__le__': NotImplemented,
1776    '__ge__': NotImplemented,
1777    '__int__': 1,
1778    '__contains__': False,
1779    '__len__': 0,
1780    '__exit__': False,
1781    '__complex__': 1j,
1782    '__float__': 1.0,
1783    '__bool__': True,
1784    '__nonzero__': True,
1785    '__oct__': '1',
1786    '__hex__': '0x1',
1787    '__long__': long(1),
1788    '__index__': 1,
1789}
1790
1791
1792def _get_eq(self):
1793    def __eq__(other):
1794        ret_val = self.__eq__._mock_return_value
1795        if ret_val is not DEFAULT:
1796            return ret_val
1797        return self is other
1798    return __eq__
1799
1800def _get_ne(self):
1801    def __ne__(other):
1802        if self.__ne__._mock_return_value is not DEFAULT:
1803            return DEFAULT
1804        return self is not other
1805    return __ne__
1806
1807def _get_iter(self):
1808    def __iter__():
1809        ret_val = self.__iter__._mock_return_value
1810        if ret_val is DEFAULT:
1811            return iter([])
1812        # if ret_val was already an iterator, then calling iter on it should
1813        # return the iterator unchanged
1814        return iter(ret_val)
1815    return __iter__
1816
1817_side_effect_methods = {
1818    '__eq__': _get_eq,
1819    '__ne__': _get_ne,
1820    '__iter__': _get_iter,
1821}
1822
1823
1824
1825def _set_return_value(mock, method, name):
1826    fixed = _return_values.get(name, DEFAULT)
1827    if fixed is not DEFAULT:
1828        method.return_value = fixed
1829        return
1830
1831    return_calulator = _calculate_return_value.get(name)
1832    if return_calulator is not None:
1833        try:
1834            return_value = return_calulator(mock)
1835        except AttributeError:
1836            # XXXX why do we return AttributeError here?
1837            #      set it as a side_effect instead?
1838            return_value = AttributeError(name)
1839        method.return_value = return_value
1840        return
1841
1842    side_effector = _side_effect_methods.get(name)
1843    if side_effector is not None:
1844        method.side_effect = side_effector(mock)
1845
1846
1847
1848class MagicMixin(object):
1849    def __init__(self, *args, **kw):
1850        _super(MagicMixin, self).__init__(*args, **kw)
1851        self._mock_set_magics()
1852
1853
1854    def _mock_set_magics(self):
1855        these_magics = _magics
1856
1857        if self._mock_methods is not None:
1858            these_magics = _magics.intersection(self._mock_methods)
1859
1860            remove_magics = set()
1861            remove_magics = _magics - these_magics
1862
1863            for entry in remove_magics:
1864                if entry in type(self).__dict__:
1865                    # remove unneeded magic methods
1866                    delattr(self, entry)
1867
1868        # don't overwrite existing attributes if called a second time
1869        these_magics = these_magics - set(type(self).__dict__)
1870
1871        _type = type(self)
1872        for entry in these_magics:
1873            setattr(_type, entry, MagicProxy(entry, self))
1874
1875
1876
1877class NonCallableMagicMock(MagicMixin, NonCallableMock):
1878    """A version of `MagicMock` that isn't callable."""
1879    def mock_add_spec(self, spec, spec_set=False):
1880        """Add a spec to a mock. `spec` can either be an object or a
1881        list of strings. Only attributes on the `spec` can be fetched as
1882        attributes from the mock.
1883
1884        If `spec_set` is True then only attributes on the spec can be set."""
1885        self._mock_add_spec(spec, spec_set)
1886        self._mock_set_magics()
1887
1888
1889
1890class MagicMock(MagicMixin, Mock):
1891    """
1892    MagicMock is a subclass of Mock with default implementations
1893    of most of the magic methods. You can use MagicMock without having to
1894    configure the magic methods yourself.
1895
1896    If you use the `spec` or `spec_set` arguments then *only* magic
1897    methods that exist in the spec will be created.
1898
1899    Attributes and the return value of a `MagicMock` will also be `MagicMocks`.
1900    """
1901    def mock_add_spec(self, spec, spec_set=False):
1902        """Add a spec to a mock. `spec` can either be an object or a
1903        list of strings. Only attributes on the `spec` can be fetched as
1904        attributes from the mock.
1905
1906        If `spec_set` is True then only attributes on the spec can be set."""
1907        self._mock_add_spec(spec, spec_set)
1908        self._mock_set_magics()
1909
1910
1911
1912class MagicProxy(object):
1913    def __init__(self, name, parent):
1914        self.name = name
1915        self.parent = parent
1916
1917    def __call__(self, *args, **kwargs):
1918        m = self.create_mock()
1919        return m(*args, **kwargs)
1920
1921    def create_mock(self):
1922        entry = self.name
1923        parent = self.parent
1924        m = parent._get_child_mock(name=entry, _new_name=entry,
1925                                   _new_parent=parent)
1926        setattr(parent, entry, m)
1927        _set_return_value(parent, m, entry)
1928        return m
1929
1930    def __get__(self, obj, _type=None):
1931        return self.create_mock()
1932
1933
1934
1935class _ANY(object):
1936    "A helper object that compares equal to everything."
1937
1938    def __eq__(self, other):
1939        return True
1940
1941    def __ne__(self, other):
1942        return False
1943
1944    def __repr__(self):
1945        return '<ANY>'
1946
1947ANY = _ANY()
1948
1949
1950
1951def _format_call_signature(name, args, kwargs):
1952    message = '%s(%%s)' % name
1953    formatted_args = ''
1954    args_string = ', '.join([repr(arg) for arg in args])
1955    kwargs_string = ', '.join([
1956        '%s=%r' % (key, value) for key, value in kwargs.items()
1957    ])
1958    if args_string:
1959        formatted_args = args_string
1960    if kwargs_string:
1961        if formatted_args:
1962            formatted_args += ', '
1963        formatted_args += kwargs_string
1964
1965    return message % formatted_args
1966
1967
1968
1969class _Call(tuple):
1970    """
1971    A tuple for holding the results of a call to a mock, either in the form
1972    `(args, kwargs)` or `(name, args, kwargs)`.
1973
1974    If args or kwargs are empty then a call tuple will compare equal to
1975    a tuple without those values. This makes comparisons less verbose::
1976
1977        _Call(('name', (), {})) == ('name',)
1978        _Call(('name', (1,), {})) == ('name', (1,))
1979        _Call(((), {'a': 'b'})) == ({'a': 'b'},)
1980
1981    The `_Call` object provides a useful shortcut for comparing with call::
1982
1983        _Call(((1, 2), {'a': 3})) == call(1, 2, a=3)
1984        _Call(('foo', (1, 2), {'a': 3})) == call.foo(1, 2, a=3)
1985
1986    If the _Call has no name then it will match any name.
1987    """
1988    def __new__(cls, value=(), name=None, parent=None, two=False,
1989                from_kall=True):
1990        name = ''
1991        args = ()
1992        kwargs = {}
1993        _len = len(value)
1994        if _len == 3:
1995            name, args, kwargs = value
1996        elif _len == 2:
1997            first, second = value
1998            if isinstance(first, basestring):
1999                name = first
2000                if isinstance(second, tuple):
2001                    args = second
2002                else:
2003                    kwargs = second
2004            else:
2005                args, kwargs = first, second
2006        elif _len == 1:
2007            value, = value
2008            if isinstance(value, basestring):
2009                name = value
2010            elif isinstance(value, tuple):
2011                args = value
2012            else:
2013                kwargs = value
2014
2015        if two:
2016            return tuple.__new__(cls, (args, kwargs))
2017
2018        return tuple.__new__(cls, (name, args, kwargs))
2019
2020
2021    def __init__(self, value=(), name=None, parent=None, two=False,
2022                 from_kall=True):
2023        self.name = name
2024        self.parent = parent
2025        self.from_kall = from_kall
2026
2027
2028    def __eq__(self, other):
2029        if other is ANY:
2030            return True
2031        try:
2032            len_other = len(other)
2033        except TypeError:
2034            return False
2035
2036        self_name = ''
2037        if len(self) == 2:
2038            self_args, self_kwargs = self
2039        else:
2040            self_name, self_args, self_kwargs = self
2041
2042        other_name = ''
2043        if len_other == 0:
2044            other_args, other_kwargs = (), {}
2045        elif len_other == 3:
2046            other_name, other_args, other_kwargs = other
2047        elif len_other == 1:
2048            value, = other
2049            if isinstance(value, tuple):
2050                other_args = value
2051                other_kwargs = {}
2052            elif isinstance(value, basestring):
2053                other_name = value
2054                other_args, other_kwargs = (), {}
2055            else:
2056                other_args = ()
2057                other_kwargs = value
2058        else:
2059            # len 2
2060            # could be (name, args) or (name, kwargs) or (args, kwargs)
2061            first, second = other
2062            if isinstance(first, basestring):
2063                other_name = first
2064                if isinstance(second, tuple):
2065                    other_args, other_kwargs = second, {}
2066                else:
2067                    other_args, other_kwargs = (), second
2068            else:
2069                other_args, other_kwargs = first, second
2070
2071        if self_name and other_name != self_name:
2072            return False
2073
2074        # this order is important for ANY to work!
2075        return (other_args, other_kwargs) == (self_args, self_kwargs)
2076
2077
2078    def __ne__(self, other):
2079        return not self.__eq__(other)
2080
2081
2082    def __call__(self, *args, **kwargs):
2083        if self.name is None:
2084            return _Call(('', args, kwargs), name='()')
2085
2086        name = self.name + '()'
2087        return _Call((self.name, args, kwargs), name=name, parent=self)
2088
2089
2090    def __getattr__(self, attr):
2091        if self.name is None:
2092            return _Call(name=attr, from_kall=False)
2093        name = '%s.%s' % (self.name, attr)
2094        return _Call(name=name, parent=self, from_kall=False)
2095
2096
2097    def __repr__(self):
2098        if not self.from_kall:
2099            name = self.name or 'call'
2100            if name.startswith('()'):
2101                name = 'call%s' % name
2102            return name
2103
2104        if len(self) == 2:
2105            name = 'call'
2106            args, kwargs = self
2107        else:
2108            name, args, kwargs = self
2109            if not name:
2110                name = 'call'
2111            elif not name.startswith('()'):
2112                name = 'call.%s' % name
2113            else:
2114                name = 'call%s' % name
2115        return _format_call_signature(name, args, kwargs)
2116
2117
2118    def call_list(self):
2119        """For a call object that represents multiple calls, `call_list`
2120        returns a list of all the intermediate calls as well as the
2121        final call."""
2122        vals = []
2123        thing = self
2124        while thing is not None:
2125            if thing.from_kall:
2126                vals.append(thing)
2127            thing = thing.parent
2128        return _CallList(reversed(vals))
2129
2130
2131call = _Call(from_kall=False)
2132
2133
2134
2135def create_autospec(spec, spec_set=False, instance=False, _parent=None,
2136                    _name=None, **kwargs):
2137    """Create a mock object using another object as a spec. Attributes on the
2138    mock will use the corresponding attribute on the `spec` object as their
2139    spec.
2140
2141    Functions or methods being mocked will have their arguments checked
2142    to check that they are called with the correct signature.
2143
2144    If `spec_set` is True then attempting to set attributes that don't exist
2145    on the spec object will raise an `AttributeError`.
2146
2147    If a class is used as a spec then the return value of the mock (the
2148    instance of the class) will have the same spec. You can use a class as the
2149    spec for an instance object by passing `instance=True`. The returned mock
2150    will only be callable if instances of the mock are callable.
2151
2152    `create_autospec` also takes arbitrary keyword arguments that are passed to
2153    the constructor of the created mock."""
2154    if _is_list(spec):
2155        # can't pass a list instance to the mock constructor as it will be
2156        # interpreted as a list of strings
2157        spec = type(spec)
2158
2159    is_type = isinstance(spec, ClassTypes)
2160
2161    _kwargs = {'spec': spec}
2162    if spec_set:
2163        _kwargs = {'spec_set': spec}
2164    elif spec is None:
2165        # None we mock with a normal mock without a spec
2166        _kwargs = {}
2167
2168    _kwargs.update(kwargs)
2169
2170    Klass = MagicMock
2171    if type(spec) in DescriptorTypes:
2172        # descriptors don't have a spec
2173        # because we don't know what type they return
2174        _kwargs = {}
2175    elif not _callable(spec):
2176        Klass = NonCallableMagicMock
2177    elif is_type and instance and not _instance_callable(spec):
2178        Klass = NonCallableMagicMock
2179
2180    _new_name = _name
2181    if _parent is None:
2182        # for a top level object no _new_name should be set
2183        _new_name = ''
2184
2185    mock = Klass(parent=_parent, _new_parent=_parent, _new_name=_new_name,
2186                 name=_name, **_kwargs)
2187
2188    if isinstance(spec, FunctionTypes):
2189        # should only happen at the top level because we don't
2190        # recurse for functions
2191        mock = _set_signature(mock, spec)
2192    else:
2193        _check_signature(spec, mock, is_type, instance)
2194
2195    if _parent is not None and not instance:
2196        _parent._mock_children[_name] = mock
2197
2198    if is_type and not instance and 'return_value' not in kwargs:
2199        mock.return_value = create_autospec(spec, spec_set, instance=True,
2200                                            _name='()', _parent=mock)
2201
2202    for entry in dir(spec):
2203        if _is_magic(entry):
2204            # MagicMock already does the useful magic methods for us
2205            continue
2206
2207        if isinstance(spec, FunctionTypes) and entry in FunctionAttributes:
2208            # allow a mock to actually be a function
2209            continue
2210
2211        # XXXX do we need a better way of getting attributes without
2212        # triggering code execution (?) Probably not - we need the actual
2213        # object to mock it so we would rather trigger a property than mock
2214        # the property descriptor. Likewise we want to mock out dynamically
2215        # provided attributes.
2216        # XXXX what about attributes that raise exceptions other than
2217        # AttributeError on being fetched?
2218        # we could be resilient against it, or catch and propagate the
2219        # exception when the attribute is fetched from the mock
2220        try:
2221            original = getattr(spec, entry)
2222        except AttributeError:
2223            continue
2224
2225        kwargs = {'spec': original}
2226        if spec_set:
2227            kwargs = {'spec_set': original}
2228
2229        if not isinstance(original, FunctionTypes):
2230            new = _SpecState(original, spec_set, mock, entry, instance)
2231            mock._mock_children[entry] = new
2232        else:
2233            parent = mock
2234            if isinstance(spec, FunctionTypes):
2235                parent = mock.mock
2236
2237            new = MagicMock(parent=parent, name=entry, _new_name=entry,
2238                            _new_parent=parent, **kwargs)
2239            mock._mock_children[entry] = new
2240            skipfirst = _must_skip(spec, entry, is_type)
2241            _check_signature(original, new, skipfirst=skipfirst)
2242
2243        # so functions created with _set_signature become instance attributes,
2244        # *plus* their underlying mock exists in _mock_children of the parent
2245        # mock. Adding to _mock_children may be unnecessary where we are also
2246        # setting as an instance attribute?
2247        if isinstance(new, FunctionTypes):
2248            setattr(mock, entry, new)
2249
2250    return mock
2251
2252
2253def _must_skip(spec, entry, is_type):
2254    if not isinstance(spec, ClassTypes):
2255        if entry in getattr(spec, '__dict__', {}):
2256            # instance attribute - shouldn't skip
2257            return False
2258        spec = spec.__class__
2259    if not hasattr(spec, '__mro__'):
2260        # old style class: can't have descriptors anyway
2261        return is_type
2262
2263    for klass in spec.__mro__:
2264        result = klass.__dict__.get(entry, DEFAULT)
2265        if result is DEFAULT:
2266            continue
2267        if isinstance(result, (staticmethod, classmethod)):
2268            return False
2269        return is_type
2270
2271    # shouldn't get here unless function is a dynamically provided attribute
2272    # XXXX untested behaviour
2273    return is_type
2274
2275
2276def _get_class(obj):
2277    try:
2278        return obj.__class__
2279    except AttributeError:
2280        # in Python 2, _sre.SRE_Pattern objects have no __class__
2281        return type(obj)
2282
2283
2284class _SpecState(object):
2285
2286    def __init__(self, spec, spec_set=False, parent=None,
2287                 name=None, ids=None, instance=False):
2288        self.spec = spec
2289        self.ids = ids
2290        self.spec_set = spec_set
2291        self.parent = parent
2292        self.instance = instance
2293        self.name = name
2294
2295
2296FunctionTypes = (
2297    # python function
2298    type(create_autospec),
2299    # instance method
2300    type(ANY.__eq__),
2301    # unbound method
2302    type(_ANY.__eq__),
2303)
2304
2305FunctionAttributes = set([
2306    'func_closure',
2307    'func_code',
2308    'func_defaults',
2309    'func_dict',
2310    'func_doc',
2311    'func_globals',
2312    'func_name',
2313])
2314
2315
2316file_spec = None
2317
2318
2319def mock_open(mock=None, read_data=''):
2320    """
2321    A helper function to create a mock to replace the use of `open`. It works
2322    for `open` called directly or used as a context manager.
2323
2324    The `mock` argument is the mock object to configure. If `None` (the
2325    default) then a `MagicMock` will be created for you, with the API limited
2326    to methods or attributes available on standard file handles.
2327
2328    `read_data` is a string for the `read` method of the file handle to return.
2329    This is an empty string by default.
2330    """
2331    global file_spec
2332    if file_spec is None:
2333        # set on first use
2334        if inPy3k:
2335            import _io
2336            file_spec = list(set(dir(_io.TextIOWrapper)).union(set(dir(_io.BytesIO))))
2337        else:
2338            file_spec = file
2339
2340    if mock is None:
2341        mock = MagicMock(name='open', spec=open)
2342
2343    handle = MagicMock(spec=file_spec)
2344    handle.write.return_value = None
2345    handle.__enter__.return_value = handle
2346    handle.read.return_value = read_data
2347
2348    mock.return_value = handle
2349    return mock
2350
2351
2352class PropertyMock(Mock):
2353    """
2354    A mock intended to be used as a property, or other descriptor, on a class.
2355    `PropertyMock` provides `__get__` and `__set__` methods so you can specify
2356    a return value when it is fetched.
2357
2358    Fetching a `PropertyMock` instance from an object calls the mock, with
2359    no args. Setting it calls the mock with the value being set.
2360    """
2361    def _get_child_mock(self, **kwargs):
2362        return MagicMock(**kwargs)
2363
2364    def __get__(self, obj, obj_type):
2365        return self()
2366    def __set__(self, obj, val):
2367        self(val)
2368