[Python-checkins] cpython (merge default -> default): Merge.
stefan.krah
python-checkins at python.org
Fri Mar 30 14:21:02 CEST 2012
http://hg.python.org/cpython/rev/cf2e74e0b7d4
changeset: 75995:cf2e74e0b7d4
parent: 75994:3a83264ebcd6
parent: 75993:37ebe64d39d2
user: Stefan Krah <skrah at bytereef.org>
date: Fri Mar 30 14:19:21 2012 +0200
summary:
Merge.
files:
Doc/glossary.rst | 16 +-
Doc/library/development.rst | 4 -
Doc/library/syslog.rst | 9 +-
Doc/library/time.rst | 7 +
Doc/library/unittest.mock-examples.rst | 425 +++-
Doc/library/unittest.mock-getting-started.rst | 417 ---
Doc/library/unittest.mock-helpers.rst | 529 ----
Doc/library/unittest.mock-magicmethods.rst | 224 -
Doc/library/unittest.mock-patch.rst | 529 ----
Doc/library/unittest.mock.rst | 1298 +++++++++-
Doc/library/xml.etree.elementtree.rst | 177 +-
Lib/idlelib/NEWS.txt | 3 +
Lib/idlelib/configHandler.py | 2 +-
Lib/logging/handlers.py | 15 +-
Lib/test/test_smtplib.py | 1 +
Lib/unittest/mock.py | 25 +-
Misc/ACKS | 1 +
Misc/NEWS | 8 +
Modules/syslogmodule.c | 8 +
Objects/floatobject.c | 158 +-
20 files changed, 1941 insertions(+), 1915 deletions(-)
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -194,7 +194,7 @@
An object exposing a file-oriented API (with methods such as
:meth:`read()` or :meth:`write()`) to an underlying resource. Depending
on the way it was created, a file object can mediate access to a real
- on-disk file or to another other type of storage or communication device
+ on-disk file or to another type of storage or communication device
(for example standard input/output, in-memory buffers, sockets, pipes,
etc.). File objects are also called :dfn:`file-like objects` or
:dfn:`streams`.
@@ -523,6 +523,20 @@
definition), or pass several arguments as a list to a function. See
:term:`argument`.
+ provisional package
+ A provisional package is one which has been deliberately excluded from the
+ standard library's backwards compatibility guarantees. While major
+ changes to such packages are not expected, as long as they are marked
+ provisional, backwards incompatible changes (up to and including removal
+ of the package) may occur if deemed necessary by core developers. Such
+ changes will not be made gratuitously -- they will occur only if serious
+ flaws are uncovered that were missed prior to the inclusion of the
+ package.
+
+ This process allows the standard library to continue to evolve over time,
+ without locking in problematic design errors for extended periods of time.
+ See :pep:`411` for more details.
+
Python 3000
Nickname for the Python 3.x release line (coined long ago when the release
of version 3 was something in the distant future.) This is also
diff --git a/Doc/library/development.rst b/Doc/library/development.rst
--- a/Doc/library/development.rst
+++ b/Doc/library/development.rst
@@ -20,10 +20,6 @@
doctest.rst
unittest.rst
unittest.mock.rst
- unittest.mock-patch.rst
- unittest.mock-magicmethods.rst
- unittest.mock-helpers.rst
- unittest.mock-getting-started.rst
unittest.mock-examples.rst
2to3.rst
test.rst
diff --git a/Doc/library/syslog.rst b/Doc/library/syslog.rst
--- a/Doc/library/syslog.rst
+++ b/Doc/library/syslog.rst
@@ -78,11 +78,14 @@
Facilities:
:const:`LOG_KERN`, :const:`LOG_USER`, :const:`LOG_MAIL`, :const:`LOG_DAEMON`,
:const:`LOG_AUTH`, :const:`LOG_LPR`, :const:`LOG_NEWS`, :const:`LOG_UUCP`,
- :const:`LOG_CRON` and :const:`LOG_LOCAL0` to :const:`LOG_LOCAL7`.
+ :const:`LOG_CRON`, :const:`LOG_SYSLOG`, :const:`LOG_LOCAL0` to
+ :const:`LOG_LOCAL7`, and, if defined in ``<syslog.h>``,
+ :const:`LOG_AUTHPRIV`.
Log options:
- :const:`LOG_PID`, :const:`LOG_CONS`, :const:`LOG_NDELAY`, :const:`LOG_NOWAIT`
- and :const:`LOG_PERROR` if defined in ``<syslog.h>``.
+ :const:`LOG_PID`, :const:`LOG_CONS`, :const:`LOG_NDELAY`, and, if defined
+ in ``<syslog.h>``, :const:`LOG_ODELAY`, :const:`LOG_NOWAIT`, and
+ :const:`LOG_PERROR`.
Examples
diff --git a/Doc/library/time.rst b/Doc/library/time.rst
--- a/Doc/library/time.rst
+++ b/Doc/library/time.rst
@@ -143,12 +143,14 @@
.. versionadded:: 3.3
+
.. function:: clock_gettime(clk_id)
Return the time of the specified clock *clk_id*.
.. versionadded:: 3.3
+
.. data:: CLOCK_REALTIME
System-wide real-time clock. Setting this clock requires appropriate
@@ -156,6 +158,7 @@
.. versionadded:: 3.3
+
.. data:: CLOCK_MONOTONIC
Clock that cannot be set and represents monotonic time since some
@@ -163,6 +166,7 @@
.. versionadded:: 3.3
+
.. data:: CLOCK_MONOTONIC_RAW
Similar to :data:`CLOCK_MONOTONIC`, but provides access to a raw
@@ -172,18 +176,21 @@
.. versionadded:: 3.3
+
.. data:: CLOCK_PROCESS_CPUTIME_ID
High-resolution per-process timer from the CPU.
.. versionadded:: 3.3
+
.. data:: CLOCK_THREAD_CPUTIME_ID
Thread-specific CPU-time clock.
.. versionadded:: 3.3
+
.. function:: ctime([secs])
Convert a time expressed in seconds since the epoch to a string representing
diff --git a/Doc/library/unittest.mock-examples.rst b/Doc/library/unittest.mock-examples.rst
--- a/Doc/library/unittest.mock-examples.rst
+++ b/Doc/library/unittest.mock-examples.rst
@@ -1,18 +1,427 @@
-.. _further-examples:
+:mod:`unittest.mock` --- getting started
+========================================
-:mod:`unittest.mock` --- further examples
-=========================================
-
-.. module:: unittest.mock
- :synopsis: Mock object library.
.. moduleauthor:: Michael Foord <michael at python.org>
.. currentmodule:: unittest.mock
.. versionadded:: 3.3
-Here are some more examples for some slightly more advanced scenarios than in
-the :ref:`getting started <getting-started>` guide.
+.. _getting-started:
+
+Using Mock
+----------
+
+Mock Patching Methods
+~~~~~~~~~~~~~~~~~~~~~
+
+Common uses for :class:`Mock` objects include:
+
+* Patching methods
+* Recording method calls on objects
+
+You might want to replace a method on an object to check that
+it is called with the correct arguments by another part of the system:
+
+ >>> real = SomeClass()
+ >>> real.method = MagicMock(name='method')
+ >>> real.method(3, 4, 5, key='value')
+ <MagicMock name='method()' id='...'>
+
+Once our mock has been used (`real.method` in this example) it has methods
+and attributes that allow you to make assertions about how it has been used.
+
+.. note::
+
+ In most of these examples the :class:`Mock` and :class:`MagicMock` classes
+ are interchangeable. As the `MagicMock` is the more capable class it makes
+ a sensible one to use by default.
+
+Once the mock has been called its :attr:`~Mock.called` attribute is set to
+`True`. More importantly we can use the :meth:`~Mock.assert_called_with` or
+:meth`~Mock.assert_called_once_with` method to check that it was called with
+the correct arguments.
+
+This example tests that calling `ProductionClass().method` results in a call to
+the `something` method:
+
+ >>> class ProductionClass(object):
+ ... def method(self):
+ ... self.something(1, 2, 3)
+ ... def something(self, a, b, c):
+ ... pass
+ ...
+ >>> real = ProductionClass()
+ >>> real.something = MagicMock()
+ >>> real.method()
+ >>> real.something.assert_called_once_with(1, 2, 3)
+
+
+
+Mock for Method Calls on an Object
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the last example we patched a method directly on an object to check that it
+was called correctly. Another common use case is to pass an object into a
+method (or some part of the system under test) and then check that it is used
+in the correct way.
+
+The simple `ProductionClass` below has a `closer` method. If it is called with
+an object then it calls `close` on it.
+
+ >>> class ProductionClass(object):
+ ... def closer(self, something):
+ ... something.close()
+ ...
+
+So to test it we need to pass in an object with a `close` method and check
+that it was called correctly.
+
+ >>> real = ProductionClass()
+ >>> mock = Mock()
+ >>> real.closer(mock)
+ >>> mock.close.assert_called_with()
+
+We don't have to do any work to provide the 'close' method on our mock.
+Accessing close creates it. So, if 'close' hasn't already been called then
+accessing it in the test will create it, but :meth:`~Mock.assert_called_with`
+will raise a failure exception.
+
+
+Mocking Classes
+~~~~~~~~~~~~~~~
+
+A common use case is to mock out classes instantiated by your code under test.
+When you patch a class, then that class is replaced with a mock. Instances
+are created by *calling the class*. This means you access the "mock instance"
+by looking at the return value of the mocked class.
+
+In the example below we have a function `some_function` that instantiates `Foo`
+and calls a method on it. The call to `patch` replaces the class `Foo` with a
+mock. The `Foo` instance is the result of calling the mock, so it is configured
+by modify the mock :attr:`~Mock.return_value`.
+
+ >>> def some_function():
+ ... instance = module.Foo()
+ ... return instance.method()
+ ...
+ >>> with patch('module.Foo') as mock:
+ ... instance = mock.return_value
+ ... instance.method.return_value = 'the result'
+ ... result = some_function()
+ ... assert result == 'the result'
+
+
+Naming your mocks
+~~~~~~~~~~~~~~~~~
+
+It can be useful to give your mocks a name. The name is shown in the repr of
+the mock and can be helpful when the mock appears in test failure messages. The
+name is also propagated to attributes or methods of the mock:
+
+ >>> mock = MagicMock(name='foo')
+ >>> mock
+ <MagicMock name='foo' id='...'>
+ >>> mock.method
+ <MagicMock name='foo.method' id='...'>
+
+
+Tracking all Calls
+~~~~~~~~~~~~~~~~~~
+
+Often you want to track more than a single call to a method. The
+:attr:`~Mock.mock_calls` attribute records all calls
+to child attributes of the mock - and also to their children.
+
+ >>> mock = MagicMock()
+ >>> mock.method()
+ <MagicMock name='mock.method()' id='...'>
+ >>> mock.attribute.method(10, x=53)
+ <MagicMock name='mock.attribute.method()' id='...'>
+ >>> mock.mock_calls
+ [call.method(), call.attribute.method(10, x=53)]
+
+If you make an assertion about `mock_calls` and any unexpected methods
+have been called, then the assertion will fail. This is useful because as well
+as asserting that the calls you expected have been made, you are also checking
+that they were made in the right order and with no additional calls:
+
+You use the :data:`call` object to construct lists for comparing with
+`mock_calls`:
+
+ >>> expected = [call.method(), call.attribute.method(10, x=53)]
+ >>> mock.mock_calls == expected
+ True
+
+
+Setting Return Values and Attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Setting the return values on a mock object is trivially easy:
+
+ >>> mock = Mock()
+ >>> mock.return_value = 3
+ >>> mock()
+ 3
+
+Of course you can do the same for methods on the mock:
+
+ >>> mock = Mock()
+ >>> mock.method.return_value = 3
+ >>> mock.method()
+ 3
+
+The return value can also be set in the constructor:
+
+ >>> mock = Mock(return_value=3)
+ >>> mock()
+ 3
+
+If you need an attribute setting on your mock, just do it:
+
+ >>> mock = Mock()
+ >>> mock.x = 3
+ >>> mock.x
+ 3
+
+Sometimes you want to mock up a more complex situation, like for example
+`mock.connection.cursor().execute("SELECT 1")`. If we wanted this call to
+return a list, then we have to configure the result of the nested call.
+
+We can use :data:`call` to construct the set of calls in a "chained call" like
+this for easy assertion afterwards:
+
+ >>> mock = Mock()
+ >>> cursor = mock.connection.cursor.return_value
+ >>> cursor.execute.return_value = ['foo']
+ >>> mock.connection.cursor().execute("SELECT 1")
+ ['foo']
+ >>> expected = call.connection.cursor().execute("SELECT 1").call_list()
+ >>> mock.mock_calls
+ [call.connection.cursor(), call.connection.cursor().execute('SELECT 1')]
+ >>> mock.mock_calls == expected
+ True
+
+It is the call to `.call_list()` that turns our call object into a list of
+calls representing the chained calls.
+
+
+Raising exceptions with mocks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A useful attribute is :attr:`~Mock.side_effect`. If you set this to an
+exception class or instance then the exception will be raised when the mock
+is called.
+
+ >>> mock = Mock(side_effect=Exception('Boom!'))
+ >>> mock()
+ Traceback (most recent call last):
+ ...
+ Exception: Boom!
+
+
+Side effect functions and iterables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`side_effect` can also be set to a function or an iterable. The use case for
+`side_effect` as an iterable is where your mock is going to be called several
+times, and you want each call to return a different value. When you set
+`side_effect` to an iterable every call to the mock returns the next value
+from the iterable:
+
+ >>> mock = MagicMock(side_effect=[4, 5, 6])
+ >>> mock()
+ 4
+ >>> mock()
+ 5
+ >>> mock()
+ 6
+
+
+For more advanced use cases, like dynamically varying the return values
+depending on what the mock is called with, `side_effect` can be a function.
+The function will be called with the same arguments as the mock. Whatever the
+function returns is what the call returns:
+
+ >>> vals = {(1, 2): 1, (2, 3): 2}
+ >>> def side_effect(*args):
+ ... return vals[args]
+ ...
+ >>> mock = MagicMock(side_effect=side_effect)
+ >>> mock(1, 2)
+ 1
+ >>> mock(2, 3)
+ 2
+
+
+Creating a Mock from an Existing Object
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+One problem with over use of mocking is that it couples your tests to the
+implementation of your mocks rather than your real code. Suppose you have a
+class that implements `some_method`. In a test for another class, you
+provide a mock of this object that *also* provides `some_method`. If later
+you refactor the first class, so that it no longer has `some_method` - then
+your tests will continue to pass even though your code is now broken!
+
+`Mock` allows you to provide an object as a specification for the mock,
+using the `spec` keyword argument. Accessing methods / attributes on the
+mock that don't exist on your specification object will immediately raise an
+attribute error. If you change the implementation of your specification, then
+tests that use that class will start failing immediately without you having to
+instantiate the class in those tests.
+
+ >>> mock = Mock(spec=SomeClass)
+ >>> mock.old_method()
+ Traceback (most recent call last):
+ ...
+ AttributeError: object has no attribute 'old_method'
+
+If you want a stronger form of specification that prevents the setting
+of arbitrary attributes as well as the getting of them then you can use
+`spec_set` instead of `spec`.
+
+
+
+Patch Decorators
+----------------
+
+.. note::
+
+ With `patch` it matters that you patch objects in the namespace where they
+ are looked up. This is normally straightforward, but for a quick guide
+ read :ref:`where to patch <where-to-patch>`.
+
+
+A common need in tests is to patch a class attribute or a module attribute,
+for example patching a builtin or patching a class in a module to test that it
+is instantiated. Modules and classes are effectively global, so patching on
+them has to be undone after the test or the patch will persist into other
+tests and cause hard to diagnose problems.
+
+mock provides three convenient decorators for this: `patch`, `patch.object` and
+`patch.dict`. `patch` takes a single string, of the form
+`package.module.Class.attribute` to specify the attribute you are patching. It
+also optionally takes a value that you want the attribute (or class or
+whatever) to be replaced with. 'patch.object' takes an object and the name of
+the attribute you would like patched, plus optionally the value to patch it
+with.
+
+`patch.object`:
+
+ >>> original = SomeClass.attribute
+ >>> @patch.object(SomeClass, 'attribute', sentinel.attribute)
+ ... def test():
+ ... assert SomeClass.attribute == sentinel.attribute
+ ...
+ >>> test()
+ >>> assert SomeClass.attribute == original
+
+ >>> @patch('package.module.attribute', sentinel.attribute)
+ ... def test():
+ ... from package.module import attribute
+ ... assert attribute is sentinel.attribute
+ ...
+ >>> test()
+
+If you are patching a module (including `__builtin__`) then use `patch`
+instead of `patch.object`:
+
+ >>> mock = MagicMock(return_value = sentinel.file_handle)
+ >>> with patch('__builtin__.open', mock):
+ ... handle = open('filename', 'r')
+ ...
+ >>> mock.assert_called_with('filename', 'r')
+ >>> assert handle == sentinel.file_handle, "incorrect file handle returned"
+
+The module name can be 'dotted', in the form `package.module` if needed:
+
+ >>> @patch('package.module.ClassName.attribute', sentinel.attribute)
+ ... def test():
+ ... from package.module import ClassName
+ ... assert ClassName.attribute == sentinel.attribute
+ ...
+ >>> test()
+
+A nice pattern is to actually decorate test methods themselves:
+
+ >>> class MyTest(unittest2.TestCase):
+ ... @patch.object(SomeClass, 'attribute', sentinel.attribute)
+ ... def test_something(self):
+ ... self.assertEqual(SomeClass.attribute, sentinel.attribute)
+ ...
+ >>> original = SomeClass.attribute
+ >>> MyTest('test_something').test_something()
+ >>> assert SomeClass.attribute == original
+
+If you want to patch with a Mock, you can use `patch` with only one argument
+(or `patch.object` with two arguments). The mock will be created for you and
+passed into the test function / method:
+
+ >>> class MyTest(unittest2.TestCase):
+ ... @patch.object(SomeClass, 'static_method')
+ ... def test_something(self, mock_method):
+ ... SomeClass.static_method()
+ ... mock_method.assert_called_with()
+ ...
+ >>> MyTest('test_something').test_something()
+
+You can stack up multiple patch decorators using this pattern:
+
+ >>> class MyTest(unittest2.TestCase):
+ ... @patch('package.module.ClassName1')
+ ... @patch('package.module.ClassName2')
+ ... def test_something(self, MockClass2, MockClass1):
+ ... self.assertTrue(package.module.ClassName1 is MockClass1)
+ ... self.assertTrue(package.module.ClassName2 is MockClass2)
+ ...
+ >>> MyTest('test_something').test_something()
+
+When you nest patch decorators the mocks are passed in to the decorated
+function in the same order they applied (the normal *python* order that
+decorators are applied). This means from the bottom up, so in the example
+above the mock for `test_module.ClassName2` is passed in first.
+
+There is also :func:`patch.dict` for setting values in a dictionary just
+during a scope and restoring the dictionary to its original state when the test
+ends:
+
+ >>> foo = {'key': 'value'}
+ >>> original = foo.copy()
+ >>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True):
+ ... assert foo == {'newkey': 'newvalue'}
+ ...
+ >>> assert foo == original
+
+`patch`, `patch.object` and `patch.dict` can all be used as context managers.
+
+Where you use `patch` to create a mock for you, you can get a reference to the
+mock using the "as" form of the with statement:
+
+ >>> class ProductionClass(object):
+ ... def method(self):
+ ... pass
+ ...
+ >>> with patch.object(ProductionClass, 'method') as mock_method:
+ ... mock_method.return_value = None
+ ... real = ProductionClass()
+ ... real.method(1, 2, 3)
+ ...
+ >>> mock_method.assert_called_with(1, 2, 3)
+
+
+As an alternative `patch`, `patch.object` and `patch.dict` can be used as
+class decorators. When used in this way it is the same as applying the
+decorator indvidually to every method whose name starts with "test".
+
+
+.. _further-examples:
+
+Further Examples
+================
+
+
+Here are some more examples for some slightly more advanced scenarios.
Mocking chained calls
diff --git a/Doc/library/unittest.mock-getting-started.rst b/Doc/library/unittest.mock-getting-started.rst
deleted file mode 100644
--- a/Doc/library/unittest.mock-getting-started.rst
+++ /dev/null
@@ -1,419 +0,0 @@
-:mod:`unittest.mock` --- getting started
-========================================
-
-.. module:: unittest.mock
- :synopsis: Mock object library.
-.. moduleauthor:: Michael Foord <michael at python.org>
-.. currentmodule:: unittest.mock
-
-.. versionadded:: 3.3
-
-
-.. _getting-started:
-
-Using Mock
-----------
-
-Mock Patching Methods
-~~~~~~~~~~~~~~~~~~~~~
-
-Common uses for :class:`Mock` objects include:
-
-* Patching methods
-* Recording method calls on objects
-
-You might want to replace a method on an object to check that
-it is called with the correct arguments by another part of the system:
-
- >>> real = SomeClass()
- >>> real.method = MagicMock(name='method')
- >>> real.method(3, 4, 5, key='value')
- <MagicMock name='method()' id='...'>
-
-Once our mock has been used (`real.method` in this example) it has methods
-and attributes that allow you to make assertions about how it has been used.
-
-.. note::
-
- In most of these examples the :class:`Mock` and :class:`MagicMock` classes
- are interchangeable. As the `MagicMock` is the more capable class it makes
- a sensible one to use by default.
-
-Once the mock has been called its :attr:`~Mock.called` attribute is set to
-`True`. More importantly we can use the :meth:`~Mock.assert_called_with` or
-:meth`~Mock.assert_called_once_with` method to check that it was called with
-the correct arguments.
-
-This example tests that calling `ProductionClass().method` results in a call to
-the `something` method:
-
- >>> class ProductionClass(object):
- ... def method(self):
- ... self.something(1, 2, 3)
- ... def something(self, a, b, c):
- ... pass
- ...
- >>> real = ProductionClass()
- >>> real.something = MagicMock()
- >>> real.method()
- >>> real.something.assert_called_once_with(1, 2, 3)
-
-
-
-Mock for Method Calls on an Object
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In the last example we patched a method directly on an object to check that it
-was called correctly. Another common use case is to pass an object into a
-method (or some part of the system under test) and then check that it is used
-in the correct way.
-
-The simple `ProductionClass` below has a `closer` method. If it is called with
-an object then it calls `close` on it.
-
- >>> class ProductionClass(object):
- ... def closer(self, something):
- ... something.close()
- ...
-
-So to test it we need to pass in an object with a `close` method and check
-that it was called correctly.
-
- >>> real = ProductionClass()
- >>> mock = Mock()
- >>> real.closer(mock)
- >>> mock.close.assert_called_with()
-
-We don't have to do any work to provide the 'close' method on our mock.
-Accessing close creates it. So, if 'close' hasn't already been called then
-accessing it in the test will create it, but :meth:`~Mock.assert_called_with`
-will raise a failure exception.
-
-
-Mocking Classes
-~~~~~~~~~~~~~~~
-
-A common use case is to mock out classes instantiated by your code under test.
-When you patch a class, then that class is replaced with a mock. Instances
-are created by *calling the class*. This means you access the "mock instance"
-by looking at the return value of the mocked class.
-
-In the example below we have a function `some_function` that instantiates `Foo`
-and calls a method on it. The call to `patch` replaces the class `Foo` with a
-mock. The `Foo` instance is the result of calling the mock, so it is configured
-by modify the mock :attr:`~Mock.return_value`.
-
- >>> def some_function():
- ... instance = module.Foo()
- ... return instance.method()
- ...
- >>> with patch('module.Foo') as mock:
- ... instance = mock.return_value
- ... instance.method.return_value = 'the result'
- ... result = some_function()
- ... assert result == 'the result'
-
-
-Naming your mocks
-~~~~~~~~~~~~~~~~~
-
-It can be useful to give your mocks a name. The name is shown in the repr of
-the mock and can be helpful when the mock appears in test failure messages. The
-name is also propagated to attributes or methods of the mock:
-
- >>> mock = MagicMock(name='foo')
- >>> mock
- <MagicMock name='foo' id='...'>
- >>> mock.method
- <MagicMock name='foo.method' id='...'>
-
-
-Tracking all Calls
-~~~~~~~~~~~~~~~~~~
-
-Often you want to track more than a single call to a method. The
-:attr:`~Mock.mock_calls` attribute records all calls
-to child attributes of the mock - and also to their children.
-
- >>> mock = MagicMock()
- >>> mock.method()
- <MagicMock name='mock.method()' id='...'>
- >>> mock.attribute.method(10, x=53)
- <MagicMock name='mock.attribute.method()' id='...'>
- >>> mock.mock_calls
- [call.method(), call.attribute.method(10, x=53)]
-
-If you make an assertion about `mock_calls` and any unexpected methods
-have been called, then the assertion will fail. This is useful because as well
-as asserting that the calls you expected have been made, you are also checking
-that they were made in the right order and with no additional calls:
-
-You use the :data:`call` object to construct lists for comparing with
-`mock_calls`:
-
- >>> expected = [call.method(), call.attribute.method(10, x=53)]
- >>> mock.mock_calls == expected
- True
-
-
-Setting Return Values and Attributes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Setting the return values on a mock object is trivially easy:
-
- >>> mock = Mock()
- >>> mock.return_value = 3
- >>> mock()
- 3
-
-Of course you can do the same for methods on the mock:
-
- >>> mock = Mock()
- >>> mock.method.return_value = 3
- >>> mock.method()
- 3
-
-The return value can also be set in the constructor:
-
- >>> mock = Mock(return_value=3)
- >>> mock()
- 3
-
-If you need an attribute setting on your mock, just do it:
-
- >>> mock = Mock()
- >>> mock.x = 3
- >>> mock.x
- 3
-
-Sometimes you want to mock up a more complex situation, like for example
-`mock.connection.cursor().execute("SELECT 1")`. If we wanted this call to
-return a list, then we have to configure the result of the nested call.
-
-We can use :data:`call` to construct the set of calls in a "chained call" like
-this for easy assertion afterwards:
-
- >>> mock = Mock()
- >>> cursor = mock.connection.cursor.return_value
- >>> cursor.execute.return_value = ['foo']
- >>> mock.connection.cursor().execute("SELECT 1")
- ['foo']
- >>> expected = call.connection.cursor().execute("SELECT 1").call_list()
- >>> mock.mock_calls
- [call.connection.cursor(), call.connection.cursor().execute('SELECT 1')]
- >>> mock.mock_calls == expected
- True
-
-It is the call to `.call_list()` that turns our call object into a list of
-calls representing the chained calls.
-
-
-Raising exceptions with mocks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A useful attribute is :attr:`~Mock.side_effect`. If you set this to an
-exception class or instance then the exception will be raised when the mock
-is called.
-
- >>> mock = Mock(side_effect=Exception('Boom!'))
- >>> mock()
- Traceback (most recent call last):
- ...
- Exception: Boom!
-
-
-Side effect functions and iterables
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-`side_effect` can also be set to a function or an iterable. The use case for
-`side_effect` as an iterable is where your mock is going to be called several
-times, and you want each call to return a different value. When you set
-`side_effect` to an iterable every call to the mock returns the next value
-from the iterable:
-
- >>> mock = MagicMock(side_effect=[4, 5, 6])
- >>> mock()
- 4
- >>> mock()
- 5
- >>> mock()
- 6
-
-
-For more advanced use cases, like dynamically varying the return values
-depending on what the mock is called with, `side_effect` can be a function.
-The function will be called with the same arguments as the mock. Whatever the
-function returns is what the call returns:
-
- >>> vals = {(1, 2): 1, (2, 3): 2}
- >>> def side_effect(*args):
- ... return vals[args]
- ...
- >>> mock = MagicMock(side_effect=side_effect)
- >>> mock(1, 2)
- 1
- >>> mock(2, 3)
- 2
-
-
-Creating a Mock from an Existing Object
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-One problem with over use of mocking is that it couples your tests to the
-implementation of your mocks rather than your real code. Suppose you have a
-class that implements `some_method`. In a test for another class, you
-provide a mock of this object that *also* provides `some_method`. If later
-you refactor the first class, so that it no longer has `some_method` - then
-your tests will continue to pass even though your code is now broken!
-
-`Mock` allows you to provide an object as a specification for the mock,
-using the `spec` keyword argument. Accessing methods / attributes on the
-mock that don't exist on your specification object will immediately raise an
-attribute error. If you change the implementation of your specification, then
-tests that use that class will start failing immediately without you having to
-instantiate the class in those tests.
-
- >>> mock = Mock(spec=SomeClass)
- >>> mock.old_method()
- Traceback (most recent call last):
- ...
- AttributeError: object has no attribute 'old_method'
-
-If you want a stronger form of specification that prevents the setting
-of arbitrary attributes as well as the getting of them then you can use
-`spec_set` instead of `spec`.
-
-
-
-Patch Decorators
-----------------
-
-.. note::
-
- With `patch` it matters that you patch objects in the namespace where they
- are looked up. This is normally straightforward, but for a quick guide
- read :ref:`where to patch <where-to-patch>`.
-
-
-A common need in tests is to patch a class attribute or a module attribute,
-for example patching a builtin or patching a class in a module to test that it
-is instantiated. Modules and classes are effectively global, so patching on
-them has to be undone after the test or the patch will persist into other
-tests and cause hard to diagnose problems.
-
-mock provides three convenient decorators for this: `patch`, `patch.object` and
-`patch.dict`. `patch` takes a single string, of the form
-`package.module.Class.attribute` to specify the attribute you are patching. It
-also optionally takes a value that you want the attribute (or class or
-whatever) to be replaced with. 'patch.object' takes an object and the name of
-the attribute you would like patched, plus optionally the value to patch it
-with.
-
-`patch.object`:
-
- >>> original = SomeClass.attribute
- >>> @patch.object(SomeClass, 'attribute', sentinel.attribute)
- ... def test():
- ... assert SomeClass.attribute == sentinel.attribute
- ...
- >>> test()
- >>> assert SomeClass.attribute == original
-
- >>> @patch('package.module.attribute', sentinel.attribute)
- ... def test():
- ... from package.module import attribute
- ... assert attribute is sentinel.attribute
- ...
- >>> test()
-
-If you are patching a module (including `__builtin__`) then use `patch`
-instead of `patch.object`:
-
- >>> mock = MagicMock(return_value = sentinel.file_handle)
- >>> with patch('__builtin__.open', mock):
- ... handle = open('filename', 'r')
- ...
- >>> mock.assert_called_with('filename', 'r')
- >>> assert handle == sentinel.file_handle, "incorrect file handle returned"
-
-The module name can be 'dotted', in the form `package.module` if needed:
-
- >>> @patch('package.module.ClassName.attribute', sentinel.attribute)
- ... def test():
- ... from package.module import ClassName
- ... assert ClassName.attribute == sentinel.attribute
- ...
- >>> test()
-
-A nice pattern is to actually decorate test methods themselves:
-
- >>> class MyTest(unittest2.TestCase):
- ... @patch.object(SomeClass, 'attribute', sentinel.attribute)
- ... def test_something(self):
- ... self.assertEqual(SomeClass.attribute, sentinel.attribute)
- ...
- >>> original = SomeClass.attribute
- >>> MyTest('test_something').test_something()
- >>> assert SomeClass.attribute == original
-
-If you want to patch with a Mock, you can use `patch` with only one argument
-(or `patch.object` with two arguments). The mock will be created for you and
-passed into the test function / method:
-
- >>> class MyTest(unittest2.TestCase):
- ... @patch.object(SomeClass, 'static_method')
- ... def test_something(self, mock_method):
- ... SomeClass.static_method()
- ... mock_method.assert_called_with()
- ...
- >>> MyTest('test_something').test_something()
-
-You can stack up multiple patch decorators using this pattern:
-
- >>> class MyTest(unittest2.TestCase):
- ... @patch('package.module.ClassName1')
- ... @patch('package.module.ClassName2')
- ... def test_something(self, MockClass2, MockClass1):
- ... self.assertTrue(package.module.ClassName1 is MockClass1)
- ... self.assertTrue(package.module.ClassName2 is MockClass2)
- ...
- >>> MyTest('test_something').test_something()
-
-When you nest patch decorators the mocks are passed in to the decorated
-function in the same order they applied (the normal *python* order that
-decorators are applied). This means from the bottom up, so in the example
-above the mock for `test_module.ClassName2` is passed in first.
-
-There is also :func:`patch.dict` for setting values in a dictionary just
-during a scope and restoring the dictionary to its original state when the test
-ends:
-
- >>> foo = {'key': 'value'}
- >>> original = foo.copy()
- >>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True):
- ... assert foo == {'newkey': 'newvalue'}
- ...
- >>> assert foo == original
-
-`patch`, `patch.object` and `patch.dict` can all be used as context managers.
-
-Where you use `patch` to create a mock for you, you can get a reference to the
-mock using the "as" form of the with statement:
-
- >>> class ProductionClass(object):
- ... def method(self):
- ... pass
- ...
- >>> with patch.object(ProductionClass, 'method') as mock_method:
- ... mock_method.return_value = None
- ... real = ProductionClass()
- ... real.method(1, 2, 3)
- ...
- >>> mock_method.assert_called_with(1, 2, 3)
-
-
-As an alternative `patch`, `patch.object` and `patch.dict` can be used as
-class decorators. When used in this way it is the same as applying the
-decorator indvidually to every method whose name starts with "test".
-
-For some more advanced examples, see the :ref:`further-examples` page.
diff --git a/Doc/library/unittest.mock-helpers.rst b/Doc/library/unittest.mock-helpers.rst
deleted file mode 100644
--- a/Doc/library/unittest.mock-helpers.rst
+++ /dev/null
@@ -1,537 +0,0 @@
-:mod:`unittest.mock` --- helpers
-================================
-
-.. module:: unittest.mock
- :synopsis: Mock object library.
-.. moduleauthor:: Michael Foord <michael at python.org>
-.. currentmodule:: unittest.mock
-
-.. versionadded:: 3.3
-
-
-sentinel
---------
-
-.. 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.
-
-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`:
-
- >>> 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
-
-
-DEFAULT
--------
-
-
-.. 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.
-
-
-
-call
-----
-
-.. function:: call(*args, **kwargs)
-
- `call` is a helper object for making simpler assertions, for comparing
- with :attr:`~Mock.call_args`, :attr:`~Mock.call_args_list`,
- :attr:`~Mock.mock_calls` and:attr: `~Mock.method_calls`. `call` can also be
- used with :meth:`~Mock.assert_has_calls`.
-
- >>> m = MagicMock(return_value=None)
- >>> m(1, 2, a='foo', b='bar')
- >>> m()
- >>> m.call_args_list == [call(1, 2, a='foo', b='bar'), call()]
- True
-
-.. method:: call.call_list()
-
- For a call object that represents multiple calls, `call_list`
- returns a list of all the intermediate calls as well as the
- final call.
-
-`call_list` is particularly useful for making assertions on "chained calls". A
-chained call is multiple calls on a single line of code. This results in
-multiple entries in :attr:`~Mock.mock_calls` on a mock. Manually constructing
-the sequence of calls can be tedious.
-
-:meth:`~call.call_list` can construct the sequence of calls from the same
-chained call:
-
- >>> m = MagicMock()
- >>> m(1).method(arg='foo').other('bar')(2.0)
- <MagicMock name='mock().method().other()()' id='...'>
- >>> kall = call(1).method(arg='foo').other('bar')(2.0)
- >>> kall.call_list()
- [call(1),
- call().method(arg='foo'),
- call().method().other('bar'),
- call().method().other()(2.0)]
- >>> m.mock_calls == kall.call_list()
- True
-
-.. _calls-as-tuples:
-
-A `call` object is either a tuple of (positional args, keyword args) or
-(name, positional args, keyword args) depending on how it was constructed. When
-you construct them yourself this isn't particularly interesting, but the `call`
-objects that are in the :attr:`Mock.call_args`, :attr:`Mock.call_args_list` and
-:attr:`Mock.mock_calls` attributes can be introspected to get at the individual
-arguments they contain.
-
-The `call` objects in :attr:`Mock.call_args` and :attr:`Mock.call_args_list`
-are two-tuples of (positional args, keyword args) whereas the `call` objects
-in :attr:`Mock.mock_calls`, along with ones you construct yourself, are
-three-tuples of (name, positional args, keyword args).
-
-You can use their "tupleness" to pull out the individual arguments for more
-complex introspection and assertions. The positional arguments are a tuple
-(an empty tuple if there are no positional arguments) and the keyword
-arguments are a dictionary:
-
- >>> m = MagicMock(return_value=None)
- >>> m(1, 2, 3, arg='one', arg2='two')
- >>> kall = m.call_args
- >>> args, kwargs = kall
- >>> args
- (1, 2, 3)
- >>> kwargs
- {'arg2': 'two', 'arg': 'one'}
- >>> args is kall[0]
- True
- >>> kwargs is kall[1]
- True
-
- >>> m = MagicMock()
- >>> m.foo(4, 5, 6, arg='two', arg2='three')
- <MagicMock name='mock.foo()' id='...'>
- >>> kall = m.mock_calls[0]
- >>> name, args, kwargs = kall
- >>> name
- 'foo'
- >>> args
- (4, 5, 6)
- >>> kwargs
- {'arg2': 'three', 'arg': 'two'}
- >>> name is m.mock_calls[0][0]
- True
-
-
-create_autospec
----------------
-
-.. function:: create_autospec(spec, spec_set=False, instance=False, **kwargs)
-
- Create a mock object using another object as a spec. Attributes on the
- mock will use the corresponding attribute on the `spec` object as their
- spec.
-
- Functions or methods being mocked will have their arguments checked to
- ensure that they are called with the correct signature.
-
- If `spec_set` is `True` then attempting to set attributes that don't exist
- on the spec object will raise an `AttributeError`.
-
- If a class is used as a spec then the return value of the mock (the
- instance of the class) will have the same spec. You can use a class as the
- spec for an instance object by passing `instance=True`. The returned mock
- will only be callable if instances of the mock are callable.
-
- `create_autospec` also takes arbitrary keyword arguments that are passed to
- the constructor of the created mock.
-
-See :ref:`auto-speccing` for examples of how to use auto-speccing with
-`create_autospec` and the `autospec` argument to :func:`patch`.
-
-
-ANY
----
-
-.. data:: ANY
-
-Sometimes you may need to make assertions about *some* of the arguments in a
-call to mock, but either not care about some of the arguments or want to pull
-them individually out of :attr:`~Mock.call_args` and make more complex
-assertions on them.
-
-To ignore certain arguments you can pass in objects that compare equal to
-*everything*. Calls to :meth:`~Mock.assert_called_with` and
-:meth:`~Mock.assert_called_once_with` will then succeed no matter what was
-passed in.
-
- >>> mock = Mock(return_value=None)
- >>> mock('foo', bar=object())
- >>> mock.assert_called_once_with('foo', bar=ANY)
-
-`ANY` can also be used in comparisons with call lists like
-:attr:`~Mock.mock_calls`:
-
- >>> m = MagicMock(return_value=None)
- >>> m(1)
- >>> m(1, 2)
- >>> m(object())
- >>> m.mock_calls == [call(1), call(1, 2), ANY]
- True
-
-
-
-FILTER_DIR
-----------
-
-.. data:: FILTER_DIR
-
-`FILTER_DIR` is a module level variable that controls the way mock objects
-respond to `dir` (only for Python 2.6 or more recent). The default is `True`,
-which uses the filtering described below, to only show useful members. If you
-dislike this filtering, or need to switch it off for diagnostic purposes, then
-set `mock.FILTER_DIR = False`.
-
-With filtering on, `dir(some_mock)` shows only useful attributes and will
-include any dynamically created attributes that wouldn't normally be shown.
-If the mock was created with a `spec` (or `autospec` of course) then all the
-attributes from the original are shown, even if they haven't been accessed
-yet:
-
- >>> dir(Mock())
- ['assert_any_call',
- 'assert_called_once_with',
- 'assert_called_with',
- 'assert_has_calls',
- 'attach_mock',
- ...
- >>> from urllib import request
- >>> dir(Mock(spec=request))
- ['AbstractBasicAuthHandler',
- 'AbstractDigestAuthHandler',
- 'AbstractHTTPHandler',
- 'BaseHandler',
- ...
-
-Many of the not-very-useful (private to `Mock` rather than the thing being
-mocked) underscore and double underscore prefixed attributes have been
-filtered from the result of calling `dir` on a `Mock`. If you dislike this
-behaviour you can switch it off by setting the module level switch
-`FILTER_DIR`:
-
- >>> from unittest import mock
- >>> mock.FILTER_DIR = False
- >>> dir(mock.Mock())
- ['_NonCallableMock__get_return_value',
- '_NonCallableMock__get_side_effect',
- '_NonCallableMock__return_value_doc',
- '_NonCallableMock__set_return_value',
- '_NonCallableMock__set_side_effect',
- '__call__',
- '__class__',
- ...
-
-Alternatively you can just use `vars(my_mock)` (instance members) and
-`dir(type(my_mock))` (type members) to bypass the filtering irrespective of
-`mock.FILTER_DIR`.
-
-
-mock_open
----------
-
-.. function:: mock_open(mock=None, read_data=None)
-
- A helper function to create a mock to replace the use of `open`. It works
- for `open` called directly or used as a context manager.
-
- The `mock` argument is the mock object to configure. If `None` (the
- default) then a `MagicMock` will be created for you, with the API limited
- to methods or attributes available on standard file handles.
-
- `read_data` is a string for the `read` method of the file handle to return.
- This is an empty string by default.
-
-Using `open` as a context manager is a great way to ensure your file handles
-are closed properly and is becoming common::
-
- with open('/some/path', 'w') as f:
- f.write('something')
-
-The issue is that even if you mock out the call to `open` it is the
-*returned object* that is used as a context manager (and has `__enter__` and
-`__exit__` called).
-
-Mocking context managers with a :class:`MagicMock` is common enough and fiddly
-enough that a helper function is useful.
-
- >>> m = mock_open()
- >>> with patch('__main__.open', m, create=True):
- ... with open('foo', 'w') as h:
- ... h.write('some stuff')
- ...
- >>> m.mock_calls
- [call('foo', 'w'),
- call().__enter__(),
- call().write('some stuff'),
- call().__exit__(None, None, None)]
- >>> m.assert_called_once_with('foo', 'w')
- >>> handle = m()
- >>> handle.write.assert_called_once_with('some stuff')
-
-And for reading files:
-
- >>> with patch('__main__.open', mock_open(read_data='bibble'), create=True) as m:
- ... with open('foo') as h:
- ... result = h.read()
- ...
- >>> m.assert_called_once_with('foo')
- >>> assert result == 'bibble'
-
-
-.. _auto-speccing:
-
-Autospeccing
-------------
-
-Autospeccing is based on the existing `spec` feature of mock. It limits the
-api of mocks to the api of an original object (the spec), but it is recursive
-(implemented lazily) so that attributes of mocks only have the same api as
-the attributes of the spec. In addition mocked functions / methods have the
-same call signature as the original so they raise a `TypeError` if they are
-called incorrectly.
-
-Before I explain how auto-speccing works, here's why it is needed.
-
-`Mock` is a very powerful and flexible object, but it suffers from two flaws
-when used to mock out objects from a system under test. One of these flaws is
-specific to the `Mock` api and the other is a more general problem with using
-mock objects.
-
-First the problem specific to `Mock`. `Mock` has two assert methods that are
-extremely handy: :meth:`~Mock.assert_called_with` and
-:meth:`~Mock.assert_called_once_with`.
-
- >>> mock = Mock(name='Thing', return_value=None)
- >>> mock(1, 2, 3)
- >>> mock.assert_called_once_with(1, 2, 3)
- >>> mock(1, 2, 3)
- >>> mock.assert_called_once_with(1, 2, 3)
- Traceback (most recent call last):
- ...
- AssertionError: Expected to be called once. Called 2 times.
-
-Because mocks auto-create attributes on demand, and allow you to call them
-with arbitrary arguments, if you misspell one of these assert methods then
-your assertion is gone:
-
-.. code-block:: pycon
-
- >>> mock = Mock(name='Thing', return_value=None)
- >>> mock(1, 2, 3)
- >>> mock.assret_called_once_with(4, 5, 6)
-
-Your tests can pass silently and incorrectly because of the typo.
-
-The second issue is more general to mocking. If you refactor some of your
-code, rename members and so on, any tests for code that is still using the
-*old api* but uses mocks instead of the real objects will still pass. This
-means your tests can all pass even though your code is broken.
-
-Note that this is another reason why you need integration tests as well as
-unit tests. Testing everything in isolation is all fine and dandy, but if you
-don't test how your units are "wired together" there is still lots of room
-for bugs that tests might have caught.
-
-`mock` already provides a feature to help with this, called speccing. If you
-use a class or instance as the `spec` for a mock then you can only access
-attributes on the mock that exist on the real class:
-
- >>> from urllib import request
- >>> mock = Mock(spec=request.Request)
- >>> mock.assret_called_with
- Traceback (most recent call last):
- ...
- AttributeError: Mock object has no attribute 'assret_called_with'
-
-The spec only applies to the mock itself, so we still have the same issue
-with any methods on the mock:
-
-.. code-block:: pycon
-
- >>> mock.has_data()
- <mock.Mock object at 0x...>
- >>> mock.has_data.assret_called_with()
-
-Auto-speccing solves this problem. You can either pass `autospec=True` to
-`patch` / `patch.object` or use the `create_autospec` function to create a
-mock with a spec. If you use the `autospec=True` argument to `patch` then the
-object that is being replaced will be used as the spec object. Because the
-speccing is done "lazily" (the spec is created as attributes on the mock are
-accessed) you can use it with very complex or deeply nested objects (like
-modules that import modules that import modules) without a big performance
-hit.
-
-Here's an example of it in use:
-
- >>> from urllib import request
- >>> patcher = patch('__main__.request', autospec=True)
- >>> mock_request = patcher.start()
- >>> request is mock_request
- True
- >>> mock_request.Request
- <MagicMock name='request.Request' spec='Request' id='...'>
-
-You can see that `request.Request` has a spec. `request.Request` takes two
-arguments in the constructor (one of which is `self`). Here's what happens if
-we try to call it incorrectly:
-
- >>> req = request.Request()
- Traceback (most recent call last):
- ...
- TypeError: <lambda>() takes at least 2 arguments (1 given)
-
-The spec also applies to instantiated classes (i.e. the return value of
-specced mocks):
-
- >>> req = request.Request('foo')
- >>> req
- <NonCallableMagicMock name='request.Request()' spec='Request' id='...'>
-
-`Request` objects are not callable, so the return value of instantiating our
-mocked out `request.Request` is a non-callable mock. With the spec in place
-any typos in our asserts will raise the correct error:
-
- >>> req.add_header('spam', 'eggs')
- <MagicMock name='request.Request().add_header()' id='...'>
- >>> req.add_header.assret_called_with
- Traceback (most recent call last):
- ...
- AttributeError: Mock object has no attribute 'assret_called_with'
- >>> req.add_header.assert_called_with('spam', 'eggs')
-
-In many cases you will just be able to add `autospec=True` to your existing
-`patch` calls and then be protected against bugs due to typos and api
-changes.
-
-As well as using `autospec` through `patch` there is a
-:func:`create_autospec` for creating autospecced mocks directly:
-
- >>> from urllib import request
- >>> mock_request = create_autospec(request)
- >>> mock_request.Request('foo', 'bar')
- <NonCallableMagicMock name='mock.Request()' spec='Request' id='...'>
-
-This isn't without caveats and limitations however, which is why it is not
-the default behaviour. In order to know what attributes are available on the
-spec object, autospec has to introspect (access attributes) the spec. As you
-traverse attributes on the mock a corresponding traversal of the original
-object is happening under the hood. If any of your specced objects have
-properties or descriptors that can trigger code execution then you may not be
-able to use autospec. On the other hand it is much better to design your
-objects so that introspection is safe [#]_.
-
-A more serious problem is that it is common for instance attributes to be
-created in the `__init__` method and not to exist on the class at all.
-`autospec` can't know about any dynamically created attributes and restricts
-the api to visible attributes.
-
- >>> class Something(object):
- ... def __init__(self):
- ... self.a = 33
- ...
- >>> with patch('__main__.Something', autospec=True):
- ... thing = Something()
- ... thing.a
- ...
- Traceback (most recent call last):
- ...
- AttributeError: Mock object has no attribute 'a'
-
-There are a few different ways of resolving this problem. The easiest, but
-not necessarily the least annoying, way is to simply set the required
-attributes on the mock after creation. Just because `autospec` doesn't allow
-you to fetch attributes that don't exist on the spec it doesn't prevent you
-setting them:
-
- >>> with patch('__main__.Something', autospec=True):
- ... thing = Something()
- ... thing.a = 33
- ...
-
-There is a more aggressive version of both `spec` and `autospec` that *does*
-prevent you setting non-existent attributes. This is useful if you want to
-ensure your code only *sets* valid attributes too, but obviously it prevents
-this particular scenario:
-
- >>> with patch('__main__.Something', autospec=True, spec_set=True):
- ... thing = Something()
- ... thing.a = 33
- ...
- Traceback (most recent call last):
- ...
- AttributeError: Mock object has no attribute 'a'
-
-Probably the best way of solving the problem is to add class attributes as
-default values for instance members initialised in `__init__`. Note that if
-you are only setting default attributes in `__init__` then providing them via
-class attributes (shared between instances of course) is faster too. e.g.
-
-.. code-block:: python
-
- class Something(object):
- a = 33
-
-This brings up another issue. It is relatively common to provide a default
-value of `None` for members that will later be an object of a different type.
-`None` would be useless as a spec because it wouldn't let you access *any*
-attributes or methods on it. As `None` is *never* going to be useful as a
-spec, and probably indicates a member that will normally of some other type,
-`autospec` doesn't use a spec for members that are set to `None`. These will
-just be ordinary mocks (well - `MagicMocks`):
-
- >>> class Something(object):
- ... member = None
- ...
- >>> mock = create_autospec(Something)
- >>> mock.member.foo.bar.baz()
- <MagicMock name='mock.member.foo.bar.baz()' id='...'>
-
-If modifying your production classes to add defaults isn't to your liking
-then there are more options. One of these is simply to use an instance as the
-spec rather than the class. The other is to create a subclass of the
-production class and add the defaults to the subclass without affecting the
-production class. Both of these require you to use an alternative object as
-the spec. Thankfully `patch` supports this - you can simply pass the
-alternative object as the `autospec` argument:
-
- >>> class Something(object):
- ... def __init__(self):
- ... self.a = 33
- ...
- >>> class SomethingForTest(Something):
- ... a = 33
- ...
- >>> p = patch('__main__.Something', autospec=SomethingForTest)
- >>> mock = p.start()
- >>> mock.a
- <NonCallableMagicMock name='Something.a' spec='int' id='...'>
-
-
-.. [#] This only applies to classes or already instantiated objects. Calling
- a mocked class to create a mock instance *does not* create a real instance.
- It is only attribute lookups - along with calls to `dir` - that are done.
diff --git a/Doc/library/unittest.mock-magicmethods.rst b/Doc/library/unittest.mock-magicmethods.rst
deleted file mode 100644
--- a/Doc/library/unittest.mock-magicmethods.rst
+++ /dev/null
@@ -1,226 +0,0 @@
-:mod:`unittest.mock` --- MagicMock and magic method support
-===========================================================
-
-.. module:: unittest.mock
- :synopsis: Mock object library.
-.. moduleauthor:: Michael Foord <michael at python.org>
-.. currentmodule:: unittest.mock
-
-.. versionadded:: 3.3
-
-
-.. _magic-methods:
-
-Mocking Magic Methods
----------------------
-
-:class:`Mock` supports mocking the Python protocol methods, also known as
-"magic methods". 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 [#]_.
-
- >>> 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:
-
- >>> 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 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:
-
- >>> 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
-* ``__index__`` : 1
-* ``__hash__`` : default hash for the mock
-* ``__str__`` : default str for the mock
-* ``__sizeof__``: default sizeof for the mock
-
-For example:
-
- >>> mock = MagicMock()
- >>> int(mock)
- 1
- >>> len(mock)
- 0
- >>> list(mock)
- []
- >>> object() in mock
- False
-
-The two equality method, `__eq__` and `__ne__`, are special.
-They do the default equality comparison on identity, using a side
-effect, unless you change their return value to return something else:
-
- >>> MagicMock() == 3
- False
- >>> MagicMock() != 3
- True
- >>> mock = MagicMock()
- >>> mock.__eq__.return_value = True
- >>> mock == 3
- True
-
-The return value of `MagicMock.__iter__` can be any iterable object and isn't
-required to be an iterator:
-
- >>> 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:
-
- >>> 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:
-
-* ``__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.
diff --git a/Doc/library/unittest.mock-patch.rst b/Doc/library/unittest.mock-patch.rst
deleted file mode 100644
--- a/Doc/library/unittest.mock-patch.rst
+++ /dev/null
@@ -1,538 +0,0 @@
-:mod:`unittest.mock` --- the patchers
-=====================================
-
-.. module:: unittest.mock
- :synopsis: Mock object library.
-.. moduleauthor:: Michael Foord <michael at python.org>
-.. currentmodule:: unittest.mock
-
-.. versionadded:: 3.3
-
-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`
- (specified in the form `'package.module.ClassName'`) is patched
- with a `new` object. When the function/with statement exits the patch is
- undone.
-
- The `target` is imported and the specified attribute patched with the new
- object, so it must be importable from the environment you are calling the
- decorator from. The target is imported when the decorated function is
- executed, not at decoration time.
-
- If `new` is omitted, then a new `MagicMock` is created and passed in as an
- extra argument to the decorated function.
-
- 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.
-
-
-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:
-
- >>> 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.
-
- >>> 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:
-
- >>> 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:
-
- >>> 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:
-
- >>> 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 `**`:
-
- >>> 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:
-
- >>> @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.
-
- >>> 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:
-
- >>> 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__`.
-
- >>> 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.
-
- >>> 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`:
-
- >>> @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:
-
- >>> 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`.
-
- >>> 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`:
-
- >>> 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.
- :meth:`unittest.TestCase.addCleanup` makes this easier:
-
- >>> 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
- ...
-
- As an added bonus you no longer need to keep a reference to the `patcher`
- object.
-
-In fact `start` and `stop` are just aliases for the context manager
-`__enter__` and `__exit__` methods.
-
-
-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
-:class:`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`:
-
- >>> 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:
-
- >>> @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.
-
-
-.. _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
---------------------------------------
-
-Both patch_ and patch.object_ correctly patch and restore descriptors: class
-methods, static methods and properties. You should patch these on the *class*
-rather than an instance. They also work 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>`_.
diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -84,7 +84,6 @@
... def test(MockClass1, MockClass2):
... module.ClassName1()
... module.ClassName2()
-
... assert MockClass1 is module.ClassName1
... assert MockClass2 is module.ClassName2
... assert MockClass1.called
@@ -898,3 +897,1300 @@
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>`.
+
+
+The patchers
+============
+
+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:
+
+ >>> @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:
+
+ >>> 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.
+
+ >>> 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:
+
+ >>> 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:
+
+ >>> 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:
+
+ >>> 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 `**`:
+
+ >>> 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:
+
+ >>> @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.
+
+ >>> 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:
+
+ >>> 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__`.
+
+ >>> 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.
+
+ >>> 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`:
+
+ >>> @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:
+
+ >>> 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`.
+
+ >>> 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`:
+
+ >>> 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.
+ :meth:`unittest.TestCase.addCleanup` makes this easier:
+
+ >>> 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
+ ...
+
+ As an added bonus you no longer need to keep a reference to the `patcher`
+ object.
+
+In fact `start` and `stop` are just aliases for the context manager
+`__enter__` and `__exit__` methods.
+
+
+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
+:class:`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`:
+
+ >>> 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:
+
+ >>> @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.
+
+
+.. _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
+--------------------------------------
+
+Both patch_ and patch.object_ correctly patch and restore descriptors: class
+methods, static methods and properties. You should patch these on the *class*
+rather than an instance. They also work 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>`_.
+
+
+MagicMock and magic method support
+==================================
+
+.. _magic-methods:
+
+Mocking Magic Methods
+---------------------
+
+:class:`Mock` supports mocking the Python protocol methods, also known as
+"magic methods". 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 [#]_.
+
+ >>> 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:
+
+ >>> 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 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:
+
+ >>> 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
+* ``__index__`` : 1
+* ``__hash__`` : default hash for the mock
+* ``__str__`` : default str for the mock
+* ``__sizeof__``: default sizeof for the mock
+
+For example:
+
+ >>> mock = MagicMock()
+ >>> int(mock)
+ 1
+ >>> len(mock)
+ 0
+ >>> list(mock)
+ []
+ >>> object() in mock
+ False
+
+The two equality method, `__eq__` and `__ne__`, are special.
+They do the default equality comparison on identity, using a side
+effect, unless you change their return value to return something else:
+
+ >>> MagicMock() == 3
+ False
+ >>> MagicMock() != 3
+ True
+ >>> mock = MagicMock()
+ >>> mock.__eq__.return_value = True
+ >>> mock == 3
+ True
+
+The return value of `MagicMock.__iter__` can be any iterable object and isn't
+required to be an iterator:
+
+ >>> 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:
+
+ >>> 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:
+
+* ``__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.
+
+
+Helpers
+=======
+
+sentinel
+--------
+
+.. 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.
+
+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`:
+
+ >>> 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
+
+
+DEFAULT
+-------
+
+
+.. 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.
+
+
+
+call
+----
+
+.. function:: call(*args, **kwargs)
+
+ `call` is a helper object for making simpler assertions, for comparing
+ with :attr:`~Mock.call_args`, :attr:`~Mock.call_args_list`,
+ :attr:`~Mock.mock_calls` and :attr: `~Mock.method_calls`. `call` can also be
+ used with :meth:`~Mock.assert_has_calls`.
+
+ >>> m = MagicMock(return_value=None)
+ >>> m(1, 2, a='foo', b='bar')
+ >>> m()
+ >>> m.call_args_list == [call(1, 2, a='foo', b='bar'), call()]
+ True
+
+.. method:: call.call_list()
+
+ For a call object that represents multiple calls, `call_list`
+ returns a list of all the intermediate calls as well as the
+ final call.
+
+`call_list` is particularly useful for making assertions on "chained calls". A
+chained call is multiple calls on a single line of code. This results in
+multiple entries in :attr:`~Mock.mock_calls` on a mock. Manually constructing
+the sequence of calls can be tedious.
+
+:meth:`~call.call_list` can construct the sequence of calls from the same
+chained call:
+
+ >>> m = MagicMock()
+ >>> m(1).method(arg='foo').other('bar')(2.0)
+ <MagicMock name='mock().method().other()()' id='...'>
+ >>> kall = call(1).method(arg='foo').other('bar')(2.0)
+ >>> kall.call_list()
+ [call(1),
+ call().method(arg='foo'),
+ call().method().other('bar'),
+ call().method().other()(2.0)]
+ >>> m.mock_calls == kall.call_list()
+ True
+
+.. _calls-as-tuples:
+
+A `call` object is either a tuple of (positional args, keyword args) or
+(name, positional args, keyword args) depending on how it was constructed. When
+you construct them yourself this isn't particularly interesting, but the `call`
+objects that are in the :attr:`Mock.call_args`, :attr:`Mock.call_args_list` and
+:attr:`Mock.mock_calls` attributes can be introspected to get at the individual
+arguments they contain.
+
+The `call` objects in :attr:`Mock.call_args` and :attr:`Mock.call_args_list`
+are two-tuples of (positional args, keyword args) whereas the `call` objects
+in :attr:`Mock.mock_calls`, along with ones you construct yourself, are
+three-tuples of (name, positional args, keyword args).
+
+You can use their "tupleness" to pull out the individual arguments for more
+complex introspection and assertions. The positional arguments are a tuple
+(an empty tuple if there are no positional arguments) and the keyword
+arguments are a dictionary:
+
+ >>> m = MagicMock(return_value=None)
+ >>> m(1, 2, 3, arg='one', arg2='two')
+ >>> kall = m.call_args
+ >>> args, kwargs = kall
+ >>> args
+ (1, 2, 3)
+ >>> kwargs
+ {'arg2': 'two', 'arg': 'one'}
+ >>> args is kall[0]
+ True
+ >>> kwargs is kall[1]
+ True
+
+ >>> m = MagicMock()
+ >>> m.foo(4, 5, 6, arg='two', arg2='three')
+ <MagicMock name='mock.foo()' id='...'>
+ >>> kall = m.mock_calls[0]
+ >>> name, args, kwargs = kall
+ >>> name
+ 'foo'
+ >>> args
+ (4, 5, 6)
+ >>> kwargs
+ {'arg2': 'three', 'arg': 'two'}
+ >>> name is m.mock_calls[0][0]
+ True
+
+
+create_autospec
+---------------
+
+.. function:: create_autospec(spec, spec_set=False, instance=False, **kwargs)
+
+ Create a mock object using another object as a spec. Attributes on the
+ mock will use the corresponding attribute on the `spec` object as their
+ spec.
+
+ Functions or methods being mocked will have their arguments checked to
+ ensure that they are called with the correct signature.
+
+ If `spec_set` is `True` then attempting to set attributes that don't exist
+ on the spec object will raise an `AttributeError`.
+
+ If a class is used as a spec then the return value of the mock (the
+ instance of the class) will have the same spec. You can use a class as the
+ spec for an instance object by passing `instance=True`. The returned mock
+ will only be callable if instances of the mock are callable.
+
+ `create_autospec` also takes arbitrary keyword arguments that are passed to
+ the constructor of the created mock.
+
+See :ref:`auto-speccing` for examples of how to use auto-speccing with
+`create_autospec` and the `autospec` argument to :func:`patch`.
+
+
+ANY
+---
+
+.. data:: ANY
+
+Sometimes you may need to make assertions about *some* of the arguments in a
+call to mock, but either not care about some of the arguments or want to pull
+them individually out of :attr:`~Mock.call_args` and make more complex
+assertions on them.
+
+To ignore certain arguments you can pass in objects that compare equal to
+*everything*. Calls to :meth:`~Mock.assert_called_with` and
+:meth:`~Mock.assert_called_once_with` will then succeed no matter what was
+passed in.
+
+ >>> mock = Mock(return_value=None)
+ >>> mock('foo', bar=object())
+ >>> mock.assert_called_once_with('foo', bar=ANY)
+
+`ANY` can also be used in comparisons with call lists like
+:attr:`~Mock.mock_calls`:
+
+ >>> m = MagicMock(return_value=None)
+ >>> m(1)
+ >>> m(1, 2)
+ >>> m(object())
+ >>> m.mock_calls == [call(1), call(1, 2), ANY]
+ True
+
+
+
+FILTER_DIR
+----------
+
+.. data:: FILTER_DIR
+
+`FILTER_DIR` is a module level variable that controls the way mock objects
+respond to `dir` (only for Python 2.6 or more recent). The default is `True`,
+which uses the filtering described below, to only show useful members. If you
+dislike this filtering, or need to switch it off for diagnostic purposes, then
+set `mock.FILTER_DIR = False`.
+
+With filtering on, `dir(some_mock)` shows only useful attributes and will
+include any dynamically created attributes that wouldn't normally be shown.
+If the mock was created with a `spec` (or `autospec` of course) then all the
+attributes from the original are shown, even if they haven't been accessed
+yet:
+
+ >>> dir(Mock())
+ ['assert_any_call',
+ 'assert_called_once_with',
+ 'assert_called_with',
+ 'assert_has_calls',
+ 'attach_mock',
+ ...
+ >>> from urllib import request
+ >>> dir(Mock(spec=request))
+ ['AbstractBasicAuthHandler',
+ 'AbstractDigestAuthHandler',
+ 'AbstractHTTPHandler',
+ 'BaseHandler',
+ ...
+
+Many of the not-very-useful (private to `Mock` rather than the thing being
+mocked) underscore and double underscore prefixed attributes have been
+filtered from the result of calling `dir` on a `Mock`. If you dislike this
+behaviour you can switch it off by setting the module level switch
+`FILTER_DIR`:
+
+ >>> from unittest import mock
+ >>> mock.FILTER_DIR = False
+ >>> dir(mock.Mock())
+ ['_NonCallableMock__get_return_value',
+ '_NonCallableMock__get_side_effect',
+ '_NonCallableMock__return_value_doc',
+ '_NonCallableMock__set_return_value',
+ '_NonCallableMock__set_side_effect',
+ '__call__',
+ '__class__',
+ ...
+
+Alternatively you can just use `vars(my_mock)` (instance members) and
+`dir(type(my_mock))` (type members) to bypass the filtering irrespective of
+`mock.FILTER_DIR`.
+
+
+mock_open
+---------
+
+.. function:: mock_open(mock=None, read_data=None)
+
+ A helper function to create a mock to replace the use of `open`. It works
+ for `open` called directly or used as a context manager.
+
+ The `mock` argument is the mock object to configure. If `None` (the
+ default) then a `MagicMock` will be created for you, with the API limited
+ to methods or attributes available on standard file handles.
+
+ `read_data` is a string for the `read` method of the file handle to return.
+ This is an empty string by default.
+
+Using `open` as a context manager is a great way to ensure your file handles
+are closed properly and is becoming common::
+
+ with open('/some/path', 'w') as f:
+ f.write('something')
+
+The issue is that even if you mock out the call to `open` it is the
+*returned object* that is used as a context manager (and has `__enter__` and
+`__exit__` called).
+
+Mocking context managers with a :class:`MagicMock` is common enough and fiddly
+enough that a helper function is useful.
+
+ >>> m = mock_open()
+ >>> with patch('__main__.open', m, create=True):
+ ... with open('foo', 'w') as h:
+ ... h.write('some stuff')
+ ...
+ >>> m.mock_calls
+ [call('foo', 'w'),
+ call().__enter__(),
+ call().write('some stuff'),
+ call().__exit__(None, None, None)]
+ >>> m.assert_called_once_with('foo', 'w')
+ >>> handle = m()
+ >>> handle.write.assert_called_once_with('some stuff')
+
+And for reading files:
+
+ >>> with patch('__main__.open', mock_open(read_data='bibble'), create=True) as m:
+ ... with open('foo') as h:
+ ... result = h.read()
+ ...
+ >>> m.assert_called_once_with('foo')
+ >>> assert result == 'bibble'
+
+
+.. _auto-speccing:
+
+Autospeccing
+------------
+
+Autospeccing is based on the existing `spec` feature of mock. It limits the
+api of mocks to the api of an original object (the spec), but it is recursive
+(implemented lazily) so that attributes of mocks only have the same api as
+the attributes of the spec. In addition mocked functions / methods have the
+same call signature as the original so they raise a `TypeError` if they are
+called incorrectly.
+
+Before I explain how auto-speccing works, here's why it is needed.
+
+`Mock` is a very powerful and flexible object, but it suffers from two flaws
+when used to mock out objects from a system under test. One of these flaws is
+specific to the `Mock` api and the other is a more general problem with using
+mock objects.
+
+First the problem specific to `Mock`. `Mock` has two assert methods that are
+extremely handy: :meth:`~Mock.assert_called_with` and
+:meth:`~Mock.assert_called_once_with`.
+
+ >>> mock = Mock(name='Thing', return_value=None)
+ >>> mock(1, 2, 3)
+ >>> mock.assert_called_once_with(1, 2, 3)
+ >>> mock(1, 2, 3)
+ >>> mock.assert_called_once_with(1, 2, 3)
+ Traceback (most recent call last):
+ ...
+ AssertionError: Expected to be called once. Called 2 times.
+
+Because mocks auto-create attributes on demand, and allow you to call them
+with arbitrary arguments, if you misspell one of these assert methods then
+your assertion is gone:
+
+.. code-block:: pycon
+
+ >>> mock = Mock(name='Thing', return_value=None)
+ >>> mock(1, 2, 3)
+ >>> mock.assret_called_once_with(4, 5, 6)
+
+Your tests can pass silently and incorrectly because of the typo.
+
+The second issue is more general to mocking. If you refactor some of your
+code, rename members and so on, any tests for code that is still using the
+*old api* but uses mocks instead of the real objects will still pass. This
+means your tests can all pass even though your code is broken.
+
+Note that this is another reason why you need integration tests as well as
+unit tests. Testing everything in isolation is all fine and dandy, but if you
+don't test how your units are "wired together" there is still lots of room
+for bugs that tests might have caught.
+
+`mock` already provides a feature to help with this, called speccing. If you
+use a class or instance as the `spec` for a mock then you can only access
+attributes on the mock that exist on the real class:
+
+ >>> from urllib import request
+ >>> mock = Mock(spec=request.Request)
+ >>> mock.assret_called_with
+ Traceback (most recent call last):
+ ...
+ AttributeError: Mock object has no attribute 'assret_called_with'
+
+The spec only applies to the mock itself, so we still have the same issue
+with any methods on the mock:
+
+.. code-block:: pycon
+
+ >>> mock.has_data()
+ <mock.Mock object at 0x...>
+ >>> mock.has_data.assret_called_with()
+
+Auto-speccing solves this problem. You can either pass `autospec=True` to
+`patch` / `patch.object` or use the `create_autospec` function to create a
+mock with a spec. If you use the `autospec=True` argument to `patch` then the
+object that is being replaced will be used as the spec object. Because the
+speccing is done "lazily" (the spec is created as attributes on the mock are
+accessed) you can use it with very complex or deeply nested objects (like
+modules that import modules that import modules) without a big performance
+hit.
+
+Here's an example of it in use:
+
+ >>> from urllib import request
+ >>> patcher = patch('__main__.request', autospec=True)
+ >>> mock_request = patcher.start()
+ >>> request is mock_request
+ True
+ >>> mock_request.Request
+ <MagicMock name='request.Request' spec='Request' id='...'>
+
+You can see that `request.Request` has a spec. `request.Request` takes two
+arguments in the constructor (one of which is `self`). Here's what happens if
+we try to call it incorrectly:
+
+ >>> req = request.Request()
+ Traceback (most recent call last):
+ ...
+ TypeError: <lambda>() takes at least 2 arguments (1 given)
+
+The spec also applies to instantiated classes (i.e. the return value of
+specced mocks):
+
+ >>> req = request.Request('foo')
+ >>> req
+ <NonCallableMagicMock name='request.Request()' spec='Request' id='...'>
+
+`Request` objects are not callable, so the return value of instantiating our
+mocked out `request.Request` is a non-callable mock. With the spec in place
+any typos in our asserts will raise the correct error:
+
+ >>> req.add_header('spam', 'eggs')
+ <MagicMock name='request.Request().add_header()' id='...'>
+ >>> req.add_header.assret_called_with
+ Traceback (most recent call last):
+ ...
+ AttributeError: Mock object has no attribute 'assret_called_with'
+ >>> req.add_header.assert_called_with('spam', 'eggs')
+
+In many cases you will just be able to add `autospec=True` to your existing
+`patch` calls and then be protected against bugs due to typos and api
+changes.
+
+As well as using `autospec` through `patch` there is a
+:func:`create_autospec` for creating autospecced mocks directly:
+
+ >>> from urllib import request
+ >>> mock_request = create_autospec(request)
+ >>> mock_request.Request('foo', 'bar')
+ <NonCallableMagicMock name='mock.Request()' spec='Request' id='...'>
+
+This isn't without caveats and limitations however, which is why it is not
+the default behaviour. In order to know what attributes are available on the
+spec object, autospec has to introspect (access attributes) the spec. As you
+traverse attributes on the mock a corresponding traversal of the original
+object is happening under the hood. If any of your specced objects have
+properties or descriptors that can trigger code execution then you may not be
+able to use autospec. On the other hand it is much better to design your
+objects so that introspection is safe [#]_.
+
+A more serious problem is that it is common for instance attributes to be
+created in the `__init__` method and not to exist on the class at all.
+`autospec` can't know about any dynamically created attributes and restricts
+the api to visible attributes.
+
+ >>> class Something(object):
+ ... def __init__(self):
+ ... self.a = 33
+ ...
+ >>> with patch('__main__.Something', autospec=True):
+ ... thing = Something()
+ ... thing.a
+ ...
+ Traceback (most recent call last):
+ ...
+ AttributeError: Mock object has no attribute 'a'
+
+There are a few different ways of resolving this problem. The easiest, but
+not necessarily the least annoying, way is to simply set the required
+attributes on the mock after creation. Just because `autospec` doesn't allow
+you to fetch attributes that don't exist on the spec it doesn't prevent you
+setting them:
+
+ >>> with patch('__main__.Something', autospec=True):
+ ... thing = Something()
+ ... thing.a = 33
+ ...
+
+There is a more aggressive version of both `spec` and `autospec` that *does*
+prevent you setting non-existent attributes. This is useful if you want to
+ensure your code only *sets* valid attributes too, but obviously it prevents
+this particular scenario:
+
+ >>> with patch('__main__.Something', autospec=True, spec_set=True):
+ ... thing = Something()
+ ... thing.a = 33
+ ...
+ Traceback (most recent call last):
+ ...
+ AttributeError: Mock object has no attribute 'a'
+
+Probably the best way of solving the problem is to add class attributes as
+default values for instance members initialised in `__init__`. Note that if
+you are only setting default attributes in `__init__` then providing them via
+class attributes (shared between instances of course) is faster too. e.g.
+
+.. code-block:: python
+
+ class Something(object):
+ a = 33
+
+This brings up another issue. It is relatively common to provide a default
+value of `None` for members that will later be an object of a different type.
+`None` would be useless as a spec because it wouldn't let you access *any*
+attributes or methods on it. As `None` is *never* going to be useful as a
+spec, and probably indicates a member that will normally of some other type,
+`autospec` doesn't use a spec for members that are set to `None`. These will
+just be ordinary mocks (well - `MagicMocks`):
+
+ >>> class Something(object):
+ ... member = None
+ ...
+ >>> mock = create_autospec(Something)
+ >>> mock.member.foo.bar.baz()
+ <MagicMock name='mock.member.foo.bar.baz()' id='...'>
+
+If modifying your production classes to add defaults isn't to your liking
+then there are more options. One of these is simply to use an instance as the
+spec rather than the class. The other is to create a subclass of the
+production class and add the defaults to the subclass without affecting the
+production class. Both of these require you to use an alternative object as
+the spec. Thankfully `patch` supports this - you can simply pass the
+alternative object as the `autospec` argument:
+
+ >>> class Something(object):
+ ... def __init__(self):
+ ... self.a = 33
+ ...
+ >>> class SomethingForTest(Something):
+ ... a = 33
+ ...
+ >>> p = patch('__main__.Something', autospec=SomethingForTest)
+ >>> mock = p.start()
+ >>> mock.a
+ <NonCallableMagicMock name='Something.a' spec='int' id='...'>
+
+
+.. [#] This only applies to classes or already instantiated objects. Calling
+ a mocked class to create a mock instance *does not* create a real instance.
+ It is only attribute lookups - along with calls to `dir` - that are done.
+
diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -5,65 +5,40 @@
:synopsis: Implementation of the ElementTree API.
.. moduleauthor:: Fredrik Lundh <fredrik at pythonware.com>
-**Source code:** :source:`Lib/xml/etree/ElementTree.py`
-
---------------
-
-The :class:`Element` type is a flexible container object, designed to store
-hierarchical data structures in memory. The type can be described as a cross
-between a list and a dictionary.
-
-Each element has a number of properties associated with it:
-
-* a tag which is a string identifying what kind of data this element represents
- (the element type, in other words).
-
-* a number of attributes, stored in a Python dictionary.
-
-* a text string.
-
-* an optional tail string.
-
-* a number of child elements, stored in a Python sequence
-
-To create an element instance, use the :class:`Element` constructor or the
-:func:`SubElement` factory function.
-
-The :class:`ElementTree` class can be used to wrap an element structure, and
-convert it from and to XML.
-
-See http://effbot.org/zone/element-index.htm for tutorials and links to other
-docs.
-
-.. versionchanged:: 3.2
- The ElementTree API is updated to 1.3. For more information, see
- `Introducing ElementTree 1.3
- <http://effbot.org/zone/elementtree-13-intro.htm>`_.
+The :mod:`xml.etree.ElementTree` module implements a simple and efficient API
+for parsing and creating XML data.
.. versionchanged:: 3.3
This module will use a fast implementation whenever available.
The :mod:`xml.etree.cElementTree` module is deprecated.
+Tutorial
+--------
-.. _elementtree-xpath:
+This is a short tutorial for using :mod:`xml.etree.ElementTree` (``ET`` in
+short). The goal is to demonstrate some of the building blocks and basic
+concepts of the module.
-XPath support
--------------
+XML tree and elements
+^^^^^^^^^^^^^^^^^^^^^
-This module provides limited support for
-`XPath expressions <http://www.w3.org/TR/xpath>`_ for locating elements in a
-tree. The goal is to support a small subset of the abbreviated syntax; a full
-XPath engine is outside the scope of the module.
+XML is an inherently hierarchical data format, and the most natural way to
+represent it is with a tree. ``ET`` has two classes for this purpose -
+:class:`ElementTree` represents the whole XML document as a tree, and
+:class:`Element` represents a single node in this tree. Interactions with
+the whole document (reading and writing to/from files) are usually done
+on the :class:`ElementTree` level. Interactions with a single XML element
+and its sub-elements are done on the :class:`Element` level.
-Example
-^^^^^^^
+.. _elementtree-parsing-xml:
-Here's an example that demonstrates some of the XPath capabilities of the
-module::
+Parsing XML
+^^^^^^^^^^^
- import xml.etree.ElementTree as ET
+We'll be using the following XML document contained in a Python string as the
+sample data for this section::
- xml = r'''<?xml version="1.0"?>
+ countrydata = r'''<?xml version="1.0"?>
<data>
<country name="Liechtenshtein">
<rank>1</rank>
@@ -88,23 +63,121 @@
</data>
'''
- tree = ET.fromstring(xml)
+First, import the module and parse the data::
+
+ import xml.etree.ElementTree as ET
+
+ root = ET.fromstring(countrydata)
+
+:func:`fromstring` parses XML from a string directly into an :class:`Element`,
+which is the root element of the parsed tree. Other parsing functions may
+create an :class:`ElementTree`. Make sure to check the documentation to be
+sure.
+
+As an :class:`Element`, ``root`` has a tag and a dictionary of attributes::
+
+ >>> root.tag
+ 'data'
+ >>> root.attrib
+ {}
+
+It also has children nodes over which we can iterate::
+
+ >>> for child in root:
+ ... print(child.tag, child.attrib)
+ ...
+ country {'name': 'Liechtenshtein'}
+ country {'name': 'Singapore'}
+ country {'name': 'Panama'}
+
+Children are nested, and we can access specific child nodes by index::
+
+ >>> root[0][1].text
+ '2008'
+
+Finding interesting elements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:class:`Element` has some useful methods that help iterate recursively over all
+the sub-tree below it (its children, their children, and so on). For example,
+:meth:`Element.iter`::
+
+ >>> for neighbor in root.iter('neighbor'):
+ ... print(neighbor.attrib)
+ ...
+ {'name': 'Austria', 'direction': 'E'}
+ {'name': 'Switzerland', 'direction': 'W'}
+ {'name': 'Malaysia', 'direction': 'N'}
+ {'name': 'Costa Rica', 'direction': 'W'}
+ {'name': 'Colombia', 'direction': 'E'}
+
+More sophisticated specification of which elements to look for is possible by
+using :ref:`XPath <elementtree-xpath>`.
+
+Building XML documents
+^^^^^^^^^^^^^^^^^^^^^^
+
+``ET`` provides a simple way to build XML documents and write them to files.
+The :meth:`ElementTree.write` method serves this purpose.
+
+Once created, an :class:`Element` object may be manipulated by directly changing
+its fields (such as :attr:`Element.text`), adding and modifying attributes
+(:meth:`Element.set` method), as well as adding new children (for example
+with :meth:`Element.append`).
+
+The :func:`SubElement` function also provides a convenient way to create new
+sub-elements for a given element::
+
+ >>> a = ET.Element('a')
+ >>> b = ET.SubElement(a, 'b')
+ >>> c = ET.SubElement(a, 'c')
+ >>> d = ET.SubElement(c, 'd')
+ >>> ET.dump(a)
+ <a><b /><c><d /></c></a>
+
+Additional resources
+^^^^^^^^^^^^^^^^^^^^
+
+See http://effbot.org/zone/element-index.htm for tutorials and links to other
+docs.
+
+
+.. _elementtree-xpath:
+
+XPath support
+-------------
+
+This module provides limited support for
+`XPath expressions <http://www.w3.org/TR/xpath>`_ for locating elements in a
+tree. The goal is to support a small subset of the abbreviated syntax; a full
+XPath engine is outside the scope of the module.
+
+Example
+^^^^^^^
+
+Here's an example that demonstrates some of the XPath capabilities of the
+module. We'll be using the ``countrydata`` XML document from the
+:ref:`Parsing XML <elementtree-parsing-xml>` section::
+
+ import xml.etree.ElementTree as ET
+
+ root = ET.fromstring(countrydata)
# Top-level elements
- tree.findall(".")
+ root.findall(".")
# All 'neighbor' grand-children of 'country' children of the top-level
# elements
- tree.findall("./country/neighbor")
+ root.findall("./country/neighbor")
# Nodes with name='Singapore' that have a 'year' child
- tree.findall(".//year/..[@name='Singapore']")
+ root.findall(".//year/..[@name='Singapore']")
# 'year' nodes that are children of nodes with name='Singapore'
- tree.findall(".//*[@name='Singapore']/year")
+ root.findall(".//*[@name='Singapore']/year")
# All 'neighbor' nodes that are the second child of their parent
- tree.findall(".//neighbor[2]")
+ root.findall(".//neighbor[2]")
Supported XPath syntax
^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Lib/idlelib/NEWS.txt b/Lib/idlelib/NEWS.txt
--- a/Lib/idlelib/NEWS.txt
+++ b/Lib/idlelib/NEWS.txt
@@ -3,6 +3,9 @@
- IDLE can be launched as `python -m idlelib`
+- Issue #14409: IDLE doesn't not execute commands from shell,
+ error with default keybinding for Return. (Patch by Roger Serwy)
+
- Issue #3573: IDLE hangs when passing invalid command line args
(directory(ies) instead of file(s)).
diff --git a/Lib/idlelib/configHandler.py b/Lib/idlelib/configHandler.py
--- a/Lib/idlelib/configHandler.py
+++ b/Lib/idlelib/configHandler.py
@@ -596,7 +596,7 @@
'<<replace>>': ['<Control-h>'],
'<<goto-line>>': ['<Alt-g>'],
'<<smart-backspace>>': ['<Key-BackSpace>'],
- '<<newline-and-indent>>': ['<Key-Return> <Key-KP_Enter>'],
+ '<<newline-and-indent>>': ['<Key-Return>', '<Key-KP_Enter>'],
'<<smart-indent>>': ['<Key-Tab>'],
'<<indent-region>>': ['<Control-Key-bracketright>'],
'<<dedent-region>>': ['<Control-Key-bracketleft>'],
diff --git a/Lib/logging/handlers.py b/Lib/logging/handlers.py
--- a/Lib/logging/handlers.py
+++ b/Lib/logging/handlers.py
@@ -559,11 +559,16 @@
"""
ei = record.exc_info
if ei:
- dummy = self.format(record) # just to get traceback text into record.exc_text
- record.exc_info = None # to avoid Unpickleable error
- s = pickle.dumps(record.__dict__, 1)
- if ei:
- record.exc_info = ei # for next handler
+ # just to get traceback text into record.exc_text ...
+ dummy = self.format(record)
+ # See issue #14436: If msg or args are objects, they may not be
+ # available on the receiving end. So we convert the msg % args
+ # to a string, save it as msg and zap the args.
+ d = dict(record.__dict__)
+ d['msg'] = record.getMessage()
+ d['args'] = None
+ d['exc_info'] = None
+ s = pickle.dumps(d, 1)
slen = struct.pack(">L", len(s))
return slen + s
diff --git a/Lib/test/test_smtplib.py b/Lib/test/test_smtplib.py
--- a/Lib/test/test_smtplib.py
+++ b/Lib/test/test_smtplib.py
@@ -9,6 +9,7 @@
import sys
import time
import select
+import errno
import unittest
from test import support, mock_socket
diff --git a/Lib/unittest/mock.py b/Lib/unittest/mock.py
--- a/Lib/unittest/mock.py
+++ b/Lib/unittest/mock.py
@@ -1352,17 +1352,20 @@
"""
`patch` acts as a function decorator, class decorator or a context
manager. Inside the body of the function or with statement, the `target`
- (specified in the form `'package.module.ClassName'`) is patched
- with a `new` object. When the function/with statement exits the patch is
- undone.
-
- The `target` is imported and the specified attribute patched with the new
- object, so it must be importable from the environment you are calling the
- decorator from. The target is imported when the decorated function is
- executed, not at decoration time.
-
- If `new` is omitted, then a new `MagicMock` is created and passed in as an
- extra argument to the decorated function.
+ 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
+ `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.
diff --git a/Misc/ACKS b/Misc/ACKS
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -832,6 +832,7 @@
Gareth Rees
Steve Reeves
Lennart Regebro
+Federico Reghenzani
Ofir Reichenberg
Sean Reifschneider
Michael P. Reilly
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -34,6 +34,12 @@
Library
-------
+- Issue #14409: IDLE doesn't not execute commands from shell,
+ error with default keybinding for Return. (Patch by Roger Serwy)
+
+- Issue #14416: syslog now defines the LOG_ODELAY and LOG_AUTHPRIV constants
+ if they are defined in <syslog.h>.
+
- IDLE can be launched as python -m idlelib
- Issue #14295: Add unittest.mock
@@ -193,6 +199,8 @@
Tests
-----
+- Issue #14442: Add missing errno import in test_smtplib.
+
- Issue #8315: (partial fix) python -m unittest test.test_email now works.
diff --git a/Modules/syslogmodule.c b/Modules/syslogmodule.c
--- a/Modules/syslogmodule.c
+++ b/Modules/syslogmodule.c
@@ -291,6 +291,9 @@
PyModule_AddIntConstant(m, "LOG_PID", LOG_PID);
PyModule_AddIntConstant(m, "LOG_CONS", LOG_CONS);
PyModule_AddIntConstant(m, "LOG_NDELAY", LOG_NDELAY);
+#ifdef LOG_ODELAY
+ PyModule_AddIntConstant(m, "LOG_ODELAY", LOG_ODELAY);
+#endif
#ifdef LOG_NOWAIT
PyModule_AddIntConstant(m, "LOG_NOWAIT", LOG_NOWAIT);
#endif
@@ -331,5 +334,10 @@
PyModule_AddIntConstant(m, "LOG_CRON", LOG_CRON);
PyModule_AddIntConstant(m, "LOG_UUCP", LOG_UUCP);
PyModule_AddIntConstant(m, "LOG_NEWS", LOG_NEWS);
+
+#ifdef LOG_AUTHPRIV
+ PyModule_AddIntConstant(m, "LOG_AUTHPRIV", LOG_AUTHPRIV);
+#endif
+
return m;
}
diff --git a/Objects/floatobject.c b/Objects/floatobject.c
--- a/Objects/floatobject.c
+++ b/Objects/floatobject.c
@@ -16,53 +16,16 @@
/* Special free list
-
- Since some Python programs can spend much of their time allocating
- and deallocating floats, these operations should be very fast.
- Therefore we use a dedicated allocation scheme with a much lower
- overhead (in space and time) than straight malloc(): a simple
- dedicated free list, filled when necessary with memory from malloc().
-
- block_list is a singly-linked list of all PyFloatBlocks ever allocated,
- linked via their next members. PyFloatBlocks are never returned to the
- system before shutdown (PyFloat_Fini).
-
free_list is a singly-linked list of available PyFloatObjects, linked
via abuse of their ob_type members.
*/
-#define BLOCK_SIZE 1000 /* 1K less typical malloc overhead */
-#define BHEAD_SIZE 8 /* Enough for a 64-bit pointer */
-#define N_FLOATOBJECTS ((BLOCK_SIZE - BHEAD_SIZE) / sizeof(PyFloatObject))
-
-struct _floatblock {
- struct _floatblock *next;
- PyFloatObject objects[N_FLOATOBJECTS];
-};
-
-typedef struct _floatblock PyFloatBlock;
-
-static PyFloatBlock *block_list = NULL;
+#ifndef PyFloat_MAXFREELIST
+#define PyFloat_MAXFREELIST 100
+#endif
+static int numfree = 0;
static PyFloatObject *free_list = NULL;
-static PyFloatObject *
-fill_free_list(void)
-{
- PyFloatObject *p, *q;
- /* XXX Float blocks escape the object heap. Use PyObject_MALLOC ??? */
- p = (PyFloatObject *) PyMem_MALLOC(sizeof(PyFloatBlock));
- if (p == NULL)
- return (PyFloatObject *) PyErr_NoMemory();
- ((PyFloatBlock *)p)->next = block_list;
- block_list = (PyFloatBlock *)p;
- p = &((PyFloatBlock *)p)->objects[0];
- q = p + N_FLOATOBJECTS;
- while (--q > p)
- Py_TYPE(q) = (struct _typeobject *)(q-1);
- Py_TYPE(q) = NULL;
- return p + N_FLOATOBJECTS - 1;
-}
-
double
PyFloat_GetMax(void)
{
@@ -151,14 +114,16 @@
PyObject *
PyFloat_FromDouble(double fval)
{
- register PyFloatObject *op;
- if (free_list == NULL) {
- if ((free_list = fill_free_list()) == NULL)
- return NULL;
+ register PyFloatObject *op = free_list;
+ if (op != NULL) {
+ free_list = (PyFloatObject *) Py_TYPE(op);
+ numfree--;
+ } else {
+ op = (PyFloatObject*) PyObject_MALLOC(sizeof(PyFloatObject));
+ if (!op)
+ return PyErr_NoMemory();
}
/* Inline PyObject_New */
- op = free_list;
- free_list = (PyFloatObject *)Py_TYPE(op);
PyObject_INIT(op, &PyFloat_Type);
op->ob_fval = fval;
return (PyObject *) op;
@@ -217,6 +182,11 @@
float_dealloc(PyFloatObject *op)
{
if (PyFloat_CheckExact(op)) {
+ if (numfree >= PyFloat_MAXFREELIST) {
+ PyObject_FREE(op);
+ return;
+ }
+ numfree++;
Py_TYPE(op) = (struct _typeobject *)free_list;
free_list = op;
}
@@ -1932,96 +1902,22 @@
int
PyFloat_ClearFreeList(void)
{
- PyFloatObject *p;
- PyFloatBlock *list, *next;
- int i;
- int u; /* remaining unfreed floats per block */
- int freelist_size = 0;
-
- list = block_list;
- block_list = NULL;
+ PyFloatObject *f = free_list, *next;
+ int i = numfree;
+ while (f) {
+ next = (PyFloatObject*) Py_TYPE(f);
+ PyObject_FREE(f);
+ f = next;
+ }
free_list = NULL;
- while (list != NULL) {
- u = 0;
- for (i = 0, p = &list->objects[0];
- i < N_FLOATOBJECTS;
- i++, p++) {
- if (PyFloat_CheckExact(p) && Py_REFCNT(p) != 0)
- u++;
- }
- next = list->next;
- if (u) {
- list->next = block_list;
- block_list = list;
- for (i = 0, p = &list->objects[0];
- i < N_FLOATOBJECTS;
- i++, p++) {
- if (!PyFloat_CheckExact(p) ||
- Py_REFCNT(p) == 0) {
- Py_TYPE(p) = (struct _typeobject *)
- free_list;
- free_list = p;
- }
- }
- }
- else {
- PyMem_FREE(list);
- }
- freelist_size += u;
- list = next;
- }
- return freelist_size;
+ numfree = 0;
+ return i;
}
void
PyFloat_Fini(void)
{
- PyFloatObject *p;
- PyFloatBlock *list;
- int i;
- int u; /* total unfreed floats per block */
-
- u = PyFloat_ClearFreeList();
-
- if (!Py_VerboseFlag)
- return;
- fprintf(stderr, "# cleanup floats");
- if (!u) {
- fprintf(stderr, "\n");
- }
- else {
- fprintf(stderr,
- ": %d unfreed float%s\n",
- u, u == 1 ? "" : "s");
- }
- if (Py_VerboseFlag > 1) {
- list = block_list;
- while (list != NULL) {
- for (i = 0, p = &list->objects[0];
- i < N_FLOATOBJECTS;
- i++, p++) {
- if (PyFloat_CheckExact(p) &&
- Py_REFCNT(p) != 0) {
- char *buf = PyOS_double_to_string(
- PyFloat_AS_DOUBLE(p), 'r',
- 0, 0, NULL);
- if (buf) {
- /* XXX(twouters) cast
- refcount to long
- until %zd is
- universally
- available
- */
- fprintf(stderr,
- "# <float at %p, refcnt=%ld, val=%s>\n",
- p, (long)Py_REFCNT(p), buf);
- PyMem_Free(buf);
- }
- }
- }
- list = list->next;
- }
- }
+ (void)PyFloat_ClearFreeList();
}
/*----------------------------------------------------------------------------
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list