incubator-ambari-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From maha...@apache.org
Subject svn commit: r1435472 [3/3] - in /incubator/ambari/trunk: ./ ambari-common/src/test/python/mock/docs/ ambari-server/src/main/python/ ambari-server/src/test/python/
Date Sat, 19 Jan 2013 02:33:01 GMT
Added: incubator/ambari/trunk/ambari-common/src/test/python/mock/docs/magicmock.txt
URL: http://svn.apache.org/viewvc/incubator/ambari/trunk/ambari-common/src/test/python/mock/docs/magicmock.txt?rev=1435472&view=auto
==============================================================================
--- incubator/ambari/trunk/ambari-common/src/test/python/mock/docs/magicmock.txt (added)
+++ incubator/ambari/trunk/ambari-common/src/test/python/mock/docs/magicmock.txt Sat Jan 19 02:33:01 2013
@@ -0,0 +1,258 @@
+
+.. currentmodule:: mock
+
+
+.. _magic-methods:
+
+Mocking Magic Methods
+=====================
+
+.. currentmodule:: mock
+
+:class:`Mock` supports mocking `magic methods
+<http://www.ironpythoninaction.com/magic-methods.html>`_. This allows mock
+objects to replace containers or other objects that implement Python
+protocols.
+
+Because magic methods are looked up differently from normal methods [#]_, this
+support has been specially implemented. This means that only specific magic
+methods are supported. The supported list includes *almost* all of them. If
+there are any missing that you need please let us know!
+
+You mock magic methods by setting the method you are interested in to a function
+or a mock instance. If you are using a function then it *must* take ``self`` as
+the first argument [#]_.
+
+.. doctest::
+
+   >>> def __str__(self):
+   ...     return 'fooble'
+   ...
+   >>> mock = Mock()
+   >>> mock.__str__ = __str__
+   >>> str(mock)
+   'fooble'
+
+   >>> mock = Mock()
+   >>> mock.__str__ = Mock()
+   >>> mock.__str__.return_value = 'fooble'
+   >>> str(mock)
+   'fooble'
+
+   >>> mock = Mock()
+   >>> mock.__iter__ = Mock(return_value=iter([]))
+   >>> list(mock)
+   []
+
+One use case for this is for mocking objects used as context managers in a
+`with` statement:
+
+.. doctest::
+
+   >>> mock = Mock()
+   >>> mock.__enter__ = Mock(return_value='foo')
+   >>> mock.__exit__ = Mock(return_value=False)
+   >>> with mock as m:
+   ...     assert m == 'foo'
+   ...
+   >>> mock.__enter__.assert_called_with()
+   >>> mock.__exit__.assert_called_with(None, None, None)
+
+Calls to magic methods do not appear in :attr:`~Mock.method_calls`, but they
+are recorded in :attr:`~Mock.mock_calls`.
+
+.. note::
+
+   If you use the `spec` keyword argument to create a mock then attempting to
+   set a magic method that isn't in the spec will raise an `AttributeError`.
+
+The full list of supported magic methods is:
+
+* ``__hash__``, ``__sizeof__``, ``__repr__`` and ``__str__``
+* ``__dir__``, ``__format__`` and ``__subclasses__``
+* ``__floor__``, ``__trunc__`` and ``__ceil__``
+* Comparisons: ``__cmp__``, ``__lt__``, ``__gt__``, ``__le__``, ``__ge__``,
+  ``__eq__`` and ``__ne__``
+* Container methods: ``__getitem__``, ``__setitem__``, ``__delitem__``,
+  ``__contains__``, ``__len__``, ``__iter__``, ``__getslice__``,
+  ``__setslice__``, ``__reversed__`` and ``__missing__``
+* Context manager: ``__enter__`` and ``__exit__``
+* Unary numeric methods: ``__neg__``, ``__pos__`` and ``__invert__``
+* The numeric methods (including right hand and in-place variants):
+  ``__add__``, ``__sub__``, ``__mul__``, ``__div__``,
+  ``__floordiv__``, ``__mod__``, ``__divmod__``, ``__lshift__``,
+  ``__rshift__``, ``__and__``, ``__xor__``, ``__or__``, and ``__pow__``
+* Numeric conversion methods: ``__complex__``, ``__int__``, ``__float__``,
+  ``__index__`` and ``__coerce__``
+* Descriptor methods: ``__get__``, ``__set__`` and ``__delete__``
+* Pickling: ``__reduce__``, ``__reduce_ex__``, ``__getinitargs__``,
+  ``__getnewargs__``, ``__getstate__`` and ``__setstate__``
+
+
+The following methods are supported in Python 2 but don't exist in Python 3:
+
+* ``__unicode__``, ``__long__``, ``__oct__``, ``__hex__`` and ``__nonzero__``
+*  ``__truediv__`` and ``__rtruediv__``
+
+The following methods are supported in Python 3 but don't exist in Python 2:
+
+* ``__bool__`` and ``__next__``
+
+The following methods exist but are *not* supported as they are either in use by
+mock, can't be set dynamically, or can cause problems:
+
+* ``__getattr__``, ``__setattr__``, ``__init__`` and ``__new__``
+* ``__prepare__``, ``__instancecheck__``, ``__subclasscheck__``, ``__del__``
+
+
+
+Magic Mock
+==========
+
+There are two `MagicMock` variants: `MagicMock` and `NonCallableMagicMock`.
+
+
+.. class:: MagicMock(*args, **kw)
+
+   ``MagicMock`` is a subclass of :class:`Mock` with default implementations
+   of most of the magic methods. You can use ``MagicMock`` without having to
+   configure the magic methods yourself.
+
+   The constructor parameters have the same meaning as for :class:`Mock`.
+
+   If you use the `spec` or `spec_set` arguments then *only* magic methods
+   that exist in the spec will be created.
+
+
+.. class:: NonCallableMagicMock(*args, **kw)
+
+    A non-callable version of `MagicMock`.
+
+    The constructor parameters have the same meaning as for
+    :class:`MagicMock`, with the exception of `return_value` and
+    `side_effect` which have no meaning on a non-callable mock.
+
+The magic methods are setup with `MagicMock` objects, so you can configure them
+and use them in the usual way:
+
+.. doctest::
+
+   >>> mock = MagicMock()
+   >>> mock[3] = 'fish'
+   >>> mock.__setitem__.assert_called_with(3, 'fish')
+   >>> mock.__getitem__.return_value = 'result'
+   >>> mock[2]
+   'result'
+
+By default many of the protocol methods are required to return objects of a
+specific type. These methods are preconfigured with a default return value, so
+that they can be used without you having to do anything if you aren't interested
+in the return value. You can still *set* the return value manually if you want
+to change the default.
+
+Methods and their defaults:
+
+* ``__lt__``: NotImplemented
+* ``__gt__``: NotImplemented
+* ``__le__``: NotImplemented
+* ``__ge__``: NotImplemented
+* ``__int__`` : 1
+* ``__contains__`` : False
+* ``__len__`` : 1
+* ``__iter__`` : iter([])
+* ``__exit__`` : False
+* ``__complex__`` : 1j
+* ``__float__`` : 1.0
+* ``__bool__`` : True
+* ``__nonzero__`` : True
+* ``__oct__`` : '1'
+* ``__hex__`` : '0x1'
+* ``__long__`` : long(1)
+* ``__index__`` : 1
+* ``__hash__`` : default hash for the mock
+* ``__str__`` : default str for the mock
+* ``__unicode__`` : default unicode for the mock
+* ``__sizeof__``: default sizeof for the mock
+
+For example:
+
+.. doctest::
+
+   >>> mock = MagicMock()
+   >>> int(mock)
+   1
+   >>> len(mock)
+   0
+   >>> hex(mock)
+   '0x1'
+   >>> list(mock)
+   []
+   >>> object() in mock
+   False
+
+The two equality method, `__eq__` and `__ne__`, are special (changed in
+0.7.2). They do the default equality comparison on identity, using a side
+effect, unless you change their return value to return something else:
+
+.. doctest::
+
+   >>> MagicMock() == 3
+   False
+   >>> MagicMock() != 3
+   True
+   >>> mock = MagicMock()
+   >>> mock.__eq__.return_value = True
+   >>> mock == 3
+   True
+
+In `0.8` the `__iter__` also gained special handling implemented with a
+side effect. The return value of `MagicMock.__iter__` can be any iterable
+object and isn't required to be an iterator:
+
+.. doctest::
+
+   >>> mock = MagicMock()
+   >>> mock.__iter__.return_value = ['a', 'b', 'c']
+   >>> list(mock)
+   ['a', 'b', 'c']
+   >>> list(mock)
+   ['a', 'b', 'c']
+
+If the return value *is* an iterator, then iterating over it once will consume
+it and subsequent iterations will result in an empty list:
+
+.. doctest::
+
+   >>> mock.__iter__.return_value = iter(['a', 'b', 'c'])
+   >>> list(mock)
+   ['a', 'b', 'c']
+   >>> list(mock)
+   []
+
+``MagicMock`` has all of the supported magic methods configured except for some
+of the obscure and obsolete ones. You can still set these up if you want.
+
+Magic methods that are supported but not setup by default in ``MagicMock`` are:
+
+* ``__cmp__``
+* ``__getslice__`` and ``__setslice__``
+* ``__coerce__``
+* ``__subclasses__``
+* ``__dir__``
+* ``__format__``
+* ``__get__``, ``__set__`` and ``__delete__``
+* ``__reversed__`` and ``__missing__``
+* ``__reduce__``, ``__reduce_ex__``, ``__getinitargs__``, ``__getnewargs__``,
+  ``__getstate__`` and ``__setstate__``
+* ``__getformat__`` and ``__setformat__``
+
+
+
+------------
+
+.. [#] Magic methods *should* be looked up on the class rather than the
+   instance. Different versions of Python are inconsistent about applying this
+   rule. The supported protocol methods should work with all supported versions
+   of Python.
+.. [#] The function is basically hooked up to the class, but each ``Mock``
+   instance is kept isolated from the others.

Added: incubator/ambari/trunk/ambari-common/src/test/python/mock/docs/mock.txt
URL: http://svn.apache.org/viewvc/incubator/ambari/trunk/ambari-common/src/test/python/mock/docs/mock.txt?rev=1435472&view=auto
==============================================================================
--- incubator/ambari/trunk/ambari-common/src/test/python/mock/docs/mock.txt (added)
+++ incubator/ambari/trunk/ambari-common/src/test/python/mock/docs/mock.txt Sat Jan 19 02:33:01 2013
@@ -0,0 +1,842 @@
+The Mock Class
+==============
+
+.. currentmodule:: mock
+
+.. testsetup::
+
+    class SomeClass:
+        pass
+
+
+`Mock` is a flexible mock object intended to replace the use of stubs and
+test doubles throughout your code. Mocks are callable and create attributes as
+new mocks when you access them [#]_. Accessing the same attribute will always
+return the same mock. Mocks record how you use them, allowing you to make
+assertions about what your code has done to them.
+
+:class:`MagicMock` is a subclass of `Mock` with all the magic methods
+pre-created and ready to use. There are also non-callable variants, useful
+when you are mocking out objects that aren't callable:
+:class:`NonCallableMock` and :class:`NonCallableMagicMock`
+
+The :func:`patch` decorators makes it easy to temporarily replace classes
+in a particular module with a `Mock` object. By default `patch` will create
+a `MagicMock` for you. You can specify an alternative class of `Mock` using
+the `new_callable` argument to `patch`.
+
+
+.. index:: side_effect
+.. index:: return_value
+.. index:: wraps
+.. index:: name
+.. index:: spec
+
+.. class:: Mock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, **kwargs)
+
+    Create a new `Mock` object. `Mock` takes several optional arguments
+    that specify the behaviour of the Mock object:
+
+    * `spec`: This can be either a list of strings or an existing object (a
+      class or instance) that acts as the specification for the mock object. If
+      you pass in an object then a list of strings is formed by calling dir on
+      the object (excluding unsupported magic attributes and methods).
+      Accessing any attribute not in this list will raise an `AttributeError`.
+
+      If `spec` is an object (rather than a list of strings) then
+      :attr:`__class__` returns the class of the spec object. This allows mocks
+      to pass `isinstance` tests.
+
+    * `spec_set`: A stricter variant of `spec`. If used, attempting to *set*
+      or get an attribute on the mock that isn't on the object passed as
+      `spec_set` will raise an `AttributeError`.
+
+    * `side_effect`: A function to be called whenever the Mock is called. See
+      the :attr:`~Mock.side_effect` attribute. Useful for raising exceptions or
+      dynamically changing return values. The function is called with the same
+      arguments as the mock, and unless it returns :data:`DEFAULT`, the return
+      value of this function is used as the return value.
+
+      Alternatively `side_effect` can be an exception class or instance. In
+      this case the exception will be raised when the mock is called.
+
+      If `side_effect` is an iterable then each call to the mock will return
+      the next value from the iterable. If any of the members of the iterable
+      are exceptions they will be raised instead of returned.
+
+      A `side_effect` can be cleared by setting it to `None`.
+
+    * `return_value`: The value returned when the mock is called. By default
+      this is a new Mock (created on first access). See the
+      :attr:`return_value` attribute.
+
+    * `wraps`: Item for the mock object to wrap. If `wraps` is not None then
+      calling the Mock will pass the call through to the wrapped object
+      (returning the real result and ignoring `return_value`). Attribute access
+      on the mock will return a Mock object that wraps the corresponding
+      attribute of the wrapped object (so attempting to access an attribute
+      that doesn't exist will raise an `AttributeError`).
+
+      If the mock has an explicit `return_value` set then calls are not passed
+      to the wrapped object and the `return_value` is returned instead.
+
+    * `name`: If the mock has a name then it will be used in the repr of the
+      mock. This can be useful for debugging. The name is propagated to child
+      mocks.
+
+    Mocks can also be called with arbitrary keyword arguments. These will be
+    used to set attributes on the mock after it is created. See the
+    :meth:`configure_mock` method for details.
+
+
+    .. method:: assert_called_with(*args, **kwargs)
+
+        This method is a convenient way of asserting that calls are made in a
+        particular way:
+
+        .. doctest::
+
+            >>> mock = Mock()
+            >>> mock.method(1, 2, 3, test='wow')
+            <Mock name='mock.method()' id='...'>
+            >>> mock.method.assert_called_with(1, 2, 3, test='wow')
+
+
+    .. method:: assert_called_once_with(*args, **kwargs)
+
+       Assert that the mock was called exactly once and with the specified
+       arguments.
+
+       .. doctest::
+
+            >>> mock = Mock(return_value=None)
+            >>> mock('foo', bar='baz')
+            >>> mock.assert_called_once_with('foo', bar='baz')
+            >>> mock('foo', bar='baz')
+            >>> mock.assert_called_once_with('foo', bar='baz')
+            Traceback (most recent call last):
+              ...
+            AssertionError: Expected to be called once. Called 2 times.
+
+
+    .. method:: assert_any_call(*args, **kwargs)
+
+        assert the mock has been called with the specified arguments.
+
+        The assert passes if the mock has *ever* been called, unlike
+        :meth:`assert_called_with` and :meth:`assert_called_once_with` that
+        only pass if the call is the most recent one.
+
+        .. doctest::
+
+            >>> mock = Mock(return_value=None)
+            >>> mock(1, 2, arg='thing')
+            >>> mock('some', 'thing', 'else')
+            >>> mock.assert_any_call(1, 2, arg='thing')
+
+
+    .. method:: assert_has_calls(calls, any_order=False)
+
+        assert the mock has been called with the specified calls.
+        The `mock_calls` list is checked for the calls.
+
+        If `any_order` is False (the default) then the calls must be
+        sequential. There can be extra calls before or after the
+        specified calls.
+
+        If `any_order` is True then the calls can be in any order, but
+        they must all appear in :attr:`mock_calls`.
+
+        .. doctest::
+
+            >>> mock = Mock(return_value=None)
+            >>> mock(1)
+            >>> mock(2)
+            >>> mock(3)
+            >>> mock(4)
+            >>> calls = [call(2), call(3)]
+            >>> mock.assert_has_calls(calls)
+            >>> calls = [call(4), call(2), call(3)]
+            >>> mock.assert_has_calls(calls, any_order=True)
+
+
+    .. method:: reset_mock()
+
+        The reset_mock method resets all the call attributes on a mock object:
+
+        .. doctest::
+
+            >>> mock = Mock(return_value=None)
+            >>> mock('hello')
+            >>> mock.called
+            True
+            >>> mock.reset_mock()
+            >>> mock.called
+            False
+
+        This can be useful where you want to make a series of assertions that
+        reuse the same object. Note that `reset_mock` *doesn't* clear the
+        return value, :attr:`side_effect` or any child attributes you have
+        set using normal assignment. Child mocks and the return value mock
+        (if any) are reset as well.
+
+
+    .. method:: mock_add_spec(spec, spec_set=False)
+
+        Add a spec to a mock. `spec` can either be an object or a
+        list of strings. Only attributes on the `spec` can be fetched as
+        attributes from the mock.
+
+        If `spec_set` is `True` then only attributes on the spec can be set.
+
+
+    .. method:: attach_mock(mock, attribute)
+
+        Attach a mock as an attribute of this one, replacing its name and
+        parent. Calls to the attached mock will be recorded in the
+        :attr:`method_calls` and :attr:`mock_calls` attributes of this one.
+
+
+    .. method:: configure_mock(**kwargs)
+
+        Set attributes on the mock through keyword arguments.
+
+        Attributes plus return values and side effects can be set on child
+        mocks using standard dot notation and unpacking a dictionary in the
+        method call:
+
+        .. doctest::
+
+            >>> mock = Mock()
+            >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError}
+            >>> mock.configure_mock(**attrs)
+            >>> mock.method()
+            3
+            >>> mock.other()
+            Traceback (most recent call last):
+              ...
+            KeyError
+
+        The same thing can be achieved in the constructor call to mocks:
+
+        .. doctest::
+
+            >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError}
+            >>> mock = Mock(some_attribute='eggs', **attrs)
+            >>> mock.some_attribute
+            'eggs'
+            >>> mock.method()
+            3
+            >>> mock.other()
+            Traceback (most recent call last):
+              ...
+            KeyError
+
+        `configure_mock` exists to make it easier to do configuration
+        after the mock has been created.
+
+
+    .. method:: __dir__()
+
+        `Mock` objects limit the results of `dir(some_mock)` to useful results.
+        For mocks with a `spec` this includes all the permitted attributes
+        for the mock.
+
+        See :data:`FILTER_DIR` for what this filtering does, and how to
+        switch it off.
+
+
+    .. method:: _get_child_mock(**kw)
+
+        Create the child mocks for attributes and return value.
+        By default child mocks will be the same type as the parent.
+        Subclasses of Mock may want to override this to customize the way
+        child mocks are made.
+
+        For non-callable mocks the callable variant will be used (rather than
+        any custom subclass).
+
+
+    .. attribute:: called
+
+        A boolean representing whether or not the mock object has been called:
+
+        .. doctest::
+
+            >>> mock = Mock(return_value=None)
+            >>> mock.called
+            False
+            >>> mock()
+            >>> mock.called
+            True
+
+    .. attribute:: call_count
+
+        An integer telling you how many times the mock object has been called:
+
+        .. doctest::
+
+            >>> mock = Mock(return_value=None)
+            >>> mock.call_count
+            0
+            >>> mock()
+            >>> mock()
+            >>> mock.call_count
+            2
+
+
+    .. attribute:: return_value
+
+        Set this to configure the value returned by calling the mock:
+
+        .. doctest::
+
+            >>> mock = Mock()
+            >>> mock.return_value = 'fish'
+            >>> mock()
+            'fish'
+
+        The default return value is a mock object and you can configure it in
+        the normal way:
+
+        .. doctest::
+
+            >>> mock = Mock()
+            >>> mock.return_value.attribute = sentinel.Attribute
+            >>> mock.return_value()
+            <Mock name='mock()()' id='...'>
+            >>> mock.return_value.assert_called_with()
+
+        `return_value` can also be set in the constructor:
+
+        .. doctest::
+
+            >>> mock = Mock(return_value=3)
+            >>> mock.return_value
+            3
+            >>> mock()
+            3
+
+
+    .. attribute:: side_effect
+
+        This can either be a function to be called when the mock is called,
+        or an exception (class or instance) to be raised.
+
+        If you pass in a function it will be called with same arguments as the
+        mock and unless the function returns the :data:`DEFAULT` singleton the
+        call to the mock will then return whatever the function returns. If the
+        function returns :data:`DEFAULT` then the mock will return its normal
+        value (from the :attr:`return_value`.
+
+        An example of a mock that raises an exception (to test exception
+        handling of an API):
+
+        .. doctest::
+
+            >>> mock = Mock()
+            >>> mock.side_effect = Exception('Boom!')
+            >>> mock()
+            Traceback (most recent call last):
+              ...
+            Exception: Boom!
+
+        Using `side_effect` to return a sequence of values:
+
+        .. doctest::
+
+            >>> mock = Mock()
+            >>> mock.side_effect = [3, 2, 1]
+            >>> mock(), mock(), mock()
+            (3, 2, 1)
+
+        The `side_effect` function is called with the same arguments as the
+        mock (so it is wise for it to take arbitrary args and keyword
+        arguments) and whatever it returns is used as the return value for
+        the call. The exception is if `side_effect` returns :data:`DEFAULT`,
+        in which case the normal :attr:`return_value` is used.
+
+        .. doctest::
+
+            >>> mock = Mock(return_value=3)
+            >>> def side_effect(*args, **kwargs):
+            ...     return DEFAULT
+            ...
+            >>> mock.side_effect = side_effect
+            >>> mock()
+            3
+
+        `side_effect` can be set in the constructor. Here's an example that
+        adds one to the value the mock is called with and returns it:
+
+        .. doctest::
+
+            >>> side_effect = lambda value: value + 1
+            >>> mock = Mock(side_effect=side_effect)
+            >>> mock(3)
+            4
+            >>> mock(-8)
+            -7
+
+        Setting `side_effect` to `None` clears it:
+
+        .. doctest::
+
+            >>> from mock import Mock
+            >>> m = Mock(side_effect=KeyError, return_value=3)
+            >>> m()
+            Traceback (most recent call last):
+             ...
+            KeyError
+            >>> m.side_effect = None
+            >>> m()
+            3
+
+
+    .. attribute:: call_args
+
+        This is either `None` (if the mock hasn't been called), or the
+        arguments that the mock was last called with. This will be in the
+        form of a tuple: the first member is any ordered arguments the mock
+        was called with (or an empty tuple) and the second member is any
+        keyword arguments (or an empty dictionary).
+
+        .. doctest::
+
+            >>> mock = Mock(return_value=None)
+            >>> print mock.call_args
+            None
+            >>> mock()
+            >>> mock.call_args
+            call()
+            >>> mock.call_args == ()
+            True
+            >>> mock(3, 4)
+            >>> mock.call_args
+            call(3, 4)
+            >>> mock.call_args == ((3, 4),)
+            True
+            >>> mock(3, 4, 5, key='fish', next='w00t!')
+            >>> mock.call_args
+            call(3, 4, 5, key='fish', next='w00t!')
+
+        `call_args`, along with members of the lists :attr:`call_args_list`,
+        :attr:`method_calls` and :attr:`mock_calls` are :data:`call` objects.
+        These are tuples, so they can be unpacked to get at the individual
+        arguments and make more complex assertions. See
+        :ref:`calls as tuples <calls-as-tuples>`.
+
+
+    .. attribute:: call_args_list
+
+        This is a list of all the calls made to the mock object in sequence
+        (so the length of the list is the number of times it has been
+        called). Before any calls have been made it is an empty list. The
+        :data:`call` object can be used for conveniently constructing lists of
+        calls to compare with `call_args_list`.
+
+        .. doctest::
+
+            >>> mock = Mock(return_value=None)
+            >>> mock()
+            >>> mock(3, 4)
+            >>> mock(key='fish', next='w00t!')
+            >>> mock.call_args_list
+            [call(), call(3, 4), call(key='fish', next='w00t!')]
+            >>> expected = [(), ((3, 4),), ({'key': 'fish', 'next': 'w00t!'},)]
+            >>> mock.call_args_list == expected
+            True
+
+        Members of `call_args_list` are :data:`call` objects. These can be
+        unpacked as tuples to get at the individual arguments. See
+        :ref:`calls as tuples <calls-as-tuples>`.
+
+
+    .. attribute:: method_calls
+
+        As well as tracking calls to themselves, mocks also track calls to
+        methods and attributes, and *their* methods and attributes:
+
+        .. doctest::
+
+            >>> mock = Mock()
+            >>> mock.method()
+            <Mock name='mock.method()' id='...'>
+            >>> mock.property.method.attribute()
+            <Mock name='mock.property.method.attribute()' id='...'>
+            >>> mock.method_calls
+            [call.method(), call.property.method.attribute()]
+
+        Members of `method_calls` are :data:`call` objects. These can be
+        unpacked as tuples to get at the individual arguments. See
+        :ref:`calls as tuples <calls-as-tuples>`.
+
+
+    .. attribute:: mock_calls
+
+        `mock_calls` records *all* calls to the mock object, its methods, magic
+        methods *and* return value mocks.
+
+        .. doctest::
+
+            >>> mock = MagicMock()
+            >>> result = mock(1, 2, 3)
+            >>> mock.first(a=3)
+            <MagicMock name='mock.first()' id='...'>
+            >>> mock.second()
+            <MagicMock name='mock.second()' id='...'>
+            >>> int(mock)
+            1
+            >>> result(1)
+            <MagicMock name='mock()()' id='...'>
+            >>> expected = [call(1, 2, 3), call.first(a=3), call.second(),
+            ... call.__int__(), call()(1)]
+            >>> mock.mock_calls == expected
+            True
+
+        Members of `mock_calls` are :data:`call` objects. These can be
+        unpacked as tuples to get at the individual arguments. See
+        :ref:`calls as tuples <calls-as-tuples>`.
+
+
+    .. attribute:: __class__
+
+        Normally the `__class__` attribute of an object will return its type.
+        For a mock object with a `spec` `__class__` returns the spec class
+        instead. This allows mock objects to pass `isinstance` tests for the
+        object they are replacing / masquerading as:
+
+        .. doctest::
+
+            >>> mock = Mock(spec=3)
+            >>> isinstance(mock, int)
+            True
+
+        `__class__` is assignable to, this allows a mock to pass an
+        `isinstance` check without forcing you to use a spec:
+
+        .. doctest::
+
+            >>> mock = Mock()
+            >>> mock.__class__ = dict
+            >>> isinstance(mock, dict)
+            True
+
+.. class:: NonCallableMock(spec=None, wraps=None, name=None, spec_set=None, **kwargs)
+
+    A non-callable version of `Mock`. The constructor parameters have the same
+    meaning of `Mock`, with the exception of `return_value` and `side_effect`
+    which have no meaning on a non-callable mock.
+
+Mock objects that use a class or an instance as a `spec` or `spec_set` are able
+to pass `isintance` tests:
+
+.. doctest::
+
+    >>> mock = Mock(spec=SomeClass)
+    >>> isinstance(mock, SomeClass)
+    True
+    >>> mock = Mock(spec_set=SomeClass())
+    >>> isinstance(mock, SomeClass)
+    True
+
+The `Mock` classes have support for mocking magic methods. See :ref:`magic
+methods <magic-methods>` for the full details.
+
+The mock classes and the :func:`patch` decorators all take arbitrary keyword
+arguments for configuration. For the `patch` decorators the keywords are
+passed to the constructor of the mock being created. The keyword arguments
+are for configuring attributes of the mock:
+
+.. doctest::
+
+        >>> m = MagicMock(attribute=3, other='fish')
+        >>> m.attribute
+        3
+        >>> m.other
+        'fish'
+
+The return value and side effect of child mocks can be set in the same way,
+using dotted notation. As you can't use dotted names directly in a call you
+have to create a dictionary and unpack it using `**`:
+
+.. doctest::
+
+    >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError}
+    >>> mock = Mock(some_attribute='eggs', **attrs)
+    >>> mock.some_attribute
+    'eggs'
+    >>> mock.method()
+    3
+    >>> mock.other()
+    Traceback (most recent call last):
+      ...
+    KeyError
+
+
+.. class:: PropertyMock(*args, **kwargs)
+
+   A mock intended to be used as a property, or other descriptor, on a class.
+   `PropertyMock` provides `__get__` and `__set__` methods so you can specify
+   a return value when it is fetched.
+
+   Fetching a `PropertyMock` instance from an object calls the mock, with
+   no args. Setting it calls the mock with the value being set.
+
+   .. doctest::
+
+        >>> class Foo(object):
+        ...     @property
+        ...     def foo(self):
+        ...         return 'something'
+        ...     @foo.setter
+        ...     def foo(self, value):
+        ...         pass
+        ...
+        >>> with patch('__main__.Foo.foo', new_callable=PropertyMock) as mock_foo:
+        ...     mock_foo.return_value = 'mockity-mock'
+        ...     this_foo = Foo()
+        ...     print this_foo.foo
+        ...     this_foo.foo = 6
+        ...
+        mockity-mock
+        >>> mock_foo.mock_calls
+        [call(), call(6)]
+
+Because of the way mock attributes are stored you can't directly attach a
+`PropertyMock` to a mock object. Instead you can attach it to the mock type
+object:
+
+.. doctest::
+
+    >>> m = MagicMock()
+    >>> p = PropertyMock(return_value=3)
+    >>> type(m).foo = p
+    >>> m.foo
+    3
+    >>> p.assert_called_once_with()
+
+
+.. index:: __call__
+.. index:: calling
+
+Calling
+=======
+
+Mock objects are callable. The call will return the value set as the
+:attr:`~Mock.return_value` attribute. The default return value is a new Mock
+object; it is created the first time the return value is accessed (either
+explicitly or by calling the Mock) - but it is stored and the same one
+returned each time.
+
+Calls made to the object will be recorded in the attributes
+like :attr:`~Mock.call_args` and :attr:`~Mock.call_args_list`.
+
+If :attr:`~Mock.side_effect` is set then it will be called after the call has
+been recorded, so if `side_effect` raises an exception the call is still
+recorded.
+
+The simplest way to make a mock raise an exception when called is to make
+:attr:`~Mock.side_effect` an exception class or instance:
+
+.. doctest::
+
+        >>> m = MagicMock(side_effect=IndexError)
+        >>> m(1, 2, 3)
+        Traceback (most recent call last):
+          ...
+        IndexError
+        >>> m.mock_calls
+        [call(1, 2, 3)]
+        >>> m.side_effect = KeyError('Bang!')
+        >>> m('two', 'three', 'four')
+        Traceback (most recent call last):
+          ...
+        KeyError: 'Bang!'
+        >>> m.mock_calls
+        [call(1, 2, 3), call('two', 'three', 'four')]
+
+If `side_effect` is a function then whatever that function returns is what
+calls to the mock return. The `side_effect` function is called with the
+same arguments as the mock. This allows you to vary the return value of the
+call dynamically, based on the input:
+
+.. doctest::
+
+        >>> def side_effect(value):
+        ...     return value + 1
+        ...
+        >>> m = MagicMock(side_effect=side_effect)
+        >>> m(1)
+        2
+        >>> m(2)
+        3
+        >>> m.mock_calls
+        [call(1), call(2)]
+
+If you want the mock to still return the default return value (a new mock), or
+any set return value, then there are two ways of doing this. Either return
+`mock.return_value` from inside `side_effect`, or return :data:`DEFAULT`:
+
+.. doctest::
+
+        >>> m = MagicMock()
+        >>> def side_effect(*args, **kwargs):
+        ...     return m.return_value
+        ...
+        >>> m.side_effect = side_effect
+        >>> m.return_value = 3
+        >>> m()
+        3
+        >>> def side_effect(*args, **kwargs):
+        ...     return DEFAULT
+        ...
+        >>> m.side_effect = side_effect
+        >>> m()
+        3
+
+To remove a `side_effect`, and return to the default behaviour, set the
+`side_effect` to `None`:
+
+.. doctest::
+
+        >>> m = MagicMock(return_value=6)
+        >>> def side_effect(*args, **kwargs):
+        ...     return 3
+        ...
+        >>> m.side_effect = side_effect
+        >>> m()
+        3
+        >>> m.side_effect = None
+        >>> m()
+        6
+
+The `side_effect` can also be any iterable object. Repeated calls to the mock
+will return values from the iterable (until the iterable is exhausted and
+a `StopIteration` is raised):
+
+.. doctest::
+
+        >>> m = MagicMock(side_effect=[1, 2, 3])
+        >>> m()
+        1
+        >>> m()
+        2
+        >>> m()
+        3
+        >>> m()
+        Traceback (most recent call last):
+          ...
+        StopIteration
+
+If any members of the iterable are exceptions they will be raised instead of
+returned:
+
+.. doctest::
+
+        >>> iterable = (33, ValueError, 66)
+        >>> m = MagicMock(side_effect=iterable)
+        >>> m()
+        33
+        >>> m()
+        Traceback (most recent call last):
+         ...
+        ValueError
+        >>> m()
+        66
+
+
+.. _deleting-attributes:
+
+Deleting Attributes
+===================
+
+Mock objects create attributes on demand. This allows them to pretend to be
+objects of any type.
+
+You may want a mock object to return `False` to a `hasattr` call, or raise an
+`AttributeError` when an attribute is fetched. You can do this by providing
+an object as a `spec` for a mock, but that isn't always convenient.
+
+You "block" attributes by deleting them. Once deleted, accessing an attribute
+will raise an `AttributeError`.
+
+.. doctest::
+
+    >>> mock = MagicMock()
+    >>> hasattr(mock, 'm')
+    True
+    >>> del mock.m
+    >>> hasattr(mock, 'm')
+    False
+    >>> del mock.f
+    >>> mock.f
+    Traceback (most recent call last):
+        ...
+    AttributeError: f
+
+
+Attaching Mocks as Attributes
+=============================
+
+When you attach a mock as an attribute of another mock (or as the return
+value) it becomes a "child" of that mock. Calls to the child are recorded in
+the :attr:`~Mock.method_calls` and :attr:`~Mock.mock_calls` attributes of the
+parent. This is useful for configuring child mocks and then attaching them to
+the parent, or for attaching mocks to a parent that records all calls to the
+children and allows you to make assertions about the order of calls between
+mocks:
+
+.. doctest::
+
+    >>> parent = MagicMock()
+    >>> child1 = MagicMock(return_value=None)
+    >>> child2 = MagicMock(return_value=None)
+    >>> parent.child1 = child1
+    >>> parent.child2 = child2
+    >>> child1(1)
+    >>> child2(2)
+    >>> parent.mock_calls
+    [call.child1(1), call.child2(2)]
+
+The exception to this is if the mock has a name. This allows you to prevent
+the "parenting" if for some reason you don't want it to happen.
+
+.. doctest::
+
+    >>> mock = MagicMock()
+    >>> not_a_child = MagicMock(name='not-a-child')
+    >>> mock.attribute = not_a_child
+    >>> mock.attribute()
+    <MagicMock name='not-a-child()' id='...'>
+    >>> mock.mock_calls
+    []
+
+Mocks created for you by :func:`patch` are automatically given names. To
+attach mocks that have names to a parent you use the :meth:`~Mock.attach_mock`
+method:
+
+.. doctest::
+
+    >>> thing1 = object()
+    >>> thing2 = object()
+    >>> parent = MagicMock()
+    >>> with patch('__main__.thing1', return_value=None) as child1:
+    ...     with patch('__main__.thing2', return_value=None) as child2:
+    ...         parent.attach_mock(child1, 'child1')
+    ...         parent.attach_mock(child2, 'child2')
+    ...         child1('one')
+    ...         child2('two')
+    ...
+    >>> parent.mock_calls
+    [call.child1('one'), call.child2('two')]
+
+
+-----
+
+.. [#] The only exceptions are magic methods and attributes (those that have
+       leading and trailing double underscores). Mock doesn't create these but
+       instead of raises an ``AttributeError``. This is because the interpreter
+       will often implicitly request these methods, and gets *very* confused to
+       get a new Mock object when it expects a magic method. If you need magic
+       method support see :ref:`magic methods <magic-methods>`.

Added: incubator/ambari/trunk/ambari-common/src/test/python/mock/docs/patch.txt
URL: http://svn.apache.org/viewvc/incubator/ambari/trunk/ambari-common/src/test/python/mock/docs/patch.txt?rev=1435472&view=auto
==============================================================================
--- incubator/ambari/trunk/ambari-common/src/test/python/mock/docs/patch.txt (added)
+++ incubator/ambari/trunk/ambari-common/src/test/python/mock/docs/patch.txt Sat Jan 19 02:33:01 2013
@@ -0,0 +1,636 @@
+==================
+ Patch Decorators
+==================
+
+
+.. currentmodule:: mock
+
+.. testsetup::
+
+    class SomeClass(object):
+        static_method = None
+        class_method = None
+        attribute = None
+
+    sys.modules['package'] = package = Mock(name='package')
+    sys.modules['package.module'] = package.module
+
+    class TestCase(unittest2.TestCase):
+        def run(self):
+            result = unittest2.TestResult()
+            super(unittest2.TestCase, self).run(result)
+            assert result.wasSuccessful()
+
+.. testcleanup::
+
+    patch.TEST_PREFIX = 'test'
+
+
+The patch decorators are used for patching objects only within the scope of
+the function they decorate. They automatically handle the unpatching for you,
+even if exceptions are raised. All of these functions can also be used in with
+statements or as class decorators.
+
+
+patch
+=====
+
+.. note::
+
+    `patch` is straightforward to use. The key is to do the patching in the
+    right namespace. See the section `where to patch`_.
+
+.. function:: patch(target, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)
+
+    `patch` acts as a function decorator, class decorator or a context
+    manager. Inside the body of the function or with statement, the `target`
+    is patched with a `new` object. When the function/with statement exits
+    the patch is undone.
+
+    If `new` is omitted, then the target is replaced with a
+    :class:`MagicMock`. If `patch` is used as a decorator and `new` is
+    omitted, the created mock is passed in as an extra argument to the
+    decorated function. If `patch` is used as a context manager the created
+    mock is returned by the context manager.
+
+    `target` should be a string in the form `'package.module.ClassName'`. The
+    `target` is imported and the specified object replaced with the `new`
+    object, so the `target` must be importable from the environment you are
+    calling `patch` from. The target is imported when the decorated function
+    is executed, not at decoration time.
+
+    The `spec` and `spec_set` keyword arguments are passed to the `MagicMock`
+    if patch is creating one for you.
+
+    In addition you can pass `spec=True` or `spec_set=True`, which causes
+    patch to pass in the object being mocked as the spec/spec_set object.
+
+    `new_callable` allows you to specify a different class, or callable object,
+    that will be called to create the `new` object. By default `MagicMock` is
+    used.
+
+    A more powerful form of `spec` is `autospec`. If you set `autospec=True`
+    then the mock with be created with a spec from the object being replaced.
+    All attributes of the mock will also have the spec of the corresponding
+    attribute of the object being replaced. Methods and functions being mocked
+    will have their arguments checked and will raise a `TypeError` if they are
+    called with the wrong signature. For mocks
+    replacing a class, their return value (the 'instance') will have the same
+    spec as the class. See the :func:`create_autospec` function and
+    :ref:`auto-speccing`.
+
+    Instead of `autospec=True` you can pass `autospec=some_object` to use an
+    arbitrary object as the spec instead of the one being replaced.
+
+    By default `patch` will fail to replace attributes that don't exist. If
+    you pass in `create=True`, and the attribute doesn't exist, patch will
+    create the attribute for you when the patched function is called, and
+    delete it again afterwards. This is useful for writing tests against
+    attributes that your production code creates at runtime. It is off by by
+    default because it can be dangerous. With it switched on you can write
+    passing tests against APIs that don't actually exist!
+
+    Patch can be used as a `TestCase` class decorator. It works by
+    decorating each test method in the class. This reduces the boilerplate
+    code when your test methods share a common patchings set. `patch` finds
+    tests by looking for method names that start with `patch.TEST_PREFIX`.
+    By default this is `test`, which matches the way `unittest` finds tests.
+    You can specify an alternative prefix by setting `patch.TEST_PREFIX`.
+
+    Patch can be used as a context manager, with the with statement. Here the
+    patching applies to the indented block after the with statement. If you
+    use "as" then the patched object will be bound to the name after the
+    "as"; very useful if `patch` is creating a mock object for you.
+
+    `patch` takes arbitrary keyword arguments. These will be passed to
+    the `Mock` (or `new_callable`) on construction.
+
+    `patch.dict(...)`, `patch.multiple(...)` and `patch.object(...)` are
+    available for alternate use-cases.
+
+`patch` as function decorator, creating the mock for you and passing it into
+the decorated function:
+
+.. doctest::
+
+    >>> @patch('__main__.SomeClass')
+    ... def function(normal_argument, mock_class):
+    ...     print mock_class is SomeClass
+    ...
+    >>> function(None)
+    True
+
+
+Patching a class replaces the class with a `MagicMock` *instance*. If the
+class is instantiated in the code under test then it will be the
+:attr:`~Mock.return_value` of the mock that will be used.
+
+If the class is instantiated multiple times you could use
+:attr:`~Mock.side_effect` to return a new mock each time. Alternatively you
+can set the `return_value` to be anything you want.
+
+To configure return values on methods of *instances* on the patched class
+you must do this on the `return_value`. For example:
+
+.. doctest::
+
+    >>> class Class(object):
+    ...     def method(self):
+    ...         pass
+    ...
+    >>> with patch('__main__.Class') as MockClass:
+    ...     instance = MockClass.return_value
+    ...     instance.method.return_value = 'foo'
+    ...     assert Class() is instance
+    ...     assert Class().method() == 'foo'
+    ...
+
+If you use `spec` or `spec_set` and `patch` is replacing a *class*, then the
+return value of the created mock will have the same spec.
+
+.. doctest::
+
+    >>> Original = Class
+    >>> patcher = patch('__main__.Class', spec=True)
+    >>> MockClass = patcher.start()
+    >>> instance = MockClass()
+    >>> assert isinstance(instance, Original)
+    >>> patcher.stop()
+
+The `new_callable` argument is useful where you want to use an alternative
+class to the default :class:`MagicMock` for the created mock. For example, if
+you wanted a :class:`NonCallableMock` to be used:
+
+.. doctest::
+
+    >>> thing = object()
+    >>> with patch('__main__.thing', new_callable=NonCallableMock) as mock_thing:
+    ...     assert thing is mock_thing
+    ...     thing()
+    ...
+    Traceback (most recent call last):
+      ...
+    TypeError: 'NonCallableMock' object is not callable
+
+Another use case might be to replace an object with a `StringIO` instance:
+
+.. doctest::
+
+    >>> from StringIO import StringIO
+    >>> def foo():
+    ...     print 'Something'
+    ...
+    >>> @patch('sys.stdout', new_callable=StringIO)
+    ... def test(mock_stdout):
+    ...     foo()
+    ...     assert mock_stdout.getvalue() == 'Something\n'
+    ...
+    >>> test()
+
+When `patch` is creating a mock for you, it is common that the first thing
+you need to do is to configure the mock. Some of that configuration can be done
+in the call to patch. Any arbitrary keywords you pass into the call will be
+used to set attributes on the created mock:
+
+.. doctest::
+
+    >>> patcher = patch('__main__.thing', first='one', second='two')
+    >>> mock_thing = patcher.start()
+    >>> mock_thing.first
+    'one'
+    >>> mock_thing.second
+    'two'
+
+As well as attributes on the created mock attributes, like the
+:attr:`~Mock.return_value` and :attr:`~Mock.side_effect`, of child mocks can
+also be configured. These aren't syntactically valid to pass in directly as
+keyword arguments, but a dictionary with these as keys can still be expanded
+into a `patch` call using `**`:
+
+.. doctest::
+
+    >>> config = {'method.return_value': 3, 'other.side_effect': KeyError}
+    >>> patcher = patch('__main__.thing', **config)
+    >>> mock_thing = patcher.start()
+    >>> mock_thing.method()
+    3
+    >>> mock_thing.other()
+    Traceback (most recent call last):
+      ...
+    KeyError
+
+
+patch.object
+============
+
+.. function:: patch.object(target, attribute, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)
+
+    patch the named member (`attribute`) on an object (`target`) with a mock
+    object.
+
+    `patch.object` can be used as a decorator, class decorator or a context
+    manager. Arguments `new`, `spec`, `create`, `spec_set`, `autospec` and
+    `new_callable` have the same meaning as for `patch`. Like `patch`,
+    `patch.object` takes arbitrary keyword arguments for configuring the mock
+    object it creates.
+
+    When used as a class decorator `patch.object` honours `patch.TEST_PREFIX`
+    for choosing which methods to wrap.
+
+You can either call `patch.object` with three arguments or two arguments. The
+three argument form takes the object to be patched, the attribute name and the
+object to replace the attribute with.
+
+When calling with the two argument form you omit the replacement object, and a
+mock is created for you and passed in as an extra argument to the decorated
+function:
+
+.. doctest::
+
+    >>> @patch.object(SomeClass, 'class_method')
+    ... def test(mock_method):
+    ...     SomeClass.class_method(3)
+    ...     mock_method.assert_called_with(3)
+    ...
+    >>> test()
+
+`spec`, `create` and the other arguments to `patch.object` have the same
+meaning as they do for `patch`.
+
+
+patch.dict
+==========
+
+.. function:: patch.dict(in_dict, values=(), clear=False, **kwargs)
+
+    Patch a dictionary, or dictionary like object, and restore the dictionary
+    to its original state after the test.
+
+    `in_dict` can be a dictionary or a mapping like container. If it is a
+    mapping then it must at least support getting, setting and deleting items
+    plus iterating over keys.
+
+    `in_dict` can also be a string specifying the name of the dictionary, which
+    will then be fetched by importing it.
+
+    `values` can be a dictionary of values to set in the dictionary. `values`
+    can also be an iterable of `(key, value)` pairs.
+
+    If `clear` is True then the dictionary will be cleared before the new
+    values are set.
+
+    `patch.dict` can also be called with arbitrary keyword arguments to set
+    values in the dictionary.
+
+    `patch.dict` can be used as a context manager, decorator or class
+    decorator. When used as a class decorator `patch.dict` honours
+    `patch.TEST_PREFIX` for choosing which methods to wrap.
+
+`patch.dict` can be used to add members to a dictionary, or simply let a test
+change a dictionary, and ensure the dictionary is restored when the test
+ends.
+
+.. doctest::
+
+    >>> from mock import patch
+    >>> foo = {}
+    >>> with patch.dict(foo, {'newkey': 'newvalue'}):
+    ...     assert foo == {'newkey': 'newvalue'}
+    ...
+    >>> assert foo == {}
+
+    >>> import os
+    >>> with patch.dict('os.environ', {'newkey': 'newvalue'}):
+    ...     print os.environ['newkey']
+    ...
+    newvalue
+    >>> assert 'newkey' not in os.environ
+
+Keywords can be used in the `patch.dict` call to set values in the dictionary:
+
+.. doctest::
+
+    >>> mymodule = MagicMock()
+    >>> mymodule.function.return_value = 'fish'
+    >>> with patch.dict('sys.modules', mymodule=mymodule):
+    ...     import mymodule
+    ...     mymodule.function('some', 'args')
+    ...
+    'fish'
+
+`patch.dict` can be used with dictionary like objects that aren't actually
+dictionaries. At the very minimum they must support item getting, setting,
+deleting and either iteration or membership test. This corresponds to the
+magic methods `__getitem__`, `__setitem__`, `__delitem__` and either
+`__iter__` or `__contains__`.
+
+.. doctest::
+
+    >>> class Container(object):
+    ...     def __init__(self):
+    ...         self.values = {}
+    ...     def __getitem__(self, name):
+    ...         return self.values[name]
+    ...     def __setitem__(self, name, value):
+    ...         self.values[name] = value
+    ...     def __delitem__(self, name):
+    ...         del self.values[name]
+    ...     def __iter__(self):
+    ...         return iter(self.values)
+    ...
+    >>> thing = Container()
+    >>> thing['one'] = 1
+    >>> with patch.dict(thing, one=2, two=3):
+    ...     assert thing['one'] == 2
+    ...     assert thing['two'] == 3
+    ...
+    >>> assert thing['one'] == 1
+    >>> assert list(thing) == ['one']
+
+
+patch.multiple
+==============
+
+.. function:: patch.multiple(target, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)
+
+    Perform multiple patches in a single call. It takes the object to be
+    patched (either as an object or a string to fetch the object by importing)
+    and keyword arguments for the patches::
+
+        with patch.multiple(settings, FIRST_PATCH='one', SECOND_PATCH='two'):
+            ...
+
+    Use :data:`DEFAULT` as the value if you want `patch.multiple` to create
+    mocks for you. In this case the created mocks are passed into a decorated
+    function by keyword, and a dictionary is returned when `patch.multiple` is
+    used as a context manager.
+
+    `patch.multiple` can be used as a decorator, class decorator or a context
+    manager. The arguments `spec`, `spec_set`, `create`, `autospec` and
+    `new_callable` have the same meaning as for `patch`. These arguments will
+    be applied to *all* patches done by `patch.multiple`.
+
+    When used as a class decorator `patch.multiple` honours `patch.TEST_PREFIX`
+    for choosing which methods to wrap.
+
+If you want `patch.multiple` to create mocks for you, then you can use
+:data:`DEFAULT` as the value. If you use `patch.multiple` as a decorator
+then the created mocks are passed into the decorated function by keyword.
+
+.. doctest::
+
+    >>> thing = object()
+    >>> other = object()
+
+    >>> @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT)
+    ... def test_function(thing, other):
+    ...     assert isinstance(thing, MagicMock)
+    ...     assert isinstance(other, MagicMock)
+    ...
+    >>> test_function()
+
+`patch.multiple` can be nested with other `patch` decorators, but put arguments
+passed by keyword *after* any of the standard arguments created by `patch`:
+
+.. doctest::
+
+    >>> @patch('sys.exit')
+    ... @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT)
+    ... def test_function(mock_exit, other, thing):
+    ...     assert 'other' in repr(other)
+    ...     assert 'thing' in repr(thing)
+    ...     assert 'exit' in repr(mock_exit)
+    ...
+    >>> test_function()
+
+If `patch.multiple` is used as a context manager, the value returned by the
+context manger is a dictionary where created mocks are keyed by name:
+
+.. doctest::
+
+    >>> with patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) as values:
+    ...     assert 'other' in repr(values['other'])
+    ...     assert 'thing' in repr(values['thing'])
+    ...     assert values['thing'] is thing
+    ...     assert values['other'] is other
+    ...
+
+
+.. _start-and-stop:
+
+patch methods: start and stop
+=============================
+
+All the patchers have `start` and `stop` methods. These make it simpler to do
+patching in `setUp` methods or where you want to do multiple patches without
+nesting decorators or with statements.
+
+To use them call `patch`, `patch.object` or `patch.dict` as normal and keep a
+reference to the returned `patcher` object. You can then call `start` to put
+the patch in place and `stop` to undo it.
+
+If you are using `patch` to create a mock for you then it will be returned by
+the call to `patcher.start`.
+
+.. doctest::
+
+    >>> patcher = patch('package.module.ClassName')
+    >>> from package import module
+    >>> original = module.ClassName
+    >>> new_mock = patcher.start()
+    >>> assert module.ClassName is not original
+    >>> assert module.ClassName is new_mock
+    >>> patcher.stop()
+    >>> assert module.ClassName is original
+    >>> assert module.ClassName is not new_mock
+
+
+A typical use case for this might be for doing multiple patches in the `setUp`
+method of a `TestCase`:
+
+.. doctest::
+
+    >>> class MyTest(TestCase):
+    ...     def setUp(self):
+    ...         self.patcher1 = patch('package.module.Class1')
+    ...         self.patcher2 = patch('package.module.Class2')
+    ...         self.MockClass1 = self.patcher1.start()
+    ...         self.MockClass2 = self.patcher2.start()
+    ...
+    ...     def tearDown(self):
+    ...         self.patcher1.stop()
+    ...         self.patcher2.stop()
+    ...
+    ...     def test_something(self):
+    ...         assert package.module.Class1 is self.MockClass1
+    ...         assert package.module.Class2 is self.MockClass2
+    ...
+    >>> MyTest('test_something').run()
+
+.. caution::
+
+    If you use this technique you must ensure that the patching is "undone" by
+    calling `stop`. This can be fiddlier than you might think, because if an
+    exception is raised in the setUp then tearDown is not called. `unittest2
+    <http://pypi.python.org/pypi/unittest2>`_ cleanup functions make this
+    easier.
+
+    .. doctest::
+
+        >>> class MyTest(TestCase):
+        ...     def setUp(self):
+        ...         patcher = patch('package.module.Class')
+        ...         self.MockClass = patcher.start()
+        ...         self.addCleanup(patcher.stop)
+        ...
+        ...     def test_something(self):
+        ...         assert package.module.Class is self.MockClass
+        ...
+        >>> MyTest('test_something').run()
+
+    As an added bonus you no longer need to keep a reference to the `patcher`
+    object.
+
+It is also possible to stop all patches which have been started by using
+`patch.stopall`.
+
+.. function:: patch.stopall
+
+    Stop all active patches. Only stops patches started with `start`.
+
+
+TEST_PREFIX
+===========
+
+All of the patchers can be used as class decorators. When used in this way
+they wrap every test method on the class. The patchers recognise methods that
+start with `test` as being test methods. This is the same way that the
+`unittest.TestLoader` finds test methods by default.
+
+It is possible that you want to use a different prefix for your tests. You can
+inform the patchers of the different prefix by setting `patch.TEST_PREFIX`:
+
+.. doctest::
+
+    >>> patch.TEST_PREFIX = 'foo'
+    >>> value = 3
+    >>>
+    >>> @patch('__main__.value', 'not three')
+    ... class Thing(object):
+    ...     def foo_one(self):
+    ...         print value
+    ...     def foo_two(self):
+    ...         print value
+    ...
+    >>>
+    >>> Thing().foo_one()
+    not three
+    >>> Thing().foo_two()
+    not three
+    >>> value
+    3
+
+
+Nesting Patch Decorators
+========================
+
+If you want to perform multiple patches then you can simply stack up the
+decorators.
+
+You can stack up multiple patch decorators using this pattern:
+
+.. doctest::
+
+    >>> @patch.object(SomeClass, 'class_method')
+    ... @patch.object(SomeClass, 'static_method')
+    ... def test(mock1, mock2):
+    ...     assert SomeClass.static_method is mock1
+    ...     assert SomeClass.class_method is mock2
+    ...     SomeClass.static_method('foo')
+    ...     SomeClass.class_method('bar')
+    ...     return mock1, mock2
+    ...
+    >>> mock1, mock2 = test()
+    >>> mock1.assert_called_once_with('foo')
+    >>> mock2.assert_called_once_with('bar')
+
+
+Note that the decorators are applied from the bottom upwards. This is the
+standard way that Python applies decorators. The order of the created mocks
+passed into your test function matches this order.
+
+Like all context-managers patches can be nested using contextlib's nested
+function; *every* patching will appear in the tuple after "as":
+
+.. doctest::
+
+    >>> from contextlib import nested
+    >>> with nested(
+    ...         patch('package.module.ClassName1'),
+    ...         patch('package.module.ClassName2')
+    ...     ) as (MockClass1, MockClass2):
+    ...     assert package.module.ClassName1 is MockClass1
+    ...     assert package.module.ClassName2 is MockClass2
+    ...
+
+
+.. _where-to-patch:
+
+Where to patch
+==============
+
+`patch` works by (temporarily) changing the object that a *name* points to with
+another one. There can be many names pointing to any individual object, so
+for patching to work you must ensure that you patch the name used by the system
+under test.
+
+The basic principle is that you patch where an object is *looked up*, which
+is not necessarily the same place as where it is defined. A couple of
+examples will help to clarify this.
+
+Imagine we have a project that we want to test with the following structure::
+
+    a.py
+        -> Defines SomeClass
+
+    b.py
+        -> from a import SomeClass
+        -> some_function instantiates SomeClass
+
+Now we want to test `some_function` but we want to mock out `SomeClass` using
+`patch`. The problem is that when we import module b, which we will have to
+do then it imports `SomeClass` from module a. If we use `patch` to mock out
+`a.SomeClass` then it will have no effect on our test; module b already has a
+reference to the *real* `SomeClass` and it looks like our patching had no
+effect.
+
+The key is to patch out `SomeClass` where it is used (or where it is looked up
+). In this case `some_function` will actually look up `SomeClass` in module b,
+where we have imported it. The patching should look like:
+
+    `@patch('b.SomeClass')`
+
+However, consider the alternative scenario where instead of `from a import
+SomeClass` module b does `import a` and `some_function` uses `a.SomeClass`. Both
+of these import forms are common. In this case the class we want to patch is
+being looked up on the a module and so we have to patch `a.SomeClass` instead:
+
+    `@patch('a.SomeClass')`
+
+
+Patching Descriptors and Proxy Objects
+======================================
+
+Since version 0.6.0 both patch_ and patch.object_ have been able to correctly
+patch and restore descriptors: class methods, static methods and properties.
+You should patch these on the *class* rather than an instance.
+
+Since version 0.7.0 patch_ and patch.object_ work correctly with some objects
+that proxy attribute access, like the `django setttings object
+<http://www.voidspace.org.uk/python/weblog/arch_d7_2010_12_04.shtml#e1198>`_.
+
+.. note::
+
+    In django `import settings` and `from django.conf import settings`
+    return different objects. If you are using libraries / apps that do both you
+    may have to patch both. Grrr...

Added: incubator/ambari/trunk/ambari-common/src/test/python/mock/docs/sentinel.txt
URL: http://svn.apache.org/viewvc/incubator/ambari/trunk/ambari-common/src/test/python/mock/docs/sentinel.txt?rev=1435472&view=auto
==============================================================================
--- incubator/ambari/trunk/ambari-common/src/test/python/mock/docs/sentinel.txt (added)
+++ incubator/ambari/trunk/ambari-common/src/test/python/mock/docs/sentinel.txt Sat Jan 19 02:33:01 2013
@@ -0,0 +1,58 @@
+==========
+ Sentinel
+==========
+
+
+.. currentmodule:: mock
+
+.. testsetup::
+
+    class ProductionClass(object):
+        def something(self):
+            return self.method()
+
+    class Test(unittest2.TestCase):
+        def testSomething(self):
+            pass
+    self = Test('testSomething')
+
+
+.. data:: sentinel
+
+    The ``sentinel`` object provides a convenient way of providing unique
+    objects for your tests.
+
+    Attributes are created on demand when you access them by name. Accessing
+    the same attribute will always return the same object. The objects
+    returned have a sensible repr so that test failure messages are readable.
+
+
+.. data:: DEFAULT
+
+    The `DEFAULT` object is a pre-created sentinel (actually
+    `sentinel.DEFAULT`). It can be used by :attr:`~Mock.side_effect`
+    functions to indicate that the normal return value should be used.
+
+
+Sentinel Example
+================
+
+Sometimes when testing you need to test that a specific object is passed as an
+argument to another method, or returned. It can be common to create named
+sentinel objects to test this. `sentinel` provides a convenient way of
+creating and testing the identity of objects like this.
+
+In this example we monkey patch `method` to return
+`sentinel.some_object`:
+
+.. doctest::
+
+    >>> real = ProductionClass()
+    >>> real.method = Mock(name="method")
+    >>> real.method.return_value = sentinel.some_object
+    >>> result = real.method()
+    >>> assert result is sentinel.some_object
+    >>> sentinel.some_object
+    sentinel.some_object
+
+

Modified: incubator/ambari/trunk/ambari-server/src/main/python/ambari-server.py
URL: http://svn.apache.org/viewvc/incubator/ambari/trunk/ambari-server/src/main/python/ambari-server.py?rev=1435472&r1=1435471&r2=1435472&view=diff
==============================================================================
--- incubator/ambari/trunk/ambari-server/src/main/python/ambari-server.py (original)
+++ incubator/ambari/trunk/ambari-server/src/main/python/ambari-server.py Sat Jan 19 02:33:01 2013
@@ -19,6 +19,7 @@ limitations under the License.
 '''
 
 import optparse
+import shlex
 import sys
 import os
 import signal
@@ -45,9 +46,6 @@ START_ACTION = "start"
 STOP_ACTION = "stop"
 RESET_ACTION = "reset"
 
-#sudo check command
-SUDO_CHECK_CMD = "rpm -qa | grep sudo"
-
 # selinux commands
 GET_SE_LINUX_ST_CMD = "/usr/sbin/sestatus"
 SE_SETENFORCE_CMD = "setenforce 0"
@@ -96,9 +94,8 @@ PID_DIR="/var/run/ambari-server"
 PID_NAME="ambari-server.pid"
 AMBARI_PROPERTIES_FILE="ambari.properties"
 
-# database commands
-SETUP_DB_CMD = "sudo -u postgres psql -f {0} -v username=\"{1}\" "\
-               "-v password=\'{2}\'"
+SETUP_DB_CMD = ['su', 'postgres',
+        '--command=psql -f {0} -v username=\'"{1}"\' -v password="\'{2}\'"']
 PG_ST_CMD = "/sbin/service postgresql status"
 PG_START_CMD = "/sbin/service postgresql start"
 PG_RESTART_CMD = "/sbin/service postgresql restart"
@@ -107,7 +104,7 @@ PG_HBA_DIR = "/var/lib/pgsql/data/"
 PG_HBA_CONF_FILE = PG_HBA_DIR + "pg_hba.conf"
 PG_HBA_CONF_FILE_BACKUP = PG_HBA_DIR + "pg_hba_bak.conf.old"
 POSTGRESQL_CONF_FILE = PG_HBA_DIR + "postgresql.conf"
-PG_HBA_RELOAD_CMD = "sudo -u postgres pg_ctl -D {0} reload"
+PG_HBA_RELOAD_CMD = "su postgres --command='pg_ctl -D {0} reload'"
 PG_DEFAULT_PASSWORD = "bigdata"
 JDBC_USER_NAME_PROPERTY = "server.jdbc.user.name"
 JDBC_PASSWORD_FILE_PROPERTY = "server.jdbc.user.passwd"
@@ -210,8 +207,10 @@ def restart_postgres():
 
 
 def run_os_command(cmd):
-  print_info_msg('about to run command: ' + cmd)
-  process = subprocess.Popen(cmd.split(' '),
+  print_info_msg('about to run command: ' + str(cmd))
+  if type(cmd) == str:
+    cmd = shlex.split(cmd)
+  process = subprocess.Popen(cmd,
     stdout=subprocess.PIPE,
     stdin=subprocess.PIPE,
     stderr=subprocess.PIPE
@@ -240,7 +239,8 @@ def setup_db(args):
   file = args.init_script_file
   username = args.postgres_username
   password = args.postgres_password
-  command = SETUP_DB_CMD.format(file, username, password)
+  command = SETUP_DB_CMD[:]
+  command[-1] = command[-1].format(file, username, password)
   retcode, outdata, errdata = run_os_command(command)
   if not retcode == 0:
     print errdata
@@ -571,27 +571,12 @@ def find_jdk():
   print "Selected JDK {0}".format(jdkPath)
   return jdkPath
 
-def check_sudo():
-  retcode, out, err = run_os_command(SUDO_CHECK_CMD)
-  if re.search('sudo', out) == None:
-    return 1
-  return 0
-  pass
-
-
 
 #
 # Setup the Ambari Server.
 #
 def setup(args):
 
-  retcode = check_sudo()
-  if retcode != 0:
-    print_error_msg(
-      "ERROR: sudo command not found on host. "
-      "Please install sudo and re-run ambari-server setup. Exiting.")
-    sys.exit(retcode)
-
   print 'Checking SELinux...'
   retcode = check_selinux()
   if not retcode == 0:
@@ -674,7 +659,8 @@ def reset(args):
   filename = args.drop_script_file
   username = args.postgres_username
   password = args.postgres_password
-  command = SETUP_DB_CMD.format(filename, username, password)
+  command = SETUP_DB_CMD[:]
+  command[-1] = command[-1].format(filename, username, password)
   retcode, outdata, errdata = run_os_command(command)
   if not retcode == 0:
     print errdata

Modified: incubator/ambari/trunk/ambari-server/src/test/python/TestAmbaryServer.py
URL: http://svn.apache.org/viewvc/incubator/ambari/trunk/ambari-server/src/test/python/TestAmbaryServer.py?rev=1435472&r1=1435471&r2=1435472&view=diff
==============================================================================
--- incubator/ambari/trunk/ambari-server/src/test/python/TestAmbaryServer.py (original)
+++ incubator/ambari/trunk/ambari-server/src/test/python/TestAmbaryServer.py Sat Jan 19 02:33:01 2013
@@ -531,17 +531,25 @@ class TestAmbariServer(TestCase):
 
 
 
+  @patch("shlex.split")
   @patch("subprocess.Popen")
   @patch.object(ambari_server, "print_info_msg")
-  def test_run_os_command(self, printInfoMsg_mock, popenMock):
+  def test_run_os_command(self, printInfoMsg_mock, popenMock, splitMock):
 
     p = MagicMock()
     p.communicate.return_value = (None, None)
     p.returncode = 3
     popenMock.return_value = p
 
+    # with list arg
+    cmd = ["exec", "arg"]
+    ambari_server.run_os_command(cmd)
+    self.assertFalse(splitMock.called)
+
+    # with str arg
     resp = ambari_server.run_os_command("runme")
     self.assertEqual(3, resp[0])
+    self.assertTrue(splitMock.called)
 
 
 
@@ -892,19 +900,6 @@ class TestAmbariServer(TestCase):
     sys.stdout = sys.__stdout__
 
 
-
-  @patch.object(ambari_server, "run_os_command")
-  def test_check_sudo(self, run_os_command_mock):
-
-    run_os_command_mock.return_value = (0, "none", None)
-    rcode = ambari_server.check_sudo()
-    self.assertEqual(1, rcode)
-
-    run_os_command_mock.return_value = (0, "sudo", None)
-    rcode = ambari_server.check_sudo()
-    self.assertEqual(0, rcode)
-
-
   @patch.object(ambari_server, "configure_os_settings")
   @patch.object(ambari_server, "download_jdk")
   @patch.object(ambari_server, "configure_postgres")
@@ -912,8 +907,7 @@ class TestAmbariServer(TestCase):
   @patch.object(ambari_server, "check_postgre_up")
   @patch.object(ambari_server, "check_iptables")
   @patch.object(ambari_server, "check_selinux")
-  @patch.object(ambari_server, "check_sudo")
-  def test_setup(self, check_sudo_mock, check_selinux_mock, check_iptables_mock,
+  def test_setup(self, check_selinux_mock, check_iptables_mock,
                  check_postgre_up_mock, setup_db_mock, configure_postgres_mock,
                  download_jdk_mock, configure_os_settings_mock):
 
@@ -922,7 +916,6 @@ class TestAmbariServer(TestCase):
 
     args = MagicMock()
 
-    check_sudo_mock.return_value = 0
     check_selinux_mock.return_value = 0
     check_iptables_mock.return_value = (0, "other")
     check_postgre_up_mock.return_value = 0



Mime
View raw message