From 5f8de423f190bbb79a62f804151bc24824fa32d8 Mon Sep 17 00:00:00 2001 From: "Matt A. Tobin" Date: Fri, 2 Feb 2018 04:16:08 -0500 Subject: Add m-esr52 at 52.6.0 --- python/mock-1.0.0/LICENSE.txt | 26 + python/mock-1.0.0/MANIFEST.in | 2 + python/mock-1.0.0/PKG-INFO | 208 ++ python/mock-1.0.0/README.txt | 177 ++ python/mock-1.0.0/docs/changelog.txt | 725 ++++++ python/mock-1.0.0/docs/compare.txt | 628 ++++++ python/mock-1.0.0/docs/conf.py | 209 ++ python/mock-1.0.0/docs/examples.txt | 1063 +++++++++ python/mock-1.0.0/docs/getting-started.txt | 479 ++++ python/mock-1.0.0/docs/helpers.txt | 583 +++++ python/mock-1.0.0/docs/index.txt | 411 ++++ python/mock-1.0.0/docs/magicmock.txt | 258 +++ python/mock-1.0.0/docs/mock.txt | 842 +++++++ python/mock-1.0.0/docs/patch.txt | 636 ++++++ python/mock-1.0.0/docs/sentinel.txt | 58 + python/mock-1.0.0/html/.doctrees/changelog.doctree | Bin 0 -> 282659 bytes python/mock-1.0.0/html/.doctrees/compare.doctree | Bin 0 -> 56915 bytes python/mock-1.0.0/html/.doctrees/examples.doctree | Bin 0 -> 167478 bytes .../html/.doctrees/getting-started.doctree | Bin 0 -> 70942 bytes python/mock-1.0.0/html/.doctrees/index.doctree | Bin 0 -> 98784 bytes python/mock-1.0.0/html/.doctrees/magicmock.doctree | Bin 0 -> 75713 bytes python/mock-1.0.0/html/.doctrees/mock.doctree | Bin 0 -> 152111 bytes .../html/.doctrees/mocksignature.doctree | Bin 0 -> 42324 bytes python/mock-1.0.0/html/.doctrees/patch.doctree | Bin 0 -> 123511 bytes python/mock-1.0.0/html/.doctrees/sentinel.doctree | Bin 0 -> 10632 bytes python/mock-1.0.0/html/_sources/changelog.txt | 725 ++++++ python/mock-1.0.0/html/_sources/compare.txt | 628 ++++++ python/mock-1.0.0/html/_sources/examples.txt | 1063 +++++++++ .../mock-1.0.0/html/_sources/getting-started.txt | 479 ++++ python/mock-1.0.0/html/_sources/index.txt | 411 ++++ python/mock-1.0.0/html/_sources/magicmock.txt | 258 +++ python/mock-1.0.0/html/_sources/mock.txt | 842 +++++++ python/mock-1.0.0/html/_sources/mocksignature.txt | 262 +++ python/mock-1.0.0/html/_sources/patch.txt | 636 ++++++ python/mock-1.0.0/html/_sources/sentinel.txt | 58 + python/mock-1.0.0/html/_static/adctheme.css | 757 +++++++ python/mock-1.0.0/html/_static/basic.css | 540 +++++ .../html/_static/breadcrumb_background.png | Bin 0 -> 136 bytes python/mock-1.0.0/html/_static/default.css | 256 +++ python/mock-1.0.0/html/_static/doctools.js | 247 ++ python/mock-1.0.0/html/_static/documentation.png | Bin 0 -> 412 bytes python/mock-1.0.0/html/_static/file.png | Bin 0 -> 392 bytes python/mock-1.0.0/html/_static/header_sm_mid.png | Bin 0 -> 159 bytes python/mock-1.0.0/html/_static/jquery.js | 154 ++ python/mock-1.0.0/html/_static/minus.png | Bin 0 -> 199 bytes python/mock-1.0.0/html/_static/mobile.css | 17 + python/mock-1.0.0/html/_static/plus.png | Bin 0 -> 199 bytes python/mock-1.0.0/html/_static/pygments.css | 62 + python/mock-1.0.0/html/_static/scrn1.png | Bin 0 -> 108046 bytes python/mock-1.0.0/html/_static/scrn2.png | Bin 0 -> 121395 bytes .../html/_static/searchfield_leftcap.png | Bin 0 -> 855 bytes .../mock-1.0.0/html/_static/searchfield_repeat.png | Bin 0 -> 158 bytes .../html/_static/searchfield_rightcap.png | Bin 0 -> 530 bytes python/mock-1.0.0/html/_static/searchtools.js | 560 +++++ python/mock-1.0.0/html/_static/sidebar.js | 148 ++ .../mock-1.0.0/html/_static/title_background.png | Bin 0 -> 132 bytes python/mock-1.0.0/html/_static/toc.js | 20 + python/mock-1.0.0/html/_static/triangle_closed.png | Bin 0 -> 181 bytes python/mock-1.0.0/html/_static/triangle_left.png | Bin 0 -> 195 bytes python/mock-1.0.0/html/_static/triangle_open.png | Bin 0 -> 191 bytes python/mock-1.0.0/html/_static/underscore.js | 23 + python/mock-1.0.0/html/changelog.html | 839 +++++++ python/mock-1.0.0/html/compare.html | 672 ++++++ python/mock-1.0.0/html/examples.html | 1006 +++++++++ python/mock-1.0.0/html/genindex.html | 479 ++++ python/mock-1.0.0/html/getting-started.html | 510 +++++ python/mock-1.0.0/html/index.html | 529 +++++ python/mock-1.0.0/html/magicmock.html | 347 +++ python/mock-1.0.0/html/mock.html | 875 ++++++++ python/mock-1.0.0/html/mocksignature.html | 352 +++ python/mock-1.0.0/html/objects.inv | Bin 0 -> 711 bytes python/mock-1.0.0/html/output.txt | 126 ++ python/mock-1.0.0/html/patch.html | 648 ++++++ python/mock-1.0.0/html/search.html | 99 + python/mock-1.0.0/html/searchindex.js | 1 + python/mock-1.0.0/html/sentinel.html | 156 ++ python/mock-1.0.0/mock.py | 2356 ++++++++++++++++++++ python/mock-1.0.0/setup.cfg | 12 + python/mock-1.0.0/setup.py | 72 + python/mock-1.0.0/tests/__init__.py | 3 + python/mock-1.0.0/tests/_testwith.py | 181 ++ python/mock-1.0.0/tests/support.py | 41 + python/mock-1.0.0/tests/support_with.py | 93 + python/mock-1.0.0/tests/testcallable.py | 158 ++ python/mock-1.0.0/tests/testhelpers.py | 940 ++++++++ python/mock-1.0.0/tests/testmagicmethods.py | 486 ++++ python/mock-1.0.0/tests/testmock.py | 1351 +++++++++++ python/mock-1.0.0/tests/testpatch.py | 1790 +++++++++++++++ python/mock-1.0.0/tests/testsentinel.py | 33 + python/mock-1.0.0/tests/testwith.py | 16 + python/mock-1.0.0/tox.ini | 40 + 91 files changed, 28662 insertions(+) create mode 100644 python/mock-1.0.0/LICENSE.txt create mode 100644 python/mock-1.0.0/MANIFEST.in create mode 100644 python/mock-1.0.0/PKG-INFO create mode 100644 python/mock-1.0.0/README.txt create mode 100644 python/mock-1.0.0/docs/changelog.txt create mode 100644 python/mock-1.0.0/docs/compare.txt create mode 100644 python/mock-1.0.0/docs/conf.py create mode 100644 python/mock-1.0.0/docs/examples.txt create mode 100644 python/mock-1.0.0/docs/getting-started.txt create mode 100644 python/mock-1.0.0/docs/helpers.txt create mode 100644 python/mock-1.0.0/docs/index.txt create mode 100644 python/mock-1.0.0/docs/magicmock.txt create mode 100644 python/mock-1.0.0/docs/mock.txt create mode 100644 python/mock-1.0.0/docs/patch.txt create mode 100644 python/mock-1.0.0/docs/sentinel.txt create mode 100644 python/mock-1.0.0/html/.doctrees/changelog.doctree create mode 100644 python/mock-1.0.0/html/.doctrees/compare.doctree create mode 100644 python/mock-1.0.0/html/.doctrees/examples.doctree create mode 100644 python/mock-1.0.0/html/.doctrees/getting-started.doctree create mode 100644 python/mock-1.0.0/html/.doctrees/index.doctree create mode 100644 python/mock-1.0.0/html/.doctrees/magicmock.doctree create mode 100644 python/mock-1.0.0/html/.doctrees/mock.doctree create mode 100644 python/mock-1.0.0/html/.doctrees/mocksignature.doctree create mode 100644 python/mock-1.0.0/html/.doctrees/patch.doctree create mode 100644 python/mock-1.0.0/html/.doctrees/sentinel.doctree create mode 100644 python/mock-1.0.0/html/_sources/changelog.txt create mode 100644 python/mock-1.0.0/html/_sources/compare.txt create mode 100644 python/mock-1.0.0/html/_sources/examples.txt create mode 100644 python/mock-1.0.0/html/_sources/getting-started.txt create mode 100644 python/mock-1.0.0/html/_sources/index.txt create mode 100644 python/mock-1.0.0/html/_sources/magicmock.txt create mode 100644 python/mock-1.0.0/html/_sources/mock.txt create mode 100644 python/mock-1.0.0/html/_sources/mocksignature.txt create mode 100644 python/mock-1.0.0/html/_sources/patch.txt create mode 100644 python/mock-1.0.0/html/_sources/sentinel.txt create mode 100644 python/mock-1.0.0/html/_static/adctheme.css create mode 100644 python/mock-1.0.0/html/_static/basic.css create mode 100644 python/mock-1.0.0/html/_static/breadcrumb_background.png create mode 100644 python/mock-1.0.0/html/_static/default.css create mode 100644 python/mock-1.0.0/html/_static/doctools.js create mode 100644 python/mock-1.0.0/html/_static/documentation.png create mode 100644 python/mock-1.0.0/html/_static/file.png create mode 100644 python/mock-1.0.0/html/_static/header_sm_mid.png create mode 100644 python/mock-1.0.0/html/_static/jquery.js create mode 100644 python/mock-1.0.0/html/_static/minus.png create mode 100644 python/mock-1.0.0/html/_static/mobile.css create mode 100644 python/mock-1.0.0/html/_static/plus.png create mode 100644 python/mock-1.0.0/html/_static/pygments.css create mode 100644 python/mock-1.0.0/html/_static/scrn1.png create mode 100644 python/mock-1.0.0/html/_static/scrn2.png create mode 100644 python/mock-1.0.0/html/_static/searchfield_leftcap.png create mode 100644 python/mock-1.0.0/html/_static/searchfield_repeat.png create mode 100644 python/mock-1.0.0/html/_static/searchfield_rightcap.png create mode 100644 python/mock-1.0.0/html/_static/searchtools.js create mode 100644 python/mock-1.0.0/html/_static/sidebar.js create mode 100644 python/mock-1.0.0/html/_static/title_background.png create mode 100644 python/mock-1.0.0/html/_static/toc.js create mode 100644 python/mock-1.0.0/html/_static/triangle_closed.png create mode 100644 python/mock-1.0.0/html/_static/triangle_left.png create mode 100644 python/mock-1.0.0/html/_static/triangle_open.png create mode 100644 python/mock-1.0.0/html/_static/underscore.js create mode 100644 python/mock-1.0.0/html/changelog.html create mode 100644 python/mock-1.0.0/html/compare.html create mode 100644 python/mock-1.0.0/html/examples.html create mode 100644 python/mock-1.0.0/html/genindex.html create mode 100644 python/mock-1.0.0/html/getting-started.html create mode 100644 python/mock-1.0.0/html/index.html create mode 100644 python/mock-1.0.0/html/magicmock.html create mode 100644 python/mock-1.0.0/html/mock.html create mode 100644 python/mock-1.0.0/html/mocksignature.html create mode 100644 python/mock-1.0.0/html/objects.inv create mode 100644 python/mock-1.0.0/html/output.txt create mode 100644 python/mock-1.0.0/html/patch.html create mode 100644 python/mock-1.0.0/html/search.html create mode 100644 python/mock-1.0.0/html/searchindex.js create mode 100644 python/mock-1.0.0/html/sentinel.html create mode 100644 python/mock-1.0.0/mock.py create mode 100644 python/mock-1.0.0/setup.cfg create mode 100755 python/mock-1.0.0/setup.py create mode 100644 python/mock-1.0.0/tests/__init__.py create mode 100644 python/mock-1.0.0/tests/_testwith.py create mode 100644 python/mock-1.0.0/tests/support.py create mode 100644 python/mock-1.0.0/tests/support_with.py create mode 100644 python/mock-1.0.0/tests/testcallable.py create mode 100644 python/mock-1.0.0/tests/testhelpers.py create mode 100644 python/mock-1.0.0/tests/testmagicmethods.py create mode 100644 python/mock-1.0.0/tests/testmock.py create mode 100644 python/mock-1.0.0/tests/testpatch.py create mode 100644 python/mock-1.0.0/tests/testsentinel.py create mode 100644 python/mock-1.0.0/tests/testwith.py create mode 100644 python/mock-1.0.0/tox.ini (limited to 'python/mock-1.0.0') diff --git a/python/mock-1.0.0/LICENSE.txt b/python/mock-1.0.0/LICENSE.txt new file mode 100644 index 000000000..7891703b1 --- /dev/null +++ b/python/mock-1.0.0/LICENSE.txt @@ -0,0 +1,26 @@ +Copyright (c) 2003-2012, Michael Foord +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/python/mock-1.0.0/MANIFEST.in b/python/mock-1.0.0/MANIFEST.in new file mode 100644 index 000000000..d52b301de --- /dev/null +++ b/python/mock-1.0.0/MANIFEST.in @@ -0,0 +1,2 @@ +include LICENSE.txt tox.ini tests/*.py +recursive-include docs *.txt *.py *.png *.css *.html *.js diff --git a/python/mock-1.0.0/PKG-INFO b/python/mock-1.0.0/PKG-INFO new file mode 100644 index 000000000..4c7309c71 --- /dev/null +++ b/python/mock-1.0.0/PKG-INFO @@ -0,0 +1,208 @@ +Metadata-Version: 1.0 +Name: mock +Version: 1.0.0 +Summary: A Python Mocking and Patching Library for Testing +Home-page: http://www.voidspace.org.uk/python/mock/ +Author: Michael Foord +Author-email: michael@voidspace.org.uk +License: UNKNOWN +Description: mock is a library for testing in Python. It allows you to replace parts of + your system under test with mock objects and make assertions about how they + have been used. + + mock is now part of the Python standard library, available as `unittest.mock < + http://docs.python.org/py3k/library/unittest.mock.html#module-unittest.mock>`_ + in Python 3.3 onwards. + + mock provides a core `MagicMock` class removing the need to create a host of + stubs throughout your test suite. After performing an action, you can make + assertions about which methods / attributes were used and arguments they were + called with. You can also specify return values and set needed attributes in + the normal way. + + mock is tested on Python versions 2.4-2.7 and Python 3. mock is also tested + with the latest versions of Jython and pypy. + + The mock module also provides utility functions / objects to assist with + testing, particularly monkey patching. + + * `PDF documentation for 1.0 beta 1 + `_ + * `mock on google code (repository and issue tracker) + `_ + * `mock documentation + `_ + * `mock on PyPI `_ + * `Mailing list (testing-in-python@lists.idyll.org) + `_ + + Mock is very easy to use and is designed for use with + `unittest `_. Mock is based on + the 'action -> assertion' pattern instead of 'record -> replay' used by many + mocking frameworks. See the `mock documentation`_ for full details. + + Mock objects create all attributes and methods as you access them and store + details of how they have been used. You can configure them, to specify return + values or limit what attributes are available, and then make assertions about + how they have been used:: + + >>> from mock import Mock + >>> real = ProductionClass() + >>> real.method = Mock(return_value=3) + >>> real.method(3, 4, 5, key='value') + 3 + >>> real.method.assert_called_with(3, 4, 5, key='value') + + `side_effect` allows you to perform side effects, return different values or + raise an exception when a mock is called:: + + >>> mock = Mock(side_effect=KeyError('foo')) + >>> mock() + Traceback (most recent call last): + ... + KeyError: 'foo' + >>> values = {'a': 1, 'b': 2, 'c': 3} + >>> def side_effect(arg): + ... return values[arg] + ... + >>> mock.side_effect = side_effect + >>> mock('a'), mock('b'), mock('c') + (3, 2, 1) + >>> mock.side_effect = [5, 4, 3, 2, 1] + >>> mock(), mock(), mock() + (5, 4, 3) + + Mock has many other ways you can configure it and control its behaviour. For + example the `spec` argument configures the mock to take its specification from + another object. Attempting to access attributes or methods on the mock that + don't exist on the spec will fail with an `AttributeError`. + + The `patch` decorator / context manager makes it easy to mock classes or + objects in a module under test. The object you specify will be replaced with a + mock (or other object) during the test and restored when the test ends:: + + >>> from mock import patch + >>> @patch('test_module.ClassName1') + ... @patch('test_module.ClassName2') + ... def test(MockClass2, MockClass1): + ... test_module.ClassName1() + ... test_module.ClassName2() + + ... assert MockClass1.called + ... assert MockClass2.called + ... + >>> test() + + .. note:: + + 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. + + 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 `where to patch + `_. + + As well as a decorator `patch` can be used as a context manager in a with + statement:: + + >>> with patch.object(ProductionClass, 'method') as mock_method: + ... mock_method.return_value = None + ... real = ProductionClass() + ... real.method(1, 2, 3) + ... + >>> mock_method.assert_called_once_with(1, 2, 3) + + There is also `patch.dict` for setting values in a dictionary just during the + scope of a test 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 + + Mock supports the mocking of Python magic methods. The easiest way of + using magic methods is with the `MagicMock` class. It allows you to do + things like:: + + >>> from mock import MagicMock + >>> mock = MagicMock() + >>> mock.__str__.return_value = 'foobarbaz' + >>> str(mock) + 'foobarbaz' + >>> mock.__str__.assert_called_once_with() + + Mock allows you to assign functions (or other Mock instances) to magic methods + and they will be called appropriately. The MagicMock class is just a Mock + variant that has all of the magic methods pre-created for you (well - all the + useful ones anyway). + + The following is an example of using magic methods with the ordinary Mock + class:: + + >>> from mock import Mock + >>> mock = Mock() + >>> mock.__str__ = Mock(return_value = 'wheeeeee') + >>> str(mock) + 'wheeeeee' + + For ensuring that the mock objects your tests use have the same api as the + objects they are replacing, you can use "auto-speccing". Auto-speccing can + be done through the `autospec` argument to patch, or the `create_autospec` + function. Auto-speccing creates mock objects that have the same attributes + and methods as the objects they are replacing, and any functions and methods + (including constructors) have the same call signature as the real object. + + This ensures that your mocks will fail in the same way as your production + code if they are used incorrectly:: + + >>> from mock import create_autospec + >>> def function(a, b, c): + ... pass + ... + >>> mock_function = create_autospec(function, return_value='fishy') + >>> mock_function(1, 2, 3) + 'fishy' + >>> mock_function.assert_called_once_with(1, 2, 3) + >>> mock_function('wrong arguments') + Traceback (most recent call last): + ... + TypeError: () takes exactly 3 arguments (1 given) + + `create_autospec` can also be used on classes, where it copies the signature of + the `__init__` method, and on callable objects where it copies the signature of + the `__call__` method. + + The distribution contains tests and documentation. The tests require + `unittest2 `_ to run. + + Docs from the in-development version of `mock` can be found at + `mock.readthedocs.org `_. + +Keywords: testing,test,mock,mocking,unittest,patching,stubs,fakes,doubles +Platform: UNKNOWN +Classifier: Development Status :: 5 - Production/Stable +Classifier: Environment :: Console +Classifier: Intended Audience :: Developers +Classifier: License :: OSI Approved :: BSD License +Classifier: Programming Language :: Python +Classifier: Programming Language :: Python :: 2 +Classifier: Programming Language :: Python :: 3 +Classifier: Programming Language :: Python :: 2.4 +Classifier: Programming Language :: Python :: 2.5 +Classifier: Programming Language :: Python :: 2.6 +Classifier: Programming Language :: Python :: 2.7 +Classifier: Programming Language :: Python :: 3.1 +Classifier: Programming Language :: Python :: 3.2 +Classifier: Programming Language :: Python :: Implementation :: CPython +Classifier: Programming Language :: Python :: Implementation :: PyPy +Classifier: Programming Language :: Python :: Implementation :: Jython +Classifier: Operating System :: OS Independent +Classifier: Topic :: Software Development :: Libraries +Classifier: Topic :: Software Development :: Libraries :: Python Modules +Classifier: Topic :: Software Development :: Testing diff --git a/python/mock-1.0.0/README.txt b/python/mock-1.0.0/README.txt new file mode 100644 index 000000000..385db3cae --- /dev/null +++ b/python/mock-1.0.0/README.txt @@ -0,0 +1,177 @@ +mock is a library for testing in Python. It allows you to replace parts of +your system under test with mock objects and make assertions about how they +have been used. + +mock is now part of the Python standard library, available as `unittest.mock < +http://docs.python.org/py3k/library/unittest.mock.html#module-unittest.mock>`_ +in Python 3.3 onwards. + +mock provides a core `MagicMock` class removing the need to create a host of +stubs throughout your test suite. After performing an action, you can make +assertions about which methods / attributes were used and arguments they were +called with. You can also specify return values and set needed attributes in +the normal way. + +mock is tested on Python versions 2.4-2.7 and Python 3. mock is also tested +with the latest versions of Jython and pypy. + +The mock module also provides utility functions / objects to assist with +testing, particularly monkey patching. + +* `PDF documentation for 1.0 beta 1 + `_ +* `mock on google code (repository and issue tracker) + `_ +* `mock documentation + `_ +* `mock on PyPI `_ +* `Mailing list (testing-in-python@lists.idyll.org) + `_ + +Mock is very easy to use and is designed for use with +`unittest `_. Mock is based on +the 'action -> assertion' pattern instead of 'record -> replay' used by many +mocking frameworks. See the `mock documentation`_ for full details. + +Mock objects create all attributes and methods as you access them and store +details of how they have been used. You can configure them, to specify return +values or limit what attributes are available, and then make assertions about +how they have been used:: + + >>> from mock import Mock + >>> real = ProductionClass() + >>> real.method = Mock(return_value=3) + >>> real.method(3, 4, 5, key='value') + 3 + >>> real.method.assert_called_with(3, 4, 5, key='value') + +`side_effect` allows you to perform side effects, return different values or +raise an exception when a mock is called:: + + >>> mock = Mock(side_effect=KeyError('foo')) + >>> mock() + Traceback (most recent call last): + ... + KeyError: 'foo' + >>> values = {'a': 1, 'b': 2, 'c': 3} + >>> def side_effect(arg): + ... return values[arg] + ... + >>> mock.side_effect = side_effect + >>> mock('a'), mock('b'), mock('c') + (3, 2, 1) + >>> mock.side_effect = [5, 4, 3, 2, 1] + >>> mock(), mock(), mock() + (5, 4, 3) + +Mock has many other ways you can configure it and control its behaviour. For +example the `spec` argument configures the mock to take its specification from +another object. Attempting to access attributes or methods on the mock that +don't exist on the spec will fail with an `AttributeError`. + +The `patch` decorator / context manager makes it easy to mock classes or +objects in a module under test. The object you specify will be replaced with a +mock (or other object) during the test and restored when the test ends:: + + >>> from mock import patch + >>> @patch('test_module.ClassName1') + ... @patch('test_module.ClassName2') + ... def test(MockClass2, MockClass1): + ... test_module.ClassName1() + ... test_module.ClassName2() + + ... assert MockClass1.called + ... assert MockClass2.called + ... + >>> test() + +.. note:: + + 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. + + 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 `where to patch + `_. + +As well as a decorator `patch` can be used as a context manager in a with +statement:: + + >>> with patch.object(ProductionClass, 'method') as mock_method: + ... mock_method.return_value = None + ... real = ProductionClass() + ... real.method(1, 2, 3) + ... + >>> mock_method.assert_called_once_with(1, 2, 3) + +There is also `patch.dict` for setting values in a dictionary just during the +scope of a test 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 + +Mock supports the mocking of Python magic methods. The easiest way of +using magic methods is with the `MagicMock` class. It allows you to do +things like:: + + >>> from mock import MagicMock + >>> mock = MagicMock() + >>> mock.__str__.return_value = 'foobarbaz' + >>> str(mock) + 'foobarbaz' + >>> mock.__str__.assert_called_once_with() + +Mock allows you to assign functions (or other Mock instances) to magic methods +and they will be called appropriately. The MagicMock class is just a Mock +variant that has all of the magic methods pre-created for you (well - all the +useful ones anyway). + +The following is an example of using magic methods with the ordinary Mock +class:: + + >>> from mock import Mock + >>> mock = Mock() + >>> mock.__str__ = Mock(return_value = 'wheeeeee') + >>> str(mock) + 'wheeeeee' + +For ensuring that the mock objects your tests use have the same api as the +objects they are replacing, you can use "auto-speccing". Auto-speccing can +be done through the `autospec` argument to patch, or the `create_autospec` +function. Auto-speccing creates mock objects that have the same attributes +and methods as the objects they are replacing, and any functions and methods +(including constructors) have the same call signature as the real object. + +This ensures that your mocks will fail in the same way as your production +code if they are used incorrectly:: + + >>> from mock import create_autospec + >>> def function(a, b, c): + ... pass + ... + >>> mock_function = create_autospec(function, return_value='fishy') + >>> mock_function(1, 2, 3) + 'fishy' + >>> mock_function.assert_called_once_with(1, 2, 3) + >>> mock_function('wrong arguments') + Traceback (most recent call last): + ... + TypeError: () takes exactly 3 arguments (1 given) + +`create_autospec` can also be used on classes, where it copies the signature of +the `__init__` method, and on callable objects where it copies the signature of +the `__call__` method. + +The distribution contains tests and documentation. The tests require +`unittest2 `_ to run. + +Docs from the in-development version of `mock` can be found at +`mock.readthedocs.org `_. diff --git a/python/mock-1.0.0/docs/changelog.txt b/python/mock-1.0.0/docs/changelog.txt new file mode 100644 index 000000000..a605be3d9 --- /dev/null +++ b/python/mock-1.0.0/docs/changelog.txt @@ -0,0 +1,725 @@ +.. currentmodule:: mock + + +CHANGELOG +========= + +2012/10/07 Version 1.0.0 +------------------------ + +No changes since 1.0.0 beta 1. This version has feature parity with +`unittest.mock +`_ +in Python 3.3. + +Full list of changes since 0.8: + +* `mocksignature`, along with the `mocksignature` argument to `patch`, removed +* Support for deleting attributes (accessing deleted attributes will raise an + `AttributeError`) +* Added the `mock_open` helper function for mocking the builtin `open` +* `__class__` is assignable, so a mock can pass an `isinstance` check without + requiring a spec +* Addition of `PropertyMock`, for mocking properties +* `MagicMocks` made unorderable by default (in Python 3). The comparison + methods (other than equality and inequality) now return `NotImplemented` +* Propagate traceback info to support subclassing of `_patch` by other + libraries +* `create_autospec` works with attributes present in results of `dir` that + can't be fetched from the object's class. Contributed by Konstantine Rybnikov +* Any exceptions in an iterable `side_effect` will be raised instead of + returned +* In Python 3, `create_autospec` now supports keyword only arguments +* Added `patch.stopall` method to stop all active patches created by `start` +* BUGFIX: calling `MagicMock.reset_mock` wouldn't reset magic method mocks +* BUGFIX: calling `reset_mock` on a `MagicMock` created with autospec could + raise an exception +* BUGFIX: passing multiple spec arguments to patchers (`spec` , `spec_set` and + `autospec`) had unpredictable results, now it is an error +* BUGFIX: using `spec=True` *and* `create=True` as arguments to patchers could + result in using `DEFAULT` as the spec. Now it is an error instead +* BUGFIX: using `spec` or `autospec` arguments to patchers, along with + `spec_set=True` did not work correctly +* BUGFIX: using an object that evaluates to False as a spec could be ignored +* BUGFIX: a list as the `spec` argument to a patcher would always result in a + non-callable mock. Now if `__call__` is in the spec the mock is callable + + +2012/07/13 Version 1.0.0 beta 1 +-------------------------------- + +* Added `patch.stopall` method to stop all active patches created by `start` +* BUGFIX: calling `MagicMock.reset_mock` wouldn't reset magic method mocks +* BUGFIX: calling `reset_mock` on a `MagicMock` created with autospec could + raise an exception + + +2012/05/04 Version 1.0.0 alpha 2 +-------------------------------- + +* `PropertyMock` attributes are now standard `MagicMocks` +* `create_autospec` works with attributes present in results of `dir` that + can't be fetched from the object's class. Contributed by Konstantine Rybnikov +* Any exceptions in an iterable `side_effect` will be raised instead of + returned +* In Python 3, `create_autospec` now supports keyword only arguments + + +2012/03/25 Version 1.0.0 alpha 1 +-------------------------------- + +The standard library version! + +* `mocksignature`, along with the `mocksignature` argument to `patch`, removed +* Support for deleting attributes (accessing deleted attributes will raise an + `AttributeError`) +* Added the `mock_open` helper function for mocking the builtin `open` +* `__class__` is assignable, so a mock can pass an `isinstance` check without + requiring a spec +* Addition of `PropertyMock`, for mocking properties +* `MagicMocks` made unorderable by default (in Python 3). The comparison + methods (other than equality and inequality) now return `NotImplemented` +* Propagate traceback info to support subclassing of `_patch` by other + libraries +* BUGFIX: passing multiple spec arguments to patchers (`spec` , `spec_set` and + `autospec`) had unpredictable results, now it is an error +* BUGFIX: using `spec=True` *and* `create=True` as arguments to patchers could + result in using `DEFAULT` as the spec. Now it is an error instead +* BUGFIX: using `spec` or `autospec` arguments to patchers, along with + `spec_set=True` did not work correctly +* BUGFIX: using an object that evaluates to False as a spec could be ignored +* BUGFIX: a list as the `spec` argument to a patcher would always result in a + non-callable mock. Now if `__call__` is in the spec the mock is callable + + +2012/02/13 Version 0.8.0 +------------------------ + +The only changes since 0.8rc2 are: + +* Improved repr of :data:`sentinel` objects +* :data:`ANY` can be used for comparisons against :data:`call` objects +* The return value of `MagicMock.__iter__` method can be set to + any iterable and isn't required to be an iterator + +Full List of changes since 0.7: + +mock 0.8.0 is the last version that will support Python 2.4. + +* Addition of :attr:`~Mock.mock_calls` list for *all* calls (including magic + methods and chained calls) +* :func:`patch` and :func:`patch.object` now create a :class:`MagicMock` + instead of a :class:`Mock` by default +* The patchers (`patch`, `patch.object` and `patch.dict`), plus `Mock` and + `MagicMock`, take arbitrary keyword arguments for configuration +* New mock method :meth:`~Mock.configure_mock` for setting attributes and + return values / side effects on the mock and its attributes +* New mock assert methods :meth:`~Mock.assert_any_call` and + :meth:`~Mock.assert_has_calls` +* Implemented :ref:`auto-speccing` (recursive, lazy speccing of mocks with + mocked signatures for functions/methods), as the `autospec` argument to + `patch` +* Added the :func:`create_autospec` function for manually creating + 'auto-specced' mocks +* :func:`patch.multiple` for doing multiple patches in a single call, using + keyword arguments +* Setting :attr:`~Mock.side_effect` to an iterable will cause calls to the mock + to return the next value from the iterable +* New `new_callable` argument to `patch` and `patch.object` allowing you to + pass in a class or callable object (instead of `MagicMock`) that will be + called to replace the object being patched +* Addition of :class:`NonCallableMock` and :class:`NonCallableMagicMock`, mocks + without a `__call__` method +* Addition of :meth:`~Mock.mock_add_spec` method for adding (or changing) a + spec on an existing mock +* Protocol methods on :class:`MagicMock` are magic mocks, and are created + lazily on first lookup. This means the result of calling a protocol method is + a `MagicMock` instead of a `Mock` as it was previously +* Addition of :meth:`~Mock.attach_mock` method +* Added :data:`ANY` for ignoring arguments in :meth:`~Mock.assert_called_with` + calls +* Addition of :data:`call` helper object +* Improved repr for mocks +* Improved repr for :attr:`Mock.call_args` and entries in + :attr:`Mock.call_args_list`, :attr:`Mock.method_calls` and + :attr:`Mock.mock_calls` +* Improved repr for :data:`sentinel` objects +* `patch` lookup is done at use time not at decoration time +* In Python 2.6 or more recent, `dir` on a mock will report all the dynamically + created attributes (or the full list of attributes if there is a spec) as + well as all the mock methods and attributes. +* Module level :data:`FILTER_DIR` added to control whether `dir(mock)` filters + private attributes. `True` by default. +* `patch.TEST_PREFIX` for controlling how patchers recognise test methods when + used to decorate a class +* Support for using Java exceptions as a :attr:`~Mock.side_effect` on Jython +* `Mock` call lists (`call_args_list`, `method_calls` & `mock_calls`) are now + custom list objects that allow membership tests for "sub lists" and have + a nicer representation if you `str` or `print` them +* Mocks attached as attributes or return values to other mocks have calls + recorded in `method_calls` and `mock_calls` of the parent (unless a name is + already set on the child) +* Improved failure messages for `assert_called_with` and + `assert_called_once_with` +* The return value of the :class:`MagicMock` `__iter__` method can be set to + any iterable and isn't required to be an iterator +* Added the Mock API (`assert_called_with` etc) to functions created by + :func:`mocksignature` +* Tuples as well as lists can be used to specify allowed methods for `spec` & + `spec_set` arguments +* Calling `stop` on an unstarted patcher fails with a more meaningful error + message +* Renamed the internal classes `Sentinel` and `SentinelObject` to prevent abuse +* BUGFIX: an error creating a patch, with nested patch decorators, won't leave + patches in place +* BUGFIX: `__truediv__` and `__rtruediv__` not available as magic methods on + mocks in Python 3 +* BUGFIX: `assert_called_with` / `assert_called_once_with` can be used with + `self` as a keyword argument +* BUGFIX: when patching a class with an explicit spec / spec_set (not a + boolean) it applies "spec inheritance" to the return value of the created + mock (the "instance") +* BUGFIX: remove the `__unittest` marker causing traceback truncation +* Removal of deprecated `patch_object` +* Private attributes `_name`, `_methods`, '_children', `_wraps` and `_parent` + (etc) renamed to reduce likelihood of clash with user attributes. +* Added license file to the distribution + + +2012/01/10 Version 0.8.0 release candidate 2 +-------------------------------------------- + +* Removed the `configure` keyword argument to `create_autospec` and allow + arbitrary keyword arguments (for the `Mock` constructor) instead +* Fixed `ANY` equality with some types in `assert_called_with` calls +* Switched to a standard Sphinx theme (compatible with + `readthedocs.org `_) + + +2011/12/29 Version 0.8.0 release candidate 1 +-------------------------------------------- + +* `create_autospec` on the return value of a mocked class will use `__call__` + for the signature rather than `__init__` +* Performance improvement instantiating `Mock` and `MagicMock` +* Mocks used as magic methods have the same type as their parent instead of + being hardcoded to `MagicMock` + +Special thanks to Julian Berman for his help with diagnosing and improving +performance in this release. + + +2011/10/09 Version 0.8.0 beta 4 +------------------------------- + +* `patch` lookup is done at use time not at decoration time +* When attaching a Mock to another Mock as a magic method, calls are recorded + in mock_calls +* Addition of `attach_mock` method +* Renamed the internal classes `Sentinel` and `SentinelObject` to prevent abuse +* BUGFIX: various issues around circular references with mocks (setting a mock + return value to be itself etc) + + +2011/08/15 Version 0.8.0 beta 3 +------------------------------- + +* Mocks attached as attributes or return values to other mocks have calls + recorded in `method_calls` and `mock_calls` of the parent (unless a name is + already set on the child) +* Addition of `mock_add_spec` method for adding (or changing) a spec on an + existing mock +* Improved repr for `Mock.call_args` and entries in `Mock.call_args_list`, + `Mock.method_calls` and `Mock.mock_calls` +* Improved repr for mocks +* BUGFIX: minor fixes in the way `mock_calls` is worked out, + especially for "intermediate" mocks in a call chain + + +2011/08/05 Version 0.8.0 beta 2 +------------------------------- + +* Setting `side_effect` to an iterable will cause calls to the mock to return + the next value from the iterable +* Added `assert_any_call` method +* Moved `assert_has_calls` from call lists onto mocks +* BUGFIX: `call_args` and all members of `call_args_list` are two tuples of + `(args, kwargs)` again instead of three tuples of `(name, args, kwargs)` + + +2011/07/25 Version 0.8.0 beta 1 +------------------------------- + +* `patch.TEST_PREFIX` for controlling how patchers recognise test methods when + used to decorate a class +* `Mock` call lists (`call_args_list`, `method_calls` & `mock_calls`) are now + custom list objects that allow membership tests for "sub lists" and have + an `assert_has_calls` method for unordered call checks +* `callargs` changed to *always* be a three-tuple of `(name, args, kwargs)` +* Addition of `mock_calls` list for *all* calls (including magic methods and + chained calls) +* Extension of `call` object to support chained calls and `callargs` for better + comparisons with or without names. `call` object has a `call_list` method for + chained calls +* Added the public `instance` argument to `create_autospec` +* Support for using Java exceptions as a `side_effect` on Jython +* Improved failure messages for `assert_called_with` and + `assert_called_once_with` +* Tuples as well as lists can be used to specify allowed methods for `spec` & + `spec_set` arguments +* BUGFIX: Fixed bug in `patch.multiple` for argument passing when creating + mocks +* Added license file to the distribution + + +2011/07/16 Version 0.8.0 alpha 2 +-------------------------------- + +* `patch.multiple` for doing multiple patches in a single call, using keyword + arguments +* New `new_callable` argument to `patch` and `patch.object` allowing you to + pass in a class or callable object (instead of `MagicMock`) that will be + called to replace the object being patched +* Addition of `NonCallableMock` and `NonCallableMagicMock`, mocks without a + `__call__` method +* Mocks created by `patch` have a `MagicMock` as the `return_value` where a + class is being patched +* `create_autospec` can create non-callable mocks for non-callable objects. + `return_value` mocks of classes will be non-callable unless the class has + a `__call__` method +* `autospec` creates a `MagicMock` without a spec for properties and slot + descriptors, because we don't know the type of object they return +* Removed the "inherit" argument from `create_autospec` +* Calling `stop` on an unstarted patcher fails with a more meaningful error + message +* BUGFIX: an error creating a patch, with nested patch decorators, won't leave + patches in place +* BUGFIX: `__truediv__` and `__rtruediv__` not available as magic methods on + mocks in Python 3 +* BUGFIX: `assert_called_with` / `assert_called_once_with` can be used with + `self` as a keyword argument +* BUGFIX: autospec for functions / methods with an argument named self that + isn't the first argument no longer broken +* BUGFIX: when patching a class with an explicit spec / spec_set (not a + boolean) it applies "spec inheritance" to the return value of the created + mock (the "instance") +* BUGFIX: remove the `__unittest` marker causing traceback truncation + + +2011/06/14 Version 0.8.0 alpha 1 +-------------------------------- + +mock 0.8.0 is the last version that will support Python 2.4. + +* The patchers (`patch`, `patch.object` and `patch.dict`), plus `Mock` and + `MagicMock`, take arbitrary keyword arguments for configuration +* New mock method `configure_mock` for setting attributes and return values / + side effects on the mock and its attributes +* In Python 2.6 or more recent, `dir` on a mock will report all the dynamically + created attributes (or the full list of attributes if there is a spec) as + well as all the mock methods and attributes. +* Module level `FILTER_DIR` added to control whether `dir(mock)` filters + private attributes. `True` by default. Note that `vars(Mock())` can still be + used to get all instance attributes and `dir(type(Mock())` will still return + all the other attributes (irrespective of `FILTER_DIR`) +* `patch` and `patch.object` now create a `MagicMock` instead of a `Mock` by + default +* Added `ANY` for ignoring arguments in `assert_called_with` calls +* Addition of `call` helper object +* Protocol methods on `MagicMock` are magic mocks, and are created lazily on + first lookup. This means the result of calling a protocol method is a + MagicMock instead of a Mock as it was previously +* Added the Mock API (`assert_called_with` etc) to functions created by + `mocksignature` +* Private attributes `_name`, `_methods`, '_children', `_wraps` and `_parent` + (etc) renamed to reduce likelihood of clash with user attributes. +* Implemented auto-speccing (recursive, lazy speccing of mocks with mocked + signatures for functions/methods) + + Limitations: + + - Doesn't mock magic methods or attributes (it creates MagicMocks, so the + magic methods are *there*, they just don't have the signature mocked nor + are attributes followed) + - Doesn't mock function / method attributes + - Uses object traversal on the objects being mocked to determine types - so + properties etc may be triggered + - The return value of mocked classes (the 'instance') has the same call + signature as the class __init__ (as they share the same spec) + + You create auto-specced mocks by passing `autospec=True` to `patch`. + + Note that attributes that are None are special cased and mocked without a + spec (so any attribute / method can be used). This is because None is + typically used as a default value for attributes that may be of some other + type, and as we don't know what type that may be we allow all access. + + Note that the `autospec` option to `patch` obsoletes the `mocksignature` + option. + +* Added the `create_autospec` function for manually creating 'auto-specced' + mocks +* Removal of deprecated `patch_object` + + +2011/05/30 Version 0.7.2 +------------------------ + +* BUGFIX: instances of list subclasses can now be used as mock specs +* BUGFIX: MagicMock equality / inequality protocol methods changed to use the + default equality / inequality. This is done through a `side_effect` on + the mocks used for `__eq__` / `__ne__` + + +2011/05/06 Version 0.7.1 +------------------------ + +Package fixes contributed by Michael Fladischer. No code changes. + +* Include template in package +* Use isolated binaries for the tox tests +* Unset executable bit on docs +* Fix DOS line endings in getting-started.txt + + +2011/03/05 Version 0.7.0 +------------------------ + +No API changes since 0.7.0 rc1. Many documentation changes including a stylish +new `Sphinx theme `_. + +The full set of changes since 0.6.0 are: + +* Python 3 compatibility +* Ability to mock magic methods with `Mock` and addition of `MagicMock` + with pre-created magic methods +* Addition of `mocksignature` and `mocksignature` argument to `patch` and + `patch.object` +* Addition of `patch.dict` for changing dictionaries during a test +* Ability to use `patch`, `patch.object` and `patch.dict` as class decorators +* Renamed ``patch_object`` to `patch.object` (``patch_object`` is + deprecated) +* Addition of soft comparisons: `call_args`, `call_args_list` and `method_calls` + now return tuple-like objects which compare equal even when empty args + or kwargs are skipped +* patchers (`patch`, `patch.object` and `patch.dict`) have start and stop + methods +* Addition of `assert_called_once_with` method +* Mocks can now be named (`name` argument to constructor) and the name is used + in the repr +* repr of a mock with a spec includes the class name of the spec +* `assert_called_with` works with `python -OO` +* New `spec_set` keyword argument to `Mock` and `patch`. If used, + attempting to *set* an attribute on a mock not on the spec will raise an + `AttributeError` +* Mocks created with a spec can now pass `isinstance` tests (`__class__` + returns the type of the spec) +* Added docstrings to all objects +* Improved failure message for `Mock.assert_called_with` when the mock + has not been called at all +* Decorated functions / methods have their docstring and `__module__` + preserved on Python 2.4. +* BUGFIX: `mock.patch` now works correctly with certain types of objects that + proxy attribute access, like the django settings object +* BUGFIX: mocks are now copyable (thanks to Ned Batchelder for reporting and + diagnosing this) +* BUGFIX: `spec=True` works with old style classes +* BUGFIX: ``help(mock)`` works now (on the module). Can no longer use ``__bases__`` + as a valid sentinel name (thanks to Stephen Emslie for reporting and + diagnosing this) +* BUGFIX: ``side_effect`` now works with ``BaseException`` exceptions like + ``KeyboardInterrupt`` +* BUGFIX: `reset_mock` caused infinite recursion when a mock is set as its own + return value +* BUGFIX: patching the same object twice now restores the patches correctly +* with statement tests now skipped on Python 2.4 +* Tests require unittest2 (or unittest2-py3k) to run +* Tested with `tox `_ on Python 2.4 - 3.2, + jython and pypy (excluding 3.0) +* Added 'build_sphinx' command to setup.py (requires setuptools or distribute) + Thanks to Florian Bauer +* Switched from subversion to mercurial for source code control +* `Konrad Delong `_ added as co-maintainer + + +2011/02/16 Version 0.7.0 RC 1 +----------------------------- + +Changes since beta 4: + +* Tested with jython, pypy and Python 3.2 and 3.1 +* Decorated functions / methods have their docstring and `__module__` + preserved on Python 2.4 +* BUGFIX: `mock.patch` now works correctly with certain types of objects that + proxy attribute access, like the django settings object +* BUGFIX: `reset_mock` caused infinite recursion when a mock is set as its own + return value + + +2010/11/12 Version 0.7.0 beta 4 +------------------------------- + +* patchers (`patch`, `patch.object` and `patch.dict`) have start and stop + methods +* Addition of `assert_called_once_with` method +* repr of a mock with a spec includes the class name of the spec +* `assert_called_with` works with `python -OO` +* New `spec_set` keyword argument to `Mock` and `patch`. If used, + attempting to *set* an attribute on a mock not on the spec will raise an + `AttributeError` +* Attributes and return value of a `MagicMock` are `MagicMock` objects +* Attempting to set an unsupported magic method now raises an `AttributeError` +* `patch.dict` works as a class decorator +* Switched from subversion to mercurial for source code control +* BUGFIX: mocks are now copyable (thanks to Ned Batchelder for reporting and + diagnosing this) +* BUGFIX: `spec=True` works with old style classes +* BUGFIX: `mocksignature=True` can now patch instance methods via + `patch.object` + + +2010/09/18 Version 0.7.0 beta 3 +------------------------------- + +* Using spec with :class:`MagicMock` only pre-creates magic methods in the spec +* Setting a magic method on a mock with a ``spec`` can only be done if the + spec has that method +* Mocks can now be named (`name` argument to constructor) and the name is used + in the repr +* `mocksignature` can now be used with classes (signature based on `__init__`) + and callable objects (signature based on `__call__`) +* Mocks created with a spec can now pass `isinstance` tests (`__class__` + returns the type of the spec) +* Default numeric value for MagicMock is 1 rather than zero (because the + MagicMock bool defaults to True and 0 is False) +* Improved failure message for :meth:`~Mock.assert_called_with` when the mock + has not been called at all +* Adding the following to the set of supported magic methods: + + - ``__getformat__`` and ``__setformat__`` + - pickle methods + - ``__trunc__``, ``__ceil__`` and ``__floor__`` + - ``__sizeof__`` + +* Added 'build_sphinx' command to setup.py (requires setuptools or distribute) + Thanks to Florian Bauer +* with statement tests now skipped on Python 2.4 +* Tests require unittest2 to run on Python 2.7 +* Improved several docstrings and documentation + + +2010/06/23 Version 0.7.0 beta 2 +------------------------------- + +* :func:`patch.dict` works as a context manager as well as a decorator +* ``patch.dict`` takes a string to specify dictionary as well as a dictionary + object. If a string is supplied the name specified is imported +* BUGFIX: ``patch.dict`` restores dictionary even when an exception is raised + + +2010/06/22 Version 0.7.0 beta 1 +------------------------------- + +* Addition of :func:`mocksignature` +* Ability to mock magic methods +* Ability to use ``patch`` and ``patch.object`` as class decorators +* Renamed ``patch_object`` to :func:`patch.object` (``patch_object`` is + deprecated) +* Addition of :class:`MagicMock` class with all magic methods pre-created for you +* Python 3 compatibility (tested with 3.2 but should work with 3.0 & 3.1 as + well) +* Addition of :func:`patch.dict` for changing dictionaries during a test +* Addition of ``mocksignature`` argument to ``patch`` and ``patch.object`` +* ``help(mock)`` works now (on the module). Can no longer use ``__bases__`` + as a valid sentinel name (thanks to Stephen Emslie for reporting and + diagnosing this) +* Addition of soft comparisons: `call_args`, `call_args_list` and `method_calls` + now return tuple-like objects which compare equal even when empty args + or kwargs are skipped +* Added docstrings. +* BUGFIX: ``side_effect`` now works with ``BaseException`` exceptions like + ``KeyboardInterrupt`` +* BUGFIX: patching the same object twice now restores the patches correctly +* The tests now require `unittest2 `_ + to run +* `Konrad Delong `_ added as co-maintainer + + +2009/08/22 Version 0.6.0 +------------------------ + +* New test layout compatible with test discovery +* Descriptors (static methods / class methods etc) can now be patched and + restored correctly +* Mocks can raise exceptions when called by setting ``side_effect`` to an + exception class or instance +* Mocks that wrap objects will not pass on calls to the underlying object if + an explicit return_value is set + + +2009/04/17 Version 0.5.0 +------------------------ + +* Made DEFAULT part of the public api. +* Documentation built with Sphinx. +* ``side_effect`` is now called with the same arguments as the mock is called with and + if returns a non-DEFAULT value that is automatically set as the ``mock.return_value``. +* ``wraps`` keyword argument used for wrapping objects (and passing calls through to the wrapped object). +* ``Mock.reset`` renamed to ``Mock.reset_mock``, as reset is a common API name. +* ``patch`` / ``patch_object`` are now context managers and can be used with ``with``. +* A new 'create' keyword argument to patch and patch_object that allows them to patch + (and unpatch) attributes that don't exist. (Potentially unsafe to use - it can allow + you to have tests that pass when they are testing an API that doesn't exist - use at + your own risk!) +* The methods keyword argument to Mock has been removed and merged with spec. The spec + argument can now be a list of methods or an object to take the spec from. +* Nested patches may now be applied in a different order (created mocks passed + in the opposite order). This is actually a bugfix. +* patch and patch_object now take a spec keyword argument. If spec is + passed in as 'True' then the Mock created will take the object it is replacing + as its spec object. If the object being replaced is a class, then the return + value for the mock will also use the class as a spec. +* A Mock created without a spec will not attempt to mock any magic methods / attributes + (they will raise an ``AttributeError`` instead). + + +2008/10/12 Version 0.4.0 +------------------------ + +* Default return value is now a new mock rather than None +* return_value added as a keyword argument to the constructor +* New method 'assert_called_with' +* Added 'side_effect' attribute / keyword argument called when mock is called +* patch decorator split into two decorators: + + - ``patch_object`` which takes an object and an attribute name to patch + (plus optionally a value to patch with which defaults to a mock object) + - ``patch`` which takes a string specifying a target to patch; in the form + 'package.module.Class.attribute'. (plus optionally a value to + patch with which defaults to a mock object) + +* Can now patch objects with ``None`` +* Change to patch for nose compatibility with error reporting in wrapped functions +* Reset no longer clears children / return value etc - it just resets + call count and call args. It also calls reset on all children (and + the return value if it is a mock). + +Thanks to Konrad Delong, Kevin Dangoor and others for patches and suggestions. + + +2007/12/03 Version 0.3.1 +------------------------- + +``patch`` maintains the name of decorated functions for compatibility with nose +test autodiscovery. + +Tests decorated with ``patch`` that use the two argument form (implicit mock +creation) will receive the mock(s) passed in as extra arguments. + +Thanks to Kevin Dangoor for these changes. + + +2007/11/30 Version 0.3.0 +------------------------- + +Removed ``patch_module``. ``patch`` can now take a string as the first +argument for patching modules. + +The third argument to ``patch`` is optional - a mock will be created by +default if it is not passed in. + + +2007/11/21 Version 0.2.1 +------------------------- + +Bug fix, allows reuse of functions decorated with ``patch`` and ``patch_module``. + + +2007/11/20 Version 0.2.0 +------------------------- + +Added ``spec`` keyword argument for creating ``Mock`` objects from a +specification object. + +Added ``patch`` and ``patch_module`` monkey patching decorators. + +Added ``sentinel`` for convenient access to unique objects. + +Distribution includes unit tests. + + +2007/11/19 Version 0.1.0 +------------------------- + +Initial release. + + +TODO and Limitations +==================== + +Contributions, bug reports and comments welcomed! + +Feature requests and bug reports are handled on the issue tracker: + + * `mock issue tracker `_ + +`wraps` is not integrated with magic methods. + +`patch` could auto-do the patching in the constructor and unpatch in the +destructor. This would be useful in itself, but violates TOOWTDI and would be +unsafe for IronPython & PyPy (non-deterministic calling of destructors). +Destructors aren't called in CPython where there are cycles, but a weak +reference with a callback can be used to get round this. + +`Mock` has several attributes. This makes it unsuitable for mocking objects +that use these attribute names. A way round this would be to provide methods +that *hide* these attributes when needed. In 0.8 many, but not all, of these +attributes are renamed to gain a `_mock` prefix, making it less likely that +they will clash. Any outstanding attributes that haven't been modified with +the prefix should be changed. + +If a patch is started using `patch.start` and then not stopped correctly then +the unpatching is not done. Using weak references it would be possible to +detect and fix this when the patch object itself is garbage collected. This +would be tricky to get right though. + +When a `Mock` is created by `patch`, arbitrary keywords can be used to set +attributes. If `patch` is created with a `spec`, and is replacing a class, then +a `return_value` mock is created. The keyword arguments are not applied to the +child mock, but could be. + +When mocking a class with `patch`, passing in `spec=True` or `autospec=True`, +the mock class has an instance created from the same spec. Should this be the +default behaviour for mocks anyway (mock return values inheriting the spec +from their parent), or should it be controlled by an additional keyword +argument (`inherit`) to the Mock constructor? `create_autospec` does this, so +an additional keyword argument to Mock is probably unnecessary. + +The `mocksignature` argument to `patch` with a non `Mock` passed into +`new_callable` will *probably* cause an error. Should it just be invalid? + +Note that `NonCallableMock` and `NonCallableMagicMock` still have the unused +(and unusable) attributes: `return_value`, `side_effect`, `call_count`, +`call_args` and `call_args_list`. These could be removed or raise errors on +getting / setting. They also have the `assert_called_with` and +`assert_called_once_with` methods. Removing these would be pointless as +fetching them would create a mock (attribute) that could be called without +error. + +Some outstanding technical debt. The way autospeccing mocks function +signatures was copied and modified from `mocksignature`. This could all be +refactored into one set of functions instead of two. The way we tell if +patchers are started and if a patcher is being used for a `patch.multiple` +call are both horrible. There are now a host of helper functions that should +be rationalised. (Probably time to split mock into a package instead of a +module.) + +Passing arbitrary keyword arguments to `create_autospec`, or `patch` with +`autospec`, when mocking a *function* works fine. However, the arbitrary +attributes are set on the created mock - but `create_autospec` returns a +real function (which doesn't have those attributes). However, what is the use +case for using autospec to create functions with attributes that don't exist +on the original? + +`mocksignature`, plus the `call_args_list` and `method_calls` attributes of +`Mock` could all be deprecated. diff --git a/python/mock-1.0.0/docs/compare.txt b/python/mock-1.0.0/docs/compare.txt new file mode 100644 index 000000000..41555308e --- /dev/null +++ b/python/mock-1.0.0/docs/compare.txt @@ -0,0 +1,628 @@ +========================= + Mock Library Comparison +========================= + + +.. testsetup:: + + def assertEqual(a, b): + assert a == b, ("%r != %r" % (a, b)) + + def assertRaises(Exc, func): + try: + func() + except Exc: + return + assert False, ("%s not raised" % Exc) + + sys.modules['somemodule'] = somemodule = mock.Mock(name='somemodule') + class SomeException(Exception): + some_method = method1 = method2 = None + some_other_object = SomeObject = SomeException + + +A side-by-side comparison of how to accomplish some basic tasks with mock and +some other popular Python mocking libraries and frameworks. + +These are: + +* `flexmock `_ +* `mox `_ +* `Mocker `_ +* `dingus `_ +* `fudge `_ + +Popular python mocking frameworks not yet represented here include +`MiniMock `_. + +`pMock `_ (last release 2004 and doesn't import +in recent versions of Python) and +`python-mock `_ (last release 2005) are +intentionally omitted. + +.. note:: + + A more up to date, and tested for all mock libraries (only the mock + examples on this page can be executed as doctests) version of this + comparison is maintained by Gary Bernhardt: + + * `Python Mock Library Comparison + `_ + +This comparison is by no means complete, and also may not be fully idiomatic +for all the libraries represented. *Please* contribute corrections, missing +comparisons, or comparisons for additional libraries to the `mock issue +tracker `_. + +This comparison page was originally created by the `Mox project +`_ and then extended for +`flexmock and mock `_ by +Herman Sheremetyev. Dingus examples written by `Gary Bernhadt +`_. fudge examples +provided by `Kumar McMillan `_. + +.. note:: + + The examples tasks here were originally created by Mox which is a mocking + *framework* rather than a library like mock. The tasks shown naturally + exemplify tasks that frameworks are good at and not the ones they make + harder. In particular you can take a `Mock` or `MagicMock` object and use + it in any way you want with no up-front configuration. The same is also + true for Dingus. + + The examples for mock here assume version 0.7.0. + + +Simple fake object +~~~~~~~~~~~~~~~~~~ + +.. doctest:: + + >>> # mock + >>> my_mock = mock.Mock() + >>> my_mock.some_method.return_value = "calculated value" + >>> my_mock.some_attribute = "value" + >>> assertEqual("calculated value", my_mock.some_method()) + >>> assertEqual("value", my_mock.some_attribute) + +:: + + # Flexmock + mock = flexmock(some_method=lambda: "calculated value", some_attribute="value") + assertEqual("calculated value", mock.some_method()) + assertEqual("value", mock.some_attribute) + + # Mox + mock = mox.MockAnything() + mock.some_method().AndReturn("calculated value") + mock.some_attribute = "value" + mox.Replay(mock) + assertEqual("calculated value", mock.some_method()) + assertEqual("value", mock.some_attribute) + + # Mocker + mock = mocker.mock() + mock.some_method() + mocker.result("calculated value") + mocker.replay() + mock.some_attribute = "value" + assertEqual("calculated value", mock.some_method()) + assertEqual("value", mock.some_attribute) + +:: + + >>> # Dingus + >>> my_dingus = dingus.Dingus(some_attribute="value", + ... some_method__returns="calculated value") + >>> assertEqual("calculated value", my_dingus.some_method()) + >>> assertEqual("value", my_dingus.some_attribute) + +:: + + >>> # fudge + >>> my_fake = (fudge.Fake() + ... .provides('some_method') + ... .returns("calculated value") + ... .has_attr(some_attribute="value")) + ... + >>> assertEqual("calculated value", my_fake.some_method()) + >>> assertEqual("value", my_fake.some_attribute) + + +Simple mock +~~~~~~~~~~~ + +.. doctest:: + + >>> # mock + >>> my_mock = mock.Mock() + >>> my_mock.some_method.return_value = "value" + >>> assertEqual("value", my_mock.some_method()) + >>> my_mock.some_method.assert_called_once_with() + +:: + + # Flexmock + mock = flexmock() + mock.should_receive("some_method").and_return("value").once + assertEqual("value", mock.some_method()) + + # Mox + mock = mox.MockAnything() + mock.some_method().AndReturn("value") + mox.Replay(mock) + assertEqual("value", mock.some_method()) + mox.Verify(mock) + + # Mocker + mock = mocker.mock() + mock.some_method() + mocker.result("value") + mocker.replay() + assertEqual("value", mock.some_method()) + mocker.verify() + +:: + + >>> # Dingus + >>> my_dingus = dingus.Dingus(some_method__returns="value") + >>> assertEqual("value", my_dingus.some_method()) + >>> assert my_dingus.some_method.calls().once() + +:: + + >>> # fudge + >>> @fudge.test + ... def test(): + ... my_fake = (fudge.Fake() + ... .expects('some_method') + ... .returns("value") + ... .times_called(1)) + ... + >>> test() + Traceback (most recent call last): + ... + AssertionError: fake:my_fake.some_method() was not called + + +Creating partial mocks +~~~~~~~~~~~~~~~~~~~~~~ + +.. doctest:: + + >>> # mock + >>> SomeObject.some_method = mock.Mock(return_value='value') + >>> assertEqual("value", SomeObject.some_method()) + +:: + + # Flexmock + flexmock(SomeObject).should_receive("some_method").and_return('value') + assertEqual("value", mock.some_method()) + + # Mox + mock = mox.MockObject(SomeObject) + mock.some_method().AndReturn("value") + mox.Replay(mock) + assertEqual("value", mock.some_method()) + mox.Verify(mock) + + # Mocker + mock = mocker.mock(SomeObject) + mock.Get() + mocker.result("value") + mocker.replay() + assertEqual("value", mock.some_method()) + mocker.verify() + +:: + + >>> # Dingus + >>> object = SomeObject + >>> object.some_method = dingus.Dingus(return_value="value") + >>> assertEqual("value", object.some_method()) + +:: + + >>> # fudge + >>> fake = fudge.Fake().is_callable().returns("") + >>> with fudge.patched_context(SomeObject, 'some_method', fake): + ... s = SomeObject() + ... assertEqual("", s.some_method()) + ... + + +Ensure calls are made in specific order +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doctest:: + + >>> # mock + >>> my_mock = mock.Mock(spec=SomeObject) + >>> my_mock.method1() + + >>> my_mock.method2() + + >>> assertEqual(my_mock.mock_calls, [call.method1(), call.method2()]) + +:: + + # Flexmock + mock = flexmock(SomeObject) + mock.should_receive('method1').once.ordered.and_return('first thing') + mock.should_receive('method2').once.ordered.and_return('second thing') + + # Mox + mock = mox.MockObject(SomeObject) + mock.method1().AndReturn('first thing') + mock.method2().AndReturn('second thing') + mox.Replay(mock) + mox.Verify(mock) + + # Mocker + mock = mocker.mock() + with mocker.order(): + mock.method1() + mocker.result('first thing') + mock.method2() + mocker.result('second thing') + mocker.replay() + mocker.verify() + +:: + + >>> # Dingus + >>> my_dingus = dingus.Dingus() + >>> my_dingus.method1() + + >>> my_dingus.method2() + + >>> assertEqual(['method1', 'method2'], [call.name for call in my_dingus.calls]) + +:: + + >>> # fudge + >>> @fudge.test + ... def test(): + ... my_fake = (fudge.Fake() + ... .remember_order() + ... .expects('method1') + ... .expects('method2')) + ... my_fake.method2() + ... my_fake.method1() + ... + >>> test() + Traceback (most recent call last): + ... + AssertionError: Call #1 was fake:my_fake.method2(); Expected: #1 fake:my_fake.method1(), #2 fake:my_fake.method2(), end + + +Raising exceptions +~~~~~~~~~~~~~~~~~~ + +.. doctest:: + + >>> # mock + >>> my_mock = mock.Mock() + >>> my_mock.some_method.side_effect = SomeException("message") + >>> assertRaises(SomeException, my_mock.some_method) + +:: + + # Flexmock + mock = flexmock() + mock.should_receive("some_method").and_raise(SomeException("message")) + assertRaises(SomeException, mock.some_method) + + # Mox + mock = mox.MockAnything() + mock.some_method().AndRaise(SomeException("message")) + mox.Replay(mock) + assertRaises(SomeException, mock.some_method) + mox.Verify(mock) + + # Mocker + mock = mocker.mock() + mock.some_method() + mocker.throw(SomeException("message")) + mocker.replay() + assertRaises(SomeException, mock.some_method) + mocker.verify() + +:: + + >>> # Dingus + >>> my_dingus = dingus.Dingus() + >>> my_dingus.some_method = dingus.exception_raiser(SomeException) + >>> assertRaises(SomeException, my_dingus.some_method) + +:: + + >>> # fudge + >>> my_fake = (fudge.Fake() + ... .is_callable() + ... .raises(SomeException("message"))) + ... + >>> my_fake() + Traceback (most recent call last): + ... + SomeException: message + + +Override new instances of a class +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doctest:: + + >>> # mock + >>> with mock.patch('somemodule.Someclass') as MockClass: + ... MockClass.return_value = some_other_object + ... assertEqual(some_other_object, somemodule.Someclass()) + ... + + +:: + + # Flexmock + flexmock(some_module.SomeClass, new_instances=some_other_object) + assertEqual(some_other_object, some_module.SomeClass()) + + # Mox + # (you will probably have mox.Mox() available as self.mox in a real test) + mox.Mox().StubOutWithMock(some_module, 'SomeClass', use_mock_anything=True) + some_module.SomeClass().AndReturn(some_other_object) + mox.ReplayAll() + assertEqual(some_other_object, some_module.SomeClass()) + + # Mocker + instance = mocker.mock() + klass = mocker.replace(SomeClass, spec=None) + klass('expected', 'args') + mocker.result(instance) + +:: + + >>> # Dingus + >>> MockClass = dingus.Dingus(return_value=some_other_object) + >>> with dingus.patch('somemodule.SomeClass', MockClass): + ... assertEqual(some_other_object, somemodule.SomeClass()) + ... + +:: + + >>> # fudge + >>> @fudge.patch('somemodule.SomeClass') + ... def test(FakeClass): + ... FakeClass.is_callable().returns(some_other_object) + ... assertEqual(some_other_object, somemodule.SomeClass()) + ... + >>> test() + + +Call the same method multiple times +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + You don't need to do *any* configuration to call `mock.Mock()` methods + multiple times. Attributes like `call_count`, `call_args_list` and + `method_calls` provide various different ways of making assertions about + how the mock was used. + +.. doctest:: + + >>> # mock + >>> my_mock = mock.Mock() + >>> my_mock.some_method() + + >>> my_mock.some_method() + + >>> assert my_mock.some_method.call_count >= 2 + +:: + + # Flexmock # (verifies that the method gets called at least twice) + flexmock(some_object).should_receive('some_method').at_least.twice + + # Mox + # (does not support variable number of calls, so you need to create a new entry for each explicit call) + mock = mox.MockObject(some_object) + mock.some_method(mox.IgnoreArg(), mox.IgnoreArg()) + mock.some_method(mox.IgnoreArg(), mox.IgnoreArg()) + mox.Replay(mock) + mox.Verify(mock) + + # Mocker + # (TODO) + +:: + + >>> # Dingus + >>> my_dingus = dingus.Dingus() + >>> my_dingus.some_method() + + >>> my_dingus.some_method() + + >>> assert len(my_dingus.calls('some_method')) == 2 + +:: + + >>> # fudge + >>> @fudge.test + ... def test(): + ... my_fake = fudge.Fake().expects('some_method').times_called(2) + ... my_fake.some_method() + ... + >>> test() + Traceback (most recent call last): + ... + AssertionError: fake:my_fake.some_method() was called 1 time(s). Expected 2. + + +Mock chained methods +~~~~~~~~~~~~~~~~~~~~ + +.. doctest:: + + >>> # mock + >>> my_mock = mock.Mock() + >>> method3 = my_mock.method1.return_value.method2.return_value.method3 + >>> method3.return_value = 'some value' + >>> assertEqual('some value', my_mock.method1().method2().method3(1, 2)) + >>> method3.assert_called_once_with(1, 2) + +:: + + # Flexmock + # (intermediate method calls are automatically assigned to temporary fake objects + # and can be called with any arguments) + flexmock(some_object).should_receive( + 'method1.method2.method3' + ).with_args(arg1, arg2).and_return('some value') + assertEqual('some_value', some_object.method1().method2().method3(arg1, arg2)) + +:: + + # Mox + mock = mox.MockObject(some_object) + mock2 = mox.MockAnything() + mock3 = mox.MockAnything() + mock.method1().AndReturn(mock1) + mock2.method2().AndReturn(mock2) + mock3.method3(arg1, arg2).AndReturn('some_value') + self.mox.ReplayAll() + assertEqual("some_value", some_object.method1().method2().method3(arg1, arg2)) + self.mox.VerifyAll() + + # Mocker + # (TODO) + +:: + + >>> # Dingus + >>> my_dingus = dingus.Dingus() + >>> method3 = my_dingus.method1.return_value.method2.return_value.method3 + >>> method3.return_value = 'some value' + >>> assertEqual('some value', my_dingus.method1().method2().method3(1, 2)) + >>> assert method3.calls('()', 1, 2).once() + +:: + + >>> # fudge + >>> @fudge.test + ... def test(): + ... my_fake = fudge.Fake() + ... (my_fake + ... .expects('method1') + ... .returns_fake() + ... .expects('method2') + ... .returns_fake() + ... .expects('method3') + ... .with_args(1, 2) + ... .returns('some value')) + ... assertEqual('some value', my_fake.method1().method2().method3(1, 2)) + ... + >>> test() + + +Mocking a context manager +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Examples for mock, Dingus and fudge only (so far): + +.. doctest:: + + >>> # mock + >>> my_mock = mock.MagicMock() + >>> with my_mock: + ... pass + ... + >>> my_mock.__enter__.assert_called_with() + >>> my_mock.__exit__.assert_called_with(None, None, None) + +:: + + + >>> # Dingus (nothing special here; all dinguses are "magic mocks") + >>> my_dingus = dingus.Dingus() + >>> with my_dingus: + ... pass + ... + >>> assert my_dingus.__enter__.calls() + >>> assert my_dingus.__exit__.calls('()', None, None, None) + +:: + + >>> # fudge + >>> my_fake = fudge.Fake().provides('__enter__').provides('__exit__') + >>> with my_fake: + ... pass + ... + + +Mocking the builtin open used as a context manager +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Example for mock only (so far): + +.. doctest:: + + >>> # mock + >>> my_mock = mock.MagicMock() + >>> with mock.patch('__builtin__.open', my_mock): + ... manager = my_mock.return_value.__enter__.return_value + ... manager.read.return_value = 'some data' + ... with open('foo') as h: + ... data = h.read() + ... + >>> data + 'some data' + >>> my_mock.assert_called_once_with('foo') + +*or*: + +.. doctest:: + + >>> # mock + >>> with mock.patch('__builtin__.open') as my_mock: + ... my_mock.return_value.__enter__ = lambda s: s + ... my_mock.return_value.__exit__ = mock.Mock() + ... my_mock.return_value.read.return_value = 'some data' + ... with open('foo') as h: + ... data = h.read() + ... + >>> data + 'some data' + >>> my_mock.assert_called_once_with('foo') + +:: + + >>> # Dingus + >>> my_dingus = dingus.Dingus() + >>> with dingus.patch('__builtin__.open', my_dingus): + ... file_ = open.return_value.__enter__.return_value + ... file_.read.return_value = 'some data' + ... with open('foo') as h: + ... data = f.read() + ... + >>> data + 'some data' + >>> assert my_dingus.calls('()', 'foo').once() + +:: + + >>> # fudge + >>> from contextlib import contextmanager + >>> from StringIO import StringIO + >>> @contextmanager + ... def fake_file(filename): + ... yield StringIO('sekrets') + ... + >>> with fudge.patch('__builtin__.open') as fake_open: + ... fake_open.is_callable().calls(fake_file) + ... with open('/etc/password') as f: + ... data = f.read() + ... + fake:__builtin__.open + >>> data + 'sekrets' \ No newline at end of file diff --git a/python/mock-1.0.0/docs/conf.py b/python/mock-1.0.0/docs/conf.py new file mode 100644 index 000000000..62f0491cc --- /dev/null +++ b/python/mock-1.0.0/docs/conf.py @@ -0,0 +1,209 @@ +# -*- coding: utf-8 -*- +# +# Mock documentation build configuration file, created by +# sphinx-quickstart on Mon Nov 17 18:12:00 2008. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# The contents of this file are pickled, so don't put values in the namespace +# that aren't pickleable (module imports are okay, they're removed automatically). +# +# All configuration values have a default value; values that are commented out +# serve to show the default value. + +import sys, os +sys.path.insert(0, os.path.abspath('..')) +from mock import __version__ + +# If your extensions are in another directory, add it here. If the directory +# is relative to the documentation root, use os.path.abspath to make it +# absolute, like shown here. +#sys.path.append(os.path.abspath('some/directory')) + +# General configuration +# --------------------- + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.doctest'] + +doctest_global_setup = """ +import os +import sys +import mock +from mock import * # yeah, I know :-/ +import unittest2 +import __main__ + +if os.getcwd() not in sys.path: + sys.path.append(os.getcwd()) + +# keep a reference to __main__ +sys.modules['__main'] = __main__ + +class ProxyModule(object): + def __init__(self): + self.__dict__ = globals() + +sys.modules['__main__'] = ProxyModule() +""" + +doctest_global_cleanup = """ +sys.modules['__main__'] = sys.modules['__main'] +""" + +html_theme = 'nature' +html_theme_options = {} + +# Add any paths that contain templates here, relative to this directory. +#templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.txt' + +# The master toctree document. +master_doc = 'index' + +# General substitutions. +project = u'Mock' +copyright = u'2007-2012, Michael Foord & the mock team' + +# The default replacements for |version| and |release|, also used in various +# other places throughout the built documents. +# +# The short X.Y version. +version = __version__[:3] +# The full version, including alpha/beta/rc tags. +release = __version__ + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directories, that shouldn't be searched +# for source files. +exclude_trees = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = False + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'friendly' + + +# Options for HTML output +# ----------------------- + +# The style sheet to use for HTML and HTML Help pages. A file of that name +# must exist either in Sphinx' static/ path, or in one of the custom paths +# given in html_static_path. +#html_style = 'adctheme.css' + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +#html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +html_use_modindex = False + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, the reST sources are included in the HTML build as _sources/. +#html_copy_source = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Mockdoc' + + +# Options for LaTeX output +# ------------------------ + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +latex_font_size = '12pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, document class [howto/manual]). +latex_documents = [ + ('index', 'Mock.tex', u'Mock Documentation', + u'Michael Foord', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +latex_use_modindex = False \ No newline at end of file diff --git a/python/mock-1.0.0/docs/examples.txt b/python/mock-1.0.0/docs/examples.txt new file mode 100644 index 000000000..ecb994b15 --- /dev/null +++ b/python/mock-1.0.0/docs/examples.txt @@ -0,0 +1,1063 @@ +.. _further-examples: + +================== + Further Examples +================== + +.. currentmodule:: mock + +.. testsetup:: + + from datetime import date + + BackendProvider = Mock() + sys.modules['mymodule'] = mymodule = Mock(name='mymodule') + + def grob(val): + "First frob and then clear val" + mymodule.frob(val) + val.clear() + + mymodule.frob = lambda val: val + mymodule.grob = grob + mymodule.date = date + + class TestCase(unittest2.TestCase): + def run(self): + result = unittest2.TestResult() + out = unittest2.TestCase.run(self, result) + assert result.wasSuccessful() + + from mock import inPy3k + + + +For comprehensive examples, see the unit tests included in the full source +distribution. + +Here are some more examples for some slightly more advanced scenarios than in +the :ref:`getting started ` guide. + + +Mocking chained calls +===================== + +Mocking chained calls is actually straightforward with mock once you +understand the :attr:`~Mock.return_value` attribute. When a mock is called for +the first time, or you fetch its `return_value` before it has been called, a +new `Mock` is created. + +This means that you can see how the object returned from a call to a mocked +object has been used by interrogating the `return_value` mock: + +.. doctest:: + + >>> mock = Mock() + >>> mock().foo(a=2, b=3) + + >>> mock.return_value.foo.assert_called_with(a=2, b=3) + +From here it is a simple step to configure and then make assertions about +chained calls. Of course another alternative is writing your code in a more +testable way in the first place... + +So, suppose we have some code that looks a little bit like this: + +.. doctest:: + + >>> class Something(object): + ... def __init__(self): + ... self.backend = BackendProvider() + ... def method(self): + ... response = self.backend.get_endpoint('foobar').create_call('spam', 'eggs').start_call() + ... # more code + +Assuming that `BackendProvider` is already well tested, how do we test +`method()`? Specifically, we want to test that the code section `# more +code` uses the response object in the correct way. + +As this chain of calls is made from an instance attribute we can monkey patch +the `backend` attribute on a `Something` instance. In this particular case +we are only interested in the return value from the final call to +`start_call` so we don't have much configuration to do. Let's assume the +object it returns is 'file-like', so we'll ensure that our response object +uses the builtin `file` as its `spec`. + +To do this we create a mock instance as our mock backend and create a mock +response object for it. To set the response as the return value for that final +`start_call` we could do this: + + `mock_backend.get_endpoint.return_value.create_call.return_value.start_call.return_value = mock_response`. + +We can do that in a slightly nicer way using the :meth:`~Mock.configure_mock` +method to directly set the return value for us: + +.. doctest:: + + >>> something = Something() + >>> mock_response = Mock(spec=file) + >>> mock_backend = Mock() + >>> config = {'get_endpoint.return_value.create_call.return_value.start_call.return_value': mock_response} + >>> mock_backend.configure_mock(**config) + +With these we monkey patch the "mock backend" in place and can make the real +call: + +.. doctest:: + + >>> something.backend = mock_backend + >>> something.method() + +Using :attr:`~Mock.mock_calls` we can check the chained call with a single +assert. A chained call is several calls in one line of code, so there will be +several entries in `mock_calls`. We can use :meth:`call.call_list` to create +this list of calls for us: + +.. doctest:: + + >>> chained = call.get_endpoint('foobar').create_call('spam', 'eggs').start_call() + >>> call_list = chained.call_list() + >>> assert mock_backend.mock_calls == call_list + + +Partial mocking +=============== + +In some tests I wanted to mock out a call to `datetime.date.today() +`_ to return +a known date, but I didn't want to prevent the code under test from +creating new date objects. Unfortunately `datetime.date` is written in C, and +so I couldn't just monkey-patch out the static `date.today` method. + +I found a simple way of doing this that involved effectively wrapping the date +class with a mock, but passing through calls to the constructor to the real +class (and returning real instances). + +The :func:`patch decorator ` is used here to +mock out the `date` class in the module under test. The :attr:`side_effect` +attribute on the mock date class is then set to a lambda function that returns +a real date. When the mock date class is called a real date will be +constructed and returned by `side_effect`. + +.. doctest:: + + >>> from datetime import date + >>> with patch('mymodule.date') as mock_date: + ... mock_date.today.return_value = date(2010, 10, 8) + ... mock_date.side_effect = lambda *args, **kw: date(*args, **kw) + ... + ... assert mymodule.date.today() == date(2010, 10, 8) + ... assert mymodule.date(2009, 6, 8) == date(2009, 6, 8) + ... + +Note that we don't patch `datetime.date` globally, we patch `date` in the +module that *uses* it. See :ref:`where to patch `. + +When `date.today()` is called a known date is returned, but calls to the +`date(...)` constructor still return normal dates. Without this you can find +yourself having to calculate an expected result using exactly the same +algorithm as the code under test, which is a classic testing anti-pattern. + +Calls to the date constructor are recorded in the `mock_date` attributes +(`call_count` and friends) which may also be useful for your tests. + +An alternative way of dealing with mocking dates, or other builtin classes, +is discussed in `this blog entry +`_. + + +Mocking a Generator Method +========================== + +A Python generator is a function or method that uses the `yield statement +`_ to +return a series of values when iterated over [#]_. + +A generator method / function is called to return the generator object. It is +the generator object that is then iterated over. The protocol method for +iteration is `__iter__ +`_, so we can +mock this using a `MagicMock`. + +Here's an example class with an "iter" method implemented as a generator: + +.. doctest:: + + >>> class Foo(object): + ... def iter(self): + ... for i in [1, 2, 3]: + ... yield i + ... + >>> foo = Foo() + >>> list(foo.iter()) + [1, 2, 3] + + +How would we mock this class, and in particular its "iter" method? + +To configure the values returned from the iteration (implicit in the call to +`list`), we need to configure the object returned by the call to `foo.iter()`. + +.. doctest:: + + >>> mock_foo = MagicMock() + >>> mock_foo.iter.return_value = iter([1, 2, 3]) + >>> list(mock_foo.iter()) + [1, 2, 3] + +.. [#] There are also generator expressions and more `advanced uses + `_ of generators, but we aren't + concerned about them here. A very good introduction to generators and how + powerful they are is: `Generator Tricks for Systems Programmers + `_. + + +Applying the same patch to every test method +============================================ + +If you want several patches in place for multiple test methods the obvious way +is to apply the patch decorators to every method. This can feel like unnecessary +repetition. For Python 2.6 or more recent you can use `patch` (in all its +various forms) as a class decorator. This applies the patches to all test +methods on the class. A test method is identified by methods whose names start +with `test`: + +.. doctest:: + + >>> @patch('mymodule.SomeClass') + ... class MyTest(TestCase): + ... + ... def test_one(self, MockSomeClass): + ... self.assertTrue(mymodule.SomeClass is MockSomeClass) + ... + ... def test_two(self, MockSomeClass): + ... self.assertTrue(mymodule.SomeClass is MockSomeClass) + ... + ... def not_a_test(self): + ... return 'something' + ... + >>> MyTest('test_one').test_one() + >>> MyTest('test_two').test_two() + >>> MyTest('test_two').not_a_test() + 'something' + +An alternative way of managing patches is to use the :ref:`start-and-stop`. +These allow you to move the patching into your `setUp` and `tearDown` methods. + +.. doctest:: + + >>> class MyTest(TestCase): + ... def setUp(self): + ... self.patcher = patch('mymodule.foo') + ... self.mock_foo = self.patcher.start() + ... + ... def test_foo(self): + ... self.assertTrue(mymodule.foo is self.mock_foo) + ... + ... def tearDown(self): + ... self.patcher.stop() + ... + >>> MyTest('test_foo').run() + +If you use this technique you must ensure that the patching is "undone" by +calling `stop`. This can be fiddlier than you might think, because if an +exception is raised in the setUp then tearDown is not called. `unittest2 +`_ cleanup functions make this simpler: + + +.. doctest:: + + >>> class MyTest(TestCase): + ... def setUp(self): + ... patcher = patch('mymodule.foo') + ... self.addCleanup(patcher.stop) + ... self.mock_foo = patcher.start() + ... + ... def test_foo(self): + ... self.assertTrue(mymodule.foo is self.mock_foo) + ... + >>> MyTest('test_foo').run() + + +Mocking Unbound Methods +======================= + +Whilst writing tests today I needed to patch an *unbound method* (patching the +method on the class rather than on the instance). I needed self to be passed +in as the first argument because I want to make asserts about which objects +were calling this particular method. The issue is that you can't patch with a +mock for this, because if you replace an unbound method with a mock it doesn't +become a bound method when fetched from the instance, and so it doesn't get +self passed in. The workaround is to patch the unbound method with a real +function instead. The :func:`patch` decorator makes it so simple to +patch out methods with a mock that having to create a real function becomes a +nuisance. + +If you pass `autospec=True` to patch then it does the patching with a +*real* function object. This function object has the same signature as the one +it is replacing, but delegates to a mock under the hood. You still get your +mock auto-created in exactly the same way as before. What it means though, is +that if you use it to patch out an unbound method on a class the mocked +function will be turned into a bound method if it is fetched from an instance. +It will have `self` passed in as the first argument, which is exactly what I +wanted: + +.. doctest:: + + >>> class Foo(object): + ... def foo(self): + ... pass + ... + >>> with patch.object(Foo, 'foo', autospec=True) as mock_foo: + ... mock_foo.return_value = 'foo' + ... foo = Foo() + ... foo.foo() + ... + 'foo' + >>> mock_foo.assert_called_once_with(foo) + +If we don't use `autospec=True` then the unbound method is patched out +with a Mock instance instead, and isn't called with `self`. + + +Checking multiple calls with mock +================================= + +mock has a nice API for making assertions about how your mock objects are used. + +.. doctest:: + + >>> mock = Mock() + >>> mock.foo_bar.return_value = None + >>> mock.foo_bar('baz', spam='eggs') + >>> mock.foo_bar.assert_called_with('baz', spam='eggs') + +If your mock is only being called once you can use the +:meth:`assert_called_once_with` method that also asserts that the +:attr:`call_count` is one. + +.. doctest:: + + >>> mock.foo_bar.assert_called_once_with('baz', spam='eggs') + >>> mock.foo_bar() + >>> mock.foo_bar.assert_called_once_with('baz', spam='eggs') + Traceback (most recent call last): + ... + AssertionError: Expected to be called once. Called 2 times. + +Both `assert_called_with` and `assert_called_once_with` make assertions about +the *most recent* call. If your mock is going to be called several times, and +you want to make assertions about *all* those calls you can use +:attr:`~Mock.call_args_list`: + +.. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock(1, 2, 3) + >>> mock(4, 5, 6) + >>> mock() + >>> mock.call_args_list + [call(1, 2, 3), call(4, 5, 6), call()] + +The :data:`call` helper makes it easy to make assertions about these calls. You +can build up a list of expected calls and compare it to `call_args_list`. This +looks remarkably similar to the repr of the `call_args_list`: + +.. doctest:: + + >>> expected = [call(1, 2, 3), call(4, 5, 6), call()] + >>> mock.call_args_list == expected + True + + +Coping with mutable arguments +============================= + +Another situation is rare, but can bite you, is when your mock is called with +mutable arguments. `call_args` and `call_args_list` store *references* to the +arguments. If the arguments are mutated by the code under test then you can no +longer make assertions about what the values were when the mock was called. + +Here's some example code that shows the problem. Imagine the following functions +defined in 'mymodule':: + + def frob(val): + pass + + def grob(val): + "First frob and then clear val" + frob(val) + val.clear() + +When we try to test that `grob` calls `frob` with the correct argument look +what happens: + +.. doctest:: + + >>> with patch('mymodule.frob') as mock_frob: + ... val = set([6]) + ... mymodule.grob(val) + ... + >>> val + set([]) + >>> mock_frob.assert_called_with(set([6])) + Traceback (most recent call last): + ... + AssertionError: Expected: ((set([6]),), {}) + Called with: ((set([]),), {}) + +One possibility would be for mock to copy the arguments you pass in. This +could then cause problems if you do assertions that rely on object identity +for equality. + +Here's one solution that uses the :attr:`side_effect` +functionality. If you provide a `side_effect` function for a mock then +`side_effect` will be called with the same args as the mock. This gives us an +opportunity to copy the arguments and store them for later assertions. In this +example I'm using *another* mock to store the arguments so that I can use the +mock methods for doing the assertion. Again a helper function sets this up for +me. + +.. doctest:: + + >>> from copy import deepcopy + >>> from mock import Mock, patch, DEFAULT + >>> def copy_call_args(mock): + ... new_mock = Mock() + ... def side_effect(*args, **kwargs): + ... args = deepcopy(args) + ... kwargs = deepcopy(kwargs) + ... new_mock(*args, **kwargs) + ... return DEFAULT + ... mock.side_effect = side_effect + ... return new_mock + ... + >>> with patch('mymodule.frob') as mock_frob: + ... new_mock = copy_call_args(mock_frob) + ... val = set([6]) + ... mymodule.grob(val) + ... + >>> new_mock.assert_called_with(set([6])) + >>> new_mock.call_args + call(set([6])) + +`copy_call_args` is called with the mock that will be called. It returns a new +mock that we do the assertion on. The `side_effect` function makes a copy of +the args and calls our `new_mock` with the copy. + +.. note:: + + If your mock is only going to be used once there is an easier way of + checking arguments at the point they are called. You can simply do the + checking inside a `side_effect` function. + + .. doctest:: + + >>> def side_effect(arg): + ... assert arg == set([6]) + ... + >>> mock = Mock(side_effect=side_effect) + >>> mock(set([6])) + >>> mock(set()) + Traceback (most recent call last): + ... + AssertionError + +An alternative approach is to create a subclass of `Mock` or `MagicMock` that +copies (using `copy.deepcopy +`_) the arguments. +Here's an example implementation: + +.. doctest:: + + >>> from copy import deepcopy + >>> class CopyingMock(MagicMock): + ... def __call__(self, *args, **kwargs): + ... args = deepcopy(args) + ... kwargs = deepcopy(kwargs) + ... return super(CopyingMock, self).__call__(*args, **kwargs) + ... + >>> c = CopyingMock(return_value=None) + >>> arg = set() + >>> c(arg) + >>> arg.add(1) + >>> c.assert_called_with(set()) + >>> c.assert_called_with(arg) + Traceback (most recent call last): + ... + AssertionError: Expected call: mock(set([1])) + Actual call: mock(set([])) + >>> c.foo + + +When you subclass `Mock` or `MagicMock` all dynamically created attributes, +and the `return_value` will use your subclass automatically. That means all +children of a `CopyingMock` will also have the type `CopyingMock`. + + +Raising exceptions on attribute access +====================================== + +You can use :class:`PropertyMock` to mimic the behaviour of properties. This +includes raising exceptions when an attribute is accessed. + +Here's an example raising a `ValueError` when the 'foo' attribute is accessed: + +.. doctest:: + + >>> m = MagicMock() + >>> p = PropertyMock(side_effect=ValueError) + >>> type(m).foo = p + >>> m.foo + Traceback (most recent call last): + .... + ValueError + +Because every mock object has its own type, a new subclass of whichever mock +class you're using, all mock objects are isolated from each other. You can +safely attach properties (or other descriptors or whatever you want in fact) +to `type(mock)` without affecting other mock objects. + + +Multiple calls with different effects +===================================== + +.. note:: + + In mock 1.0 the handling of iterable `side_effect` was changed. Any + exceptions in the iterable will be raised instead of returned. + +Handling code that needs to behave differently on subsequent calls during the +test can be tricky. For example you may have a function that needs to raise +an exception the first time it is called but returns a response on the second +call (testing retry behaviour). + +One approach is to use a :attr:`side_effect` function that replaces itself. The +first time it is called the `side_effect` sets a new `side_effect` that will +be used for the second call. It then raises an exception: + +.. doctest:: + + >>> def side_effect(*args): + ... def second_call(*args): + ... return 'response' + ... mock.side_effect = second_call + ... raise Exception('boom') + ... + >>> mock = Mock(side_effect=side_effect) + >>> mock('first') + Traceback (most recent call last): + ... + Exception: boom + >>> mock('second') + 'response' + >>> mock.assert_called_with('second') + +Another perfectly valid way would be to pop return values from a list. If the +return value is an exception, raise it instead of returning it: + +.. doctest:: + + >>> returns = [Exception('boom'), 'response'] + >>> def side_effect(*args): + ... result = returns.pop(0) + ... if isinstance(result, Exception): + ... raise result + ... return result + ... + >>> mock = Mock(side_effect=side_effect) + >>> mock('first') + Traceback (most recent call last): + ... + Exception: boom + >>> mock('second') + 'response' + >>> mock.assert_called_with('second') + +Which approach you prefer is a matter of taste. The first approach is actually +a line shorter but maybe the second approach is more readable. + + +Nesting Patches +=============== + +Using patch as a context manager is nice, but if you do multiple patches you +can end up with nested with statements indenting further and further to the +right: + +.. doctest:: + + >>> class MyTest(TestCase): + ... + ... def test_foo(self): + ... with patch('mymodule.Foo') as mock_foo: + ... with patch('mymodule.Bar') as mock_bar: + ... with patch('mymodule.Spam') as mock_spam: + ... assert mymodule.Foo is mock_foo + ... assert mymodule.Bar is mock_bar + ... assert mymodule.Spam is mock_spam + ... + >>> original = mymodule.Foo + >>> MyTest('test_foo').test_foo() + >>> assert mymodule.Foo is original + +With unittest2_ `cleanup` functions and the :ref:`start-and-stop` we can +achieve the same effect without the nested indentation. A simple helper +method, `create_patch`, puts the patch in place and returns the created mock +for us: + +.. doctest:: + + >>> class MyTest(TestCase): + ... + ... def create_patch(self, name): + ... patcher = patch(name) + ... thing = patcher.start() + ... self.addCleanup(patcher.stop) + ... return thing + ... + ... def test_foo(self): + ... mock_foo = self.create_patch('mymodule.Foo') + ... mock_bar = self.create_patch('mymodule.Bar') + ... mock_spam = self.create_patch('mymodule.Spam') + ... + ... assert mymodule.Foo is mock_foo + ... assert mymodule.Bar is mock_bar + ... assert mymodule.Spam is mock_spam + ... + >>> original = mymodule.Foo + >>> MyTest('test_foo').run() + >>> assert mymodule.Foo is original + + +Mocking a dictionary with MagicMock +=================================== + +You may want to mock a dictionary, or other container object, recording all +access to it whilst having it still behave like a dictionary. + +We can do this with :class:`MagicMock`, which will behave like a dictionary, +and using :data:`~Mock.side_effect` to delegate dictionary access to a real +underlying dictionary that is under our control. + +When the `__getitem__` and `__setitem__` methods of our `MagicMock` are called +(normal dictionary access) then `side_effect` is called with the key (and in +the case of `__setitem__` the value too). We can also control what is returned. + +After the `MagicMock` has been used we can use attributes like +:data:`~Mock.call_args_list` to assert about how the dictionary was used: + +.. doctest:: + + >>> my_dict = {'a': 1, 'b': 2, 'c': 3} + >>> def getitem(name): + ... return my_dict[name] + ... + >>> def setitem(name, val): + ... my_dict[name] = val + ... + >>> mock = MagicMock() + >>> mock.__getitem__.side_effect = getitem + >>> mock.__setitem__.side_effect = setitem + +.. note:: + + An alternative to using `MagicMock` is to use `Mock` and *only* provide + the magic methods you specifically want: + + .. doctest:: + + >>> mock = Mock() + >>> mock.__setitem__ = Mock(side_effect=getitem) + >>> mock.__getitem__ = Mock(side_effect=setitem) + + A *third* option is to use `MagicMock` but passing in `dict` as the `spec` + (or `spec_set`) argument so that the `MagicMock` created only has + dictionary magic methods available: + + .. doctest:: + + >>> mock = MagicMock(spec_set=dict) + >>> mock.__getitem__.side_effect = getitem + >>> mock.__setitem__.side_effect = setitem + +With these side effect functions in place, the `mock` will behave like a normal +dictionary but recording the access. It even raises a `KeyError` if you try +to access a key that doesn't exist. + +.. doctest:: + + >>> mock['a'] + 1 + >>> mock['c'] + 3 + >>> mock['d'] + Traceback (most recent call last): + ... + KeyError: 'd' + >>> mock['b'] = 'fish' + >>> mock['d'] = 'eggs' + >>> mock['b'] + 'fish' + >>> mock['d'] + 'eggs' + +After it has been used you can make assertions about the access using the normal +mock methods and attributes: + +.. doctest:: + + >>> mock.__getitem__.call_args_list + [call('a'), call('c'), call('d'), call('b'), call('d')] + >>> mock.__setitem__.call_args_list + [call('b', 'fish'), call('d', 'eggs')] + >>> my_dict + {'a': 1, 'c': 3, 'b': 'fish', 'd': 'eggs'} + + +Mock subclasses and their attributes +==================================== + +There are various reasons why you might want to subclass `Mock`. One reason +might be to add helper methods. Here's a silly example: + +.. doctest:: + + >>> class MyMock(MagicMock): + ... def has_been_called(self): + ... return self.called + ... + >>> mymock = MyMock(return_value=None) + >>> mymock + + >>> mymock.has_been_called() + False + >>> mymock() + >>> mymock.has_been_called() + True + +The standard behaviour for `Mock` instances is that attributes and the return +value mocks are of the same type as the mock they are accessed on. This ensures +that `Mock` attributes are `Mocks` and `MagicMock` attributes are `MagicMocks` +[#]_. So if you're subclassing to add helper methods then they'll also be +available on the attributes and return value mock of instances of your +subclass. + +.. doctest:: + + >>> mymock.foo + + >>> mymock.foo.has_been_called() + False + >>> mymock.foo() + + >>> mymock.foo.has_been_called() + True + +Sometimes this is inconvenient. For example, `one user +`_ is subclassing mock to +created a `Twisted adaptor +`_. +Having this applied to attributes too actually causes errors. + +`Mock` (in all its flavours) uses a method called `_get_child_mock` to create +these "sub-mocks" for attributes and return values. You can prevent your +subclass being used for attributes by overriding this method. The signature is +that it takes arbitrary keyword arguments (`**kwargs`) which are then passed +onto the mock constructor: + +.. doctest:: + + >>> class Subclass(MagicMock): + ... def _get_child_mock(self, **kwargs): + ... return MagicMock(**kwargs) + ... + >>> mymock = Subclass() + >>> mymock.foo + + >>> assert isinstance(mymock, Subclass) + >>> assert not isinstance(mymock.foo, Subclass) + >>> assert not isinstance(mymock(), Subclass) + +.. [#] An exception to this rule are the non-callable mocks. Attributes use the + callable variant because otherwise non-callable mocks couldn't have callable + methods. + + +Mocking imports with patch.dict +=============================== + +One situation where mocking can be hard is where you have a local import inside +a function. These are harder to mock because they aren't using an object from +the module namespace that we can patch out. + +Generally local imports are to be avoided. They are sometimes done to prevent +circular dependencies, for which there is *usually* a much better way to solve +the problem (refactor the code) or to prevent "up front costs" by delaying the +import. This can also be solved in better ways than an unconditional local +import (store the module as a class or module attribute and only do the import +on first use). + +That aside there is a way to use `mock` to affect the results of an import. +Importing fetches an *object* from the `sys.modules` dictionary. Note that it +fetches an *object*, which need not be a module. Importing a module for the +first time results in a module object being put in `sys.modules`, so usually +when you import something you get a module back. This need not be the case +however. + +This means you can use :func:`patch.dict` to *temporarily* put a mock in place +in `sys.modules`. Any imports whilst this patch is active will fetch the mock. +When the patch is complete (the decorated function exits, the with statement +body is complete or `patcher.stop()` is called) then whatever was there +previously will be restored safely. + +Here's an example that mocks out the 'fooble' module. + +.. doctest:: + + >>> mock = Mock() + >>> with patch.dict('sys.modules', {'fooble': mock}): + ... import fooble + ... fooble.blob() + ... + + >>> assert 'fooble' not in sys.modules + >>> mock.blob.assert_called_once_with() + +As you can see the `import fooble` succeeds, but on exit there is no 'fooble' +left in `sys.modules`. + +This also works for the `from module import name` form: + +.. doctest:: + + >>> mock = Mock() + >>> with patch.dict('sys.modules', {'fooble': mock}): + ... from fooble import blob + ... blob.blip() + ... + + >>> mock.blob.blip.assert_called_once_with() + +With slightly more work you can also mock package imports: + +.. doctest:: + + >>> mock = Mock() + >>> modules = {'package': mock, 'package.module': mock.module} + >>> with patch.dict('sys.modules', modules): + ... from package.module import fooble + ... fooble() + ... + + >>> mock.module.fooble.assert_called_once_with() + + +Tracking order of calls and less verbose call assertions +======================================================== + +The :class:`Mock` class allows you to track the *order* of method calls on +your mock objects through the :attr:`~Mock.method_calls` attribute. This +doesn't allow you to track the order of calls between separate mock objects, +however we can use :attr:`~Mock.mock_calls` to achieve the same effect. + +Because mocks track calls to child mocks in `mock_calls`, and accessing an +arbitrary attribute of a mock creates a child mock, we can create our separate +mocks from a parent one. Calls to those child mock will then all be recorded, +in order, in the `mock_calls` of the parent: + +.. doctest:: + + >>> manager = Mock() + >>> mock_foo = manager.foo + >>> mock_bar = manager.bar + + >>> mock_foo.something() + + >>> mock_bar.other.thing() + + + >>> manager.mock_calls + [call.foo.something(), call.bar.other.thing()] + +We can then assert about the calls, including the order, by comparing with +the `mock_calls` attribute on the manager mock: + +.. doctest:: + + >>> expected_calls = [call.foo.something(), call.bar.other.thing()] + >>> manager.mock_calls == expected_calls + True + +If `patch` is creating, and putting in place, your mocks then you can attach +them to a manager mock using the :meth:`~Mock.attach_mock` method. After +attaching calls will be recorded in `mock_calls` of the manager. + +.. doctest:: + + >>> manager = MagicMock() + >>> with patch('mymodule.Class1') as MockClass1: + ... with patch('mymodule.Class2') as MockClass2: + ... manager.attach_mock(MockClass1, 'MockClass1') + ... manager.attach_mock(MockClass2, 'MockClass2') + ... MockClass1().foo() + ... MockClass2().bar() + ... + + + >>> manager.mock_calls + [call.MockClass1(), + call.MockClass1().foo(), + call.MockClass2(), + call.MockClass2().bar()] + +If many calls have been made, but you're only interested in a particular +sequence of them then an alternative is to use the +:meth:`~Mock.assert_has_calls` method. This takes a list of calls (constructed +with the :data:`call` object). If that sequence of calls are in +:attr:`~Mock.mock_calls` then the assert succeeds. + +.. doctest:: + + >>> m = MagicMock() + >>> m().foo().bar().baz() + + >>> m.one().two().three() + + >>> calls = call.one().two().three().call_list() + >>> m.assert_has_calls(calls) + +Even though the chained call `m.one().two().three()` aren't the only calls that +have been made to the mock, the assert still succeeds. + +Sometimes a mock may have several calls made to it, and you are only interested +in asserting about *some* of those calls. You may not even care about the +order. In this case you can pass `any_order=True` to `assert_has_calls`: + +.. doctest:: + + >>> m = MagicMock() + >>> m(1), m.two(2, 3), m.seven(7), m.fifty('50') + (...) + >>> calls = [call.fifty('50'), call(1), call.seven(7)] + >>> m.assert_has_calls(calls, any_order=True) + + +More complex argument matching +============================== + +Using the same basic concept as `ANY` we can implement matchers to do more +complex assertions on objects used as arguments to mocks. + +Suppose we expect some object to be passed to a mock that by default +compares equal based on object identity (which is the Python default for user +defined classes). To use :meth:`~Mock.assert_called_with` we would need to pass +in the exact same object. If we are only interested in some of the attributes +of this object then we can create a matcher that will check these attributes +for us. + +You can see in this example how a 'standard' call to `assert_called_with` isn't +sufficient: + +.. doctest:: + + >>> class Foo(object): + ... def __init__(self, a, b): + ... self.a, self.b = a, b + ... + >>> mock = Mock(return_value=None) + >>> mock(Foo(1, 2)) + >>> mock.assert_called_with(Foo(1, 2)) + Traceback (most recent call last): + ... + AssertionError: Expected: call(<__main__.Foo object at 0x...>) + Actual call: call(<__main__.Foo object at 0x...>) + +A comparison function for our `Foo` class might look something like this: + +.. doctest:: + + >>> def compare(self, other): + ... if not type(self) == type(other): + ... return False + ... if self.a != other.a: + ... return False + ... if self.b != other.b: + ... return False + ... return True + ... + +And a matcher object that can use comparison functions like this for its +equality operation would look something like this: + +.. doctest:: + + >>> class Matcher(object): + ... def __init__(self, compare, some_obj): + ... self.compare = compare + ... self.some_obj = some_obj + ... def __eq__(self, other): + ... return self.compare(self.some_obj, other) + ... + +Putting all this together: + +.. doctest:: + + >>> match_foo = Matcher(compare, Foo(1, 2)) + >>> mock.assert_called_with(match_foo) + +The `Matcher` is instantiated with our compare function and the `Foo` object +we want to compare against. In `assert_called_with` the `Matcher` equality +method will be called, which compares the object the mock was called with +against the one we created our matcher with. If they match then +`assert_called_with` passes, and if they don't an `AssertionError` is raised: + +.. doctest:: + + >>> match_wrong = Matcher(compare, Foo(3, 4)) + >>> mock.assert_called_with(match_wrong) + Traceback (most recent call last): + ... + AssertionError: Expected: ((,), {}) + Called with: ((,), {}) + +With a bit of tweaking you could have the comparison function raise the +`AssertionError` directly and provide a more useful failure message. + +As of version 1.5, the Python testing library `PyHamcrest +`_ provides similar functionality, +that may be useful here, in the form of its equality matcher +(`hamcrest.library.integration.match_equality +`_). + + +Less verbose configuration of mock objects +========================================== + +This recipe, for easier configuration of mock objects, is now part of `Mock`. +See the :meth:`~Mock.configure_mock` method. + + +Matching any argument in assertions +=================================== + +This example is now built in to mock. See :data:`ANY`. + + +Mocking Properties +================== + +This example is now built in to mock. See :class:`PropertyMock`. + + +Mocking open +============ + +This example is now built in to mock. See :func:`mock_open`. + + +Mocks without some attributes +============================= + +This example is now built in to mock. See :ref:`deleting-attributes`. diff --git a/python/mock-1.0.0/docs/getting-started.txt b/python/mock-1.0.0/docs/getting-started.txt new file mode 100644 index 000000000..1b5d289eb --- /dev/null +++ b/python/mock-1.0.0/docs/getting-started.txt @@ -0,0 +1,479 @@ +=========================== + Getting Started with Mock +=========================== + +.. _getting-started: + +.. index:: Getting Started + +.. testsetup:: + + class SomeClass(object): + static_method = None + class_method = None + attribute = None + + sys.modules['package'] = package = Mock(name='package') + sys.modules['package.module'] = module = package.module + sys.modules['module'] = package.module + + +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: + +.. doctest:: + + >>> real = SomeClass() + >>> real.method = MagicMock(name='method') + >>> real.method(3, 4, 5, key='value') + + +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: + +.. doctest:: + + >>> from mock import MagicMock + >>> 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. + +.. doctest:: + + >>> 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. + +.. doctest:: + + >>> 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 modifying the mock :attr:`~Mock.return_value`. + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> mock = MagicMock(name='foo') + >>> mock + + >>> mock.method + + + +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. + +.. doctest:: + + >>> mock = MagicMock() + >>> mock.method() + + >>> mock.attribute.method(10, x=53) + + >>> 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`: + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> mock = Mock() + >>> mock.return_value = 3 + >>> mock() + 3 + +Of course you can do the same for methods on the mock: + +.. doctest:: + + >>> mock = Mock() + >>> mock.method.return_value = 3 + >>> mock.method() + 3 + +The return value can also be set in the constructor: + +.. doctest:: + + >>> mock = Mock(return_value=3) + >>> mock() + 3 + +If you need an attribute setting on your mock, just do it: + +.. doctest:: + + >>> 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: + + +.. doctest:: + + >>> 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. + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> 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. + +.. doctest:: + + >>> 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 `. + + +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`: + +.. doctest:: + + >>> 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`: + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> @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: + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> 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/python/mock-1.0.0/docs/helpers.txt b/python/mock-1.0.0/docs/helpers.txt new file mode 100644 index 000000000..571b71d5e --- /dev/null +++ b/python/mock-1.0.0/docs/helpers.txt @@ -0,0 +1,583 @@ +========= + Helpers +========= + +.. currentmodule:: mock + +.. testsetup:: + + mock.FILTER_DIR = True + from pprint import pprint as pp + original_dir = dir + def dir(obj): + print pp(original_dir(obj)) + + import urllib2 + __main__.urllib2 = urllib2 + +.. testcleanup:: + + dir = original_dir + mock.FILTER_DIR = True + + + +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`. + + .. doctest:: + + >>> 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: + +.. doctest:: + + >>> m = MagicMock() + >>> m(1).method(arg='foo').other('bar')(2.0) + + >>> 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: + +.. doctest:: + + >>> 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') + + >>> 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. + +.. doctest:: + + >>> 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`: + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> dir(Mock()) + ['assert_any_call', + 'assert_called_once_with', + 'assert_called_with', + 'assert_has_calls', + 'attach_mock', + ... + >>> import urllib2 + >>> dir(Mock(spec=urllib2)) + ['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`: + +.. doctest:: + + >>> 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. + +.. doctest:: + + >>> from mock import mock_open + >>> 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: + +.. doctest:: + + >>> 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`. + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> import urllib2 + >>> mock = Mock(spec=urllib2.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.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: + +.. doctest:: + + >>> import urllib2 + >>> patcher = patch('__main__.urllib2', autospec=True) + >>> mock_urllib2 = patcher.start() + >>> urllib2 is mock_urllib2 + True + >>> urllib2.Request + + +You can see that `urllib2.Request` has a spec. `urllib2.Request` takes two +arguments in the constructor (one of which is `self`). Here's what happens if +we try to call it incorrectly: + +.. doctest:: + + >>> req = urllib2.Request() + Traceback (most recent call last): + ... + TypeError: () takes at least 2 arguments (1 given) + +The spec also applies to instantiated classes (i.e. the return value of +specced mocks): + +.. doctest:: + + >>> req = urllib2.Request('foo') + >>> req + + +`Request` objects are not callable, so the return value of instantiating our +mocked out `urllib2.Request` is a non-callable mock. With the spec in place +any typos in our asserts will raise the correct error: + +.. doctest:: + + >>> req.add_header('spam', 'eggs') + + >>> 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: + +.. doctest:: + + >>> import urllib2 + >>> mock_urllib2 = create_autospec(urllib2) + >>> mock_urllib2.Request('foo', 'bar') + + +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. + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> 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`): + +.. doctest:: + + >>> class Something(object): + ... member = None + ... + >>> mock = create_autospec(Something) + >>> mock.member.foo.bar.baz() + + +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: + +.. doctest:: + + >>> 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 + + +.. note:: + + An additional limitation (currently) with `autospec` is that unbound + methods on mocked classes *don't* take an "explicit self" as the first + argument - so this usage will fail with `autospec`. + + .. doctest:: + + >>> class Foo(object): + ... def foo(self): + ... pass + ... + >>> Foo.foo(Foo()) + >>> MockFoo = create_autospec(Foo) + >>> MockFoo.foo(MockFoo()) + Traceback (most recent call last): + ... + TypeError: () takes exactly 1 argument (2 given) + + The reason is that its very hard to tell the difference between functions, + unbound methods and staticmethods across Python 2 & 3 and the alternative + implementations. This restriction may be fixed in future versions. + + +------ + +.. [#] 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. A + way round this problem would have been to use `getattr_static + `_, + which can fetch attributes without triggering code execution. Descriptors + like `classmethod` and `staticmethod` *need* to be fetched correctly though, + so that their signatures can be mocked correctly. diff --git a/python/mock-1.0.0/docs/index.txt b/python/mock-1.0.0/docs/index.txt new file mode 100644 index 000000000..7e4a8daca --- /dev/null +++ b/python/mock-1.0.0/docs/index.txt @@ -0,0 +1,411 @@ +==================================== + Mock - Mocking and Testing Library +==================================== + +.. currentmodule:: mock + +:Author: `Michael Foord + `_ +:Version: |release| +:Date: 2012/10/07 +:Homepage: `Mock Homepage`_ +:Download: `Mock on PyPI`_ +:Documentation: `PDF Documentation + `_ +:License: `BSD License`_ +:Support: `Mailing list (testing-in-python@lists.idyll.org) + `_ +:Issue tracker: `Google code project + `_ + +.. _Mock Homepage: http://www.voidspace.org.uk/python/mock/ +.. _BSD License: http://www.voidspace.org.uk/python/license.shtml + + +.. currentmodule:: mock + +.. module:: mock + :synopsis: Mock object and testing library. + +.. index:: introduction + +mock is a library for testing in Python. It allows you to replace parts of +your system under test with mock objects and make assertions about how they +have been used. + +mock is now part of the Python standard library, available as `unittest.mock +`_ +in Python 3.3 onwards. + +mock provides a core :class:`Mock` class removing the need to create a host +of stubs throughout your test suite. After performing an action, you can make +assertions about which methods / attributes were used and arguments they were +called with. You can also specify return values and set needed attributes in +the normal way. + +Additionally, mock provides a :func:`patch` decorator that handles patching +module and class level attributes within the scope of a test, along with +:const:`sentinel` for creating unique objects. See the `quick guide`_ for +some examples of how to use :class:`Mock`, :class:`MagicMock` and +:func:`patch`. + +Mock is very easy to use and is designed for use with +`unittest `_. Mock is based on +the 'action -> assertion' pattern instead of `'record -> replay'` used by many +mocking frameworks. + +mock is tested on Python versions 2.4-2.7, Python 3 plus the latest versions of +Jython and PyPy. + + +.. testsetup:: + + class ProductionClass(object): + def method(self, *args): + pass + + module = sys.modules['module'] = ProductionClass + ProductionClass.ClassName1 = ProductionClass + ProductionClass.ClassName2 = ProductionClass + + + +API Documentation +================= + +.. toctree:: + :maxdepth: 2 + + mock + patch + helpers + sentinel + magicmock + + +User Guide +========== + +.. toctree:: + :maxdepth: 2 + + getting-started + examples + compare + changelog + + +.. index:: installing + +Installing +========== + +The current version is |release|. Mock is stable and widely used. If you do +find any bugs, or have suggestions for improvements / extensions +then please contact us. + +* `mock on PyPI `_ +* `mock documentation as PDF + `_ +* `Google Code Home & Mercurial Repository `_ + +.. index:: repository +.. index:: hg + +You can checkout the latest development version from the Google Code Mercurial +repository with the following command: + + ``hg clone https://mock.googlecode.com/hg/ mock`` + + +.. index:: pip +.. index:: easy_install +.. index:: setuptools + +If you have pip, setuptools or distribute you can install mock with: + + | ``easy_install -U mock`` + | ``pip install -U mock`` + +Alternatively you can download the mock distribution from PyPI and after +unpacking run: + + ``python setup.py install`` + + +Quick Guide +=========== + +:class:`Mock` and :class:`MagicMock` objects create all attributes and +methods as you access them and store details of how they have been used. You +can configure them, to specify return values or limit what attributes are +available, and then make assertions about how they have been used: + +.. doctest:: + + >>> from mock import MagicMock + >>> thing = ProductionClass() + >>> thing.method = MagicMock(return_value=3) + >>> thing.method(3, 4, 5, key='value') + 3 + >>> thing.method.assert_called_with(3, 4, 5, key='value') + +:attr:`side_effect` allows you to perform side effects, including raising an +exception when a mock is called: + +.. doctest:: + + >>> mock = Mock(side_effect=KeyError('foo')) + >>> mock() + Traceback (most recent call last): + ... + KeyError: 'foo' + + >>> values = {'a': 1, 'b': 2, 'c': 3} + >>> def side_effect(arg): + ... return values[arg] + ... + >>> mock.side_effect = side_effect + >>> mock('a'), mock('b'), mock('c') + (1, 2, 3) + >>> mock.side_effect = [5, 4, 3, 2, 1] + >>> mock(), mock(), mock() + (5, 4, 3) + +Mock has many other ways you can configure it and control its behaviour. For +example the `spec` argument configures the mock to take its specification +from another object. Attempting to access attributes or methods on the mock +that don't exist on the spec will fail with an `AttributeError`. + +The :func:`patch` decorator / context manager makes it easy to mock classes or +objects in a module under test. The object you specify will be replaced with a +mock (or other object) during the test and restored when the test ends: + +.. doctest:: + + >>> from mock import patch + >>> @patch('module.ClassName2') + ... @patch('module.ClassName1') + ... def test(MockClass1, MockClass2): + ... module.ClassName1() + ... module.ClassName2() + + ... assert MockClass1 is module.ClassName1 + ... assert MockClass2 is module.ClassName2 + ... assert MockClass1.called + ... assert MockClass2.called + ... + >>> test() + +.. note:: + + 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 `module.ClassName1` is passed in first. + + 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 `. + +As well as a decorator `patch` can be used as a context manager in a with +statement: + +.. doctest:: + + >>> with patch.object(ProductionClass, 'method', return_value=None) as mock_method: + ... thing = ProductionClass() + ... thing.method(1, 2, 3) + ... + >>> mock_method.assert_called_once_with(1, 2, 3) + + +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: + +.. doctest:: + + >>> foo = {'key': 'value'} + >>> original = foo.copy() + >>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True): + ... assert foo == {'newkey': 'newvalue'} + ... + >>> assert foo == original + +Mock supports the mocking of Python :ref:`magic methods `. The +easiest way of using magic methods is with the :class:`MagicMock` class. It +allows you to do things like: + +.. doctest:: + + >>> mock = MagicMock() + >>> mock.__str__.return_value = 'foobarbaz' + >>> str(mock) + 'foobarbaz' + >>> mock.__str__.assert_called_with() + +Mock allows you to assign functions (or other Mock instances) to magic methods +and they will be called appropriately. The `MagicMock` class is just a Mock +variant that has all of the magic methods pre-created for you (well, all the +useful ones anyway). + +The following is an example of using magic methods with the ordinary Mock +class: + +.. doctest:: + + >>> mock = Mock() + >>> mock.__str__ = Mock(return_value='wheeeeee') + >>> str(mock) + 'wheeeeee' + +For ensuring that the mock objects in your tests have the same api as the +objects they are replacing, you can use :ref:`auto-speccing `. +Auto-speccing can be done through the `autospec` argument to patch, or the +:func:`create_autospec` function. Auto-speccing creates mock objects that +have the same attributes and methods as the objects they are replacing, and +any functions and methods (including constructors) have the same call +signature as the real object. + +This ensures that your mocks will fail in the same way as your production +code if they are used incorrectly: + +.. doctest:: + + >>> from mock import create_autospec + >>> def function(a, b, c): + ... pass + ... + >>> mock_function = create_autospec(function, return_value='fishy') + >>> mock_function(1, 2, 3) + 'fishy' + >>> mock_function.assert_called_once_with(1, 2, 3) + >>> mock_function('wrong arguments') + Traceback (most recent call last): + ... + TypeError: () takes exactly 3 arguments (1 given) + +`create_autospec` can also be used on classes, where it copies the signature of +the `__init__` method, and on callable objects where it copies the signature of +the `__call__` method. + + +.. index:: references +.. index:: articles + +References +========== + +Articles, blog entries and other stuff related to testing with Mock: + +* `Imposing a No DB Discipline on Django unit tests + `_ +* `mock-django: tools for mocking the Django ORM and models + `_ +* `PyCon 2011 Video: Testing with mock `_ +* `Mock objects in Python + `_ +* `Python: Injecting Mock Objects for Powerful Testing + `_ +* `Python Mock: How to assert a substring of logger output + `_ +* `Mocking Django `_ +* `Mocking dates and other classes that can't be modified + `_ +* `Mock recipes `_ +* `Mockity mock mock - some love for the mock module + `_ +* `Coverage and Mock (with django) + `_ +* `Python Unit Testing with Mock `_ +* `Getting started with Python Mock + `_ +* `Smart Parameter Checks with mock + `_ +* `Python mock testing techniques and tools + `_ +* `How To Test Django Template Tags + `_ +* `A presentation on Unit Testing with Mock + `_ +* `Mocking with Django and Google AppEngine + `_ + + +.. index:: tests +.. index:: unittest2 + +Tests +===== + +Mock uses `unittest2 `_ for its own +test suite. In order to run it, use the `unit2` script that comes with +`unittest2` module on a checkout of the source repository: + + `unit2 discover` + +If you have `setuptools `_ as well as +unittest2 you can run: + + ``python setup.py test`` + +On Python 3.2 you can use ``unittest`` module from the standard library. + + ``python3.2 -m unittest discover`` + +.. index:: Python 3 + +On Python 3 the tests for unicode are skipped as they are not relevant. On +Python 2.4 tests that use the with statements are skipped as the with statement +is invalid syntax on Python 2.4. + + +.. index:: older versions + +Older Versions +============== + +Documentation for older versions of mock: + +* `mock 0.8 `_ +* `mock 0.7 `_ +* `mock 0.6 `_ + +Docs from the in-development version of `mock` can be found at +`mock.readthedocs.org `_. + + +Terminology +=========== + +Terminology for objects used to replace other ones can be confusing. Terms +like double, fake, mock, stub, and spy are all used with varying meanings. + +In `classic mock terminology +`_ +:class:`mock.Mock` is a `spy `_ that +allows for *post-mortem* examination. This is what I call the "action -> +assertion" [#]_ pattern of testing. + +I'm not however a fan of this "statically typed mocking terminology" +promulgated by `Martin Fowler +`_. It confuses usage +patterns with implementation and prevents you from using natural terminology +when discussing mocking. + +I much prefer duck typing, if an object used in your test suite looks like a +mock object and quacks like a mock object then it's fine to call it a mock, no +matter what the implementation looks like. + +This terminology is perhaps more useful in less capable languages where +different usage patterns will *require* different implementations. +`mock.Mock()` is capable of being used in most of the different roles +described by Fowler, except (annoyingly / frustratingly / ironically) a Mock +itself! + +How about a simpler definition: a "mock object" is an object used to replace a +real one in a system under test. + +.. [#] This pattern is called "AAA" by some members of the testing community; + "Arrange - Act - Assert". diff --git a/python/mock-1.0.0/docs/magicmock.txt b/python/mock-1.0.0/docs/magicmock.txt new file mode 100644 index 000000000..42b2ed9db --- /dev/null +++ b/python/mock-1.0.0/docs/magicmock.txt @@ -0,0 +1,258 @@ + +.. currentmodule:: mock + + +.. _magic-methods: + +Mocking Magic Methods +===================== + +.. currentmodule:: mock + +:class:`Mock` supports mocking `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 [#]_. + +.. doctest:: + + >>> def __str__(self): + ... return 'fooble' + ... + >>> mock = Mock() + >>> mock.__str__ = __str__ + >>> str(mock) + 'fooble' + + >>> mock = Mock() + >>> mock.__str__ = Mock() + >>> mock.__str__.return_value = 'fooble' + >>> str(mock) + 'fooble' + + >>> mock = Mock() + >>> mock.__iter__ = Mock(return_value=iter([])) + >>> list(mock) + [] + +One use case for this is for mocking objects used as context managers in a +`with` statement: + +.. doctest:: + + >>> mock = Mock() + >>> mock.__enter__ = Mock(return_value='foo') + >>> mock.__exit__ = Mock(return_value=False) + >>> with mock as m: + ... assert m == 'foo' + ... + >>> mock.__enter__.assert_called_with() + >>> mock.__exit__.assert_called_with(None, None, None) + +Calls to magic methods do not appear in :attr:`~Mock.method_calls`, but they +are recorded in :attr:`~Mock.mock_calls`. + +.. note:: + + If you use the `spec` keyword argument to create a mock then attempting to + set a magic method that isn't in the spec will raise an `AttributeError`. + +The full list of supported magic methods is: + +* ``__hash__``, ``__sizeof__``, ``__repr__`` and ``__str__`` +* ``__dir__``, ``__format__`` and ``__subclasses__`` +* ``__floor__``, ``__trunc__`` and ``__ceil__`` +* Comparisons: ``__cmp__``, ``__lt__``, ``__gt__``, ``__le__``, ``__ge__``, + ``__eq__`` and ``__ne__`` +* Container methods: ``__getitem__``, ``__setitem__``, ``__delitem__``, + ``__contains__``, ``__len__``, ``__iter__``, ``__getslice__``, + ``__setslice__``, ``__reversed__`` and ``__missing__`` +* Context manager: ``__enter__`` and ``__exit__`` +* Unary numeric methods: ``__neg__``, ``__pos__`` and ``__invert__`` +* The numeric methods (including right hand and in-place variants): + ``__add__``, ``__sub__``, ``__mul__``, ``__div__``, + ``__floordiv__``, ``__mod__``, ``__divmod__``, ``__lshift__``, + ``__rshift__``, ``__and__``, ``__xor__``, ``__or__``, and ``__pow__`` +* Numeric conversion methods: ``__complex__``, ``__int__``, ``__float__``, + ``__index__`` and ``__coerce__`` +* Descriptor methods: ``__get__``, ``__set__`` and ``__delete__`` +* Pickling: ``__reduce__``, ``__reduce_ex__``, ``__getinitargs__``, + ``__getnewargs__``, ``__getstate__`` and ``__setstate__`` + + +The following methods are supported in Python 2 but don't exist in Python 3: + +* ``__unicode__``, ``__long__``, ``__oct__``, ``__hex__`` and ``__nonzero__`` +* ``__truediv__`` and ``__rtruediv__`` + +The following methods are supported in Python 3 but don't exist in Python 2: + +* ``__bool__`` and ``__next__`` + +The following methods exist but are *not* supported as they are either in use by +mock, can't be set dynamically, or can cause problems: + +* ``__getattr__``, ``__setattr__``, ``__init__`` and ``__new__`` +* ``__prepare__``, ``__instancecheck__``, ``__subclasscheck__``, ``__del__`` + + + +Magic Mock +========== + +There are two `MagicMock` variants: `MagicMock` and `NonCallableMagicMock`. + + +.. class:: MagicMock(*args, **kw) + + ``MagicMock`` is a subclass of :class:`Mock` with default implementations + of most of the magic methods. You can use ``MagicMock`` without having to + configure the magic methods yourself. + + The constructor parameters have the same meaning as for :class:`Mock`. + + If you use the `spec` or `spec_set` arguments then *only* magic methods + that exist in the spec will be created. + + +.. class:: NonCallableMagicMock(*args, **kw) + + A non-callable version of `MagicMock`. + + The constructor parameters have the same meaning as for + :class:`MagicMock`, with the exception of `return_value` and + `side_effect` which have no meaning on a non-callable mock. + +The magic methods are setup with `MagicMock` objects, so you can configure them +and use them in the usual way: + +.. doctest:: + + >>> mock = MagicMock() + >>> mock[3] = 'fish' + >>> mock.__setitem__.assert_called_with(3, 'fish') + >>> mock.__getitem__.return_value = 'result' + >>> mock[2] + 'result' + +By default many of the protocol methods are required to return objects of a +specific type. These methods are preconfigured with a default return value, so +that they can be used without you having to do anything if you aren't interested +in the return value. You can still *set* the return value manually if you want +to change the default. + +Methods and their defaults: + +* ``__lt__``: NotImplemented +* ``__gt__``: NotImplemented +* ``__le__``: NotImplemented +* ``__ge__``: NotImplemented +* ``__int__`` : 1 +* ``__contains__`` : False +* ``__len__`` : 1 +* ``__iter__`` : iter([]) +* ``__exit__`` : False +* ``__complex__`` : 1j +* ``__float__`` : 1.0 +* ``__bool__`` : True +* ``__nonzero__`` : True +* ``__oct__`` : '1' +* ``__hex__`` : '0x1' +* ``__long__`` : long(1) +* ``__index__`` : 1 +* ``__hash__`` : default hash for the mock +* ``__str__`` : default str for the mock +* ``__unicode__`` : default unicode for the mock +* ``__sizeof__``: default sizeof for the mock + +For example: + +.. doctest:: + + >>> mock = MagicMock() + >>> int(mock) + 1 + >>> len(mock) + 0 + >>> hex(mock) + '0x1' + >>> list(mock) + [] + >>> object() in mock + False + +The two equality method, `__eq__` and `__ne__`, are special (changed in +0.7.2). They do the default equality comparison on identity, using a side +effect, unless you change their return value to return something else: + +.. doctest:: + + >>> MagicMock() == 3 + False + >>> MagicMock() != 3 + True + >>> mock = MagicMock() + >>> mock.__eq__.return_value = True + >>> mock == 3 + True + +In `0.8` the `__iter__` also gained special handling implemented with a +side effect. The return value of `MagicMock.__iter__` can be any iterable +object and isn't required to be an iterator: + +.. doctest:: + + >>> mock = MagicMock() + >>> mock.__iter__.return_value = ['a', 'b', 'c'] + >>> list(mock) + ['a', 'b', 'c'] + >>> list(mock) + ['a', 'b', 'c'] + +If the return value *is* an iterator, then iterating over it once will consume +it and subsequent iterations will result in an empty list: + +.. doctest:: + + >>> mock.__iter__.return_value = iter(['a', 'b', 'c']) + >>> list(mock) + ['a', 'b', 'c'] + >>> list(mock) + [] + +``MagicMock`` has all of the supported magic methods configured except for some +of the obscure and obsolete ones. You can still set these up if you want. + +Magic methods that are supported but not setup by default in ``MagicMock`` are: + +* ``__cmp__`` +* ``__getslice__`` and ``__setslice__`` +* ``__coerce__`` +* ``__subclasses__`` +* ``__dir__`` +* ``__format__`` +* ``__get__``, ``__set__`` and ``__delete__`` +* ``__reversed__`` and ``__missing__`` +* ``__reduce__``, ``__reduce_ex__``, ``__getinitargs__``, ``__getnewargs__``, + ``__getstate__`` and ``__setstate__`` +* ``__getformat__`` and ``__setformat__`` + + + +------------ + +.. [#] Magic methods *should* be looked up on the class rather than the + instance. Different versions of Python are inconsistent about applying this + rule. The supported protocol methods should work with all supported versions + of Python. +.. [#] The function is basically hooked up to the class, but each ``Mock`` + instance is kept isolated from the others. diff --git a/python/mock-1.0.0/docs/mock.txt b/python/mock-1.0.0/docs/mock.txt new file mode 100644 index 000000000..58712b21a --- /dev/null +++ b/python/mock-1.0.0/docs/mock.txt @@ -0,0 +1,842 @@ +The Mock Class +============== + +.. currentmodule:: mock + +.. testsetup:: + + class SomeClass: + pass + + +`Mock` is a flexible mock object intended to replace the use of stubs and +test doubles throughout your code. Mocks are callable and create attributes as +new mocks when you access them [#]_. Accessing the same attribute will always +return the same mock. Mocks record how you use them, allowing you to make +assertions about what your code has done to them. + +:class:`MagicMock` is a subclass of `Mock` with all the magic methods +pre-created and ready to use. There are also non-callable variants, useful +when you are mocking out objects that aren't callable: +:class:`NonCallableMock` and :class:`NonCallableMagicMock` + +The :func:`patch` decorators makes it easy to temporarily replace classes +in a particular module with a `Mock` object. By default `patch` will create +a `MagicMock` for you. You can specify an alternative class of `Mock` using +the `new_callable` argument to `patch`. + + +.. index:: side_effect +.. index:: return_value +.. index:: wraps +.. index:: name +.. index:: spec + +.. class:: Mock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, **kwargs) + + Create a new `Mock` object. `Mock` takes several optional arguments + that specify the behaviour of the Mock object: + + * `spec`: This can be either a list of strings or an existing object (a + class or instance) that acts as the specification for the mock object. If + you pass in an object then a list of strings is formed by calling dir on + the object (excluding unsupported magic attributes and methods). + Accessing any attribute not in this list will raise an `AttributeError`. + + If `spec` is an object (rather than a list of strings) then + :attr:`__class__` returns the class of the spec object. This allows mocks + to pass `isinstance` tests. + + * `spec_set`: A stricter variant of `spec`. If used, attempting to *set* + or get an attribute on the mock that isn't on the object passed as + `spec_set` will raise an `AttributeError`. + + * `side_effect`: A function to be called whenever the Mock is called. See + the :attr:`~Mock.side_effect` attribute. Useful for raising exceptions or + dynamically changing return values. The function is called with the same + arguments as the mock, and unless it returns :data:`DEFAULT`, the return + value of this function is used as the return value. + + Alternatively `side_effect` can be an exception class or instance. In + this case the exception will be raised when the mock is called. + + If `side_effect` is an iterable then each call to the mock will return + the next value from the iterable. If any of the members of the iterable + are exceptions they will be raised instead of returned. + + A `side_effect` can be cleared by setting it to `None`. + + * `return_value`: The value returned when the mock is called. By default + this is a new Mock (created on first access). See the + :attr:`return_value` attribute. + + * `wraps`: Item for the mock object to wrap. If `wraps` is not None then + calling the Mock will pass the call through to the wrapped object + (returning the real result and ignoring `return_value`). Attribute access + on the mock will return a Mock object that wraps the corresponding + attribute of the wrapped object (so attempting to access an attribute + that doesn't exist will raise an `AttributeError`). + + If the mock has an explicit `return_value` set then calls are not passed + to the wrapped object and the `return_value` is returned instead. + + * `name`: If the mock has a name then it will be used in the repr of the + mock. This can be useful for debugging. The name is propagated to child + mocks. + + Mocks can also be called with arbitrary keyword arguments. These will be + used to set attributes on the mock after it is created. See the + :meth:`configure_mock` method for details. + + + .. method:: assert_called_with(*args, **kwargs) + + This method is a convenient way of asserting that calls are made in a + particular way: + + .. doctest:: + + >>> mock = Mock() + >>> mock.method(1, 2, 3, test='wow') + + >>> mock.method.assert_called_with(1, 2, 3, test='wow') + + + .. method:: assert_called_once_with(*args, **kwargs) + + Assert that the mock was called exactly once and with the specified + arguments. + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock('foo', bar='baz') + >>> mock.assert_called_once_with('foo', bar='baz') + >>> mock('foo', bar='baz') + >>> mock.assert_called_once_with('foo', bar='baz') + Traceback (most recent call last): + ... + AssertionError: Expected to be called once. Called 2 times. + + + .. method:: assert_any_call(*args, **kwargs) + + assert the mock has been called with the specified arguments. + + The assert passes if the mock has *ever* been called, unlike + :meth:`assert_called_with` and :meth:`assert_called_once_with` that + only pass if the call is the most recent one. + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock(1, 2, arg='thing') + >>> mock('some', 'thing', 'else') + >>> mock.assert_any_call(1, 2, arg='thing') + + + .. method:: assert_has_calls(calls, any_order=False) + + assert the mock has been called with the specified calls. + The `mock_calls` list is checked for the calls. + + If `any_order` is False (the default) then the calls must be + sequential. There can be extra calls before or after the + specified calls. + + If `any_order` is True then the calls can be in any order, but + they must all appear in :attr:`mock_calls`. + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock(1) + >>> mock(2) + >>> mock(3) + >>> mock(4) + >>> calls = [call(2), call(3)] + >>> mock.assert_has_calls(calls) + >>> calls = [call(4), call(2), call(3)] + >>> mock.assert_has_calls(calls, any_order=True) + + + .. method:: reset_mock() + + The reset_mock method resets all the call attributes on a mock object: + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock('hello') + >>> mock.called + True + >>> mock.reset_mock() + >>> mock.called + False + + This can be useful where you want to make a series of assertions that + reuse the same object. Note that `reset_mock` *doesn't* clear the + return value, :attr:`side_effect` or any child attributes you have + set using normal assignment. Child mocks and the return value mock + (if any) are reset as well. + + + .. method:: mock_add_spec(spec, spec_set=False) + + Add a spec to a mock. `spec` can either be an object or a + list of strings. Only attributes on the `spec` can be fetched as + attributes from the mock. + + If `spec_set` is `True` then only attributes on the spec can be set. + + + .. method:: attach_mock(mock, attribute) + + Attach a mock as an attribute of this one, replacing its name and + parent. Calls to the attached mock will be recorded in the + :attr:`method_calls` and :attr:`mock_calls` attributes of this one. + + + .. method:: configure_mock(**kwargs) + + Set attributes on the mock through keyword arguments. + + Attributes plus return values and side effects can be set on child + mocks using standard dot notation and unpacking a dictionary in the + method call: + + .. doctest:: + + >>> mock = Mock() + >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} + >>> mock.configure_mock(**attrs) + >>> mock.method() + 3 + >>> mock.other() + Traceback (most recent call last): + ... + KeyError + + The same thing can be achieved in the constructor call to mocks: + + .. doctest:: + + >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} + >>> mock = Mock(some_attribute='eggs', **attrs) + >>> mock.some_attribute + 'eggs' + >>> mock.method() + 3 + >>> mock.other() + Traceback (most recent call last): + ... + KeyError + + `configure_mock` exists to make it easier to do configuration + after the mock has been created. + + + .. method:: __dir__() + + `Mock` objects limit the results of `dir(some_mock)` to useful results. + For mocks with a `spec` this includes all the permitted attributes + for the mock. + + See :data:`FILTER_DIR` for what this filtering does, and how to + switch it off. + + + .. method:: _get_child_mock(**kw) + + Create the child mocks for attributes and return value. + By default child mocks will be the same type as the parent. + Subclasses of Mock may want to override this to customize the way + child mocks are made. + + For non-callable mocks the callable variant will be used (rather than + any custom subclass). + + + .. attribute:: called + + A boolean representing whether or not the mock object has been called: + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock.called + False + >>> mock() + >>> mock.called + True + + .. attribute:: call_count + + An integer telling you how many times the mock object has been called: + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock.call_count + 0 + >>> mock() + >>> mock() + >>> mock.call_count + 2 + + + .. attribute:: return_value + + Set this to configure the value returned by calling the mock: + + .. doctest:: + + >>> mock = Mock() + >>> mock.return_value = 'fish' + >>> mock() + 'fish' + + The default return value is a mock object and you can configure it in + the normal way: + + .. doctest:: + + >>> mock = Mock() + >>> mock.return_value.attribute = sentinel.Attribute + >>> mock.return_value() + + >>> mock.return_value.assert_called_with() + + `return_value` can also be set in the constructor: + + .. doctest:: + + >>> mock = Mock(return_value=3) + >>> mock.return_value + 3 + >>> mock() + 3 + + + .. attribute:: side_effect + + This can either be a function to be called when the mock is called, + or an exception (class or instance) to be raised. + + If you pass in a function it will be called with same arguments as the + mock and unless the function returns the :data:`DEFAULT` singleton the + call to the mock will then return whatever the function returns. If the + function returns :data:`DEFAULT` then the mock will return its normal + value (from the :attr:`return_value`. + + An example of a mock that raises an exception (to test exception + handling of an API): + + .. doctest:: + + >>> mock = Mock() + >>> mock.side_effect = Exception('Boom!') + >>> mock() + Traceback (most recent call last): + ... + Exception: Boom! + + Using `side_effect` to return a sequence of values: + + .. doctest:: + + >>> mock = Mock() + >>> mock.side_effect = [3, 2, 1] + >>> mock(), mock(), mock() + (3, 2, 1) + + The `side_effect` function is called with the same arguments as the + mock (so it is wise for it to take arbitrary args and keyword + arguments) and whatever it returns is used as the return value for + the call. The exception is if `side_effect` returns :data:`DEFAULT`, + in which case the normal :attr:`return_value` is used. + + .. doctest:: + + >>> mock = Mock(return_value=3) + >>> def side_effect(*args, **kwargs): + ... return DEFAULT + ... + >>> mock.side_effect = side_effect + >>> mock() + 3 + + `side_effect` can be set in the constructor. Here's an example that + adds one to the value the mock is called with and returns it: + + .. doctest:: + + >>> side_effect = lambda value: value + 1 + >>> mock = Mock(side_effect=side_effect) + >>> mock(3) + 4 + >>> mock(-8) + -7 + + Setting `side_effect` to `None` clears it: + + .. doctest:: + + >>> from mock import Mock + >>> m = Mock(side_effect=KeyError, return_value=3) + >>> m() + Traceback (most recent call last): + ... + KeyError + >>> m.side_effect = None + >>> m() + 3 + + + .. attribute:: call_args + + This is either `None` (if the mock hasn't been called), or the + arguments that the mock was last called with. This will be in the + form of a tuple: the first member is any ordered arguments the mock + was called with (or an empty tuple) and the second member is any + keyword arguments (or an empty dictionary). + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> print mock.call_args + None + >>> mock() + >>> mock.call_args + call() + >>> mock.call_args == () + True + >>> mock(3, 4) + >>> mock.call_args + call(3, 4) + >>> mock.call_args == ((3, 4),) + True + >>> mock(3, 4, 5, key='fish', next='w00t!') + >>> mock.call_args + call(3, 4, 5, key='fish', next='w00t!') + + `call_args`, along with members of the lists :attr:`call_args_list`, + :attr:`method_calls` and :attr:`mock_calls` are :data:`call` objects. + These are tuples, so they can be unpacked to get at the individual + arguments and make more complex assertions. See + :ref:`calls as tuples `. + + + .. attribute:: call_args_list + + This is a list of all the calls made to the mock object in sequence + (so the length of the list is the number of times it has been + called). Before any calls have been made it is an empty list. The + :data:`call` object can be used for conveniently constructing lists of + calls to compare with `call_args_list`. + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock() + >>> mock(3, 4) + >>> mock(key='fish', next='w00t!') + >>> mock.call_args_list + [call(), call(3, 4), call(key='fish', next='w00t!')] + >>> expected = [(), ((3, 4),), ({'key': 'fish', 'next': 'w00t!'},)] + >>> mock.call_args_list == expected + True + + Members of `call_args_list` are :data:`call` objects. These can be + unpacked as tuples to get at the individual arguments. See + :ref:`calls as tuples `. + + + .. attribute:: method_calls + + As well as tracking calls to themselves, mocks also track calls to + methods and attributes, and *their* methods and attributes: + + .. doctest:: + + >>> mock = Mock() + >>> mock.method() + + >>> mock.property.method.attribute() + + >>> mock.method_calls + [call.method(), call.property.method.attribute()] + + Members of `method_calls` are :data:`call` objects. These can be + unpacked as tuples to get at the individual arguments. See + :ref:`calls as tuples `. + + + .. attribute:: mock_calls + + `mock_calls` records *all* calls to the mock object, its methods, magic + methods *and* return value mocks. + + .. doctest:: + + >>> mock = MagicMock() + >>> result = mock(1, 2, 3) + >>> mock.first(a=3) + + >>> mock.second() + + >>> int(mock) + 1 + >>> result(1) + + >>> expected = [call(1, 2, 3), call.first(a=3), call.second(), + ... call.__int__(), call()(1)] + >>> mock.mock_calls == expected + True + + Members of `mock_calls` are :data:`call` objects. These can be + unpacked as tuples to get at the individual arguments. See + :ref:`calls as tuples `. + + + .. attribute:: __class__ + + Normally the `__class__` attribute of an object will return its type. + For a mock object with a `spec` `__class__` returns the spec class + instead. This allows mock objects to pass `isinstance` tests for the + object they are replacing / masquerading as: + + .. doctest:: + + >>> mock = Mock(spec=3) + >>> isinstance(mock, int) + True + + `__class__` is assignable to, this allows a mock to pass an + `isinstance` check without forcing you to use a spec: + + .. doctest:: + + >>> mock = Mock() + >>> mock.__class__ = dict + >>> isinstance(mock, dict) + True + +.. class:: NonCallableMock(spec=None, wraps=None, name=None, spec_set=None, **kwargs) + + A non-callable version of `Mock`. The constructor parameters have the same + meaning of `Mock`, with the exception of `return_value` and `side_effect` + which have no meaning on a non-callable mock. + +Mock objects that use a class or an instance as a `spec` or `spec_set` are able +to pass `isintance` tests: + +.. doctest:: + + >>> mock = Mock(spec=SomeClass) + >>> isinstance(mock, SomeClass) + True + >>> mock = Mock(spec_set=SomeClass()) + >>> isinstance(mock, SomeClass) + True + +The `Mock` classes have support for mocking magic methods. See :ref:`magic +methods ` for the full details. + +The mock classes and the :func:`patch` decorators all take arbitrary keyword +arguments for configuration. For the `patch` decorators the keywords are +passed to the constructor of the mock being created. The keyword arguments +are for configuring attributes of the mock: + +.. doctest:: + + >>> m = MagicMock(attribute=3, other='fish') + >>> m.attribute + 3 + >>> m.other + 'fish' + +The return value and side effect of child mocks can be set in the same way, +using dotted notation. As you can't use dotted names directly in a call you +have to create a dictionary and unpack it using `**`: + +.. doctest:: + + >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} + >>> mock = Mock(some_attribute='eggs', **attrs) + >>> mock.some_attribute + 'eggs' + >>> mock.method() + 3 + >>> mock.other() + Traceback (most recent call last): + ... + KeyError + + +.. class:: PropertyMock(*args, **kwargs) + + A mock intended to be used as a property, or other descriptor, on a class. + `PropertyMock` provides `__get__` and `__set__` methods so you can specify + a return value when it is fetched. + + Fetching a `PropertyMock` instance from an object calls the mock, with + no args. Setting it calls the mock with the value being set. + + .. doctest:: + + >>> class Foo(object): + ... @property + ... def foo(self): + ... return 'something' + ... @foo.setter + ... def foo(self, value): + ... pass + ... + >>> with patch('__main__.Foo.foo', new_callable=PropertyMock) as mock_foo: + ... mock_foo.return_value = 'mockity-mock' + ... this_foo = Foo() + ... print this_foo.foo + ... this_foo.foo = 6 + ... + mockity-mock + >>> mock_foo.mock_calls + [call(), call(6)] + +Because of the way mock attributes are stored you can't directly attach a +`PropertyMock` to a mock object. Instead you can attach it to the mock type +object: + +.. doctest:: + + >>> m = MagicMock() + >>> p = PropertyMock(return_value=3) + >>> type(m).foo = p + >>> m.foo + 3 + >>> p.assert_called_once_with() + + +.. index:: __call__ +.. index:: calling + +Calling +======= + +Mock objects are callable. The call will return the value set as the +:attr:`~Mock.return_value` attribute. The default return value is a new Mock +object; it is created the first time the return value is accessed (either +explicitly or by calling the Mock) - but it is stored and the same one +returned each time. + +Calls made to the object will be recorded in the attributes +like :attr:`~Mock.call_args` and :attr:`~Mock.call_args_list`. + +If :attr:`~Mock.side_effect` is set then it will be called after the call has +been recorded, so if `side_effect` raises an exception the call is still +recorded. + +The simplest way to make a mock raise an exception when called is to make +:attr:`~Mock.side_effect` an exception class or instance: + +.. doctest:: + + >>> m = MagicMock(side_effect=IndexError) + >>> m(1, 2, 3) + Traceback (most recent call last): + ... + IndexError + >>> m.mock_calls + [call(1, 2, 3)] + >>> m.side_effect = KeyError('Bang!') + >>> m('two', 'three', 'four') + Traceback (most recent call last): + ... + KeyError: 'Bang!' + >>> m.mock_calls + [call(1, 2, 3), call('two', 'three', 'four')] + +If `side_effect` is a function then whatever that function returns is what +calls to the mock return. The `side_effect` function is called with the +same arguments as the mock. This allows you to vary the return value of the +call dynamically, based on the input: + +.. doctest:: + + >>> def side_effect(value): + ... return value + 1 + ... + >>> m = MagicMock(side_effect=side_effect) + >>> m(1) + 2 + >>> m(2) + 3 + >>> m.mock_calls + [call(1), call(2)] + +If you want the mock to still return the default return value (a new mock), or +any set return value, then there are two ways of doing this. Either return +`mock.return_value` from inside `side_effect`, or return :data:`DEFAULT`: + +.. doctest:: + + >>> m = MagicMock() + >>> def side_effect(*args, **kwargs): + ... return m.return_value + ... + >>> m.side_effect = side_effect + >>> m.return_value = 3 + >>> m() + 3 + >>> def side_effect(*args, **kwargs): + ... return DEFAULT + ... + >>> m.side_effect = side_effect + >>> m() + 3 + +To remove a `side_effect`, and return to the default behaviour, set the +`side_effect` to `None`: + +.. doctest:: + + >>> m = MagicMock(return_value=6) + >>> def side_effect(*args, **kwargs): + ... return 3 + ... + >>> m.side_effect = side_effect + >>> m() + 3 + >>> m.side_effect = None + >>> m() + 6 + +The `side_effect` can also be any iterable object. Repeated calls to the mock +will return values from the iterable (until the iterable is exhausted and +a `StopIteration` is raised): + +.. doctest:: + + >>> m = MagicMock(side_effect=[1, 2, 3]) + >>> m() + 1 + >>> m() + 2 + >>> m() + 3 + >>> m() + Traceback (most recent call last): + ... + StopIteration + +If any members of the iterable are exceptions they will be raised instead of +returned: + +.. doctest:: + + >>> iterable = (33, ValueError, 66) + >>> m = MagicMock(side_effect=iterable) + >>> m() + 33 + >>> m() + Traceback (most recent call last): + ... + ValueError + >>> m() + 66 + + +.. _deleting-attributes: + +Deleting Attributes +=================== + +Mock objects create attributes on demand. This allows them to pretend to be +objects of any type. + +You may want a mock object to return `False` to a `hasattr` call, or raise an +`AttributeError` when an attribute is fetched. You can do this by providing +an object as a `spec` for a mock, but that isn't always convenient. + +You "block" attributes by deleting them. Once deleted, accessing an attribute +will raise an `AttributeError`. + +.. doctest:: + + >>> mock = MagicMock() + >>> hasattr(mock, 'm') + True + >>> del mock.m + >>> hasattr(mock, 'm') + False + >>> del mock.f + >>> mock.f + Traceback (most recent call last): + ... + AttributeError: f + + +Attaching Mocks as Attributes +============================= + +When you attach a mock as an attribute of another mock (or as the return +value) it becomes a "child" of that mock. Calls to the child are recorded in +the :attr:`~Mock.method_calls` and :attr:`~Mock.mock_calls` attributes of the +parent. This is useful for configuring child mocks and then attaching them to +the parent, or for attaching mocks to a parent that records all calls to the +children and allows you to make assertions about the order of calls between +mocks: + +.. doctest:: + + >>> parent = MagicMock() + >>> child1 = MagicMock(return_value=None) + >>> child2 = MagicMock(return_value=None) + >>> parent.child1 = child1 + >>> parent.child2 = child2 + >>> child1(1) + >>> child2(2) + >>> parent.mock_calls + [call.child1(1), call.child2(2)] + +The exception to this is if the mock has a name. This allows you to prevent +the "parenting" if for some reason you don't want it to happen. + +.. doctest:: + + >>> mock = MagicMock() + >>> not_a_child = MagicMock(name='not-a-child') + >>> mock.attribute = not_a_child + >>> mock.attribute() + + >>> mock.mock_calls + [] + +Mocks created for you by :func:`patch` are automatically given names. To +attach mocks that have names to a parent you use the :meth:`~Mock.attach_mock` +method: + +.. doctest:: + + >>> thing1 = object() + >>> thing2 = object() + >>> parent = MagicMock() + >>> with patch('__main__.thing1', return_value=None) as child1: + ... with patch('__main__.thing2', return_value=None) as child2: + ... parent.attach_mock(child1, 'child1') + ... parent.attach_mock(child2, 'child2') + ... child1('one') + ... child2('two') + ... + >>> parent.mock_calls + [call.child1('one'), call.child2('two')] + + +----- + +.. [#] The only exceptions are magic methods and attributes (those that have + leading and trailing double underscores). Mock doesn't create these but + instead of raises an ``AttributeError``. This is because the interpreter + will often implicitly request these methods, and gets *very* confused to + get a new Mock object when it expects a magic method. If you need magic + method support see :ref:`magic methods `. diff --git a/python/mock-1.0.0/docs/patch.txt b/python/mock-1.0.0/docs/patch.txt new file mode 100644 index 000000000..3d56264fb --- /dev/null +++ b/python/mock-1.0.0/docs/patch.txt @@ -0,0 +1,636 @@ +================== + Patch Decorators +================== + + +.. currentmodule:: mock + +.. testsetup:: + + class SomeClass(object): + static_method = None + class_method = None + attribute = None + + sys.modules['package'] = package = Mock(name='package') + sys.modules['package.module'] = package.module + + class TestCase(unittest2.TestCase): + def run(self): + result = unittest2.TestResult() + super(unittest2.TestCase, self).run(result) + assert result.wasSuccessful() + +.. testcleanup:: + + patch.TEST_PREFIX = 'test' + + +The patch decorators are used for patching objects only within the scope of +the function they decorate. They automatically handle the unpatching for you, +even if exceptions are raised. All of these functions can also be used in with +statements or as class decorators. + + +patch +===== + +.. note:: + + `patch` is straightforward to use. The key is to do the patching in the + right namespace. See the section `where to patch`_. + +.. function:: patch(target, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs) + + `patch` acts as a function decorator, class decorator or a context + manager. Inside the body of the function or with statement, the `target` + is patched with a `new` object. When the function/with statement exits + the patch is undone. + + If `new` is omitted, then the target is replaced with a + :class:`MagicMock`. If `patch` is used as a decorator and `new` is + omitted, the created mock is passed in as an extra argument to the + decorated function. If `patch` is used as a context manager the created + mock is returned by the context manager. + + `target` should be a string in the form `'package.module.ClassName'`. The + `target` is imported and the specified object replaced with the `new` + object, so the `target` must be importable from the environment you are + calling `patch` from. The target is imported when the decorated function + is executed, not at decoration time. + + The `spec` and `spec_set` keyword arguments are passed to the `MagicMock` + if patch is creating one for you. + + In addition you can pass `spec=True` or `spec_set=True`, which causes + patch to pass in the object being mocked as the spec/spec_set object. + + `new_callable` allows you to specify a different class, or callable object, + that will be called to create the `new` object. By default `MagicMock` is + used. + + A more powerful form of `spec` is `autospec`. If you set `autospec=True` + then the mock with be created with a spec from the object being replaced. + All attributes of the mock will also have the spec of the corresponding + attribute of the object being replaced. Methods and functions being mocked + will have their arguments checked and will raise a `TypeError` if they are + called with the wrong signature. For mocks + replacing a class, their return value (the 'instance') will have the same + spec as the class. See the :func:`create_autospec` function and + :ref:`auto-speccing`. + + Instead of `autospec=True` you can pass `autospec=some_object` to use an + arbitrary object as the spec instead of the one being replaced. + + By default `patch` will fail to replace attributes that don't exist. If + you pass in `create=True`, and the attribute doesn't exist, patch will + create the attribute for you when the patched function is called, and + delete it again afterwards. This is useful for writing tests against + attributes that your production code creates at runtime. It is off by by + default because it can be dangerous. With it switched on you can write + passing tests against APIs that don't actually exist! + + Patch can be used as a `TestCase` class decorator. It works by + decorating each test method in the class. This reduces the boilerplate + code when your test methods share a common patchings set. `patch` finds + tests by looking for method names that start with `patch.TEST_PREFIX`. + By default this is `test`, which matches the way `unittest` finds tests. + You can specify an alternative prefix by setting `patch.TEST_PREFIX`. + + Patch can be used as a context manager, with the with statement. Here the + patching applies to the indented block after the with statement. If you + use "as" then the patched object will be bound to the name after the + "as"; very useful if `patch` is creating a mock object for you. + + `patch` takes arbitrary keyword arguments. These will be passed to + the `Mock` (or `new_callable`) on construction. + + `patch.dict(...)`, `patch.multiple(...)` and `patch.object(...)` are + available for alternate use-cases. + +`patch` as function decorator, creating the mock for you and passing it into +the decorated function: + +.. doctest:: + + >>> @patch('__main__.SomeClass') + ... def function(normal_argument, mock_class): + ... print mock_class is SomeClass + ... + >>> function(None) + True + + +Patching a class replaces the class with a `MagicMock` *instance*. If the +class is instantiated in the code under test then it will be the +:attr:`~Mock.return_value` of the mock that will be used. + +If the class is instantiated multiple times you could use +:attr:`~Mock.side_effect` to return a new mock each time. Alternatively you +can set the `return_value` to be anything you want. + +To configure return values on methods of *instances* on the patched class +you must do this on the `return_value`. For example: + +.. doctest:: + + >>> class Class(object): + ... def method(self): + ... pass + ... + >>> with patch('__main__.Class') as MockClass: + ... instance = MockClass.return_value + ... instance.method.return_value = 'foo' + ... assert Class() is instance + ... assert Class().method() == 'foo' + ... + +If you use `spec` or `spec_set` and `patch` is replacing a *class*, then the +return value of the created mock will have the same spec. + +.. doctest:: + + >>> Original = Class + >>> patcher = patch('__main__.Class', spec=True) + >>> MockClass = patcher.start() + >>> instance = MockClass() + >>> assert isinstance(instance, Original) + >>> patcher.stop() + +The `new_callable` argument is useful where you want to use an alternative +class to the default :class:`MagicMock` for the created mock. For example, if +you wanted a :class:`NonCallableMock` to be used: + +.. doctest:: + + >>> thing = object() + >>> with patch('__main__.thing', new_callable=NonCallableMock) as mock_thing: + ... assert thing is mock_thing + ... thing() + ... + Traceback (most recent call last): + ... + TypeError: 'NonCallableMock' object is not callable + +Another use case might be to replace an object with a `StringIO` instance: + +.. doctest:: + + >>> from StringIO import StringIO + >>> def foo(): + ... print 'Something' + ... + >>> @patch('sys.stdout', new_callable=StringIO) + ... def test(mock_stdout): + ... foo() + ... assert mock_stdout.getvalue() == 'Something\n' + ... + >>> test() + +When `patch` is creating a mock for you, it is common that the first thing +you need to do is to configure the mock. Some of that configuration can be done +in the call to patch. Any arbitrary keywords you pass into the call will be +used to set attributes on the created mock: + +.. doctest:: + + >>> patcher = patch('__main__.thing', first='one', second='two') + >>> mock_thing = patcher.start() + >>> mock_thing.first + 'one' + >>> mock_thing.second + 'two' + +As well as attributes on the created mock attributes, like the +:attr:`~Mock.return_value` and :attr:`~Mock.side_effect`, of child mocks can +also be configured. These aren't syntactically valid to pass in directly as +keyword arguments, but a dictionary with these as keys can still be expanded +into a `patch` call using `**`: + +.. doctest:: + + >>> config = {'method.return_value': 3, 'other.side_effect': KeyError} + >>> patcher = patch('__main__.thing', **config) + >>> mock_thing = patcher.start() + >>> mock_thing.method() + 3 + >>> mock_thing.other() + Traceback (most recent call last): + ... + KeyError + + +patch.object +============ + +.. function:: patch.object(target, attribute, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs) + + patch the named member (`attribute`) on an object (`target`) with a mock + object. + + `patch.object` can be used as a decorator, class decorator or a context + manager. Arguments `new`, `spec`, `create`, `spec_set`, `autospec` and + `new_callable` have the same meaning as for `patch`. Like `patch`, + `patch.object` takes arbitrary keyword arguments for configuring the mock + object it creates. + + When used as a class decorator `patch.object` honours `patch.TEST_PREFIX` + for choosing which methods to wrap. + +You can either call `patch.object` with three arguments or two arguments. The +three argument form takes the object to be patched, the attribute name and the +object to replace the attribute with. + +When calling with the two argument form you omit the replacement object, and a +mock is created for you and passed in as an extra argument to the decorated +function: + +.. doctest:: + + >>> @patch.object(SomeClass, 'class_method') + ... def test(mock_method): + ... SomeClass.class_method(3) + ... mock_method.assert_called_with(3) + ... + >>> test() + +`spec`, `create` and the other arguments to `patch.object` have the same +meaning as they do for `patch`. + + +patch.dict +========== + +.. function:: patch.dict(in_dict, values=(), clear=False, **kwargs) + + Patch a dictionary, or dictionary like object, and restore the dictionary + to its original state after the test. + + `in_dict` can be a dictionary or a mapping like container. If it is a + mapping then it must at least support getting, setting and deleting items + plus iterating over keys. + + `in_dict` can also be a string specifying the name of the dictionary, which + will then be fetched by importing it. + + `values` can be a dictionary of values to set in the dictionary. `values` + can also be an iterable of `(key, value)` pairs. + + If `clear` is True then the dictionary will be cleared before the new + values are set. + + `patch.dict` can also be called with arbitrary keyword arguments to set + values in the dictionary. + + `patch.dict` can be used as a context manager, decorator or class + decorator. When used as a class decorator `patch.dict` honours + `patch.TEST_PREFIX` for choosing which methods to wrap. + +`patch.dict` can be used to add members to a dictionary, or simply let a test +change a dictionary, and ensure the dictionary is restored when the test +ends. + +.. doctest:: + + >>> from mock import patch + >>> foo = {} + >>> with patch.dict(foo, {'newkey': 'newvalue'}): + ... assert foo == {'newkey': 'newvalue'} + ... + >>> assert foo == {} + + >>> import os + >>> with patch.dict('os.environ', {'newkey': 'newvalue'}): + ... print os.environ['newkey'] + ... + newvalue + >>> assert 'newkey' not in os.environ + +Keywords can be used in the `patch.dict` call to set values in the dictionary: + +.. doctest:: + + >>> mymodule = MagicMock() + >>> mymodule.function.return_value = 'fish' + >>> with patch.dict('sys.modules', mymodule=mymodule): + ... import mymodule + ... mymodule.function('some', 'args') + ... + 'fish' + +`patch.dict` can be used with dictionary like objects that aren't actually +dictionaries. At the very minimum they must support item getting, setting, +deleting and either iteration or membership test. This corresponds to the +magic methods `__getitem__`, `__setitem__`, `__delitem__` and either +`__iter__` or `__contains__`. + +.. doctest:: + + >>> class Container(object): + ... def __init__(self): + ... self.values = {} + ... def __getitem__(self, name): + ... return self.values[name] + ... def __setitem__(self, name, value): + ... self.values[name] = value + ... def __delitem__(self, name): + ... del self.values[name] + ... def __iter__(self): + ... return iter(self.values) + ... + >>> thing = Container() + >>> thing['one'] = 1 + >>> with patch.dict(thing, one=2, two=3): + ... assert thing['one'] == 2 + ... assert thing['two'] == 3 + ... + >>> assert thing['one'] == 1 + >>> assert list(thing) == ['one'] + + +patch.multiple +============== + +.. function:: patch.multiple(target, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs) + + Perform multiple patches in a single call. It takes the object to be + patched (either as an object or a string to fetch the object by importing) + and keyword arguments for the patches:: + + with patch.multiple(settings, FIRST_PATCH='one', SECOND_PATCH='two'): + ... + + Use :data:`DEFAULT` as the value if you want `patch.multiple` to create + mocks for you. In this case the created mocks are passed into a decorated + function by keyword, and a dictionary is returned when `patch.multiple` is + used as a context manager. + + `patch.multiple` can be used as a decorator, class decorator or a context + manager. The arguments `spec`, `spec_set`, `create`, `autospec` and + `new_callable` have the same meaning as for `patch`. These arguments will + be applied to *all* patches done by `patch.multiple`. + + When used as a class decorator `patch.multiple` honours `patch.TEST_PREFIX` + for choosing which methods to wrap. + +If you want `patch.multiple` to create mocks for you, then you can use +:data:`DEFAULT` as the value. If you use `patch.multiple` as a decorator +then the created mocks are passed into the decorated function by keyword. + +.. doctest:: + + >>> thing = object() + >>> other = object() + + >>> @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) + ... def test_function(thing, other): + ... assert isinstance(thing, MagicMock) + ... assert isinstance(other, MagicMock) + ... + >>> test_function() + +`patch.multiple` can be nested with other `patch` decorators, but put arguments +passed by keyword *after* any of the standard arguments created by `patch`: + +.. doctest:: + + >>> @patch('sys.exit') + ... @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) + ... def test_function(mock_exit, other, thing): + ... assert 'other' in repr(other) + ... assert 'thing' in repr(thing) + ... assert 'exit' in repr(mock_exit) + ... + >>> test_function() + +If `patch.multiple` is used as a context manager, the value returned by the +context manger is a dictionary where created mocks are keyed by name: + +.. doctest:: + + >>> with patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) as values: + ... assert 'other' in repr(values['other']) + ... assert 'thing' in repr(values['thing']) + ... assert values['thing'] is thing + ... assert values['other'] is other + ... + + +.. _start-and-stop: + +patch methods: start and stop +============================= + +All the patchers have `start` and `stop` methods. These make it simpler to do +patching in `setUp` methods or where you want to do multiple patches without +nesting decorators or with statements. + +To use them call `patch`, `patch.object` or `patch.dict` as normal and keep a +reference to the returned `patcher` object. You can then call `start` to put +the patch in place and `stop` to undo it. + +If you are using `patch` to create a mock for you then it will be returned by +the call to `patcher.start`. + +.. doctest:: + + >>> patcher = patch('package.module.ClassName') + >>> from package import module + >>> original = module.ClassName + >>> new_mock = patcher.start() + >>> assert module.ClassName is not original + >>> assert module.ClassName is new_mock + >>> patcher.stop() + >>> assert module.ClassName is original + >>> assert module.ClassName is not new_mock + + +A typical use case for this might be for doing multiple patches in the `setUp` +method of a `TestCase`: + +.. doctest:: + + >>> class MyTest(TestCase): + ... def setUp(self): + ... self.patcher1 = patch('package.module.Class1') + ... self.patcher2 = patch('package.module.Class2') + ... self.MockClass1 = self.patcher1.start() + ... self.MockClass2 = self.patcher2.start() + ... + ... def tearDown(self): + ... self.patcher1.stop() + ... self.patcher2.stop() + ... + ... def test_something(self): + ... assert package.module.Class1 is self.MockClass1 + ... assert package.module.Class2 is self.MockClass2 + ... + >>> MyTest('test_something').run() + +.. caution:: + + If you use this technique you must ensure that the patching is "undone" by + calling `stop`. This can be fiddlier than you might think, because if an + exception is raised in the setUp then tearDown is not called. `unittest2 + `_ cleanup functions make this + easier. + + .. doctest:: + + >>> class MyTest(TestCase): + ... def setUp(self): + ... patcher = patch('package.module.Class') + ... self.MockClass = patcher.start() + ... self.addCleanup(patcher.stop) + ... + ... def test_something(self): + ... assert package.module.Class is self.MockClass + ... + >>> MyTest('test_something').run() + + As an added bonus you no longer need to keep a reference to the `patcher` + object. + +It is also possible to stop all patches which have been started by using +`patch.stopall`. + +.. function:: patch.stopall + + Stop all active patches. Only stops patches started with `start`. + + +TEST_PREFIX +=========== + +All of the patchers can be used as class decorators. When used in this way +they wrap every test method on the class. The patchers recognise methods that +start with `test` as being test methods. This is the same way that the +`unittest.TestLoader` finds test methods by default. + +It is possible that you want to use a different prefix for your tests. You can +inform the patchers of the different prefix by setting `patch.TEST_PREFIX`: + +.. doctest:: + + >>> patch.TEST_PREFIX = 'foo' + >>> value = 3 + >>> + >>> @patch('__main__.value', 'not three') + ... class Thing(object): + ... def foo_one(self): + ... print value + ... def foo_two(self): + ... print value + ... + >>> + >>> Thing().foo_one() + not three + >>> Thing().foo_two() + not three + >>> value + 3 + + +Nesting Patch Decorators +======================== + +If you want to perform multiple patches then you can simply stack up the +decorators. + +You can stack up multiple patch decorators using this pattern: + +.. doctest:: + + >>> @patch.object(SomeClass, 'class_method') + ... @patch.object(SomeClass, 'static_method') + ... def test(mock1, mock2): + ... assert SomeClass.static_method is mock1 + ... assert SomeClass.class_method is mock2 + ... SomeClass.static_method('foo') + ... SomeClass.class_method('bar') + ... return mock1, mock2 + ... + >>> mock1, mock2 = test() + >>> mock1.assert_called_once_with('foo') + >>> mock2.assert_called_once_with('bar') + + +Note that the decorators are applied from the bottom upwards. This is the +standard way that Python applies decorators. The order of the created mocks +passed into your test function matches this order. + +Like all context-managers patches can be nested using contextlib's nested +function; *every* patching will appear in the tuple after "as": + +.. doctest:: + + >>> from contextlib import nested + >>> with nested( + ... patch('package.module.ClassName1'), + ... patch('package.module.ClassName2') + ... ) as (MockClass1, MockClass2): + ... assert package.module.ClassName1 is MockClass1 + ... assert package.module.ClassName2 is MockClass2 + ... + + +.. _where-to-patch: + +Where to patch +============== + +`patch` works by (temporarily) changing the object that a *name* points to with +another one. There can be many names pointing to any individual object, so +for patching to work you must ensure that you patch the name used by the system +under test. + +The basic principle is that you patch where an object is *looked up*, which +is not necessarily the same place as where it is defined. A couple of +examples will help to clarify this. + +Imagine we have a project that we want to test with the following structure:: + + a.py + -> Defines SomeClass + + b.py + -> from a import SomeClass + -> some_function instantiates SomeClass + +Now we want to test `some_function` but we want to mock out `SomeClass` using +`patch`. The problem is that when we import module b, which we will have to +do then it imports `SomeClass` from module a. If we use `patch` to mock out +`a.SomeClass` then it will have no effect on our test; module b already has a +reference to the *real* `SomeClass` and it looks like our patching had no +effect. + +The key is to patch out `SomeClass` where it is used (or where it is looked up +). In this case `some_function` will actually look up `SomeClass` in module b, +where we have imported it. The patching should look like: + + `@patch('b.SomeClass')` + +However, consider the alternative scenario where instead of `from a import +SomeClass` module b does `import a` and `some_function` uses `a.SomeClass`. Both +of these import forms are common. In this case the class we want to patch is +being looked up on the a module and so we have to patch `a.SomeClass` instead: + + `@patch('a.SomeClass')` + + +Patching Descriptors and Proxy Objects +====================================== + +Since version 0.6.0 both patch_ and patch.object_ have been able to correctly +patch and restore descriptors: class methods, static methods and properties. +You should patch these on the *class* rather than an instance. + +Since version 0.7.0 patch_ and patch.object_ work correctly with some objects +that proxy attribute access, like the `django setttings object +`_. + +.. note:: + + In django `import settings` and `from django.conf import settings` + return different objects. If you are using libraries / apps that do both you + may have to patch both. Grrr... diff --git a/python/mock-1.0.0/docs/sentinel.txt b/python/mock-1.0.0/docs/sentinel.txt new file mode 100644 index 000000000..1c5223da0 --- /dev/null +++ b/python/mock-1.0.0/docs/sentinel.txt @@ -0,0 +1,58 @@ +========== + Sentinel +========== + + +.. currentmodule:: mock + +.. testsetup:: + + class ProductionClass(object): + def something(self): + return self.method() + + class Test(unittest2.TestCase): + def testSomething(self): + pass + self = Test('testSomething') + + +.. data:: sentinel + + The ``sentinel`` object provides a convenient way of providing unique + objects for your tests. + + Attributes are created on demand when you access them by name. Accessing + the same attribute will always return the same object. The objects + returned have a sensible repr so that test failure messages are readable. + + +.. data:: DEFAULT + + The `DEFAULT` object is a pre-created sentinel (actually + `sentinel.DEFAULT`). It can be used by :attr:`~Mock.side_effect` + functions to indicate that the normal return value should be used. + + +Sentinel Example +================ + +Sometimes when testing you need to test that a specific object is passed as an +argument to another method, or returned. It can be common to create named +sentinel objects to test this. `sentinel` provides a convenient way of +creating and testing the identity of objects like this. + +In this example we monkey patch `method` to return +`sentinel.some_object`: + +.. doctest:: + + >>> real = ProductionClass() + >>> real.method = Mock(name="method") + >>> real.method.return_value = sentinel.some_object + >>> result = real.method() + >>> assert result is sentinel.some_object + >>> sentinel.some_object + sentinel.some_object + + diff --git a/python/mock-1.0.0/html/.doctrees/changelog.doctree b/python/mock-1.0.0/html/.doctrees/changelog.doctree new file mode 100644 index 000000000..635630302 Binary files /dev/null and b/python/mock-1.0.0/html/.doctrees/changelog.doctree differ diff --git a/python/mock-1.0.0/html/.doctrees/compare.doctree b/python/mock-1.0.0/html/.doctrees/compare.doctree new file mode 100644 index 000000000..2a961fce4 Binary files /dev/null and b/python/mock-1.0.0/html/.doctrees/compare.doctree differ diff --git a/python/mock-1.0.0/html/.doctrees/examples.doctree b/python/mock-1.0.0/html/.doctrees/examples.doctree new file mode 100644 index 000000000..40e4fded5 Binary files /dev/null and b/python/mock-1.0.0/html/.doctrees/examples.doctree differ diff --git a/python/mock-1.0.0/html/.doctrees/getting-started.doctree b/python/mock-1.0.0/html/.doctrees/getting-started.doctree new file mode 100644 index 000000000..ba82a8998 Binary files /dev/null and b/python/mock-1.0.0/html/.doctrees/getting-started.doctree differ diff --git a/python/mock-1.0.0/html/.doctrees/index.doctree b/python/mock-1.0.0/html/.doctrees/index.doctree new file mode 100644 index 000000000..4c53f11a5 Binary files /dev/null and b/python/mock-1.0.0/html/.doctrees/index.doctree differ diff --git a/python/mock-1.0.0/html/.doctrees/magicmock.doctree b/python/mock-1.0.0/html/.doctrees/magicmock.doctree new file mode 100644 index 000000000..d57214e98 Binary files /dev/null and b/python/mock-1.0.0/html/.doctrees/magicmock.doctree differ diff --git a/python/mock-1.0.0/html/.doctrees/mock.doctree b/python/mock-1.0.0/html/.doctrees/mock.doctree new file mode 100644 index 000000000..44dc3043c Binary files /dev/null and b/python/mock-1.0.0/html/.doctrees/mock.doctree differ diff --git a/python/mock-1.0.0/html/.doctrees/mocksignature.doctree b/python/mock-1.0.0/html/.doctrees/mocksignature.doctree new file mode 100644 index 000000000..58313c2cf Binary files /dev/null and b/python/mock-1.0.0/html/.doctrees/mocksignature.doctree differ diff --git a/python/mock-1.0.0/html/.doctrees/patch.doctree b/python/mock-1.0.0/html/.doctrees/patch.doctree new file mode 100644 index 000000000..100ef505d Binary files /dev/null and b/python/mock-1.0.0/html/.doctrees/patch.doctree differ diff --git a/python/mock-1.0.0/html/.doctrees/sentinel.doctree b/python/mock-1.0.0/html/.doctrees/sentinel.doctree new file mode 100644 index 000000000..e0312ed60 Binary files /dev/null and b/python/mock-1.0.0/html/.doctrees/sentinel.doctree differ diff --git a/python/mock-1.0.0/html/_sources/changelog.txt b/python/mock-1.0.0/html/_sources/changelog.txt new file mode 100644 index 000000000..a605be3d9 --- /dev/null +++ b/python/mock-1.0.0/html/_sources/changelog.txt @@ -0,0 +1,725 @@ +.. currentmodule:: mock + + +CHANGELOG +========= + +2012/10/07 Version 1.0.0 +------------------------ + +No changes since 1.0.0 beta 1. This version has feature parity with +`unittest.mock +`_ +in Python 3.3. + +Full list of changes since 0.8: + +* `mocksignature`, along with the `mocksignature` argument to `patch`, removed +* Support for deleting attributes (accessing deleted attributes will raise an + `AttributeError`) +* Added the `mock_open` helper function for mocking the builtin `open` +* `__class__` is assignable, so a mock can pass an `isinstance` check without + requiring a spec +* Addition of `PropertyMock`, for mocking properties +* `MagicMocks` made unorderable by default (in Python 3). The comparison + methods (other than equality and inequality) now return `NotImplemented` +* Propagate traceback info to support subclassing of `_patch` by other + libraries +* `create_autospec` works with attributes present in results of `dir` that + can't be fetched from the object's class. Contributed by Konstantine Rybnikov +* Any exceptions in an iterable `side_effect` will be raised instead of + returned +* In Python 3, `create_autospec` now supports keyword only arguments +* Added `patch.stopall` method to stop all active patches created by `start` +* BUGFIX: calling `MagicMock.reset_mock` wouldn't reset magic method mocks +* BUGFIX: calling `reset_mock` on a `MagicMock` created with autospec could + raise an exception +* BUGFIX: passing multiple spec arguments to patchers (`spec` , `spec_set` and + `autospec`) had unpredictable results, now it is an error +* BUGFIX: using `spec=True` *and* `create=True` as arguments to patchers could + result in using `DEFAULT` as the spec. Now it is an error instead +* BUGFIX: using `spec` or `autospec` arguments to patchers, along with + `spec_set=True` did not work correctly +* BUGFIX: using an object that evaluates to False as a spec could be ignored +* BUGFIX: a list as the `spec` argument to a patcher would always result in a + non-callable mock. Now if `__call__` is in the spec the mock is callable + + +2012/07/13 Version 1.0.0 beta 1 +-------------------------------- + +* Added `patch.stopall` method to stop all active patches created by `start` +* BUGFIX: calling `MagicMock.reset_mock` wouldn't reset magic method mocks +* BUGFIX: calling `reset_mock` on a `MagicMock` created with autospec could + raise an exception + + +2012/05/04 Version 1.0.0 alpha 2 +-------------------------------- + +* `PropertyMock` attributes are now standard `MagicMocks` +* `create_autospec` works with attributes present in results of `dir` that + can't be fetched from the object's class. Contributed by Konstantine Rybnikov +* Any exceptions in an iterable `side_effect` will be raised instead of + returned +* In Python 3, `create_autospec` now supports keyword only arguments + + +2012/03/25 Version 1.0.0 alpha 1 +-------------------------------- + +The standard library version! + +* `mocksignature`, along with the `mocksignature` argument to `patch`, removed +* Support for deleting attributes (accessing deleted attributes will raise an + `AttributeError`) +* Added the `mock_open` helper function for mocking the builtin `open` +* `__class__` is assignable, so a mock can pass an `isinstance` check without + requiring a spec +* Addition of `PropertyMock`, for mocking properties +* `MagicMocks` made unorderable by default (in Python 3). The comparison + methods (other than equality and inequality) now return `NotImplemented` +* Propagate traceback info to support subclassing of `_patch` by other + libraries +* BUGFIX: passing multiple spec arguments to patchers (`spec` , `spec_set` and + `autospec`) had unpredictable results, now it is an error +* BUGFIX: using `spec=True` *and* `create=True` as arguments to patchers could + result in using `DEFAULT` as the spec. Now it is an error instead +* BUGFIX: using `spec` or `autospec` arguments to patchers, along with + `spec_set=True` did not work correctly +* BUGFIX: using an object that evaluates to False as a spec could be ignored +* BUGFIX: a list as the `spec` argument to a patcher would always result in a + non-callable mock. Now if `__call__` is in the spec the mock is callable + + +2012/02/13 Version 0.8.0 +------------------------ + +The only changes since 0.8rc2 are: + +* Improved repr of :data:`sentinel` objects +* :data:`ANY` can be used for comparisons against :data:`call` objects +* The return value of `MagicMock.__iter__` method can be set to + any iterable and isn't required to be an iterator + +Full List of changes since 0.7: + +mock 0.8.0 is the last version that will support Python 2.4. + +* Addition of :attr:`~Mock.mock_calls` list for *all* calls (including magic + methods and chained calls) +* :func:`patch` and :func:`patch.object` now create a :class:`MagicMock` + instead of a :class:`Mock` by default +* The patchers (`patch`, `patch.object` and `patch.dict`), plus `Mock` and + `MagicMock`, take arbitrary keyword arguments for configuration +* New mock method :meth:`~Mock.configure_mock` for setting attributes and + return values / side effects on the mock and its attributes +* New mock assert methods :meth:`~Mock.assert_any_call` and + :meth:`~Mock.assert_has_calls` +* Implemented :ref:`auto-speccing` (recursive, lazy speccing of mocks with + mocked signatures for functions/methods), as the `autospec` argument to + `patch` +* Added the :func:`create_autospec` function for manually creating + 'auto-specced' mocks +* :func:`patch.multiple` for doing multiple patches in a single call, using + keyword arguments +* Setting :attr:`~Mock.side_effect` to an iterable will cause calls to the mock + to return the next value from the iterable +* New `new_callable` argument to `patch` and `patch.object` allowing you to + pass in a class or callable object (instead of `MagicMock`) that will be + called to replace the object being patched +* Addition of :class:`NonCallableMock` and :class:`NonCallableMagicMock`, mocks + without a `__call__` method +* Addition of :meth:`~Mock.mock_add_spec` method for adding (or changing) a + spec on an existing mock +* Protocol methods on :class:`MagicMock` are magic mocks, and are created + lazily on first lookup. This means the result of calling a protocol method is + a `MagicMock` instead of a `Mock` as it was previously +* Addition of :meth:`~Mock.attach_mock` method +* Added :data:`ANY` for ignoring arguments in :meth:`~Mock.assert_called_with` + calls +* Addition of :data:`call` helper object +* Improved repr for mocks +* Improved repr for :attr:`Mock.call_args` and entries in + :attr:`Mock.call_args_list`, :attr:`Mock.method_calls` and + :attr:`Mock.mock_calls` +* Improved repr for :data:`sentinel` objects +* `patch` lookup is done at use time not at decoration time +* In Python 2.6 or more recent, `dir` on a mock will report all the dynamically + created attributes (or the full list of attributes if there is a spec) as + well as all the mock methods and attributes. +* Module level :data:`FILTER_DIR` added to control whether `dir(mock)` filters + private attributes. `True` by default. +* `patch.TEST_PREFIX` for controlling how patchers recognise test methods when + used to decorate a class +* Support for using Java exceptions as a :attr:`~Mock.side_effect` on Jython +* `Mock` call lists (`call_args_list`, `method_calls` & `mock_calls`) are now + custom list objects that allow membership tests for "sub lists" and have + a nicer representation if you `str` or `print` them +* Mocks attached as attributes or return values to other mocks have calls + recorded in `method_calls` and `mock_calls` of the parent (unless a name is + already set on the child) +* Improved failure messages for `assert_called_with` and + `assert_called_once_with` +* The return value of the :class:`MagicMock` `__iter__` method can be set to + any iterable and isn't required to be an iterator +* Added the Mock API (`assert_called_with` etc) to functions created by + :func:`mocksignature` +* Tuples as well as lists can be used to specify allowed methods for `spec` & + `spec_set` arguments +* Calling `stop` on an unstarted patcher fails with a more meaningful error + message +* Renamed the internal classes `Sentinel` and `SentinelObject` to prevent abuse +* BUGFIX: an error creating a patch, with nested patch decorators, won't leave + patches in place +* BUGFIX: `__truediv__` and `__rtruediv__` not available as magic methods on + mocks in Python 3 +* BUGFIX: `assert_called_with` / `assert_called_once_with` can be used with + `self` as a keyword argument +* BUGFIX: when patching a class with an explicit spec / spec_set (not a + boolean) it applies "spec inheritance" to the return value of the created + mock (the "instance") +* BUGFIX: remove the `__unittest` marker causing traceback truncation +* Removal of deprecated `patch_object` +* Private attributes `_name`, `_methods`, '_children', `_wraps` and `_parent` + (etc) renamed to reduce likelihood of clash with user attributes. +* Added license file to the distribution + + +2012/01/10 Version 0.8.0 release candidate 2 +-------------------------------------------- + +* Removed the `configure` keyword argument to `create_autospec` and allow + arbitrary keyword arguments (for the `Mock` constructor) instead +* Fixed `ANY` equality with some types in `assert_called_with` calls +* Switched to a standard Sphinx theme (compatible with + `readthedocs.org `_) + + +2011/12/29 Version 0.8.0 release candidate 1 +-------------------------------------------- + +* `create_autospec` on the return value of a mocked class will use `__call__` + for the signature rather than `__init__` +* Performance improvement instantiating `Mock` and `MagicMock` +* Mocks used as magic methods have the same type as their parent instead of + being hardcoded to `MagicMock` + +Special thanks to Julian Berman for his help with diagnosing and improving +performance in this release. + + +2011/10/09 Version 0.8.0 beta 4 +------------------------------- + +* `patch` lookup is done at use time not at decoration time +* When attaching a Mock to another Mock as a magic method, calls are recorded + in mock_calls +* Addition of `attach_mock` method +* Renamed the internal classes `Sentinel` and `SentinelObject` to prevent abuse +* BUGFIX: various issues around circular references with mocks (setting a mock + return value to be itself etc) + + +2011/08/15 Version 0.8.0 beta 3 +------------------------------- + +* Mocks attached as attributes or return values to other mocks have calls + recorded in `method_calls` and `mock_calls` of the parent (unless a name is + already set on the child) +* Addition of `mock_add_spec` method for adding (or changing) a spec on an + existing mock +* Improved repr for `Mock.call_args` and entries in `Mock.call_args_list`, + `Mock.method_calls` and `Mock.mock_calls` +* Improved repr for mocks +* BUGFIX: minor fixes in the way `mock_calls` is worked out, + especially for "intermediate" mocks in a call chain + + +2011/08/05 Version 0.8.0 beta 2 +------------------------------- + +* Setting `side_effect` to an iterable will cause calls to the mock to return + the next value from the iterable +* Added `assert_any_call` method +* Moved `assert_has_calls` from call lists onto mocks +* BUGFIX: `call_args` and all members of `call_args_list` are two tuples of + `(args, kwargs)` again instead of three tuples of `(name, args, kwargs)` + + +2011/07/25 Version 0.8.0 beta 1 +------------------------------- + +* `patch.TEST_PREFIX` for controlling how patchers recognise test methods when + used to decorate a class +* `Mock` call lists (`call_args_list`, `method_calls` & `mock_calls`) are now + custom list objects that allow membership tests for "sub lists" and have + an `assert_has_calls` method for unordered call checks +* `callargs` changed to *always* be a three-tuple of `(name, args, kwargs)` +* Addition of `mock_calls` list for *all* calls (including magic methods and + chained calls) +* Extension of `call` object to support chained calls and `callargs` for better + comparisons with or without names. `call` object has a `call_list` method for + chained calls +* Added the public `instance` argument to `create_autospec` +* Support for using Java exceptions as a `side_effect` on Jython +* Improved failure messages for `assert_called_with` and + `assert_called_once_with` +* Tuples as well as lists can be used to specify allowed methods for `spec` & + `spec_set` arguments +* BUGFIX: Fixed bug in `patch.multiple` for argument passing when creating + mocks +* Added license file to the distribution + + +2011/07/16 Version 0.8.0 alpha 2 +-------------------------------- + +* `patch.multiple` for doing multiple patches in a single call, using keyword + arguments +* New `new_callable` argument to `patch` and `patch.object` allowing you to + pass in a class or callable object (instead of `MagicMock`) that will be + called to replace the object being patched +* Addition of `NonCallableMock` and `NonCallableMagicMock`, mocks without a + `__call__` method +* Mocks created by `patch` have a `MagicMock` as the `return_value` where a + class is being patched +* `create_autospec` can create non-callable mocks for non-callable objects. + `return_value` mocks of classes will be non-callable unless the class has + a `__call__` method +* `autospec` creates a `MagicMock` without a spec for properties and slot + descriptors, because we don't know the type of object they return +* Removed the "inherit" argument from `create_autospec` +* Calling `stop` on an unstarted patcher fails with a more meaningful error + message +* BUGFIX: an error creating a patch, with nested patch decorators, won't leave + patches in place +* BUGFIX: `__truediv__` and `__rtruediv__` not available as magic methods on + mocks in Python 3 +* BUGFIX: `assert_called_with` / `assert_called_once_with` can be used with + `self` as a keyword argument +* BUGFIX: autospec for functions / methods with an argument named self that + isn't the first argument no longer broken +* BUGFIX: when patching a class with an explicit spec / spec_set (not a + boolean) it applies "spec inheritance" to the return value of the created + mock (the "instance") +* BUGFIX: remove the `__unittest` marker causing traceback truncation + + +2011/06/14 Version 0.8.0 alpha 1 +-------------------------------- + +mock 0.8.0 is the last version that will support Python 2.4. + +* The patchers (`patch`, `patch.object` and `patch.dict`), plus `Mock` and + `MagicMock`, take arbitrary keyword arguments for configuration +* New mock method `configure_mock` for setting attributes and return values / + side effects on the mock and its attributes +* In Python 2.6 or more recent, `dir` on a mock will report all the dynamically + created attributes (or the full list of attributes if there is a spec) as + well as all the mock methods and attributes. +* Module level `FILTER_DIR` added to control whether `dir(mock)` filters + private attributes. `True` by default. Note that `vars(Mock())` can still be + used to get all instance attributes and `dir(type(Mock())` will still return + all the other attributes (irrespective of `FILTER_DIR`) +* `patch` and `patch.object` now create a `MagicMock` instead of a `Mock` by + default +* Added `ANY` for ignoring arguments in `assert_called_with` calls +* Addition of `call` helper object +* Protocol methods on `MagicMock` are magic mocks, and are created lazily on + first lookup. This means the result of calling a protocol method is a + MagicMock instead of a Mock as it was previously +* Added the Mock API (`assert_called_with` etc) to functions created by + `mocksignature` +* Private attributes `_name`, `_methods`, '_children', `_wraps` and `_parent` + (etc) renamed to reduce likelihood of clash with user attributes. +* Implemented auto-speccing (recursive, lazy speccing of mocks with mocked + signatures for functions/methods) + + Limitations: + + - Doesn't mock magic methods or attributes (it creates MagicMocks, so the + magic methods are *there*, they just don't have the signature mocked nor + are attributes followed) + - Doesn't mock function / method attributes + - Uses object traversal on the objects being mocked to determine types - so + properties etc may be triggered + - The return value of mocked classes (the 'instance') has the same call + signature as the class __init__ (as they share the same spec) + + You create auto-specced mocks by passing `autospec=True` to `patch`. + + Note that attributes that are None are special cased and mocked without a + spec (so any attribute / method can be used). This is because None is + typically used as a default value for attributes that may be of some other + type, and as we don't know what type that may be we allow all access. + + Note that the `autospec` option to `patch` obsoletes the `mocksignature` + option. + +* Added the `create_autospec` function for manually creating 'auto-specced' + mocks +* Removal of deprecated `patch_object` + + +2011/05/30 Version 0.7.2 +------------------------ + +* BUGFIX: instances of list subclasses can now be used as mock specs +* BUGFIX: MagicMock equality / inequality protocol methods changed to use the + default equality / inequality. This is done through a `side_effect` on + the mocks used for `__eq__` / `__ne__` + + +2011/05/06 Version 0.7.1 +------------------------ + +Package fixes contributed by Michael Fladischer. No code changes. + +* Include template in package +* Use isolated binaries for the tox tests +* Unset executable bit on docs +* Fix DOS line endings in getting-started.txt + + +2011/03/05 Version 0.7.0 +------------------------ + +No API changes since 0.7.0 rc1. Many documentation changes including a stylish +new `Sphinx theme `_. + +The full set of changes since 0.6.0 are: + +* Python 3 compatibility +* Ability to mock magic methods with `Mock` and addition of `MagicMock` + with pre-created magic methods +* Addition of `mocksignature` and `mocksignature` argument to `patch` and + `patch.object` +* Addition of `patch.dict` for changing dictionaries during a test +* Ability to use `patch`, `patch.object` and `patch.dict` as class decorators +* Renamed ``patch_object`` to `patch.object` (``patch_object`` is + deprecated) +* Addition of soft comparisons: `call_args`, `call_args_list` and `method_calls` + now return tuple-like objects which compare equal even when empty args + or kwargs are skipped +* patchers (`patch`, `patch.object` and `patch.dict`) have start and stop + methods +* Addition of `assert_called_once_with` method +* Mocks can now be named (`name` argument to constructor) and the name is used + in the repr +* repr of a mock with a spec includes the class name of the spec +* `assert_called_with` works with `python -OO` +* New `spec_set` keyword argument to `Mock` and `patch`. If used, + attempting to *set* an attribute on a mock not on the spec will raise an + `AttributeError` +* Mocks created with a spec can now pass `isinstance` tests (`__class__` + returns the type of the spec) +* Added docstrings to all objects +* Improved failure message for `Mock.assert_called_with` when the mock + has not been called at all +* Decorated functions / methods have their docstring and `__module__` + preserved on Python 2.4. +* BUGFIX: `mock.patch` now works correctly with certain types of objects that + proxy attribute access, like the django settings object +* BUGFIX: mocks are now copyable (thanks to Ned Batchelder for reporting and + diagnosing this) +* BUGFIX: `spec=True` works with old style classes +* BUGFIX: ``help(mock)`` works now (on the module). Can no longer use ``__bases__`` + as a valid sentinel name (thanks to Stephen Emslie for reporting and + diagnosing this) +* BUGFIX: ``side_effect`` now works with ``BaseException`` exceptions like + ``KeyboardInterrupt`` +* BUGFIX: `reset_mock` caused infinite recursion when a mock is set as its own + return value +* BUGFIX: patching the same object twice now restores the patches correctly +* with statement tests now skipped on Python 2.4 +* Tests require unittest2 (or unittest2-py3k) to run +* Tested with `tox `_ on Python 2.4 - 3.2, + jython and pypy (excluding 3.0) +* Added 'build_sphinx' command to setup.py (requires setuptools or distribute) + Thanks to Florian Bauer +* Switched from subversion to mercurial for source code control +* `Konrad Delong `_ added as co-maintainer + + +2011/02/16 Version 0.7.0 RC 1 +----------------------------- + +Changes since beta 4: + +* Tested with jython, pypy and Python 3.2 and 3.1 +* Decorated functions / methods have their docstring and `__module__` + preserved on Python 2.4 +* BUGFIX: `mock.patch` now works correctly with certain types of objects that + proxy attribute access, like the django settings object +* BUGFIX: `reset_mock` caused infinite recursion when a mock is set as its own + return value + + +2010/11/12 Version 0.7.0 beta 4 +------------------------------- + +* patchers (`patch`, `patch.object` and `patch.dict`) have start and stop + methods +* Addition of `assert_called_once_with` method +* repr of a mock with a spec includes the class name of the spec +* `assert_called_with` works with `python -OO` +* New `spec_set` keyword argument to `Mock` and `patch`. If used, + attempting to *set* an attribute on a mock not on the spec will raise an + `AttributeError` +* Attributes and return value of a `MagicMock` are `MagicMock` objects +* Attempting to set an unsupported magic method now raises an `AttributeError` +* `patch.dict` works as a class decorator +* Switched from subversion to mercurial for source code control +* BUGFIX: mocks are now copyable (thanks to Ned Batchelder for reporting and + diagnosing this) +* BUGFIX: `spec=True` works with old style classes +* BUGFIX: `mocksignature=True` can now patch instance methods via + `patch.object` + + +2010/09/18 Version 0.7.0 beta 3 +------------------------------- + +* Using spec with :class:`MagicMock` only pre-creates magic methods in the spec +* Setting a magic method on a mock with a ``spec`` can only be done if the + spec has that method +* Mocks can now be named (`name` argument to constructor) and the name is used + in the repr +* `mocksignature` can now be used with classes (signature based on `__init__`) + and callable objects (signature based on `__call__`) +* Mocks created with a spec can now pass `isinstance` tests (`__class__` + returns the type of the spec) +* Default numeric value for MagicMock is 1 rather than zero (because the + MagicMock bool defaults to True and 0 is False) +* Improved failure message for :meth:`~Mock.assert_called_with` when the mock + has not been called at all +* Adding the following to the set of supported magic methods: + + - ``__getformat__`` and ``__setformat__`` + - pickle methods + - ``__trunc__``, ``__ceil__`` and ``__floor__`` + - ``__sizeof__`` + +* Added 'build_sphinx' command to setup.py (requires setuptools or distribute) + Thanks to Florian Bauer +* with statement tests now skipped on Python 2.4 +* Tests require unittest2 to run on Python 2.7 +* Improved several docstrings and documentation + + +2010/06/23 Version 0.7.0 beta 2 +------------------------------- + +* :func:`patch.dict` works as a context manager as well as a decorator +* ``patch.dict`` takes a string to specify dictionary as well as a dictionary + object. If a string is supplied the name specified is imported +* BUGFIX: ``patch.dict`` restores dictionary even when an exception is raised + + +2010/06/22 Version 0.7.0 beta 1 +------------------------------- + +* Addition of :func:`mocksignature` +* Ability to mock magic methods +* Ability to use ``patch`` and ``patch.object`` as class decorators +* Renamed ``patch_object`` to :func:`patch.object` (``patch_object`` is + deprecated) +* Addition of :class:`MagicMock` class with all magic methods pre-created for you +* Python 3 compatibility (tested with 3.2 but should work with 3.0 & 3.1 as + well) +* Addition of :func:`patch.dict` for changing dictionaries during a test +* Addition of ``mocksignature`` argument to ``patch`` and ``patch.object`` +* ``help(mock)`` works now (on the module). Can no longer use ``__bases__`` + as a valid sentinel name (thanks to Stephen Emslie for reporting and + diagnosing this) +* Addition of soft comparisons: `call_args`, `call_args_list` and `method_calls` + now return tuple-like objects which compare equal even when empty args + or kwargs are skipped +* Added docstrings. +* BUGFIX: ``side_effect`` now works with ``BaseException`` exceptions like + ``KeyboardInterrupt`` +* BUGFIX: patching the same object twice now restores the patches correctly +* The tests now require `unittest2 `_ + to run +* `Konrad Delong `_ added as co-maintainer + + +2009/08/22 Version 0.6.0 +------------------------ + +* New test layout compatible with test discovery +* Descriptors (static methods / class methods etc) can now be patched and + restored correctly +* Mocks can raise exceptions when called by setting ``side_effect`` to an + exception class or instance +* Mocks that wrap objects will not pass on calls to the underlying object if + an explicit return_value is set + + +2009/04/17 Version 0.5.0 +------------------------ + +* Made DEFAULT part of the public api. +* Documentation built with Sphinx. +* ``side_effect`` is now called with the same arguments as the mock is called with and + if returns a non-DEFAULT value that is automatically set as the ``mock.return_value``. +* ``wraps`` keyword argument used for wrapping objects (and passing calls through to the wrapped object). +* ``Mock.reset`` renamed to ``Mock.reset_mock``, as reset is a common API name. +* ``patch`` / ``patch_object`` are now context managers and can be used with ``with``. +* A new 'create' keyword argument to patch and patch_object that allows them to patch + (and unpatch) attributes that don't exist. (Potentially unsafe to use - it can allow + you to have tests that pass when they are testing an API that doesn't exist - use at + your own risk!) +* The methods keyword argument to Mock has been removed and merged with spec. The spec + argument can now be a list of methods or an object to take the spec from. +* Nested patches may now be applied in a different order (created mocks passed + in the opposite order). This is actually a bugfix. +* patch and patch_object now take a spec keyword argument. If spec is + passed in as 'True' then the Mock created will take the object it is replacing + as its spec object. If the object being replaced is a class, then the return + value for the mock will also use the class as a spec. +* A Mock created without a spec will not attempt to mock any magic methods / attributes + (they will raise an ``AttributeError`` instead). + + +2008/10/12 Version 0.4.0 +------------------------ + +* Default return value is now a new mock rather than None +* return_value added as a keyword argument to the constructor +* New method 'assert_called_with' +* Added 'side_effect' attribute / keyword argument called when mock is called +* patch decorator split into two decorators: + + - ``patch_object`` which takes an object and an attribute name to patch + (plus optionally a value to patch with which defaults to a mock object) + - ``patch`` which takes a string specifying a target to patch; in the form + 'package.module.Class.attribute'. (plus optionally a value to + patch with which defaults to a mock object) + +* Can now patch objects with ``None`` +* Change to patch for nose compatibility with error reporting in wrapped functions +* Reset no longer clears children / return value etc - it just resets + call count and call args. It also calls reset on all children (and + the return value if it is a mock). + +Thanks to Konrad Delong, Kevin Dangoor and others for patches and suggestions. + + +2007/12/03 Version 0.3.1 +------------------------- + +``patch`` maintains the name of decorated functions for compatibility with nose +test autodiscovery. + +Tests decorated with ``patch`` that use the two argument form (implicit mock +creation) will receive the mock(s) passed in as extra arguments. + +Thanks to Kevin Dangoor for these changes. + + +2007/11/30 Version 0.3.0 +------------------------- + +Removed ``patch_module``. ``patch`` can now take a string as the first +argument for patching modules. + +The third argument to ``patch`` is optional - a mock will be created by +default if it is not passed in. + + +2007/11/21 Version 0.2.1 +------------------------- + +Bug fix, allows reuse of functions decorated with ``patch`` and ``patch_module``. + + +2007/11/20 Version 0.2.0 +------------------------- + +Added ``spec`` keyword argument for creating ``Mock`` objects from a +specification object. + +Added ``patch`` and ``patch_module`` monkey patching decorators. + +Added ``sentinel`` for convenient access to unique objects. + +Distribution includes unit tests. + + +2007/11/19 Version 0.1.0 +------------------------- + +Initial release. + + +TODO and Limitations +==================== + +Contributions, bug reports and comments welcomed! + +Feature requests and bug reports are handled on the issue tracker: + + * `mock issue tracker `_ + +`wraps` is not integrated with magic methods. + +`patch` could auto-do the patching in the constructor and unpatch in the +destructor. This would be useful in itself, but violates TOOWTDI and would be +unsafe for IronPython & PyPy (non-deterministic calling of destructors). +Destructors aren't called in CPython where there are cycles, but a weak +reference with a callback can be used to get round this. + +`Mock` has several attributes. This makes it unsuitable for mocking objects +that use these attribute names. A way round this would be to provide methods +that *hide* these attributes when needed. In 0.8 many, but not all, of these +attributes are renamed to gain a `_mock` prefix, making it less likely that +they will clash. Any outstanding attributes that haven't been modified with +the prefix should be changed. + +If a patch is started using `patch.start` and then not stopped correctly then +the unpatching is not done. Using weak references it would be possible to +detect and fix this when the patch object itself is garbage collected. This +would be tricky to get right though. + +When a `Mock` is created by `patch`, arbitrary keywords can be used to set +attributes. If `patch` is created with a `spec`, and is replacing a class, then +a `return_value` mock is created. The keyword arguments are not applied to the +child mock, but could be. + +When mocking a class with `patch`, passing in `spec=True` or `autospec=True`, +the mock class has an instance created from the same spec. Should this be the +default behaviour for mocks anyway (mock return values inheriting the spec +from their parent), or should it be controlled by an additional keyword +argument (`inherit`) to the Mock constructor? `create_autospec` does this, so +an additional keyword argument to Mock is probably unnecessary. + +The `mocksignature` argument to `patch` with a non `Mock` passed into +`new_callable` will *probably* cause an error. Should it just be invalid? + +Note that `NonCallableMock` and `NonCallableMagicMock` still have the unused +(and unusable) attributes: `return_value`, `side_effect`, `call_count`, +`call_args` and `call_args_list`. These could be removed or raise errors on +getting / setting. They also have the `assert_called_with` and +`assert_called_once_with` methods. Removing these would be pointless as +fetching them would create a mock (attribute) that could be called without +error. + +Some outstanding technical debt. The way autospeccing mocks function +signatures was copied and modified from `mocksignature`. This could all be +refactored into one set of functions instead of two. The way we tell if +patchers are started and if a patcher is being used for a `patch.multiple` +call are both horrible. There are now a host of helper functions that should +be rationalised. (Probably time to split mock into a package instead of a +module.) + +Passing arbitrary keyword arguments to `create_autospec`, or `patch` with +`autospec`, when mocking a *function* works fine. However, the arbitrary +attributes are set on the created mock - but `create_autospec` returns a +real function (which doesn't have those attributes). However, what is the use +case for using autospec to create functions with attributes that don't exist +on the original? + +`mocksignature`, plus the `call_args_list` and `method_calls` attributes of +`Mock` could all be deprecated. diff --git a/python/mock-1.0.0/html/_sources/compare.txt b/python/mock-1.0.0/html/_sources/compare.txt new file mode 100644 index 000000000..41555308e --- /dev/null +++ b/python/mock-1.0.0/html/_sources/compare.txt @@ -0,0 +1,628 @@ +========================= + Mock Library Comparison +========================= + + +.. testsetup:: + + def assertEqual(a, b): + assert a == b, ("%r != %r" % (a, b)) + + def assertRaises(Exc, func): + try: + func() + except Exc: + return + assert False, ("%s not raised" % Exc) + + sys.modules['somemodule'] = somemodule = mock.Mock(name='somemodule') + class SomeException(Exception): + some_method = method1 = method2 = None + some_other_object = SomeObject = SomeException + + +A side-by-side comparison of how to accomplish some basic tasks with mock and +some other popular Python mocking libraries and frameworks. + +These are: + +* `flexmock `_ +* `mox `_ +* `Mocker `_ +* `dingus `_ +* `fudge `_ + +Popular python mocking frameworks not yet represented here include +`MiniMock `_. + +`pMock `_ (last release 2004 and doesn't import +in recent versions of Python) and +`python-mock `_ (last release 2005) are +intentionally omitted. + +.. note:: + + A more up to date, and tested for all mock libraries (only the mock + examples on this page can be executed as doctests) version of this + comparison is maintained by Gary Bernhardt: + + * `Python Mock Library Comparison + `_ + +This comparison is by no means complete, and also may not be fully idiomatic +for all the libraries represented. *Please* contribute corrections, missing +comparisons, or comparisons for additional libraries to the `mock issue +tracker `_. + +This comparison page was originally created by the `Mox project +`_ and then extended for +`flexmock and mock `_ by +Herman Sheremetyev. Dingus examples written by `Gary Bernhadt +`_. fudge examples +provided by `Kumar McMillan `_. + +.. note:: + + The examples tasks here were originally created by Mox which is a mocking + *framework* rather than a library like mock. The tasks shown naturally + exemplify tasks that frameworks are good at and not the ones they make + harder. In particular you can take a `Mock` or `MagicMock` object and use + it in any way you want with no up-front configuration. The same is also + true for Dingus. + + The examples for mock here assume version 0.7.0. + + +Simple fake object +~~~~~~~~~~~~~~~~~~ + +.. doctest:: + + >>> # mock + >>> my_mock = mock.Mock() + >>> my_mock.some_method.return_value = "calculated value" + >>> my_mock.some_attribute = "value" + >>> assertEqual("calculated value", my_mock.some_method()) + >>> assertEqual("value", my_mock.some_attribute) + +:: + + # Flexmock + mock = flexmock(some_method=lambda: "calculated value", some_attribute="value") + assertEqual("calculated value", mock.some_method()) + assertEqual("value", mock.some_attribute) + + # Mox + mock = mox.MockAnything() + mock.some_method().AndReturn("calculated value") + mock.some_attribute = "value" + mox.Replay(mock) + assertEqual("calculated value", mock.some_method()) + assertEqual("value", mock.some_attribute) + + # Mocker + mock = mocker.mock() + mock.some_method() + mocker.result("calculated value") + mocker.replay() + mock.some_attribute = "value" + assertEqual("calculated value", mock.some_method()) + assertEqual("value", mock.some_attribute) + +:: + + >>> # Dingus + >>> my_dingus = dingus.Dingus(some_attribute="value", + ... some_method__returns="calculated value") + >>> assertEqual("calculated value", my_dingus.some_method()) + >>> assertEqual("value", my_dingus.some_attribute) + +:: + + >>> # fudge + >>> my_fake = (fudge.Fake() + ... .provides('some_method') + ... .returns("calculated value") + ... .has_attr(some_attribute="value")) + ... + >>> assertEqual("calculated value", my_fake.some_method()) + >>> assertEqual("value", my_fake.some_attribute) + + +Simple mock +~~~~~~~~~~~ + +.. doctest:: + + >>> # mock + >>> my_mock = mock.Mock() + >>> my_mock.some_method.return_value = "value" + >>> assertEqual("value", my_mock.some_method()) + >>> my_mock.some_method.assert_called_once_with() + +:: + + # Flexmock + mock = flexmock() + mock.should_receive("some_method").and_return("value").once + assertEqual("value", mock.some_method()) + + # Mox + mock = mox.MockAnything() + mock.some_method().AndReturn("value") + mox.Replay(mock) + assertEqual("value", mock.some_method()) + mox.Verify(mock) + + # Mocker + mock = mocker.mock() + mock.some_method() + mocker.result("value") + mocker.replay() + assertEqual("value", mock.some_method()) + mocker.verify() + +:: + + >>> # Dingus + >>> my_dingus = dingus.Dingus(some_method__returns="value") + >>> assertEqual("value", my_dingus.some_method()) + >>> assert my_dingus.some_method.calls().once() + +:: + + >>> # fudge + >>> @fudge.test + ... def test(): + ... my_fake = (fudge.Fake() + ... .expects('some_method') + ... .returns("value") + ... .times_called(1)) + ... + >>> test() + Traceback (most recent call last): + ... + AssertionError: fake:my_fake.some_method() was not called + + +Creating partial mocks +~~~~~~~~~~~~~~~~~~~~~~ + +.. doctest:: + + >>> # mock + >>> SomeObject.some_method = mock.Mock(return_value='value') + >>> assertEqual("value", SomeObject.some_method()) + +:: + + # Flexmock + flexmock(SomeObject).should_receive("some_method").and_return('value') + assertEqual("value", mock.some_method()) + + # Mox + mock = mox.MockObject(SomeObject) + mock.some_method().AndReturn("value") + mox.Replay(mock) + assertEqual("value", mock.some_method()) + mox.Verify(mock) + + # Mocker + mock = mocker.mock(SomeObject) + mock.Get() + mocker.result("value") + mocker.replay() + assertEqual("value", mock.some_method()) + mocker.verify() + +:: + + >>> # Dingus + >>> object = SomeObject + >>> object.some_method = dingus.Dingus(return_value="value") + >>> assertEqual("value", object.some_method()) + +:: + + >>> # fudge + >>> fake = fudge.Fake().is_callable().returns("") + >>> with fudge.patched_context(SomeObject, 'some_method', fake): + ... s = SomeObject() + ... assertEqual("", s.some_method()) + ... + + +Ensure calls are made in specific order +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doctest:: + + >>> # mock + >>> my_mock = mock.Mock(spec=SomeObject) + >>> my_mock.method1() + + >>> my_mock.method2() + + >>> assertEqual(my_mock.mock_calls, [call.method1(), call.method2()]) + +:: + + # Flexmock + mock = flexmock(SomeObject) + mock.should_receive('method1').once.ordered.and_return('first thing') + mock.should_receive('method2').once.ordered.and_return('second thing') + + # Mox + mock = mox.MockObject(SomeObject) + mock.method1().AndReturn('first thing') + mock.method2().AndReturn('second thing') + mox.Replay(mock) + mox.Verify(mock) + + # Mocker + mock = mocker.mock() + with mocker.order(): + mock.method1() + mocker.result('first thing') + mock.method2() + mocker.result('second thing') + mocker.replay() + mocker.verify() + +:: + + >>> # Dingus + >>> my_dingus = dingus.Dingus() + >>> my_dingus.method1() + + >>> my_dingus.method2() + + >>> assertEqual(['method1', 'method2'], [call.name for call in my_dingus.calls]) + +:: + + >>> # fudge + >>> @fudge.test + ... def test(): + ... my_fake = (fudge.Fake() + ... .remember_order() + ... .expects('method1') + ... .expects('method2')) + ... my_fake.method2() + ... my_fake.method1() + ... + >>> test() + Traceback (most recent call last): + ... + AssertionError: Call #1 was fake:my_fake.method2(); Expected: #1 fake:my_fake.method1(), #2 fake:my_fake.method2(), end + + +Raising exceptions +~~~~~~~~~~~~~~~~~~ + +.. doctest:: + + >>> # mock + >>> my_mock = mock.Mock() + >>> my_mock.some_method.side_effect = SomeException("message") + >>> assertRaises(SomeException, my_mock.some_method) + +:: + + # Flexmock + mock = flexmock() + mock.should_receive("some_method").and_raise(SomeException("message")) + assertRaises(SomeException, mock.some_method) + + # Mox + mock = mox.MockAnything() + mock.some_method().AndRaise(SomeException("message")) + mox.Replay(mock) + assertRaises(SomeException, mock.some_method) + mox.Verify(mock) + + # Mocker + mock = mocker.mock() + mock.some_method() + mocker.throw(SomeException("message")) + mocker.replay() + assertRaises(SomeException, mock.some_method) + mocker.verify() + +:: + + >>> # Dingus + >>> my_dingus = dingus.Dingus() + >>> my_dingus.some_method = dingus.exception_raiser(SomeException) + >>> assertRaises(SomeException, my_dingus.some_method) + +:: + + >>> # fudge + >>> my_fake = (fudge.Fake() + ... .is_callable() + ... .raises(SomeException("message"))) + ... + >>> my_fake() + Traceback (most recent call last): + ... + SomeException: message + + +Override new instances of a class +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doctest:: + + >>> # mock + >>> with mock.patch('somemodule.Someclass') as MockClass: + ... MockClass.return_value = some_other_object + ... assertEqual(some_other_object, somemodule.Someclass()) + ... + + +:: + + # Flexmock + flexmock(some_module.SomeClass, new_instances=some_other_object) + assertEqual(some_other_object, some_module.SomeClass()) + + # Mox + # (you will probably have mox.Mox() available as self.mox in a real test) + mox.Mox().StubOutWithMock(some_module, 'SomeClass', use_mock_anything=True) + some_module.SomeClass().AndReturn(some_other_object) + mox.ReplayAll() + assertEqual(some_other_object, some_module.SomeClass()) + + # Mocker + instance = mocker.mock() + klass = mocker.replace(SomeClass, spec=None) + klass('expected', 'args') + mocker.result(instance) + +:: + + >>> # Dingus + >>> MockClass = dingus.Dingus(return_value=some_other_object) + >>> with dingus.patch('somemodule.SomeClass', MockClass): + ... assertEqual(some_other_object, somemodule.SomeClass()) + ... + +:: + + >>> # fudge + >>> @fudge.patch('somemodule.SomeClass') + ... def test(FakeClass): + ... FakeClass.is_callable().returns(some_other_object) + ... assertEqual(some_other_object, somemodule.SomeClass()) + ... + >>> test() + + +Call the same method multiple times +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + You don't need to do *any* configuration to call `mock.Mock()` methods + multiple times. Attributes like `call_count`, `call_args_list` and + `method_calls` provide various different ways of making assertions about + how the mock was used. + +.. doctest:: + + >>> # mock + >>> my_mock = mock.Mock() + >>> my_mock.some_method() + + >>> my_mock.some_method() + + >>> assert my_mock.some_method.call_count >= 2 + +:: + + # Flexmock # (verifies that the method gets called at least twice) + flexmock(some_object).should_receive('some_method').at_least.twice + + # Mox + # (does not support variable number of calls, so you need to create a new entry for each explicit call) + mock = mox.MockObject(some_object) + mock.some_method(mox.IgnoreArg(), mox.IgnoreArg()) + mock.some_method(mox.IgnoreArg(), mox.IgnoreArg()) + mox.Replay(mock) + mox.Verify(mock) + + # Mocker + # (TODO) + +:: + + >>> # Dingus + >>> my_dingus = dingus.Dingus() + >>> my_dingus.some_method() + + >>> my_dingus.some_method() + + >>> assert len(my_dingus.calls('some_method')) == 2 + +:: + + >>> # fudge + >>> @fudge.test + ... def test(): + ... my_fake = fudge.Fake().expects('some_method').times_called(2) + ... my_fake.some_method() + ... + >>> test() + Traceback (most recent call last): + ... + AssertionError: fake:my_fake.some_method() was called 1 time(s). Expected 2. + + +Mock chained methods +~~~~~~~~~~~~~~~~~~~~ + +.. doctest:: + + >>> # mock + >>> my_mock = mock.Mock() + >>> method3 = my_mock.method1.return_value.method2.return_value.method3 + >>> method3.return_value = 'some value' + >>> assertEqual('some value', my_mock.method1().method2().method3(1, 2)) + >>> method3.assert_called_once_with(1, 2) + +:: + + # Flexmock + # (intermediate method calls are automatically assigned to temporary fake objects + # and can be called with any arguments) + flexmock(some_object).should_receive( + 'method1.method2.method3' + ).with_args(arg1, arg2).and_return('some value') + assertEqual('some_value', some_object.method1().method2().method3(arg1, arg2)) + +:: + + # Mox + mock = mox.MockObject(some_object) + mock2 = mox.MockAnything() + mock3 = mox.MockAnything() + mock.method1().AndReturn(mock1) + mock2.method2().AndReturn(mock2) + mock3.method3(arg1, arg2).AndReturn('some_value') + self.mox.ReplayAll() + assertEqual("some_value", some_object.method1().method2().method3(arg1, arg2)) + self.mox.VerifyAll() + + # Mocker + # (TODO) + +:: + + >>> # Dingus + >>> my_dingus = dingus.Dingus() + >>> method3 = my_dingus.method1.return_value.method2.return_value.method3 + >>> method3.return_value = 'some value' + >>> assertEqual('some value', my_dingus.method1().method2().method3(1, 2)) + >>> assert method3.calls('()', 1, 2).once() + +:: + + >>> # fudge + >>> @fudge.test + ... def test(): + ... my_fake = fudge.Fake() + ... (my_fake + ... .expects('method1') + ... .returns_fake() + ... .expects('method2') + ... .returns_fake() + ... .expects('method3') + ... .with_args(1, 2) + ... .returns('some value')) + ... assertEqual('some value', my_fake.method1().method2().method3(1, 2)) + ... + >>> test() + + +Mocking a context manager +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Examples for mock, Dingus and fudge only (so far): + +.. doctest:: + + >>> # mock + >>> my_mock = mock.MagicMock() + >>> with my_mock: + ... pass + ... + >>> my_mock.__enter__.assert_called_with() + >>> my_mock.__exit__.assert_called_with(None, None, None) + +:: + + + >>> # Dingus (nothing special here; all dinguses are "magic mocks") + >>> my_dingus = dingus.Dingus() + >>> with my_dingus: + ... pass + ... + >>> assert my_dingus.__enter__.calls() + >>> assert my_dingus.__exit__.calls('()', None, None, None) + +:: + + >>> # fudge + >>> my_fake = fudge.Fake().provides('__enter__').provides('__exit__') + >>> with my_fake: + ... pass + ... + + +Mocking the builtin open used as a context manager +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Example for mock only (so far): + +.. doctest:: + + >>> # mock + >>> my_mock = mock.MagicMock() + >>> with mock.patch('__builtin__.open', my_mock): + ... manager = my_mock.return_value.__enter__.return_value + ... manager.read.return_value = 'some data' + ... with open('foo') as h: + ... data = h.read() + ... + >>> data + 'some data' + >>> my_mock.assert_called_once_with('foo') + +*or*: + +.. doctest:: + + >>> # mock + >>> with mock.patch('__builtin__.open') as my_mock: + ... my_mock.return_value.__enter__ = lambda s: s + ... my_mock.return_value.__exit__ = mock.Mock() + ... my_mock.return_value.read.return_value = 'some data' + ... with open('foo') as h: + ... data = h.read() + ... + >>> data + 'some data' + >>> my_mock.assert_called_once_with('foo') + +:: + + >>> # Dingus + >>> my_dingus = dingus.Dingus() + >>> with dingus.patch('__builtin__.open', my_dingus): + ... file_ = open.return_value.__enter__.return_value + ... file_.read.return_value = 'some data' + ... with open('foo') as h: + ... data = f.read() + ... + >>> data + 'some data' + >>> assert my_dingus.calls('()', 'foo').once() + +:: + + >>> # fudge + >>> from contextlib import contextmanager + >>> from StringIO import StringIO + >>> @contextmanager + ... def fake_file(filename): + ... yield StringIO('sekrets') + ... + >>> with fudge.patch('__builtin__.open') as fake_open: + ... fake_open.is_callable().calls(fake_file) + ... with open('/etc/password') as f: + ... data = f.read() + ... + fake:__builtin__.open + >>> data + 'sekrets' \ No newline at end of file diff --git a/python/mock-1.0.0/html/_sources/examples.txt b/python/mock-1.0.0/html/_sources/examples.txt new file mode 100644 index 000000000..ecb994b15 --- /dev/null +++ b/python/mock-1.0.0/html/_sources/examples.txt @@ -0,0 +1,1063 @@ +.. _further-examples: + +================== + Further Examples +================== + +.. currentmodule:: mock + +.. testsetup:: + + from datetime import date + + BackendProvider = Mock() + sys.modules['mymodule'] = mymodule = Mock(name='mymodule') + + def grob(val): + "First frob and then clear val" + mymodule.frob(val) + val.clear() + + mymodule.frob = lambda val: val + mymodule.grob = grob + mymodule.date = date + + class TestCase(unittest2.TestCase): + def run(self): + result = unittest2.TestResult() + out = unittest2.TestCase.run(self, result) + assert result.wasSuccessful() + + from mock import inPy3k + + + +For comprehensive examples, see the unit tests included in the full source +distribution. + +Here are some more examples for some slightly more advanced scenarios than in +the :ref:`getting started ` guide. + + +Mocking chained calls +===================== + +Mocking chained calls is actually straightforward with mock once you +understand the :attr:`~Mock.return_value` attribute. When a mock is called for +the first time, or you fetch its `return_value` before it has been called, a +new `Mock` is created. + +This means that you can see how the object returned from a call to a mocked +object has been used by interrogating the `return_value` mock: + +.. doctest:: + + >>> mock = Mock() + >>> mock().foo(a=2, b=3) + + >>> mock.return_value.foo.assert_called_with(a=2, b=3) + +From here it is a simple step to configure and then make assertions about +chained calls. Of course another alternative is writing your code in a more +testable way in the first place... + +So, suppose we have some code that looks a little bit like this: + +.. doctest:: + + >>> class Something(object): + ... def __init__(self): + ... self.backend = BackendProvider() + ... def method(self): + ... response = self.backend.get_endpoint('foobar').create_call('spam', 'eggs').start_call() + ... # more code + +Assuming that `BackendProvider` is already well tested, how do we test +`method()`? Specifically, we want to test that the code section `# more +code` uses the response object in the correct way. + +As this chain of calls is made from an instance attribute we can monkey patch +the `backend` attribute on a `Something` instance. In this particular case +we are only interested in the return value from the final call to +`start_call` so we don't have much configuration to do. Let's assume the +object it returns is 'file-like', so we'll ensure that our response object +uses the builtin `file` as its `spec`. + +To do this we create a mock instance as our mock backend and create a mock +response object for it. To set the response as the return value for that final +`start_call` we could do this: + + `mock_backend.get_endpoint.return_value.create_call.return_value.start_call.return_value = mock_response`. + +We can do that in a slightly nicer way using the :meth:`~Mock.configure_mock` +method to directly set the return value for us: + +.. doctest:: + + >>> something = Something() + >>> mock_response = Mock(spec=file) + >>> mock_backend = Mock() + >>> config = {'get_endpoint.return_value.create_call.return_value.start_call.return_value': mock_response} + >>> mock_backend.configure_mock(**config) + +With these we monkey patch the "mock backend" in place and can make the real +call: + +.. doctest:: + + >>> something.backend = mock_backend + >>> something.method() + +Using :attr:`~Mock.mock_calls` we can check the chained call with a single +assert. A chained call is several calls in one line of code, so there will be +several entries in `mock_calls`. We can use :meth:`call.call_list` to create +this list of calls for us: + +.. doctest:: + + >>> chained = call.get_endpoint('foobar').create_call('spam', 'eggs').start_call() + >>> call_list = chained.call_list() + >>> assert mock_backend.mock_calls == call_list + + +Partial mocking +=============== + +In some tests I wanted to mock out a call to `datetime.date.today() +`_ to return +a known date, but I didn't want to prevent the code under test from +creating new date objects. Unfortunately `datetime.date` is written in C, and +so I couldn't just monkey-patch out the static `date.today` method. + +I found a simple way of doing this that involved effectively wrapping the date +class with a mock, but passing through calls to the constructor to the real +class (and returning real instances). + +The :func:`patch decorator ` is used here to +mock out the `date` class in the module under test. The :attr:`side_effect` +attribute on the mock date class is then set to a lambda function that returns +a real date. When the mock date class is called a real date will be +constructed and returned by `side_effect`. + +.. doctest:: + + >>> from datetime import date + >>> with patch('mymodule.date') as mock_date: + ... mock_date.today.return_value = date(2010, 10, 8) + ... mock_date.side_effect = lambda *args, **kw: date(*args, **kw) + ... + ... assert mymodule.date.today() == date(2010, 10, 8) + ... assert mymodule.date(2009, 6, 8) == date(2009, 6, 8) + ... + +Note that we don't patch `datetime.date` globally, we patch `date` in the +module that *uses* it. See :ref:`where to patch `. + +When `date.today()` is called a known date is returned, but calls to the +`date(...)` constructor still return normal dates. Without this you can find +yourself having to calculate an expected result using exactly the same +algorithm as the code under test, which is a classic testing anti-pattern. + +Calls to the date constructor are recorded in the `mock_date` attributes +(`call_count` and friends) which may also be useful for your tests. + +An alternative way of dealing with mocking dates, or other builtin classes, +is discussed in `this blog entry +`_. + + +Mocking a Generator Method +========================== + +A Python generator is a function or method that uses the `yield statement +`_ to +return a series of values when iterated over [#]_. + +A generator method / function is called to return the generator object. It is +the generator object that is then iterated over. The protocol method for +iteration is `__iter__ +`_, so we can +mock this using a `MagicMock`. + +Here's an example class with an "iter" method implemented as a generator: + +.. doctest:: + + >>> class Foo(object): + ... def iter(self): + ... for i in [1, 2, 3]: + ... yield i + ... + >>> foo = Foo() + >>> list(foo.iter()) + [1, 2, 3] + + +How would we mock this class, and in particular its "iter" method? + +To configure the values returned from the iteration (implicit in the call to +`list`), we need to configure the object returned by the call to `foo.iter()`. + +.. doctest:: + + >>> mock_foo = MagicMock() + >>> mock_foo.iter.return_value = iter([1, 2, 3]) + >>> list(mock_foo.iter()) + [1, 2, 3] + +.. [#] There are also generator expressions and more `advanced uses + `_ of generators, but we aren't + concerned about them here. A very good introduction to generators and how + powerful they are is: `Generator Tricks for Systems Programmers + `_. + + +Applying the same patch to every test method +============================================ + +If you want several patches in place for multiple test methods the obvious way +is to apply the patch decorators to every method. This can feel like unnecessary +repetition. For Python 2.6 or more recent you can use `patch` (in all its +various forms) as a class decorator. This applies the patches to all test +methods on the class. A test method is identified by methods whose names start +with `test`: + +.. doctest:: + + >>> @patch('mymodule.SomeClass') + ... class MyTest(TestCase): + ... + ... def test_one(self, MockSomeClass): + ... self.assertTrue(mymodule.SomeClass is MockSomeClass) + ... + ... def test_two(self, MockSomeClass): + ... self.assertTrue(mymodule.SomeClass is MockSomeClass) + ... + ... def not_a_test(self): + ... return 'something' + ... + >>> MyTest('test_one').test_one() + >>> MyTest('test_two').test_two() + >>> MyTest('test_two').not_a_test() + 'something' + +An alternative way of managing patches is to use the :ref:`start-and-stop`. +These allow you to move the patching into your `setUp` and `tearDown` methods. + +.. doctest:: + + >>> class MyTest(TestCase): + ... def setUp(self): + ... self.patcher = patch('mymodule.foo') + ... self.mock_foo = self.patcher.start() + ... + ... def test_foo(self): + ... self.assertTrue(mymodule.foo is self.mock_foo) + ... + ... def tearDown(self): + ... self.patcher.stop() + ... + >>> MyTest('test_foo').run() + +If you use this technique you must ensure that the patching is "undone" by +calling `stop`. This can be fiddlier than you might think, because if an +exception is raised in the setUp then tearDown is not called. `unittest2 +`_ cleanup functions make this simpler: + + +.. doctest:: + + >>> class MyTest(TestCase): + ... def setUp(self): + ... patcher = patch('mymodule.foo') + ... self.addCleanup(patcher.stop) + ... self.mock_foo = patcher.start() + ... + ... def test_foo(self): + ... self.assertTrue(mymodule.foo is self.mock_foo) + ... + >>> MyTest('test_foo').run() + + +Mocking Unbound Methods +======================= + +Whilst writing tests today I needed to patch an *unbound method* (patching the +method on the class rather than on the instance). I needed self to be passed +in as the first argument because I want to make asserts about which objects +were calling this particular method. The issue is that you can't patch with a +mock for this, because if you replace an unbound method with a mock it doesn't +become a bound method when fetched from the instance, and so it doesn't get +self passed in. The workaround is to patch the unbound method with a real +function instead. The :func:`patch` decorator makes it so simple to +patch out methods with a mock that having to create a real function becomes a +nuisance. + +If you pass `autospec=True` to patch then it does the patching with a +*real* function object. This function object has the same signature as the one +it is replacing, but delegates to a mock under the hood. You still get your +mock auto-created in exactly the same way as before. What it means though, is +that if you use it to patch out an unbound method on a class the mocked +function will be turned into a bound method if it is fetched from an instance. +It will have `self` passed in as the first argument, which is exactly what I +wanted: + +.. doctest:: + + >>> class Foo(object): + ... def foo(self): + ... pass + ... + >>> with patch.object(Foo, 'foo', autospec=True) as mock_foo: + ... mock_foo.return_value = 'foo' + ... foo = Foo() + ... foo.foo() + ... + 'foo' + >>> mock_foo.assert_called_once_with(foo) + +If we don't use `autospec=True` then the unbound method is patched out +with a Mock instance instead, and isn't called with `self`. + + +Checking multiple calls with mock +================================= + +mock has a nice API for making assertions about how your mock objects are used. + +.. doctest:: + + >>> mock = Mock() + >>> mock.foo_bar.return_value = None + >>> mock.foo_bar('baz', spam='eggs') + >>> mock.foo_bar.assert_called_with('baz', spam='eggs') + +If your mock is only being called once you can use the +:meth:`assert_called_once_with` method that also asserts that the +:attr:`call_count` is one. + +.. doctest:: + + >>> mock.foo_bar.assert_called_once_with('baz', spam='eggs') + >>> mock.foo_bar() + >>> mock.foo_bar.assert_called_once_with('baz', spam='eggs') + Traceback (most recent call last): + ... + AssertionError: Expected to be called once. Called 2 times. + +Both `assert_called_with` and `assert_called_once_with` make assertions about +the *most recent* call. If your mock is going to be called several times, and +you want to make assertions about *all* those calls you can use +:attr:`~Mock.call_args_list`: + +.. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock(1, 2, 3) + >>> mock(4, 5, 6) + >>> mock() + >>> mock.call_args_list + [call(1, 2, 3), call(4, 5, 6), call()] + +The :data:`call` helper makes it easy to make assertions about these calls. You +can build up a list of expected calls and compare it to `call_args_list`. This +looks remarkably similar to the repr of the `call_args_list`: + +.. doctest:: + + >>> expected = [call(1, 2, 3), call(4, 5, 6), call()] + >>> mock.call_args_list == expected + True + + +Coping with mutable arguments +============================= + +Another situation is rare, but can bite you, is when your mock is called with +mutable arguments. `call_args` and `call_args_list` store *references* to the +arguments. If the arguments are mutated by the code under test then you can no +longer make assertions about what the values were when the mock was called. + +Here's some example code that shows the problem. Imagine the following functions +defined in 'mymodule':: + + def frob(val): + pass + + def grob(val): + "First frob and then clear val" + frob(val) + val.clear() + +When we try to test that `grob` calls `frob` with the correct argument look +what happens: + +.. doctest:: + + >>> with patch('mymodule.frob') as mock_frob: + ... val = set([6]) + ... mymodule.grob(val) + ... + >>> val + set([]) + >>> mock_frob.assert_called_with(set([6])) + Traceback (most recent call last): + ... + AssertionError: Expected: ((set([6]),), {}) + Called with: ((set([]),), {}) + +One possibility would be for mock to copy the arguments you pass in. This +could then cause problems if you do assertions that rely on object identity +for equality. + +Here's one solution that uses the :attr:`side_effect` +functionality. If you provide a `side_effect` function for a mock then +`side_effect` will be called with the same args as the mock. This gives us an +opportunity to copy the arguments and store them for later assertions. In this +example I'm using *another* mock to store the arguments so that I can use the +mock methods for doing the assertion. Again a helper function sets this up for +me. + +.. doctest:: + + >>> from copy import deepcopy + >>> from mock import Mock, patch, DEFAULT + >>> def copy_call_args(mock): + ... new_mock = Mock() + ... def side_effect(*args, **kwargs): + ... args = deepcopy(args) + ... kwargs = deepcopy(kwargs) + ... new_mock(*args, **kwargs) + ... return DEFAULT + ... mock.side_effect = side_effect + ... return new_mock + ... + >>> with patch('mymodule.frob') as mock_frob: + ... new_mock = copy_call_args(mock_frob) + ... val = set([6]) + ... mymodule.grob(val) + ... + >>> new_mock.assert_called_with(set([6])) + >>> new_mock.call_args + call(set([6])) + +`copy_call_args` is called with the mock that will be called. It returns a new +mock that we do the assertion on. The `side_effect` function makes a copy of +the args and calls our `new_mock` with the copy. + +.. note:: + + If your mock is only going to be used once there is an easier way of + checking arguments at the point they are called. You can simply do the + checking inside a `side_effect` function. + + .. doctest:: + + >>> def side_effect(arg): + ... assert arg == set([6]) + ... + >>> mock = Mock(side_effect=side_effect) + >>> mock(set([6])) + >>> mock(set()) + Traceback (most recent call last): + ... + AssertionError + +An alternative approach is to create a subclass of `Mock` or `MagicMock` that +copies (using `copy.deepcopy +`_) the arguments. +Here's an example implementation: + +.. doctest:: + + >>> from copy import deepcopy + >>> class CopyingMock(MagicMock): + ... def __call__(self, *args, **kwargs): + ... args = deepcopy(args) + ... kwargs = deepcopy(kwargs) + ... return super(CopyingMock, self).__call__(*args, **kwargs) + ... + >>> c = CopyingMock(return_value=None) + >>> arg = set() + >>> c(arg) + >>> arg.add(1) + >>> c.assert_called_with(set()) + >>> c.assert_called_with(arg) + Traceback (most recent call last): + ... + AssertionError: Expected call: mock(set([1])) + Actual call: mock(set([])) + >>> c.foo + + +When you subclass `Mock` or `MagicMock` all dynamically created attributes, +and the `return_value` will use your subclass automatically. That means all +children of a `CopyingMock` will also have the type `CopyingMock`. + + +Raising exceptions on attribute access +====================================== + +You can use :class:`PropertyMock` to mimic the behaviour of properties. This +includes raising exceptions when an attribute is accessed. + +Here's an example raising a `ValueError` when the 'foo' attribute is accessed: + +.. doctest:: + + >>> m = MagicMock() + >>> p = PropertyMock(side_effect=ValueError) + >>> type(m).foo = p + >>> m.foo + Traceback (most recent call last): + .... + ValueError + +Because every mock object has its own type, a new subclass of whichever mock +class you're using, all mock objects are isolated from each other. You can +safely attach properties (or other descriptors or whatever you want in fact) +to `type(mock)` without affecting other mock objects. + + +Multiple calls with different effects +===================================== + +.. note:: + + In mock 1.0 the handling of iterable `side_effect` was changed. Any + exceptions in the iterable will be raised instead of returned. + +Handling code that needs to behave differently on subsequent calls during the +test can be tricky. For example you may have a function that needs to raise +an exception the first time it is called but returns a response on the second +call (testing retry behaviour). + +One approach is to use a :attr:`side_effect` function that replaces itself. The +first time it is called the `side_effect` sets a new `side_effect` that will +be used for the second call. It then raises an exception: + +.. doctest:: + + >>> def side_effect(*args): + ... def second_call(*args): + ... return 'response' + ... mock.side_effect = second_call + ... raise Exception('boom') + ... + >>> mock = Mock(side_effect=side_effect) + >>> mock('first') + Traceback (most recent call last): + ... + Exception: boom + >>> mock('second') + 'response' + >>> mock.assert_called_with('second') + +Another perfectly valid way would be to pop return values from a list. If the +return value is an exception, raise it instead of returning it: + +.. doctest:: + + >>> returns = [Exception('boom'), 'response'] + >>> def side_effect(*args): + ... result = returns.pop(0) + ... if isinstance(result, Exception): + ... raise result + ... return result + ... + >>> mock = Mock(side_effect=side_effect) + >>> mock('first') + Traceback (most recent call last): + ... + Exception: boom + >>> mock('second') + 'response' + >>> mock.assert_called_with('second') + +Which approach you prefer is a matter of taste. The first approach is actually +a line shorter but maybe the second approach is more readable. + + +Nesting Patches +=============== + +Using patch as a context manager is nice, but if you do multiple patches you +can end up with nested with statements indenting further and further to the +right: + +.. doctest:: + + >>> class MyTest(TestCase): + ... + ... def test_foo(self): + ... with patch('mymodule.Foo') as mock_foo: + ... with patch('mymodule.Bar') as mock_bar: + ... with patch('mymodule.Spam') as mock_spam: + ... assert mymodule.Foo is mock_foo + ... assert mymodule.Bar is mock_bar + ... assert mymodule.Spam is mock_spam + ... + >>> original = mymodule.Foo + >>> MyTest('test_foo').test_foo() + >>> assert mymodule.Foo is original + +With unittest2_ `cleanup` functions and the :ref:`start-and-stop` we can +achieve the same effect without the nested indentation. A simple helper +method, `create_patch`, puts the patch in place and returns the created mock +for us: + +.. doctest:: + + >>> class MyTest(TestCase): + ... + ... def create_patch(self, name): + ... patcher = patch(name) + ... thing = patcher.start() + ... self.addCleanup(patcher.stop) + ... return thing + ... + ... def test_foo(self): + ... mock_foo = self.create_patch('mymodule.Foo') + ... mock_bar = self.create_patch('mymodule.Bar') + ... mock_spam = self.create_patch('mymodule.Spam') + ... + ... assert mymodule.Foo is mock_foo + ... assert mymodule.Bar is mock_bar + ... assert mymodule.Spam is mock_spam + ... + >>> original = mymodule.Foo + >>> MyTest('test_foo').run() + >>> assert mymodule.Foo is original + + +Mocking a dictionary with MagicMock +=================================== + +You may want to mock a dictionary, or other container object, recording all +access to it whilst having it still behave like a dictionary. + +We can do this with :class:`MagicMock`, which will behave like a dictionary, +and using :data:`~Mock.side_effect` to delegate dictionary access to a real +underlying dictionary that is under our control. + +When the `__getitem__` and `__setitem__` methods of our `MagicMock` are called +(normal dictionary access) then `side_effect` is called with the key (and in +the case of `__setitem__` the value too). We can also control what is returned. + +After the `MagicMock` has been used we can use attributes like +:data:`~Mock.call_args_list` to assert about how the dictionary was used: + +.. doctest:: + + >>> my_dict = {'a': 1, 'b': 2, 'c': 3} + >>> def getitem(name): + ... return my_dict[name] + ... + >>> def setitem(name, val): + ... my_dict[name] = val + ... + >>> mock = MagicMock() + >>> mock.__getitem__.side_effect = getitem + >>> mock.__setitem__.side_effect = setitem + +.. note:: + + An alternative to using `MagicMock` is to use `Mock` and *only* provide + the magic methods you specifically want: + + .. doctest:: + + >>> mock = Mock() + >>> mock.__setitem__ = Mock(side_effect=getitem) + >>> mock.__getitem__ = Mock(side_effect=setitem) + + A *third* option is to use `MagicMock` but passing in `dict` as the `spec` + (or `spec_set`) argument so that the `MagicMock` created only has + dictionary magic methods available: + + .. doctest:: + + >>> mock = MagicMock(spec_set=dict) + >>> mock.__getitem__.side_effect = getitem + >>> mock.__setitem__.side_effect = setitem + +With these side effect functions in place, the `mock` will behave like a normal +dictionary but recording the access. It even raises a `KeyError` if you try +to access a key that doesn't exist. + +.. doctest:: + + >>> mock['a'] + 1 + >>> mock['c'] + 3 + >>> mock['d'] + Traceback (most recent call last): + ... + KeyError: 'd' + >>> mock['b'] = 'fish' + >>> mock['d'] = 'eggs' + >>> mock['b'] + 'fish' + >>> mock['d'] + 'eggs' + +After it has been used you can make assertions about the access using the normal +mock methods and attributes: + +.. doctest:: + + >>> mock.__getitem__.call_args_list + [call('a'), call('c'), call('d'), call('b'), call('d')] + >>> mock.__setitem__.call_args_list + [call('b', 'fish'), call('d', 'eggs')] + >>> my_dict + {'a': 1, 'c': 3, 'b': 'fish', 'd': 'eggs'} + + +Mock subclasses and their attributes +==================================== + +There are various reasons why you might want to subclass `Mock`. One reason +might be to add helper methods. Here's a silly example: + +.. doctest:: + + >>> class MyMock(MagicMock): + ... def has_been_called(self): + ... return self.called + ... + >>> mymock = MyMock(return_value=None) + >>> mymock + + >>> mymock.has_been_called() + False + >>> mymock() + >>> mymock.has_been_called() + True + +The standard behaviour for `Mock` instances is that attributes and the return +value mocks are of the same type as the mock they are accessed on. This ensures +that `Mock` attributes are `Mocks` and `MagicMock` attributes are `MagicMocks` +[#]_. So if you're subclassing to add helper methods then they'll also be +available on the attributes and return value mock of instances of your +subclass. + +.. doctest:: + + >>> mymock.foo + + >>> mymock.foo.has_been_called() + False + >>> mymock.foo() + + >>> mymock.foo.has_been_called() + True + +Sometimes this is inconvenient. For example, `one user +`_ is subclassing mock to +created a `Twisted adaptor +`_. +Having this applied to attributes too actually causes errors. + +`Mock` (in all its flavours) uses a method called `_get_child_mock` to create +these "sub-mocks" for attributes and return values. You can prevent your +subclass being used for attributes by overriding this method. The signature is +that it takes arbitrary keyword arguments (`**kwargs`) which are then passed +onto the mock constructor: + +.. doctest:: + + >>> class Subclass(MagicMock): + ... def _get_child_mock(self, **kwargs): + ... return MagicMock(**kwargs) + ... + >>> mymock = Subclass() + >>> mymock.foo + + >>> assert isinstance(mymock, Subclass) + >>> assert not isinstance(mymock.foo, Subclass) + >>> assert not isinstance(mymock(), Subclass) + +.. [#] An exception to this rule are the non-callable mocks. Attributes use the + callable variant because otherwise non-callable mocks couldn't have callable + methods. + + +Mocking imports with patch.dict +=============================== + +One situation where mocking can be hard is where you have a local import inside +a function. These are harder to mock because they aren't using an object from +the module namespace that we can patch out. + +Generally local imports are to be avoided. They are sometimes done to prevent +circular dependencies, for which there is *usually* a much better way to solve +the problem (refactor the code) or to prevent "up front costs" by delaying the +import. This can also be solved in better ways than an unconditional local +import (store the module as a class or module attribute and only do the import +on first use). + +That aside there is a way to use `mock` to affect the results of an import. +Importing fetches an *object* from the `sys.modules` dictionary. Note that it +fetches an *object*, which need not be a module. Importing a module for the +first time results in a module object being put in `sys.modules`, so usually +when you import something you get a module back. This need not be the case +however. + +This means you can use :func:`patch.dict` to *temporarily* put a mock in place +in `sys.modules`. Any imports whilst this patch is active will fetch the mock. +When the patch is complete (the decorated function exits, the with statement +body is complete or `patcher.stop()` is called) then whatever was there +previously will be restored safely. + +Here's an example that mocks out the 'fooble' module. + +.. doctest:: + + >>> mock = Mock() + >>> with patch.dict('sys.modules', {'fooble': mock}): + ... import fooble + ... fooble.blob() + ... + + >>> assert 'fooble' not in sys.modules + >>> mock.blob.assert_called_once_with() + +As you can see the `import fooble` succeeds, but on exit there is no 'fooble' +left in `sys.modules`. + +This also works for the `from module import name` form: + +.. doctest:: + + >>> mock = Mock() + >>> with patch.dict('sys.modules', {'fooble': mock}): + ... from fooble import blob + ... blob.blip() + ... + + >>> mock.blob.blip.assert_called_once_with() + +With slightly more work you can also mock package imports: + +.. doctest:: + + >>> mock = Mock() + >>> modules = {'package': mock, 'package.module': mock.module} + >>> with patch.dict('sys.modules', modules): + ... from package.module import fooble + ... fooble() + ... + + >>> mock.module.fooble.assert_called_once_with() + + +Tracking order of calls and less verbose call assertions +======================================================== + +The :class:`Mock` class allows you to track the *order* of method calls on +your mock objects through the :attr:`~Mock.method_calls` attribute. This +doesn't allow you to track the order of calls between separate mock objects, +however we can use :attr:`~Mock.mock_calls` to achieve the same effect. + +Because mocks track calls to child mocks in `mock_calls`, and accessing an +arbitrary attribute of a mock creates a child mock, we can create our separate +mocks from a parent one. Calls to those child mock will then all be recorded, +in order, in the `mock_calls` of the parent: + +.. doctest:: + + >>> manager = Mock() + >>> mock_foo = manager.foo + >>> mock_bar = manager.bar + + >>> mock_foo.something() + + >>> mock_bar.other.thing() + + + >>> manager.mock_calls + [call.foo.something(), call.bar.other.thing()] + +We can then assert about the calls, including the order, by comparing with +the `mock_calls` attribute on the manager mock: + +.. doctest:: + + >>> expected_calls = [call.foo.something(), call.bar.other.thing()] + >>> manager.mock_calls == expected_calls + True + +If `patch` is creating, and putting in place, your mocks then you can attach +them to a manager mock using the :meth:`~Mock.attach_mock` method. After +attaching calls will be recorded in `mock_calls` of the manager. + +.. doctest:: + + >>> manager = MagicMock() + >>> with patch('mymodule.Class1') as MockClass1: + ... with patch('mymodule.Class2') as MockClass2: + ... manager.attach_mock(MockClass1, 'MockClass1') + ... manager.attach_mock(MockClass2, 'MockClass2') + ... MockClass1().foo() + ... MockClass2().bar() + ... + + + >>> manager.mock_calls + [call.MockClass1(), + call.MockClass1().foo(), + call.MockClass2(), + call.MockClass2().bar()] + +If many calls have been made, but you're only interested in a particular +sequence of them then an alternative is to use the +:meth:`~Mock.assert_has_calls` method. This takes a list of calls (constructed +with the :data:`call` object). If that sequence of calls are in +:attr:`~Mock.mock_calls` then the assert succeeds. + +.. doctest:: + + >>> m = MagicMock() + >>> m().foo().bar().baz() + + >>> m.one().two().three() + + >>> calls = call.one().two().three().call_list() + >>> m.assert_has_calls(calls) + +Even though the chained call `m.one().two().three()` aren't the only calls that +have been made to the mock, the assert still succeeds. + +Sometimes a mock may have several calls made to it, and you are only interested +in asserting about *some* of those calls. You may not even care about the +order. In this case you can pass `any_order=True` to `assert_has_calls`: + +.. doctest:: + + >>> m = MagicMock() + >>> m(1), m.two(2, 3), m.seven(7), m.fifty('50') + (...) + >>> calls = [call.fifty('50'), call(1), call.seven(7)] + >>> m.assert_has_calls(calls, any_order=True) + + +More complex argument matching +============================== + +Using the same basic concept as `ANY` we can implement matchers to do more +complex assertions on objects used as arguments to mocks. + +Suppose we expect some object to be passed to a mock that by default +compares equal based on object identity (which is the Python default for user +defined classes). To use :meth:`~Mock.assert_called_with` we would need to pass +in the exact same object. If we are only interested in some of the attributes +of this object then we can create a matcher that will check these attributes +for us. + +You can see in this example how a 'standard' call to `assert_called_with` isn't +sufficient: + +.. doctest:: + + >>> class Foo(object): + ... def __init__(self, a, b): + ... self.a, self.b = a, b + ... + >>> mock = Mock(return_value=None) + >>> mock(Foo(1, 2)) + >>> mock.assert_called_with(Foo(1, 2)) + Traceback (most recent call last): + ... + AssertionError: Expected: call(<__main__.Foo object at 0x...>) + Actual call: call(<__main__.Foo object at 0x...>) + +A comparison function for our `Foo` class might look something like this: + +.. doctest:: + + >>> def compare(self, other): + ... if not type(self) == type(other): + ... return False + ... if self.a != other.a: + ... return False + ... if self.b != other.b: + ... return False + ... return True + ... + +And a matcher object that can use comparison functions like this for its +equality operation would look something like this: + +.. doctest:: + + >>> class Matcher(object): + ... def __init__(self, compare, some_obj): + ... self.compare = compare + ... self.some_obj = some_obj + ... def __eq__(self, other): + ... return self.compare(self.some_obj, other) + ... + +Putting all this together: + +.. doctest:: + + >>> match_foo = Matcher(compare, Foo(1, 2)) + >>> mock.assert_called_with(match_foo) + +The `Matcher` is instantiated with our compare function and the `Foo` object +we want to compare against. In `assert_called_with` the `Matcher` equality +method will be called, which compares the object the mock was called with +against the one we created our matcher with. If they match then +`assert_called_with` passes, and if they don't an `AssertionError` is raised: + +.. doctest:: + + >>> match_wrong = Matcher(compare, Foo(3, 4)) + >>> mock.assert_called_with(match_wrong) + Traceback (most recent call last): + ... + AssertionError: Expected: ((,), {}) + Called with: ((,), {}) + +With a bit of tweaking you could have the comparison function raise the +`AssertionError` directly and provide a more useful failure message. + +As of version 1.5, the Python testing library `PyHamcrest +`_ provides similar functionality, +that may be useful here, in the form of its equality matcher +(`hamcrest.library.integration.match_equality +`_). + + +Less verbose configuration of mock objects +========================================== + +This recipe, for easier configuration of mock objects, is now part of `Mock`. +See the :meth:`~Mock.configure_mock` method. + + +Matching any argument in assertions +=================================== + +This example is now built in to mock. See :data:`ANY`. + + +Mocking Properties +================== + +This example is now built in to mock. See :class:`PropertyMock`. + + +Mocking open +============ + +This example is now built in to mock. See :func:`mock_open`. + + +Mocks without some attributes +============================= + +This example is now built in to mock. See :ref:`deleting-attributes`. diff --git a/python/mock-1.0.0/html/_sources/getting-started.txt b/python/mock-1.0.0/html/_sources/getting-started.txt new file mode 100644 index 000000000..1b5d289eb --- /dev/null +++ b/python/mock-1.0.0/html/_sources/getting-started.txt @@ -0,0 +1,479 @@ +=========================== + Getting Started with Mock +=========================== + +.. _getting-started: + +.. index:: Getting Started + +.. testsetup:: + + class SomeClass(object): + static_method = None + class_method = None + attribute = None + + sys.modules['package'] = package = Mock(name='package') + sys.modules['package.module'] = module = package.module + sys.modules['module'] = package.module + + +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: + +.. doctest:: + + >>> real = SomeClass() + >>> real.method = MagicMock(name='method') + >>> real.method(3, 4, 5, key='value') + + +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: + +.. doctest:: + + >>> from mock import MagicMock + >>> 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. + +.. doctest:: + + >>> 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. + +.. doctest:: + + >>> 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 modifying the mock :attr:`~Mock.return_value`. + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> mock = MagicMock(name='foo') + >>> mock + + >>> mock.method + + + +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. + +.. doctest:: + + >>> mock = MagicMock() + >>> mock.method() + + >>> mock.attribute.method(10, x=53) + + >>> 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`: + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> mock = Mock() + >>> mock.return_value = 3 + >>> mock() + 3 + +Of course you can do the same for methods on the mock: + +.. doctest:: + + >>> mock = Mock() + >>> mock.method.return_value = 3 + >>> mock.method() + 3 + +The return value can also be set in the constructor: + +.. doctest:: + + >>> mock = Mock(return_value=3) + >>> mock() + 3 + +If you need an attribute setting on your mock, just do it: + +.. doctest:: + + >>> 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: + + +.. doctest:: + + >>> 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. + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> 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. + +.. doctest:: + + >>> 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 `. + + +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`: + +.. doctest:: + + >>> 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`: + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> @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: + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> 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/python/mock-1.0.0/html/_sources/index.txt b/python/mock-1.0.0/html/_sources/index.txt new file mode 100644 index 000000000..7e4a8daca --- /dev/null +++ b/python/mock-1.0.0/html/_sources/index.txt @@ -0,0 +1,411 @@ +==================================== + Mock - Mocking and Testing Library +==================================== + +.. currentmodule:: mock + +:Author: `Michael Foord + `_ +:Version: |release| +:Date: 2012/10/07 +:Homepage: `Mock Homepage`_ +:Download: `Mock on PyPI`_ +:Documentation: `PDF Documentation + `_ +:License: `BSD License`_ +:Support: `Mailing list (testing-in-python@lists.idyll.org) + `_ +:Issue tracker: `Google code project + `_ + +.. _Mock Homepage: http://www.voidspace.org.uk/python/mock/ +.. _BSD License: http://www.voidspace.org.uk/python/license.shtml + + +.. currentmodule:: mock + +.. module:: mock + :synopsis: Mock object and testing library. + +.. index:: introduction + +mock is a library for testing in Python. It allows you to replace parts of +your system under test with mock objects and make assertions about how they +have been used. + +mock is now part of the Python standard library, available as `unittest.mock +`_ +in Python 3.3 onwards. + +mock provides a core :class:`Mock` class removing the need to create a host +of stubs throughout your test suite. After performing an action, you can make +assertions about which methods / attributes were used and arguments they were +called with. You can also specify return values and set needed attributes in +the normal way. + +Additionally, mock provides a :func:`patch` decorator that handles patching +module and class level attributes within the scope of a test, along with +:const:`sentinel` for creating unique objects. See the `quick guide`_ for +some examples of how to use :class:`Mock`, :class:`MagicMock` and +:func:`patch`. + +Mock is very easy to use and is designed for use with +`unittest `_. Mock is based on +the 'action -> assertion' pattern instead of `'record -> replay'` used by many +mocking frameworks. + +mock is tested on Python versions 2.4-2.7, Python 3 plus the latest versions of +Jython and PyPy. + + +.. testsetup:: + + class ProductionClass(object): + def method(self, *args): + pass + + module = sys.modules['module'] = ProductionClass + ProductionClass.ClassName1 = ProductionClass + ProductionClass.ClassName2 = ProductionClass + + + +API Documentation +================= + +.. toctree:: + :maxdepth: 2 + + mock + patch + helpers + sentinel + magicmock + + +User Guide +========== + +.. toctree:: + :maxdepth: 2 + + getting-started + examples + compare + changelog + + +.. index:: installing + +Installing +========== + +The current version is |release|. Mock is stable and widely used. If you do +find any bugs, or have suggestions for improvements / extensions +then please contact us. + +* `mock on PyPI `_ +* `mock documentation as PDF + `_ +* `Google Code Home & Mercurial Repository `_ + +.. index:: repository +.. index:: hg + +You can checkout the latest development version from the Google Code Mercurial +repository with the following command: + + ``hg clone https://mock.googlecode.com/hg/ mock`` + + +.. index:: pip +.. index:: easy_install +.. index:: setuptools + +If you have pip, setuptools or distribute you can install mock with: + + | ``easy_install -U mock`` + | ``pip install -U mock`` + +Alternatively you can download the mock distribution from PyPI and after +unpacking run: + + ``python setup.py install`` + + +Quick Guide +=========== + +:class:`Mock` and :class:`MagicMock` objects create all attributes and +methods as you access them and store details of how they have been used. You +can configure them, to specify return values or limit what attributes are +available, and then make assertions about how they have been used: + +.. doctest:: + + >>> from mock import MagicMock + >>> thing = ProductionClass() + >>> thing.method = MagicMock(return_value=3) + >>> thing.method(3, 4, 5, key='value') + 3 + >>> thing.method.assert_called_with(3, 4, 5, key='value') + +:attr:`side_effect` allows you to perform side effects, including raising an +exception when a mock is called: + +.. doctest:: + + >>> mock = Mock(side_effect=KeyError('foo')) + >>> mock() + Traceback (most recent call last): + ... + KeyError: 'foo' + + >>> values = {'a': 1, 'b': 2, 'c': 3} + >>> def side_effect(arg): + ... return values[arg] + ... + >>> mock.side_effect = side_effect + >>> mock('a'), mock('b'), mock('c') + (1, 2, 3) + >>> mock.side_effect = [5, 4, 3, 2, 1] + >>> mock(), mock(), mock() + (5, 4, 3) + +Mock has many other ways you can configure it and control its behaviour. For +example the `spec` argument configures the mock to take its specification +from another object. Attempting to access attributes or methods on the mock +that don't exist on the spec will fail with an `AttributeError`. + +The :func:`patch` decorator / context manager makes it easy to mock classes or +objects in a module under test. The object you specify will be replaced with a +mock (or other object) during the test and restored when the test ends: + +.. doctest:: + + >>> from mock import patch + >>> @patch('module.ClassName2') + ... @patch('module.ClassName1') + ... def test(MockClass1, MockClass2): + ... module.ClassName1() + ... module.ClassName2() + + ... assert MockClass1 is module.ClassName1 + ... assert MockClass2 is module.ClassName2 + ... assert MockClass1.called + ... assert MockClass2.called + ... + >>> test() + +.. note:: + + 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 `module.ClassName1` is passed in first. + + 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 `. + +As well as a decorator `patch` can be used as a context manager in a with +statement: + +.. doctest:: + + >>> with patch.object(ProductionClass, 'method', return_value=None) as mock_method: + ... thing = ProductionClass() + ... thing.method(1, 2, 3) + ... + >>> mock_method.assert_called_once_with(1, 2, 3) + + +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: + +.. doctest:: + + >>> foo = {'key': 'value'} + >>> original = foo.copy() + >>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True): + ... assert foo == {'newkey': 'newvalue'} + ... + >>> assert foo == original + +Mock supports the mocking of Python :ref:`magic methods `. The +easiest way of using magic methods is with the :class:`MagicMock` class. It +allows you to do things like: + +.. doctest:: + + >>> mock = MagicMock() + >>> mock.__str__.return_value = 'foobarbaz' + >>> str(mock) + 'foobarbaz' + >>> mock.__str__.assert_called_with() + +Mock allows you to assign functions (or other Mock instances) to magic methods +and they will be called appropriately. The `MagicMock` class is just a Mock +variant that has all of the magic methods pre-created for you (well, all the +useful ones anyway). + +The following is an example of using magic methods with the ordinary Mock +class: + +.. doctest:: + + >>> mock = Mock() + >>> mock.__str__ = Mock(return_value='wheeeeee') + >>> str(mock) + 'wheeeeee' + +For ensuring that the mock objects in your tests have the same api as the +objects they are replacing, you can use :ref:`auto-speccing `. +Auto-speccing can be done through the `autospec` argument to patch, or the +:func:`create_autospec` function. Auto-speccing creates mock objects that +have the same attributes and methods as the objects they are replacing, and +any functions and methods (including constructors) have the same call +signature as the real object. + +This ensures that your mocks will fail in the same way as your production +code if they are used incorrectly: + +.. doctest:: + + >>> from mock import create_autospec + >>> def function(a, b, c): + ... pass + ... + >>> mock_function = create_autospec(function, return_value='fishy') + >>> mock_function(1, 2, 3) + 'fishy' + >>> mock_function.assert_called_once_with(1, 2, 3) + >>> mock_function('wrong arguments') + Traceback (most recent call last): + ... + TypeError: () takes exactly 3 arguments (1 given) + +`create_autospec` can also be used on classes, where it copies the signature of +the `__init__` method, and on callable objects where it copies the signature of +the `__call__` method. + + +.. index:: references +.. index:: articles + +References +========== + +Articles, blog entries and other stuff related to testing with Mock: + +* `Imposing a No DB Discipline on Django unit tests + `_ +* `mock-django: tools for mocking the Django ORM and models + `_ +* `PyCon 2011 Video: Testing with mock `_ +* `Mock objects in Python + `_ +* `Python: Injecting Mock Objects for Powerful Testing + `_ +* `Python Mock: How to assert a substring of logger output + `_ +* `Mocking Django `_ +* `Mocking dates and other classes that can't be modified + `_ +* `Mock recipes `_ +* `Mockity mock mock - some love for the mock module + `_ +* `Coverage and Mock (with django) + `_ +* `Python Unit Testing with Mock `_ +* `Getting started with Python Mock + `_ +* `Smart Parameter Checks with mock + `_ +* `Python mock testing techniques and tools + `_ +* `How To Test Django Template Tags + `_ +* `A presentation on Unit Testing with Mock + `_ +* `Mocking with Django and Google AppEngine + `_ + + +.. index:: tests +.. index:: unittest2 + +Tests +===== + +Mock uses `unittest2 `_ for its own +test suite. In order to run it, use the `unit2` script that comes with +`unittest2` module on a checkout of the source repository: + + `unit2 discover` + +If you have `setuptools `_ as well as +unittest2 you can run: + + ``python setup.py test`` + +On Python 3.2 you can use ``unittest`` module from the standard library. + + ``python3.2 -m unittest discover`` + +.. index:: Python 3 + +On Python 3 the tests for unicode are skipped as they are not relevant. On +Python 2.4 tests that use the with statements are skipped as the with statement +is invalid syntax on Python 2.4. + + +.. index:: older versions + +Older Versions +============== + +Documentation for older versions of mock: + +* `mock 0.8 `_ +* `mock 0.7 `_ +* `mock 0.6 `_ + +Docs from the in-development version of `mock` can be found at +`mock.readthedocs.org `_. + + +Terminology +=========== + +Terminology for objects used to replace other ones can be confusing. Terms +like double, fake, mock, stub, and spy are all used with varying meanings. + +In `classic mock terminology +`_ +:class:`mock.Mock` is a `spy `_ that +allows for *post-mortem* examination. This is what I call the "action -> +assertion" [#]_ pattern of testing. + +I'm not however a fan of this "statically typed mocking terminology" +promulgated by `Martin Fowler +`_. It confuses usage +patterns with implementation and prevents you from using natural terminology +when discussing mocking. + +I much prefer duck typing, if an object used in your test suite looks like a +mock object and quacks like a mock object then it's fine to call it a mock, no +matter what the implementation looks like. + +This terminology is perhaps more useful in less capable languages where +different usage patterns will *require* different implementations. +`mock.Mock()` is capable of being used in most of the different roles +described by Fowler, except (annoyingly / frustratingly / ironically) a Mock +itself! + +How about a simpler definition: a "mock object" is an object used to replace a +real one in a system under test. + +.. [#] This pattern is called "AAA" by some members of the testing community; + "Arrange - Act - Assert". diff --git a/python/mock-1.0.0/html/_sources/magicmock.txt b/python/mock-1.0.0/html/_sources/magicmock.txt new file mode 100644 index 000000000..42b2ed9db --- /dev/null +++ b/python/mock-1.0.0/html/_sources/magicmock.txt @@ -0,0 +1,258 @@ + +.. currentmodule:: mock + + +.. _magic-methods: + +Mocking Magic Methods +===================== + +.. currentmodule:: mock + +:class:`Mock` supports mocking `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 [#]_. + +.. doctest:: + + >>> def __str__(self): + ... return 'fooble' + ... + >>> mock = Mock() + >>> mock.__str__ = __str__ + >>> str(mock) + 'fooble' + + >>> mock = Mock() + >>> mock.__str__ = Mock() + >>> mock.__str__.return_value = 'fooble' + >>> str(mock) + 'fooble' + + >>> mock = Mock() + >>> mock.__iter__ = Mock(return_value=iter([])) + >>> list(mock) + [] + +One use case for this is for mocking objects used as context managers in a +`with` statement: + +.. doctest:: + + >>> mock = Mock() + >>> mock.__enter__ = Mock(return_value='foo') + >>> mock.__exit__ = Mock(return_value=False) + >>> with mock as m: + ... assert m == 'foo' + ... + >>> mock.__enter__.assert_called_with() + >>> mock.__exit__.assert_called_with(None, None, None) + +Calls to magic methods do not appear in :attr:`~Mock.method_calls`, but they +are recorded in :attr:`~Mock.mock_calls`. + +.. note:: + + If you use the `spec` keyword argument to create a mock then attempting to + set a magic method that isn't in the spec will raise an `AttributeError`. + +The full list of supported magic methods is: + +* ``__hash__``, ``__sizeof__``, ``__repr__`` and ``__str__`` +* ``__dir__``, ``__format__`` and ``__subclasses__`` +* ``__floor__``, ``__trunc__`` and ``__ceil__`` +* Comparisons: ``__cmp__``, ``__lt__``, ``__gt__``, ``__le__``, ``__ge__``, + ``__eq__`` and ``__ne__`` +* Container methods: ``__getitem__``, ``__setitem__``, ``__delitem__``, + ``__contains__``, ``__len__``, ``__iter__``, ``__getslice__``, + ``__setslice__``, ``__reversed__`` and ``__missing__`` +* Context manager: ``__enter__`` and ``__exit__`` +* Unary numeric methods: ``__neg__``, ``__pos__`` and ``__invert__`` +* The numeric methods (including right hand and in-place variants): + ``__add__``, ``__sub__``, ``__mul__``, ``__div__``, + ``__floordiv__``, ``__mod__``, ``__divmod__``, ``__lshift__``, + ``__rshift__``, ``__and__``, ``__xor__``, ``__or__``, and ``__pow__`` +* Numeric conversion methods: ``__complex__``, ``__int__``, ``__float__``, + ``__index__`` and ``__coerce__`` +* Descriptor methods: ``__get__``, ``__set__`` and ``__delete__`` +* Pickling: ``__reduce__``, ``__reduce_ex__``, ``__getinitargs__``, + ``__getnewargs__``, ``__getstate__`` and ``__setstate__`` + + +The following methods are supported in Python 2 but don't exist in Python 3: + +* ``__unicode__``, ``__long__``, ``__oct__``, ``__hex__`` and ``__nonzero__`` +* ``__truediv__`` and ``__rtruediv__`` + +The following methods are supported in Python 3 but don't exist in Python 2: + +* ``__bool__`` and ``__next__`` + +The following methods exist but are *not* supported as they are either in use by +mock, can't be set dynamically, or can cause problems: + +* ``__getattr__``, ``__setattr__``, ``__init__`` and ``__new__`` +* ``__prepare__``, ``__instancecheck__``, ``__subclasscheck__``, ``__del__`` + + + +Magic Mock +========== + +There are two `MagicMock` variants: `MagicMock` and `NonCallableMagicMock`. + + +.. class:: MagicMock(*args, **kw) + + ``MagicMock`` is a subclass of :class:`Mock` with default implementations + of most of the magic methods. You can use ``MagicMock`` without having to + configure the magic methods yourself. + + The constructor parameters have the same meaning as for :class:`Mock`. + + If you use the `spec` or `spec_set` arguments then *only* magic methods + that exist in the spec will be created. + + +.. class:: NonCallableMagicMock(*args, **kw) + + A non-callable version of `MagicMock`. + + The constructor parameters have the same meaning as for + :class:`MagicMock`, with the exception of `return_value` and + `side_effect` which have no meaning on a non-callable mock. + +The magic methods are setup with `MagicMock` objects, so you can configure them +and use them in the usual way: + +.. doctest:: + + >>> mock = MagicMock() + >>> mock[3] = 'fish' + >>> mock.__setitem__.assert_called_with(3, 'fish') + >>> mock.__getitem__.return_value = 'result' + >>> mock[2] + 'result' + +By default many of the protocol methods are required to return objects of a +specific type. These methods are preconfigured with a default return value, so +that they can be used without you having to do anything if you aren't interested +in the return value. You can still *set* the return value manually if you want +to change the default. + +Methods and their defaults: + +* ``__lt__``: NotImplemented +* ``__gt__``: NotImplemented +* ``__le__``: NotImplemented +* ``__ge__``: NotImplemented +* ``__int__`` : 1 +* ``__contains__`` : False +* ``__len__`` : 1 +* ``__iter__`` : iter([]) +* ``__exit__`` : False +* ``__complex__`` : 1j +* ``__float__`` : 1.0 +* ``__bool__`` : True +* ``__nonzero__`` : True +* ``__oct__`` : '1' +* ``__hex__`` : '0x1' +* ``__long__`` : long(1) +* ``__index__`` : 1 +* ``__hash__`` : default hash for the mock +* ``__str__`` : default str for the mock +* ``__unicode__`` : default unicode for the mock +* ``__sizeof__``: default sizeof for the mock + +For example: + +.. doctest:: + + >>> mock = MagicMock() + >>> int(mock) + 1 + >>> len(mock) + 0 + >>> hex(mock) + '0x1' + >>> list(mock) + [] + >>> object() in mock + False + +The two equality method, `__eq__` and `__ne__`, are special (changed in +0.7.2). They do the default equality comparison on identity, using a side +effect, unless you change their return value to return something else: + +.. doctest:: + + >>> MagicMock() == 3 + False + >>> MagicMock() != 3 + True + >>> mock = MagicMock() + >>> mock.__eq__.return_value = True + >>> mock == 3 + True + +In `0.8` the `__iter__` also gained special handling implemented with a +side effect. The return value of `MagicMock.__iter__` can be any iterable +object and isn't required to be an iterator: + +.. doctest:: + + >>> mock = MagicMock() + >>> mock.__iter__.return_value = ['a', 'b', 'c'] + >>> list(mock) + ['a', 'b', 'c'] + >>> list(mock) + ['a', 'b', 'c'] + +If the return value *is* an iterator, then iterating over it once will consume +it and subsequent iterations will result in an empty list: + +.. doctest:: + + >>> mock.__iter__.return_value = iter(['a', 'b', 'c']) + >>> list(mock) + ['a', 'b', 'c'] + >>> list(mock) + [] + +``MagicMock`` has all of the supported magic methods configured except for some +of the obscure and obsolete ones. You can still set these up if you want. + +Magic methods that are supported but not setup by default in ``MagicMock`` are: + +* ``__cmp__`` +* ``__getslice__`` and ``__setslice__`` +* ``__coerce__`` +* ``__subclasses__`` +* ``__dir__`` +* ``__format__`` +* ``__get__``, ``__set__`` and ``__delete__`` +* ``__reversed__`` and ``__missing__`` +* ``__reduce__``, ``__reduce_ex__``, ``__getinitargs__``, ``__getnewargs__``, + ``__getstate__`` and ``__setstate__`` +* ``__getformat__`` and ``__setformat__`` + + + +------------ + +.. [#] Magic methods *should* be looked up on the class rather than the + instance. Different versions of Python are inconsistent about applying this + rule. The supported protocol methods should work with all supported versions + of Python. +.. [#] The function is basically hooked up to the class, but each ``Mock`` + instance is kept isolated from the others. diff --git a/python/mock-1.0.0/html/_sources/mock.txt b/python/mock-1.0.0/html/_sources/mock.txt new file mode 100644 index 000000000..58712b21a --- /dev/null +++ b/python/mock-1.0.0/html/_sources/mock.txt @@ -0,0 +1,842 @@ +The Mock Class +============== + +.. currentmodule:: mock + +.. testsetup:: + + class SomeClass: + pass + + +`Mock` is a flexible mock object intended to replace the use of stubs and +test doubles throughout your code. Mocks are callable and create attributes as +new mocks when you access them [#]_. Accessing the same attribute will always +return the same mock. Mocks record how you use them, allowing you to make +assertions about what your code has done to them. + +:class:`MagicMock` is a subclass of `Mock` with all the magic methods +pre-created and ready to use. There are also non-callable variants, useful +when you are mocking out objects that aren't callable: +:class:`NonCallableMock` and :class:`NonCallableMagicMock` + +The :func:`patch` decorators makes it easy to temporarily replace classes +in a particular module with a `Mock` object. By default `patch` will create +a `MagicMock` for you. You can specify an alternative class of `Mock` using +the `new_callable` argument to `patch`. + + +.. index:: side_effect +.. index:: return_value +.. index:: wraps +.. index:: name +.. index:: spec + +.. class:: Mock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, **kwargs) + + Create a new `Mock` object. `Mock` takes several optional arguments + that specify the behaviour of the Mock object: + + * `spec`: This can be either a list of strings or an existing object (a + class or instance) that acts as the specification for the mock object. If + you pass in an object then a list of strings is formed by calling dir on + the object (excluding unsupported magic attributes and methods). + Accessing any attribute not in this list will raise an `AttributeError`. + + If `spec` is an object (rather than a list of strings) then + :attr:`__class__` returns the class of the spec object. This allows mocks + to pass `isinstance` tests. + + * `spec_set`: A stricter variant of `spec`. If used, attempting to *set* + or get an attribute on the mock that isn't on the object passed as + `spec_set` will raise an `AttributeError`. + + * `side_effect`: A function to be called whenever the Mock is called. See + the :attr:`~Mock.side_effect` attribute. Useful for raising exceptions or + dynamically changing return values. The function is called with the same + arguments as the mock, and unless it returns :data:`DEFAULT`, the return + value of this function is used as the return value. + + Alternatively `side_effect` can be an exception class or instance. In + this case the exception will be raised when the mock is called. + + If `side_effect` is an iterable then each call to the mock will return + the next value from the iterable. If any of the members of the iterable + are exceptions they will be raised instead of returned. + + A `side_effect` can be cleared by setting it to `None`. + + * `return_value`: The value returned when the mock is called. By default + this is a new Mock (created on first access). See the + :attr:`return_value` attribute. + + * `wraps`: Item for the mock object to wrap. If `wraps` is not None then + calling the Mock will pass the call through to the wrapped object + (returning the real result and ignoring `return_value`). Attribute access + on the mock will return a Mock object that wraps the corresponding + attribute of the wrapped object (so attempting to access an attribute + that doesn't exist will raise an `AttributeError`). + + If the mock has an explicit `return_value` set then calls are not passed + to the wrapped object and the `return_value` is returned instead. + + * `name`: If the mock has a name then it will be used in the repr of the + mock. This can be useful for debugging. The name is propagated to child + mocks. + + Mocks can also be called with arbitrary keyword arguments. These will be + used to set attributes on the mock after it is created. See the + :meth:`configure_mock` method for details. + + + .. method:: assert_called_with(*args, **kwargs) + + This method is a convenient way of asserting that calls are made in a + particular way: + + .. doctest:: + + >>> mock = Mock() + >>> mock.method(1, 2, 3, test='wow') + + >>> mock.method.assert_called_with(1, 2, 3, test='wow') + + + .. method:: assert_called_once_with(*args, **kwargs) + + Assert that the mock was called exactly once and with the specified + arguments. + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock('foo', bar='baz') + >>> mock.assert_called_once_with('foo', bar='baz') + >>> mock('foo', bar='baz') + >>> mock.assert_called_once_with('foo', bar='baz') + Traceback (most recent call last): + ... + AssertionError: Expected to be called once. Called 2 times. + + + .. method:: assert_any_call(*args, **kwargs) + + assert the mock has been called with the specified arguments. + + The assert passes if the mock has *ever* been called, unlike + :meth:`assert_called_with` and :meth:`assert_called_once_with` that + only pass if the call is the most recent one. + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock(1, 2, arg='thing') + >>> mock('some', 'thing', 'else') + >>> mock.assert_any_call(1, 2, arg='thing') + + + .. method:: assert_has_calls(calls, any_order=False) + + assert the mock has been called with the specified calls. + The `mock_calls` list is checked for the calls. + + If `any_order` is False (the default) then the calls must be + sequential. There can be extra calls before or after the + specified calls. + + If `any_order` is True then the calls can be in any order, but + they must all appear in :attr:`mock_calls`. + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock(1) + >>> mock(2) + >>> mock(3) + >>> mock(4) + >>> calls = [call(2), call(3)] + >>> mock.assert_has_calls(calls) + >>> calls = [call(4), call(2), call(3)] + >>> mock.assert_has_calls(calls, any_order=True) + + + .. method:: reset_mock() + + The reset_mock method resets all the call attributes on a mock object: + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock('hello') + >>> mock.called + True + >>> mock.reset_mock() + >>> mock.called + False + + This can be useful where you want to make a series of assertions that + reuse the same object. Note that `reset_mock` *doesn't* clear the + return value, :attr:`side_effect` or any child attributes you have + set using normal assignment. Child mocks and the return value mock + (if any) are reset as well. + + + .. method:: mock_add_spec(spec, spec_set=False) + + Add a spec to a mock. `spec` can either be an object or a + list of strings. Only attributes on the `spec` can be fetched as + attributes from the mock. + + If `spec_set` is `True` then only attributes on the spec can be set. + + + .. method:: attach_mock(mock, attribute) + + Attach a mock as an attribute of this one, replacing its name and + parent. Calls to the attached mock will be recorded in the + :attr:`method_calls` and :attr:`mock_calls` attributes of this one. + + + .. method:: configure_mock(**kwargs) + + Set attributes on the mock through keyword arguments. + + Attributes plus return values and side effects can be set on child + mocks using standard dot notation and unpacking a dictionary in the + method call: + + .. doctest:: + + >>> mock = Mock() + >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} + >>> mock.configure_mock(**attrs) + >>> mock.method() + 3 + >>> mock.other() + Traceback (most recent call last): + ... + KeyError + + The same thing can be achieved in the constructor call to mocks: + + .. doctest:: + + >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} + >>> mock = Mock(some_attribute='eggs', **attrs) + >>> mock.some_attribute + 'eggs' + >>> mock.method() + 3 + >>> mock.other() + Traceback (most recent call last): + ... + KeyError + + `configure_mock` exists to make it easier to do configuration + after the mock has been created. + + + .. method:: __dir__() + + `Mock` objects limit the results of `dir(some_mock)` to useful results. + For mocks with a `spec` this includes all the permitted attributes + for the mock. + + See :data:`FILTER_DIR` for what this filtering does, and how to + switch it off. + + + .. method:: _get_child_mock(**kw) + + Create the child mocks for attributes and return value. + By default child mocks will be the same type as the parent. + Subclasses of Mock may want to override this to customize the way + child mocks are made. + + For non-callable mocks the callable variant will be used (rather than + any custom subclass). + + + .. attribute:: called + + A boolean representing whether or not the mock object has been called: + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock.called + False + >>> mock() + >>> mock.called + True + + .. attribute:: call_count + + An integer telling you how many times the mock object has been called: + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock.call_count + 0 + >>> mock() + >>> mock() + >>> mock.call_count + 2 + + + .. attribute:: return_value + + Set this to configure the value returned by calling the mock: + + .. doctest:: + + >>> mock = Mock() + >>> mock.return_value = 'fish' + >>> mock() + 'fish' + + The default return value is a mock object and you can configure it in + the normal way: + + .. doctest:: + + >>> mock = Mock() + >>> mock.return_value.attribute = sentinel.Attribute + >>> mock.return_value() + + >>> mock.return_value.assert_called_with() + + `return_value` can also be set in the constructor: + + .. doctest:: + + >>> mock = Mock(return_value=3) + >>> mock.return_value + 3 + >>> mock() + 3 + + + .. attribute:: side_effect + + This can either be a function to be called when the mock is called, + or an exception (class or instance) to be raised. + + If you pass in a function it will be called with same arguments as the + mock and unless the function returns the :data:`DEFAULT` singleton the + call to the mock will then return whatever the function returns. If the + function returns :data:`DEFAULT` then the mock will return its normal + value (from the :attr:`return_value`. + + An example of a mock that raises an exception (to test exception + handling of an API): + + .. doctest:: + + >>> mock = Mock() + >>> mock.side_effect = Exception('Boom!') + >>> mock() + Traceback (most recent call last): + ... + Exception: Boom! + + Using `side_effect` to return a sequence of values: + + .. doctest:: + + >>> mock = Mock() + >>> mock.side_effect = [3, 2, 1] + >>> mock(), mock(), mock() + (3, 2, 1) + + The `side_effect` function is called with the same arguments as the + mock (so it is wise for it to take arbitrary args and keyword + arguments) and whatever it returns is used as the return value for + the call. The exception is if `side_effect` returns :data:`DEFAULT`, + in which case the normal :attr:`return_value` is used. + + .. doctest:: + + >>> mock = Mock(return_value=3) + >>> def side_effect(*args, **kwargs): + ... return DEFAULT + ... + >>> mock.side_effect = side_effect + >>> mock() + 3 + + `side_effect` can be set in the constructor. Here's an example that + adds one to the value the mock is called with and returns it: + + .. doctest:: + + >>> side_effect = lambda value: value + 1 + >>> mock = Mock(side_effect=side_effect) + >>> mock(3) + 4 + >>> mock(-8) + -7 + + Setting `side_effect` to `None` clears it: + + .. doctest:: + + >>> from mock import Mock + >>> m = Mock(side_effect=KeyError, return_value=3) + >>> m() + Traceback (most recent call last): + ... + KeyError + >>> m.side_effect = None + >>> m() + 3 + + + .. attribute:: call_args + + This is either `None` (if the mock hasn't been called), or the + arguments that the mock was last called with. This will be in the + form of a tuple: the first member is any ordered arguments the mock + was called with (or an empty tuple) and the second member is any + keyword arguments (or an empty dictionary). + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> print mock.call_args + None + >>> mock() + >>> mock.call_args + call() + >>> mock.call_args == () + True + >>> mock(3, 4) + >>> mock.call_args + call(3, 4) + >>> mock.call_args == ((3, 4),) + True + >>> mock(3, 4, 5, key='fish', next='w00t!') + >>> mock.call_args + call(3, 4, 5, key='fish', next='w00t!') + + `call_args`, along with members of the lists :attr:`call_args_list`, + :attr:`method_calls` and :attr:`mock_calls` are :data:`call` objects. + These are tuples, so they can be unpacked to get at the individual + arguments and make more complex assertions. See + :ref:`calls as tuples `. + + + .. attribute:: call_args_list + + This is a list of all the calls made to the mock object in sequence + (so the length of the list is the number of times it has been + called). Before any calls have been made it is an empty list. The + :data:`call` object can be used for conveniently constructing lists of + calls to compare with `call_args_list`. + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock() + >>> mock(3, 4) + >>> mock(key='fish', next='w00t!') + >>> mock.call_args_list + [call(), call(3, 4), call(key='fish', next='w00t!')] + >>> expected = [(), ((3, 4),), ({'key': 'fish', 'next': 'w00t!'},)] + >>> mock.call_args_list == expected + True + + Members of `call_args_list` are :data:`call` objects. These can be + unpacked as tuples to get at the individual arguments. See + :ref:`calls as tuples `. + + + .. attribute:: method_calls + + As well as tracking calls to themselves, mocks also track calls to + methods and attributes, and *their* methods and attributes: + + .. doctest:: + + >>> mock = Mock() + >>> mock.method() + + >>> mock.property.method.attribute() + + >>> mock.method_calls + [call.method(), call.property.method.attribute()] + + Members of `method_calls` are :data:`call` objects. These can be + unpacked as tuples to get at the individual arguments. See + :ref:`calls as tuples `. + + + .. attribute:: mock_calls + + `mock_calls` records *all* calls to the mock object, its methods, magic + methods *and* return value mocks. + + .. doctest:: + + >>> mock = MagicMock() + >>> result = mock(1, 2, 3) + >>> mock.first(a=3) + + >>> mock.second() + + >>> int(mock) + 1 + >>> result(1) + + >>> expected = [call(1, 2, 3), call.first(a=3), call.second(), + ... call.__int__(), call()(1)] + >>> mock.mock_calls == expected + True + + Members of `mock_calls` are :data:`call` objects. These can be + unpacked as tuples to get at the individual arguments. See + :ref:`calls as tuples `. + + + .. attribute:: __class__ + + Normally the `__class__` attribute of an object will return its type. + For a mock object with a `spec` `__class__` returns the spec class + instead. This allows mock objects to pass `isinstance` tests for the + object they are replacing / masquerading as: + + .. doctest:: + + >>> mock = Mock(spec=3) + >>> isinstance(mock, int) + True + + `__class__` is assignable to, this allows a mock to pass an + `isinstance` check without forcing you to use a spec: + + .. doctest:: + + >>> mock = Mock() + >>> mock.__class__ = dict + >>> isinstance(mock, dict) + True + +.. class:: NonCallableMock(spec=None, wraps=None, name=None, spec_set=None, **kwargs) + + A non-callable version of `Mock`. The constructor parameters have the same + meaning of `Mock`, with the exception of `return_value` and `side_effect` + which have no meaning on a non-callable mock. + +Mock objects that use a class or an instance as a `spec` or `spec_set` are able +to pass `isintance` tests: + +.. doctest:: + + >>> mock = Mock(spec=SomeClass) + >>> isinstance(mock, SomeClass) + True + >>> mock = Mock(spec_set=SomeClass()) + >>> isinstance(mock, SomeClass) + True + +The `Mock` classes have support for mocking magic methods. See :ref:`magic +methods ` for the full details. + +The mock classes and the :func:`patch` decorators all take arbitrary keyword +arguments for configuration. For the `patch` decorators the keywords are +passed to the constructor of the mock being created. The keyword arguments +are for configuring attributes of the mock: + +.. doctest:: + + >>> m = MagicMock(attribute=3, other='fish') + >>> m.attribute + 3 + >>> m.other + 'fish' + +The return value and side effect of child mocks can be set in the same way, +using dotted notation. As you can't use dotted names directly in a call you +have to create a dictionary and unpack it using `**`: + +.. doctest:: + + >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} + >>> mock = Mock(some_attribute='eggs', **attrs) + >>> mock.some_attribute + 'eggs' + >>> mock.method() + 3 + >>> mock.other() + Traceback (most recent call last): + ... + KeyError + + +.. class:: PropertyMock(*args, **kwargs) + + A mock intended to be used as a property, or other descriptor, on a class. + `PropertyMock` provides `__get__` and `__set__` methods so you can specify + a return value when it is fetched. + + Fetching a `PropertyMock` instance from an object calls the mock, with + no args. Setting it calls the mock with the value being set. + + .. doctest:: + + >>> class Foo(object): + ... @property + ... def foo(self): + ... return 'something' + ... @foo.setter + ... def foo(self, value): + ... pass + ... + >>> with patch('__main__.Foo.foo', new_callable=PropertyMock) as mock_foo: + ... mock_foo.return_value = 'mockity-mock' + ... this_foo = Foo() + ... print this_foo.foo + ... this_foo.foo = 6 + ... + mockity-mock + >>> mock_foo.mock_calls + [call(), call(6)] + +Because of the way mock attributes are stored you can't directly attach a +`PropertyMock` to a mock object. Instead you can attach it to the mock type +object: + +.. doctest:: + + >>> m = MagicMock() + >>> p = PropertyMock(return_value=3) + >>> type(m).foo = p + >>> m.foo + 3 + >>> p.assert_called_once_with() + + +.. index:: __call__ +.. index:: calling + +Calling +======= + +Mock objects are callable. The call will return the value set as the +:attr:`~Mock.return_value` attribute. The default return value is a new Mock +object; it is created the first time the return value is accessed (either +explicitly or by calling the Mock) - but it is stored and the same one +returned each time. + +Calls made to the object will be recorded in the attributes +like :attr:`~Mock.call_args` and :attr:`~Mock.call_args_list`. + +If :attr:`~Mock.side_effect` is set then it will be called after the call has +been recorded, so if `side_effect` raises an exception the call is still +recorded. + +The simplest way to make a mock raise an exception when called is to make +:attr:`~Mock.side_effect` an exception class or instance: + +.. doctest:: + + >>> m = MagicMock(side_effect=IndexError) + >>> m(1, 2, 3) + Traceback (most recent call last): + ... + IndexError + >>> m.mock_calls + [call(1, 2, 3)] + >>> m.side_effect = KeyError('Bang!') + >>> m('two', 'three', 'four') + Traceback (most recent call last): + ... + KeyError: 'Bang!' + >>> m.mock_calls + [call(1, 2, 3), call('two', 'three', 'four')] + +If `side_effect` is a function then whatever that function returns is what +calls to the mock return. The `side_effect` function is called with the +same arguments as the mock. This allows you to vary the return value of the +call dynamically, based on the input: + +.. doctest:: + + >>> def side_effect(value): + ... return value + 1 + ... + >>> m = MagicMock(side_effect=side_effect) + >>> m(1) + 2 + >>> m(2) + 3 + >>> m.mock_calls + [call(1), call(2)] + +If you want the mock to still return the default return value (a new mock), or +any set return value, then there are two ways of doing this. Either return +`mock.return_value` from inside `side_effect`, or return :data:`DEFAULT`: + +.. doctest:: + + >>> m = MagicMock() + >>> def side_effect(*args, **kwargs): + ... return m.return_value + ... + >>> m.side_effect = side_effect + >>> m.return_value = 3 + >>> m() + 3 + >>> def side_effect(*args, **kwargs): + ... return DEFAULT + ... + >>> m.side_effect = side_effect + >>> m() + 3 + +To remove a `side_effect`, and return to the default behaviour, set the +`side_effect` to `None`: + +.. doctest:: + + >>> m = MagicMock(return_value=6) + >>> def side_effect(*args, **kwargs): + ... return 3 + ... + >>> m.side_effect = side_effect + >>> m() + 3 + >>> m.side_effect = None + >>> m() + 6 + +The `side_effect` can also be any iterable object. Repeated calls to the mock +will return values from the iterable (until the iterable is exhausted and +a `StopIteration` is raised): + +.. doctest:: + + >>> m = MagicMock(side_effect=[1, 2, 3]) + >>> m() + 1 + >>> m() + 2 + >>> m() + 3 + >>> m() + Traceback (most recent call last): + ... + StopIteration + +If any members of the iterable are exceptions they will be raised instead of +returned: + +.. doctest:: + + >>> iterable = (33, ValueError, 66) + >>> m = MagicMock(side_effect=iterable) + >>> m() + 33 + >>> m() + Traceback (most recent call last): + ... + ValueError + >>> m() + 66 + + +.. _deleting-attributes: + +Deleting Attributes +=================== + +Mock objects create attributes on demand. This allows them to pretend to be +objects of any type. + +You may want a mock object to return `False` to a `hasattr` call, or raise an +`AttributeError` when an attribute is fetched. You can do this by providing +an object as a `spec` for a mock, but that isn't always convenient. + +You "block" attributes by deleting them. Once deleted, accessing an attribute +will raise an `AttributeError`. + +.. doctest:: + + >>> mock = MagicMock() + >>> hasattr(mock, 'm') + True + >>> del mock.m + >>> hasattr(mock, 'm') + False + >>> del mock.f + >>> mock.f + Traceback (most recent call last): + ... + AttributeError: f + + +Attaching Mocks as Attributes +============================= + +When you attach a mock as an attribute of another mock (or as the return +value) it becomes a "child" of that mock. Calls to the child are recorded in +the :attr:`~Mock.method_calls` and :attr:`~Mock.mock_calls` attributes of the +parent. This is useful for configuring child mocks and then attaching them to +the parent, or for attaching mocks to a parent that records all calls to the +children and allows you to make assertions about the order of calls between +mocks: + +.. doctest:: + + >>> parent = MagicMock() + >>> child1 = MagicMock(return_value=None) + >>> child2 = MagicMock(return_value=None) + >>> parent.child1 = child1 + >>> parent.child2 = child2 + >>> child1(1) + >>> child2(2) + >>> parent.mock_calls + [call.child1(1), call.child2(2)] + +The exception to this is if the mock has a name. This allows you to prevent +the "parenting" if for some reason you don't want it to happen. + +.. doctest:: + + >>> mock = MagicMock() + >>> not_a_child = MagicMock(name='not-a-child') + >>> mock.attribute = not_a_child + >>> mock.attribute() + + >>> mock.mock_calls + [] + +Mocks created for you by :func:`patch` are automatically given names. To +attach mocks that have names to a parent you use the :meth:`~Mock.attach_mock` +method: + +.. doctest:: + + >>> thing1 = object() + >>> thing2 = object() + >>> parent = MagicMock() + >>> with patch('__main__.thing1', return_value=None) as child1: + ... with patch('__main__.thing2', return_value=None) as child2: + ... parent.attach_mock(child1, 'child1') + ... parent.attach_mock(child2, 'child2') + ... child1('one') + ... child2('two') + ... + >>> parent.mock_calls + [call.child1('one'), call.child2('two')] + + +----- + +.. [#] The only exceptions are magic methods and attributes (those that have + leading and trailing double underscores). Mock doesn't create these but + instead of raises an ``AttributeError``. This is because the interpreter + will often implicitly request these methods, and gets *very* confused to + get a new Mock object when it expects a magic method. If you need magic + method support see :ref:`magic methods `. diff --git a/python/mock-1.0.0/html/_sources/mocksignature.txt b/python/mock-1.0.0/html/_sources/mocksignature.txt new file mode 100644 index 000000000..dbb5019fb --- /dev/null +++ b/python/mock-1.0.0/html/_sources/mocksignature.txt @@ -0,0 +1,262 @@ +mocksignature +============= + +.. currentmodule:: mock + +.. note:: + + :ref:`auto-speccing`, added in mock 0.8, is a more advanced version of + `mocksignature` and can be used for many of the same use cases. + +A problem with using mock objects to replace real objects in your tests is that +:class:`Mock` can be *too* flexible. Your code can treat the mock objects in +any way and you have to manually check that they were called correctly. If your +code calls functions or methods with the wrong number of arguments then mocks +don't complain. + +The solution to this is `mocksignature`, which creates functions with the +same signature as the original, but delegating to a mock. You can interrogate +the mock in the usual way to check it has been called with the *right* +arguments, but if it is called with the wrong number of arguments it will +raise a `TypeError` in the same way your production code would. + +Another advantage is that your mocked objects are real functions, which can +be useful when your code uses +`inspect `_ or depends on +functions being function objects. + +.. function:: mocksignature(func, mock=None, skipfirst=False) + + Create a new function with the same signature as `func` that delegates + to `mock`. If `skipfirst` is True the first argument is skipped, useful + for methods where `self` needs to be omitted from the new function. + + If you don't pass in a `mock` then one will be created for you. + + Functions returned by `mocksignature` have many of the same attributes + and assert methods as a mock object. + + The mock is set as the `mock` attribute of the returned function for easy + access. + + `mocksignature` can also be used with classes. It copies the signature of + the `__init__` method. + + When used with callable objects (instances) it copies the signature of the + `__call__` method. + +`mocksignature` will work out if it is mocking the signature of a method on +an instance or a method on a class and do the "right thing" with the `self` +argument in both cases. + +Because of a limitation in the way that arguments are collected by functions +created by `mocksignature` they are *always* passed as positional arguments +(including defaults) and not keyword arguments. + + +mocksignature api +----------------- + +Although the objects returned by `mocksignature` api are real function objects, +they have much of the same api as the :class:`Mock` class. This includes the +assert methods: + +.. doctest:: + + >>> def func(a, b, c): + ... pass + ... + >>> func2 = mocksignature(func) + >>> func2.called + False + >>> func2.return_value = 3 + >>> func2(1, 2, 3) + 3 + >>> func2.called + True + >>> func2.assert_called_once_with(1, 2, 3) + >>> func2.assert_called_with(1, 2, 4) + Traceback (most recent call last): + ... + AssertionError: Expected call: mock(1, 2, 4) + Actual call: mock(1, 2, 3) + >>> func2.call_count + 1 + >>> func2.side_effect = IndexError + >>> func2(4, 5, 6) + Traceback (most recent call last): + ... + IndexError + +The mock object that is being delegated to is available as the `mock` attribute +of the function created by `mocksignature`. + +.. doctest:: + + >>> func2.mock.mock_calls + [call(1, 2, 3), call(4, 5, 6)] + +The methods and attributes available on functions returned by `mocksignature` +are: + + :meth:`~Mock.assert_any_call`, :meth:`~Mock.assert_called_once_with`, + :meth:`~Mock.assert_called_with`, :meth:`~Mock.assert_has_calls`, + :attr:`~Mock.call_args`, :attr:`~Mock.call_args_list`, + :attr:`~Mock.call_count`, :attr:`~Mock.called`, + :attr:`~Mock.method_calls`, `mock`, :attr:`~Mock.mock_calls`, + :meth:`~Mock.reset_mock`, :attr:`~Mock.return_value`, and + :attr:`~Mock.side_effect`. + + +Example use +----------- + +Basic use +~~~~~~~~~ + +.. doctest:: + + >>> def function(a, b, c=None): + ... pass + ... + >>> mock = Mock() + >>> function = mocksignature(function, mock) + >>> function() + Traceback (most recent call last): + ... + TypeError: () takes at least 2 arguments (0 given) + >>> function.return_value = 'some value' + >>> function(1, 2, 'foo') + 'some value' + >>> function.assert_called_with(1, 2, 'foo') + + +Keyword arguments +~~~~~~~~~~~~~~~~~ + +Note that arguments to functions created by `mocksignature` are always passed +in to the underlying mock by position even when called with keywords: + +.. doctest:: + + >>> def function(a, b, c=None): + ... pass + ... + >>> function = mocksignature(function) + >>> function.return_value = None + >>> function(1, 2) + >>> function.assert_called_with(1, 2, None) + + +Mocking methods and self +~~~~~~~~~~~~~~~~~~~~~~~~ + +When you use `mocksignature` to replace a method on a class then `self` +will be included in the method signature - and you will need to include +the instance when you do your asserts. + +As a curious factor of the way Python (2) wraps methods fetched from a class, +we can *get* the `return_value` from a function set on a class, but we can't +set it. We have to do this through the exposed `mock` attribute instead: + +.. doctest:: + + >>> class SomeClass(object): + ... def method(self, a, b, c=None): + ... pass + ... + >>> SomeClass.method = mocksignature(SomeClass.method) + >>> SomeClass.method.mock.return_value = None + >>> instance = SomeClass() + >>> instance.method() + Traceback (most recent call last): + ... + TypeError: () takes at least 4 arguments (1 given) + >>> instance.method(1, 2, 3) + >>> instance.method.assert_called_with(instance, 1, 2, 3) + +When you use `mocksignature` on instance methods `self` isn't included (and we +can set the `return_value` etc directly): + +.. doctest:: + + >>> class SomeClass(object): + ... def method(self, a, b, c=None): + ... pass + ... + >>> instance = SomeClass() + >>> instance.method = mocksignature(instance.method) + >>> instance.method.return_value = None + >>> instance.method(1, 2, 3) + >>> instance.method.assert_called_with(1, 2, 3) + + +mocksignature with classes +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When used with a class `mocksignature` copies the signature of the `__init__` +method. + +.. doctest:: + + >>> class Something(object): + ... def __init__(self, foo, bar): + ... pass + ... + >>> MockSomething = mocksignature(Something) + >>> instance = MockSomething(10, 9) + >>> assert instance is MockSomething.return_value + >>> MockSomething.assert_called_with(10, 9) + >>> MockSomething() + Traceback (most recent call last): + ... + TypeError: () takes at least 2 arguments (0 given) + +Because the object returned by `mocksignature` is a function rather than a +`Mock` you lose the other capabilities of `Mock`, like dynamic attribute +creation. + + +mocksignature with callable objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When used with a callable object `mocksignature` copies the signature of the +`__call__` method. + +.. doctest:: + + >>> class Something(object): + ... def __call__(self, spam, eggs): + ... pass + ... + >>> something = Something() + >>> mock_something = mocksignature(something) + >>> result = mock_something(10, 9) + >>> mock_something.assert_called_with(10, 9) + >>> mock_something() + Traceback (most recent call last): + ... + TypeError: () takes at least 2 arguments (0 given) + + +mocksignature argument to patch +------------------------------- + +`mocksignature` is available as a keyword argument to :func:`patch` or +:func:`patch.object`. It can be used with functions / methods / classes and +callable objects. + +.. doctest:: + + >>> class SomeClass(object): + ... def method(self, a, b, c=None): + ... pass + ... + >>> @patch.object(SomeClass, 'method', mocksignature=True) + ... def test(mock_method): + ... instance = SomeClass() + ... mock_method.return_value = None + ... instance.method(1, 2) + ... mock_method.assert_called_with(instance, 1, 2, None) + ... + >>> test() diff --git a/python/mock-1.0.0/html/_sources/patch.txt b/python/mock-1.0.0/html/_sources/patch.txt new file mode 100644 index 000000000..3d56264fb --- /dev/null +++ b/python/mock-1.0.0/html/_sources/patch.txt @@ -0,0 +1,636 @@ +================== + Patch Decorators +================== + + +.. currentmodule:: mock + +.. testsetup:: + + class SomeClass(object): + static_method = None + class_method = None + attribute = None + + sys.modules['package'] = package = Mock(name='package') + sys.modules['package.module'] = package.module + + class TestCase(unittest2.TestCase): + def run(self): + result = unittest2.TestResult() + super(unittest2.TestCase, self).run(result) + assert result.wasSuccessful() + +.. testcleanup:: + + patch.TEST_PREFIX = 'test' + + +The patch decorators are used for patching objects only within the scope of +the function they decorate. They automatically handle the unpatching for you, +even if exceptions are raised. All of these functions can also be used in with +statements or as class decorators. + + +patch +===== + +.. note:: + + `patch` is straightforward to use. The key is to do the patching in the + right namespace. See the section `where to patch`_. + +.. function:: patch(target, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs) + + `patch` acts as a function decorator, class decorator or a context + manager. Inside the body of the function or with statement, the `target` + is patched with a `new` object. When the function/with statement exits + the patch is undone. + + If `new` is omitted, then the target is replaced with a + :class:`MagicMock`. If `patch` is used as a decorator and `new` is + omitted, the created mock is passed in as an extra argument to the + decorated function. If `patch` is used as a context manager the created + mock is returned by the context manager. + + `target` should be a string in the form `'package.module.ClassName'`. The + `target` is imported and the specified object replaced with the `new` + object, so the `target` must be importable from the environment you are + calling `patch` from. The target is imported when the decorated function + is executed, not at decoration time. + + The `spec` and `spec_set` keyword arguments are passed to the `MagicMock` + if patch is creating one for you. + + In addition you can pass `spec=True` or `spec_set=True`, which causes + patch to pass in the object being mocked as the spec/spec_set object. + + `new_callable` allows you to specify a different class, or callable object, + that will be called to create the `new` object. By default `MagicMock` is + used. + + A more powerful form of `spec` is `autospec`. If you set `autospec=True` + then the mock with be created with a spec from the object being replaced. + All attributes of the mock will also have the spec of the corresponding + attribute of the object being replaced. Methods and functions being mocked + will have their arguments checked and will raise a `TypeError` if they are + called with the wrong signature. For mocks + replacing a class, their return value (the 'instance') will have the same + spec as the class. See the :func:`create_autospec` function and + :ref:`auto-speccing`. + + Instead of `autospec=True` you can pass `autospec=some_object` to use an + arbitrary object as the spec instead of the one being replaced. + + By default `patch` will fail to replace attributes that don't exist. If + you pass in `create=True`, and the attribute doesn't exist, patch will + create the attribute for you when the patched function is called, and + delete it again afterwards. This is useful for writing tests against + attributes that your production code creates at runtime. It is off by by + default because it can be dangerous. With it switched on you can write + passing tests against APIs that don't actually exist! + + Patch can be used as a `TestCase` class decorator. It works by + decorating each test method in the class. This reduces the boilerplate + code when your test methods share a common patchings set. `patch` finds + tests by looking for method names that start with `patch.TEST_PREFIX`. + By default this is `test`, which matches the way `unittest` finds tests. + You can specify an alternative prefix by setting `patch.TEST_PREFIX`. + + Patch can be used as a context manager, with the with statement. Here the + patching applies to the indented block after the with statement. If you + use "as" then the patched object will be bound to the name after the + "as"; very useful if `patch` is creating a mock object for you. + + `patch` takes arbitrary keyword arguments. These will be passed to + the `Mock` (or `new_callable`) on construction. + + `patch.dict(...)`, `patch.multiple(...)` and `patch.object(...)` are + available for alternate use-cases. + +`patch` as function decorator, creating the mock for you and passing it into +the decorated function: + +.. doctest:: + + >>> @patch('__main__.SomeClass') + ... def function(normal_argument, mock_class): + ... print mock_class is SomeClass + ... + >>> function(None) + True + + +Patching a class replaces the class with a `MagicMock` *instance*. If the +class is instantiated in the code under test then it will be the +:attr:`~Mock.return_value` of the mock that will be used. + +If the class is instantiated multiple times you could use +:attr:`~Mock.side_effect` to return a new mock each time. Alternatively you +can set the `return_value` to be anything you want. + +To configure return values on methods of *instances* on the patched class +you must do this on the `return_value`. For example: + +.. doctest:: + + >>> class Class(object): + ... def method(self): + ... pass + ... + >>> with patch('__main__.Class') as MockClass: + ... instance = MockClass.return_value + ... instance.method.return_value = 'foo' + ... assert Class() is instance + ... assert Class().method() == 'foo' + ... + +If you use `spec` or `spec_set` and `patch` is replacing a *class*, then the +return value of the created mock will have the same spec. + +.. doctest:: + + >>> Original = Class + >>> patcher = patch('__main__.Class', spec=True) + >>> MockClass = patcher.start() + >>> instance = MockClass() + >>> assert isinstance(instance, Original) + >>> patcher.stop() + +The `new_callable` argument is useful where you want to use an alternative +class to the default :class:`MagicMock` for the created mock. For example, if +you wanted a :class:`NonCallableMock` to be used: + +.. doctest:: + + >>> thing = object() + >>> with patch('__main__.thing', new_callable=NonCallableMock) as mock_thing: + ... assert thing is mock_thing + ... thing() + ... + Traceback (most recent call last): + ... + TypeError: 'NonCallableMock' object is not callable + +Another use case might be to replace an object with a `StringIO` instance: + +.. doctest:: + + >>> from StringIO import StringIO + >>> def foo(): + ... print 'Something' + ... + >>> @patch('sys.stdout', new_callable=StringIO) + ... def test(mock_stdout): + ... foo() + ... assert mock_stdout.getvalue() == 'Something\n' + ... + >>> test() + +When `patch` is creating a mock for you, it is common that the first thing +you need to do is to configure the mock. Some of that configuration can be done +in the call to patch. Any arbitrary keywords you pass into the call will be +used to set attributes on the created mock: + +.. doctest:: + + >>> patcher = patch('__main__.thing', first='one', second='two') + >>> mock_thing = patcher.start() + >>> mock_thing.first + 'one' + >>> mock_thing.second + 'two' + +As well as attributes on the created mock attributes, like the +:attr:`~Mock.return_value` and :attr:`~Mock.side_effect`, of child mocks can +also be configured. These aren't syntactically valid to pass in directly as +keyword arguments, but a dictionary with these as keys can still be expanded +into a `patch` call using `**`: + +.. doctest:: + + >>> config = {'method.return_value': 3, 'other.side_effect': KeyError} + >>> patcher = patch('__main__.thing', **config) + >>> mock_thing = patcher.start() + >>> mock_thing.method() + 3 + >>> mock_thing.other() + Traceback (most recent call last): + ... + KeyError + + +patch.object +============ + +.. function:: patch.object(target, attribute, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs) + + patch the named member (`attribute`) on an object (`target`) with a mock + object. + + `patch.object` can be used as a decorator, class decorator or a context + manager. Arguments `new`, `spec`, `create`, `spec_set`, `autospec` and + `new_callable` have the same meaning as for `patch`. Like `patch`, + `patch.object` takes arbitrary keyword arguments for configuring the mock + object it creates. + + When used as a class decorator `patch.object` honours `patch.TEST_PREFIX` + for choosing which methods to wrap. + +You can either call `patch.object` with three arguments or two arguments. The +three argument form takes the object to be patched, the attribute name and the +object to replace the attribute with. + +When calling with the two argument form you omit the replacement object, and a +mock is created for you and passed in as an extra argument to the decorated +function: + +.. doctest:: + + >>> @patch.object(SomeClass, 'class_method') + ... def test(mock_method): + ... SomeClass.class_method(3) + ... mock_method.assert_called_with(3) + ... + >>> test() + +`spec`, `create` and the other arguments to `patch.object` have the same +meaning as they do for `patch`. + + +patch.dict +========== + +.. function:: patch.dict(in_dict, values=(), clear=False, **kwargs) + + Patch a dictionary, or dictionary like object, and restore the dictionary + to its original state after the test. + + `in_dict` can be a dictionary or a mapping like container. If it is a + mapping then it must at least support getting, setting and deleting items + plus iterating over keys. + + `in_dict` can also be a string specifying the name of the dictionary, which + will then be fetched by importing it. + + `values` can be a dictionary of values to set in the dictionary. `values` + can also be an iterable of `(key, value)` pairs. + + If `clear` is True then the dictionary will be cleared before the new + values are set. + + `patch.dict` can also be called with arbitrary keyword arguments to set + values in the dictionary. + + `patch.dict` can be used as a context manager, decorator or class + decorator. When used as a class decorator `patch.dict` honours + `patch.TEST_PREFIX` for choosing which methods to wrap. + +`patch.dict` can be used to add members to a dictionary, or simply let a test +change a dictionary, and ensure the dictionary is restored when the test +ends. + +.. doctest:: + + >>> from mock import patch + >>> foo = {} + >>> with patch.dict(foo, {'newkey': 'newvalue'}): + ... assert foo == {'newkey': 'newvalue'} + ... + >>> assert foo == {} + + >>> import os + >>> with patch.dict('os.environ', {'newkey': 'newvalue'}): + ... print os.environ['newkey'] + ... + newvalue + >>> assert 'newkey' not in os.environ + +Keywords can be used in the `patch.dict` call to set values in the dictionary: + +.. doctest:: + + >>> mymodule = MagicMock() + >>> mymodule.function.return_value = 'fish' + >>> with patch.dict('sys.modules', mymodule=mymodule): + ... import mymodule + ... mymodule.function('some', 'args') + ... + 'fish' + +`patch.dict` can be used with dictionary like objects that aren't actually +dictionaries. At the very minimum they must support item getting, setting, +deleting and either iteration or membership test. This corresponds to the +magic methods `__getitem__`, `__setitem__`, `__delitem__` and either +`__iter__` or `__contains__`. + +.. doctest:: + + >>> class Container(object): + ... def __init__(self): + ... self.values = {} + ... def __getitem__(self, name): + ... return self.values[name] + ... def __setitem__(self, name, value): + ... self.values[name] = value + ... def __delitem__(self, name): + ... del self.values[name] + ... def __iter__(self): + ... return iter(self.values) + ... + >>> thing = Container() + >>> thing['one'] = 1 + >>> with patch.dict(thing, one=2, two=3): + ... assert thing['one'] == 2 + ... assert thing['two'] == 3 + ... + >>> assert thing['one'] == 1 + >>> assert list(thing) == ['one'] + + +patch.multiple +============== + +.. function:: patch.multiple(target, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs) + + Perform multiple patches in a single call. It takes the object to be + patched (either as an object or a string to fetch the object by importing) + and keyword arguments for the patches:: + + with patch.multiple(settings, FIRST_PATCH='one', SECOND_PATCH='two'): + ... + + Use :data:`DEFAULT` as the value if you want `patch.multiple` to create + mocks for you. In this case the created mocks are passed into a decorated + function by keyword, and a dictionary is returned when `patch.multiple` is + used as a context manager. + + `patch.multiple` can be used as a decorator, class decorator or a context + manager. The arguments `spec`, `spec_set`, `create`, `autospec` and + `new_callable` have the same meaning as for `patch`. These arguments will + be applied to *all* patches done by `patch.multiple`. + + When used as a class decorator `patch.multiple` honours `patch.TEST_PREFIX` + for choosing which methods to wrap. + +If you want `patch.multiple` to create mocks for you, then you can use +:data:`DEFAULT` as the value. If you use `patch.multiple` as a decorator +then the created mocks are passed into the decorated function by keyword. + +.. doctest:: + + >>> thing = object() + >>> other = object() + + >>> @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) + ... def test_function(thing, other): + ... assert isinstance(thing, MagicMock) + ... assert isinstance(other, MagicMock) + ... + >>> test_function() + +`patch.multiple` can be nested with other `patch` decorators, but put arguments +passed by keyword *after* any of the standard arguments created by `patch`: + +.. doctest:: + + >>> @patch('sys.exit') + ... @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) + ... def test_function(mock_exit, other, thing): + ... assert 'other' in repr(other) + ... assert 'thing' in repr(thing) + ... assert 'exit' in repr(mock_exit) + ... + >>> test_function() + +If `patch.multiple` is used as a context manager, the value returned by the +context manger is a dictionary where created mocks are keyed by name: + +.. doctest:: + + >>> with patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) as values: + ... assert 'other' in repr(values['other']) + ... assert 'thing' in repr(values['thing']) + ... assert values['thing'] is thing + ... assert values['other'] is other + ... + + +.. _start-and-stop: + +patch methods: start and stop +============================= + +All the patchers have `start` and `stop` methods. These make it simpler to do +patching in `setUp` methods or where you want to do multiple patches without +nesting decorators or with statements. + +To use them call `patch`, `patch.object` or `patch.dict` as normal and keep a +reference to the returned `patcher` object. You can then call `start` to put +the patch in place and `stop` to undo it. + +If you are using `patch` to create a mock for you then it will be returned by +the call to `patcher.start`. + +.. doctest:: + + >>> patcher = patch('package.module.ClassName') + >>> from package import module + >>> original = module.ClassName + >>> new_mock = patcher.start() + >>> assert module.ClassName is not original + >>> assert module.ClassName is new_mock + >>> patcher.stop() + >>> assert module.ClassName is original + >>> assert module.ClassName is not new_mock + + +A typical use case for this might be for doing multiple patches in the `setUp` +method of a `TestCase`: + +.. doctest:: + + >>> class MyTest(TestCase): + ... def setUp(self): + ... self.patcher1 = patch('package.module.Class1') + ... self.patcher2 = patch('package.module.Class2') + ... self.MockClass1 = self.patcher1.start() + ... self.MockClass2 = self.patcher2.start() + ... + ... def tearDown(self): + ... self.patcher1.stop() + ... self.patcher2.stop() + ... + ... def test_something(self): + ... assert package.module.Class1 is self.MockClass1 + ... assert package.module.Class2 is self.MockClass2 + ... + >>> MyTest('test_something').run() + +.. caution:: + + If you use this technique you must ensure that the patching is "undone" by + calling `stop`. This can be fiddlier than you might think, because if an + exception is raised in the setUp then tearDown is not called. `unittest2 + `_ cleanup functions make this + easier. + + .. doctest:: + + >>> class MyTest(TestCase): + ... def setUp(self): + ... patcher = patch('package.module.Class') + ... self.MockClass = patcher.start() + ... self.addCleanup(patcher.stop) + ... + ... def test_something(self): + ... assert package.module.Class is self.MockClass + ... + >>> MyTest('test_something').run() + + As an added bonus you no longer need to keep a reference to the `patcher` + object. + +It is also possible to stop all patches which have been started by using +`patch.stopall`. + +.. function:: patch.stopall + + Stop all active patches. Only stops patches started with `start`. + + +TEST_PREFIX +=========== + +All of the patchers can be used as class decorators. When used in this way +they wrap every test method on the class. The patchers recognise methods that +start with `test` as being test methods. This is the same way that the +`unittest.TestLoader` finds test methods by default. + +It is possible that you want to use a different prefix for your tests. You can +inform the patchers of the different prefix by setting `patch.TEST_PREFIX`: + +.. doctest:: + + >>> patch.TEST_PREFIX = 'foo' + >>> value = 3 + >>> + >>> @patch('__main__.value', 'not three') + ... class Thing(object): + ... def foo_one(self): + ... print value + ... def foo_two(self): + ... print value + ... + >>> + >>> Thing().foo_one() + not three + >>> Thing().foo_two() + not three + >>> value + 3 + + +Nesting Patch Decorators +======================== + +If you want to perform multiple patches then you can simply stack up the +decorators. + +You can stack up multiple patch decorators using this pattern: + +.. doctest:: + + >>> @patch.object(SomeClass, 'class_method') + ... @patch.object(SomeClass, 'static_method') + ... def test(mock1, mock2): + ... assert SomeClass.static_method is mock1 + ... assert SomeClass.class_method is mock2 + ... SomeClass.static_method('foo') + ... SomeClass.class_method('bar') + ... return mock1, mock2 + ... + >>> mock1, mock2 = test() + >>> mock1.assert_called_once_with('foo') + >>> mock2.assert_called_once_with('bar') + + +Note that the decorators are applied from the bottom upwards. This is the +standard way that Python applies decorators. The order of the created mocks +passed into your test function matches this order. + +Like all context-managers patches can be nested using contextlib's nested +function; *every* patching will appear in the tuple after "as": + +.. doctest:: + + >>> from contextlib import nested + >>> with nested( + ... patch('package.module.ClassName1'), + ... patch('package.module.ClassName2') + ... ) as (MockClass1, MockClass2): + ... assert package.module.ClassName1 is MockClass1 + ... assert package.module.ClassName2 is MockClass2 + ... + + +.. _where-to-patch: + +Where to patch +============== + +`patch` works by (temporarily) changing the object that a *name* points to with +another one. There can be many names pointing to any individual object, so +for patching to work you must ensure that you patch the name used by the system +under test. + +The basic principle is that you patch where an object is *looked up*, which +is not necessarily the same place as where it is defined. A couple of +examples will help to clarify this. + +Imagine we have a project that we want to test with the following structure:: + + a.py + -> Defines SomeClass + + b.py + -> from a import SomeClass + -> some_function instantiates SomeClass + +Now we want to test `some_function` but we want to mock out `SomeClass` using +`patch`. The problem is that when we import module b, which we will have to +do then it imports `SomeClass` from module a. If we use `patch` to mock out +`a.SomeClass` then it will have no effect on our test; module b already has a +reference to the *real* `SomeClass` and it looks like our patching had no +effect. + +The key is to patch out `SomeClass` where it is used (or where it is looked up +). In this case `some_function` will actually look up `SomeClass` in module b, +where we have imported it. The patching should look like: + + `@patch('b.SomeClass')` + +However, consider the alternative scenario where instead of `from a import +SomeClass` module b does `import a` and `some_function` uses `a.SomeClass`. Both +of these import forms are common. In this case the class we want to patch is +being looked up on the a module and so we have to patch `a.SomeClass` instead: + + `@patch('a.SomeClass')` + + +Patching Descriptors and Proxy Objects +====================================== + +Since version 0.6.0 both patch_ and patch.object_ have been able to correctly +patch and restore descriptors: class methods, static methods and properties. +You should patch these on the *class* rather than an instance. + +Since version 0.7.0 patch_ and patch.object_ work correctly with some objects +that proxy attribute access, like the `django setttings object +`_. + +.. note:: + + In django `import settings` and `from django.conf import settings` + return different objects. If you are using libraries / apps that do both you + may have to patch both. Grrr... diff --git a/python/mock-1.0.0/html/_sources/sentinel.txt b/python/mock-1.0.0/html/_sources/sentinel.txt new file mode 100644 index 000000000..1c5223da0 --- /dev/null +++ b/python/mock-1.0.0/html/_sources/sentinel.txt @@ -0,0 +1,58 @@ +========== + Sentinel +========== + + +.. currentmodule:: mock + +.. testsetup:: + + class ProductionClass(object): + def something(self): + return self.method() + + class Test(unittest2.TestCase): + def testSomething(self): + pass + self = Test('testSomething') + + +.. data:: sentinel + + The ``sentinel`` object provides a convenient way of providing unique + objects for your tests. + + Attributes are created on demand when you access them by name. Accessing + the same attribute will always return the same object. The objects + returned have a sensible repr so that test failure messages are readable. + + +.. data:: DEFAULT + + The `DEFAULT` object is a pre-created sentinel (actually + `sentinel.DEFAULT`). It can be used by :attr:`~Mock.side_effect` + functions to indicate that the normal return value should be used. + + +Sentinel Example +================ + +Sometimes when testing you need to test that a specific object is passed as an +argument to another method, or returned. It can be common to create named +sentinel objects to test this. `sentinel` provides a convenient way of +creating and testing the identity of objects like this. + +In this example we monkey patch `method` to return +`sentinel.some_object`: + +.. doctest:: + + >>> real = ProductionClass() + >>> real.method = Mock(name="method") + >>> real.method.return_value = sentinel.some_object + >>> result = real.method() + >>> assert result is sentinel.some_object + >>> sentinel.some_object + sentinel.some_object + + diff --git a/python/mock-1.0.0/html/_static/adctheme.css b/python/mock-1.0.0/html/_static/adctheme.css new file mode 100644 index 000000000..60395bcef --- /dev/null +++ b/python/mock-1.0.0/html/_static/adctheme.css @@ -0,0 +1,757 @@ +/** + * Sphinx stylesheet -- basic theme + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + */ + h3 { + color:#000000; + font-size: 17px; + margin-bottom:0.5em; + margin-top:2em; + } +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +/* -- header ---------------------------------------------------------------- */ + +#header #title { + background:#29334F url(title_background.png) repeat-x scroll 0 0; + border-bottom:1px solid #B6B6B6; + height:25px; + overflow:hidden; +} +#headerButtons { + position: absolute; + list-style: none outside; + top: 26px; + left: 0px; + right: 0px; + margin: 0px; + padding: 0px; + border-top: 1px solid #2B334F; + border-bottom: 1px solid #EDEDED; + height: 20px; + font-size: 8pt; + overflow: hidden; + background-color: #D8D8D8; +} + +#headerButtons li { + background-repeat:no-repeat; + display:inline; + margin-top:0; + padding:0; +} + +.headerButton { + display: inline; + height:20px; +} + +.headerButton a { + text-decoration: none; + float: right; + height: 20px; + padding: 4px 15px; + border-left: 1px solid #ACACAC; + font-family:'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; + color: black; +} +.headerButton a:hover { + color: white; + background-color: #787878; + +} + +li#toc_button { + text-align:left; +} + +li#toc_button .headerButton a { + width:198px; + padding-top: 4px; + font-family:'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; + color: black; + float: left; + padding-left:15px; + border-right:1px solid #ACACAC; + background:transparent url(triangle_open.png) no-repeat scroll 4px 6px; +} + +li#toc_button .headerButton a:hover { + background-color: #787878; + color: white; +} + +li#page_buttons { +position:absolute; +right:0; +} + +#breadcrumbs { + color: black; + background-image:url(breadcrumb_background.png); + border-top:1px solid #2B334F; + bottom:0; + font-size:10px; + height:15px; + left:0; + overflow:hidden; + padding:3px 10px 0; + position:absolute; + right:0; + white-space:nowrap; + z-index:901; +} +#breadcrumbs a { + color: black; + text-decoration: none; +} +#breadcrumbs a:hover { + text-decoration: underline; +} +#breadcrumbs img { + padding-left: 3px; +} +/* -- sidebar --------------------------------------------------------------- */ +#sphinxsidebar { + position: absolute; + top: 84px; + bottom: 19px; + left: 0px; + width: 229px; + background-color: #E4EBF7; + border-right: 1px solid #ACACAC; + border-top: 1px solid #2B334F; + overflow-x: hidden; + overflow-y: auto; + padding: 0px 0px 0px 0px; + font-size:11px; +} + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +#sphinxsidebar li { + margin: 0px; + padding: 0px; + font-weight: normal; + margin: 0px 0px 7px 0px; + overflow: hidden; + text-overflow: ellipsis; + font-size: 11px; +} + +#sphinxsidebar ul { + list-style: none; + margin: 0px 0px 0px 0px; + padding: 0px 5px 0px 5px; +} + +#sphinxsidebar ul ul, +#sphinxsidebar ul.want-points { + list-style: square; +} + +#sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +#sphinxsidebar form { + margin-top: 10px; +} + +#sphinxsidebar input { + border: 1px solid #787878; + font-family: sans-serif; + font-size: 1em; +} + +img { + border: 0; +} + +#sphinxsidebar li.toctree-l1 a { + font-weight: bold; + color: #000; + text-decoration: none; +} + +#sphinxsidebar li.toctree-l2 a { + font-weight: bold; + color: #4f4f4f; + text-decoration: none; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} +#sphinxsidebar input.prettysearch {border:none;} +input.searchbutton { + float: right; +} +.search-wrapper {width: 100%; height: 25px;} +.search-wrapper input.prettysearch { border: none; width:200px; height: 16px; background: url(searchfield_repeat.png) center top repeat-x; border: 0px; margin: 0; padding: 3px 0 0 0; font: 11px "Lucida Grande", "Lucida Sans Unicode", Arial, sans-serif; } +.search-wrapper input.prettysearch { width: 184px; margin-left: 20px; *margin-top:-1px; *margin-right:-2px; *margin-left:10px; } +.search-wrapper .search-left { display: block; position: absolute; width: 20px; height: 19px; background: url(searchfield_leftcap.png) left top no-repeat; } +.search-wrapper .search-right { display: block; position: relative; left: 204px; top: -19px; width: 10px; height: 19px; background: url(searchfield_rightcap.png) right top no-repeat; } + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable dl, table.indextable dd { + margin-top: 0; + margin-bottom: 0; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +/* -- general body styles --------------------------------------------------- */ +.document { + border-top:1px solid #2B334F; + overflow:auto; + padding-left:2em; + padding-right:2em; + position:absolute; + z-index:1; + top:84px; + bottom:19px; + right:0; + left:230px; +} + +a.headerlink { + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.field-list ul { + padding-left: 1em; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +/* -- sidebars -------------------------------------------------------------- */ + +/*div.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px 7px 0 7px; + background-color: #ffe; + width: 40%; + float: right; +} + +p.sidebar-title { + font-weight: bold; +} +*/ +/* -- topics ---------------------------------------------------------------- */ + +div.topic { + border: 1px solid #ccc; + padding: 7px 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ +.admonition { + border: 1px solid #a1a5a9; + background-color: #f7f7f7; + margin: 20px; + padding: 0px 8px 7px 9px; + text-align: left; +} +.warning { + background-color:#E8E8E8; + border:1px solid #111111; + margin:30px; +} +.admonition p { + font: 12px 'Lucida Grande', Geneva, Helvetica, Arial, sans-serif; + margin-top: 7px; + margin-bottom: 0px; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dl { + margin-bottom: 0; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; + padding-top: 3px; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + border-collapse: collapse; + border-top: 1px solid #919699; + border-left: 1px solid #919699; + border-right: 1px solid #919699; + font-size:12px; + padding:8px; + text-align:left; + vertical-align:top; +} + +table.docutils td, table.docutils th { + padding: 8px; + font-size: 12px; + text-align: left; + vertical-align: top; + border-bottom: 1px solid #919699; +} + +table.docutils th { + font-weight: bold; +} +/* This alternates colors in up to six table rows (light blue for odd, white for even)*/ +.docutils tr { + background: #F0F5F9; +} + +.docutils tr + tr { + background: #FFFFFF; +} + +.docutils tr + tr + tr { + background: #F0F5F9; +} + +.docutils tr + tr + tr + tr { + background: #FFFFFF; +} + +.docutils tr + tr + tr +tr + tr { + background: #F0F5F9; +} + +.docutils tr + tr + tr + tr + tr + tr { + background: #FFFFFF; +} + +.docutils tr + tr + tr + tr + tr + tr + tr { + background: #F0F5F9; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +th { + text-align: left; + padding-right: 5px; +} + +/* -- other body styles ----------------------------------------------------- */ + +dl { + margin-bottom: 15px; +} + +dd p { + margin-top: 0px; + font-size: 12px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; + font-size: 12px; +} + +dt:target, .highlight { + background-color: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 0.8em; +} + +dl.glossary dd { + font-size:12px; +} +.field-list ul { + vertical-align: top; + margin: 0; + padding-bottom: 0; + list-style: none inside; +} + +.field-list ul li { + margin-top: 0; +} + +.field-list p { + margin: 0; +} + +.refcount { + color: #060; +} + +.optional { + font-size: 1.3em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + background-color:#F1F5F9; + border:1px solid #C9D1D7; + border-spacing:0; + font-family:"Bitstream Vera Sans Mono",Monaco,"Lucida Console",Courier,Consolas,monospace; + font-size:11px; + padding: 10px; +} + +td.linenos pre { + padding: 5px 0px; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +tt { + font-family:"Bitstream Vera Sans Mono",Monaco,"Lucida Console",Courier,Consolas,monospace; + +} + +tt.descname { + background-color: transparent; + font-weight: bold; + font-size: 1em; +} + +tt.descclassname { + background-color: transparent; +} + +tt.xref, a tt { + background-color: transparent; + font-weight: bold; +} + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + background-color: transparent; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} + +body { + font-family:'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; +} + +dl.class dt { + padding: 3px; +/* border-top: 2px solid #999;*/ +} + +em.property { + font-style: normal; +} + +dl.class dd p { + margin-top: 6px; +} + +dl.class dd dl.exception dt { + padding: 3px; + background-color: #FFD6D6; + border-top: none; +} + +dl.class dd dl.method dt { + padding: 3px; + background-color: #e9e9e9; + border-top: none; + +} + +dl.function dt { + padding: 3px; + border-top: 2px solid #999; +} + +ul { +list-style-image:none; +list-style-position:outside; +list-style-type:square; +margin:0 0 0 30px; +padding:0 0 12px 6px; +} +#docstitle { + height: 36px; + background-image: url(header_sm_mid.png); + left: 0; + top: 0; + position: absolute; + width: 100%; +} +#docstitle p { + padding:7px 0 0 45px; + margin: 0; + color: white; + text-shadow:0 1px 0 #787878; + background: transparent url(documentation.png) no-repeat scroll 10px 3px; + height: 36px; + font-size: 15px; +} +#header { +height:45px; +left:0; +position:absolute; +right:0; +top:36px; +z-index:900; +} + +#header h1 { +font-size:10pt; +margin:0; +padding:5px 0 0 10px; +text-shadow:0 1px 0 #D5D5D5; +white-space:nowrap; +} + +h1 { +-x-system-font:none; +color:#000000; +font-family:'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; +font-size:30px; +font-size-adjust:none; +font-stretch:normal; +font-style:normal; +font-variant:normal; +font-weight:bold; +line-height:normal; +margin-bottom:25px; +margin-top:1em; +} + +.footer { +border-top:1px solid #DDDDDD; +clear:both; +padding-top:9px; +width:100%; +font-size:10px; +} + +p { +-x-system-font:none; +font-family:'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; +font-size:12px; +font-size-adjust:none; +font-stretch:normal; +font-style:normal; +font-variant:normal; +font-weight:normal; +line-height:normal; +margin-bottom:10px; +margin-top:0; +} + +h2 { +border-bottom:1px solid #919699; +color:#000000; +font-size:24px; +margin-top:2.5em; +padding-bottom:2px; +} + +a:link:hover { +color:#093D92; +text-decoration:underline; +} + +a:link { +color:#093D92; +text-decoration:none; +} + + +ol { +list-style-position:outside; +list-style-type:decimal; +margin:0 0 0 30px; +padding:0 0 12px 6px; +} +li { +margin-top:7px; +font-family:'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; +font-size:12px; +font-size-adjust:none; +font-stretch:normal; +font-style:normal; +font-variant:normal; +font-weight:normal; +line-height:normal; +} +li p { +margin-top:8px; +} \ No newline at end of file diff --git a/python/mock-1.0.0/html/_static/basic.css b/python/mock-1.0.0/html/_static/basic.css new file mode 100644 index 000000000..43e8bafaf --- /dev/null +++ b/python/mock-1.0.0/html/_static/basic.css @@ -0,0 +1,540 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox input[type="text"] { + width: 170px; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + width: 30px; +} + +img { + border: 0; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable dl, table.indextable dd { + margin-top: 0; + margin-bottom: 0; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- general body styles --------------------------------------------------- */ + +a.headerlink { + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.field-list ul { + padding-left: 1em; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px 7px 0 7px; + background-color: #ffe; + width: 40%; + float: right; +} + +p.sidebar-title { + font-weight: bold; +} + +/* -- topics ---------------------------------------------------------------- */ + +div.topic { + border: 1px solid #ccc; + padding: 7px 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dl { + margin-bottom: 0; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + border: 0; + border-collapse: collapse; +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +table.field-list td, table.field-list th { + border: 0 !important; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +dl { + margin-bottom: 15px; +} + +dd p { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dt:target, .highlighted { + background-color: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.refcount { + color: #060; +} + +.optional { + font-size: 1.3em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +td.linenos pre { + padding: 5px 0px; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +tt.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; +} + +tt.descclassname { + background-color: transparent; +} + +tt.xref, a tt { + background-color: transparent; + font-weight: bold; +} + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/python/mock-1.0.0/html/_static/breadcrumb_background.png b/python/mock-1.0.0/html/_static/breadcrumb_background.png new file mode 100644 index 000000000..9b45910e0 Binary files /dev/null and b/python/mock-1.0.0/html/_static/breadcrumb_background.png differ diff --git a/python/mock-1.0.0/html/_static/default.css b/python/mock-1.0.0/html/_static/default.css new file mode 100644 index 000000000..2a3ac1331 --- /dev/null +++ b/python/mock-1.0.0/html/_static/default.css @@ -0,0 +1,256 @@ +/* + * default.css_t + * ~~~~~~~~~~~~~ + * + * Sphinx stylesheet -- default theme. + * + * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: sans-serif; + font-size: 100%; + background-color: #11303d; + color: #000; + margin: 0; + padding: 0; +} + +div.document { + background-color: #1c4e63; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 230px; +} + +div.body { + background-color: #ffffff; + color: #000000; + padding: 0 20px 30px 20px; +} + +div.footer { + color: #ffffff; + width: 100%; + padding: 9px 0 9px 0; + text-align: center; + font-size: 75%; +} + +div.footer a { + color: #ffffff; + text-decoration: underline; +} + +div.related { + background-color: #133f52; + line-height: 30px; + color: #ffffff; +} + +div.related a { + color: #ffffff; +} + +div.sphinxsidebar { +} + +div.sphinxsidebar h3 { + font-family: 'Trebuchet MS', sans-serif; + color: #ffffff; + font-size: 1.4em; + font-weight: normal; + margin: 0; + padding: 0; +} + +div.sphinxsidebar h3 a { + color: #ffffff; +} + +div.sphinxsidebar h4 { + font-family: 'Trebuchet MS', sans-serif; + color: #ffffff; + font-size: 1.3em; + font-weight: normal; + margin: 5px 0 0 0; + padding: 0; +} + +div.sphinxsidebar p { + color: #ffffff; +} + +div.sphinxsidebar p.topless { + margin: 5px 10px 10px 10px; +} + +div.sphinxsidebar ul { + margin: 10px; + padding: 0; + color: #ffffff; +} + +div.sphinxsidebar a { + color: #98dbcc; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + + + +/* -- hyperlink styles ------------------------------------------------------ */ + +a { + color: #355f7c; + text-decoration: none; +} + +a:visited { + color: #355f7c; + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + + + +/* -- body styles ----------------------------------------------------------- */ + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: 'Trebuchet MS', sans-serif; + background-color: #f2f2f2; + font-weight: normal; + color: #20435c; + border-bottom: 1px solid #ccc; + margin: 20px -20px 10px -20px; + padding: 3px 0 3px 10px; +} + +div.body h1 { margin-top: 0; font-size: 200%; } +div.body h2 { font-size: 160%; } +div.body h3 { font-size: 140%; } +div.body h4 { font-size: 120%; } +div.body h5 { font-size: 110%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: #c60f0f; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + background-color: #c60f0f; + color: white; +} + +div.body p, div.body dd, div.body li { + text-align: justify; + line-height: 130%; +} + +div.admonition p.admonition-title + p { + display: inline; +} + +div.admonition p { + margin-bottom: 5px; +} + +div.admonition pre { + margin-bottom: 5px; +} + +div.admonition ul, div.admonition ol { + margin-bottom: 5px; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre { + padding: 5px; + background-color: #eeffcc; + color: #333333; + line-height: 120%; + border: 1px solid #ac9; + border-left: none; + border-right: none; +} + +tt { + background-color: #ecf0f3; + padding: 0 1px 0 1px; + font-size: 0.95em; +} + +th { + background-color: #ede; +} + +.warning tt { + background: #efc2c2; +} + +.note tt { + background: #d6d6d6; +} + +.viewcode-back { + font-family: sans-serif; +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; +} \ No newline at end of file diff --git a/python/mock-1.0.0/html/_static/doctools.js b/python/mock-1.0.0/html/_static/doctools.js new file mode 100644 index 000000000..d4619fdfb --- /dev/null +++ b/python/mock-1.0.0/html/_static/doctools.js @@ -0,0 +1,247 @@ +/* + * doctools.js + * ~~~~~~~~~~~ + * + * Sphinx JavaScript utilities for all documentation. + * + * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/** + * select a different prefix for underscore + */ +$u = _.noConflict(); + +/** + * make the code below compatible with browsers without + * an installed firebug like debugger +if (!window.console || !console.firebug) { + var names = ["log", "debug", "info", "warn", "error", "assert", "dir", + "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace", + "profile", "profileEnd"]; + window.console = {}; + for (var i = 0; i < names.length; ++i) + window.console[names[i]] = function() {}; +} + */ + +/** + * small helper function to urldecode strings + */ +jQuery.urldecode = function(x) { + return decodeURIComponent(x).replace(/\+/g, ' '); +} + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s == 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +}; + +/** + * small function to check if an array contains + * a given item. + */ +jQuery.contains = function(arr, item) { + for (var i = 0; i < arr.length; i++) { + if (arr[i] == item) + return true; + } + return false; +}; + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node) { + if (node.nodeType == 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && !jQuery(node.parentNode).hasClass(className)) { + var span = document.createElement("span"); + span.className = className; + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this); + }); + } + } + return this.each(function() { + highlight(this); + }); +}; + +/** + * Small JavaScript module for the documentation. + */ +var Documentation = { + + init : function() { + this.fixFirefoxAnchorBug(); + this.highlightSearchWords(); + this.initIndexTable(); + }, + + /** + * i18n support + */ + TRANSLATIONS : {}, + PLURAL_EXPR : function(n) { return n == 1 ? 0 : 1; }, + LOCALE : 'unknown', + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext : function(string) { + var translated = Documentation.TRANSLATIONS[string]; + if (typeof translated == 'undefined') + return string; + return (typeof translated == 'string') ? translated : translated[0]; + }, + + ngettext : function(singular, plural, n) { + var translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated == 'undefined') + return (n == 1) ? singular : plural; + return translated[Documentation.PLURALEXPR(n)]; + }, + + addTranslations : function(catalog) { + for (var key in catalog.messages) + this.TRANSLATIONS[key] = catalog.messages[key]; + this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')'); + this.LOCALE = catalog.locale; + }, + + /** + * add context elements like header anchor links + */ + addContextElements : function() { + $('div[id] > :header:first').each(function() { + $('\u00B6'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this headline')). + appendTo(this); + }); + $('dt[id]').each(function() { + $('\u00B6'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this definition')). + appendTo(this); + }); + }, + + /** + * workaround a firefox stupidity + */ + fixFirefoxAnchorBug : function() { + if (document.location.hash && $.browser.mozilla) + window.setTimeout(function() { + document.location.href += ''; + }, 10); + }, + + /** + * highlight the search words provided in the url in the text + */ + highlightSearchWords : function() { + var params = $.getQueryParameters(); + var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : []; + if (terms.length) { + var body = $('div.body'); + window.setTimeout(function() { + $.each(terms, function() { + body.highlightText(this.toLowerCase(), 'highlighted'); + }); + }, 10); + $('

' + _('Hide Search Matches') + '

') + .appendTo($('#searchbox')); + } + }, + + /** + * init the domain index toggle buttons + */ + initIndexTable : function() { + var togglers = $('img.toggler').click(function() { + var src = $(this).attr('src'); + var idnum = $(this).attr('id').substr(7); + $('tr.cg-' + idnum).toggle(); + if (src.substr(-9) == 'minus.png') + $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); + else + $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); + }).css('display', ''); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) { + togglers.click(); + } + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords : function() { + $('#searchbox .highlight-link').fadeOut(300); + $('span.highlighted').removeClass('highlighted'); + }, + + /** + * make the url absolute + */ + makeURL : function(relativeURL) { + return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; + }, + + /** + * get the current relative url + */ + getCurrentURL : function() { + var path = document.location.pathname; + var parts = path.split(/\//); + $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { + if (this == '..') + parts.pop(); + }); + var url = parts.join('/'); + return path.substring(url.lastIndexOf('/') + 1, path.length - 1); + } +}; + +// quick alias for translations +_ = Documentation.gettext; + +$(document).ready(function() { + Documentation.init(); +}); diff --git a/python/mock-1.0.0/html/_static/documentation.png b/python/mock-1.0.0/html/_static/documentation.png new file mode 100644 index 000000000..f0d334b57 Binary files /dev/null and b/python/mock-1.0.0/html/_static/documentation.png differ diff --git a/python/mock-1.0.0/html/_static/file.png b/python/mock-1.0.0/html/_static/file.png new file mode 100644 index 000000000..d18082e39 Binary files /dev/null and b/python/mock-1.0.0/html/_static/file.png differ diff --git a/python/mock-1.0.0/html/_static/header_sm_mid.png b/python/mock-1.0.0/html/_static/header_sm_mid.png new file mode 100644 index 000000000..dce5a40e9 Binary files /dev/null and b/python/mock-1.0.0/html/_static/header_sm_mid.png differ diff --git a/python/mock-1.0.0/html/_static/jquery.js b/python/mock-1.0.0/html/_static/jquery.js new file mode 100644 index 000000000..7c2430802 --- /dev/null +++ b/python/mock-1.0.0/html/_static/jquery.js @@ -0,0 +1,154 @@ +/*! + * jQuery JavaScript Library v1.4.2 + * http://jquery.com/ + * + * Copyright 2010, John Resig + * Dual licensed under the MIT or GPL Version 2 licenses. + * http://jquery.org/license + * + * Includes Sizzle.js + * http://sizzlejs.com/ + * Copyright 2010, The Dojo Foundation + * Released under the MIT, BSD, and GPL Licenses. + * + * Date: Sat Feb 13 22:33:48 2010 -0500 + */ +(function(A,w){function ma(){if(!c.isReady){try{s.documentElement.doScroll("left")}catch(a){setTimeout(ma,1);return}c.ready()}}function Qa(a,b){b.src?c.ajax({url:b.src,async:false,dataType:"script"}):c.globalEval(b.text||b.textContent||b.innerHTML||"");b.parentNode&&b.parentNode.removeChild(b)}function X(a,b,d,f,e,j){var i=a.length;if(typeof b==="object"){for(var o in b)X(a,o,b[o],f,e,d);return a}if(d!==w){f=!j&&f&&c.isFunction(d);for(o=0;o)[^>]*$|^#([\w-]+)$/,Ua=/^.[^:#\[\.,]*$/,Va=/\S/, +Wa=/^(\s|\u00A0)+|(\s|\u00A0)+$/g,Xa=/^<(\w+)\s*\/?>(?:<\/\1>)?$/,P=navigator.userAgent,xa=false,Q=[],L,$=Object.prototype.toString,aa=Object.prototype.hasOwnProperty,ba=Array.prototype.push,R=Array.prototype.slice,ya=Array.prototype.indexOf;c.fn=c.prototype={init:function(a,b){var d,f;if(!a)return this;if(a.nodeType){this.context=this[0]=a;this.length=1;return this}if(a==="body"&&!b){this.context=s;this[0]=s.body;this.selector="body";this.length=1;return this}if(typeof a==="string")if((d=Ta.exec(a))&& +(d[1]||!b))if(d[1]){f=b?b.ownerDocument||b:s;if(a=Xa.exec(a))if(c.isPlainObject(b)){a=[s.createElement(a[1])];c.fn.attr.call(a,b,true)}else a=[f.createElement(a[1])];else{a=sa([d[1]],[f]);a=(a.cacheable?a.fragment.cloneNode(true):a.fragment).childNodes}return c.merge(this,a)}else{if(b=s.getElementById(d[2])){if(b.id!==d[2])return T.find(a);this.length=1;this[0]=b}this.context=s;this.selector=a;return this}else if(!b&&/^\w+$/.test(a)){this.selector=a;this.context=s;a=s.getElementsByTagName(a);return c.merge(this, +a)}else return!b||b.jquery?(b||T).find(a):c(b).find(a);else if(c.isFunction(a))return T.ready(a);if(a.selector!==w){this.selector=a.selector;this.context=a.context}return c.makeArray(a,this)},selector:"",jquery:"1.4.2",length:0,size:function(){return this.length},toArray:function(){return R.call(this,0)},get:function(a){return a==null?this.toArray():a<0?this.slice(a)[0]:this[a]},pushStack:function(a,b,d){var f=c();c.isArray(a)?ba.apply(f,a):c.merge(f,a);f.prevObject=this;f.context=this.context;if(b=== +"find")f.selector=this.selector+(this.selector?" ":"")+d;else if(b)f.selector=this.selector+"."+b+"("+d+")";return f},each:function(a,b){return c.each(this,a,b)},ready:function(a){c.bindReady();if(c.isReady)a.call(s,c);else Q&&Q.push(a);return this},eq:function(a){return a===-1?this.slice(a):this.slice(a,+a+1)},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},slice:function(){return this.pushStack(R.apply(this,arguments),"slice",R.call(arguments).join(","))},map:function(a){return this.pushStack(c.map(this, +function(b,d){return a.call(b,d,b)}))},end:function(){return this.prevObject||c(null)},push:ba,sort:[].sort,splice:[].splice};c.fn.init.prototype=c.fn;c.extend=c.fn.extend=function(){var a=arguments[0]||{},b=1,d=arguments.length,f=false,e,j,i,o;if(typeof a==="boolean"){f=a;a=arguments[1]||{};b=2}if(typeof a!=="object"&&!c.isFunction(a))a={};if(d===b){a=this;--b}for(;b
a"; +var e=d.getElementsByTagName("*"),j=d.getElementsByTagName("a")[0];if(!(!e||!e.length||!j)){c.support={leadingWhitespace:d.firstChild.nodeType===3,tbody:!d.getElementsByTagName("tbody").length,htmlSerialize:!!d.getElementsByTagName("link").length,style:/red/.test(j.getAttribute("style")),hrefNormalized:j.getAttribute("href")==="/a",opacity:/^0.55$/.test(j.style.opacity),cssFloat:!!j.style.cssFloat,checkOn:d.getElementsByTagName("input")[0].value==="on",optSelected:s.createElement("select").appendChild(s.createElement("option")).selected, +parentNode:d.removeChild(d.appendChild(s.createElement("div"))).parentNode===null,deleteExpando:true,checkClone:false,scriptEval:false,noCloneEvent:true,boxModel:null};b.type="text/javascript";try{b.appendChild(s.createTextNode("window."+f+"=1;"))}catch(i){}a.insertBefore(b,a.firstChild);if(A[f]){c.support.scriptEval=true;delete A[f]}try{delete b.test}catch(o){c.support.deleteExpando=false}a.removeChild(b);if(d.attachEvent&&d.fireEvent){d.attachEvent("onclick",function k(){c.support.noCloneEvent= +false;d.detachEvent("onclick",k)});d.cloneNode(true).fireEvent("onclick")}d=s.createElement("div");d.innerHTML="";a=s.createDocumentFragment();a.appendChild(d.firstChild);c.support.checkClone=a.cloneNode(true).cloneNode(true).lastChild.checked;c(function(){var k=s.createElement("div");k.style.width=k.style.paddingLeft="1px";s.body.appendChild(k);c.boxModel=c.support.boxModel=k.offsetWidth===2;s.body.removeChild(k).style.display="none"});a=function(k){var n= +s.createElement("div");k="on"+k;var r=k in n;if(!r){n.setAttribute(k,"return;");r=typeof n[k]==="function"}return r};c.support.submitBubbles=a("submit");c.support.changeBubbles=a("change");a=b=d=e=j=null}})();c.props={"for":"htmlFor","class":"className",readonly:"readOnly",maxlength:"maxLength",cellspacing:"cellSpacing",rowspan:"rowSpan",colspan:"colSpan",tabindex:"tabIndex",usemap:"useMap",frameborder:"frameBorder"};var G="jQuery"+J(),Ya=0,za={};c.extend({cache:{},expando:G,noData:{embed:true,object:true, +applet:true},data:function(a,b,d){if(!(a.nodeName&&c.noData[a.nodeName.toLowerCase()])){a=a==A?za:a;var f=a[G],e=c.cache;if(!f&&typeof b==="string"&&d===w)return null;f||(f=++Ya);if(typeof b==="object"){a[G]=f;e[f]=c.extend(true,{},b)}else if(!e[f]){a[G]=f;e[f]={}}a=e[f];if(d!==w)a[b]=d;return typeof b==="string"?a[b]:a}},removeData:function(a,b){if(!(a.nodeName&&c.noData[a.nodeName.toLowerCase()])){a=a==A?za:a;var d=a[G],f=c.cache,e=f[d];if(b){if(e){delete e[b];c.isEmptyObject(e)&&c.removeData(a)}}else{if(c.support.deleteExpando)delete a[c.expando]; +else a.removeAttribute&&a.removeAttribute(c.expando);delete f[d]}}}});c.fn.extend({data:function(a,b){if(typeof a==="undefined"&&this.length)return c.data(this[0]);else if(typeof a==="object")return this.each(function(){c.data(this,a)});var d=a.split(".");d[1]=d[1]?"."+d[1]:"";if(b===w){var f=this.triggerHandler("getData"+d[1]+"!",[d[0]]);if(f===w&&this.length)f=c.data(this[0],a);return f===w&&d[1]?this.data(d[0]):f}else return this.trigger("setData"+d[1]+"!",[d[0],b]).each(function(){c.data(this, +a,b)})},removeData:function(a){return this.each(function(){c.removeData(this,a)})}});c.extend({queue:function(a,b,d){if(a){b=(b||"fx")+"queue";var f=c.data(a,b);if(!d)return f||[];if(!f||c.isArray(d))f=c.data(a,b,c.makeArray(d));else f.push(d);return f}},dequeue:function(a,b){b=b||"fx";var d=c.queue(a,b),f=d.shift();if(f==="inprogress")f=d.shift();if(f){b==="fx"&&d.unshift("inprogress");f.call(a,function(){c.dequeue(a,b)})}}});c.fn.extend({queue:function(a,b){if(typeof a!=="string"){b=a;a="fx"}if(b=== +w)return c.queue(this[0],a);return this.each(function(){var d=c.queue(this,a,b);a==="fx"&&d[0]!=="inprogress"&&c.dequeue(this,a)})},dequeue:function(a){return this.each(function(){c.dequeue(this,a)})},delay:function(a,b){a=c.fx?c.fx.speeds[a]||a:a;b=b||"fx";return this.queue(b,function(){var d=this;setTimeout(function(){c.dequeue(d,b)},a)})},clearQueue:function(a){return this.queue(a||"fx",[])}});var Aa=/[\n\t]/g,ca=/\s+/,Za=/\r/g,$a=/href|src|style/,ab=/(button|input)/i,bb=/(button|input|object|select|textarea)/i, +cb=/^(a|area)$/i,Ba=/radio|checkbox/;c.fn.extend({attr:function(a,b){return X(this,a,b,true,c.attr)},removeAttr:function(a){return this.each(function(){c.attr(this,a,"");this.nodeType===1&&this.removeAttribute(a)})},addClass:function(a){if(c.isFunction(a))return this.each(function(n){var r=c(this);r.addClass(a.call(this,n,r.attr("class")))});if(a&&typeof a==="string")for(var b=(a||"").split(ca),d=0,f=this.length;d-1)return true;return false},val:function(a){if(a===w){var b=this[0];if(b){if(c.nodeName(b,"option"))return(b.attributes.value||{}).specified?b.value:b.text;if(c.nodeName(b,"select")){var d=b.selectedIndex,f=[],e=b.options;b=b.type==="select-one";if(d<0)return null;var j=b?d:0;for(d=b?d+1:e.length;j=0;else if(c.nodeName(this,"select")){var u=c.makeArray(r);c("option",this).each(function(){this.selected= +c.inArray(c(this).val(),u)>=0});if(!u.length)this.selectedIndex=-1}else this.value=r}})}});c.extend({attrFn:{val:true,css:true,html:true,text:true,data:true,width:true,height:true,offset:true},attr:function(a,b,d,f){if(!a||a.nodeType===3||a.nodeType===8)return w;if(f&&b in c.attrFn)return c(a)[b](d);f=a.nodeType!==1||!c.isXMLDoc(a);var e=d!==w;b=f&&c.props[b]||b;if(a.nodeType===1){var j=$a.test(b);if(b in a&&f&&!j){if(e){b==="type"&&ab.test(a.nodeName)&&a.parentNode&&c.error("type property can't be changed"); +a[b]=d}if(c.nodeName(a,"form")&&a.getAttributeNode(b))return a.getAttributeNode(b).nodeValue;if(b==="tabIndex")return(b=a.getAttributeNode("tabIndex"))&&b.specified?b.value:bb.test(a.nodeName)||cb.test(a.nodeName)&&a.href?0:w;return a[b]}if(!c.support.style&&f&&b==="style"){if(e)a.style.cssText=""+d;return a.style.cssText}e&&a.setAttribute(b,""+d);a=!c.support.hrefNormalized&&f&&j?a.getAttribute(b,2):a.getAttribute(b);return a===null?w:a}return c.style(a,b,d)}});var O=/\.(.*)$/,db=function(a){return a.replace(/[^\w\s\.\|`]/g, +function(b){return"\\"+b})};c.event={add:function(a,b,d,f){if(!(a.nodeType===3||a.nodeType===8)){if(a.setInterval&&a!==A&&!a.frameElement)a=A;var e,j;if(d.handler){e=d;d=e.handler}if(!d.guid)d.guid=c.guid++;if(j=c.data(a)){var i=j.events=j.events||{},o=j.handle;if(!o)j.handle=o=function(){return typeof c!=="undefined"&&!c.event.triggered?c.event.handle.apply(o.elem,arguments):w};o.elem=a;b=b.split(" ");for(var k,n=0,r;k=b[n++];){j=e?c.extend({},e):{handler:d,data:f};if(k.indexOf(".")>-1){r=k.split("."); +k=r.shift();j.namespace=r.slice(0).sort().join(".")}else{r=[];j.namespace=""}j.type=k;j.guid=d.guid;var u=i[k],z=c.event.special[k]||{};if(!u){u=i[k]=[];if(!z.setup||z.setup.call(a,f,r,o)===false)if(a.addEventListener)a.addEventListener(k,o,false);else a.attachEvent&&a.attachEvent("on"+k,o)}if(z.add){z.add.call(a,j);if(!j.handler.guid)j.handler.guid=d.guid}u.push(j);c.event.global[k]=true}a=null}}},global:{},remove:function(a,b,d,f){if(!(a.nodeType===3||a.nodeType===8)){var e,j=0,i,o,k,n,r,u,z=c.data(a), +C=z&&z.events;if(z&&C){if(b&&b.type){d=b.handler;b=b.type}if(!b||typeof b==="string"&&b.charAt(0)==="."){b=b||"";for(e in C)c.event.remove(a,e+b)}else{for(b=b.split(" ");e=b[j++];){n=e;i=e.indexOf(".")<0;o=[];if(!i){o=e.split(".");e=o.shift();k=new RegExp("(^|\\.)"+c.map(o.slice(0).sort(),db).join("\\.(?:.*\\.)?")+"(\\.|$)")}if(r=C[e])if(d){n=c.event.special[e]||{};for(B=f||0;B=0){a.type= +e=e.slice(0,-1);a.exclusive=true}if(!d){a.stopPropagation();c.event.global[e]&&c.each(c.cache,function(){this.events&&this.events[e]&&c.event.trigger(a,b,this.handle.elem)})}if(!d||d.nodeType===3||d.nodeType===8)return w;a.result=w;a.target=d;b=c.makeArray(b);b.unshift(a)}a.currentTarget=d;(f=c.data(d,"handle"))&&f.apply(d,b);f=d.parentNode||d.ownerDocument;try{if(!(d&&d.nodeName&&c.noData[d.nodeName.toLowerCase()]))if(d["on"+e]&&d["on"+e].apply(d,b)===false)a.result=false}catch(j){}if(!a.isPropagationStopped()&& +f)c.event.trigger(a,b,f,true);else if(!a.isDefaultPrevented()){f=a.target;var i,o=c.nodeName(f,"a")&&e==="click",k=c.event.special[e]||{};if((!k._default||k._default.call(d,a)===false)&&!o&&!(f&&f.nodeName&&c.noData[f.nodeName.toLowerCase()])){try{if(f[e]){if(i=f["on"+e])f["on"+e]=null;c.event.triggered=true;f[e]()}}catch(n){}if(i)f["on"+e]=i;c.event.triggered=false}}},handle:function(a){var b,d,f,e;a=arguments[0]=c.event.fix(a||A.event);a.currentTarget=this;b=a.type.indexOf(".")<0&&!a.exclusive; +if(!b){d=a.type.split(".");a.type=d.shift();f=new RegExp("(^|\\.)"+d.slice(0).sort().join("\\.(?:.*\\.)?")+"(\\.|$)")}e=c.data(this,"events");d=e[a.type];if(e&&d){d=d.slice(0);e=0;for(var j=d.length;e-1?c.map(a.options,function(f){return f.selected}).join("-"):"";else if(a.nodeName.toLowerCase()==="select")d=a.selectedIndex;return d},fa=function(a,b){var d=a.target,f,e;if(!(!da.test(d.nodeName)||d.readOnly)){f=c.data(d,"_change_data");e=Fa(d);if(a.type!=="focusout"||d.type!=="radio")c.data(d,"_change_data", +e);if(!(f===w||e===f))if(f!=null||e){a.type="change";return c.event.trigger(a,b,d)}}};c.event.special.change={filters:{focusout:fa,click:function(a){var b=a.target,d=b.type;if(d==="radio"||d==="checkbox"||b.nodeName.toLowerCase()==="select")return fa.call(this,a)},keydown:function(a){var b=a.target,d=b.type;if(a.keyCode===13&&b.nodeName.toLowerCase()!=="textarea"||a.keyCode===32&&(d==="checkbox"||d==="radio")||d==="select-multiple")return fa.call(this,a)},beforeactivate:function(a){a=a.target;c.data(a, +"_change_data",Fa(a))}},setup:function(){if(this.type==="file")return false;for(var a in ea)c.event.add(this,a+".specialChange",ea[a]);return da.test(this.nodeName)},teardown:function(){c.event.remove(this,".specialChange");return da.test(this.nodeName)}};ea=c.event.special.change.filters}s.addEventListener&&c.each({focus:"focusin",blur:"focusout"},function(a,b){function d(f){f=c.event.fix(f);f.type=b;return c.event.handle.call(this,f)}c.event.special[b]={setup:function(){this.addEventListener(a, +d,true)},teardown:function(){this.removeEventListener(a,d,true)}}});c.each(["bind","one"],function(a,b){c.fn[b]=function(d,f,e){if(typeof d==="object"){for(var j in d)this[b](j,f,d[j],e);return this}if(c.isFunction(f)){e=f;f=w}var i=b==="one"?c.proxy(e,function(k){c(this).unbind(k,i);return e.apply(this,arguments)}):e;if(d==="unload"&&b!=="one")this.one(d,f,e);else{j=0;for(var o=this.length;j0){y=t;break}}t=t[g]}m[q]=y}}}var f=/((?:\((?:\([^()]+\)|[^()]+)+\)|\[(?:\[[^[\]]*\]|['"][^'"]*['"]|[^[\]'"]+)+\]|\\.|[^ >+~,(\[\\]+)+|[>+~])(\s*,\s*)?((?:.|\r|\n)*)/g, +e=0,j=Object.prototype.toString,i=false,o=true;[0,0].sort(function(){o=false;return 0});var k=function(g,h,l,m){l=l||[];var q=h=h||s;if(h.nodeType!==1&&h.nodeType!==9)return[];if(!g||typeof g!=="string")return l;for(var p=[],v,t,y,S,H=true,M=x(h),I=g;(f.exec(""),v=f.exec(I))!==null;){I=v[3];p.push(v[1]);if(v[2]){S=v[3];break}}if(p.length>1&&r.exec(g))if(p.length===2&&n.relative[p[0]])t=ga(p[0]+p[1],h);else for(t=n.relative[p[0]]?[h]:k(p.shift(),h);p.length;){g=p.shift();if(n.relative[g])g+=p.shift(); +t=ga(g,t)}else{if(!m&&p.length>1&&h.nodeType===9&&!M&&n.match.ID.test(p[0])&&!n.match.ID.test(p[p.length-1])){v=k.find(p.shift(),h,M);h=v.expr?k.filter(v.expr,v.set)[0]:v.set[0]}if(h){v=m?{expr:p.pop(),set:z(m)}:k.find(p.pop(),p.length===1&&(p[0]==="~"||p[0]==="+")&&h.parentNode?h.parentNode:h,M);t=v.expr?k.filter(v.expr,v.set):v.set;if(p.length>0)y=z(t);else H=false;for(;p.length;){var D=p.pop();v=D;if(n.relative[D])v=p.pop();else D="";if(v==null)v=h;n.relative[D](y,v,M)}}else y=[]}y||(y=t);y||k.error(D|| +g);if(j.call(y)==="[object Array]")if(H)if(h&&h.nodeType===1)for(g=0;y[g]!=null;g++){if(y[g]&&(y[g]===true||y[g].nodeType===1&&E(h,y[g])))l.push(t[g])}else for(g=0;y[g]!=null;g++)y[g]&&y[g].nodeType===1&&l.push(t[g]);else l.push.apply(l,y);else z(y,l);if(S){k(S,q,l,m);k.uniqueSort(l)}return l};k.uniqueSort=function(g){if(B){i=o;g.sort(B);if(i)for(var h=1;h":function(g,h){var l=typeof h==="string";if(l&&!/\W/.test(h)){h=h.toLowerCase();for(var m=0,q=g.length;m=0))l||m.push(v);else if(l)h[p]=false;return false},ID:function(g){return g[1].replace(/\\/g,"")},TAG:function(g){return g[1].toLowerCase()}, +CHILD:function(g){if(g[1]==="nth"){var h=/(-?)(\d*)n((?:\+|-)?\d*)/.exec(g[2]==="even"&&"2n"||g[2]==="odd"&&"2n+1"||!/\D/.test(g[2])&&"0n+"+g[2]||g[2]);g[2]=h[1]+(h[2]||1)-0;g[3]=h[3]-0}g[0]=e++;return g},ATTR:function(g,h,l,m,q,p){h=g[1].replace(/\\/g,"");if(!p&&n.attrMap[h])g[1]=n.attrMap[h];if(g[2]==="~=")g[4]=" "+g[4]+" ";return g},PSEUDO:function(g,h,l,m,q){if(g[1]==="not")if((f.exec(g[3])||"").length>1||/^\w/.test(g[3]))g[3]=k(g[3],null,null,h);else{g=k.filter(g[3],h,l,true^q);l||m.push.apply(m, +g);return false}else if(n.match.POS.test(g[0])||n.match.CHILD.test(g[0]))return true;return g},POS:function(g){g.unshift(true);return g}},filters:{enabled:function(g){return g.disabled===false&&g.type!=="hidden"},disabled:function(g){return g.disabled===true},checked:function(g){return g.checked===true},selected:function(g){return g.selected===true},parent:function(g){return!!g.firstChild},empty:function(g){return!g.firstChild},has:function(g,h,l){return!!k(l[3],g).length},header:function(g){return/h\d/i.test(g.nodeName)}, +text:function(g){return"text"===g.type},radio:function(g){return"radio"===g.type},checkbox:function(g){return"checkbox"===g.type},file:function(g){return"file"===g.type},password:function(g){return"password"===g.type},submit:function(g){return"submit"===g.type},image:function(g){return"image"===g.type},reset:function(g){return"reset"===g.type},button:function(g){return"button"===g.type||g.nodeName.toLowerCase()==="button"},input:function(g){return/input|select|textarea|button/i.test(g.nodeName)}}, +setFilters:{first:function(g,h){return h===0},last:function(g,h,l,m){return h===m.length-1},even:function(g,h){return h%2===0},odd:function(g,h){return h%2===1},lt:function(g,h,l){return hl[3]-0},nth:function(g,h,l){return l[3]-0===h},eq:function(g,h,l){return l[3]-0===h}},filter:{PSEUDO:function(g,h,l,m){var q=h[1],p=n.filters[q];if(p)return p(g,l,h,m);else if(q==="contains")return(g.textContent||g.innerText||a([g])||"").indexOf(h[3])>=0;else if(q==="not"){h= +h[3];l=0;for(m=h.length;l=0}},ID:function(g,h){return g.nodeType===1&&g.getAttribute("id")===h},TAG:function(g,h){return h==="*"&&g.nodeType===1||g.nodeName.toLowerCase()===h},CLASS:function(g,h){return(" "+(g.className||g.getAttribute("class"))+" ").indexOf(h)>-1},ATTR:function(g,h){var l=h[1];g=n.attrHandle[l]?n.attrHandle[l](g):g[l]!=null?g[l]:g.getAttribute(l);l=g+"";var m=h[2];h=h[4];return g==null?m==="!=":m=== +"="?l===h:m==="*="?l.indexOf(h)>=0:m==="~="?(" "+l+" ").indexOf(h)>=0:!h?l&&g!==false:m==="!="?l!==h:m==="^="?l.indexOf(h)===0:m==="$="?l.substr(l.length-h.length)===h:m==="|="?l===h||l.substr(0,h.length+1)===h+"-":false},POS:function(g,h,l,m){var q=n.setFilters[h[2]];if(q)return q(g,l,h,m)}}},r=n.match.POS;for(var u in n.match){n.match[u]=new RegExp(n.match[u].source+/(?![^\[]*\])(?![^\(]*\))/.source);n.leftMatch[u]=new RegExp(/(^(?:.|\r|\n)*?)/.source+n.match[u].source.replace(/\\(\d+)/g,function(g, +h){return"\\"+(h-0+1)}))}var z=function(g,h){g=Array.prototype.slice.call(g,0);if(h){h.push.apply(h,g);return h}return g};try{Array.prototype.slice.call(s.documentElement.childNodes,0)}catch(C){z=function(g,h){h=h||[];if(j.call(g)==="[object Array]")Array.prototype.push.apply(h,g);else if(typeof g.length==="number")for(var l=0,m=g.length;l";var l=s.documentElement;l.insertBefore(g,l.firstChild);if(s.getElementById(h)){n.find.ID=function(m,q,p){if(typeof q.getElementById!=="undefined"&&!p)return(q=q.getElementById(m[1]))?q.id===m[1]||typeof q.getAttributeNode!=="undefined"&& +q.getAttributeNode("id").nodeValue===m[1]?[q]:w:[]};n.filter.ID=function(m,q){var p=typeof m.getAttributeNode!=="undefined"&&m.getAttributeNode("id");return m.nodeType===1&&p&&p.nodeValue===q}}l.removeChild(g);l=g=null})();(function(){var g=s.createElement("div");g.appendChild(s.createComment(""));if(g.getElementsByTagName("*").length>0)n.find.TAG=function(h,l){l=l.getElementsByTagName(h[1]);if(h[1]==="*"){h=[];for(var m=0;l[m];m++)l[m].nodeType===1&&h.push(l[m]);l=h}return l};g.innerHTML=""; +if(g.firstChild&&typeof g.firstChild.getAttribute!=="undefined"&&g.firstChild.getAttribute("href")!=="#")n.attrHandle.href=function(h){return h.getAttribute("href",2)};g=null})();s.querySelectorAll&&function(){var g=k,h=s.createElement("div");h.innerHTML="

";if(!(h.querySelectorAll&&h.querySelectorAll(".TEST").length===0)){k=function(m,q,p,v){q=q||s;if(!v&&q.nodeType===9&&!x(q))try{return z(q.querySelectorAll(m),p)}catch(t){}return g(m,q,p,v)};for(var l in g)k[l]=g[l];h=null}}(); +(function(){var g=s.createElement("div");g.innerHTML="
";if(!(!g.getElementsByClassName||g.getElementsByClassName("e").length===0)){g.lastChild.className="e";if(g.getElementsByClassName("e").length!==1){n.order.splice(1,0,"CLASS");n.find.CLASS=function(h,l,m){if(typeof l.getElementsByClassName!=="undefined"&&!m)return l.getElementsByClassName(h[1])};g=null}}})();var E=s.compareDocumentPosition?function(g,h){return!!(g.compareDocumentPosition(h)&16)}: +function(g,h){return g!==h&&(g.contains?g.contains(h):true)},x=function(g){return(g=(g?g.ownerDocument||g:0).documentElement)?g.nodeName!=="HTML":false},ga=function(g,h){var l=[],m="",q;for(h=h.nodeType?[h]:h;q=n.match.PSEUDO.exec(g);){m+=q[0];g=g.replace(n.match.PSEUDO,"")}g=n.relative[g]?g+"*":g;q=0;for(var p=h.length;q=0===d})};c.fn.extend({find:function(a){for(var b=this.pushStack("","find",a),d=0,f=0,e=this.length;f0)for(var j=d;j0},closest:function(a,b){if(c.isArray(a)){var d=[],f=this[0],e,j= +{},i;if(f&&a.length){e=0;for(var o=a.length;e-1:c(f).is(e)){d.push({selector:i,elem:f});delete j[i]}}f=f.parentNode}}return d}var k=c.expr.match.POS.test(a)?c(a,b||this.context):null;return this.map(function(n,r){for(;r&&r.ownerDocument&&r!==b;){if(k?k.index(r)>-1:c(r).is(a))return r;r=r.parentNode}return null})},index:function(a){if(!a||typeof a=== +"string")return c.inArray(this[0],a?c(a):this.parent().children());return c.inArray(a.jquery?a[0]:a,this)},add:function(a,b){a=typeof a==="string"?c(a,b||this.context):c.makeArray(a);b=c.merge(this.get(),a);return this.pushStack(qa(a[0])||qa(b[0])?b:c.unique(b))},andSelf:function(){return this.add(this.prevObject)}});c.each({parent:function(a){return(a=a.parentNode)&&a.nodeType!==11?a:null},parents:function(a){return c.dir(a,"parentNode")},parentsUntil:function(a,b,d){return c.dir(a,"parentNode", +d)},next:function(a){return c.nth(a,2,"nextSibling")},prev:function(a){return c.nth(a,2,"previousSibling")},nextAll:function(a){return c.dir(a,"nextSibling")},prevAll:function(a){return c.dir(a,"previousSibling")},nextUntil:function(a,b,d){return c.dir(a,"nextSibling",d)},prevUntil:function(a,b,d){return c.dir(a,"previousSibling",d)},siblings:function(a){return c.sibling(a.parentNode.firstChild,a)},children:function(a){return c.sibling(a.firstChild)},contents:function(a){return c.nodeName(a,"iframe")? +a.contentDocument||a.contentWindow.document:c.makeArray(a.childNodes)}},function(a,b){c.fn[a]=function(d,f){var e=c.map(this,b,d);eb.test(a)||(f=d);if(f&&typeof f==="string")e=c.filter(f,e);e=this.length>1?c.unique(e):e;if((this.length>1||gb.test(f))&&fb.test(a))e=e.reverse();return this.pushStack(e,a,R.call(arguments).join(","))}});c.extend({filter:function(a,b,d){if(d)a=":not("+a+")";return c.find.matches(a,b)},dir:function(a,b,d){var f=[];for(a=a[b];a&&a.nodeType!==9&&(d===w||a.nodeType!==1||!c(a).is(d));){a.nodeType=== +1&&f.push(a);a=a[b]}return f},nth:function(a,b,d){b=b||1;for(var f=0;a;a=a[d])if(a.nodeType===1&&++f===b)break;return a},sibling:function(a,b){for(var d=[];a;a=a.nextSibling)a.nodeType===1&&a!==b&&d.push(a);return d}});var Ja=/ jQuery\d+="(?:\d+|null)"/g,V=/^\s+/,Ka=/(<([\w:]+)[^>]*?)\/>/g,hb=/^(?:area|br|col|embed|hr|img|input|link|meta|param)$/i,La=/<([\w:]+)/,ib=/"},F={option:[1,""],legend:[1,"
","
"],thead:[1,"","
"],tr:[2,"","
"],td:[3,"","
"],col:[2,"","
"],area:[1,"",""],_default:[0,"",""]};F.optgroup=F.option;F.tbody=F.tfoot=F.colgroup=F.caption=F.thead;F.th=F.td;if(!c.support.htmlSerialize)F._default=[1,"div
","
"];c.fn.extend({text:function(a){if(c.isFunction(a))return this.each(function(b){var d= +c(this);d.text(a.call(this,b,d.text()))});if(typeof a!=="object"&&a!==w)return this.empty().append((this[0]&&this[0].ownerDocument||s).createTextNode(a));return c.text(this)},wrapAll:function(a){if(c.isFunction(a))return this.each(function(d){c(this).wrapAll(a.call(this,d))});if(this[0]){var b=c(a,this[0].ownerDocument).eq(0).clone(true);this[0].parentNode&&b.insertBefore(this[0]);b.map(function(){for(var d=this;d.firstChild&&d.firstChild.nodeType===1;)d=d.firstChild;return d}).append(this)}return this}, +wrapInner:function(a){if(c.isFunction(a))return this.each(function(b){c(this).wrapInner(a.call(this,b))});return this.each(function(){var b=c(this),d=b.contents();d.length?d.wrapAll(a):b.append(a)})},wrap:function(a){return this.each(function(){c(this).wrapAll(a)})},unwrap:function(){return this.parent().each(function(){c.nodeName(this,"body")||c(this).replaceWith(this.childNodes)}).end()},append:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.appendChild(a)})}, +prepend:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.insertBefore(a,this.firstChild)})},before:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,false,function(b){this.parentNode.insertBefore(b,this)});else if(arguments.length){var a=c(arguments[0]);a.push.apply(a,this.toArray());return this.pushStack(a,"before",arguments)}},after:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,false,function(b){this.parentNode.insertBefore(b, +this.nextSibling)});else if(arguments.length){var a=this.pushStack(this,"after",arguments);a.push.apply(a,c(arguments[0]).toArray());return a}},remove:function(a,b){for(var d=0,f;(f=this[d])!=null;d++)if(!a||c.filter(a,[f]).length){if(!b&&f.nodeType===1){c.cleanData(f.getElementsByTagName("*"));c.cleanData([f])}f.parentNode&&f.parentNode.removeChild(f)}return this},empty:function(){for(var a=0,b;(b=this[a])!=null;a++)for(b.nodeType===1&&c.cleanData(b.getElementsByTagName("*"));b.firstChild;)b.removeChild(b.firstChild); +return this},clone:function(a){var b=this.map(function(){if(!c.support.noCloneEvent&&!c.isXMLDoc(this)){var d=this.outerHTML,f=this.ownerDocument;if(!d){d=f.createElement("div");d.appendChild(this.cloneNode(true));d=d.innerHTML}return c.clean([d.replace(Ja,"").replace(/=([^="'>\s]+\/)>/g,'="$1">').replace(V,"")],f)[0]}else return this.cloneNode(true)});if(a===true){ra(this,b);ra(this.find("*"),b.find("*"))}return b},html:function(a){if(a===w)return this[0]&&this[0].nodeType===1?this[0].innerHTML.replace(Ja, +""):null;else if(typeof a==="string"&&!ta.test(a)&&(c.support.leadingWhitespace||!V.test(a))&&!F[(La.exec(a)||["",""])[1].toLowerCase()]){a=a.replace(Ka,Ma);try{for(var b=0,d=this.length;b0||e.cacheable||this.length>1?k.cloneNode(true):k)}o.length&&c.each(o,Qa)}return this}});c.fragments={};c.each({appendTo:"append",prependTo:"prepend",insertBefore:"before",insertAfter:"after",replaceAll:"replaceWith"},function(a,b){c.fn[a]=function(d){var f=[];d=c(d);var e=this.length===1&&this[0].parentNode;if(e&&e.nodeType===11&&e.childNodes.length===1&&d.length===1){d[b](this[0]); +return this}else{e=0;for(var j=d.length;e0?this.clone(true):this).get();c.fn[b].apply(c(d[e]),i);f=f.concat(i)}return this.pushStack(f,a,d.selector)}}});c.extend({clean:function(a,b,d,f){b=b||s;if(typeof b.createElement==="undefined")b=b.ownerDocument||b[0]&&b[0].ownerDocument||s;for(var e=[],j=0,i;(i=a[j])!=null;j++){if(typeof i==="number")i+="";if(i){if(typeof i==="string"&&!jb.test(i))i=b.createTextNode(i);else if(typeof i==="string"){i=i.replace(Ka,Ma);var o=(La.exec(i)||["", +""])[1].toLowerCase(),k=F[o]||F._default,n=k[0],r=b.createElement("div");for(r.innerHTML=k[1]+i+k[2];n--;)r=r.lastChild;if(!c.support.tbody){n=ib.test(i);o=o==="table"&&!n?r.firstChild&&r.firstChild.childNodes:k[1]===""&&!n?r.childNodes:[];for(k=o.length-1;k>=0;--k)c.nodeName(o[k],"tbody")&&!o[k].childNodes.length&&o[k].parentNode.removeChild(o[k])}!c.support.leadingWhitespace&&V.test(i)&&r.insertBefore(b.createTextNode(V.exec(i)[0]),r.firstChild);i=r.childNodes}if(i.nodeType)e.push(i);else e= +c.merge(e,i)}}if(d)for(j=0;e[j];j++)if(f&&c.nodeName(e[j],"script")&&(!e[j].type||e[j].type.toLowerCase()==="text/javascript"))f.push(e[j].parentNode?e[j].parentNode.removeChild(e[j]):e[j]);else{e[j].nodeType===1&&e.splice.apply(e,[j+1,0].concat(c.makeArray(e[j].getElementsByTagName("script"))));d.appendChild(e[j])}return e},cleanData:function(a){for(var b,d,f=c.cache,e=c.event.special,j=c.support.deleteExpando,i=0,o;(o=a[i])!=null;i++)if(d=o[c.expando]){b=f[d];if(b.events)for(var k in b.events)e[k]? +c.event.remove(o,k):Ca(o,k,b.handle);if(j)delete o[c.expando];else o.removeAttribute&&o.removeAttribute(c.expando);delete f[d]}}});var kb=/z-?index|font-?weight|opacity|zoom|line-?height/i,Na=/alpha\([^)]*\)/,Oa=/opacity=([^)]*)/,ha=/float/i,ia=/-([a-z])/ig,lb=/([A-Z])/g,mb=/^-?\d+(?:px)?$/i,nb=/^-?\d/,ob={position:"absolute",visibility:"hidden",display:"block"},pb=["Left","Right"],qb=["Top","Bottom"],rb=s.defaultView&&s.defaultView.getComputedStyle,Pa=c.support.cssFloat?"cssFloat":"styleFloat",ja= +function(a,b){return b.toUpperCase()};c.fn.css=function(a,b){return X(this,a,b,true,function(d,f,e){if(e===w)return c.curCSS(d,f);if(typeof e==="number"&&!kb.test(f))e+="px";c.style(d,f,e)})};c.extend({style:function(a,b,d){if(!a||a.nodeType===3||a.nodeType===8)return w;if((b==="width"||b==="height")&&parseFloat(d)<0)d=w;var f=a.style||a,e=d!==w;if(!c.support.opacity&&b==="opacity"){if(e){f.zoom=1;b=parseInt(d,10)+""==="NaN"?"":"alpha(opacity="+d*100+")";a=f.filter||c.curCSS(a,"filter")||"";f.filter= +Na.test(a)?a.replace(Na,b):b}return f.filter&&f.filter.indexOf("opacity=")>=0?parseFloat(Oa.exec(f.filter)[1])/100+"":""}if(ha.test(b))b=Pa;b=b.replace(ia,ja);if(e)f[b]=d;return f[b]},css:function(a,b,d,f){if(b==="width"||b==="height"){var e,j=b==="width"?pb:qb;function i(){e=b==="width"?a.offsetWidth:a.offsetHeight;f!=="border"&&c.each(j,function(){f||(e-=parseFloat(c.curCSS(a,"padding"+this,true))||0);if(f==="margin")e+=parseFloat(c.curCSS(a,"margin"+this,true))||0;else e-=parseFloat(c.curCSS(a, +"border"+this+"Width",true))||0})}a.offsetWidth!==0?i():c.swap(a,ob,i);return Math.max(0,Math.round(e))}return c.curCSS(a,b,d)},curCSS:function(a,b,d){var f,e=a.style;if(!c.support.opacity&&b==="opacity"&&a.currentStyle){f=Oa.test(a.currentStyle.filter||"")?parseFloat(RegExp.$1)/100+"":"";return f===""?"1":f}if(ha.test(b))b=Pa;if(!d&&e&&e[b])f=e[b];else if(rb){if(ha.test(b))b="float";b=b.replace(lb,"-$1").toLowerCase();e=a.ownerDocument.defaultView;if(!e)return null;if(a=e.getComputedStyle(a,null))f= +a.getPropertyValue(b);if(b==="opacity"&&f==="")f="1"}else if(a.currentStyle){d=b.replace(ia,ja);f=a.currentStyle[b]||a.currentStyle[d];if(!mb.test(f)&&nb.test(f)){b=e.left;var j=a.runtimeStyle.left;a.runtimeStyle.left=a.currentStyle.left;e.left=d==="fontSize"?"1em":f||0;f=e.pixelLeft+"px";e.left=b;a.runtimeStyle.left=j}}return f},swap:function(a,b,d){var f={};for(var e in b){f[e]=a.style[e];a.style[e]=b[e]}d.call(a);for(e in b)a.style[e]=f[e]}});if(c.expr&&c.expr.filters){c.expr.filters.hidden=function(a){var b= +a.offsetWidth,d=a.offsetHeight,f=a.nodeName.toLowerCase()==="tr";return b===0&&d===0&&!f?true:b>0&&d>0&&!f?false:c.curCSS(a,"display")==="none"};c.expr.filters.visible=function(a){return!c.expr.filters.hidden(a)}}var sb=J(),tb=//gi,ub=/select|textarea/i,vb=/color|date|datetime|email|hidden|month|number|password|range|search|tel|text|time|url|week/i,N=/=\?(&|$)/,ka=/\?/,wb=/(\?|&)_=.*?(&|$)/,xb=/^(\w+:)?\/\/([^\/?#]+)/,yb=/%20/g,zb=c.fn.load;c.fn.extend({load:function(a,b,d){if(typeof a!== +"string")return zb.call(this,a);else if(!this.length)return this;var f=a.indexOf(" ");if(f>=0){var e=a.slice(f,a.length);a=a.slice(0,f)}f="GET";if(b)if(c.isFunction(b)){d=b;b=null}else if(typeof b==="object"){b=c.param(b,c.ajaxSettings.traditional);f="POST"}var j=this;c.ajax({url:a,type:f,dataType:"html",data:b,complete:function(i,o){if(o==="success"||o==="notmodified")j.html(e?c("
").append(i.responseText.replace(tb,"")).find(e):i.responseText);d&&j.each(d,[i.responseText,o,i])}});return this}, +serialize:function(){return c.param(this.serializeArray())},serializeArray:function(){return this.map(function(){return this.elements?c.makeArray(this.elements):this}).filter(function(){return this.name&&!this.disabled&&(this.checked||ub.test(this.nodeName)||vb.test(this.type))}).map(function(a,b){a=c(this).val();return a==null?null:c.isArray(a)?c.map(a,function(d){return{name:b.name,value:d}}):{name:b.name,value:a}}).get()}});c.each("ajaxStart ajaxStop ajaxComplete ajaxError ajaxSuccess ajaxSend".split(" "), +function(a,b){c.fn[b]=function(d){return this.bind(b,d)}});c.extend({get:function(a,b,d,f){if(c.isFunction(b)){f=f||d;d=b;b=null}return c.ajax({type:"GET",url:a,data:b,success:d,dataType:f})},getScript:function(a,b){return c.get(a,null,b,"script")},getJSON:function(a,b,d){return c.get(a,b,d,"json")},post:function(a,b,d,f){if(c.isFunction(b)){f=f||d;d=b;b={}}return c.ajax({type:"POST",url:a,data:b,success:d,dataType:f})},ajaxSetup:function(a){c.extend(c.ajaxSettings,a)},ajaxSettings:{url:location.href, +global:true,type:"GET",contentType:"application/x-www-form-urlencoded",processData:true,async:true,xhr:A.XMLHttpRequest&&(A.location.protocol!=="file:"||!A.ActiveXObject)?function(){return new A.XMLHttpRequest}:function(){try{return new A.ActiveXObject("Microsoft.XMLHTTP")}catch(a){}},accepts:{xml:"application/xml, text/xml",html:"text/html",script:"text/javascript, application/javascript",json:"application/json, text/javascript",text:"text/plain",_default:"*/*"}},lastModified:{},etag:{},ajax:function(a){function b(){e.success&& +e.success.call(k,o,i,x);e.global&&f("ajaxSuccess",[x,e])}function d(){e.complete&&e.complete.call(k,x,i);e.global&&f("ajaxComplete",[x,e]);e.global&&!--c.active&&c.event.trigger("ajaxStop")}function f(q,p){(e.context?c(e.context):c.event).trigger(q,p)}var e=c.extend(true,{},c.ajaxSettings,a),j,i,o,k=a&&a.context||e,n=e.type.toUpperCase();if(e.data&&e.processData&&typeof e.data!=="string")e.data=c.param(e.data,e.traditional);if(e.dataType==="jsonp"){if(n==="GET")N.test(e.url)||(e.url+=(ka.test(e.url)? +"&":"?")+(e.jsonp||"callback")+"=?");else if(!e.data||!N.test(e.data))e.data=(e.data?e.data+"&":"")+(e.jsonp||"callback")+"=?";e.dataType="json"}if(e.dataType==="json"&&(e.data&&N.test(e.data)||N.test(e.url))){j=e.jsonpCallback||"jsonp"+sb++;if(e.data)e.data=(e.data+"").replace(N,"="+j+"$1");e.url=e.url.replace(N,"="+j+"$1");e.dataType="script";A[j]=A[j]||function(q){o=q;b();d();A[j]=w;try{delete A[j]}catch(p){}z&&z.removeChild(C)}}if(e.dataType==="script"&&e.cache===null)e.cache=false;if(e.cache=== +false&&n==="GET"){var r=J(),u=e.url.replace(wb,"$1_="+r+"$2");e.url=u+(u===e.url?(ka.test(e.url)?"&":"?")+"_="+r:"")}if(e.data&&n==="GET")e.url+=(ka.test(e.url)?"&":"?")+e.data;e.global&&!c.active++&&c.event.trigger("ajaxStart");r=(r=xb.exec(e.url))&&(r[1]&&r[1]!==location.protocol||r[2]!==location.host);if(e.dataType==="script"&&n==="GET"&&r){var z=s.getElementsByTagName("head")[0]||s.documentElement,C=s.createElement("script");C.src=e.url;if(e.scriptCharset)C.charset=e.scriptCharset;if(!j){var B= +false;C.onload=C.onreadystatechange=function(){if(!B&&(!this.readyState||this.readyState==="loaded"||this.readyState==="complete")){B=true;b();d();C.onload=C.onreadystatechange=null;z&&C.parentNode&&z.removeChild(C)}}}z.insertBefore(C,z.firstChild);return w}var E=false,x=e.xhr();if(x){e.username?x.open(n,e.url,e.async,e.username,e.password):x.open(n,e.url,e.async);try{if(e.data||a&&a.contentType)x.setRequestHeader("Content-Type",e.contentType);if(e.ifModified){c.lastModified[e.url]&&x.setRequestHeader("If-Modified-Since", +c.lastModified[e.url]);c.etag[e.url]&&x.setRequestHeader("If-None-Match",c.etag[e.url])}r||x.setRequestHeader("X-Requested-With","XMLHttpRequest");x.setRequestHeader("Accept",e.dataType&&e.accepts[e.dataType]?e.accepts[e.dataType]+", */*":e.accepts._default)}catch(ga){}if(e.beforeSend&&e.beforeSend.call(k,x,e)===false){e.global&&!--c.active&&c.event.trigger("ajaxStop");x.abort();return false}e.global&&f("ajaxSend",[x,e]);var g=x.onreadystatechange=function(q){if(!x||x.readyState===0||q==="abort"){E|| +d();E=true;if(x)x.onreadystatechange=c.noop}else if(!E&&x&&(x.readyState===4||q==="timeout")){E=true;x.onreadystatechange=c.noop;i=q==="timeout"?"timeout":!c.httpSuccess(x)?"error":e.ifModified&&c.httpNotModified(x,e.url)?"notmodified":"success";var p;if(i==="success")try{o=c.httpData(x,e.dataType,e)}catch(v){i="parsererror";p=v}if(i==="success"||i==="notmodified")j||b();else c.handleError(e,x,i,p);d();q==="timeout"&&x.abort();if(e.async)x=null}};try{var h=x.abort;x.abort=function(){x&&h.call(x); +g("abort")}}catch(l){}e.async&&e.timeout>0&&setTimeout(function(){x&&!E&&g("timeout")},e.timeout);try{x.send(n==="POST"||n==="PUT"||n==="DELETE"?e.data:null)}catch(m){c.handleError(e,x,null,m);d()}e.async||g();return x}},handleError:function(a,b,d,f){if(a.error)a.error.call(a.context||a,b,d,f);if(a.global)(a.context?c(a.context):c.event).trigger("ajaxError",[b,a,f])},active:0,httpSuccess:function(a){try{return!a.status&&location.protocol==="file:"||a.status>=200&&a.status<300||a.status===304||a.status=== +1223||a.status===0}catch(b){}return false},httpNotModified:function(a,b){var d=a.getResponseHeader("Last-Modified"),f=a.getResponseHeader("Etag");if(d)c.lastModified[b]=d;if(f)c.etag[b]=f;return a.status===304||a.status===0},httpData:function(a,b,d){var f=a.getResponseHeader("content-type")||"",e=b==="xml"||!b&&f.indexOf("xml")>=0;a=e?a.responseXML:a.responseText;e&&a.documentElement.nodeName==="parsererror"&&c.error("parsererror");if(d&&d.dataFilter)a=d.dataFilter(a,b);if(typeof a==="string")if(b=== +"json"||!b&&f.indexOf("json")>=0)a=c.parseJSON(a);else if(b==="script"||!b&&f.indexOf("javascript")>=0)c.globalEval(a);return a},param:function(a,b){function d(i,o){if(c.isArray(o))c.each(o,function(k,n){b||/\[\]$/.test(i)?f(i,n):d(i+"["+(typeof n==="object"||c.isArray(n)?k:"")+"]",n)});else!b&&o!=null&&typeof o==="object"?c.each(o,function(k,n){d(i+"["+k+"]",n)}):f(i,o)}function f(i,o){o=c.isFunction(o)?o():o;e[e.length]=encodeURIComponent(i)+"="+encodeURIComponent(o)}var e=[];if(b===w)b=c.ajaxSettings.traditional; +if(c.isArray(a)||a.jquery)c.each(a,function(){f(this.name,this.value)});else for(var j in a)d(j,a[j]);return e.join("&").replace(yb,"+")}});var la={},Ab=/toggle|show|hide/,Bb=/^([+-]=)?([\d+-.]+)(.*)$/,W,va=[["height","marginTop","marginBottom","paddingTop","paddingBottom"],["width","marginLeft","marginRight","paddingLeft","paddingRight"],["opacity"]];c.fn.extend({show:function(a,b){if(a||a===0)return this.animate(K("show",3),a,b);else{a=0;for(b=this.length;a").appendTo("body");f=e.css("display");if(f==="none")f="block";e.remove();la[d]=f}c.data(this[a],"olddisplay",f)}}a=0;for(b=this.length;a=0;f--)if(d[f].elem===this){b&&d[f](true);d.splice(f,1)}});b||this.dequeue();return this}});c.each({slideDown:K("show",1),slideUp:K("hide",1),slideToggle:K("toggle",1),fadeIn:{opacity:"show"},fadeOut:{opacity:"hide"}},function(a,b){c.fn[a]=function(d,f){return this.animate(b,d,f)}});c.extend({speed:function(a,b,d){var f=a&&typeof a==="object"?a:{complete:d||!d&&b||c.isFunction(a)&&a,duration:a,easing:d&&b||b&&!c.isFunction(b)&&b};f.duration=c.fx.off?0:typeof f.duration=== +"number"?f.duration:c.fx.speeds[f.duration]||c.fx.speeds._default;f.old=f.complete;f.complete=function(){f.queue!==false&&c(this).dequeue();c.isFunction(f.old)&&f.old.call(this)};return f},easing:{linear:function(a,b,d,f){return d+f*a},swing:function(a,b,d,f){return(-Math.cos(a*Math.PI)/2+0.5)*f+d}},timers:[],fx:function(a,b,d){this.options=b;this.elem=a;this.prop=d;if(!b.orig)b.orig={}}});c.fx.prototype={update:function(){this.options.step&&this.options.step.call(this.elem,this.now,this);(c.fx.step[this.prop]|| +c.fx.step._default)(this);if((this.prop==="height"||this.prop==="width")&&this.elem.style)this.elem.style.display="block"},cur:function(a){if(this.elem[this.prop]!=null&&(!this.elem.style||this.elem.style[this.prop]==null))return this.elem[this.prop];return(a=parseFloat(c.css(this.elem,this.prop,a)))&&a>-10000?a:parseFloat(c.curCSS(this.elem,this.prop))||0},custom:function(a,b,d){function f(j){return e.step(j)}this.startTime=J();this.start=a;this.end=b;this.unit=d||this.unit||"px";this.now=this.start; +this.pos=this.state=0;var e=this;f.elem=this.elem;if(f()&&c.timers.push(f)&&!W)W=setInterval(c.fx.tick,13)},show:function(){this.options.orig[this.prop]=c.style(this.elem,this.prop);this.options.show=true;this.custom(this.prop==="width"||this.prop==="height"?1:0,this.cur());c(this.elem).show()},hide:function(){this.options.orig[this.prop]=c.style(this.elem,this.prop);this.options.hide=true;this.custom(this.cur(),0)},step:function(a){var b=J(),d=true;if(a||b>=this.options.duration+this.startTime){this.now= +this.end;this.pos=this.state=1;this.update();this.options.curAnim[this.prop]=true;for(var f in this.options.curAnim)if(this.options.curAnim[f]!==true)d=false;if(d){if(this.options.display!=null){this.elem.style.overflow=this.options.overflow;a=c.data(this.elem,"olddisplay");this.elem.style.display=a?a:this.options.display;if(c.css(this.elem,"display")==="none")this.elem.style.display="block"}this.options.hide&&c(this.elem).hide();if(this.options.hide||this.options.show)for(var e in this.options.curAnim)c.style(this.elem, +e,this.options.orig[e]);this.options.complete.call(this.elem)}return false}else{e=b-this.startTime;this.state=e/this.options.duration;a=this.options.easing||(c.easing.swing?"swing":"linear");this.pos=c.easing[this.options.specialEasing&&this.options.specialEasing[this.prop]||a](this.state,e,0,1,this.options.duration);this.now=this.start+(this.end-this.start)*this.pos;this.update()}return true}};c.extend(c.fx,{tick:function(){for(var a=c.timers,b=0;b
"; +a.insertBefore(b,a.firstChild);d=b.firstChild;f=d.firstChild;e=d.nextSibling.firstChild.firstChild;this.doesNotAddBorder=f.offsetTop!==5;this.doesAddBorderForTableAndCells=e.offsetTop===5;f.style.position="fixed";f.style.top="20px";this.supportsFixedPosition=f.offsetTop===20||f.offsetTop===15;f.style.position=f.style.top="";d.style.overflow="hidden";d.style.position="relative";this.subtractsBorderForOverflowNotVisible=f.offsetTop===-5;this.doesNotIncludeMarginInBodyOffset=a.offsetTop!==j;a.removeChild(b); +c.offset.initialize=c.noop},bodyOffset:function(a){var b=a.offsetTop,d=a.offsetLeft;c.offset.initialize();if(c.offset.doesNotIncludeMarginInBodyOffset){b+=parseFloat(c.curCSS(a,"marginTop",true))||0;d+=parseFloat(c.curCSS(a,"marginLeft",true))||0}return{top:b,left:d}},setOffset:function(a,b,d){if(/static/.test(c.curCSS(a,"position")))a.style.position="relative";var f=c(a),e=f.offset(),j=parseInt(c.curCSS(a,"top",true),10)||0,i=parseInt(c.curCSS(a,"left",true),10)||0;if(c.isFunction(b))b=b.call(a, +d,e);d={top:b.top-e.top+j,left:b.left-e.left+i};"using"in b?b.using.call(a,d):f.css(d)}};c.fn.extend({position:function(){if(!this[0])return null;var a=this[0],b=this.offsetParent(),d=this.offset(),f=/^body|html$/i.test(b[0].nodeName)?{top:0,left:0}:b.offset();d.top-=parseFloat(c.curCSS(a,"marginTop",true))||0;d.left-=parseFloat(c.curCSS(a,"marginLeft",true))||0;f.top+=parseFloat(c.curCSS(b[0],"borderTopWidth",true))||0;f.left+=parseFloat(c.curCSS(b[0],"borderLeftWidth",true))||0;return{top:d.top- +f.top,left:d.left-f.left}},offsetParent:function(){return this.map(function(){for(var a=this.offsetParent||s.body;a&&!/^body|html$/i.test(a.nodeName)&&c.css(a,"position")==="static";)a=a.offsetParent;return a})}});c.each(["Left","Top"],function(a,b){var d="scroll"+b;c.fn[d]=function(f){var e=this[0],j;if(!e)return null;if(f!==w)return this.each(function(){if(j=wa(this))j.scrollTo(!a?f:c(j).scrollLeft(),a?f:c(j).scrollTop());else this[d]=f});else return(j=wa(e))?"pageXOffset"in j?j[a?"pageYOffset": +"pageXOffset"]:c.support.boxModel&&j.document.documentElement[d]||j.document.body[d]:e[d]}});c.each(["Height","Width"],function(a,b){var d=b.toLowerCase();c.fn["inner"+b]=function(){return this[0]?c.css(this[0],d,false,"padding"):null};c.fn["outer"+b]=function(f){return this[0]?c.css(this[0],d,false,f?"margin":"border"):null};c.fn[d]=function(f){var e=this[0];if(!e)return f==null?null:this;if(c.isFunction(f))return this.each(function(j){var i=c(this);i[d](f.call(this,j,i[d]()))});return"scrollTo"in +e&&e.document?e.document.compatMode==="CSS1Compat"&&e.document.documentElement["client"+b]||e.document.body["client"+b]:e.nodeType===9?Math.max(e.documentElement["client"+b],e.body["scroll"+b],e.documentElement["scroll"+b],e.body["offset"+b],e.documentElement["offset"+b]):f===w?c.css(e,d):this.css(d,typeof f==="string"?f:f+"px")}});A.jQuery=A.$=c})(window); diff --git a/python/mock-1.0.0/html/_static/minus.png b/python/mock-1.0.0/html/_static/minus.png new file mode 100644 index 000000000..da1c5620d Binary files /dev/null and b/python/mock-1.0.0/html/_static/minus.png differ diff --git a/python/mock-1.0.0/html/_static/mobile.css b/python/mock-1.0.0/html/_static/mobile.css new file mode 100644 index 000000000..0cfe799b2 --- /dev/null +++ b/python/mock-1.0.0/html/_static/mobile.css @@ -0,0 +1,17 @@ +/* + * CSS adjustments (overrides) for mobile browsers that cannot handle + * fix-positioned div's very well. + * This makes long pages scrollable on mobile browsers. + */ + +#breadcrumbs { + display: none !important; +} + +.document { + bottom: inherit !important; +} + +#sphinxsidebar { + bottom: inherit !important; +} diff --git a/python/mock-1.0.0/html/_static/plus.png b/python/mock-1.0.0/html/_static/plus.png new file mode 100644 index 000000000..b3cb37425 Binary files /dev/null and b/python/mock-1.0.0/html/_static/plus.png differ diff --git a/python/mock-1.0.0/html/_static/pygments.css b/python/mock-1.0.0/html/_static/pygments.css new file mode 100644 index 000000000..f07b654ba --- /dev/null +++ b/python/mock-1.0.0/html/_static/pygments.css @@ -0,0 +1,62 @@ +.highlight .hll { background-color: #ffffcc } +.highlight { background: #f0f0f0; } +.highlight .c { color: #60a0b0; font-style: italic } /* Comment */ +.highlight .err { border: 1px solid #FF0000 } /* Error */ +.highlight .k { color: #007020; font-weight: bold } /* Keyword */ +.highlight .o { color: #666666 } /* Operator */ +.highlight .cm { color: #60a0b0; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #007020 } /* Comment.Preproc */ +.highlight .c1 { color: #60a0b0; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #60a0b0; background-color: #fff0f0 } /* Comment.Special */ +.highlight .gd { color: #A00000 } /* Generic.Deleted */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .gr { color: #FF0000 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #00A000 } /* Generic.Inserted */ +.highlight .go { color: #808080 } /* Generic.Output */ +.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #0040D0 } /* Generic.Traceback */ +.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #007020 } /* Keyword.Pseudo */ +.highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #902000 } /* Keyword.Type */ +.highlight .m { color: #40a070 } /* Literal.Number */ +.highlight .s { color: #4070a0 } /* Literal.String */ +.highlight .na { color: #4070a0 } /* Name.Attribute */ +.highlight .nb { color: #007020 } /* Name.Builtin */ +.highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */ +.highlight .no { color: #60add5 } /* Name.Constant */ +.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */ +.highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */ +.highlight .ne { color: #007020 } /* Name.Exception */ +.highlight .nf { color: #06287e } /* Name.Function */ +.highlight .nl { color: #002070; font-weight: bold } /* Name.Label */ +.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ +.highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #bb60d5 } /* Name.Variable */ +.highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */ +.highlight .w { color: #bbbbbb } /* Text.Whitespace */ +.highlight .mf { color: #40a070 } /* Literal.Number.Float */ +.highlight .mh { color: #40a070 } /* Literal.Number.Hex */ +.highlight .mi { color: #40a070 } /* Literal.Number.Integer */ +.highlight .mo { color: #40a070 } /* Literal.Number.Oct */ +.highlight .sb { color: #4070a0 } /* Literal.String.Backtick */ +.highlight .sc { color: #4070a0 } /* Literal.String.Char */ +.highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */ +.highlight .s2 { color: #4070a0 } /* Literal.String.Double */ +.highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */ +.highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */ +.highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */ +.highlight .sx { color: #c65d09 } /* Literal.String.Other */ +.highlight .sr { color: #235388 } /* Literal.String.Regex */ +.highlight .s1 { color: #4070a0 } /* Literal.String.Single */ +.highlight .ss { color: #517918 } /* Literal.String.Symbol */ +.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */ +.highlight .vc { color: #bb60d5 } /* Name.Variable.Class */ +.highlight .vg { color: #bb60d5 } /* Name.Variable.Global */ +.highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */ +.highlight .il { color: #40a070 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/python/mock-1.0.0/html/_static/scrn1.png b/python/mock-1.0.0/html/_static/scrn1.png new file mode 100644 index 000000000..6499b3cf7 Binary files /dev/null and b/python/mock-1.0.0/html/_static/scrn1.png differ diff --git a/python/mock-1.0.0/html/_static/scrn2.png b/python/mock-1.0.0/html/_static/scrn2.png new file mode 100644 index 000000000..2a60215d0 Binary files /dev/null and b/python/mock-1.0.0/html/_static/scrn2.png differ diff --git a/python/mock-1.0.0/html/_static/searchfield_leftcap.png b/python/mock-1.0.0/html/_static/searchfield_leftcap.png new file mode 100644 index 000000000..cc00c22b0 Binary files /dev/null and b/python/mock-1.0.0/html/_static/searchfield_leftcap.png differ diff --git a/python/mock-1.0.0/html/_static/searchfield_repeat.png b/python/mock-1.0.0/html/_static/searchfield_repeat.png new file mode 100644 index 000000000..b429a16ba Binary files /dev/null and b/python/mock-1.0.0/html/_static/searchfield_repeat.png differ diff --git a/python/mock-1.0.0/html/_static/searchfield_rightcap.png b/python/mock-1.0.0/html/_static/searchfield_rightcap.png new file mode 100644 index 000000000..8e13620ec Binary files /dev/null and b/python/mock-1.0.0/html/_static/searchfield_rightcap.png differ diff --git a/python/mock-1.0.0/html/_static/searchtools.js b/python/mock-1.0.0/html/_static/searchtools.js new file mode 100644 index 000000000..663be4c90 --- /dev/null +++ b/python/mock-1.0.0/html/_static/searchtools.js @@ -0,0 +1,560 @@ +/* + * searchtools.js_t + * ~~~~~~~~~~~~~~~~ + * + * Sphinx JavaScript utilties for the full-text search. + * + * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words, hlwords is the list of normal, unstemmed + * words. the first one is used to find the occurance, the + * latter for highlighting it. + */ + +jQuery.makeSearchSummary = function(text, keywords, hlwords) { + var textLower = text.toLowerCase(); + var start = 0; + $.each(keywords, function() { + var i = textLower.indexOf(this.toLowerCase()); + if (i > -1) + start = i; + }); + start = Math.max(start - 120, 0); + var excerpt = ((start > 0) ? '...' : '') + + $.trim(text.substr(start, 240)) + + ((start + 240 - text.length) ? '...' : ''); + var rv = $('
').text(excerpt); + $.each(hlwords, function() { + rv = rv.highlightText(this, 'highlighted'); + }); + return rv; +} + + +/** + * Porter Stemmer + */ +var Stemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + + +/** + * Search Module + */ +var Search = { + + _index : null, + _queued_query : null, + _pulse_status : -1, + + init : function() { + var params = $.getQueryParameters(); + if (params.q) { + var query = params.q[0]; + $('input[name="q"]')[0].value = query; + this.performSearch(query); + } + }, + + loadIndex : function(url) { + $.ajax({type: "GET", url: url, data: null, success: null, + dataType: "script", cache: true}); + }, + + setIndex : function(index) { + var q; + this._index = index; + if ((q = this._queued_query) !== null) { + this._queued_query = null; + Search.query(q); + } + }, + + hasIndex : function() { + return this._index !== null; + }, + + deferQuery : function(query) { + this._queued_query = query; + }, + + stopPulse : function() { + this._pulse_status = 0; + }, + + startPulse : function() { + if (this._pulse_status >= 0) + return; + function pulse() { + Search._pulse_status = (Search._pulse_status + 1) % 4; + var dotString = ''; + for (var i = 0; i < Search._pulse_status; i++) + dotString += '.'; + Search.dots.text(dotString); + if (Search._pulse_status > -1) + window.setTimeout(pulse, 500); + }; + pulse(); + }, + + /** + * perform a search for something + */ + performSearch : function(query) { + // create the required interface elements + this.out = $('#search-results'); + this.title = $('

' + _('Searching') + '

').appendTo(this.out); + this.dots = $('').appendTo(this.title); + this.status = $('

').appendTo(this.out); + this.output = $('
    ').appendTo(this.out); + + $('#search-progress').text(_('Preparing search...')); + this.startPulse(); + + // index already loaded, the browser was quick! + if (this.hasIndex()) + this.query(query); + else + this.deferQuery(query); + }, + + query : function(query) { + var stopwords = ["and","then","into","it","as","are","in","if","for","no","there","their","was","is","be","to","that","but","they","not","such","with","by","a","on","these","of","will","this","near","the","or","at"]; + + // Stem the searchterms and add them to the correct list + var stemmer = new Stemmer(); + var searchterms = []; + var excluded = []; + var hlterms = []; + var tmp = query.split(/\s+/); + var objectterms = []; + for (var i = 0; i < tmp.length; i++) { + if (tmp[i] != "") { + objectterms.push(tmp[i].toLowerCase()); + } + + if ($u.indexOf(stopwords, tmp[i]) != -1 || tmp[i].match(/^\d+$/) || + tmp[i] == "") { + // skip this "word" + continue; + } + // stem the word + var word = stemmer.stemWord(tmp[i]).toLowerCase(); + // select the correct list + if (word[0] == '-') { + var toAppend = excluded; + word = word.substr(1); + } + else { + var toAppend = searchterms; + hlterms.push(tmp[i].toLowerCase()); + } + // only add if not already in the list + if (!$.contains(toAppend, word)) + toAppend.push(word); + }; + var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" ")); + + // console.debug('SEARCH: searching for:'); + // console.info('required: ', searchterms); + // console.info('excluded: ', excluded); + + // prepare search + var filenames = this._index.filenames; + var titles = this._index.titles; + var terms = this._index.terms; + var fileMap = {}; + var files = null; + // different result priorities + var importantResults = []; + var objectResults = []; + var regularResults = []; + var unimportantResults = []; + $('#search-progress').empty(); + + // lookup as object + for (var i = 0; i < objectterms.length; i++) { + var others = [].concat(objectterms.slice(0,i), + objectterms.slice(i+1, objectterms.length)) + var results = this.performObjectSearch(objectterms[i], others); + // Assume first word is most likely to be the object, + // other words more likely to be in description. + // Therefore put matches for earlier words first. + // (Results are eventually used in reverse order). + objectResults = results[0].concat(objectResults); + importantResults = results[1].concat(importantResults); + unimportantResults = results[2].concat(unimportantResults); + } + + // perform the search on the required terms + for (var i = 0; i < searchterms.length; i++) { + var word = searchterms[i]; + // no match but word was a required one + if ((files = terms[word]) == null) + break; + if (files.length == undefined) { + files = [files]; + } + // create the mapping + for (var j = 0; j < files.length; j++) { + var file = files[j]; + if (file in fileMap) + fileMap[file].push(word); + else + fileMap[file] = [word]; + } + } + + // now check if the files don't contain excluded terms + for (var file in fileMap) { + var valid = true; + + // check if all requirements are matched + if (fileMap[file].length != searchterms.length) + continue; + + // ensure that none of the excluded terms is in the + // search result. + for (var i = 0; i < excluded.length; i++) { + if (terms[excluded[i]] == file || + $.contains(terms[excluded[i]] || [], file)) { + valid = false; + break; + } + } + + // if we have still a valid result we can add it + // to the result list + if (valid) + regularResults.push([filenames[file], titles[file], '', null]); + } + + // delete unused variables in order to not waste + // memory until list is retrieved completely + delete filenames, titles, terms; + + // now sort the regular results descending by title + regularResults.sort(function(a, b) { + var left = a[1].toLowerCase(); + var right = b[1].toLowerCase(); + return (left > right) ? -1 : ((left < right) ? 1 : 0); + }); + + // combine all results + var results = unimportantResults.concat(regularResults) + .concat(objectResults).concat(importantResults); + + // print the results + var resultCount = results.length; + function displayNextItem() { + // results left, load the summary and display it + if (results.length) { + var item = results.pop(); + var listItem = $('
  • '); + if (DOCUMENTATION_OPTIONS.FILE_SUFFIX == '') { + // dirhtml builder + var dirname = item[0] + '/'; + if (dirname.match(/\/index\/$/)) { + dirname = dirname.substring(0, dirname.length-6); + } else if (dirname == 'index/') { + dirname = ''; + } + listItem.append($('').attr('href', + DOCUMENTATION_OPTIONS.URL_ROOT + dirname + + highlightstring + item[2]).html(item[1])); + } else { + // normal html builders + listItem.append($('').attr('href', + item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX + + highlightstring + item[2]).html(item[1])); + } + if (item[3]) { + listItem.append($(' (' + item[3] + ')')); + Search.output.append(listItem); + listItem.slideDown(5, function() { + displayNextItem(); + }); + } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) { + $.get(DOCUMENTATION_OPTIONS.URL_ROOT + '_sources/' + + item[0] + '.txt', function(data) { + if (data != '') { + listItem.append($.makeSearchSummary(data, searchterms, hlterms)); + Search.output.append(listItem); + } + listItem.slideDown(5, function() { + displayNextItem(); + }); + }, "text"); + } else { + // no source available, just display title + Search.output.append(listItem); + listItem.slideDown(5, function() { + displayNextItem(); + }); + } + } + // search finished, update title and status message + else { + Search.stopPulse(); + Search.title.text(_('Search Results')); + if (!resultCount) + Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.')); + else + Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount)); + Search.status.fadeIn(500); + } + } + displayNextItem(); + }, + + performObjectSearch : function(object, otherterms) { + var filenames = this._index.filenames; + var objects = this._index.objects; + var objnames = this._index.objnames; + var titles = this._index.titles; + + var importantResults = []; + var objectResults = []; + var unimportantResults = []; + + for (var prefix in objects) { + for (var name in objects[prefix]) { + var fullname = (prefix ? prefix + '.' : '') + name; + if (fullname.toLowerCase().indexOf(object) > -1) { + var match = objects[prefix][name]; + var objname = objnames[match[1]][2]; + var title = titles[match[0]]; + // If more than one term searched for, we require other words to be + // found in the name/title/description + if (otherterms.length > 0) { + var haystack = (prefix + ' ' + name + ' ' + + objname + ' ' + title).toLowerCase(); + var allfound = true; + for (var i = 0; i < otherterms.length; i++) { + if (haystack.indexOf(otherterms[i]) == -1) { + allfound = false; + break; + } + } + if (!allfound) { + continue; + } + } + var descr = objname + _(', in ') + title; + anchor = match[3]; + if (anchor == '') + anchor = fullname; + else if (anchor == '-') + anchor = objnames[match[1]][1] + '-' + fullname; + result = [filenames[match[0]], fullname, '#'+anchor, descr]; + switch (match[2]) { + case 1: objectResults.push(result); break; + case 0: importantResults.push(result); break; + case 2: unimportantResults.push(result); break; + } + } + } + } + + // sort results descending + objectResults.sort(function(a, b) { + return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0); + }); + + importantResults.sort(function(a, b) { + return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0); + }); + + unimportantResults.sort(function(a, b) { + return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0); + }); + + return [importantResults, objectResults, unimportantResults] + } +} + +$(document).ready(function() { + Search.init(); +}); \ No newline at end of file diff --git a/python/mock-1.0.0/html/_static/sidebar.js b/python/mock-1.0.0/html/_static/sidebar.js new file mode 100644 index 000000000..731851711 --- /dev/null +++ b/python/mock-1.0.0/html/_static/sidebar.js @@ -0,0 +1,148 @@ +/* + * sidebar.js + * ~~~~~~~~~~ + * + * This script makes the Sphinx sidebar collapsible. + * + * .sphinxsidebar contains .sphinxsidebarwrapper. This script adds + * in .sphixsidebar, after .sphinxsidebarwrapper, the #sidebarbutton + * used to collapse and expand the sidebar. + * + * When the sidebar is collapsed the .sphinxsidebarwrapper is hidden + * and the width of the sidebar and the margin-left of the document + * are decreased. When the sidebar is expanded the opposite happens. + * This script saves a per-browser/per-session cookie used to + * remember the position of the sidebar among the pages. + * Once the browser is closed the cookie is deleted and the position + * reset to the default (expanded). + * + * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +$(function() { + // global elements used by the functions. + // the 'sidebarbutton' element is defined as global after its + // creation, in the add_sidebar_button function + var bodywrapper = $('.bodywrapper'); + var sidebar = $('.sphinxsidebar'); + var sidebarwrapper = $('.sphinxsidebarwrapper'); + + // original margin-left of the bodywrapper and width of the sidebar + // with the sidebar expanded + var bw_margin_expanded = bodywrapper.css('margin-left'); + var ssb_width_expanded = sidebar.width(); + + // margin-left of the bodywrapper and width of the sidebar + // with the sidebar collapsed + var bw_margin_collapsed = '.8em'; + var ssb_width_collapsed = '.8em'; + + // colors used by the current theme + var dark_color = $('.related').css('background-color'); + var light_color = $('.document').css('background-color'); + + function sidebar_is_collapsed() { + return sidebarwrapper.is(':not(:visible)'); + } + + function toggle_sidebar() { + if (sidebar_is_collapsed()) + expand_sidebar(); + else + collapse_sidebar(); + } + + function collapse_sidebar() { + sidebarwrapper.hide(); + sidebar.css('width', ssb_width_collapsed); + bodywrapper.css('margin-left', bw_margin_collapsed); + sidebarbutton.css({ + 'margin-left': '0', + 'height': bodywrapper.height() + }); + sidebarbutton.find('span').text('»'); + sidebarbutton.attr('title', _('Expand sidebar')); + document.cookie = 'sidebar=collapsed'; + } + + function expand_sidebar() { + bodywrapper.css('margin-left', bw_margin_expanded); + sidebar.css('width', ssb_width_expanded); + sidebarwrapper.show(); + sidebarbutton.css({ + 'margin-left': ssb_width_expanded-12, + 'height': bodywrapper.height() + }); + sidebarbutton.find('span').text('«'); + sidebarbutton.attr('title', _('Collapse sidebar')); + document.cookie = 'sidebar=expanded'; + } + + function add_sidebar_button() { + sidebarwrapper.css({ + 'float': 'left', + 'margin-right': '0', + 'width': ssb_width_expanded - 28 + }); + // create the button + sidebar.append( + '
    «
    ' + ); + var sidebarbutton = $('#sidebarbutton'); + light_color = sidebarbutton.css('background-color'); + // find the height of the viewport to center the '<<' in the page + var viewport_height; + if (window.innerHeight) + viewport_height = window.innerHeight; + else + viewport_height = $(window).height(); + sidebarbutton.find('span').css({ + 'display': 'block', + 'margin-top': (viewport_height - sidebar.position().top - 20) / 2 + }); + + sidebarbutton.click(toggle_sidebar); + sidebarbutton.attr('title', _('Collapse sidebar')); + sidebarbutton.css({ + 'color': '#FFFFFF', + 'border-left': '1px solid ' + dark_color, + 'font-size': '1.2em', + 'cursor': 'pointer', + 'height': bodywrapper.height(), + 'padding-top': '1px', + 'margin-left': ssb_width_expanded - 12 + }); + + sidebarbutton.hover( + function () { + $(this).css('background-color', dark_color); + }, + function () { + $(this).css('background-color', light_color); + } + ); + } + + function set_position_from_cookie() { + if (!document.cookie) + return; + var items = document.cookie.split(';'); + for(var k=0; k=e.computed&&(e={value:f,computed:g})});return e.value};b.min=function(a,c,d){if(!c&&b.isArray(a))return Math.min.apply(Math,a);var e={computed:Infinity};b.each(a,function(f,g,h){g=c?c.call(d,f,g,h):f;gf?1:0}),"value")};b.sortedIndex=function(a,c,d){d=d||b.identity;for(var e=0,f=a.length;e>1;d(a[g])=0})})};b.zip=function(){for(var a=b.toArray(arguments),c=b.max(b.pluck(a,"length")),d=new Array(c),e=0;e0?f-c:c-f)>=0)return e;e[g++]=f}};b.bind=function(a,c){var d=b.rest(arguments,2);return function(){return a.apply(c||j,d.concat(b.toArray(arguments)))}};b.bindAll=function(a){var c=b.rest(arguments);if(c.length==0)c=b.functions(a);b.each(c,function(d){a[d]=b.bind(a[d],a)}); +return a};b.delay=function(a,c){var d=b.rest(arguments,2);return setTimeout(function(){return a.apply(a,d)},c)};b.defer=function(a){return b.delay.apply(b,[a,1].concat(b.rest(arguments)))};b.wrap=function(a,c){return function(){var d=[a].concat(b.toArray(arguments));return c.apply(c,d)}};b.compose=function(){var a=b.toArray(arguments);return function(){for(var c=b.toArray(arguments),d=a.length-1;d>=0;d--)c=[a[d].apply(this,c)];return c[0]}};b.keys=function(a){if(b.isArray(a))return b.range(0,a.length); +var c=[];for(var d in a)q.call(a,d)&&c.push(d);return c};b.values=function(a){return b.map(a,b.identity)};b.functions=function(a){return b.select(b.keys(a),function(c){return b.isFunction(a[c])}).sort()};b.extend=function(a,c){for(var d in c)a[d]=c[d];return a};b.clone=function(a){if(b.isArray(a))return a.slice(0);return b.extend({},a)};b.tap=function(a,c){c(a);return a};b.isEqual=function(a,c){if(a===c)return true;var d=typeof a;if(d!=typeof c)return false;if(a==c)return true;if(!a&&c||a&&!c)return false; +if(a.isEqual)return a.isEqual(c);if(b.isDate(a)&&b.isDate(c))return a.getTime()===c.getTime();if(b.isNaN(a)&&b.isNaN(c))return true;if(b.isRegExp(a)&&b.isRegExp(c))return a.source===c.source&&a.global===c.global&&a.ignoreCase===c.ignoreCase&&a.multiline===c.multiline;if(d!=="object")return false;if(a.length&&a.length!==c.length)return false;d=b.keys(a);var e=b.keys(c);if(d.length!=e.length)return false;for(var f in a)if(!b.isEqual(a[f],c[f]))return false;return true};b.isEmpty=function(a){return b.keys(a).length== +0};b.isElement=function(a){return!!(a&&a.nodeType==1)};b.isArray=function(a){return!!(a&&a.concat&&a.unshift)};b.isArguments=function(a){return a&&b.isNumber(a.length)&&!b.isArray(a)&&!r.call(a,"length")};b.isFunction=function(a){return!!(a&&a.constructor&&a.call&&a.apply)};b.isString=function(a){return!!(a===""||a&&a.charCodeAt&&a.substr)};b.isNumber=function(a){return p.call(a)==="[object Number]"};b.isDate=function(a){return!!(a&&a.getTimezoneOffset&&a.setUTCFullYear)};b.isRegExp=function(a){return!!(a&& +a.test&&a.exec&&(a.ignoreCase||a.ignoreCase===false))};b.isNaN=function(a){return b.isNumber(a)&&isNaN(a)};b.isNull=function(a){return a===null};b.isUndefined=function(a){return typeof a=="undefined"};b.noConflict=function(){j._=n;return this};b.identity=function(a){return a};b.breakLoop=function(){throw m;};var s=0;b.uniqueId=function(a){var c=s++;return a?a+c:c};b.template=function(a,c){a=new Function("obj","var p=[],print=function(){p.push.apply(p,arguments);};with(obj){p.push('"+a.replace(/[\r\t\n]/g, +" ").replace(/'(?=[^%]*%>)/g,"\t").split("'").join("\\'").split("\t").join("'").replace(/<%=(.+?)%>/g,"',$1,'").split("<%").join("');").split("%>").join("p.push('")+"');}return p.join('');");return c?a(c):a};b.forEach=b.each;b.foldl=b.inject=b.reduce;b.foldr=b.reduceRight;b.filter=b.select;b.every=b.all;b.some=b.any;b.head=b.first;b.tail=b.rest;b.methods=b.functions;var l=function(a,c){return c?b(a).chain():a};b.each(b.functions(b),function(a){var c=b[a];i.prototype[a]=function(){var d=b.toArray(arguments); +o.call(d,this._wrapped);return l(c.apply(b,d),this._chain)}});b.each(["pop","push","reverse","shift","sort","splice","unshift"],function(a){var c=Array.prototype[a];i.prototype[a]=function(){c.apply(this._wrapped,arguments);return l(this._wrapped,this._chain)}});b.each(["concat","join","slice"],function(a){var c=Array.prototype[a];i.prototype[a]=function(){return l(c.apply(this._wrapped,arguments),this._chain)}});i.prototype.chain=function(){this._chain=true;return this};i.prototype.value=function(){return this._wrapped}})(); diff --git a/python/mock-1.0.0/html/changelog.html b/python/mock-1.0.0/html/changelog.html new file mode 100644 index 000000000..c4b935d2c --- /dev/null +++ b/python/mock-1.0.0/html/changelog.html @@ -0,0 +1,839 @@ + + + + + + + + + CHANGELOG — Mock 1.0.0 documentation + + + + + + + + + + + + +
    +

    Navigation

    +     +
    + +
    +
    +
    +
    + +
    +

    CHANGELOG¶

    +
    +

    2012/10/07 Version 1.0.0¶

    +

    No changes since 1.0.0 beta 1. This version has feature parity with +unittest.mock +in Python 3.3.

    +

    Full list of changes since 0.8:

    +
      +
    • mocksignature, along with the mocksignature argument to patch, removed
      • +
    • Support for deleting attributes (accessing deleted attributes will raise an +AttributeError)
      • +
    • Added the mock_open helper function for mocking the builtin open
      • +
    • __class__ is assignable, so a mock can pass an isinstance check without +requiring a spec
      • +
    • Addition of PropertyMock, for mocking properties
      • +
    • MagicMocks made unorderable by default (in Python 3). The comparison +methods (other than equality and inequality) now return NotImplemented
      • +
    • Propagate traceback info to support subclassing of _patch by other +libraries
      • +
    • create_autospec works with attributes present in results of dir that +can’t be fetched from the object’s class. Contributed by Konstantine Rybnikov
      • +
    • Any exceptions in an iterable side_effect will be raised instead of +returned
      • +
    • In Python 3, create_autospec now supports keyword only arguments
      • +
    • Added patch.stopall method to stop all active patches created by start
      • +
    • BUGFIX: calling MagicMock.reset_mock wouldn’t reset magic method mocks
      • +
    • BUGFIX: calling reset_mock on a MagicMock created with autospec could +raise an exception
      • +
    • BUGFIX: passing multiple spec arguments to patchers (spec , spec_set and +autospec) had unpredictable results, now it is an error
      • +
    • BUGFIX: using spec=True and create=True as arguments to patchers could +result in using DEFAULT as the spec. Now it is an error instead
      • +
    • BUGFIX: using spec or autospec arguments to patchers, along with +spec_set=True did not work correctly
      • +
    • BUGFIX: using an object that evaluates to False as a spec could be ignored
      • +
    • BUGFIX: a list as the spec argument to a patcher would always result in a +non-callable mock. Now if __call__ is in the spec the mock is callable
      • +
    +
    +
    +

    2012/07/13 Version 1.0.0 beta 1¶

    +
      +
    • Added patch.stopall method to stop all active patches created by start
      • +
    • BUGFIX: calling MagicMock.reset_mock wouldn’t reset magic method mocks
      • +
    • BUGFIX: calling reset_mock on a MagicMock created with autospec could +raise an exception
      • +
    +
    +
    +

    2012/05/04 Version 1.0.0 alpha 2¶

    +
      +
    • PropertyMock attributes are now standard MagicMocks
      • +
    • create_autospec works with attributes present in results of dir that +can’t be fetched from the object’s class. Contributed by Konstantine Rybnikov
      • +
    • Any exceptions in an iterable side_effect will be raised instead of +returned
      • +
    • In Python 3, create_autospec now supports keyword only arguments
      • +
    +
    +
    +

    2012/03/25 Version 1.0.0 alpha 1¶

    +

    The standard library version!

    +
      +
    • mocksignature, along with the mocksignature argument to patch, removed
      • +
    • Support for deleting attributes (accessing deleted attributes will raise an +AttributeError)
      • +
    • Added the mock_open helper function for mocking the builtin open
      • +
    • __class__ is assignable, so a mock can pass an isinstance check without +requiring a spec
      • +
    • Addition of PropertyMock, for mocking properties
      • +
    • MagicMocks made unorderable by default (in Python 3). The comparison +methods (other than equality and inequality) now return NotImplemented
      • +
    • Propagate traceback info to support subclassing of _patch by other +libraries
      • +
    • BUGFIX: passing multiple spec arguments to patchers (spec , spec_set and +autospec) had unpredictable results, now it is an error
      • +
    • BUGFIX: using spec=True and create=True as arguments to patchers could +result in using DEFAULT as the spec. Now it is an error instead
      • +
    • BUGFIX: using spec or autospec arguments to patchers, along with +spec_set=True did not work correctly
      • +
    • BUGFIX: using an object that evaluates to False as a spec could be ignored
      • +
    • BUGFIX: a list as the spec argument to a patcher would always result in a +non-callable mock. Now if __call__ is in the spec the mock is callable
      • +
    +
    +
    +

    2012/02/13 Version 0.8.0¶

    +

    The only changes since 0.8rc2 are:

    +
      +
    • Improved repr of sentinel objects
      • +
    • ANY can be used for comparisons against call objects
      • +
    • The return value of MagicMock.__iter__ method can be set to +any iterable and isn’t required to be an iterator
      • +
    +

    Full List of changes since 0.7:

    +

    mock 0.8.0 is the last version that will support Python 2.4.

    +
      +
    • Addition of mock_calls list for all calls (including magic +methods and chained calls)
      • +
    • patch() and patch.object() now create a MagicMock +instead of a Mock by default
      • +
    • The patchers (patch, patch.object and patch.dict), plus Mock and +MagicMock, take arbitrary keyword arguments for configuration
      • +
    • New mock method configure_mock() for setting attributes and +return values / side effects on the mock and its attributes
      • +
    • New mock assert methods assert_any_call() and +assert_has_calls()
      • +
    • Implemented Autospeccing (recursive, lazy speccing of mocks with +mocked signatures for functions/methods), as the autospec argument to +patch
      • +
    • Added the create_autospec() function for manually creating +‘auto-specced’ mocks
      • +
    • patch.multiple() for doing multiple patches in a single call, using +keyword arguments
      • +
    • Setting side_effect to an iterable will cause calls to the mock +to return the next value from the iterable
      • +
    • New new_callable argument to patch and patch.object allowing you to +pass in a class or callable object (instead of MagicMock) that will be +called to replace the object being patched
      • +
    • Addition of NonCallableMock and NonCallableMagicMock, mocks +without a __call__ method
      • +
    • Addition of mock_add_spec() method for adding (or changing) a +spec on an existing mock
      • +
    • Protocol methods on MagicMock are magic mocks, and are created +lazily on first lookup. This means the result of calling a protocol method is +a MagicMock instead of a Mock as it was previously
      • +
    • Addition of attach_mock() method
      • +
    • Added ANY for ignoring arguments in assert_called_with() +calls
      • +
    • Addition of call helper object
      • +
    • Improved repr for mocks
      • +
    • Improved repr for Mock.call_args and entries in +Mock.call_args_list, Mock.method_calls and +Mock.mock_calls
      • +
    • Improved repr for sentinel objects
      • +
    • patch lookup is done at use time not at decoration time
      • +
    • In Python 2.6 or more recent, dir on a mock will report all the dynamically +created attributes (or the full list of attributes if there is a spec) as +well as all the mock methods and attributes.
      • +
    • Module level FILTER_DIR added to control whether dir(mock) filters +private attributes. True by default.
      • +
    • patch.TEST_PREFIX for controlling how patchers recognise test methods when +used to decorate a class
      • +
    • Support for using Java exceptions as a side_effect on Jython
      • +
    • Mock call lists (call_args_list, method_calls & mock_calls) are now +custom list objects that allow membership tests for “sub lists” and have +a nicer representation if you str or print them
      • +
    • Mocks attached as attributes or return values to other mocks have calls +recorded in method_calls and mock_calls of the parent (unless a name is +already set on the child)
      • +
    • Improved failure messages for assert_called_with and +assert_called_once_with
      • +
    • The return value of the MagicMock __iter__ method can be set to +any iterable and isn’t required to be an iterator
      • +
    • Added the Mock API (assert_called_with etc) to functions created by +mocksignature()
      • +
    • Tuples as well as lists can be used to specify allowed methods for spec & +spec_set arguments
      • +
    • Calling stop on an unstarted patcher fails with a more meaningful error +message
      • +
    • Renamed the internal classes Sentinel and SentinelObject to prevent abuse
      • +
    • BUGFIX: an error creating a patch, with nested patch decorators, won’t leave +patches in place
      • +
    • BUGFIX: __truediv__ and __rtruediv__ not available as magic methods on +mocks in Python 3
      • +
    • BUGFIX: assert_called_with / assert_called_once_with can be used with +self as a keyword argument
      • +
    • BUGFIX: when patching a class with an explicit spec / spec_set (not a +boolean) it applies “spec inheritance” to the return value of the created +mock (the “instance”)
      • +
    • BUGFIX: remove the __unittest marker causing traceback truncation
      • +
    • Removal of deprecated patch_object
      • +
    • Private attributes _name, _methods, ‘_children’, _wraps and _parent +(etc) renamed to reduce likelihood of clash with user attributes.
      • +
    • Added license file to the distribution
      • +
    +
    +
    +

    2012/01/10 Version 0.8.0 release candidate 2¶

    +
      +
    • Removed the configure keyword argument to create_autospec and allow +arbitrary keyword arguments (for the Mock constructor) instead
      • +
    • Fixed ANY equality with some types in assert_called_with calls
      • +
    • Switched to a standard Sphinx theme (compatible with +readthedocs.org)
      • +
    +
    +
    +

    2011/12/29 Version 0.8.0 release candidate 1¶

    +
      +
    • create_autospec on the return value of a mocked class will use __call__ +for the signature rather than __init__
      • +
    • Performance improvement instantiating Mock and MagicMock
      • +
    • Mocks used as magic methods have the same type as their parent instead of +being hardcoded to MagicMock
      • +
    +

    Special thanks to Julian Berman for his help with diagnosing and improving +performance in this release.

    +
    +
    +

    2011/10/09 Version 0.8.0 beta 4¶

    +
      +
    • patch lookup is done at use time not at decoration time
      • +
    • When attaching a Mock to another Mock as a magic method, calls are recorded +in mock_calls
      • +
    • Addition of attach_mock method
      • +
    • Renamed the internal classes Sentinel and SentinelObject to prevent abuse
      • +
    • BUGFIX: various issues around circular references with mocks (setting a mock +return value to be itself etc)
      • +
    +
    +
    +

    2011/08/15 Version 0.8.0 beta 3¶

    +
      +
    • Mocks attached as attributes or return values to other mocks have calls +recorded in method_calls and mock_calls of the parent (unless a name is +already set on the child)
      • +
    • Addition of mock_add_spec method for adding (or changing) a spec on an +existing mock
      • +
    • Improved repr for Mock.call_args and entries in Mock.call_args_list, +Mock.method_calls and Mock.mock_calls
      • +
    • Improved repr for mocks
      • +
    • BUGFIX: minor fixes in the way mock_calls is worked out, +especially for “intermediate” mocks in a call chain
      • +
    +
    +
    +

    2011/08/05 Version 0.8.0 beta 2¶

    +
      +
    • Setting side_effect to an iterable will cause calls to the mock to return +the next value from the iterable
      • +
    • Added assert_any_call method
      • +
    • Moved assert_has_calls from call lists onto mocks
      • +
    • BUGFIX: call_args and all members of call_args_list are two tuples of +(args, kwargs) again instead of three tuples of (name, args, kwargs)
      • +
    +
    +
    +

    2011/07/25 Version 0.8.0 beta 1¶

    +
      +
    • patch.TEST_PREFIX for controlling how patchers recognise test methods when +used to decorate a class
      • +
    • Mock call lists (call_args_list, method_calls & mock_calls) are now +custom list objects that allow membership tests for “sub lists” and have +an assert_has_calls method for unordered call checks
      • +
    • callargs changed to always be a three-tuple of (name, args, kwargs)
      • +
    • Addition of mock_calls list for all calls (including magic methods and +chained calls)
      • +
    • Extension of call object to support chained calls and callargs for better +comparisons with or without names. call object has a call_list method for +chained calls
      • +
    • Added the public instance argument to create_autospec
      • +
    • Support for using Java exceptions as a side_effect on Jython
      • +
    • Improved failure messages for assert_called_with and +assert_called_once_with
      • +
    • Tuples as well as lists can be used to specify allowed methods for spec & +spec_set arguments
      • +
    • BUGFIX: Fixed bug in patch.multiple for argument passing when creating +mocks
      • +
    • Added license file to the distribution
      • +
    +
    +
    +

    2011/07/16 Version 0.8.0 alpha 2¶

    +
      +
    • patch.multiple for doing multiple patches in a single call, using keyword +arguments
      • +
    • New new_callable argument to patch and patch.object allowing you to +pass in a class or callable object (instead of MagicMock) that will be +called to replace the object being patched
      • +
    • Addition of NonCallableMock and NonCallableMagicMock, mocks without a +__call__ method
      • +
    • Mocks created by patch have a MagicMock as the return_value where a +class is being patched
      • +
    • create_autospec can create non-callable mocks for non-callable objects. +return_value mocks of classes will be non-callable unless the class has +a __call__ method
      • +
    • autospec creates a MagicMock without a spec for properties and slot +descriptors, because we don’t know the type of object they return
      • +
    • Removed the “inherit” argument from create_autospec
      • +
    • Calling stop on an unstarted patcher fails with a more meaningful error +message
      • +
    • BUGFIX: an error creating a patch, with nested patch decorators, won’t leave +patches in place
      • +
    • BUGFIX: __truediv__ and __rtruediv__ not available as magic methods on +mocks in Python 3
      • +
    • BUGFIX: assert_called_with / assert_called_once_with can be used with +self as a keyword argument
      • +
    • BUGFIX: autospec for functions / methods with an argument named self that +isn’t the first argument no longer broken
      • +
    • BUGFIX: when patching a class with an explicit spec / spec_set (not a +boolean) it applies “spec inheritance” to the return value of the created +mock (the “instance”)
      • +
    • BUGFIX: remove the __unittest marker causing traceback truncation
      • +
    +
    +
    +

    2011/06/14 Version 0.8.0 alpha 1¶

    +

    mock 0.8.0 is the last version that will support Python 2.4.

    +
      +

    • The patchers (patch, patch.object and patch.dict), plus Mock and +MagicMock, take arbitrary keyword arguments for configuration

      +
      • +

    • New mock method configure_mock for setting attributes and return values / +side effects on the mock and its attributes

      +
      • +

    • In Python 2.6 or more recent, dir on a mock will report all the dynamically +created attributes (or the full list of attributes if there is a spec) as +well as all the mock methods and attributes.

      +
      • +

    • Module level FILTER_DIR added to control whether dir(mock) filters +private attributes. True by default. Note that vars(Mock()) can still be +used to get all instance attributes and dir(type(Mock()) will still return +all the other attributes (irrespective of FILTER_DIR)

      +
      • +

    • patch and patch.object now create a MagicMock instead of a Mock by +default

      +
      • +

    • Added ANY for ignoring arguments in assert_called_with calls

      +
      • +

    • Addition of call helper object

      +
      • +

    • Protocol methods on MagicMock are magic mocks, and are created lazily on +first lookup. This means the result of calling a protocol method is a +MagicMock instead of a Mock as it was previously

      +
      • +

    • Added the Mock API (assert_called_with etc) to functions created by +mocksignature

      +
      • +

    • Private attributes _name, _methods, ‘_children’, _wraps and _parent +(etc) renamed to reduce likelihood of clash with user attributes.

      +
      • +

    • Implemented auto-speccing (recursive, lazy speccing of mocks with mocked +signatures for functions/methods)

      +

      Limitations:

      +
        +
      • Doesn’t mock magic methods or attributes (it creates MagicMocks, so the +magic methods are there, they just don’t have the signature mocked nor +are attributes followed)
        • +
      • Doesn’t mock function / method attributes
        • +
      • Uses object traversal on the objects being mocked to determine types - so +properties etc may be triggered
        • +
      • The return value of mocked classes (the ‘instance’) has the same call +signature as the class __init__ (as they share the same spec)
        • +
      +

      You create auto-specced mocks by passing autospec=True to patch.

      +

      Note that attributes that are None are special cased and mocked without a +spec (so any attribute / method can be used). This is because None is +typically used as a default value for attributes that may be of some other +type, and as we don’t know what type that may be we allow all access.

      +

      Note that the autospec option to patch obsoletes the mocksignature +option.

      +
      • +

    • Added the create_autospec function for manually creating ‘auto-specced’ +mocks

      +
      • +

    • Removal of deprecated patch_object

      +
      • +
    +
    +
    +

    2011/05/30 Version 0.7.2¶

    +
      +
    • BUGFIX: instances of list subclasses can now be used as mock specs
      • +
    • BUGFIX: MagicMock equality / inequality protocol methods changed to use the +default equality / inequality. This is done through a side_effect on +the mocks used for __eq__ / __ne__
      • +
    +
    +
    +

    2011/05/06 Version 0.7.1¶

    +

    Package fixes contributed by Michael Fladischer. No code changes.

    +
      +
    • Include template in package
      • +
    • Use isolated binaries for the tox tests
      • +
    • Unset executable bit on docs
      • +
    • Fix DOS line endings in getting-started.txt
      • +
    +
    +
    +

    2011/03/05 Version 0.7.0¶

    +

    No API changes since 0.7.0 rc1. Many documentation changes including a stylish +new Sphinx theme.

    +

    The full set of changes since 0.6.0 are:

    +
      +
    • Python 3 compatibility
      • +
    • Ability to mock magic methods with Mock and addition of MagicMock +with pre-created magic methods
      • +
    • Addition of mocksignature and mocksignature argument to patch and +patch.object
      • +
    • Addition of patch.dict for changing dictionaries during a test
      • +
    • Ability to use patch, patch.object and patch.dict as class decorators
      • +
    • Renamed patch_object to patch.object (patch_object is +deprecated)
      • +
    • Addition of soft comparisons: call_args, call_args_list and method_calls +now return tuple-like objects which compare equal even when empty args +or kwargs are skipped
      • +
    • patchers (patch, patch.object and patch.dict) have start and stop +methods
      • +
    • Addition of assert_called_once_with method
      • +
    • Mocks can now be named (name argument to constructor) and the name is used +in the repr
      • +
    • repr of a mock with a spec includes the class name of the spec
      • +
    • assert_called_with works with python -OO
      • +
    • New spec_set keyword argument to Mock and patch. If used, +attempting to set an attribute on a mock not on the spec will raise an +AttributeError
      • +
    • Mocks created with a spec can now pass isinstance tests (__class__ +returns the type of the spec)
      • +
    • Added docstrings to all objects
      • +
    • Improved failure message for Mock.assert_called_with when the mock +has not been called at all
      • +
    • Decorated functions / methods have their docstring and __module__ +preserved on Python 2.4.
      • +
    • BUGFIX: mock.patch now works correctly with certain types of objects that +proxy attribute access, like the django settings object
      • +
    • BUGFIX: mocks are now copyable (thanks to Ned Batchelder for reporting and +diagnosing this)
      • +
    • BUGFIX: spec=True works with old style classes
      • +
    • BUGFIX: help(mock) works now (on the module). Can no longer use __bases__ +as a valid sentinel name (thanks to Stephen Emslie for reporting and +diagnosing this)
      • +
    • BUGFIX: side_effect now works with BaseException exceptions like +KeyboardInterrupt
      • +
    • BUGFIX: reset_mock caused infinite recursion when a mock is set as its own +return value
      • +
    • BUGFIX: patching the same object twice now restores the patches correctly
      • +
    • with statement tests now skipped on Python 2.4
      • +
    • Tests require unittest2 (or unittest2-py3k) to run
      • +
    • Tested with tox on Python 2.4 - 3.2, +jython and pypy (excluding 3.0)
      • +
    • Added ‘build_sphinx’ command to setup.py (requires setuptools or distribute) +Thanks to Florian Bauer
      • +
    • Switched from subversion to mercurial for source code control
      • +
    • Konrad Delong added as co-maintainer
      • +
    +
    +
    +

    2011/02/16 Version 0.7.0 RC 1¶

    +

    Changes since beta 4:

    +
      +
    • Tested with jython, pypy and Python 3.2 and 3.1
      • +
    • Decorated functions / methods have their docstring and __module__ +preserved on Python 2.4
      • +
    • BUGFIX: mock.patch now works correctly with certain types of objects that +proxy attribute access, like the django settings object
      • +
    • BUGFIX: reset_mock caused infinite recursion when a mock is set as its own +return value
      • +
    +
    +
    +

    2010/11/12 Version 0.7.0 beta 4¶

    +
      +
    • patchers (patch, patch.object and patch.dict) have start and stop +methods
      • +
    • Addition of assert_called_once_with method
      • +
    • repr of a mock with a spec includes the class name of the spec
      • +
    • assert_called_with works with python -OO
      • +
    • New spec_set keyword argument to Mock and patch. If used, +attempting to set an attribute on a mock not on the spec will raise an +AttributeError
      • +
    • Attributes and return value of a MagicMock are MagicMock objects
      • +
    • Attempting to set an unsupported magic method now raises an AttributeError
      • +
    • patch.dict works as a class decorator
      • +
    • Switched from subversion to mercurial for source code control
      • +
    • BUGFIX: mocks are now copyable (thanks to Ned Batchelder for reporting and +diagnosing this)
      • +
    • BUGFIX: spec=True works with old style classes
      • +
    • BUGFIX: mocksignature=True can now patch instance methods via +patch.object
      • +
    +
    +
    +

    2010/09/18 Version 0.7.0 beta 3¶

    +
      +
    • Using spec with MagicMock only pre-creates magic methods in the spec
      • +
    • Setting a magic method on a mock with a spec can only be done if the +spec has that method
      • +
    • Mocks can now be named (name argument to constructor) and the name is used +in the repr
      • +
    • mocksignature can now be used with classes (signature based on __init__) +and callable objects (signature based on __call__)
      • +
    • Mocks created with a spec can now pass isinstance tests (__class__ +returns the type of the spec)
      • +
    • Default numeric value for MagicMock is 1 rather than zero (because the +MagicMock bool defaults to True and 0 is False)
      • +
    • Improved failure message for assert_called_with() when the mock +has not been called at all
      • +
    • Adding the following to the set of supported magic methods:
        +
      • __getformat__ and __setformat__
        • +
      • pickle methods
        • +
      • __trunc__, __ceil__ and __floor__
        • +
      • __sizeof__
        • +
      +
      • +
    • Added ‘build_sphinx’ command to setup.py (requires setuptools or distribute) +Thanks to Florian Bauer
      • +
    • with statement tests now skipped on Python 2.4
      • +
    • Tests require unittest2 to run on Python 2.7
      • +
    • Improved several docstrings and documentation
      • +
    +
    +
    +

    2010/06/23 Version 0.7.0 beta 2¶

    +
      +
    • patch.dict() works as a context manager as well as a decorator
      • +
    • patch.dict takes a string to specify dictionary as well as a dictionary +object. If a string is supplied the name specified is imported
      • +
    • BUGFIX: patch.dict restores dictionary even when an exception is raised
      • +
    +
    +
    +

    2010/06/22 Version 0.7.0 beta 1¶

    +
      +
    • Addition of mocksignature()
      • +
    • Ability to mock magic methods
      • +
    • Ability to use patch and patch.object as class decorators
      • +
    • Renamed patch_object to patch.object() (patch_object is +deprecated)
      • +
    • Addition of MagicMock class with all magic methods pre-created for you
      • +
    • Python 3 compatibility (tested with 3.2 but should work with 3.0 & 3.1 as +well)
      • +
    • Addition of patch.dict() for changing dictionaries during a test
      • +
    • Addition of mocksignature argument to patch and patch.object
      • +
    • help(mock) works now (on the module). Can no longer use __bases__ +as a valid sentinel name (thanks to Stephen Emslie for reporting and +diagnosing this)
      • +
    • Addition of soft comparisons: call_args, call_args_list and method_calls +now return tuple-like objects which compare equal even when empty args +or kwargs are skipped
      • +
    • Added docstrings.
      • +
    • BUGFIX: side_effect now works with BaseException exceptions like +KeyboardInterrupt
      • +
    • BUGFIX: patching the same object twice now restores the patches correctly
      • +
    • The tests now require unittest2 +to run
      • +
    • Konrad Delong added as co-maintainer
      • +
    +
    +
    +

    2009/08/22 Version 0.6.0¶

    +
      +
    • New test layout compatible with test discovery
      • +
    • Descriptors (static methods / class methods etc) can now be patched and +restored correctly
      • +
    • Mocks can raise exceptions when called by setting side_effect to an +exception class or instance
      • +
    • Mocks that wrap objects will not pass on calls to the underlying object if +an explicit return_value is set
      • +
    +
    +
    +

    2009/04/17 Version 0.5.0¶

    +
      +
    • Made DEFAULT part of the public api.
      • +
    • Documentation built with Sphinx.
      • +
    • side_effect is now called with the same arguments as the mock is called with and +if returns a non-DEFAULT value that is automatically set as the mock.return_value.
      • +
    • wraps keyword argument used for wrapping objects (and passing calls through to the wrapped object).
      • +
    • Mock.reset renamed to Mock.reset_mock, as reset is a common API name.
      • +
    • patch / patch_object are now context managers and can be used with with.
      • +
    • A new ‘create’ keyword argument to patch and patch_object that allows them to patch +(and unpatch) attributes that don’t exist. (Potentially unsafe to use - it can allow +you to have tests that pass when they are testing an API that doesn’t exist - use at +your own risk!)
      • +
    • The methods keyword argument to Mock has been removed and merged with spec. The spec +argument can now be a list of methods or an object to take the spec from.
      • +
    • Nested patches may now be applied in a different order (created mocks passed +in the opposite order). This is actually a bugfix.
      • +
    • patch and patch_object now take a spec keyword argument. If spec is +passed in as ‘True’ then the Mock created will take the object it is replacing +as its spec object. If the object being replaced is a class, then the return +value for the mock will also use the class as a spec.
      • +
    • A Mock created without a spec will not attempt to mock any magic methods / attributes +(they will raise an AttributeError instead).
      • +
    +
    +
    +

    2008/10/12 Version 0.4.0¶

    +
      +

    • Default return value is now a new mock rather than None

      +
      • +

    • return_value added as a keyword argument to the constructor

      +
      • +

    • New method ‘assert_called_with’

      +
      • +

    • Added ‘side_effect’ attribute / keyword argument called when mock is called

      +
      • +

    • patch decorator split into two decorators:

      +
      +
        +
      • patch_object which takes an object and an attribute name to patch +(plus optionally a value to patch with which defaults to a mock object)
        • +
      • patch which takes a string specifying a target to patch; in the form +‘package.module.Class.attribute’. (plus optionally a value to +patch with which defaults to a mock object)
        • +
      +
      +
      • +

    • Can now patch objects with None

      +
      • +

    • Change to patch for nose compatibility with error reporting in wrapped functions

      +
      • +

    • Reset no longer clears children / return value etc - it just resets +call count and call args. It also calls reset on all children (and +the return value if it is a mock).

      +
      • +
    +

    Thanks to Konrad Delong, Kevin Dangoor and others for patches and suggestions.

    +
    +
    +

    2007/12/03 Version 0.3.1¶

    +

    patch maintains the name of decorated functions for compatibility with nose +test autodiscovery.

    +

    Tests decorated with patch that use the two argument form (implicit mock +creation) will receive the mock(s) passed in as extra arguments.

    +

    Thanks to Kevin Dangoor for these changes.

    +
    +
    +

    2007/11/30 Version 0.3.0¶

    +

    Removed patch_module. patch can now take a string as the first +argument for patching modules.

    +

    The third argument to patch is optional - a mock will be created by +default if it is not passed in.

    +
    +
    +

    2007/11/21 Version 0.2.1¶

    +

    Bug fix, allows reuse of functions decorated with patch and patch_module.

    +
    +
    +

    2007/11/20 Version 0.2.0¶

    +

    Added spec keyword argument for creating Mock objects from a +specification object.

    +

    Added patch and patch_module monkey patching decorators.

    +

    Added sentinel for convenient access to unique objects.

    +

    Distribution includes unit tests.

    +
    +
    +

    2007/11/19 Version 0.1.0¶

    +

    Initial release.

    +
    +
    +
    +

    TODO and Limitations¶

    +

    Contributions, bug reports and comments welcomed!

    +

    Feature requests and bug reports are handled on the issue tracker:

    +
    +
    +

    wraps is not integrated with magic methods.

    +

    patch could auto-do the patching in the constructor and unpatch in the +destructor. This would be useful in itself, but violates TOOWTDI and would be +unsafe for IronPython & PyPy (non-deterministic calling of destructors). +Destructors aren’t called in CPython where there are cycles, but a weak +reference with a callback can be used to get round this.

    +

    Mock has several attributes. This makes it unsuitable for mocking objects +that use these attribute names. A way round this would be to provide methods +that hide these attributes when needed. In 0.8 many, but not all, of these +attributes are renamed to gain a _mock prefix, making it less likely that +they will clash. Any outstanding attributes that haven’t been modified with +the prefix should be changed.

    +

    If a patch is started using patch.start and then not stopped correctly then +the unpatching is not done. Using weak references it would be possible to +detect and fix this when the patch object itself is garbage collected. This +would be tricky to get right though.

    +

    When a Mock is created by patch, arbitrary keywords can be used to set +attributes. If patch is created with a spec, and is replacing a class, then +a return_value mock is created. The keyword arguments are not applied to the +child mock, but could be.

    +

    When mocking a class with patch, passing in spec=True or autospec=True, +the mock class has an instance created from the same spec. Should this be the +default behaviour for mocks anyway (mock return values inheriting the spec +from their parent), or should it be controlled by an additional keyword +argument (inherit) to the Mock constructor? create_autospec does this, so +an additional keyword argument to Mock is probably unnecessary.

    +

    The mocksignature argument to patch with a non Mock passed into +new_callable will probably cause an error. Should it just be invalid?

    +

    Note that NonCallableMock and NonCallableMagicMock still have the unused +(and unusable) attributes: return_value, side_effect, call_count, +call_args and call_args_list. These could be removed or raise errors on +getting / setting. They also have the assert_called_with and +assert_called_once_with methods. Removing these would be pointless as +fetching them would create a mock (attribute) that could be called without +error.

    +

    Some outstanding technical debt. The way autospeccing mocks function +signatures was copied and modified from mocksignature. This could all be +refactored into one set of functions instead of two. The way we tell if +patchers are started and if a patcher is being used for a patch.multiple +call are both horrible. There are now a host of helper functions that should +be rationalised. (Probably time to split mock into a package instead of a +module.)

    +

    Passing arbitrary keyword arguments to create_autospec, or patch with +autospec, when mocking a function works fine. However, the arbitrary +attributes are set on the created mock - but create_autospec returns a +real function (which doesn’t have those attributes). However, what is the use +case for using autospec to create functions with attributes that don’t exist +on the original?

    +

    mocksignature, plus the call_args_list and method_calls attributes of +Mock could all be deprecated.

    +
    + + +
    +
    +
    +
    +
    +

    Table Of Contents

    + + +

    Previous topic

    +

    Mock Library Comparison

    +

    This Page

    + + + +
    +
    +
    +
    +
    +

    Navigation

    + +
    +
    + © Copyright 2007-2012, Michael Foord & the mock team. + Last updated on Oct 07, 2012. + Created using Sphinx 1.1.3. +
    + + \ No newline at end of file diff --git a/python/mock-1.0.0/html/compare.html b/python/mock-1.0.0/html/compare.html new file mode 100644 index 000000000..bfc9d519a --- /dev/null +++ b/python/mock-1.0.0/html/compare.html @@ -0,0 +1,672 @@ + + + + + + + + + Mock Library Comparison — Mock 1.0.0 documentation + + + + + + + + + + + + + +
    +

    Navigation

    + +
    + +
    +
    +
    +
    + +
    +

    Mock Library Comparison¶

    +

    A side-by-side comparison of how to accomplish some basic tasks with mock and +some other popular Python mocking libraries and frameworks.

    +

    These are:

    + +

    Popular python mocking frameworks not yet represented here include +MiniMock.

    +

    pMock (last release 2004 and doesn’t import +in recent versions of Python) and +python-mock (last release 2005) are +intentionally omitted.

    +
    +

    Note

    +

    A more up to date, and tested for all mock libraries (only the mock +examples on this page can be executed as doctests) version of this +comparison is maintained by Gary Bernhardt:

    + +
    +

    This comparison is by no means complete, and also may not be fully idiomatic +for all the libraries represented. Please contribute corrections, missing +comparisons, or comparisons for additional libraries to the mock issue +tracker.

    +

    This comparison page was originally created by the Mox project and then extended for +flexmock and mock by +Herman Sheremetyev. Dingus examples written by Gary Bernhadt. fudge examples +provided by Kumar McMillan.

    +
    +

    Note

    +

    The examples tasks here were originally created by Mox which is a mocking +framework rather than a library like mock. The tasks shown naturally +exemplify tasks that frameworks are good at and not the ones they make +harder. In particular you can take a Mock or MagicMock object and use +it in any way you want with no up-front configuration. The same is also +true for Dingus.

    +

    The examples for mock here assume version 0.7.0.

    +
    +
    +

    Simple fake object¶

    +
    >>> # mock
+>>> my_mock = mock.Mock()
+>>> my_mock.some_method.return_value = "calculated value"
+>>> my_mock.some_attribute = "value"
+>>> assertEqual("calculated value", my_mock.some_method())
+>>> assertEqual("value", my_mock.some_attribute)
+
    +
    +
    # Flexmock
+mock = flexmock(some_method=lambda: "calculated value", some_attribute="value")
+assertEqual("calculated value", mock.some_method())
+assertEqual("value", mock.some_attribute)
+
+# Mox
+mock = mox.MockAnything()
+mock.some_method().AndReturn("calculated value")
+mock.some_attribute = "value"
+mox.Replay(mock)
+assertEqual("calculated value", mock.some_method())
+assertEqual("value", mock.some_attribute)
+
+# Mocker
+mock = mocker.mock()
+mock.some_method()
+mocker.result("calculated value")
+mocker.replay()
+mock.some_attribute = "value"
+assertEqual("calculated value", mock.some_method())
+assertEqual("value", mock.some_attribute)
+
    +
    +
    >>> # Dingus
+>>> my_dingus = dingus.Dingus(some_attribute="value",
+...                           some_method__returns="calculated value")
+>>> assertEqual("calculated value", my_dingus.some_method())
+>>> assertEqual("value", my_dingus.some_attribute)
+
    +
    +
    >>> # fudge
+>>> my_fake = (fudge.Fake()
+...            .provides('some_method')
+...            .returns("calculated value")
+...            .has_attr(some_attribute="value"))
+...
+>>> assertEqual("calculated value", my_fake.some_method())
+>>> assertEqual("value", my_fake.some_attribute)
+
    +
    +
    +
    +

    Simple mock¶

    +
    >>> # mock
+>>> my_mock = mock.Mock()
+>>> my_mock.some_method.return_value = "value"
+>>> assertEqual("value", my_mock.some_method())
+>>> my_mock.some_method.assert_called_once_with()
+
    +
    +
    # Flexmock
+mock = flexmock()
+mock.should_receive("some_method").and_return("value").once
+assertEqual("value", mock.some_method())
+
+# Mox
+mock = mox.MockAnything()
+mock.some_method().AndReturn("value")
+mox.Replay(mock)
+assertEqual("value", mock.some_method())
+mox.Verify(mock)
+
+# Mocker
+mock = mocker.mock()
+mock.some_method()
+mocker.result("value")
+mocker.replay()
+assertEqual("value", mock.some_method())
+mocker.verify()
+
    +
    +
    >>> # Dingus
+>>> my_dingus = dingus.Dingus(some_method__returns="value")
+>>> assertEqual("value", my_dingus.some_method())
+>>> assert my_dingus.some_method.calls().once()
+
    +
    +
    >>> # fudge
+>>> @fudge.test
+... def test():
+...     my_fake = (fudge.Fake()
+...                .expects('some_method')
+...                .returns("value")
+...                .times_called(1))
+...
+>>> test()
+Traceback (most recent call last):
+...
+AssertionError: fake:my_fake.some_method() was not called
+
    +
    +
    +
    +

    Creating partial mocks¶

    +
    >>> # mock
+>>> SomeObject.some_method = mock.Mock(return_value='value')
+>>> assertEqual("value", SomeObject.some_method())
+
    +
    +
    # Flexmock
+flexmock(SomeObject).should_receive("some_method").and_return('value')
+assertEqual("value", mock.some_method())
+
+# Mox
+mock = mox.MockObject(SomeObject)
+mock.some_method().AndReturn("value")
+mox.Replay(mock)
+assertEqual("value", mock.some_method())
+mox.Verify(mock)
+
+# Mocker
+mock = mocker.mock(SomeObject)
+mock.Get()
+mocker.result("value")
+mocker.replay()
+assertEqual("value", mock.some_method())
+mocker.verify()
+
    +
    +
    >>> # Dingus
+>>> object = SomeObject
+>>> object.some_method = dingus.Dingus(return_value="value")
+>>> assertEqual("value", object.some_method())
+
    +
    +
    >>> # fudge
+>>> fake = fudge.Fake().is_callable().returns("<fudge-value>")
+>>> with fudge.patched_context(SomeObject, 'some_method', fake):
+...     s = SomeObject()
+...     assertEqual("<fudge-value>", s.some_method())
+...
+
    +
    +
    +
    +

    Ensure calls are made in specific order¶

    +
    >>> # mock
+>>> my_mock = mock.Mock(spec=SomeObject)
+>>> my_mock.method1()
+<Mock name='mock.method1()' id='...'>
+>>> my_mock.method2()
+<Mock name='mock.method2()' id='...'>
+>>> assertEqual(my_mock.mock_calls, [call.method1(), call.method2()])
+
    +
    +
    # Flexmock
+mock = flexmock(SomeObject)
+mock.should_receive('method1').once.ordered.and_return('first thing')
+mock.should_receive('method2').once.ordered.and_return('second thing')
+
+# Mox
+mock = mox.MockObject(SomeObject)
+mock.method1().AndReturn('first thing')
+mock.method2().AndReturn('second thing')
+mox.Replay(mock)
+mox.Verify(mock)
+
+# Mocker
+mock = mocker.mock()
+with mocker.order():
+    mock.method1()
+    mocker.result('first thing')
+    mock.method2()
+    mocker.result('second thing')
+    mocker.replay()
+    mocker.verify()
+
    +
    +
    >>> # Dingus
+>>> my_dingus = dingus.Dingus()
+>>> my_dingus.method1()
+<Dingus ...>
+>>> my_dingus.method2()
+<Dingus ...>
+>>> assertEqual(['method1', 'method2'], [call.name for call in my_dingus.calls])
+
    +
    +
    >>> # fudge
+>>> @fudge.test
+... def test():
+...     my_fake = (fudge.Fake()
+...                .remember_order()
+...                .expects('method1')
+...                .expects('method2'))
+...     my_fake.method2()
+...     my_fake.method1()
+...
+>>> test()
+Traceback (most recent call last):
+...
+AssertionError: Call #1 was fake:my_fake.method2(); Expected: #1 fake:my_fake.method1(), #2 fake:my_fake.method2(), end
+
    +
    +
    +
    +

    Raising exceptions¶

    +
    >>> # mock
+>>> my_mock = mock.Mock()
+>>> my_mock.some_method.side_effect = SomeException("message")
+>>> assertRaises(SomeException, my_mock.some_method)
+
    +
    +
    # Flexmock
+mock = flexmock()
+mock.should_receive("some_method").and_raise(SomeException("message"))
+assertRaises(SomeException, mock.some_method)
+
+# Mox
+mock = mox.MockAnything()
+mock.some_method().AndRaise(SomeException("message"))
+mox.Replay(mock)
+assertRaises(SomeException, mock.some_method)
+mox.Verify(mock)
+
+# Mocker
+mock = mocker.mock()
+mock.some_method()
+mocker.throw(SomeException("message"))
+mocker.replay()
+assertRaises(SomeException, mock.some_method)
+mocker.verify()
+
    +
    +
    >>> # Dingus
+>>> my_dingus = dingus.Dingus()
+>>> my_dingus.some_method = dingus.exception_raiser(SomeException)
+>>> assertRaises(SomeException, my_dingus.some_method)
+
    +
    +
    >>> # fudge
+>>> my_fake = (fudge.Fake()
+...            .is_callable()
+...            .raises(SomeException("message")))
+...
+>>> my_fake()
+Traceback (most recent call last):
+...
+SomeException: message
+
    +
    +
    +
    +

    Override new instances of a class¶

    +
    >>> # mock
+>>> with mock.patch('somemodule.Someclass') as MockClass:
+...     MockClass.return_value = some_other_object
+...     assertEqual(some_other_object, somemodule.Someclass())
+...
+
    +
    +
    # Flexmock
+flexmock(some_module.SomeClass, new_instances=some_other_object)
+assertEqual(some_other_object, some_module.SomeClass())
+
+# Mox
+# (you will probably have mox.Mox() available as self.mox in a real test)
+mox.Mox().StubOutWithMock(some_module, 'SomeClass', use_mock_anything=True)
+some_module.SomeClass().AndReturn(some_other_object)
+mox.ReplayAll()
+assertEqual(some_other_object, some_module.SomeClass())
+
+# Mocker
+instance = mocker.mock()
+klass = mocker.replace(SomeClass, spec=None)
+klass('expected', 'args')
+mocker.result(instance)
+
    +
    +
    >>> # Dingus
+>>> MockClass = dingus.Dingus(return_value=some_other_object)
+>>> with dingus.patch('somemodule.SomeClass', MockClass):
+...     assertEqual(some_other_object, somemodule.SomeClass())
+...
+
    +
    +
    >>> # fudge
+>>> @fudge.patch('somemodule.SomeClass')
+... def test(FakeClass):
+...     FakeClass.is_callable().returns(some_other_object)
+...     assertEqual(some_other_object, somemodule.SomeClass())
+...
+>>> test()
+
    +
    +
    +
    +

    Call the same method multiple times¶

    +
    +

    Note

    +

    You don’t need to do any configuration to call mock.Mock() methods +multiple times. Attributes like call_count, call_args_list and +method_calls provide various different ways of making assertions about +how the mock was used.

    +
    +
    >>> # mock
+>>> my_mock = mock.Mock()
+>>> my_mock.some_method()
+<Mock name='mock.some_method()' id='...'>
+>>> my_mock.some_method()
+<Mock name='mock.some_method()' id='...'>
+>>> assert my_mock.some_method.call_count >= 2
+
    +
    +
    # Flexmock # (verifies that the method gets called at least twice)
+flexmock(some_object).should_receive('some_method').at_least.twice
+
+# Mox
+# (does not support variable number of calls, so you need to create a new entry for each explicit call)
+mock = mox.MockObject(some_object)
+mock.some_method(mox.IgnoreArg(), mox.IgnoreArg())
+mock.some_method(mox.IgnoreArg(), mox.IgnoreArg())
+mox.Replay(mock)
+mox.Verify(mock)
+
+# Mocker
+# (TODO)
+
    +
    +
    >>> # Dingus
+>>> my_dingus = dingus.Dingus()
+>>> my_dingus.some_method()
+<Dingus ...>
+>>> my_dingus.some_method()
+<Dingus ...>
+>>> assert len(my_dingus.calls('some_method')) == 2
+
    +
    +
    >>> # fudge
+>>> @fudge.test
+... def test():
+...     my_fake = fudge.Fake().expects('some_method').times_called(2)
+...     my_fake.some_method()
+...
+>>> test()
+Traceback (most recent call last):
+...
+AssertionError: fake:my_fake.some_method() was called 1 time(s). Expected 2.
+
    +
    +
    +
    +

    Mock chained methods¶

    +
    >>> # mock
+>>> my_mock = mock.Mock()
+>>> method3 = my_mock.method1.return_value.method2.return_value.method3
+>>> method3.return_value = 'some value'
+>>> assertEqual('some value', my_mock.method1().method2().method3(1, 2))
+>>> method3.assert_called_once_with(1, 2)
+
    +
    +
    # Flexmock
+# (intermediate method calls are automatically assigned to temporary fake objects
+# and can be called with any arguments)
+flexmock(some_object).should_receive(
+    'method1.method2.method3'
+).with_args(arg1, arg2).and_return('some value')
+assertEqual('some_value', some_object.method1().method2().method3(arg1, arg2))
+
    +
    +
    # Mox
+mock = mox.MockObject(some_object)
+mock2 = mox.MockAnything()
+mock3 = mox.MockAnything()
+mock.method1().AndReturn(mock1)
+mock2.method2().AndReturn(mock2)
+mock3.method3(arg1, arg2).AndReturn('some_value')
+self.mox.ReplayAll()
+assertEqual("some_value", some_object.method1().method2().method3(arg1, arg2))
+self.mox.VerifyAll()
+
+# Mocker
+# (TODO)
+
    +
    +
    >>> # Dingus
+>>> my_dingus = dingus.Dingus()
+>>> method3 = my_dingus.method1.return_value.method2.return_value.method3
+>>> method3.return_value = 'some value'
+>>> assertEqual('some value', my_dingus.method1().method2().method3(1, 2))
+>>> assert method3.calls('()', 1, 2).once()
+
    +
    +
    >>> # fudge
+>>> @fudge.test
+... def test():
+...     my_fake = fudge.Fake()
+...     (my_fake
+...      .expects('method1')
+...      .returns_fake()
+...      .expects('method2')
+...      .returns_fake()
+...      .expects('method3')
+...      .with_args(1, 2)
+...      .returns('some value'))
+...     assertEqual('some value', my_fake.method1().method2().method3(1, 2))
+...
+>>> test()
+
    +
    +
    +
    +

    Mocking a context manager¶

    +

    Examples for mock, Dingus and fudge only (so far):

    +
    >>> # mock
+>>> my_mock = mock.MagicMock()
+>>> with my_mock:
+...     pass
+...
+>>> my_mock.__enter__.assert_called_with()
+>>> my_mock.__exit__.assert_called_with(None, None, None)
+
    +
    +
    >>> # Dingus (nothing special here; all dinguses are "magic mocks")
+>>> my_dingus = dingus.Dingus()
+>>> with my_dingus:
+...     pass
+...
+>>> assert my_dingus.__enter__.calls()
+>>> assert my_dingus.__exit__.calls('()', None, None, None)
+
    +
    +
    >>> # fudge
+>>> my_fake = fudge.Fake().provides('__enter__').provides('__exit__')
+>>> with my_fake:
+...     pass
+...
+
    +
    +
    +
    +

    Mocking the builtin open used as a context manager¶

    +

    Example for mock only (so far):

    +
    >>> # mock
+>>> my_mock = mock.MagicMock()
+>>> with mock.patch('__builtin__.open', my_mock):
+...     manager = my_mock.return_value.__enter__.return_value
+...     manager.read.return_value = 'some data'
+...     with open('foo') as h:
+...         data = h.read()
+...
+>>> data
+'some data'
+>>> my_mock.assert_called_once_with('foo')
+
    +
    +

    or:

    +
    >>> # mock
+>>> with mock.patch('__builtin__.open') as my_mock:
+...     my_mock.return_value.__enter__ = lambda s: s
+...     my_mock.return_value.__exit__ = mock.Mock()
+...     my_mock.return_value.read.return_value = 'some data'
+...     with open('foo') as h:
+...         data = h.read()
+...
+>>> data
+'some data'
+>>> my_mock.assert_called_once_with('foo')
+
    +
    +
    >>> # Dingus
+>>> my_dingus = dingus.Dingus()
+>>> with dingus.patch('__builtin__.open', my_dingus):
+...     file_ = open.return_value.__enter__.return_value
+...     file_.read.return_value = 'some data'
+...     with open('foo') as h:
+...         data = f.read()
+...
+>>> data
+'some data'
+>>> assert my_dingus.calls('()', 'foo').once()
+
    +
    +
    >>> # fudge
+>>> from contextlib import contextmanager
+>>> from StringIO import StringIO
+>>> @contextmanager
+... def fake_file(filename):
+...     yield StringIO('sekrets')
+...
+>>> with fudge.patch('__builtin__.open') as fake_open:
+...     fake_open.is_callable().calls(fake_file)
+...     with open('/etc/password') as f:
+...         data = f.read()
+...
+fake:__builtin__.open
+>>> data
+'sekrets'
+
    +
    +
    +
    + + +
    +
    +
    +
    +
    +

    Table Of Contents

    + + +

    Previous topic

    +

    Further Examples

    +

    Next topic

    +

    CHANGELOG

    +

    This Page

    + + + +
    +
    +
    +
    +
    +

    Navigation

    + +
    +
    + © Copyright 2007-2012, Michael Foord & the mock team. + Last updated on Oct 07, 2012. + Created using Sphinx 1.1.3. +
    + + \ No newline at end of file diff --git a/python/mock-1.0.0/html/examples.html b/python/mock-1.0.0/html/examples.html new file mode 100644 index 000000000..8d8113e58 --- /dev/null +++ b/python/mock-1.0.0/html/examples.html @@ -0,0 +1,1006 @@ + + + + + + + + + Further Examples — Mock 1.0.0 documentation + + + + + + + + + + + + + +
    +

    Navigation

    + +
    + +
    +
    +
    +
    + +
    +

    Further Examples¶

    +

    For comprehensive examples, see the unit tests included in the full source +distribution.

    +

    Here are some more examples for some slightly more advanced scenarios than in +the getting started guide.

    +
    +

    Mocking chained calls¶

    +

    Mocking chained calls is actually straightforward with mock once you +understand the return_value attribute. When a mock is called for +the first time, or you fetch its return_value before it has been called, a +new Mock is created.

    +

    This means that you can see how the object returned from a call to a mocked +object has been used by interrogating the return_value mock:

    +
    >>> mock = Mock()
+>>> mock().foo(a=2, b=3)
+<Mock name='mock().foo()' id='...'>
+>>> mock.return_value.foo.assert_called_with(a=2, b=3)
+
    +
    +

    From here it is a simple step to configure and then make assertions about +chained calls. Of course another alternative is writing your code in a more +testable way in the first place...

    +

    So, suppose we have some code that looks a little bit like this:

    +
    >>> class Something(object):
+...     def __init__(self):
+...         self.backend = BackendProvider()
+...     def method(self):
+...         response = self.backend.get_endpoint('foobar').create_call('spam', 'eggs').start_call()
+...         # more code
+
    +
    +

    Assuming that BackendProvider is already well tested, how do we test +method()? Specifically, we want to test that the code section # more +code uses the response object in the correct way.

    +

    As this chain of calls is made from an instance attribute we can monkey patch +the backend attribute on a Something instance. In this particular case +we are only interested in the return value from the final call to +start_call so we don’t have much configuration to do. Let’s assume the +object it returns is ‘file-like’, so we’ll ensure that our response object +uses the builtin file as its spec.

    +

    To do this we create a mock instance as our mock backend and create a mock +response object for it. To set the response as the return value for that final +start_call we could do this:

    +
    +
    mock_backend.get_endpoint.return_value.create_call.return_value.start_call.return_value = mock_response.
    +

    We can do that in a slightly nicer way using the configure_mock() +method to directly set the return value for us:

    +
    >>> something = Something()
+>>> mock_response = Mock(spec=file)
+>>> mock_backend = Mock()
+>>> config = {'get_endpoint.return_value.create_call.return_value.start_call.return_value': mock_response}
+>>> mock_backend.configure_mock(**config)
+
    +
    +

    With these we monkey patch the “mock backend” in place and can make the real +call:

    +
    >>> something.backend = mock_backend
+>>> something.method()
+
    +
    +

    Using mock_calls we can check the chained call with a single +assert. A chained call is several calls in one line of code, so there will be +several entries in mock_calls. We can use call.call_list() to create +this list of calls for us:

    +
    >>> chained = call.get_endpoint('foobar').create_call('spam', 'eggs').start_call()
+>>> call_list = chained.call_list()
+>>> assert mock_backend.mock_calls == call_list
+
    +
    +
    +
    +

    Partial mocking¶

    +

    In some tests I wanted to mock out a call to datetime.date.today() to return +a known date, but I didn’t want to prevent the code under test from +creating new date objects. Unfortunately datetime.date is written in C, and +so I couldn’t just monkey-patch out the static date.today method.

    +

    I found a simple way of doing this that involved effectively wrapping the date +class with a mock, but passing through calls to the constructor to the real +class (and returning real instances).

    +

    The patch decorator is used here to +mock out the date class in the module under test. The side_effect +attribute on the mock date class is then set to a lambda function that returns +a real date. When the mock date class is called a real date will be +constructed and returned by side_effect.

    +
    >>> from datetime import date
+>>> with patch('mymodule.date') as mock_date:
+...     mock_date.today.return_value = date(2010, 10, 8)
+...     mock_date.side_effect = lambda *args, **kw: date(*args, **kw)
+...
+...     assert mymodule.date.today() == date(2010, 10, 8)
+...     assert mymodule.date(2009, 6, 8) == date(2009, 6, 8)
+...
+
    +
    +

    Note that we don’t patch datetime.date globally, we patch date in the +module that uses it. See where to patch.

    +

    When date.today() is called a known date is returned, but calls to the +date(...) constructor still return normal dates. Without this you can find +yourself having to calculate an expected result using exactly the same +algorithm as the code under test, which is a classic testing anti-pattern.

    +

    Calls to the date constructor are recorded in the mock_date attributes +(call_count and friends) which may also be useful for your tests.

    +

    An alternative way of dealing with mocking dates, or other builtin classes, +is discussed in this blog entry.

    +
    +
    +

    Mocking a Generator Method¶

    +

    A Python generator is a function or method that uses the yield statement to +return a series of values when iterated over [1].

    +

    A generator method / function is called to return the generator object. It is +the generator object that is then iterated over. The protocol method for +iteration is __iter__, so we can +mock this using a MagicMock.

    +

    Here’s an example class with an “iter” method implemented as a generator:

    +
    >>> class Foo(object):
+...     def iter(self):
+...         for i in [1, 2, 3]:
+...             yield i
+...
+>>> foo = Foo()
+>>> list(foo.iter())
+[1, 2, 3]
+
    +
    +

    How would we mock this class, and in particular its “iter” method?

    +

    To configure the values returned from the iteration (implicit in the call to +list), we need to configure the object returned by the call to foo.iter().

    +
    >>> mock_foo = MagicMock()
+>>> mock_foo.iter.return_value = iter([1, 2, 3])
+>>> list(mock_foo.iter())
+[1, 2, 3]
+
    +
    + + + + + +
    [1]There are also generator expressions and more advanced uses of generators, but we aren’t +concerned about them here. A very good introduction to generators and how +powerful they are is: Generator Tricks for Systems Programmers.
    +
    +
    +

    Applying the same patch to every test method¶

    +

    If you want several patches in place for multiple test methods the obvious way +is to apply the patch decorators to every method. This can feel like unnecessary +repetition. For Python 2.6 or more recent you can use patch (in all its +various forms) as a class decorator. This applies the patches to all test +methods on the class. A test method is identified by methods whose names start +with test:

    +
    >>> @patch('mymodule.SomeClass')
+... class MyTest(TestCase):
+...
+...     def test_one(self, MockSomeClass):
+...         self.assertTrue(mymodule.SomeClass is MockSomeClass)
+...
+...     def test_two(self, MockSomeClass):
+...         self.assertTrue(mymodule.SomeClass is MockSomeClass)
+...
+...     def not_a_test(self):
+...         return 'something'
+...
+>>> MyTest('test_one').test_one()
+>>> MyTest('test_two').test_two()
+>>> MyTest('test_two').not_a_test()
+'something'
+
    +
    +

    An alternative way of managing patches is to use the patch methods: start and stop. +These allow you to move the patching into your setUp and tearDown methods.

    +
    >>> class MyTest(TestCase):
+...     def setUp(self):
+...         self.patcher = patch('mymodule.foo')
+...         self.mock_foo = self.patcher.start()
+...
+...     def test_foo(self):
+...         self.assertTrue(mymodule.foo is self.mock_foo)
+...
+...     def tearDown(self):
+...         self.patcher.stop()
+...
+>>> MyTest('test_foo').run()
+
    +
    +

    If you use this technique you must ensure that the patching is “undone” by +calling stop. This can be fiddlier than you might think, because if an +exception is raised in the setUp then tearDown is not called. unittest2 cleanup functions make this simpler:

    +
    >>> class MyTest(TestCase):
+...     def setUp(self):
+...         patcher = patch('mymodule.foo')
+...         self.addCleanup(patcher.stop)
+...         self.mock_foo = patcher.start()
+...
+...     def test_foo(self):
+...         self.assertTrue(mymodule.foo is self.mock_foo)
+...
+>>> MyTest('test_foo').run()
+
    +
    +
    +
    +

    Mocking Unbound Methods¶

    +

    Whilst writing tests today I needed to patch an unbound method (patching the +method on the class rather than on the instance). I needed self to be passed +in as the first argument because I want to make asserts about which objects +were calling this particular method. The issue is that you can’t patch with a +mock for this, because if you replace an unbound method with a mock it doesn’t +become a bound method when fetched from the instance, and so it doesn’t get +self passed in. The workaround is to patch the unbound method with a real +function instead. The patch() decorator makes it so simple to +patch out methods with a mock that having to create a real function becomes a +nuisance.

    +

    If you pass autospec=True to patch then it does the patching with a +real function object. This function object has the same signature as the one +it is replacing, but delegates to a mock under the hood. You still get your +mock auto-created in exactly the same way as before. What it means though, is +that if you use it to patch out an unbound method on a class the mocked +function will be turned into a bound method if it is fetched from an instance. +It will have self passed in as the first argument, which is exactly what I +wanted:

    +
    >>> class Foo(object):
+...   def foo(self):
+...     pass
+...
+>>> with patch.object(Foo, 'foo', autospec=True) as mock_foo:
+...   mock_foo.return_value = 'foo'
+...   foo = Foo()
+...   foo.foo()
+...
+'foo'
+>>> mock_foo.assert_called_once_with(foo)
+
    +
    +

    If we don’t use autospec=True then the unbound method is patched out +with a Mock instance instead, and isn’t called with self.

    +
    +
    +

    Checking multiple calls with mock¶

    +

    mock has a nice API for making assertions about how your mock objects are used.

    +
    >>> mock = Mock()
+>>> mock.foo_bar.return_value = None
+>>> mock.foo_bar('baz', spam='eggs')
+>>> mock.foo_bar.assert_called_with('baz', spam='eggs')
+
    +
    +

    If your mock is only being called once you can use the +assert_called_once_with() method that also asserts that the +call_count is one.

    +
    >>> mock.foo_bar.assert_called_once_with('baz', spam='eggs')
+>>> mock.foo_bar()
+>>> mock.foo_bar.assert_called_once_with('baz', spam='eggs')
+Traceback (most recent call last):
+    ...
+AssertionError: Expected to be called once. Called 2 times.
+
    +
    +

    Both assert_called_with and assert_called_once_with make assertions about +the most recent call. If your mock is going to be called several times, and +you want to make assertions about all those calls you can use +call_args_list:

    +
    >>> mock = Mock(return_value=None)
+>>> mock(1, 2, 3)
+>>> mock(4, 5, 6)
+>>> mock()
+>>> mock.call_args_list
+[call(1, 2, 3), call(4, 5, 6), call()]
+
    +
    +

    The call helper makes it easy to make assertions about these calls. You +can build up a list of expected calls and compare it to call_args_list. This +looks remarkably similar to the repr of the call_args_list:

    +
    >>> expected = [call(1, 2, 3), call(4, 5, 6), call()]
+>>> mock.call_args_list == expected
+True
+
    +
    +
    +
    +

    Coping with mutable arguments¶

    +

    Another situation is rare, but can bite you, is when your mock is called with +mutable arguments. call_args and call_args_list store references to the +arguments. If the arguments are mutated by the code under test then you can no +longer make assertions about what the values were when the mock was called.

    +

    Here’s some example code that shows the problem. Imagine the following functions +defined in ‘mymodule’:

    +
    def frob(val):
+    pass
+
+def grob(val):
+    "First frob and then clear val"
+    frob(val)
+    val.clear()
+
    +
    +

    When we try to test that grob calls frob with the correct argument look +what happens:

    +
    >>> with patch('mymodule.frob') as mock_frob:
+...     val = set([6])
+...     mymodule.grob(val)
+...
+>>> val
+set([])
+>>> mock_frob.assert_called_with(set([6]))
+Traceback (most recent call last):
+    ...
+AssertionError: Expected: ((set([6]),), {})
+Called with: ((set([]),), {})
+
    +
    +

    One possibility would be for mock to copy the arguments you pass in. This +could then cause problems if you do assertions that rely on object identity +for equality.

    +

    Here’s one solution that uses the side_effect +functionality. If you provide a side_effect function for a mock then +side_effect will be called with the same args as the mock. This gives us an +opportunity to copy the arguments and store them for later assertions. In this +example I’m using another mock to store the arguments so that I can use the +mock methods for doing the assertion. Again a helper function sets this up for +me.

    +
    >>> from copy import deepcopy
+>>> from mock import Mock, patch, DEFAULT
+>>> def copy_call_args(mock):
+...     new_mock = Mock()
+...     def side_effect(*args, **kwargs):
+...         args = deepcopy(args)
+...         kwargs = deepcopy(kwargs)
+...         new_mock(*args, **kwargs)
+...         return DEFAULT
+...     mock.side_effect = side_effect
+...     return new_mock
+...
+>>> with patch('mymodule.frob') as mock_frob:
+...     new_mock = copy_call_args(mock_frob)
+...     val = set([6])
+...     mymodule.grob(val)
+...
+>>> new_mock.assert_called_with(set([6]))
+>>> new_mock.call_args
+call(set([6]))
+
    +
    +

    copy_call_args is called with the mock that will be called. It returns a new +mock that we do the assertion on. The side_effect function makes a copy of +the args and calls our new_mock with the copy.

    +
    +

    Note

    +

    If your mock is only going to be used once there is an easier way of +checking arguments at the point they are called. You can simply do the +checking inside a side_effect function.

    +
    >>> def side_effect(arg):
+...     assert arg == set([6])
+...
+>>> mock = Mock(side_effect=side_effect)
+>>> mock(set([6]))
+>>> mock(set())
+Traceback (most recent call last):
+    ...
+AssertionError
+
    +
    +
    +

    An alternative approach is to create a subclass of Mock or MagicMock that +copies (using copy.deepcopy) the arguments. +Here’s an example implementation:

    +
    >>> from copy import deepcopy
+>>> class CopyingMock(MagicMock):
+...     def __call__(self, *args, **kwargs):
+...         args = deepcopy(args)
+...         kwargs = deepcopy(kwargs)
+...         return super(CopyingMock, self).__call__(*args, **kwargs)
+...
+>>> c = CopyingMock(return_value=None)
+>>> arg = set()
+>>> c(arg)
+>>> arg.add(1)
+>>> c.assert_called_with(set())
+>>> c.assert_called_with(arg)
+Traceback (most recent call last):
+    ...
+AssertionError: Expected call: mock(set([1]))
+Actual call: mock(set([]))
+>>> c.foo
+<CopyingMock name='mock.foo' id='...'>
+
    +
    +

    When you subclass Mock or MagicMock all dynamically created attributes, +and the return_value will use your subclass automatically. That means all +children of a CopyingMock will also have the type CopyingMock.

    +
    +
    +

    Raising exceptions on attribute access¶

    +

    You can use PropertyMock to mimic the behaviour of properties. This +includes raising exceptions when an attribute is accessed.

    +

    Here’s an example raising a ValueError when the ‘foo’ attribute is accessed:

    +
    >>> m = MagicMock()
+>>> p = PropertyMock(side_effect=ValueError)
+>>> type(m).foo = p
+>>> m.foo
+Traceback (most recent call last):
+....
+ValueError
    +
    +

    Because every mock object has its own type, a new subclass of whichever mock +class you’re using, all mock objects are isolated from each other. You can +safely attach properties (or other descriptors or whatever you want in fact) +to type(mock) without affecting other mock objects.

    +
    +
    +

    Multiple calls with different effects¶

    +
    +

    Note

    +

    In mock 1.0 the handling of iterable side_effect was changed. Any +exceptions in the iterable will be raised instead of returned.

    +
    +

    Handling code that needs to behave differently on subsequent calls during the +test can be tricky. For example you may have a function that needs to raise +an exception the first time it is called but returns a response on the second +call (testing retry behaviour).

    +

    One approach is to use a side_effect function that replaces itself. The +first time it is called the side_effect sets a new side_effect that will +be used for the second call. It then raises an exception:

    +
    >>> def side_effect(*args):
+...   def second_call(*args):
+...     return 'response'
+...   mock.side_effect = second_call
+...   raise Exception('boom')
+...
+>>> mock = Mock(side_effect=side_effect)
+>>> mock('first')
+Traceback (most recent call last):
+    ...
+Exception: boom
+>>> mock('second')
+'response'
+>>> mock.assert_called_with('second')
+
    +
    +

    Another perfectly valid way would be to pop return values from a list. If the +return value is an exception, raise it instead of returning it:

    +
    >>> returns = [Exception('boom'), 'response']
+>>> def side_effect(*args):
+...   result = returns.pop(0)
+...   if isinstance(result, Exception):
+...     raise result
+...   return result
+...
+>>> mock = Mock(side_effect=side_effect)
+>>> mock('first')
+Traceback (most recent call last):
+    ...
+Exception: boom
+>>> mock('second')
+'response'
+>>> mock.assert_called_with('second')
+
    +
    +

    Which approach you prefer is a matter of taste. The first approach is actually +a line shorter but maybe the second approach is more readable.

    +
    +
    +

    Nesting Patches¶

    +

    Using patch as a context manager is nice, but if you do multiple patches you +can end up with nested with statements indenting further and further to the +right:

    +
    >>> class MyTest(TestCase):
+...
+...     def test_foo(self):
+...         with patch('mymodule.Foo') as mock_foo:
+...             with patch('mymodule.Bar') as mock_bar:
+...                 with patch('mymodule.Spam') as mock_spam:
+...                     assert mymodule.Foo is mock_foo
+...                     assert mymodule.Bar is mock_bar
+...                     assert mymodule.Spam is mock_spam
+...
+>>> original = mymodule.Foo
+>>> MyTest('test_foo').test_foo()
+>>> assert mymodule.Foo is original
+
    +
    +

    With unittest2 cleanup functions and the patch methods: start and stop we can +achieve the same effect without the nested indentation. A simple helper +method, create_patch, puts the patch in place and returns the created mock +for us:

    +
    >>> class MyTest(TestCase):
+...
+...     def create_patch(self, name):
+...         patcher = patch(name)
+...         thing = patcher.start()
+...         self.addCleanup(patcher.stop)
+...         return thing
+...
+...     def test_foo(self):
+...         mock_foo = self.create_patch('mymodule.Foo')
+...         mock_bar = self.create_patch('mymodule.Bar')
+...         mock_spam = self.create_patch('mymodule.Spam')
+...
+...         assert mymodule.Foo is mock_foo
+...         assert mymodule.Bar is mock_bar
+...         assert mymodule.Spam is mock_spam
+...
+>>> original = mymodule.Foo
+>>> MyTest('test_foo').run()
+>>> assert mymodule.Foo is original
+
    +
    +
    +
    +

    Mocking a dictionary with MagicMock¶

    +

    You may want to mock a dictionary, or other container object, recording all +access to it whilst having it still behave like a dictionary.

    +

    We can do this with MagicMock, which will behave like a dictionary, +and using side_effect to delegate dictionary access to a real +underlying dictionary that is under our control.

    +

    When the __getitem__ and __setitem__ methods of our MagicMock are called +(normal dictionary access) then side_effect is called with the key (and in +the case of __setitem__ the value too). We can also control what is returned.

    +

    After the MagicMock has been used we can use attributes like +call_args_list to assert about how the dictionary was used:

    +
    >>> my_dict = {'a': 1, 'b': 2, 'c': 3}
+>>> def getitem(name):
+...      return my_dict[name]
+...
+>>> def setitem(name, val):
+...     my_dict[name] = val
+...
+>>> mock = MagicMock()
+>>> mock.__getitem__.side_effect = getitem
+>>> mock.__setitem__.side_effect = setitem
+
    +
    +
    +

    Note

    +

    An alternative to using MagicMock is to use Mock and only provide +the magic methods you specifically want:

    +
    >>> mock = Mock()
+>>> mock.__setitem__ = Mock(side_effect=getitem)
+>>> mock.__getitem__ = Mock(side_effect=setitem)
+
    +
    +

    A third option is to use MagicMock but passing in dict as the spec +(or spec_set) argument so that the MagicMock created only has +dictionary magic methods available:

    +
    >>> mock = MagicMock(spec_set=dict)
+>>> mock.__getitem__.side_effect = getitem
+>>> mock.__setitem__.side_effect = setitem
+
    +
    +
    +

    With these side effect functions in place, the mock will behave like a normal +dictionary but recording the access. It even raises a KeyError if you try +to access a key that doesn’t exist.

    +
    >>> mock['a']
+1
+>>> mock['c']
+3
+>>> mock['d']
+Traceback (most recent call last):
+    ...
+KeyError: 'd'
+>>> mock['b'] = 'fish'
+>>> mock['d'] = 'eggs'
+>>> mock['b']
+'fish'
+>>> mock['d']
+'eggs'
+
    +
    +

    After it has been used you can make assertions about the access using the normal +mock methods and attributes:

    +
    >>> mock.__getitem__.call_args_list
+[call('a'), call('c'), call('d'), call('b'), call('d')]
+>>> mock.__setitem__.call_args_list
+[call('b', 'fish'), call('d', 'eggs')]
+>>> my_dict
+{'a': 1, 'c': 3, 'b': 'fish', 'd': 'eggs'}
+
    +
    +
    +
    +

    Mock subclasses and their attributes¶

    +

    There are various reasons why you might want to subclass Mock. One reason +might be to add helper methods. Here’s a silly example:

    +
    >>> class MyMock(MagicMock):
+...     def has_been_called(self):
+...         return self.called
+...
+>>> mymock = MyMock(return_value=None)
+>>> mymock
+<MyMock id='...'>
+>>> mymock.has_been_called()
+False
+>>> mymock()
+>>> mymock.has_been_called()
+True
+
    +
    +

    The standard behaviour for Mock instances is that attributes and the return +value mocks are of the same type as the mock they are accessed on. This ensures +that Mock attributes are Mocks and MagicMock attributes are MagicMocks +[2]. So if you’re subclassing to add helper methods then they’ll also be +available on the attributes and return value mock of instances of your +subclass.

    +
    >>> mymock.foo
+<MyMock name='mock.foo' id='...'>
+>>> mymock.foo.has_been_called()
+False
+>>> mymock.foo()
+<MyMock name='mock.foo()' id='...'>
+>>> mymock.foo.has_been_called()
+True
+
    +
    +

    Sometimes this is inconvenient. For example, one user is subclassing mock to +created a Twisted adaptor. +Having this applied to attributes too actually causes errors.

    +

    Mock (in all its flavours) uses a method called _get_child_mock to create +these “sub-mocks” for attributes and return values. You can prevent your +subclass being used for attributes by overriding this method. The signature is +that it takes arbitrary keyword arguments (**kwargs) which are then passed +onto the mock constructor:

    +
    >>> class Subclass(MagicMock):
+...     def _get_child_mock(self, **kwargs):
+...         return MagicMock(**kwargs)
+...
+>>> mymock = Subclass()
+>>> mymock.foo
+<MagicMock name='mock.foo' id='...'>
+>>> assert isinstance(mymock, Subclass)
+>>> assert not isinstance(mymock.foo, Subclass)
+>>> assert not isinstance(mymock(), Subclass)
+
    +
    + + + + + +
    [2]An exception to this rule are the non-callable mocks. Attributes use the +callable variant because otherwise non-callable mocks couldn’t have callable +methods.
    +
    +
    +

    Mocking imports with patch.dict¶

    +

    One situation where mocking can be hard is where you have a local import inside +a function. These are harder to mock because they aren’t using an object from +the module namespace that we can patch out.

    +

    Generally local imports are to be avoided. They are sometimes done to prevent +circular dependencies, for which there is usually a much better way to solve +the problem (refactor the code) or to prevent “up front costs” by delaying the +import. This can also be solved in better ways than an unconditional local +import (store the module as a class or module attribute and only do the import +on first use).

    +

    That aside there is a way to use mock to affect the results of an import. +Importing fetches an object from the sys.modules dictionary. Note that it +fetches an object, which need not be a module. Importing a module for the +first time results in a module object being put in sys.modules, so usually +when you import something you get a module back. This need not be the case +however.

    +

    This means you can use patch.dict() to temporarily put a mock in place +in sys.modules. Any imports whilst this patch is active will fetch the mock. +When the patch is complete (the decorated function exits, the with statement +body is complete or patcher.stop() is called) then whatever was there +previously will be restored safely.

    +

    Here’s an example that mocks out the ‘fooble’ module.

    +
    >>> mock = Mock()
+>>> with patch.dict('sys.modules', {'fooble': mock}):
+...    import fooble
+...    fooble.blob()
+...
+<Mock name='mock.blob()' id='...'>
+>>> assert 'fooble' not in sys.modules
+>>> mock.blob.assert_called_once_with()
+
    +
    +

    As you can see the import fooble succeeds, but on exit there is no ‘fooble’ +left in sys.modules.

    +

    This also works for the from module import name form:

    +
    >>> mock = Mock()
+>>> with patch.dict('sys.modules', {'fooble': mock}):
+...    from fooble import blob
+...    blob.blip()
+...
+<Mock name='mock.blob.blip()' id='...'>
+>>> mock.blob.blip.assert_called_once_with()
+
    +
    +

    With slightly more work you can also mock package imports:

    +
    >>> mock = Mock()
+>>> modules = {'package': mock, 'package.module': mock.module}
+>>> with patch.dict('sys.modules', modules):
+...    from package.module import fooble
+...    fooble()
+...
+<Mock name='mock.module.fooble()' id='...'>
+>>> mock.module.fooble.assert_called_once_with()
+
    +
    +
    +
    +

    Tracking order of calls and less verbose call assertions¶

    +

    The Mock class allows you to track the order of method calls on +your mock objects through the method_calls attribute. This +doesn’t allow you to track the order of calls between separate mock objects, +however we can use mock_calls to achieve the same effect.

    +

    Because mocks track calls to child mocks in mock_calls, and accessing an +arbitrary attribute of a mock creates a child mock, we can create our separate +mocks from a parent one. Calls to those child mock will then all be recorded, +in order, in the mock_calls of the parent:

    +
    >>> manager = Mock()
+>>> mock_foo = manager.foo
+>>> mock_bar = manager.bar
+
+>>> mock_foo.something()
+<Mock name='mock.foo.something()' id='...'>
+>>> mock_bar.other.thing()
+<Mock name='mock.bar.other.thing()' id='...'>
+
+>>> manager.mock_calls
+[call.foo.something(), call.bar.other.thing()]
+
    +
    +

    We can then assert about the calls, including the order, by comparing with +the mock_calls attribute on the manager mock:

    +
    >>> expected_calls = [call.foo.something(), call.bar.other.thing()]
+>>> manager.mock_calls == expected_calls
+True
+
    +
    +

    If patch is creating, and putting in place, your mocks then you can attach +them to a manager mock using the attach_mock() method. After +attaching calls will be recorded in mock_calls of the manager.

    +
    >>> manager = MagicMock()
+>>> with patch('mymodule.Class1') as MockClass1:
+...     with patch('mymodule.Class2') as MockClass2:
+...         manager.attach_mock(MockClass1, 'MockClass1')
+...         manager.attach_mock(MockClass2, 'MockClass2')
+...         MockClass1().foo()
+...         MockClass2().bar()
+...
+<MagicMock name='mock.MockClass1().foo()' id='...'>
+<MagicMock name='mock.MockClass2().bar()' id='...'>
+>>> manager.mock_calls
+[call.MockClass1(),
+ call.MockClass1().foo(),
+ call.MockClass2(),
+ call.MockClass2().bar()]
+
    +
    +

    If many calls have been made, but you’re only interested in a particular +sequence of them then an alternative is to use the +assert_has_calls() method. This takes a list of calls (constructed +with the call object). If that sequence of calls are in +mock_calls then the assert succeeds.

    +
    >>> m = MagicMock()
+>>> m().foo().bar().baz()
+<MagicMock name='mock().foo().bar().baz()' id='...'>
+>>> m.one().two().three()
+<MagicMock name='mock.one().two().three()' id='...'>
+>>> calls = call.one().two().three().call_list()
+>>> m.assert_has_calls(calls)
+
    +
    +

    Even though the chained call m.one().two().three() aren’t the only calls that +have been made to the mock, the assert still succeeds.

    +

    Sometimes a mock may have several calls made to it, and you are only interested +in asserting about some of those calls. You may not even care about the +order. In this case you can pass any_order=True to assert_has_calls:

    +
    >>> m = MagicMock()
+>>> m(1), m.two(2, 3), m.seven(7), m.fifty('50')
+(...)
+>>> calls = [call.fifty('50'), call(1), call.seven(7)]
+>>> m.assert_has_calls(calls, any_order=True)
+
    +
    +
    +
    +

    More complex argument matching¶

    +

    Using the same basic concept as ANY we can implement matchers to do more +complex assertions on objects used as arguments to mocks.

    +

    Suppose we expect some object to be passed to a mock that by default +compares equal based on object identity (which is the Python default for user +defined classes). To use assert_called_with() we would need to pass +in the exact same object. If we are only interested in some of the attributes +of this object then we can create a matcher that will check these attributes +for us.

    +

    You can see in this example how a ‘standard’ call to assert_called_with isn’t +sufficient:

    +
    >>> class Foo(object):
+...     def __init__(self, a, b):
+...         self.a, self.b = a, b
+...
+>>> mock = Mock(return_value=None)
+>>> mock(Foo(1, 2))
+>>> mock.assert_called_with(Foo(1, 2))
+Traceback (most recent call last):
+    ...
+AssertionError: Expected: call(<__main__.Foo object at 0x...>)
+Actual call: call(<__main__.Foo object at 0x...>)
+
    +
    +

    A comparison function for our Foo class might look something like this:

    +
    >>> def compare(self, other):
+...     if not type(self) == type(other):
+...         return False
+...     if self.a != other.a:
+...         return False
+...     if self.b != other.b:
+...         return False
+...     return True
+...
+
    +
    +

    And a matcher object that can use comparison functions like this for its +equality operation would look something like this:

    +
    >>> class Matcher(object):
+...     def __init__(self, compare, some_obj):
+...         self.compare = compare
+...         self.some_obj = some_obj
+...     def __eq__(self, other):
+...         return self.compare(self.some_obj, other)
+...
+
    +
    +

    Putting all this together:

    +
    >>> match_foo = Matcher(compare, Foo(1, 2))
+>>> mock.assert_called_with(match_foo)
+
    +
    +

    The Matcher is instantiated with our compare function and the Foo object +we want to compare against. In assert_called_with the Matcher equality +method will be called, which compares the object the mock was called with +against the one we created our matcher with. If they match then +assert_called_with passes, and if they don’t an AssertionError is raised:

    +
    >>> match_wrong = Matcher(compare, Foo(3, 4))
+>>> mock.assert_called_with(match_wrong)
+Traceback (most recent call last):
+    ...
+AssertionError: Expected: ((<Matcher object at 0x...>,), {})
+Called with: ((<Foo object at 0x...>,), {})
+
    +
    +

    With a bit of tweaking you could have the comparison function raise the +AssertionError directly and provide a more useful failure message.

    +

    As of version 1.5, the Python testing library PyHamcrest provides similar functionality, +that may be useful here, in the form of its equality matcher +(hamcrest.library.integration.match_equality).

    +
    +
    +

    Less verbose configuration of mock objects¶

    +

    This recipe, for easier configuration of mock objects, is now part of Mock. +See the configure_mock() method.

    +
    +
    +

    Matching any argument in assertions¶

    +

    This example is now built in to mock. See ANY.

    +
    +
    +

    Mocking Properties¶

    +

    This example is now built in to mock. See PropertyMock.

    +
    +
    +

    Mocking open¶

    +

    This example is now built in to mock. See mock_open().

    +
    +
    +

    Mocks without some attributes¶

    +

    This example is now built in to mock. See Deleting Attributes.

    +
    +
    + + +
    +
    +
    +
    +
    +

    Table Of Contents

    + + +

    Previous topic

    +

    Getting Started with Mock

    +

    Next topic

    +

    Mock Library Comparison

    +

    This Page

    + + + +
    +
    +
    +
    +
    +

    Navigation

    + +
    +
    + © Copyright 2007-2012, Michael Foord & the mock team. + Last updated on Oct 07, 2012. + Created using Sphinx 1.1.3. +
    + + \ No newline at end of file diff --git a/python/mock-1.0.0/html/genindex.html b/python/mock-1.0.0/html/genindex.html new file mode 100644 index 000000000..2d1acf0b4 --- /dev/null +++ b/python/mock-1.0.0/html/genindex.html @@ -0,0 +1,479 @@ + + + + + + + + + + + Index — Mock 1.0.0 documentation + + + + + + + + + + + +
    +

    Navigation

    + +
    + +
    +
    +
    +
    + + +

    Index

    + +
    + _ + | A + | C + | D + | E + | F + | G + | H + | I + | M + | N + | O + | P + | R + | S + | T + | U + | W + +
    +

    _

    + + + +
    + +
    __call__ +
    + + +
    __class__ (Mock attribute) +
    + +
    + +
    __dir__() (Mock method) +
    + + +
    _get_child_mock() (Mock method) +
    + +
    + +

    A

    + + + +
    + +
    ANY (in module mock) +
    + + +
    articles +
    + + +
    assert_any_call() (Mock method) +
    + + +
    assert_called_once_with() (Mock method) +
    + +
    + +
    assert_called_with() (Mock method) +
    + + +
    assert_has_calls() (Mock method) +
    + + +
    attach_mock() (Mock method) +
    + +
    + +

    C

    + + + +
    + +
    call() (in module mock) +
    + + +
    call_args (Mock attribute) +
    + + +
    call_args_list (Mock attribute) +
    + + +
    call_count (Mock attribute) +
    + + +
    call_list() (call method) +
    + +
    + +
    called (Mock attribute) +
    + + +
    calling +
    + + +
    configure_mock() (Mock method) +
    + + +
    create_autospec() (in module mock) +
    + +
    + +

    D

    + + +
    + +
    DEFAULT (in module mock) +
    + +
    + +

    E

    + + +
    + +
    easy_install +
    + +
    + +

    F

    + + +
    + +
    FILTER_DIR (in module mock) +
    + +
    + +

    G

    + + +
    + +
    Getting Started +
    + +
    + +

    H

    + + +
    + +
    hg +
    + +
    + +

    I

    + + + +
    + +
    installing +
    + +
    + +
    introduction +
    + +
    + +

    M

    + + + +
    + +
    MagicMock (class in mock) +
    + + +
    method_calls (Mock attribute) +
    + + +
    Mock (class in mock) +
    + + +
    mock (module) +
    + +
    + +
    mock_add_spec() (Mock method) +
    + + +
    mock_calls (Mock attribute) +
    + + +
    mock_open() (in module mock) +
    + +
    + +

    N

    + + + +
    + +
    name +
    + + +
    NonCallableMagicMock (class in mock) +
    + +
    + +
    NonCallableMock (class in mock) +
    + +
    + +

    O

    + + +
    + +
    older versions +
    + +
    + +

    P

    + + + +
    + +
    patch() (in module mock) +
    + + +
    patch.dict() (in module mock) +
    + + +
    patch.multiple() (in module mock) +
    + + +
    patch.object() (in module mock) +
    + +
    + +
    patch.stopall() (in module mock) +
    + + +
    pip +
    + + +
    PropertyMock (class in mock) +
    + + +
    Python 3 +
    + +
    + +

    R

    + + + +
    + +
    references +
    + + +
    repository +
    + +
    + +
    reset_mock() (Mock method) +
    + + +
    return_value +
    + +
    + +
    (Mock attribute) +
    + +
    +
    + +

    S

    + + + +
    + +
    sentinel (in module mock) +
    + + +
    setuptools +
    + +
    + +
    side_effect +
    + +
    + +
    (Mock attribute) +
    + +
    + +
    spec +
    + +
    + +

    T

    + + +
    + +
    tests +
    + +
    + +

    U

    + + +
    + +
    unittest2 +
    + +
    + +

    W

    + + +
    + +
    wraps +
    + +
    + + + +
    +
    +
    +
    +
    + + + + + +
    +
    +
    +
    +
    +

    Navigation

    + +
    +
    + © Copyright 2007-2012, Michael Foord & the mock team. + Last updated on Oct 07, 2012. + Created using Sphinx 1.1.3. +
    + + \ No newline at end of file diff --git a/python/mock-1.0.0/html/getting-started.html b/python/mock-1.0.0/html/getting-started.html new file mode 100644 index 000000000..73d708ac9 --- /dev/null +++ b/python/mock-1.0.0/html/getting-started.html @@ -0,0 +1,510 @@ + + + + + + + + + Getting Started with Mock — Mock 1.0.0 documentation + + + + + + + + + + + + + +
    +

    Navigation

    + +
    + +
    +
    +
    +
    + +
    +

    Getting Started with Mock¶

    +
    +

    Using Mock¶

    +
    +

    Mock Patching Methods¶

    +

    Common uses for 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 Mock and 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 called attribute is set to +True. More importantly we can use the assert_called_with() or +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:

    +
    >>> from mock import MagicMock
+>>> 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 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 modifying the 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 +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 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 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 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 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 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 Further Examples page.

    +
    +
    + + +
    +
    +
    +
    +
    +

    Table Of Contents

    + + +

    Previous topic

    +

    Mocking Magic Methods

    +

    Next topic

    +

    Further Examples

    +

    This Page

    + + + +
    +
    +
    +
    +
    +

    Navigation

    + +
    +
    + © Copyright 2007-2012, Michael Foord & the mock team. + Last updated on Oct 07, 2012. + Created using Sphinx 1.1.3. +
    + + \ No newline at end of file diff --git a/python/mock-1.0.0/html/index.html b/python/mock-1.0.0/html/index.html new file mode 100644 index 000000000..2cdf89d5c --- /dev/null +++ b/python/mock-1.0.0/html/index.html @@ -0,0 +1,529 @@ + + + + + + + + + Mock - Mocking and Testing Library — Mock 1.0.0 documentation + + + + + + + + + + + + +
    +

    Navigation

    + +
    + +
    +
    +
    +
    + +
    +

    Mock - Mocking and Testing Library¶

    + +++ + + + + + + + + + + + + + + + + + + + +
    Author:Michael Foord
    Version:1.0.0
    Date:2012/10/07
    Homepage:Mock Homepage
    Download:Mock on PyPI
    Documentation:PDF Documentation
    License:BSD License
    Support:Mailing list (testing-in-python@lists.idyll.org)
    Issue tracker:Google code project
    +

    mock is a library for testing in Python. It allows you to replace parts of +your system under test with mock objects and make assertions about how they +have been used.

    +

    mock is now part of the Python standard library, available as unittest.mock +in Python 3.3 onwards.

    +

    mock provides a core Mock class removing the need to create a host +of stubs throughout your test suite. After performing an action, you can make +assertions about which methods / attributes were used and arguments they were +called with. You can also specify return values and set needed attributes in +the normal way.

    +

    Additionally, mock provides a patch() decorator that handles patching +module and class level attributes within the scope of a test, along with +sentinel for creating unique objects. See the quick guide for +some examples of how to use Mock, MagicMock and +patch().

    +

    Mock is very easy to use and is designed for use with +unittest. Mock is based on +the ‘action -> assertion’ pattern instead of ‘record -> replay’ used by many +mocking frameworks.

    +

    mock is tested on Python versions 2.4-2.7, Python 3 plus the latest versions of +Jython and PyPy.

    + +
    +

    User Guide¶

    +
    + +
    +
    +
    +

    Installing¶

    +

    The current version is 1.0.0. Mock is stable and widely used. If you do +find any bugs, or have suggestions for improvements / extensions +then please contact us.

    + +

    You can checkout the latest development version from the Google Code Mercurial +repository with the following command:

    +
    +
    hg clone https://mock.googlecode.com/hg/ mock
    +

    If you have pip, setuptools or distribute you can install mock with:

    +
    +
    +
    easy_install -U mock
    +
    pip install -U mock
    +
    +
    +

    Alternatively you can download the mock distribution from PyPI and after +unpacking run:

    +
    +
    python setup.py install
    +
    +
    +

    Quick Guide¶

    +

    Mock and MagicMock objects create all attributes and +methods as you access them and store details of how they have been used. You +can configure them, to specify return values or limit what attributes are +available, and then make assertions about how they have been used:

    +
    >>> from mock import MagicMock
+>>> thing = ProductionClass()
+>>> thing.method = MagicMock(return_value=3)
+>>> thing.method(3, 4, 5, key='value')
+3
+>>> thing.method.assert_called_with(3, 4, 5, key='value')
+
    +
    +

    side_effect allows you to perform side effects, including raising an +exception when a mock is called:

    +
    >>> mock = Mock(side_effect=KeyError('foo'))
+>>> mock()
+Traceback (most recent call last):
+ ...
+KeyError: 'foo'
+
+>>> values = {'a': 1, 'b': 2, 'c': 3}
+>>> def side_effect(arg):
+...     return values[arg]
+...
+>>> mock.side_effect = side_effect
+>>> mock('a'), mock('b'), mock('c')
+(1, 2, 3)
+>>> mock.side_effect = [5, 4, 3, 2, 1]
+>>> mock(), mock(), mock()
+(5, 4, 3)
+
    +
    +

    Mock has many other ways you can configure it and control its behaviour. For +example the spec argument configures the mock to take its specification +from another object. Attempting to access attributes or methods on the mock +that don’t exist on the spec will fail with an AttributeError.

    +

    The patch() decorator / context manager makes it easy to mock classes or +objects in a module under test. The object you specify will be replaced with a +mock (or other object) during the test and restored when the test ends:

    +
    >>> from mock import patch
+>>> @patch('module.ClassName2')
+... @patch('module.ClassName1')
+... def test(MockClass1, MockClass2):
+...     module.ClassName1()
+...     module.ClassName2()
+
+...     assert MockClass1 is module.ClassName1
+...     assert MockClass2 is module.ClassName2
+...     assert MockClass1.called
+...     assert MockClass2.called
+...
+>>> test()
+
    +
    +
    +

    Note

    +

    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 module.ClassName1 is passed in first.

    +

    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 where to patch.

    +
    +

    As well as a decorator patch can be used as a context manager in a with +statement:

    +
    >>> with patch.object(ProductionClass, 'method', return_value=None) as mock_method:
+...     thing = ProductionClass()
+...     thing.method(1, 2, 3)
+...
+>>> mock_method.assert_called_once_with(1, 2, 3)
+
    +
    +

    There is also 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
+
    +
    +

    Mock supports the mocking of Python magic methods. The +easiest way of using magic methods is with the MagicMock class. It +allows you to do things like:

    +
    >>> mock = MagicMock()
+>>> mock.__str__.return_value = 'foobarbaz'
+>>> str(mock)
+'foobarbaz'
+>>> mock.__str__.assert_called_with()
+
    +
    +

    Mock allows you to assign functions (or other Mock instances) to magic methods +and they will be called appropriately. The MagicMock class is just a Mock +variant that has all of the magic methods pre-created for you (well, all the +useful ones anyway).

    +

    The following is an example of using magic methods with the ordinary Mock +class:

    +
    >>> mock = Mock()
+>>> mock.__str__ = Mock(return_value='wheeeeee')
+>>> str(mock)
+'wheeeeee'
+
    +
    +

    For ensuring that the mock objects in your tests have the same api as the +objects they are replacing, you can use auto-speccing. +Auto-speccing can be done through the autospec argument to patch, or the +create_autospec() function. Auto-speccing creates mock objects that +have the same attributes and methods as the objects they are replacing, and +any functions and methods (including constructors) have the same call +signature as the real object.

    +

    This ensures that your mocks will fail in the same way as your production +code if they are used incorrectly:

    +
    >>> from mock import create_autospec
+>>> def function(a, b, c):
+...     pass
+...
+>>> mock_function = create_autospec(function, return_value='fishy')
+>>> mock_function(1, 2, 3)
+'fishy'
+>>> mock_function.assert_called_once_with(1, 2, 3)
+>>> mock_function('wrong arguments')
+Traceback (most recent call last):
+ ...
+TypeError: <lambda>() takes exactly 3 arguments (1 given)
+
    +
    +

    create_autospec can also be used on classes, where it copies the signature of +the __init__ method, and on callable objects where it copies the signature of +the __call__ method.

    +
    + +
    +

    Tests¶

    +

    Mock uses unittest2 for its own +test suite. In order to run it, use the unit2 script that comes with +unittest2 module on a checkout of the source repository:

    +
    +
    unit2 discover
    +

    If you have setuptools as well as +unittest2 you can run:

    +
    +
    python setup.py test
    +

    On Python 3.2 you can use unittest module from the standard library.

    +
    +
    python3.2 -m unittest discover
    +

    On Python 3 the tests for unicode are skipped as they are not relevant. On +Python 2.4 tests that use the with statements are skipped as the with statement +is invalid syntax on Python 2.4.

    +
    +
    +

    Older Versions¶

    +

    Documentation for older versions of mock:

    + +

    Docs from the in-development version of mock can be found at +mock.readthedocs.org.

    +
    +
    +

    Terminology¶

    +

    Terminology for objects used to replace other ones can be confusing. Terms +like double, fake, mock, stub, and spy are all used with varying meanings.

    +

    In classic mock terminology +mock.Mock is a spy that +allows for post-mortem examination. This is what I call the “action -> +assertion” [1] pattern of testing.

    +

    I’m not however a fan of this “statically typed mocking terminology” +promulgated by Martin Fowler. It confuses usage +patterns with implementation and prevents you from using natural terminology +when discussing mocking.

    +

    I much prefer duck typing, if an object used in your test suite looks like a +mock object and quacks like a mock object then it’s fine to call it a mock, no +matter what the implementation looks like.

    +

    This terminology is perhaps more useful in less capable languages where +different usage patterns will require different implementations. +mock.Mock() is capable of being used in most of the different roles +described by Fowler, except (annoyingly / frustratingly / ironically) a Mock +itself!

    +

    How about a simpler definition: a “mock object” is an object used to replace a +real one in a system under test.

    + + + + + +
    [1]This pattern is called “AAA” by some members of the testing community; +“Arrange - Act - Assert”.
    +
    +
    + + +
    +
    +
    +
    +
    +

    Table Of Contents

    + + +

    Next topic

    +

    The Mock Class

    +

    This Page

    + + + +
    +
    +
    +
    +
    +

    Navigation

    + +
    +
    + © Copyright 2007-2012, Michael Foord & the mock team. + Last updated on Oct 07, 2012. + Created using Sphinx 1.1.3. +
    + + \ No newline at end of file diff --git a/python/mock-1.0.0/html/magicmock.html b/python/mock-1.0.0/html/magicmock.html new file mode 100644 index 000000000..f49fae763 --- /dev/null +++ b/python/mock-1.0.0/html/magicmock.html @@ -0,0 +1,347 @@ + + + + + + + + + Mocking Magic Methods — Mock 1.0.0 documentation + + + + + + + + + + + + + +
    +

    Navigation

    + +
    + +
    +
    +
    +
    + +
    +

    Mocking Magic Methods¶

    +

    Mock supports mocking 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 [1], 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 [2].

    +
    >>> 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 method_calls, but they +are recorded in mock_calls.

    +
    +

    Note

    +

    If you use the spec keyword argument to create a mock then attempting to +set a magic method that isn’t in the spec will raise an AttributeError.

    +
    +

    The full list of supported magic methods is:

    +
      +
    • __hash__, __sizeof__, __repr__ and __str__
      • +
    • __dir__, __format__ and __subclasses__
      • +
    • __floor__, __trunc__ and __ceil__
      • +
    • Comparisons: __cmp__, __lt__, __gt__, __le__, __ge__, +__eq__ and __ne__
      • +
    • Container methods: __getitem__, __setitem__, __delitem__, +__contains__, __len__, __iter__, __getslice__, +__setslice__, __reversed__ and __missing__
      • +
    • Context manager: __enter__ and __exit__
      • +
    • Unary numeric methods: __neg__, __pos__ and __invert__
      • +
    • The numeric methods (including right hand and in-place variants): +__add__, __sub__, __mul__, __div__, +__floordiv__, __mod__, __divmod__, __lshift__, +__rshift__, __and__, __xor__, __or__, and __pow__
      • +
    • Numeric conversion methods: __complex__, __int__, __float__, +__index__ and __coerce__
      • +
    • Descriptor methods: __get__, __set__ and __delete__
      • +
    • Pickling: __reduce__, __reduce_ex__, __getinitargs__, +__getnewargs__, __getstate__ and __setstate__
      • +
    +

    The following methods are supported in Python 2 but don’t exist in Python 3:

    +
      +
    • __unicode__, __long__, __oct__, __hex__ and __nonzero__
      • +
    • __truediv__ and __rtruediv__
      • +
    +

    The following methods are supported in Python 3 but don’t exist in Python 2:

    +
      +
    • __bool__ and __next__
      • +
    +

    The following methods exist but are not supported as they are either in use by +mock, can’t be set dynamically, or can cause problems:

    +
      +
    • __getattr__, __setattr__, __init__ and __new__
      • +
    • __prepare__, __instancecheck__, __subclasscheck__, __del__
      • +
    +
    +
    +

    Magic Mock¶

    +

    There are two MagicMock variants: MagicMock and NonCallableMagicMock.

    +
    +
    +class MagicMock(*args, **kw)¶
    +

    MagicMock is a subclass of 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 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 +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
      • +
    • __nonzero__ : True
      • +
    • __oct__ : ‘1’
      • +
    • __hex__ : ‘0x1’
      • +
    • __long__ : long(1)
      • +
    • __index__ : 1
      • +
    • __hash__ : default hash for the mock
      • +
    • __str__ : default str for the mock
      • +
    • __unicode__ : default unicode for the mock
      • +
    • __sizeof__: default sizeof for the mock
      • +
    +

    For example:

    +
    >>> mock = MagicMock()
+>>> int(mock)
+1
+>>> len(mock)
+0
+>>> hex(mock)
+'0x1'
+>>> list(mock)
+[]
+>>> object() in mock
+False
+
    +
    +

    The two equality method, __eq__ and __ne__, are special (changed in +0.7.2). They do the default equality comparison on identity, using a side +effect, unless you change their return value to return something else:

    +
    >>> MagicMock() == 3
+False
+>>> MagicMock() != 3
+True
+>>> mock = MagicMock()
+>>> mock.__eq__.return_value = True
+>>> mock == 3
+True
+
    +
    +

    In 0.8 the __iter__ also gained special handling implemented with a +side effect. The return value of MagicMock.__iter__ can be any iterable +object and isn’t required to be an iterator:

    +
    >>> 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:

    +
      +
    • __cmp__
      • +
    • __getslice__ and __setslice__
      • +
    • __coerce__
      • +
    • __subclasses__
      • +
    • __dir__
      • +
    • __format__
      • +
    • __get__, __set__ and __delete__
      • +
    • __reversed__ and __missing__
      • +
    • __reduce__, __reduce_ex__, __getinitargs__, __getnewargs__, +__getstate__ and __setstate__
      • +
    • __getformat__ and __setformat__
      • +
    +
    + + + + + +
    [1]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.
    + + + + + +
    [2]The function is basically hooked up to the class, but each Mock +instance is kept isolated from the others.
    +
    + + +
    +
    +
    +
    +
    +

    Table Of Contents

    + + +

    Previous topic

    +

    Sentinel

    +

    Next topic

    +

    Getting Started with Mock

    +

    This Page

    + + + +
    +
    +
    +
    +
    +

    Navigation

    + +
    +
    + © Copyright 2007-2012, Michael Foord & the mock team. + Last updated on Oct 07, 2012. + Created using Sphinx 1.1.3. +
    + + \ No newline at end of file diff --git a/python/mock-1.0.0/html/mock.html b/python/mock-1.0.0/html/mock.html new file mode 100644 index 000000000..84ba37b2b --- /dev/null +++ b/python/mock-1.0.0/html/mock.html @@ -0,0 +1,875 @@ + + + + + + + + + The Mock Class — Mock 1.0.0 documentation + + + + + + + + + + + + + +
    +

    Navigation

    + +
    + +
    +
    +
    +
    + +
    +

    The Mock Class¶

    +

    Mock is a flexible mock object intended to replace the use of stubs and +test doubles throughout your code. Mocks are callable and create attributes as +new mocks when you access them [1]. Accessing the same attribute will always +return the same mock. Mocks record how you use them, allowing you to make +assertions about what your code has done to them.

    +

    MagicMock is a subclass of Mock with all the magic methods +pre-created and ready to use. There are also non-callable variants, useful +when you are mocking out objects that aren’t callable: +NonCallableMock and NonCallableMagicMock

    +

    The patch() decorators makes it easy to temporarily replace classes +in a particular module with a Mock object. By default patch will create +a MagicMock for you. You can specify an alternative class of Mock using +the new_callable argument to patch.

    +
    +
    +class Mock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, **kwargs)¶
    +

    Create a new Mock object. Mock takes several optional arguments +that specify the behaviour of the Mock object:

    +
      +

    • spec: This can be either a list of strings or an existing object (a +class or instance) that acts as the specification for the mock object. If +you pass in an object then a list of strings is formed by calling dir on +the object (excluding unsupported magic attributes and methods). +Accessing any attribute not in this list will raise an AttributeError.

      +

      If spec is an object (rather than a list of strings) then +__class__ returns the class of the spec object. This allows mocks +to pass isinstance tests.

      +
      • +

    • spec_set: A stricter variant of spec. If used, attempting to set +or get an attribute on the mock that isn’t on the object passed as +spec_set will raise an AttributeError.

      +
      • +

    • side_effect: A function to be called whenever the Mock is called. See +the side_effect attribute. Useful for raising exceptions or +dynamically changing return values. The function is called with the same +arguments as the mock, and unless it returns DEFAULT, the return +value of this function is used as the return value.

      +

      Alternatively side_effect can be an exception class or instance. In +this case the exception will be raised when the mock is called.

      +

      If side_effect is an iterable then each call to the mock will return +the next value from the iterable. If any of the members of the iterable +are exceptions they will be raised instead of returned.

      +

      A side_effect can be cleared by setting it to None.

      +
      • +

    • return_value: The value returned when the mock is called. By default +this is a new Mock (created on first access). See the +return_value attribute.

      +
      • +

    • wraps: Item for the mock object to wrap. If wraps is not None then +calling the Mock will pass the call through to the wrapped object +(returning the real result and ignoring return_value). Attribute access +on the mock will return a Mock object that wraps the corresponding +attribute of the wrapped object (so attempting to access an attribute +that doesn’t exist will raise an AttributeError).

      +

      If the mock has an explicit return_value set then calls are not passed +to the wrapped object and the return_value is returned instead.

      +
      • +

    • name: If the mock has a name then it will be used in the repr of the +mock. This can be useful for debugging. The name is propagated to child +mocks.

      +
      • +
    +

    Mocks can also be called with arbitrary keyword arguments. These will be +used to set attributes on the mock after it is created. See the +configure_mock() method for details.

    +
    +
    +assert_called_with(*args, **kwargs)¶
    +

    This method is a convenient way of asserting that calls are made in a +particular way:

    +
    >>> mock = Mock()
+>>> mock.method(1, 2, 3, test='wow')
+<Mock name='mock.method()' id='...'>
+>>> mock.method.assert_called_with(1, 2, 3, test='wow')
+
    +
    +
    + +
    +
    +assert_called_once_with(*args, **kwargs)¶
    +

    Assert that the mock was called exactly once and with the specified +arguments.

    +
    >>> mock = Mock(return_value=None)
+>>> mock('foo', bar='baz')
+>>> mock.assert_called_once_with('foo', bar='baz')
+>>> mock('foo', bar='baz')
+>>> mock.assert_called_once_with('foo', bar='baz')
+Traceback (most recent call last):
+  ...
+AssertionError: Expected to be called once. Called 2 times.
+
    +
    +
    + +
    +
    +assert_any_call(*args, **kwargs)¶
    +

    assert the mock has been called with the specified arguments.

    +

    The assert passes if the mock has ever been called, unlike +assert_called_with() and assert_called_once_with() that +only pass if the call is the most recent one.

    +
    >>> mock = Mock(return_value=None)
+>>> mock(1, 2, arg='thing')
+>>> mock('some', 'thing', 'else')
+>>> mock.assert_any_call(1, 2, arg='thing')
+
    +
    +
    + +
    +
    +assert_has_calls(calls, any_order=False)¶
    +

    assert the mock has been called with the specified calls. +The mock_calls list is checked for the calls.

    +

    If any_order is False (the default) then the calls must be +sequential. There can be extra calls before or after the +specified calls.

    +

    If any_order is True then the calls can be in any order, but +they must all appear in mock_calls.

    +
    >>> mock = Mock(return_value=None)
+>>> mock(1)
+>>> mock(2)
+>>> mock(3)
+>>> mock(4)
+>>> calls = [call(2), call(3)]
+>>> mock.assert_has_calls(calls)
+>>> calls = [call(4), call(2), call(3)]
+>>> mock.assert_has_calls(calls, any_order=True)
+
    +
    +
    + +
    +
    +reset_mock()¶
    +

    The reset_mock method resets all the call attributes on a mock object:

    +
    >>> mock = Mock(return_value=None)
+>>> mock('hello')
+>>> mock.called
+True
+>>> mock.reset_mock()
+>>> mock.called
+False
+
    +
    +

    This can be useful where you want to make a series of assertions that +reuse the same object. Note that reset_mock doesn’t clear the +return value, side_effect or any child attributes you have +set using normal assignment. Child mocks and the return value mock +(if any) are reset as well.

    +
    + +
    +
    +mock_add_spec(spec, spec_set=False)¶
    +

    Add a spec to a mock. spec can either be an object or a +list of strings. Only attributes on the spec can be fetched as +attributes from the mock.

    +

    If spec_set is True then only attributes on the spec can be set.

    +
    + +
    +
    +attach_mock(mock, attribute)¶
    +

    Attach a mock as an attribute of this one, replacing its name and +parent. Calls to the attached mock will be recorded in the +method_calls and mock_calls attributes of this one.

    +
    + +
    +
    +configure_mock(**kwargs)¶
    +

    Set attributes on the mock through keyword arguments.

    +

    Attributes plus return values and side effects can be set on child +mocks using standard dot notation and unpacking a dictionary in the +method call:

    +
    >>> mock = Mock()
+>>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError}
+>>> mock.configure_mock(**attrs)
+>>> mock.method()
+3
+>>> mock.other()
+Traceback (most recent call last):
+  ...
+KeyError
+
    +
    +

    The same thing can be achieved in the constructor call to mocks:

    +
    >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError}
+>>> mock = Mock(some_attribute='eggs', **attrs)
+>>> mock.some_attribute
+'eggs'
+>>> mock.method()
+3
+>>> mock.other()
+Traceback (most recent call last):
+  ...
+KeyError
+
    +
    +

    configure_mock exists to make it easier to do configuration +after the mock has been created.

    +
    + +
    +
    +__dir__()¶
    +

    Mock objects limit the results of dir(some_mock) to useful results. +For mocks with a spec this includes all the permitted attributes +for the mock.

    +

    See FILTER_DIR for what this filtering does, and how to +switch it off.

    +
    + +
    +
    +_get_child_mock(**kw)¶
    +

    Create the child mocks for attributes and return value. +By default child mocks will be the same type as the parent. +Subclasses of Mock may want to override this to customize the way +child mocks are made.

    +

    For non-callable mocks the callable variant will be used (rather than +any custom subclass).

    +
    + +
    +
    +called¶
    +

    A boolean representing whether or not the mock object has been called:

    +
    >>> mock = Mock(return_value=None)
+>>> mock.called
+False
+>>> mock()
+>>> mock.called
+True
+
    +
    +
    + +
    +
    +call_count¶
    +

    An integer telling you how many times the mock object has been called:

    +
    >>> mock = Mock(return_value=None)
+>>> mock.call_count
+0
+>>> mock()
+>>> mock()
+>>> mock.call_count
+2
+
    +
    +
    + +
    +
    +return_value¶
    +

    Set this to configure the value returned by calling the mock:

    +
    >>> mock = Mock()
+>>> mock.return_value = 'fish'
+>>> mock()
+'fish'
+
    +
    +

    The default return value is a mock object and you can configure it in +the normal way:

    +
    >>> mock = Mock()
+>>> mock.return_value.attribute = sentinel.Attribute
+>>> mock.return_value()
+<Mock name='mock()()' id='...'>
+>>> mock.return_value.assert_called_with()
+
    +
    +

    return_value can also be set in the constructor:

    +
    >>> mock = Mock(return_value=3)
+>>> mock.return_value
+3
+>>> mock()
+3
+
    +
    +
    + +
    +
    +side_effect¶
    +

    This can either be a function to be called when the mock is called, +or an exception (class or instance) to be raised.

    +

    If you pass in a function it will be called with same arguments as the +mock and unless the function returns the DEFAULT singleton the +call to the mock will then return whatever the function returns. If the +function returns DEFAULT then the mock will return its normal +value (from the return_value.

    +

    An example of a mock that raises an exception (to test exception +handling of an API):

    +
    >>> mock = Mock()
+>>> mock.side_effect = Exception('Boom!')
+>>> mock()
+Traceback (most recent call last):
+  ...
+Exception: Boom!
+
    +
    +

    Using side_effect to return a sequence of values:

    +
    >>> mock = Mock()
+>>> mock.side_effect = [3, 2, 1]
+>>> mock(), mock(), mock()
+(3, 2, 1)
+
    +
    +

    The side_effect function is called with the same arguments as the +mock (so it is wise for it to take arbitrary args and keyword +arguments) and whatever it returns is used as the return value for +the call. The exception is if side_effect returns DEFAULT, +in which case the normal return_value is used.

    +
    >>> mock = Mock(return_value=3)
+>>> def side_effect(*args, **kwargs):
+...     return DEFAULT
+...
+>>> mock.side_effect = side_effect
+>>> mock()
+3
+
    +
    +

    side_effect can be set in the constructor. Here’s an example that +adds one to the value the mock is called with and returns it:

    +
    >>> side_effect = lambda value: value + 1
+>>> mock = Mock(side_effect=side_effect)
+>>> mock(3)
+4
+>>> mock(-8)
+-7
+
    +
    +

    Setting side_effect to None clears it:

    +
    >>> from mock import Mock
+>>> m = Mock(side_effect=KeyError, return_value=3)
+>>> m()
+Traceback (most recent call last):
+ ...
+KeyError
+>>> m.side_effect = None
+>>> m()
+3
+
    +
    +
    + +
    +
    +call_args¶
    +

    This is either None (if the mock hasn’t been called), or the +arguments that the mock was last called with. This will be in the +form of a tuple: the first member is any ordered arguments the mock +was called with (or an empty tuple) and the second member is any +keyword arguments (or an empty dictionary).

    +
    >>> mock = Mock(return_value=None)
+>>> print mock.call_args
+None
+>>> mock()
+>>> mock.call_args
+call()
+>>> mock.call_args == ()
+True
+>>> mock(3, 4)
+>>> mock.call_args
+call(3, 4)
+>>> mock.call_args == ((3, 4),)
+True
+>>> mock(3, 4, 5, key='fish', next='w00t!')
+>>> mock.call_args
+call(3, 4, 5, key='fish', next='w00t!')
+
    +
    +

    call_args, along with members of the lists call_args_list, +method_calls and mock_calls are call objects. +These are tuples, so they can be unpacked to get at the individual +arguments and make more complex assertions. See +calls as tuples.

    +
    + +
    +
    +call_args_list¶
    +

    This is a list of all the calls made to the mock object in sequence +(so the length of the list is the number of times it has been +called). Before any calls have been made it is an empty list. The +call object can be used for conveniently constructing lists of +calls to compare with call_args_list.

    +
    >>> mock = Mock(return_value=None)
+>>> mock()
+>>> mock(3, 4)
+>>> mock(key='fish', next='w00t!')
+>>> mock.call_args_list
+[call(), call(3, 4), call(key='fish', next='w00t!')]
+>>> expected = [(), ((3, 4),), ({'key': 'fish', 'next': 'w00t!'},)]
+>>> mock.call_args_list == expected
+True
+
    +
    +

    Members of call_args_list are call objects. These can be +unpacked as tuples to get at the individual arguments. See +calls as tuples.

    +
    + +
    +
    +method_calls¶
    +

    As well as tracking calls to themselves, mocks also track calls to +methods and attributes, and their methods and attributes:

    +
    >>> mock = Mock()
+>>> mock.method()
+<Mock name='mock.method()' id='...'>
+>>> mock.property.method.attribute()
+<Mock name='mock.property.method.attribute()' id='...'>
+>>> mock.method_calls
+[call.method(), call.property.method.attribute()]
+
    +
    +

    Members of method_calls are call objects. These can be +unpacked as tuples to get at the individual arguments. See +calls as tuples.

    +
    + +
    +
    +mock_calls¶
    +

    mock_calls records all calls to the mock object, its methods, magic +methods and return value mocks.

    +
    >>> mock = MagicMock()
+>>> result = mock(1, 2, 3)
+>>> mock.first(a=3)
+<MagicMock name='mock.first()' id='...'>
+>>> mock.second()
+<MagicMock name='mock.second()' id='...'>
+>>> int(mock)
+1
+>>> result(1)
+<MagicMock name='mock()()' id='...'>
+>>> expected = [call(1, 2, 3), call.first(a=3), call.second(),
+... call.__int__(), call()(1)]
+>>> mock.mock_calls == expected
+True
+
    +
    +

    Members of mock_calls are call objects. These can be +unpacked as tuples to get at the individual arguments. See +calls as tuples.

    +
    + +
    +
    +__class__¶
    +

    Normally the __class__ attribute of an object will return its type. +For a mock object with a spec __class__ returns the spec class +instead. This allows mock objects to pass isinstance tests for the +object they are replacing / masquerading as:

    +
    >>> mock = Mock(spec=3)
+>>> isinstance(mock, int)
+True
+
    +
    +

    __class__ is assignable to, this allows a mock to pass an +isinstance check without forcing you to use a spec:

    +
    >>> mock = Mock()
+>>> mock.__class__ = dict
+>>> isinstance(mock, dict)
+True
+
    +
    +
    + +
    + +
    +
    +class NonCallableMock(spec=None, wraps=None, name=None, spec_set=None, **kwargs)¶
    +

    A non-callable version of Mock. The constructor parameters have the same +meaning of Mock, with the exception of return_value and side_effect +which have no meaning on a non-callable mock.

    +
    + +

    Mock objects that use a class or an instance as a spec or spec_set are able +to pass isintance tests:

    +
    >>> mock = Mock(spec=SomeClass)
+>>> isinstance(mock, SomeClass)
+True
+>>> mock = Mock(spec_set=SomeClass())
+>>> isinstance(mock, SomeClass)
+True
+
    +
    +

    The Mock classes have support for mocking magic methods. See magic +methods for the full details.

    +

    The mock classes and the patch() decorators all take arbitrary keyword +arguments for configuration. For the patch decorators the keywords are +passed to the constructor of the mock being created. The keyword arguments +are for configuring attributes of the mock:

    +
    >>> m = MagicMock(attribute=3, other='fish')
+>>> m.attribute
+3
+>>> m.other
+'fish'
+
    +
    +

    The return value and side effect of child mocks can be set in the same way, +using dotted notation. As you can’t use dotted names directly in a call you +have to create a dictionary and unpack it using **:

    +
    >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError}
+>>> mock = Mock(some_attribute='eggs', **attrs)
+>>> mock.some_attribute
+'eggs'
+>>> mock.method()
+3
+>>> mock.other()
+Traceback (most recent call last):
+  ...
+KeyError
+
    +
    +
    +
    +class PropertyMock(*args, **kwargs)¶
    +

    A mock intended to be used as a property, or other descriptor, on a class. +PropertyMock provides __get__ and __set__ methods so you can specify +a return value when it is fetched.

    +

    Fetching a PropertyMock instance from an object calls the mock, with +no args. Setting it calls the mock with the value being set.

    +
    >>> class Foo(object):
+...     @property
+...     def foo(self):
+...         return 'something'
+...     @foo.setter
+...     def foo(self, value):
+...         pass
+...
+>>> with patch('__main__.Foo.foo', new_callable=PropertyMock) as mock_foo:
+...     mock_foo.return_value = 'mockity-mock'
+...     this_foo = Foo()
+...     print this_foo.foo
+...     this_foo.foo = 6
+...
+mockity-mock
+>>> mock_foo.mock_calls
+[call(), call(6)]
+
    +
    +
    + +

    Because of the way mock attributes are stored you can’t directly attach a +PropertyMock to a mock object. Instead you can attach it to the mock type +object:

    +
    >>> m = MagicMock()
+>>> p = PropertyMock(return_value=3)
+>>> type(m).foo = p
+>>> m.foo
+3
+>>> p.assert_called_once_with()
+
    +
    +
    +
    +

    Calling¶

    +

    Mock objects are callable. The call will return the value set as the +return_value attribute. The default return value is a new Mock +object; it is created the first time the return value is accessed (either +explicitly or by calling the Mock) - but it is stored and the same one +returned each time.

    +

    Calls made to the object will be recorded in the attributes +like call_args and call_args_list.

    +

    If side_effect is set then it will be called after the call has +been recorded, so if side_effect raises an exception the call is still +recorded.

    +

    The simplest way to make a mock raise an exception when called is to make +side_effect an exception class or instance:

    +
    >>> m = MagicMock(side_effect=IndexError)
+>>> m(1, 2, 3)
+Traceback (most recent call last):
+  ...
+IndexError
+>>> m.mock_calls
+[call(1, 2, 3)]
+>>> m.side_effect = KeyError('Bang!')
+>>> m('two', 'three', 'four')
+Traceback (most recent call last):
+  ...
+KeyError: 'Bang!'
+>>> m.mock_calls
+[call(1, 2, 3), call('two', 'three', 'four')]
+
    +
    +

    If side_effect is a function then whatever that function returns is what +calls to the mock return. The side_effect function is called with the +same arguments as the mock. This allows you to vary the return value of the +call dynamically, based on the input:

    +
    >>> def side_effect(value):
+...     return value + 1
+...
+>>> m = MagicMock(side_effect=side_effect)
+>>> m(1)
+2
+>>> m(2)
+3
+>>> m.mock_calls
+[call(1), call(2)]
+
    +
    +

    If you want the mock to still return the default return value (a new mock), or +any set return value, then there are two ways of doing this. Either return +mock.return_value from inside side_effect, or return DEFAULT:

    +
    >>> m = MagicMock()
+>>> def side_effect(*args, **kwargs):
+...     return m.return_value
+...
+>>> m.side_effect = side_effect
+>>> m.return_value = 3
+>>> m()
+3
+>>> def side_effect(*args, **kwargs):
+...     return DEFAULT
+...
+>>> m.side_effect = side_effect
+>>> m()
+3
+
    +
    +

    To remove a side_effect, and return to the default behaviour, set the +side_effect to None:

    +
    >>> m = MagicMock(return_value=6)
+>>> def side_effect(*args, **kwargs):
+...     return 3
+...
+>>> m.side_effect = side_effect
+>>> m()
+3
+>>> m.side_effect = None
+>>> m()
+6
+
    +
    +

    The side_effect can also be any iterable object. Repeated calls to the mock +will return values from the iterable (until the iterable is exhausted and +a StopIteration is raised):

    +
    >>> m = MagicMock(side_effect=[1, 2, 3])
+>>> m()
+1
+>>> m()
+2
+>>> m()
+3
+>>> m()
+Traceback (most recent call last):
+  ...
+StopIteration
+
    +
    +

    If any members of the iterable are exceptions they will be raised instead of +returned:

    +
    >>> iterable = (33, ValueError, 66)
+>>> m = MagicMock(side_effect=iterable)
+>>> m()
+33
+>>> m()
+Traceback (most recent call last):
+ ...
+ValueError
+>>> m()
+66
+
    +
    +
    +
    +

    Deleting Attributes¶

    +

    Mock objects create attributes on demand. This allows them to pretend to be +objects of any type.

    +

    You may want a mock object to return False to a hasattr call, or raise an +AttributeError when an attribute is fetched. You can do this by providing +an object as a spec for a mock, but that isn’t always convenient.

    +

    You “block” attributes by deleting them. Once deleted, accessing an attribute +will raise an AttributeError.

    +
    >>> mock = MagicMock()
+>>> hasattr(mock, 'm')
+True
+>>> del mock.m
+>>> hasattr(mock, 'm')
+False
+>>> del mock.f
+>>> mock.f
+Traceback (most recent call last):
+    ...
+AttributeError: f
+
    +
    +
    +
    +

    Attaching Mocks as Attributes¶

    +

    When you attach a mock as an attribute of another mock (or as the return +value) it becomes a “child” of that mock. Calls to the child are recorded in +the method_calls and mock_calls attributes of the +parent. This is useful for configuring child mocks and then attaching them to +the parent, or for attaching mocks to a parent that records all calls to the +children and allows you to make assertions about the order of calls between +mocks:

    +
    >>> parent = MagicMock()
+>>> child1 = MagicMock(return_value=None)
+>>> child2 = MagicMock(return_value=None)
+>>> parent.child1 = child1
+>>> parent.child2 = child2
+>>> child1(1)
+>>> child2(2)
+>>> parent.mock_calls
+[call.child1(1), call.child2(2)]
+
    +
    +

    The exception to this is if the mock has a name. This allows you to prevent +the “parenting” if for some reason you don’t want it to happen.

    +
    >>> mock = MagicMock()
+>>> not_a_child = MagicMock(name='not-a-child')
+>>> mock.attribute = not_a_child
+>>> mock.attribute()
+<MagicMock name='not-a-child()' id='...'>
+>>> mock.mock_calls
+[]
+
    +
    +

    Mocks created for you by patch() are automatically given names. To +attach mocks that have names to a parent you use the attach_mock() +method:

    +
    >>> thing1 = object()
+>>> thing2 = object()
+>>> parent = MagicMock()
+>>> with patch('__main__.thing1', return_value=None) as child1:
+...     with patch('__main__.thing2', return_value=None) as child2:
+...         parent.attach_mock(child1, 'child1')
+...         parent.attach_mock(child2, 'child2')
+...         child1('one')
+...         child2('two')
+...
+>>> parent.mock_calls
+[call.child1('one'), call.child2('two')]
+
    +
    +
    + + + + + +
    [1]The only exceptions are magic methods and attributes (those that have +leading and trailing double underscores). Mock doesn’t create these but +instead of raises an AttributeError. This is because the interpreter +will often implicitly request these methods, and gets very confused to +get a new Mock object when it expects a magic method. If you need magic +method support see magic methods.
    +
    + + +
    +
    +
    +
    +
    +

    Table Of Contents

    + + +

    Previous topic

    +

    Mock - Mocking and Testing Library

    +

    Next topic

    +

    Patch Decorators

    +

    This Page

    + + + +
    +
    +
    +
    +
    +

    Navigation

    + +
    +
    + © Copyright 2007-2012, Michael Foord & the mock team. + Last updated on Oct 07, 2012. + Created using Sphinx 1.1.3. +
    + + \ No newline at end of file diff --git a/python/mock-1.0.0/html/mocksignature.html b/python/mock-1.0.0/html/mocksignature.html new file mode 100644 index 000000000..5b266f031 --- /dev/null +++ b/python/mock-1.0.0/html/mocksignature.html @@ -0,0 +1,352 @@ + + + + + + + + + mocksignature — Mock 0.8.1alpha1 documentation + + + + + + + + + + + + + +
    +

    Navigation

    + +
    + +
    +
    +
    +
    + +
    +

    mocksignature¶

    +
    +

    Note

    +

    Autospeccing, added in mock 0.8, is a more advanced version of +mocksignature and can be used for many of the same use cases.

    +
    +

    A problem with using mock objects to replace real objects in your tests is that +Mock can be too flexible. Your code can treat the mock objects in +any way and you have to manually check that they were called correctly. If your +code calls functions or methods with the wrong number of arguments then mocks +don’t complain.

    +

    The solution to this is mocksignature, which creates functions with the +same signature as the original, but delegating to a mock. You can interrogate +the mock in the usual way to check it has been called with the right +arguments, but if it is called with the wrong number of arguments it will +raise a TypeError in the same way your production code would.

    +

    Another advantage is that your mocked objects are real functions, which can +be useful when your code uses +inspect or depends on +functions being function objects.

    +
    +
    +mocksignature(func, mock=None, skipfirst=False)¶
    +

    Create a new function with the same signature as func that delegates +to mock. If skipfirst is True the first argument is skipped, useful +for methods where self needs to be omitted from the new function.

    +

    If you don’t pass in a mock then one will be created for you.

    +

    Functions returned by mocksignature have many of the same attributes +and assert methods as a mock object.

    +

    The mock is set as the mock attribute of the returned function for easy +access.

    +

    mocksignature can also be used with classes. It copies the signature of +the __init__ method.

    +

    When used with callable objects (instances) it copies the signature of the +__call__ method.

    +
    + +

    mocksignature will work out if it is mocking the signature of a method on +an instance or a method on a class and do the “right thing” with the self +argument in both cases.

    +

    Because of a limitation in the way that arguments are collected by functions +created by mocksignature they are always passed as positional arguments +(including defaults) and not keyword arguments.

    +
    +

    mocksignature api¶

    +

    Although the objects returned by mocksignature api are real function objects, +they have much of the same api as the Mock class. This includes the +assert methods:

    +
    >>> def func(a, b, c):
+...     pass
+...
+>>> func2 = mocksignature(func)
+>>> func2.called
+False
+>>> func2.return_value = 3
+>>> func2(1, 2, 3)
+3
+>>> func2.called
+True
+>>> func2.assert_called_once_with(1, 2, 3)
+>>> func2.assert_called_with(1, 2, 4)
+Traceback (most recent call last):
+  ...
+AssertionError: Expected call: mock(1, 2, 4)
+Actual call: mock(1, 2, 3)
+>>> func2.call_count
+1
+>>> func2.side_effect = IndexError
+>>> func2(4, 5, 6)
+Traceback (most recent call last):
+  ...
+IndexError
+
    +
    +

    The mock object that is being delegated to is available as the mock attribute +of the function created by mocksignature.

    +
    >>> func2.mock.mock_calls
+[call(1, 2, 3), call(4, 5, 6)]
+
    +
    +

    The methods and attributes available on functions returned by mocksignature +are:

    +
    +
    +
    +
    +

    Example use¶

    +
    +

    Basic use¶

    +
    >>> def function(a, b, c=None):
+...     pass
+...
+>>> mock = Mock()
+>>> function = mocksignature(function, mock)
+>>> function()
+Traceback (most recent call last):
+  ...
+TypeError: <lambda>() takes at least 2 arguments (0 given)
+>>> function.return_value = 'some value'
+>>> function(1, 2, 'foo')
+'some value'
+>>> function.assert_called_with(1, 2, 'foo')
+
    +
    +
    +
    +

    Keyword arguments¶

    +

    Note that arguments to functions created by mocksignature are always passed +in to the underlying mock by position even when called with keywords:

    +
    >>> def function(a, b, c=None):
+...     pass
+...
+>>> function = mocksignature(function)
+>>> function.return_value = None
+>>> function(1, 2)
+>>> function.assert_called_with(1, 2, None)
+
    +
    +
    +
    +

    Mocking methods and self¶

    +

    When you use mocksignature to replace a method on a class then self +will be included in the method signature - and you will need to include +the instance when you do your asserts.

    +

    As a curious factor of the way Python (2) wraps methods fetched from a class, +we can get the return_value from a function set on a class, but we can’t +set it. We have to do this through the exposed mock attribute instead:

    +
    >>> class SomeClass(object):
+...     def method(self, a, b, c=None):
+...         pass
+...
+>>> SomeClass.method = mocksignature(SomeClass.method)
+>>> SomeClass.method.mock.return_value = None
+>>> instance = SomeClass()
+>>> instance.method()
+Traceback (most recent call last):
+  ...
+TypeError: <lambda>() takes at least 4 arguments (1 given)
+>>> instance.method(1, 2, 3)
+>>> instance.method.assert_called_with(instance, 1, 2, 3)
+
    +
    +

    When you use mocksignature on instance methods self isn’t included (and we +can set the return_value etc directly):

    +
    >>> class SomeClass(object):
+...     def method(self, a, b, c=None):
+...         pass
+...
+>>> instance = SomeClass()
+>>> instance.method = mocksignature(instance.method)
+>>> instance.method.return_value = None
+>>> instance.method(1, 2, 3)
+>>> instance.method.assert_called_with(1, 2, 3)
+
    +
    +
    +
    +

    mocksignature with classes¶

    +

    When used with a class mocksignature copies the signature of the __init__ +method.

    +
    >>> class Something(object):
+...     def __init__(self, foo, bar):
+...         pass
+...
+>>> MockSomething = mocksignature(Something)
+>>> instance = MockSomething(10, 9)
+>>> assert instance is MockSomething.return_value
+>>> MockSomething.assert_called_with(10, 9)
+>>> MockSomething()
+Traceback (most recent call last):
+  ...
+TypeError: <lambda>() takes at least 2 arguments (0 given)
+
    +
    +

    Because the object returned by mocksignature is a function rather than a +Mock you lose the other capabilities of Mock, like dynamic attribute +creation.

    +
    +
    +

    mocksignature with callable objects¶

    +

    When used with a callable object mocksignature copies the signature of the +__call__ method.

    +
    >>> class Something(object):
+...     def __call__(self, spam, eggs):
+...         pass
+...
+>>> something = Something()
+>>> mock_something = mocksignature(something)
+>>> result = mock_something(10, 9)
+>>> mock_something.assert_called_with(10, 9)
+>>> mock_something()
+Traceback (most recent call last):
+  ...
+TypeError: <lambda>() takes at least 2 arguments (0 given)
+
    +
    +
    +
    +
    +

    mocksignature argument to patch¶

    +

    mocksignature is available as a keyword argument to patch() or +patch.object(). It can be used with functions / methods / classes and +callable objects.

    +
    >>> class SomeClass(object):
+...     def method(self, a, b, c=None):
+...         pass
+...
+>>> @patch.object(SomeClass, 'method', mocksignature=True)
+... def test(mock_method):
+...     instance = SomeClass()
+...     mock_method.return_value = None
+...     instance.method(1, 2)
+...     mock_method.assert_called_with(instance, 1, 2, None)
+...
+>>> test()
+
    +
    +
    +
    + + +
    +
    +
    +
    +
    +

    Table Of Contents

    + + +

    Previous topic

    +

    Mocking Magic Methods

    +

    Next topic

    +

    Getting Started with Mock

    +

    This Page

    + + + +
    +
    +
    +
    +
    +

    Navigation

    + +
    +
    + © Copyright 2007-2012, Michael Foord & the mock team. + Last updated on Feb 16, 2012. + Created using Sphinx 1.1.2. +
    + + \ No newline at end of file diff --git a/python/mock-1.0.0/html/objects.inv b/python/mock-1.0.0/html/objects.inv new file mode 100644 index 000000000..363889257 Binary files /dev/null and b/python/mock-1.0.0/html/objects.inv differ diff --git a/python/mock-1.0.0/html/output.txt b/python/mock-1.0.0/html/output.txt new file mode 100644 index 000000000..56093e750 --- /dev/null +++ b/python/mock-1.0.0/html/output.txt @@ -0,0 +1,126 @@ +Results of doctest builder run on 2012-10-07 18:33:27 +===================================================== + +Document: index +--------------- +1 items passed all tests: + 35 tests in default +35 tests in 1 items. +35 passed and 0 failed. +Test passed. +1 items passed all tests: + 1 tests in default (cleanup code) +1 tests in 1 items. +1 passed and 0 failed. +Test passed. + +Document: compare +----------------- +1 items passed all tests: + 39 tests in default +39 tests in 1 items. +39 passed and 0 failed. +Test passed. +1 items passed all tests: + 1 tests in default (cleanup code) +1 tests in 1 items. +1 passed and 0 failed. +Test passed. + +Document: getting-started +------------------------- +1 items passed all tests: + 83 tests in default +83 tests in 1 items. +83 passed and 0 failed. +Test passed. +1 items passed all tests: + 1 tests in default (cleanup code) +1 tests in 1 items. +1 passed and 0 failed. +Test passed. + +Document: magicmock +------------------- +1 items passed all tests: + 40 tests in default +40 tests in 1 items. +40 passed and 0 failed. +Test passed. +1 items passed all tests: + 1 tests in default (cleanup code) +1 tests in 1 items. +1 passed and 0 failed. +Test passed. + +Document: patch +--------------- +1 items passed all tests: + 75 tests in default +75 tests in 1 items. +75 passed and 0 failed. +Test passed. +1 items passed all tests: + 2 tests in default (cleanup code) +2 tests in 1 items. +2 passed and 0 failed. +Test passed. + +Document: helpers +----------------- +1 items passed all tests: + 87 tests in default +87 tests in 1 items. +87 passed and 0 failed. +Test passed. +1 items passed all tests: + 2 tests in default (cleanup code) +2 tests in 1 items. +2 passed and 0 failed. +Test passed. + +Document: examples +------------------ +1 items passed all tests: + 171 tests in default +171 tests in 1 items. +171 passed and 0 failed. +Test passed. +1 items passed all tests: + 1 tests in default (cleanup code) +1 tests in 1 items. +1 passed and 0 failed. +Test passed. + +Document: sentinel +------------------ +1 items passed all tests: + 6 tests in default +6 tests in 1 items. +6 passed and 0 failed. +Test passed. +1 items passed all tests: + 1 tests in default (cleanup code) +1 tests in 1 items. +1 passed and 0 failed. +Test passed. + +Document: mock +-------------- +1 items passed all tests: + 187 tests in default +187 tests in 1 items. +187 passed and 0 failed. +Test passed. +1 items passed all tests: + 1 tests in default (cleanup code) +1 tests in 1 items. +1 passed and 0 failed. +Test passed. + +Doctest summary +=============== + 723 tests + 0 failures in tests + 0 failures in setup code + 0 failures in cleanup code diff --git a/python/mock-1.0.0/html/patch.html b/python/mock-1.0.0/html/patch.html new file mode 100644 index 000000000..e7164d147 --- /dev/null +++ b/python/mock-1.0.0/html/patch.html @@ -0,0 +1,648 @@ + + + + + + + + + Patch Decorators — Mock 1.0.0 documentation + + + + + + + + + + + + + +
    +

    Navigation

    + +
    + +
    +
    +
    +
    + +
    +

    Patch Decorators¶

    +

    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.

    +
    +
    +
    +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 +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 create_autospec() function and +Autospeccing.

    +

    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 +return_value of the mock that will be used.

    +

    If the class is instantiated multiple times you could use +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 MagicMock for the created mock. For example, if +you wanted a 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 +return_value and 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¶

    +
    +
    +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¶

    +
    +
    +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.

    +
    >>> from mock import patch
+>>> foo = {}
+>>> with patch.dict(foo, {'newkey': 'newvalue'}):
+...     assert foo == {'newkey': 'newvalue'}
+...
+>>> assert foo == {}
+
+>>> import os
+>>> with patch.dict('os.environ', {'newkey': 'newvalue'}):
+...     print os.environ['newkey']
+...
+newvalue
+>>> assert 'newkey' not in os.environ
+
    +
    +

    Keywords can be used in the patch.dict call to set values in the dictionary:

    +
    >>> 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¶

    +
    +
    +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 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 +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
+...
+
    +
    +
    +
    +

    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. unittest2 cleanup functions make 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
+...
+>>> MyTest('test_something').run()
+
    +
    +

    As an added bonus you no longer need to keep a reference to the patcher +object.

    +
    +

    It is also possible to stop all patches which have been started by using +patch.stopall.

    +
    +
    +patch.stopall()¶
    +

    Stop all active patches. Only stops patches started with start.

    +
    + +
    +
    +

    TEST_PREFIX¶

    +

    All of the patchers can be used as class decorators. When used in this way +they wrap every test method on the class. The patchers recognise methods that +start with test as being test methods. This is the same way that the +unittest.TestLoader finds test methods by default.

    +

    It is possible that you want to use a different prefix for your tests. You can +inform the patchers of the different prefix by setting patch.TEST_PREFIX:

    +
    >>> 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.

    +

    Like all context-managers patches can be nested using contextlib’s nested +function; every patching will appear in the tuple after “as”:

    +
    >>> from contextlib import nested
+>>> with nested(
+...         patch('package.module.ClassName1'),
+...         patch('package.module.ClassName2')
+...     ) as (MockClass1, MockClass2):
+...     assert package.module.ClassName1 is MockClass1
+...     assert package.module.ClassName2 is MockClass2
+...
+
    +
    +
    +
    +

    Where to patch¶

    +

    patch works by (temporarily) changing the object that a name points to with +another one. There can be many names pointing to any individual object, so +for patching to work you must ensure that you patch the name used by the system +under test.

    +

    The basic principle is that you patch where an object is looked up, which +is not necessarily the same place as where it is defined. A couple of +examples will help to clarify this.

    +

    Imagine we have a project that we want to test with the following structure:

    +
    a.py
+    -> Defines SomeClass
+
+b.py
+    -> from a import SomeClass
+    -> some_function instantiates SomeClass
    +
    +

    Now we want to test some_function but we want to mock out SomeClass using +patch. The problem is that when we import module b, which we will have to +do then it imports SomeClass from module a. If we use patch to mock out +a.SomeClass then it will have no effect on our test; module b already has a +reference to the real SomeClass and it looks like our patching had no +effect.

    +

    The key is to patch out SomeClass where it is used (or where it is looked up +). In this case some_function will actually look up SomeClass in module b, +where we have imported it. The patching should look like:

    +
    +
    @patch(‘b.SomeClass’)
    +

    However, consider the alternative scenario where instead of from a import +SomeClass module b does import a and some_function uses a.SomeClass. Both +of these import forms are common. In this case the class we want to patch is +being looked up on the a module and so we have to patch a.SomeClass instead:

    +
    +
    @patch(‘a.SomeClass’)
    +
    +
    +

    Patching Descriptors and Proxy Objects¶

    +

    Since version 0.6.0 both patch and patch.object have been able to correctly +patch and restore descriptors: class methods, static methods and properties. +You should patch these on the class rather than an instance.

    +

    Since version 0.7.0 patch and patch.object work correctly with some objects +that proxy attribute access, like the django setttings object.

    +
    +

    Note

    +

    In django import settings and from django.conf import settings +return different objects. If you are using libraries / apps that do both you +may have to patch both. Grrr...

    +
    +
    +
    + + +
    +
    +
    +
    +
    +

    Table Of Contents

    + + +

    Previous topic

    +

    The Mock Class

    +

    Next topic

    +

    Helpers

    +

    This Page

    + + + +
    +
    +
    +
    +
    +

    Navigation

    + +
    +
    + © Copyright 2007-2012, Michael Foord & the mock team. + Last updated on Oct 07, 2012. + Created using Sphinx 1.1.3. +
    + + \ No newline at end of file diff --git a/python/mock-1.0.0/html/search.html b/python/mock-1.0.0/html/search.html new file mode 100644 index 000000000..8e0a907ca --- /dev/null +++ b/python/mock-1.0.0/html/search.html @@ -0,0 +1,99 @@ + + + + + + + + + Search — Mock 1.0.0 documentation + + + + + + + + + + + + + + + +
    +

    Navigation

    + +
    + +
    +
    +
    +
    + +

    Search

    +
    + +

    + Please activate JavaScript to enable the search + functionality. +

    +
    +

    + From here you can search these documents. Enter your search + words into the box below and click "search". Note that the search + function will automatically search for all of the words. Pages + containing fewer words won't appear in the result list. +

    +
    + + + +
    + +
    + +
    + +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +

    Navigation

    + +
    +
    + © Copyright 2007-2012, Michael Foord & the mock team. + Last updated on Oct 07, 2012. + Created using Sphinx 1.1.3. +
    + + \ No newline at end of file diff --git a/python/mock-1.0.0/html/searchindex.js b/python/mock-1.0.0/html/searchindex.js new file mode 100644 index 000000000..a71918b93 --- /dev/null +++ b/python/mock-1.0.0/html/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({objects:{"":{mock:[0,0,1,""]},"mock.patch":{dict:[5,2,1,""],object:[5,2,1,""],multiple:[5,2,1,""],stopall:[5,2,1,""]},"mock.Mock":{reset_mock:[9,5,1,""],method_calls:[9,4,1,""],attach_mock:[9,5,1,""],assert_called_with:[9,5,1,""],assert_has_calls:[9,5,1,""],"_get_child_mock":[9,5,1,""],mock_calls:[9,4,1,""],side_effect:[9,4,1,""],"__class__":[9,4,1,""],assert_called_once_with:[9,5,1,""],call_args_list:[9,4,1,""],configure_mock:[9,5,1,""],return_value:[9,4,1,""],call_count:[9,4,1,""],assert_any_call:[9,5,1,""],mock_add_spec:[9,5,1,""],called:[9,4,1,""],"__dir__":[9,5,1,""],call_args:[9,4,1,""]},mock:{create_autospec:[6,2,1,""],MagicMock:[3,3,1,""],DEFAULT:[8,1,1,""],PropertyMock:[9,3,1,""],NonCallableMock:[9,3,1,""],patch:[5,2,1,""],FILTER_DIR:[6,1,1,""],NonCallableMagicMock:[3,3,1,""],call:[6,2,1,""],sentinel:[8,1,1,""],mock_open:[6,2,1,""],ANY:[6,1,1,""],Mock:[9,3,1,""]},"mock.call":{call_list:[6,5,1,""]}},terms:{"__lshift__":3,"_children":4,demand:[8,6,9],interchang:2,four:9,prefix:[5,6,4],"1alpha1":[],repetit:7,whose:[2,7],typeerror:[0,6,5],patcher:[5,6,7,4],test_foo:7,not_a_child:9,under:[0,2,6,7,5],testabl:7,spec:[0,1,2,3,4,5,6,7,9],everi:[0,2,7,5],risk:4,"__instancecheck__":3,"__oct__":3,"__nonzero__":3,noncallablemock:[5,9,4],sentinelobject:4,readthedoc:[0,4],initialis:6,request:[6,9,4],second:[1,6,7,9,5],even:[5,2,6,7,4],hide:4,"20spy":[],ned:4,introspect:6,calcul:[1,7],"new":[0,1,4,5,7,9],ever:9,never:6,here:[1,6,7,9,5],path:6,interpret:9,datetim:7,permit:9,aka:[],contextmanag:1,propag:[2,9,4],substr:0,articl:0,abstracthttphandl:6,describ:[0,6],would:[2,6,7,4],call:[0,1,2,3,4,5,6,7,9],typo:6,type:[0,3,4,6,7,9],tell:[6,9,4],mock_db:[],relat:0,"__iter__":[5,7,3,4],isatti:[],unpack:[0,9],must:[9,7,3,5],kumar:1,word:[],room:6,restor:[0,2,7,5,4],setup:[0,5,7,3,4],work:[2,3,4,5,6,7],line_buff:[],overrid:[0,1,7,9],give:[2,7],indic:[8,6],caution:5,want:[1,2,3,5,6,7,9],masquerad:9,unstart:4,end:[0,1,2,4,5,7],turn:[2,7],noncallablemagicmock:[6,9,3,4],ordinari:[0,6],how:[0,1,2,4,6,7,9],mockobject:1,mock_cal:[1,2,3,4,6,7,9],verifi:1,config:[7,5],earlier:[],befor:[6,7,9,5],wrong:[0,5],attempt:[0,6,9,3,4],third:[7,4],classmethod:6,obsolet:[3,4],foord:0,delong:4,maintain:[1,4],environ:5,emsli:4,lambda:[0,1,6,7,9],order:[0,1,2,4,5,6,7,9],create_autospec:[0,5,6,4],oper:7,diagnos:[2,4],over:[2,7,3,5],becaus:[2,3,4,5,6,7,9],affect:[6,7],flexibl:[6,9],vari:[0,2,9],fix:[6,4],"__class__":[6,9,4],better:[6,7,4],persist:2,comprehens:7,easier:[7,9,5],them:[0,2,3,4,5,6,7,8,9],thei:[0,1,2,3,4,5,6,7,9],"__setstate__":3,safe:[6,7],"__subclasscheck__":3,bang:9,changelog:[0,4],bonu:5,getvalu:5,each:[1,2,3,5,7,9],debug:9,complet:[1,7],dingu:1,side:[0,1,2,3,4,7,9],mean:[0,1,2,3,4,5,6,7,9],colleagu:[],test_method_calls_someth:[],appengin:0,unbound:[0,6,7],foo_bar:7,got:[],situat:[2,7],standard:[0,4,5,6,7,9],test_someth:[2,5],"__setitem__":[7,3,5],call_list:[2,6,7,4],bernhadt:1,traceback:[0,1,2,4,5,6,7,9],"_patch":4,filter:[6,9,4],isn:[9,6,7,3,4],onto:[7,4],bite:7,user:[0,7,4],restrict:6,hook:3,unlik:9,alreadi:[5,2,6,7,4],hood:[6,7],seekabl:[],tox:4,top:[],sometim:[8,2,6,7],mercuri:[0,4],too:[6,7],skipfirst:[],with_arg:1,namespac:[0,2,7,5],tool:0,setuptool:[0,4],"0alpha3":[],"0alpha2":[],"0alpha1":[],technic:4,silli:7,target:[5,4],keyword:[2,3,4,5,6,7,9],provid:[0,1,2,4,6,7,8,9],zero:4,file_spec:[],project:[0,1,5],matter:[0,2,6,7],some_method__return:1,iron:0,add_head:6,modern:[],raw:[],"__main__":[6,7,9,5],seen:[],seem:[],seek:[],"__new__":3,especi:4,adaptor:7,"__getstate__":3,"_new_nam":[],though:[2,6,7,4],object:[0,1,2,3,4,5,6,7,8,9],what:[0,2,4,6,7,9],monkeypatch:[],bsd:0,konstantin:4,don:[0,1,2,3,4,5,6,7,9],doc:[0,4],doe:[1,4,5,6,7,9],dot:[2,9],asid:7,opposit:4,"__str__":[0,3],syntax:0,somethingfortest:6,identifi:7,involv:7,despit:[],layout:4,explain:6,configur:[0,1,2,3,4,5,6,7,9],theme:4,"__call__":[0,6,7,4],plate:[],stop:[0,5,7,4],assertrais:1,report:4,reconstruct:[],softli:[],bar:[6,7,9,5],baz:[6,7,9],method:[0,1,2,3,4,5,6,7,8,9],twice:[1,4],respond:6,assert_called_with:[0,1,2,3,4,5,6,7,9],result:[1,2,3,4,6,7,8,9],respons:7,fail:[0,2,6,5,4],themselv:[2,9],best:6,hopefulli:[],discoveri:4,outstand:4,simplest:9,approach:7,attribut:[0,1,2,4,5,6,7,8,9],extend:1,weak:4,autodiscoveri:4,posit:6,lazi:4,returns_fak:1,debt:4,"__unicode__":3,protect:6,expos:[],"_noncallablemock__get_side_effect":6,howev:[0,5,6,7,4],against:[5,6,7,4],py3k:4,com:0,callarg:4,foobar:7,exception_rais:1,assum:[1,7],three:[2,4,5,6,7,9],been:[0,2,3,4,5,6,7,9],much:[0,6,7],interest:[6,7,3],basic:[1,7,3,5],mocksignatur:4,"__len__":3,xxx:[],uncommon:[],ani:[0,1,2,3,4,5,6,7,9],prop_mock:[],child:[5,2,7,9,4],"catch":[],ugli:[],ident:[8,7,3],properti:[0,4,5,6,7,9],weren:[],build_sphinx:4,suffici:7,"__ge__":3,seven:7,kwarg:[5,6,7,9,4],conf:5,tediou:6,somemodul:1,file_handl:2,incorrectli:[0,6],perform:[0,5,6,4],suggest:[0,4],make:[0,1,2,4,5,6,7,9],"0beta3":[],complex:[0,2,6,7,9],split:4,nosetest:[],idyl:0,hand:[6,3],rais:[0,1,2,3,4,5,6,7,9],boiler:[],second_cal:7,kept:3,scenario:[6,7,5],fiddlier:[7,5],thing2:9,thing1:9,inherit:4,contact:0,thi:[0,1,2,3,4,5,6,7,8,9],programm:7,everyth:6,left:7,protocol:[7,3,4],just:[0,2,6,7,4],kall:6,mock_fish:[],"__dict__":[],testwith:[],yet:[1,6],languag:0,previous:[7,4],easi:[0,2,7,9],interfer:[],had:[5,4],els:[9,3],"0beta4":[],"0beta2":[],mayb:7,preserv:4,mocker:1,measur:[],specif:[0,1,2,3,4,6,7,8,9],arbitrari:[2,4,5,6,7,9],manual:[6,3,4],noth:1,"__long__":3,unnecessari:[7,4],underli:[7,4],right:[5,2,7,3,4],old:[6,4],deal:7,stopiter:9,intern:4,test_method:[],txt:4,implement:[0,2,3,4,6,7],bottom:[0,2,5],subclass:[0,3,4,6,7,9],buffer:[],tracker:[0,1,4],unit:[0,6,7,4],foo:[0,1,2,3,5,6,7,9],core:0,plu:[0,2,9,5,4],sensibl:[8,2],idiomat:1,someclass:[1,2,7,9,5],repositori:0,post:0,"super":7,normal_argu:5,unsaf:4,obj:[],slightli:7,unfortun:7,"__mul__":3,some_object:[8,1,5],curiou:[],encod:[],bound:[7,5],"__and__":3,opportun:7,wai:[0,1,2,3,4,5,6,7,8,9],support:[0,1,3,4,5,6,9],herman:1,avail:[0,1,4,5,6,7],reli:7,mymock:7,creation:[6,4],form:[5,2,7,9,4],forc:9,"true":[0,1,2,3,4,5,6,7,9],something_els:[],reset:[9,4],flavour:7,attr:[6,9],bugfix:4,until:9,testutil:[],featur:[6,4],classic:[0,7],stronger:2,diagnost:6,exist:[0,2,3,4,5,6,7,9],check:[0,2,4,5,6,7,9],"__reduce_ex__":3,when:[0,2,4,5,6,7,8,9],refactor:[2,6,7,4],"8rc2":4,role:0,test:[0,1,2,4,5,6,7,8,9],intend:9,stringio:[1,5],assret_called_with:6,urllib2:6,consid:5,in_dict:5,receiv:4,faster:6,ignor:[6,9,4],time:[0,1,2,4,5,6,7,9],preconfigur:3,my_dict:7,concept:7,"__ne__":[3,4],chain:[0,1,2,4,6,7],skip:[0,4],global:[2,7],"__rshift__":3,depend:[2,6,7],readabl:[8,7],certainli:[],isinst:[5,7,9,4],child1:9,child2:9,sourc:[0,7,4],"__exit__":[1,6,3],string:[5,2,6,9,4],addcleanup:[7,5],"__bool__":3,exact:7,w00t:9,level:[0,6,4],did:4,iter:[2,3,4,5,7,9],assertequ:[1,2],item:[9,5],setitem:7,unsupport:[9,4],quick:[0,2],round:[6,4],dir:[6,9,4],inpy3k:[],prevent:[0,2,4,6,7,9],peek:[],cost:7,run:[0,5,7,4],lazili:[6,4],"_checkwrit":[],abstractbasicauthhandl:6,"_mock_children":[],current:[0,6],suspect:[],del:[9,5],fifti:7,honour:5,gener:[0,6,7],"__hex__":3,along:[0,6,9,4],mock_backend:7,has_attr:1,behav:7,extrem:6,weird:[],someobject:1,semant:[],love:0,"__getslice__":3,extra:[5,9,4],tweak:7,modul:[0,2,4,5,6,7,9],prefer:[0,7],fake:[0,1],marker:4,instal:0,ignorearg:1,method_cal:[1,3,4,6,7,9],baseexcept:4,todai:7,subvers:4,scope:[0,2,5],checkout:0,remember_ord:1,python:[0,1,2,3,4,5,6,7],peopl:[],asserttru:[2,7],prototyp:[],examin:0,easiest:[0,6],pretend:9,uniqu:[8,0,4],descriptor:[0,3,4,5,6,7,9],whatev:[2,7,9],purpos:6,boilerpl:5,spy:0,topic:[],konrad:4,mock3:1,mock2:[1,5],"__sizeof__":[3,4],occur:[],alwai:[8,9,4],multipl:[0,1,2,4,5,6,7],modulenam:[],write:[6,7,5],classname2:[0,2,5],map:5,product:[0,6,5],grob:7,clone:0,"__next__":3,membership:[5,4],mai:[1,4,5,6,7,9],underscor:[6,9],data:1,grow:[],toowtdi:4,"_chunk_siz":[],explicit:[1,6,9,4],inform:5,"switch":[5,6,9,4],cannot:[],combin:[],block:[9,5],callabl:[0,3,4,5,6,7,9],still:[3,4,5,6,7,9],dynam:[2,3,4,6,7,9],thank:4,match_foo:7,mail:0,main:[],non:[9,6,7,3,4],matcher:7,initi:4,now:[0,2,7,5,4],"_checkclos":[],discuss:[0,7],nor:4,introduct:7,term:0,name:[1,2,4,5,6,7,8,9],didn:7,separ:7,getitem:7,attributeerror:[0,2,3,4,6,9],replai:[0,1],arg1:1,individu:[6,9,5],continu:2,wrap:[5,7,9,4],year:[],happen:[6,7,9],shown:[1,2,6],accomplish:1,correct:[1,2,6,7],some_mock:[6,9],"_checkread":[],runtimeerror:[],orm:0,org:[0,4],unpredict:4,care:[6,7],couldn:7,"_get_child_mock":[7,9],class_method:5,refus:[],thing:[0,1,5,6,7,9],place:[5,6,7,3,4],principl:5,think:[7,5],first:[0,1,2,3,4,5,6,7,9],origin:[0,1,2,4,5,6,7],directli:[2,6,7,9,5],onc:[1,2,3,6,7,9],yourself:[6,7,3],open:[0,1,2,4,6,7],given:[0,6,9],"__subclasses__":3,silent:6,workaround:7,teardown:[7,5],caught:6,necessarili:[6,5],conveni:[8,2,9,4],friend:7,spec_set:[2,3,4,5,6,7,9],cope:[0,7],copi:[0,2,7,4],specifi:[0,2,9,5,4],than:[1,2,3,4,5,6,7,9],wide:0,setattr:[],autospec:[0,5,6,7,4],were:[0,1,2,7],bauer:4,nuisanc:7,seri:[7,9],pre:[8,0,9,4],nicer:[7,4],argument:[0,1,2,3,4,5,6,7,8,9],exclud:[9,4],kevin:4,"__builtin__":[1,2],techniqu:[0,7,5],alias:[],note:[0,1,2,3,4,5,6,7,9],take:[0,1,2,3,4,5,6,7,9],new_mock:[7,5],wonder:[],unittest2:[0,2,7,5,4],sure:[],importantli:2,normal:[0,2,3,5,6,7,8,9],track:[0,2,7,9],beta:[0,4],wire:6,abus:4,pair:5,homepag:0,renam:[6,4],later:[2,6,7],runtim:5,stopal:[5,4],uncondit:7,show:[6,7],"_new_par":[],slot:4,onli:[1,2,3,4,5,6,7,9],explicitli:9,activ:[5,7,4],written:[1,7],dict:[0,2,4,5,7,9],variou:[1,7,4],get:[0,1,2,4,5,6,7,9],repr:[2,4,5,7,8,9],soon:[],newkei:[0,2,5],attach_mock:[6,7,9,4],should_rec:1,requir:[0,6,3,4],fileno:[],yield:[1,7],email:[],irrespect:[6,4],mocksomeclass:7,where:[0,2,4,5,7,9],"__module__":4,dangoor:4,testcas:[2,7,5],concern:7,infinit:4,detect:4,getattr:[],between:[6,7,9],"import":[0,1,2,4,5,6,7,9],across:6,parent:[7,9,4],cycl:4,mock_add_spec:[9,4],come:0,quack:0,copyabl:4,inconsist:3,mani:[0,3,4,5,6,7,9],unittest:[0,5,4],pop:7,anti:7,sentinel:[8,0,2,9,4],typic:[5,4],"0a2":[],"0a3":[],coupl:[2,5],mock_someth:[],valueerror:[7,9],fake_open:1,ironpython:4,"__eq__":[7,3,4],those:[2,7,9,4],"case":[2,3,4,5,6,7,9],"__mod__":3,trick:7,ran_emo:[],advantag:[],stdout:5,side_effect:[0,1,2,3,4,5,7,8,9],"__getformat__":[3,4],"__init__":[0,3,4,5,6,7],develop:0,author:0,same:[0,1,2,3,4,5,6,7,8,9],binari:4,html:[],document:[0,4],exhaust:9,nest:[0,2,4,5,6,7],companion:[],capabl:[0,2],improv:[0,4],extern:[],"_spec_stat":[],appropri:0,without:[0,2,3,4,5,6,7,9],model:0,"__getinitargs__":3,"__int__":[9,3],execut:[5,1,2,6,4],aspect:[],is_cal:1,testmethod:[],any_ord:[7,9],except:[0,1,2,3,4,5,7,9],littl:7,blog:[0,7],blob:7,real:[0,1,2,4,5,6,7,8,9],mox:1,around:4,read:[0,1,2,6],read_data:6,some_funct:[2,5],integ:9,benefit:[],either:[6,9,3,5],output:0,manag:[0,1,2,3,4,5,6,7],assertionerror:[1,6,7,9],definit:0,exit:[7,5],inject:0,overli:[],refer:[0,2,7,5,4],power:[0,6,7,5],garbag:4,inspect:[],broken:[2,6,4],fulli:1,"__name__":[],"throw":1,comparison:[0,1,3,4,6,7],"__setslice__":3,call_args_list:[1,6,7,9,4],act:[0,9,5],gari:1,terminolog:0,call_arg:[6,7,9,4],patcher1:5,patcher2:5,your:[0,2,4,5,6,7,8,9],aren:[9,5,7,3,4],hex:3,start:[0,2,4,5,6,7],lot:6,replayal:1,"__invert__":3,enough:6,tupl:[5,6,9,4],mock_frob:7,"__get__":[9,3],verifyal:1,notat:9,copy_call_arg:7,mockmethod:[],abstractdigestauthhandl:6,possibl:[5,7,4],"default":[2,3,4,5,6,7,8,9],unusu:[],expect:[1,2,6,7,9],gone:6,creat:[0,1,2,3,4,5,6,7,8,9],certain:[6,4],strongli:[],"__floor__":[3,4],file:[2,6,7,4],incorrect:2,again:[5,7,4],googl:0,readinto:[],compel:[],pmock:1,valid:[5,6,7,4],writabl:[],you:[0,1,2,3,4,5,6,7,8,9],isint:9,sequenc:[6,7,9],minimock:1,docstr:4,testload:5,reduc:[5,4],tricki:[7,4],mimic:7,nelson:[],potenti:4,unset:4,represent:4,all:[0,1,2,3,4,5,6,7,9],test_closer_closes_someth:[],month:[],abil:4,follow:[0,5,7,3,4],children:[2,7,9,4],"__cmp__":3,hasattr:9,foo_on:5,patch_modul:4,introduc:[],consum:3,bibbl:6,open_nam:[],straightforward:[0,2,7,5],fals:[3,4,5,6,7,9],pop_last_cal:[],xunitpattern:[],candid:[0,4],fan:0,failur:[8,2,7,4],veri:[0,6,7,9,5],reset_mock:[9,4],list:[0,2,3,4,5,6,7,9],productionclass:[8,0,2],sane:[],"__missing__":3,mockanyth:1,"__truediv__":[3,4],design:[0,6],pass:[0,1,2,4,5,6,7,8,9],further:[0,2,7],cursor:2,deleg:7,sub:[7,4],section:[7,5],"_noncallablemock__set_side_effect":6,abl:[6,9,5],delet:[0,5,7,9,4],version:[0,1,3,4,5,6,7,9],deepli:6,some_method:[1,2],"public":4,hasn:[2,9],full:[9,7,3,4],hash:3,misspel:6,behaviour:[0,6,7,9,4],shouldn:[],modifi:[0,2,6,4],valu:[0,1,2,3,4,5,6,7,8,9],test_two:7,not_a_test:7,"_noncallablemock__return_value_doc":6,"__xor__":3,doctest:1,action:0,via:[6,4],packagenam:[],intermedi:[1,6,4],ask:[],"__setformat__":[3,4],thankfulli:6,decrement:[],select:2,aggress:6,etc:[1,4],two:[2,3,4,5,6,7,9],coverag:0,almost:3,minor:4,more:[0,1,2,4,5,6,7,9],flaw:6,"__coerce__":3,particular:[1,6,7,9],known:7,cach:[],none:[0,1,2,3,4,5,6,7,9],copyingmock:7,caveat:6,def:[0,1,2,3,5,6,7,9],frustratingli:0,share:[5,6,4],templat:[0,4],minimum:5,cours:[2,6,7],xxxx:[],newlin:[],rather:[1,2,3,4,5,6,7,9],anoth:[0,2,4,5,6,7,8,9],assert_called_once_with:[0,1,2,4,5,6,7,9],simpl:[0,1,2,7],variant:[0,7,3,9],confus:[0,9],django:[0,5,4],caus:[5,2,7,3,4],callback:4,mortem:0,"__le__":3,egg:[6,7,9],help:[5,2,6,4],mockiti:[0,9],through:[0,6,7,9,4],suffer:6,annoyingli:0,paramet:[0,9,3],style:4,mockstat:[],times_cal:1,bypass:6,stephen:4,might:[2,6,7,5],wouldn:[6,4],good:[1,7],"return":[0,1,2,3,4,5,6,7,8,9],framework:[0,1],detach:[],complain:[],achiev:[7,9],found:[0,7],unicod:[0,3],mock_respons:7,truncat:4,obj_typ:[],michael:[0,4],fish:[9,7,3,5],hard:[2,6,7],realli:[],some_modul:1,connect:2,horribl:4,todo:[0,1,4],some_valu:1,mock_foo:[7,9],print:[5,9,4],proxi:[0,5,4],advanc:[2,7],reason:[6,7,9],base:[0,6,7,9,4],put:[7,5],new_inst:1,omit:[1,5],perhap:0,assign:[0,1,9,4],singleton:9,obviou:7,feel:7,number:[1,9],done:[0,4,5,6,7,9],construct:[2,6,7,9,5],stabl:0,miss:[1,3],"__float__":3,differ:[0,1,2,3,4,5,6,7],script:0,interact:[],least:[1,6,5],fladisch:4,"__dir__":[9,3],statement:[0,2,3,4,5,7],store:[0,7,9],option:[2,6,7,9,4],propertymock:[7,9,4],part:[0,2,7,4],aaa:0,whenev:9,remov:[0,9,4],my_dingu:1,reus:[9,4],str:[0,3,4],arrang:0,toward:[],well:[0,2,4,5,6,7,9],packag:[5,2,7,4],use_mock_anyth:1,imagin:[7,5],built:[7,4],florian:4,self:[1,2,3,4,5,6,7,9],violat:4,also:[0,1,2,3,4,5,6,7,9],useless:6,distribut:[0,7,4],previou:[],most:[0,1,2,3,5,6,7,9],alpha:[0,4],promulg:0,appear:[2,9,3,5],clear:[0,2,4,5,7,9],and_return:1,newvalu:[0,2,5],usual:[7,3],visibl:6,favour:[],particularli:6,and_rais:1,mock_open:[0,6,7,4],find:[0,7,5],has_data:6,indexerror:9,solut:7,factor:[],hit:6,unus:4,express:7,mock_method:[0,2,5],foobarbaz:0,"_ani":[],common:[8,5,2,6,4],manger:5,set:[0,2,3,4,5,6,7,9],get_endpoint:7,mutabl:[0,7],see:[0,2,5,6,7,9],arg:[0,1,2,3,4,5,6,7,9],close:[2,6],inconveni:7,wow:9,won:4,has_been_cal:7,altern:[0,2,5,6,7,9],signatur:[0,5,6,7,4],syntact:5,numer:[3,4],isol:[6,7,3,4],"__divmod__":3,solv:[6,7],nervou:[],classnam:[2,5],both:[5,6,7,4],last:[0,1,2,4,5,6,7,9],"__trunc__":[3,4],someexcept:1,context:[0,1,2,3,4,5,6,7],pdf:0,whole:[],onward:0,simpli:[6,7,5],point:[7,5],instanti:[5,2,6,7,4],suppli:4,throughout:[0,9],batcheld:4,pycon:0,backend:7,sever:[2,7,9,4],java:4,due:6,empti:[6,9,3,4],sinc:[5,4],andrais:1,remark:7,understand:7,func:[],"_old_nam":[],unpatch:[5,4],look:[0,2,7,3,5],keywarg:[],unifi:[],match:[0,7,5],abov:[0,2],error:[2,6,7,4],"__hash__":3,sheremetyev:1,expected_cal:7,readi:9,flexmock:1,itself:[0,6,7,4],decor:[0,2,4,5,7,9],mockclass:[1,5],minim:[],shorter:7,lenient:[],conflict:[],"__repr__":3,wherea:6,read1:[],temporari:1,"__or__":3,"__add__":3,stack:[2,5],recent:[0,1,2,4,5,6,7,9],travers:[6,4],task:1,older:0,entri:[0,1,6,7,4],pickl:[3,4],raise_except:[],"__neg__":3,elev:[],"_wrap":4,tast:7,match_equ:7,obscur:3,stabilis:[],"_parent":4,input:9,subsequ:[7,3],hamcrest:7,big:6,inequ:4,"__gt__":3,bit:[7,4],"_method":4,resolv:6,collect:4,"boolean":[9,4],popular:1,stylish:4,often:[2,9],"1st":[],some:[0,1,2,3,4,5,6,7,9],back:7,sizeof:3,retri:7,undon:[2,7,5],recognis:[5,4],nose:4,method2:1,method3:1,method1:1,martin:0,step:7,impos:0,patched_context:1,doubl:[0,6,9],within:[0,5],ensur:[0,1,6,7,5],spam:[6,7],question:[],"long":3,custom:[9,4],includ:[0,1,2,3,4,6,7,9],suit:0,assert_has_cal:[6,7,9,4],properli:6,fishi:0,line:[6,7,4],info:4,test_modul:2,file_:1,readlin:[],similar:7,match_wrong:7,doesn:[1,4,5,6,7,9],repres:[1,2,6,9],wheeeeee:0,deletingmock:[],titl:[],sequenti:9,"__format__":3,test_prefix:[0,5,4],invalid:[0,4],mock:[0,1,2,3,4,5,6,7,8,9],nice:[2,7],test_funct:5,meaning:4,eval:[],mymodul:[7,5],dingus:1,algorithm:7,berman:4,far:1,hello:9,code:[0,2,4,5,6,7,9],partial:[0,1,7],privat:[6,4],old_method:2,this_foo:9,mock_stdout:5,func2:[],whichev:7,dandi:6,implicitli:9,relev:0,recip:[0,7],magic:[0,1,3,4,5,7,9],"__prepare__":3,mocksetexpect:[],"try":[6,7],"_mock":4,pleas:[0,1,3],"_checkseek":[],natur:[0,1],"0x1":3,video:0,mock_spam:7,download:0,"__ceil__":[3,4],compat:4,compar:[2,6,7,9,4],fine:[0,6,4],access:[0,2,4,5,6,7,8,9],experiment:[],can:[0,1,2,3,4,5,6,7,8,9],len:[1,3],bodi:[7,5],let:[6,7,3,5],becom:[6,7,9],implicit:[7,4],great:6,convers:3,"_name":4,staticmethod:6,opinion:[],chang:[2,3,4,5,6,7,9],"__enter__":[1,6,3],danger:5,appli:[0,2,3,4,5,6,7],app:5,disciplin:0,mockfoo:6,api:[0,4,5,6,7,9],duck:0,from:[0,1,2,3,4,5,6,7,9],commun:0,assret_called_once_with:6,frob:7,next:[2,9,4],few:6,sort:[],bernhardt:1,trail:9,actual:[8,5,2,7,4],annoi:6,obvious:6,create_patch:7,fetch:[5,6,7,9,4],control:[0,6,7,4],deepcopi:7,tag:0,mock1:[1,5],delai:7,foo_two:5,six:[],"__pos__":3,instead:[0,2,4,5,6,7,9],class2:[7,5],circular:[7,4],exemplifi:1,seriou:6,correspond:[6,9,5],element:[],issu:[0,1,6,7,4],allow:[0,2,3,4,5,6,7,9],move:[7,4],whilst:7,mock_class:5,bunch:[],classname1:[0,2,5],static_method:[2,5],"__getitem__":[7,3,5],handl:[0,2,3,4,5,6,7,9],auto:[0,6,7,4],handi:6,configure_mock:[7,9,4],"__pow__":3,front:[1,7],"__delitem__":[3,5],anyth:[3,5],mytest:[2,7,5],mode:[],fiddli:6,reserv:[],class1:[7,5],upward:5,second_patch:5,"static":[0,5,7,4],our:[2,6,7,5],meth:[],patch:[0,1,2,4,5,6,7,8,9],special:[1,3,4],out:[2,4,5,6,7,9],variabl:[1,6],req:6,stub:[0,9],rel:6,new_cal:[5,9,4],ref:[],clarifi:5,insid:[7,9,5],manipul:[],undo:5,dictionari:[0,2,4,5,6,7,9],releas:[0,1,4],likelihood:4,afterward:[2,5],indent:[7,5],could:[5,7,4],keep:5,keen:[],length:9,"__delete__":3,date:[0,1,7],my_fak:1,owner:[],licens:[0,4],perfectli:7,system:[0,2,6,7,5],messag:[8,1,2,7,4],attach:[0,7,9,4],monkei:[8,7,4],"final":[6,7],"__del__":3,getattr_stat:6,mmckclass:[],exactli:[0,6,7,9],haven:[6,4],cpython:4,structur:5,rybnikov:4,sens:[],stricter:9,"__rtruediv__":[3,4],julian:4,deprec:4,liner:[],blip:7,have:[0,1,2,3,4,5,6,7,8,9],disadvantag:[],need:[0,1,2,3,4,5,6,7,8,9],unexpect:2,"__unittest":4,mix:[],builtin:[0,1,2,7,4],patch_object:4,which:[0,1,3,4,5,6,7,9],singl:[5,2,6,7,4],unless:[9,3,4],writelin:[],clash:4,sekret:1,who:[],discov:0,why:[6,7],magicmock:[0,1,2,3,4,5,6,7,9],hardcod:4,some_other_object:1,basehandl:6,determin:4,fowler:0,someth:[2,3,5,6,7,9],fact:7,"_calllist":[],verbos:[0,7],bring:6,mockcheckcal:[],longer:[5,2,7,4],trivial:2,anywai:[0,4],setter:9,mock_bar:7,should:[8,5,3,4],suppos:[2,7],start_cal:7,local:7,contribut:[1,4],"0b4":[],pypi:[0,4],notimpl:[3,4],stuff:[0,6],integr:[6,7,4],contain:[6,7,3,5],noodl:[],temporarili:[7,9,5],mock_th:5,closer:2,test_on:7,correctli:[5,2,6,4],pattern:[0,2,7,5],mock_dat:7,state:[0,2,5],"__bases__":4,expectexcept:[],stuboutwithmock:1,kei:[0,2,7,9,5],dislik:6,job:[],addit:[5,1,2,6,4],indvidu:2,extens:[0,4],equal:[6,7,3,4],"__delattr__":[],instanc:[0,1,2,3,4,5,6,7,9],comment:4,"__complex__":3,unorder:4,quit:[],addition:0,"__set__":[9,3],some_attribut:[1,9],treat:[],foobl:[7,3],"0rc2":[],"0rc1":[],immedi:2,create_cal:7,assert:[0,1,2,3,4,5,6,7,8,9],togeth:[6,7],fake_fil:1,present:[0,4],determinist:4,harder:[1,7],unsuit:4,defin:[7,5],intro:[],"__floordiv__":3,"__sub__":3,helper:[0,6,7,4],fakeclass:1,"__reduce__":3,mock_urllib2:6,mutat:7,welcom:4,backendprovid:7,member:[0,5,6,9,4],mock_exit:5,andreturn:1,call_count:[1,7,9,4],"_noncallablemock__get_return_valu":6,http:0,interrog:7,effect:[0,2,3,4,5,7,9],dai:[],build:7,at_least:1,expand:5,pull:6,off:[6,9,5],keyboardinterrupt:4,pyhamcrest:7,sett:5,"__div__":3,exampl:[0,1,2,3,5,6,7,8,9],command:[0,4],choos:5,unit2:0,latest:0,unari:3,less:[0,7,4],first_patch:5,"__lt__":3,simultan:[],mock_funct:0,add:[6,7,9,5],cleanup:[7,5],bool:4,logger:0,smart:0,futur:6,rationalis:4,jython:[0,4],assert_any_cal:[6,9,4],know:[6,3,4],password:1,recurs:[6,4],python3:0,"__reversed__":3,like:[0,1,2,4,5,6,7,8,9],unord:4,lose:[],soft:4,page:[1,2],revers:[],pariti:4,flush:[],home:0,"__getnewargs__":3,librari:[0,1,5,7,4],"__setattr__":3,guid:[0,2,7],lead:9,"__contains__":[3,5],avoid:7,"__getattr__":3,leav:4,grrr:5,some_obj:7,usag:[0,6],host:[0,4],although:[],after:[0,2,5,6,7,9],simpler:[0,6,7,5],about:[0,1,2,3,6,7,9],"_noncallablemock__set_return_valu":6,rare:7,fudg:1,constructor:[0,2,3,4,6,7,9],own:[0,7,4],easy_instal:0,automat:[1,5,7,9,4],destructor:4,pointless:4,merg:4,val:[2,7],mcmillan:1,intention:1,trigger:[6,4],return_valu:[0,1,2,3,4,5,6,7,8,9],replac:[0,1,2,3,4,5,6,7,9],"var":[6,4],arg2:[1,6],"function":[0,2,3,4,5,6,7,8,9],mockclass1:[0,2,7,5],mockclass2:[0,2,7,5],filter_dir:[0,6,9,4],keyerror:[0,7,9,5],gain:[3,4],sphinx:4,bug:[0,6,4],count:4,succe:[6,7],made:[0,1,2,4,7,9],wise:9,whether:[9,4],googlecod:0,rc1:4,record:[0,2,3,4,7,9],below:[2,6],limit:[0,6,9,4],otherwis:7,problem:[2,6,7,3,5],evalu:4,"int":[6,9,3],dure:[0,2,7,4],filenam:[1,2],twist:7,contextlib:[1,5],pip:0,probabl:[1,6,4],detail:[0,9],other:[0,1,2,3,4,5,6,7,9],lookup:[6,4],boom:[2,7,9],mocksometh:[],repeat:9,"class":[0,1,2,3,4,5,6,7,9],function2:[],my_mock:[1,6],rule:[7,3],klass:1,"__index__":3},objtypes:{"0":"py:module","1":"py:data","2":"py:function","3":"py:class","4":"py:attribute","5":"py:method"},titles:["Mock - Mocking and Testing Library","Mock Library Comparison","Getting Started with Mock","Mocking Magic Methods","CHANGELOG","Patch Decorators","Helpers","Further Examples","Sentinel","The Mock Class"],objnames:{"0":["py","module","Python module"],"1":["py","data","Python data"],"2":["py","function","Python function"],"3":["py","class","Python class"],"4":["py","attribute","Python attribute"],"5":["py","method","Python method"]},filenames:["index","compare","getting-started","magicmock","changelog","patch","helpers","examples","sentinel","mock"]}) \ No newline at end of file diff --git a/python/mock-1.0.0/html/sentinel.html b/python/mock-1.0.0/html/sentinel.html new file mode 100644 index 000000000..5b28deb2c --- /dev/null +++ b/python/mock-1.0.0/html/sentinel.html @@ -0,0 +1,156 @@ + + + + + + + + + Sentinel — Mock 1.0.0 documentation + + + + + + + + + + + + + +
    +

    Navigation

    + +
    + +
    +
    +
    +
    + +
    +

    Sentinel¶

    +
    +
    +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.

    +
    + +
    +
    +DEFAULT¶
    +

    The DEFAULT object is a pre-created sentinel (actually +sentinel.DEFAULT). It can be used by side_effect +functions to indicate that the normal return value should be used.

    +
    + +
    +

    Sentinel Example¶

    +

    Sometimes when testing you need to test that a specific object is passed as an +argument to another method, or returned. It can be common to create named +sentinel objects to test this. sentinel provides a convenient way of +creating and testing the identity of objects like this.

    +

    In this example we monkey patch method to return +sentinel.some_object:

    +
    >>> 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
+
    +
    +
    +
    + + +
    +
    +
    +
    +
    +

    Table Of Contents

    + + +

    Previous topic

    +

    Helpers

    +

    Next topic

    +

    Mocking Magic Methods

    +

    This Page

    + + + +
    +
    +
    +
    +
    +

    Navigation

    + +
    +
    + © Copyright 2007-2012, Michael Foord & the mock team. + Last updated on Oct 07, 2012. + Created using Sphinx 1.1.3. +
    + + \ No newline at end of file diff --git a/python/mock-1.0.0/mock.py b/python/mock-1.0.0/mock.py new file mode 100644 index 000000000..1be4e6e45 --- /dev/null +++ b/python/mock-1.0.0/mock.py @@ -0,0 +1,2356 @@ +# mock.py +# Test tools for mocking and patching. +# Copyright (C) 2007-2012 Michael Foord & the mock team +# E-mail: fuzzyman AT voidspace DOT org DOT uk + +# mock 1.0 +# http://www.voidspace.org.uk/python/mock/ + +# Released subject to the BSD License +# Please see http://www.voidspace.org.uk/python/license.shtml + +# Scripts maintained at http://www.voidspace.org.uk/python/index.shtml +# Comments, suggestions and bug reports welcome. + + +__all__ = ( + 'Mock', + 'MagicMock', + 'patch', + 'sentinel', + 'DEFAULT', + 'ANY', + 'call', + 'create_autospec', + 'FILTER_DIR', + 'NonCallableMock', + 'NonCallableMagicMock', + 'mock_open', + 'PropertyMock', +) + + +__version__ = '1.0.0' + + +import pprint +import sys + +try: + import inspect +except ImportError: + # for alternative platforms that + # may not have inspect + inspect = None + +try: + from functools import wraps +except ImportError: + # Python 2.4 compatibility + def wraps(original): + def inner(f): + f.__name__ = original.__name__ + f.__doc__ = original.__doc__ + f.__module__ = original.__module__ + return f + return inner + +try: + unicode +except NameError: + # Python 3 + basestring = unicode = str + +try: + long +except NameError: + # Python 3 + long = int + +try: + BaseException +except NameError: + # Python 2.4 compatibility + BaseException = Exception + +try: + next +except NameError: + def next(obj): + return obj.next() + + +BaseExceptions = (BaseException,) +if 'java' in sys.platform: + # jython + import java + BaseExceptions = (BaseException, java.lang.Throwable) + +try: + _isidentifier = str.isidentifier +except AttributeError: + # Python 2.X + import keyword + import re + regex = re.compile(r'^[a-z_][a-z0-9_]*$', re.I) + def _isidentifier(string): + if string in keyword.kwlist: + return False + return regex.match(string) + + +inPy3k = sys.version_info[0] == 3 + +# Needed to work around Python 3 bug where use of "super" interferes with +# defining __class__ as a descriptor +_super = super + +self = 'im_self' +builtin = '__builtin__' +if inPy3k: + self = '__self__' + builtin = 'builtins' + +FILTER_DIR = True + + +def _is_instance_mock(obj): + # can't use isinstance on Mock objects because they override __class__ + # The base class for all mocks is NonCallableMock + return issubclass(type(obj), NonCallableMock) + + +def _is_exception(obj): + return ( + isinstance(obj, BaseExceptions) or + isinstance(obj, ClassTypes) and issubclass(obj, BaseExceptions) + ) + + +class _slotted(object): + __slots__ = ['a'] + + +DescriptorTypes = ( + type(_slotted.a), + property, +) + + +def _getsignature(func, skipfirst, instance=False): + if inspect is None: + raise ImportError('inspect module not available') + + if isinstance(func, ClassTypes) and not instance: + try: + func = func.__init__ + except AttributeError: + return + skipfirst = True + elif not isinstance(func, FunctionTypes): + # for classes where instance is True we end up here too + try: + func = func.__call__ + except AttributeError: + return + + if inPy3k: + try: + argspec = inspect.getfullargspec(func) + except TypeError: + # C function / method, possibly inherited object().__init__ + return + regargs, varargs, varkw, defaults, kwonly, kwonlydef, ann = argspec + else: + try: + regargs, varargs, varkwargs, defaults = inspect.getargspec(func) + except TypeError: + # C function / method, possibly inherited object().__init__ + return + + # instance methods and classmethods need to lose the self argument + if getattr(func, self, None) is not None: + regargs = regargs[1:] + if skipfirst: + # this condition and the above one are never both True - why? + regargs = regargs[1:] + + if inPy3k: + signature = inspect.formatargspec( + regargs, varargs, varkw, defaults, + kwonly, kwonlydef, ann, formatvalue=lambda value: "") + else: + signature = inspect.formatargspec( + regargs, varargs, varkwargs, defaults, + formatvalue=lambda value: "") + return signature[1:-1], func + + +def _check_signature(func, mock, skipfirst, instance=False): + if not _callable(func): + return + + result = _getsignature(func, skipfirst, instance) + if result is None: + return + signature, func = result + + # can't use self because "self" is common as an argument name + # unfortunately even not in the first place + src = "lambda _mock_self, %s: None" % signature + checksig = eval(src, {}) + _copy_func_details(func, checksig) + type(mock)._mock_check_sig = checksig + + +def _copy_func_details(func, funcopy): + funcopy.__name__ = func.__name__ + funcopy.__doc__ = func.__doc__ + #funcopy.__dict__.update(func.__dict__) + funcopy.__module__ = func.__module__ + if not inPy3k: + funcopy.func_defaults = func.func_defaults + return + funcopy.__defaults__ = func.__defaults__ + funcopy.__kwdefaults__ = func.__kwdefaults__ + + +def _callable(obj): + if isinstance(obj, ClassTypes): + return True + if getattr(obj, '__call__', None) is not None: + return True + return False + + +def _is_list(obj): + # checks for list or tuples + # XXXX badly named! + return type(obj) in (list, tuple) + + +def _instance_callable(obj): + """Given an object, return True if the object is callable. + For classes, return True if instances would be callable.""" + if not isinstance(obj, ClassTypes): + # already an instance + return getattr(obj, '__call__', None) is not None + + klass = obj + # uses __bases__ instead of __mro__ so that we work with old style classes + if klass.__dict__.get('__call__') is not None: + return True + + for base in klass.__bases__: + if _instance_callable(base): + return True + return False + + +def _set_signature(mock, original, instance=False): + # creates a function with signature (*args, **kwargs) that delegates to a + # mock. It still does signature checking by calling a lambda with the same + # signature as the original. + if not _callable(original): + return + + skipfirst = isinstance(original, ClassTypes) + result = _getsignature(original, skipfirst, instance) + if result is None: + # was a C function (e.g. object().__init__ ) that can't be mocked + return + + signature, func = result + + src = "lambda %s: None" % signature + checksig = eval(src, {}) + _copy_func_details(func, checksig) + + name = original.__name__ + if not _isidentifier(name): + name = 'funcopy' + context = {'_checksig_': checksig, 'mock': mock} + src = """def %s(*args, **kwargs): + _checksig_(*args, **kwargs) + return mock(*args, **kwargs)""" % name + exec (src, context) + funcopy = context[name] + _setup_func(funcopy, mock) + return funcopy + + +def _setup_func(funcopy, mock): + funcopy.mock = mock + + # can't use isinstance with mocks + if not _is_instance_mock(mock): + return + + def assert_called_with(*args, **kwargs): + return mock.assert_called_with(*args, **kwargs) + def assert_called_once_with(*args, **kwargs): + return mock.assert_called_once_with(*args, **kwargs) + def assert_has_calls(*args, **kwargs): + return mock.assert_has_calls(*args, **kwargs) + def assert_any_call(*args, **kwargs): + return mock.assert_any_call(*args, **kwargs) + def reset_mock(): + funcopy.method_calls = _CallList() + funcopy.mock_calls = _CallList() + mock.reset_mock() + ret = funcopy.return_value + if _is_instance_mock(ret) and not ret is mock: + ret.reset_mock() + + funcopy.called = False + funcopy.call_count = 0 + funcopy.call_args = None + funcopy.call_args_list = _CallList() + funcopy.method_calls = _CallList() + funcopy.mock_calls = _CallList() + + funcopy.return_value = mock.return_value + funcopy.side_effect = mock.side_effect + funcopy._mock_children = mock._mock_children + + funcopy.assert_called_with = assert_called_with + funcopy.assert_called_once_with = assert_called_once_with + funcopy.assert_has_calls = assert_has_calls + funcopy.assert_any_call = assert_any_call + funcopy.reset_mock = reset_mock + + mock._mock_delegate = funcopy + + +def _is_magic(name): + return '__%s__' % name[2:-2] == name + + +class _SentinelObject(object): + "A unique, named, sentinel object." + def __init__(self, name): + self.name = name + + def __repr__(self): + return 'sentinel.%s' % self.name + + +class _Sentinel(object): + """Access attributes to return a named object, usable as a sentinel.""" + def __init__(self): + self._sentinels = {} + + def __getattr__(self, name): + if name == '__bases__': + # Without this help(mock) raises an exception + raise AttributeError + return self._sentinels.setdefault(name, _SentinelObject(name)) + + +sentinel = _Sentinel() + +DEFAULT = sentinel.DEFAULT +_missing = sentinel.MISSING +_deleted = sentinel.DELETED + + +class OldStyleClass: + pass +ClassType = type(OldStyleClass) + + +def _copy(value): + if type(value) in (dict, list, tuple, set): + return type(value)(value) + return value + + +ClassTypes = (type,) +if not inPy3k: + ClassTypes = (type, ClassType) + +_allowed_names = set( + [ + 'return_value', '_mock_return_value', 'side_effect', + '_mock_side_effect', '_mock_parent', '_mock_new_parent', + '_mock_name', '_mock_new_name' + ] +) + + +def _delegating_property(name): + _allowed_names.add(name) + _the_name = '_mock_' + name + def _get(self, name=name, _the_name=_the_name): + sig = self._mock_delegate + if sig is None: + return getattr(self, _the_name) + return getattr(sig, name) + def _set(self, value, name=name, _the_name=_the_name): + sig = self._mock_delegate + if sig is None: + self.__dict__[_the_name] = value + else: + setattr(sig, name, value) + + return property(_get, _set) + + + +class _CallList(list): + + def __contains__(self, value): + if not isinstance(value, list): + return list.__contains__(self, value) + len_value = len(value) + len_self = len(self) + if len_value > len_self: + return False + + for i in range(0, len_self - len_value + 1): + sub_list = self[i:i+len_value] + if sub_list == value: + return True + return False + + def __repr__(self): + return pprint.pformat(list(self)) + + +def _check_and_set_parent(parent, value, name, new_name): + if not _is_instance_mock(value): + return False + if ((value._mock_name or value._mock_new_name) or + (value._mock_parent is not None) or + (value._mock_new_parent is not None)): + return False + + _parent = parent + while _parent is not None: + # setting a mock (value) as a child or return value of itself + # should not modify the mock + if _parent is value: + return False + _parent = _parent._mock_new_parent + + if new_name: + value._mock_new_parent = parent + value._mock_new_name = new_name + if name: + value._mock_parent = parent + value._mock_name = name + return True + + + +class Base(object): + _mock_return_value = DEFAULT + _mock_side_effect = None + def __init__(self, *args, **kwargs): + pass + + + +class NonCallableMock(Base): + """A non-callable version of `Mock`""" + + def __new__(cls, *args, **kw): + # every instance has its own class + # so we can create magic methods on the + # class without stomping on other mocks + new = type(cls.__name__, (cls,), {'__doc__': cls.__doc__}) + instance = object.__new__(new) + return instance + + + def __init__( + self, spec=None, wraps=None, name=None, spec_set=None, + parent=None, _spec_state=None, _new_name='', _new_parent=None, + **kwargs + ): + if _new_parent is None: + _new_parent = parent + + __dict__ = self.__dict__ + __dict__['_mock_parent'] = parent + __dict__['_mock_name'] = name + __dict__['_mock_new_name'] = _new_name + __dict__['_mock_new_parent'] = _new_parent + + if spec_set is not None: + spec = spec_set + spec_set = True + + self._mock_add_spec(spec, spec_set) + + __dict__['_mock_children'] = {} + __dict__['_mock_wraps'] = wraps + __dict__['_mock_delegate'] = None + + __dict__['_mock_called'] = False + __dict__['_mock_call_args'] = None + __dict__['_mock_call_count'] = 0 + __dict__['_mock_call_args_list'] = _CallList() + __dict__['_mock_mock_calls'] = _CallList() + + __dict__['method_calls'] = _CallList() + + if kwargs: + self.configure_mock(**kwargs) + + _super(NonCallableMock, self).__init__( + spec, wraps, name, spec_set, parent, + _spec_state + ) + + + def attach_mock(self, mock, attribute): + """ + Attach a mock as an attribute of this one, replacing its name and + parent. Calls to the attached mock will be recorded in the + `method_calls` and `mock_calls` attributes of this one.""" + mock._mock_parent = None + mock._mock_new_parent = None + mock._mock_name = '' + mock._mock_new_name = None + + setattr(self, attribute, mock) + + + def mock_add_spec(self, spec, spec_set=False): + """Add a spec to a mock. `spec` can either be an object or a + list of strings. Only attributes on the `spec` can be fetched as + attributes from the mock. + + If `spec_set` is True then only attributes on the spec can be set.""" + self._mock_add_spec(spec, spec_set) + + + def _mock_add_spec(self, spec, spec_set): + _spec_class = None + + if spec is not None and not _is_list(spec): + if isinstance(spec, ClassTypes): + _spec_class = spec + else: + _spec_class = _get_class(spec) + + spec = dir(spec) + + __dict__ = self.__dict__ + __dict__['_spec_class'] = _spec_class + __dict__['_spec_set'] = spec_set + __dict__['_mock_methods'] = spec + + + def __get_return_value(self): + ret = self._mock_return_value + if self._mock_delegate is not None: + ret = self._mock_delegate.return_value + + if ret is DEFAULT: + ret = self._get_child_mock( + _new_parent=self, _new_name='()' + ) + self.return_value = ret + return ret + + + def __set_return_value(self, value): + if self._mock_delegate is not None: + self._mock_delegate.return_value = value + else: + self._mock_return_value = value + _check_and_set_parent(self, value, None, '()') + + __return_value_doc = "The value to be returned when the mock is called." + return_value = property(__get_return_value, __set_return_value, + __return_value_doc) + + + @property + def __class__(self): + if self._spec_class is None: + return type(self) + return self._spec_class + + called = _delegating_property('called') + call_count = _delegating_property('call_count') + call_args = _delegating_property('call_args') + call_args_list = _delegating_property('call_args_list') + mock_calls = _delegating_property('mock_calls') + + + def __get_side_effect(self): + sig = self._mock_delegate + if sig is None: + return self._mock_side_effect + return sig.side_effect + + def __set_side_effect(self, value): + value = _try_iter(value) + sig = self._mock_delegate + if sig is None: + self._mock_side_effect = value + else: + sig.side_effect = value + + side_effect = property(__get_side_effect, __set_side_effect) + + + def reset_mock(self): + "Restore the mock object to its initial state." + self.called = False + self.call_args = None + self.call_count = 0 + self.mock_calls = _CallList() + self.call_args_list = _CallList() + self.method_calls = _CallList() + + for child in self._mock_children.values(): + if isinstance(child, _SpecState): + continue + child.reset_mock() + + ret = self._mock_return_value + if _is_instance_mock(ret) and ret is not self: + ret.reset_mock() + + + def configure_mock(self, **kwargs): + """Set attributes on the mock through keyword arguments. + + Attributes plus return values and side effects can be set on child + mocks using standard dot notation and unpacking a dictionary in the + method call: + + >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} + >>> mock.configure_mock(**attrs)""" + for arg, val in sorted(kwargs.items(), + # we sort on the number of dots so that + # attributes are set before we set attributes on + # attributes + key=lambda entry: entry[0].count('.')): + args = arg.split('.') + final = args.pop() + obj = self + for entry in args: + obj = getattr(obj, entry) + setattr(obj, final, val) + + + def __getattr__(self, name): + if name == '_mock_methods': + raise AttributeError(name) + elif self._mock_methods is not None: + if name not in self._mock_methods or name in _all_magics: + raise AttributeError("Mock object has no attribute %r" % name) + elif _is_magic(name): + raise AttributeError(name) + + result = self._mock_children.get(name) + if result is _deleted: + raise AttributeError(name) + elif result is None: + wraps = None + if self._mock_wraps is not None: + # XXXX should we get the attribute without triggering code + # execution? + wraps = getattr(self._mock_wraps, name) + + result = self._get_child_mock( + parent=self, name=name, wraps=wraps, _new_name=name, + _new_parent=self + ) + self._mock_children[name] = result + + elif isinstance(result, _SpecState): + result = create_autospec( + result.spec, result.spec_set, result.instance, + result.parent, result.name + ) + self._mock_children[name] = result + + return result + + + def __repr__(self): + _name_list = [self._mock_new_name] + _parent = self._mock_new_parent + last = self + + dot = '.' + if _name_list == ['()']: + dot = '' + seen = set() + while _parent is not None: + last = _parent + + _name_list.append(_parent._mock_new_name + dot) + dot = '.' + if _parent._mock_new_name == '()': + dot = '' + + _parent = _parent._mock_new_parent + + # use ids here so as not to call __hash__ on the mocks + if id(_parent) in seen: + break + seen.add(id(_parent)) + + _name_list = list(reversed(_name_list)) + _first = last._mock_name or 'mock' + if len(_name_list) > 1: + if _name_list[1] not in ('()', '().'): + _first += '.' + _name_list[0] = _first + name = ''.join(_name_list) + + name_string = '' + if name not in ('mock', 'mock.'): + name_string = ' name=%r' % name + + spec_string = '' + if self._spec_class is not None: + spec_string = ' spec=%r' + if self._spec_set: + spec_string = ' spec_set=%r' + spec_string = spec_string % self._spec_class.__name__ + return "<%s%s%s id='%s'>" % ( + type(self).__name__, + name_string, + spec_string, + id(self) + ) + + + def __dir__(self): + """Filter the output of `dir(mock)` to only useful members. + XXXX + """ + extras = self._mock_methods or [] + from_type = dir(type(self)) + from_dict = list(self.__dict__) + + if FILTER_DIR: + from_type = [e for e in from_type if not e.startswith('_')] + from_dict = [e for e in from_dict if not e.startswith('_') or + _is_magic(e)] + return sorted(set(extras + from_type + from_dict + + list(self._mock_children))) + + + def __setattr__(self, name, value): + if name in _allowed_names: + # property setters go through here + return object.__setattr__(self, name, value) + elif (self._spec_set and self._mock_methods is not None and + name not in self._mock_methods and + name not in self.__dict__): + raise AttributeError("Mock object has no attribute '%s'" % name) + elif name in _unsupported_magics: + msg = 'Attempting to set unsupported magic method %r.' % name + raise AttributeError(msg) + elif name in _all_magics: + if self._mock_methods is not None and name not in self._mock_methods: + raise AttributeError("Mock object has no attribute '%s'" % name) + + if not _is_instance_mock(value): + setattr(type(self), name, _get_method(name, value)) + original = value + value = lambda *args, **kw: original(self, *args, **kw) + else: + # only set _new_name and not name so that mock_calls is tracked + # but not method calls + _check_and_set_parent(self, value, None, name) + setattr(type(self), name, value) + self._mock_children[name] = value + elif name == '__class__': + self._spec_class = value + return + else: + if _check_and_set_parent(self, value, name, name): + self._mock_children[name] = value + return object.__setattr__(self, name, value) + + + def __delattr__(self, name): + if name in _all_magics and name in type(self).__dict__: + delattr(type(self), name) + if name not in self.__dict__: + # for magic methods that are still MagicProxy objects and + # not set on the instance itself + return + + if name in self.__dict__: + object.__delattr__(self, name) + + obj = self._mock_children.get(name, _missing) + if obj is _deleted: + raise AttributeError(name) + if obj is not _missing: + del self._mock_children[name] + self._mock_children[name] = _deleted + + + + def _format_mock_call_signature(self, args, kwargs): + name = self._mock_name or 'mock' + return _format_call_signature(name, args, kwargs) + + + def _format_mock_failure_message(self, args, kwargs): + message = 'Expected call: %s\nActual call: %s' + expected_string = self._format_mock_call_signature(args, kwargs) + call_args = self.call_args + if len(call_args) == 3: + call_args = call_args[1:] + actual_string = self._format_mock_call_signature(*call_args) + return message % (expected_string, actual_string) + + + def assert_called_with(_mock_self, *args, **kwargs): + """assert that the mock was called with the specified arguments. + + Raises an AssertionError if the args and keyword args passed in are + different to the last call to the mock.""" + self = _mock_self + if self.call_args is None: + expected = self._format_mock_call_signature(args, kwargs) + raise AssertionError('Expected call: %s\nNot called' % (expected,)) + + if self.call_args != (args, kwargs): + msg = self._format_mock_failure_message(args, kwargs) + raise AssertionError(msg) + + + def assert_called_once_with(_mock_self, *args, **kwargs): + """assert that the mock was called exactly once and with the specified + arguments.""" + self = _mock_self + if not self.call_count == 1: + msg = ("Expected to be called once. Called %s times." % + self.call_count) + raise AssertionError(msg) + return self.assert_called_with(*args, **kwargs) + + + def assert_has_calls(self, calls, any_order=False): + """assert the mock has been called with the specified calls. + The `mock_calls` list is checked for the calls. + + If `any_order` is False (the default) then the calls must be + sequential. There can be extra calls before or after the + specified calls. + + If `any_order` is True then the calls can be in any order, but + they must all appear in `mock_calls`.""" + if not any_order: + if calls not in self.mock_calls: + raise AssertionError( + 'Calls not found.\nExpected: %r\n' + 'Actual: %r' % (calls, self.mock_calls) + ) + return + + all_calls = list(self.mock_calls) + + not_found = [] + for kall in calls: + try: + all_calls.remove(kall) + except ValueError: + not_found.append(kall) + if not_found: + raise AssertionError( + '%r not all found in call list' % (tuple(not_found),) + ) + + + def assert_any_call(self, *args, **kwargs): + """assert the mock has been called with the specified arguments. + + The assert passes if the mock has *ever* been called, unlike + `assert_called_with` and `assert_called_once_with` that only pass if + the call is the most recent one.""" + kall = call(*args, **kwargs) + if kall not in self.call_args_list: + expected_string = self._format_mock_call_signature(args, kwargs) + raise AssertionError( + '%s call not found' % expected_string + ) + + + def _get_child_mock(self, **kw): + """Create the child mocks for attributes and return value. + By default child mocks will be the same type as the parent. + Subclasses of Mock may want to override this to customize the way + child mocks are made. + + For non-callable mocks the callable variant will be used (rather than + any custom subclass).""" + _type = type(self) + if not issubclass(_type, CallableMixin): + if issubclass(_type, NonCallableMagicMock): + klass = MagicMock + elif issubclass(_type, NonCallableMock) : + klass = Mock + else: + klass = _type.__mro__[1] + return klass(**kw) + + + +def _try_iter(obj): + if obj is None: + return obj + if _is_exception(obj): + return obj + if _callable(obj): + return obj + try: + return iter(obj) + except TypeError: + # XXXX backwards compatibility + # but this will blow up on first call - so maybe we should fail early? + return obj + + + +class CallableMixin(Base): + + def __init__(self, spec=None, side_effect=None, return_value=DEFAULT, + wraps=None, name=None, spec_set=None, parent=None, + _spec_state=None, _new_name='', _new_parent=None, **kwargs): + self.__dict__['_mock_return_value'] = return_value + + _super(CallableMixin, self).__init__( + spec, wraps, name, spec_set, parent, + _spec_state, _new_name, _new_parent, **kwargs + ) + + self.side_effect = side_effect + + + def _mock_check_sig(self, *args, **kwargs): + # stub method that can be replaced with one with a specific signature + pass + + + def __call__(_mock_self, *args, **kwargs): + # can't use self in-case a function / method we are mocking uses self + # in the signature + _mock_self._mock_check_sig(*args, **kwargs) + return _mock_self._mock_call(*args, **kwargs) + + + def _mock_call(_mock_self, *args, **kwargs): + self = _mock_self + self.called = True + self.call_count += 1 + self.call_args = _Call((args, kwargs), two=True) + self.call_args_list.append(_Call((args, kwargs), two=True)) + + _new_name = self._mock_new_name + _new_parent = self._mock_new_parent + self.mock_calls.append(_Call(('', args, kwargs))) + + seen = set() + skip_next_dot = _new_name == '()' + do_method_calls = self._mock_parent is not None + name = self._mock_name + while _new_parent is not None: + this_mock_call = _Call((_new_name, args, kwargs)) + if _new_parent._mock_new_name: + dot = '.' + if skip_next_dot: + dot = '' + + skip_next_dot = False + if _new_parent._mock_new_name == '()': + skip_next_dot = True + + _new_name = _new_parent._mock_new_name + dot + _new_name + + if do_method_calls: + if _new_name == name: + this_method_call = this_mock_call + else: + this_method_call = _Call((name, args, kwargs)) + _new_parent.method_calls.append(this_method_call) + + do_method_calls = _new_parent._mock_parent is not None + if do_method_calls: + name = _new_parent._mock_name + '.' + name + + _new_parent.mock_calls.append(this_mock_call) + _new_parent = _new_parent._mock_new_parent + + # use ids here so as not to call __hash__ on the mocks + _new_parent_id = id(_new_parent) + if _new_parent_id in seen: + break + seen.add(_new_parent_id) + + ret_val = DEFAULT + effect = self.side_effect + if effect is not None: + if _is_exception(effect): + raise effect + + if not _callable(effect): + result = next(effect) + if _is_exception(result): + raise result + return result + + ret_val = effect(*args, **kwargs) + if ret_val is DEFAULT: + ret_val = self.return_value + + if (self._mock_wraps is not None and + self._mock_return_value is DEFAULT): + return self._mock_wraps(*args, **kwargs) + if ret_val is DEFAULT: + ret_val = self.return_value + return ret_val + + + +class Mock(CallableMixin, NonCallableMock): + """ + Create a new `Mock` object. `Mock` takes several optional arguments + that specify the behaviour of the Mock object: + + * `spec`: This can be either a list of strings or an existing object (a + class or instance) that acts as the specification for the mock object. If + you pass in an object then a list of strings is formed by calling dir on + the object (excluding unsupported magic attributes and methods). Accessing + any attribute not in this list will raise an `AttributeError`. + + If `spec` is an object (rather than a list of strings) then + `mock.__class__` returns the class of the spec object. This allows mocks + to pass `isinstance` tests. + + * `spec_set`: A stricter variant of `spec`. If used, attempting to *set* + or get an attribute on the mock that isn't on the object passed as + `spec_set` will raise an `AttributeError`. + + * `side_effect`: A function to be called whenever the Mock is called. See + the `side_effect` attribute. Useful for raising exceptions or + dynamically changing return values. The function is called with the same + arguments as the mock, and unless it returns `DEFAULT`, the return + value of this function is used as the return value. + + Alternatively `side_effect` can be an exception class or instance. In + this case the exception will be raised when the mock is called. + + If `side_effect` is an iterable then each call to the mock will return + the next value from the iterable. If any of the members of the iterable + are exceptions they will be raised instead of returned. + + * `return_value`: The value returned when the mock is called. By default + this is a new Mock (created on first access). See the + `return_value` attribute. + + * `wraps`: Item for the mock object to wrap. If `wraps` is not None then + calling the Mock will pass the call through to the wrapped object + (returning the real result). Attribute access on the mock will return a + Mock object that wraps the corresponding attribute of the wrapped object + (so attempting to access an attribute that doesn't exist will raise an + `AttributeError`). + + If the mock has an explicit `return_value` set then calls are not passed + to the wrapped object and the `return_value` is returned instead. + + * `name`: If the mock has a name then it will be used in the repr of the + mock. This can be useful for debugging. The name is propagated to child + mocks. + + Mocks can also be called with arbitrary keyword arguments. These will be + used to set attributes on the mock after it is created. + """ + + + +def _dot_lookup(thing, comp, import_path): + try: + return getattr(thing, comp) + except AttributeError: + __import__(import_path) + return getattr(thing, comp) + + +def _importer(target): + components = target.split('.') + import_path = components.pop(0) + thing = __import__(import_path) + + for comp in components: + import_path += ".%s" % comp + thing = _dot_lookup(thing, comp, import_path) + return thing + + +def _is_started(patcher): + # XXXX horrible + return hasattr(patcher, 'is_local') + + +class _patch(object): + + attribute_name = None + _active_patches = set() + + def __init__( + self, getter, attribute, new, spec, create, + spec_set, autospec, new_callable, kwargs + ): + if new_callable is not None: + if new is not DEFAULT: + raise ValueError( + "Cannot use 'new' and 'new_callable' together" + ) + if autospec is not None: + raise ValueError( + "Cannot use 'autospec' and 'new_callable' together" + ) + + self.getter = getter + self.attribute = attribute + self.new = new + self.new_callable = new_callable + self.spec = spec + self.create = create + self.has_local = False + self.spec_set = spec_set + self.autospec = autospec + self.kwargs = kwargs + self.additional_patchers = [] + + + def copy(self): + patcher = _patch( + self.getter, self.attribute, self.new, self.spec, + self.create, self.spec_set, + self.autospec, self.new_callable, self.kwargs + ) + patcher.attribute_name = self.attribute_name + patcher.additional_patchers = [ + p.copy() for p in self.additional_patchers + ] + return patcher + + + def __call__(self, func): + if isinstance(func, ClassTypes): + return self.decorate_class(func) + return self.decorate_callable(func) + + + def decorate_class(self, klass): + for attr in dir(klass): + if not attr.startswith(patch.TEST_PREFIX): + continue + + attr_value = getattr(klass, attr) + if not hasattr(attr_value, "__call__"): + continue + + patcher = self.copy() + setattr(klass, attr, patcher(attr_value)) + return klass + + + def decorate_callable(self, func): + if hasattr(func, 'patchings'): + func.patchings.append(self) + return func + + @wraps(func) + def patched(*args, **keywargs): + # don't use a with here (backwards compatability with Python 2.4) + extra_args = [] + entered_patchers = [] + + # can't use try...except...finally because of Python 2.4 + # compatibility + exc_info = tuple() + try: + try: + for patching in patched.patchings: + arg = patching.__enter__() + entered_patchers.append(patching) + if patching.attribute_name is not None: + keywargs.update(arg) + elif patching.new is DEFAULT: + extra_args.append(arg) + + args += tuple(extra_args) + return func(*args, **keywargs) + except: + if (patching not in entered_patchers and + _is_started(patching)): + # the patcher may have been started, but an exception + # raised whilst entering one of its additional_patchers + entered_patchers.append(patching) + # Pass the exception to __exit__ + exc_info = sys.exc_info() + # re-raise the exception + raise + finally: + for patching in reversed(entered_patchers): + patching.__exit__(*exc_info) + + patched.patchings = [self] + if hasattr(func, 'func_code'): + # not in Python 3 + patched.compat_co_firstlineno = getattr( + func, "compat_co_firstlineno", + func.func_code.co_firstlineno + ) + return patched + + + def get_original(self): + target = self.getter() + name = self.attribute + + original = DEFAULT + local = False + + try: + original = target.__dict__[name] + except (AttributeError, KeyError): + original = getattr(target, name, DEFAULT) + else: + local = True + + if not self.create and original is DEFAULT: + raise AttributeError( + "%s does not have the attribute %r" % (target, name) + ) + return original, local + + + def __enter__(self): + """Perform the patch.""" + new, spec, spec_set = self.new, self.spec, self.spec_set + autospec, kwargs = self.autospec, self.kwargs + new_callable = self.new_callable + self.target = self.getter() + + # normalise False to None + if spec is False: + spec = None + if spec_set is False: + spec_set = None + if autospec is False: + autospec = None + + if spec is not None and autospec is not None: + raise TypeError("Can't specify spec and autospec") + if ((spec is not None or autospec is not None) and + spec_set not in (True, None)): + raise TypeError("Can't provide explicit spec_set *and* spec or autospec") + + original, local = self.get_original() + + if new is DEFAULT and autospec is None: + inherit = False + if spec is True: + # set spec to the object we are replacing + spec = original + if spec_set is True: + spec_set = original + spec = None + elif spec is not None: + if spec_set is True: + spec_set = spec + spec = None + elif spec_set is True: + spec_set = original + + if spec is not None or spec_set is not None: + if original is DEFAULT: + raise TypeError("Can't use 'spec' with create=True") + if isinstance(original, ClassTypes): + # If we're patching out a class and there is a spec + inherit = True + + Klass = MagicMock + _kwargs = {} + if new_callable is not None: + Klass = new_callable + elif spec is not None or spec_set is not None: + this_spec = spec + if spec_set is not None: + this_spec = spec_set + if _is_list(this_spec): + not_callable = '__call__' not in this_spec + else: + not_callable = not _callable(this_spec) + if not_callable: + Klass = NonCallableMagicMock + + if spec is not None: + _kwargs['spec'] = spec + if spec_set is not None: + _kwargs['spec_set'] = spec_set + + # add a name to mocks + if (isinstance(Klass, type) and + issubclass(Klass, NonCallableMock) and self.attribute): + _kwargs['name'] = self.attribute + + _kwargs.update(kwargs) + new = Klass(**_kwargs) + + if inherit and _is_instance_mock(new): + # we can only tell if the instance should be callable if the + # spec is not a list + this_spec = spec + if spec_set is not None: + this_spec = spec_set + if (not _is_list(this_spec) and not + _instance_callable(this_spec)): + Klass = NonCallableMagicMock + + _kwargs.pop('name') + new.return_value = Klass(_new_parent=new, _new_name='()', + **_kwargs) + elif autospec is not None: + # spec is ignored, new *must* be default, spec_set is treated + # as a boolean. Should we check spec is not None and that spec_set + # is a bool? + if new is not DEFAULT: + raise TypeError( + "autospec creates the mock for you. Can't specify " + "autospec and new." + ) + if original is DEFAULT: + raise TypeError("Can't use 'autospec' with create=True") + spec_set = bool(spec_set) + if autospec is True: + autospec = original + + new = create_autospec(autospec, spec_set=spec_set, + _name=self.attribute, **kwargs) + elif kwargs: + # can't set keyword args when we aren't creating the mock + # XXXX If new is a Mock we could call new.configure_mock(**kwargs) + raise TypeError("Can't pass kwargs to a mock we aren't creating") + + new_attr = new + + self.temp_original = original + self.is_local = local + setattr(self.target, self.attribute, new_attr) + if self.attribute_name is not None: + extra_args = {} + if self.new is DEFAULT: + extra_args[self.attribute_name] = new + for patching in self.additional_patchers: + arg = patching.__enter__() + if patching.new is DEFAULT: + extra_args.update(arg) + return extra_args + + return new + + + def __exit__(self, *exc_info): + """Undo the patch.""" + if not _is_started(self): + raise RuntimeError('stop called on unstarted patcher') + + if self.is_local and self.temp_original is not DEFAULT: + setattr(self.target, self.attribute, self.temp_original) + else: + delattr(self.target, self.attribute) + if not self.create and not hasattr(self.target, self.attribute): + # needed for proxy objects like django settings + setattr(self.target, self.attribute, self.temp_original) + + del self.temp_original + del self.is_local + del self.target + for patcher in reversed(self.additional_patchers): + if _is_started(patcher): + patcher.__exit__(*exc_info) + + + def start(self): + """Activate a patch, returning any created mock.""" + result = self.__enter__() + self._active_patches.add(self) + return result + + + def stop(self): + """Stop an active patch.""" + self._active_patches.discard(self) + return self.__exit__() + + + +def _get_target(target): + try: + target, attribute = target.rsplit('.', 1) + except (TypeError, ValueError): + raise TypeError("Need a valid target to patch. You supplied: %r" % + (target,)) + getter = lambda: _importer(target) + return getter, attribute + + +def _patch_object( + target, attribute, new=DEFAULT, spec=None, + create=False, spec_set=None, autospec=None, + new_callable=None, **kwargs + ): + """ + 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. + """ + getter = lambda: target + return _patch( + getter, attribute, new, spec, create, + spec_set, autospec, new_callable, kwargs + ) + + +def _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 `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 type(target) in (unicode, str): + getter = lambda: _importer(target) + else: + getter = lambda: target + + if not kwargs: + raise ValueError( + 'Must supply at least one keyword argument with patch.multiple' + ) + # need to wrap in a list for python 3, where items is a view + items = list(kwargs.items()) + attribute, new = items[0] + patcher = _patch( + getter, attribute, new, spec, create, spec_set, + autospec, new_callable, {} + ) + patcher.attribute_name = attribute + for attribute, new in items[1:]: + this_patcher = _patch( + getter, attribute, new, spec, create, spec_set, + autospec, new_callable, {} + ) + this_patcher.attribute_name = attribute + patcher.additional_patchers.append(this_patcher) + return patcher + + +def 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 + `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. + + 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. + """ + getter, attribute = _get_target(target) + return _patch( + getter, attribute, new, spec, create, + spec_set, autospec, new_callable, kwargs + ) + + +class _patch_dict(object): + """ + 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:: + + with patch.dict('sys.modules', mymodule=Mock(), other_module=Mock()): + ... + + `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. + """ + + def __init__(self, in_dict, values=(), clear=False, **kwargs): + if isinstance(in_dict, basestring): + in_dict = _importer(in_dict) + self.in_dict = in_dict + # support any argument supported by dict(...) constructor + self.values = dict(values) + self.values.update(kwargs) + self.clear = clear + self._original = None + + + def __call__(self, f): + if isinstance(f, ClassTypes): + return self.decorate_class(f) + @wraps(f) + def _inner(*args, **kw): + self._patch_dict() + try: + return f(*args, **kw) + finally: + self._unpatch_dict() + + return _inner + + + def decorate_class(self, klass): + for attr in dir(klass): + attr_value = getattr(klass, attr) + if (attr.startswith(patch.TEST_PREFIX) and + hasattr(attr_value, "__call__")): + decorator = _patch_dict(self.in_dict, self.values, self.clear) + decorated = decorator(attr_value) + setattr(klass, attr, decorated) + return klass + + + def __enter__(self): + """Patch the dict.""" + self._patch_dict() + + + def _patch_dict(self): + values = self.values + in_dict = self.in_dict + clear = self.clear + + try: + original = in_dict.copy() + except AttributeError: + # dict like object with no copy method + # must support iteration over keys + original = {} + for key in in_dict: + original[key] = in_dict[key] + self._original = original + + if clear: + _clear_dict(in_dict) + + try: + in_dict.update(values) + except AttributeError: + # dict like object with no update method + for key in values: + in_dict[key] = values[key] + + + def _unpatch_dict(self): + in_dict = self.in_dict + original = self._original + + _clear_dict(in_dict) + + try: + in_dict.update(original) + except AttributeError: + for key in original: + in_dict[key] = original[key] + + + def __exit__(self, *args): + """Unpatch the dict.""" + self._unpatch_dict() + return False + + start = __enter__ + stop = __exit__ + + +def _clear_dict(in_dict): + try: + in_dict.clear() + except AttributeError: + keys = list(in_dict) + for key in keys: + del in_dict[key] + + +def _patch_stopall(): + """Stop all active patches.""" + for patch in list(_patch._active_patches): + patch.stop() + + +patch.object = _patch_object +patch.dict = _patch_dict +patch.multiple = _patch_multiple +patch.stopall = _patch_stopall +patch.TEST_PREFIX = 'test' + +magic_methods = ( + "lt le gt ge eq ne " + "getitem setitem delitem " + "len contains iter " + "hash str sizeof " + "enter exit " + "divmod neg pos abs invert " + "complex int float index " + "trunc floor ceil " +) + +numerics = "add sub mul div floordiv mod lshift rshift and xor or pow " +inplace = ' '.join('i%s' % n for n in numerics.split()) +right = ' '.join('r%s' % n for n in numerics.split()) +extra = '' +if inPy3k: + extra = 'bool next ' +else: + extra = 'unicode long nonzero oct hex truediv rtruediv ' + +# not including __prepare__, __instancecheck__, __subclasscheck__ +# (as they are metaclass methods) +# __del__ is not supported at all as it causes problems if it exists + +_non_defaults = set('__%s__' % method for method in [ + 'cmp', 'getslice', 'setslice', 'coerce', 'subclasses', + 'format', 'get', 'set', 'delete', 'reversed', + 'missing', 'reduce', 'reduce_ex', 'getinitargs', + 'getnewargs', 'getstate', 'setstate', 'getformat', + 'setformat', 'repr', 'dir' +]) + + +def _get_method(name, func): + "Turns a callable object (like a mock) into a real function" + def method(self, *args, **kw): + return func(self, *args, **kw) + method.__name__ = name + return method + + +_magics = set( + '__%s__' % method for method in + ' '.join([magic_methods, numerics, inplace, right, extra]).split() +) + +_all_magics = _magics | _non_defaults + +_unsupported_magics = set([ + '__getattr__', '__setattr__', + '__init__', '__new__', '__prepare__' + '__instancecheck__', '__subclasscheck__', + '__del__' +]) + +_calculate_return_value = { + '__hash__': lambda self: object.__hash__(self), + '__str__': lambda self: object.__str__(self), + '__sizeof__': lambda self: object.__sizeof__(self), + '__unicode__': lambda self: unicode(object.__str__(self)), +} + +_return_values = { + '__lt__': NotImplemented, + '__gt__': NotImplemented, + '__le__': NotImplemented, + '__ge__': NotImplemented, + '__int__': 1, + '__contains__': False, + '__len__': 0, + '__exit__': False, + '__complex__': 1j, + '__float__': 1.0, + '__bool__': True, + '__nonzero__': True, + '__oct__': '1', + '__hex__': '0x1', + '__long__': long(1), + '__index__': 1, +} + + +def _get_eq(self): + def __eq__(other): + ret_val = self.__eq__._mock_return_value + if ret_val is not DEFAULT: + return ret_val + return self is other + return __eq__ + +def _get_ne(self): + def __ne__(other): + if self.__ne__._mock_return_value is not DEFAULT: + return DEFAULT + return self is not other + return __ne__ + +def _get_iter(self): + def __iter__(): + ret_val = self.__iter__._mock_return_value + if ret_val is DEFAULT: + return iter([]) + # if ret_val was already an iterator, then calling iter on it should + # return the iterator unchanged + return iter(ret_val) + return __iter__ + +_side_effect_methods = { + '__eq__': _get_eq, + '__ne__': _get_ne, + '__iter__': _get_iter, +} + + + +def _set_return_value(mock, method, name): + fixed = _return_values.get(name, DEFAULT) + if fixed is not DEFAULT: + method.return_value = fixed + return + + return_calulator = _calculate_return_value.get(name) + if return_calulator is not None: + try: + return_value = return_calulator(mock) + except AttributeError: + # XXXX why do we return AttributeError here? + # set it as a side_effect instead? + return_value = AttributeError(name) + method.return_value = return_value + return + + side_effector = _side_effect_methods.get(name) + if side_effector is not None: + method.side_effect = side_effector(mock) + + + +class MagicMixin(object): + def __init__(self, *args, **kw): + _super(MagicMixin, self).__init__(*args, **kw) + self._mock_set_magics() + + + def _mock_set_magics(self): + these_magics = _magics + + if self._mock_methods is not None: + these_magics = _magics.intersection(self._mock_methods) + + remove_magics = set() + remove_magics = _magics - these_magics + + for entry in remove_magics: + if entry in type(self).__dict__: + # remove unneeded magic methods + delattr(self, entry) + + # don't overwrite existing attributes if called a second time + these_magics = these_magics - set(type(self).__dict__) + + _type = type(self) + for entry in these_magics: + setattr(_type, entry, MagicProxy(entry, self)) + + + +class NonCallableMagicMock(MagicMixin, NonCallableMock): + """A version of `MagicMock` that isn't callable.""" + def mock_add_spec(self, spec, spec_set=False): + """Add a spec to a mock. `spec` can either be an object or a + list of strings. Only attributes on the `spec` can be fetched as + attributes from the mock. + + If `spec_set` is True then only attributes on the spec can be set.""" + self._mock_add_spec(spec, spec_set) + self._mock_set_magics() + + + +class MagicMock(MagicMixin, Mock): + """ + MagicMock is a subclass of Mock with default implementations + of most of the magic methods. You can use MagicMock without having to + configure the magic methods yourself. + + If you use the `spec` or `spec_set` arguments then *only* magic + methods that exist in the spec will be created. + + Attributes and the return value of a `MagicMock` will also be `MagicMocks`. + """ + def mock_add_spec(self, spec, spec_set=False): + """Add a spec to a mock. `spec` can either be an object or a + list of strings. Only attributes on the `spec` can be fetched as + attributes from the mock. + + If `spec_set` is True then only attributes on the spec can be set.""" + self._mock_add_spec(spec, spec_set) + self._mock_set_magics() + + + +class MagicProxy(object): + def __init__(self, name, parent): + self.name = name + self.parent = parent + + def __call__(self, *args, **kwargs): + m = self.create_mock() + return m(*args, **kwargs) + + def create_mock(self): + entry = self.name + parent = self.parent + m = parent._get_child_mock(name=entry, _new_name=entry, + _new_parent=parent) + setattr(parent, entry, m) + _set_return_value(parent, m, entry) + return m + + def __get__(self, obj, _type=None): + return self.create_mock() + + + +class _ANY(object): + "A helper object that compares equal to everything." + + def __eq__(self, other): + return True + + def __ne__(self, other): + return False + + def __repr__(self): + return '' + +ANY = _ANY() + + + +def _format_call_signature(name, args, kwargs): + message = '%s(%%s)' % name + formatted_args = '' + args_string = ', '.join([repr(arg) for arg in args]) + kwargs_string = ', '.join([ + '%s=%r' % (key, value) for key, value in kwargs.items() + ]) + if args_string: + formatted_args = args_string + if kwargs_string: + if formatted_args: + formatted_args += ', ' + formatted_args += kwargs_string + + return message % formatted_args + + + +class _Call(tuple): + """ + A tuple for holding the results of a call to a mock, either in the form + `(args, kwargs)` or `(name, args, kwargs)`. + + If args or kwargs are empty then a call tuple will compare equal to + a tuple without those values. This makes comparisons less verbose:: + + _Call(('name', (), {})) == ('name',) + _Call(('name', (1,), {})) == ('name', (1,)) + _Call(((), {'a': 'b'})) == ({'a': 'b'},) + + The `_Call` object provides a useful shortcut for comparing with call:: + + _Call(((1, 2), {'a': 3})) == call(1, 2, a=3) + _Call(('foo', (1, 2), {'a': 3})) == call.foo(1, 2, a=3) + + If the _Call has no name then it will match any name. + """ + def __new__(cls, value=(), name=None, parent=None, two=False, + from_kall=True): + name = '' + args = () + kwargs = {} + _len = len(value) + if _len == 3: + name, args, kwargs = value + elif _len == 2: + first, second = value + if isinstance(first, basestring): + name = first + if isinstance(second, tuple): + args = second + else: + kwargs = second + else: + args, kwargs = first, second + elif _len == 1: + value, = value + if isinstance(value, basestring): + name = value + elif isinstance(value, tuple): + args = value + else: + kwargs = value + + if two: + return tuple.__new__(cls, (args, kwargs)) + + return tuple.__new__(cls, (name, args, kwargs)) + + + def __init__(self, value=(), name=None, parent=None, two=False, + from_kall=True): + self.name = name + self.parent = parent + self.from_kall = from_kall + + + def __eq__(self, other): + if other is ANY: + return True + try: + len_other = len(other) + except TypeError: + return False + + self_name = '' + if len(self) == 2: + self_args, self_kwargs = self + else: + self_name, self_args, self_kwargs = self + + other_name = '' + if len_other == 0: + other_args, other_kwargs = (), {} + elif len_other == 3: + other_name, other_args, other_kwargs = other + elif len_other == 1: + value, = other + if isinstance(value, tuple): + other_args = value + other_kwargs = {} + elif isinstance(value, basestring): + other_name = value + other_args, other_kwargs = (), {} + else: + other_args = () + other_kwargs = value + else: + # len 2 + # could be (name, args) or (name, kwargs) or (args, kwargs) + first, second = other + if isinstance(first, basestring): + other_name = first + if isinstance(second, tuple): + other_args, other_kwargs = second, {} + else: + other_args, other_kwargs = (), second + else: + other_args, other_kwargs = first, second + + if self_name and other_name != self_name: + return False + + # this order is important for ANY to work! + return (other_args, other_kwargs) == (self_args, self_kwargs) + + + def __ne__(self, other): + return not self.__eq__(other) + + + def __call__(self, *args, **kwargs): + if self.name is None: + return _Call(('', args, kwargs), name='()') + + name = self.name + '()' + return _Call((self.name, args, kwargs), name=name, parent=self) + + + def __getattr__(self, attr): + if self.name is None: + return _Call(name=attr, from_kall=False) + name = '%s.%s' % (self.name, attr) + return _Call(name=name, parent=self, from_kall=False) + + + def __repr__(self): + if not self.from_kall: + name = self.name or 'call' + if name.startswith('()'): + name = 'call%s' % name + return name + + if len(self) == 2: + name = 'call' + args, kwargs = self + else: + name, args, kwargs = self + if not name: + name = 'call' + elif not name.startswith('()'): + name = 'call.%s' % name + else: + name = 'call%s' % name + return _format_call_signature(name, args, kwargs) + + + def call_list(self): + """For a call object that represents multiple calls, `call_list` + returns a list of all the intermediate calls as well as the + final call.""" + vals = [] + thing = self + while thing is not None: + if thing.from_kall: + vals.append(thing) + thing = thing.parent + return _CallList(reversed(vals)) + + +call = _Call(from_kall=False) + + + +def create_autospec(spec, spec_set=False, instance=False, _parent=None, + _name=None, **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 check 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.""" + if _is_list(spec): + # can't pass a list instance to the mock constructor as it will be + # interpreted as a list of strings + spec = type(spec) + + is_type = isinstance(spec, ClassTypes) + + _kwargs = {'spec': spec} + if spec_set: + _kwargs = {'spec_set': spec} + elif spec is None: + # None we mock with a normal mock without a spec + _kwargs = {} + + _kwargs.update(kwargs) + + Klass = MagicMock + if type(spec) in DescriptorTypes: + # descriptors don't have a spec + # because we don't know what type they return + _kwargs = {} + elif not _callable(spec): + Klass = NonCallableMagicMock + elif is_type and instance and not _instance_callable(spec): + Klass = NonCallableMagicMock + + _new_name = _name + if _parent is None: + # for a top level object no _new_name should be set + _new_name = '' + + mock = Klass(parent=_parent, _new_parent=_parent, _new_name=_new_name, + name=_name, **_kwargs) + + if isinstance(spec, FunctionTypes): + # should only happen at the top level because we don't + # recurse for functions + mock = _set_signature(mock, spec) + else: + _check_signature(spec, mock, is_type, instance) + + if _parent is not None and not instance: + _parent._mock_children[_name] = mock + + if is_type and not instance and 'return_value' not in kwargs: + mock.return_value = create_autospec(spec, spec_set, instance=True, + _name='()', _parent=mock) + + for entry in dir(spec): + if _is_magic(entry): + # MagicMock already does the useful magic methods for us + continue + + if isinstance(spec, FunctionTypes) and entry in FunctionAttributes: + # allow a mock to actually be a function + continue + + # XXXX do we need a better way of getting attributes without + # triggering code execution (?) Probably not - we need the actual + # object to mock it so we would rather trigger a property than mock + # the property descriptor. Likewise we want to mock out dynamically + # provided attributes. + # XXXX what about attributes that raise exceptions other than + # AttributeError on being fetched? + # we could be resilient against it, or catch and propagate the + # exception when the attribute is fetched from the mock + try: + original = getattr(spec, entry) + except AttributeError: + continue + + kwargs = {'spec': original} + if spec_set: + kwargs = {'spec_set': original} + + if not isinstance(original, FunctionTypes): + new = _SpecState(original, spec_set, mock, entry, instance) + mock._mock_children[entry] = new + else: + parent = mock + if isinstance(spec, FunctionTypes): + parent = mock.mock + + new = MagicMock(parent=parent, name=entry, _new_name=entry, + _new_parent=parent, **kwargs) + mock._mock_children[entry] = new + skipfirst = _must_skip(spec, entry, is_type) + _check_signature(original, new, skipfirst=skipfirst) + + # so functions created with _set_signature become instance attributes, + # *plus* their underlying mock exists in _mock_children of the parent + # mock. Adding to _mock_children may be unnecessary where we are also + # setting as an instance attribute? + if isinstance(new, FunctionTypes): + setattr(mock, entry, new) + + return mock + + +def _must_skip(spec, entry, is_type): + if not isinstance(spec, ClassTypes): + if entry in getattr(spec, '__dict__', {}): + # instance attribute - shouldn't skip + return False + spec = spec.__class__ + if not hasattr(spec, '__mro__'): + # old style class: can't have descriptors anyway + return is_type + + for klass in spec.__mro__: + result = klass.__dict__.get(entry, DEFAULT) + if result is DEFAULT: + continue + if isinstance(result, (staticmethod, classmethod)): + return False + return is_type + + # shouldn't get here unless function is a dynamically provided attribute + # XXXX untested behaviour + return is_type + + +def _get_class(obj): + try: + return obj.__class__ + except AttributeError: + # in Python 2, _sre.SRE_Pattern objects have no __class__ + return type(obj) + + +class _SpecState(object): + + def __init__(self, spec, spec_set=False, parent=None, + name=None, ids=None, instance=False): + self.spec = spec + self.ids = ids + self.spec_set = spec_set + self.parent = parent + self.instance = instance + self.name = name + + +FunctionTypes = ( + # python function + type(create_autospec), + # instance method + type(ANY.__eq__), + # unbound method + type(_ANY.__eq__), +) + +FunctionAttributes = set([ + 'func_closure', + 'func_code', + 'func_defaults', + 'func_dict', + 'func_doc', + 'func_globals', + 'func_name', +]) + + +file_spec = None + + +def mock_open(mock=None, read_data=''): + """ + 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. + """ + global file_spec + if file_spec is None: + # set on first use + if inPy3k: + import _io + file_spec = list(set(dir(_io.TextIOWrapper)).union(set(dir(_io.BytesIO)))) + else: + file_spec = file + + if mock is None: + mock = MagicMock(name='open', spec=open) + + handle = MagicMock(spec=file_spec) + handle.write.return_value = None + handle.__enter__.return_value = handle + handle.read.return_value = read_data + + mock.return_value = handle + return mock + + +class PropertyMock(Mock): + """ + A mock intended to be used as a property, or other descriptor, on a class. + `PropertyMock` provides `__get__` and `__set__` methods so you can specify + a return value when it is fetched. + + Fetching a `PropertyMock` instance from an object calls the mock, with + no args. Setting it calls the mock with the value being set. + """ + def _get_child_mock(self, **kwargs): + return MagicMock(**kwargs) + + def __get__(self, obj, obj_type): + return self() + def __set__(self, obj, val): + self(val) diff --git a/python/mock-1.0.0/setup.cfg b/python/mock-1.0.0/setup.cfg new file mode 100644 index 000000000..00948b7e4 --- /dev/null +++ b/python/mock-1.0.0/setup.cfg @@ -0,0 +1,12 @@ +[build_sphinx] +source-dir = docs +build-dir = html + +[sdist] +force-manifest = 1 + +[egg_info] +tag_build = +tag_date = 0 +tag_svn_revision = 0 + diff --git a/python/mock-1.0.0/setup.py b/python/mock-1.0.0/setup.py new file mode 100755 index 000000000..7c25e8f2d --- /dev/null +++ b/python/mock-1.0.0/setup.py @@ -0,0 +1,72 @@ +#! /usr/bin/env python + +# Copyright (C) 2007-2012 Michael Foord & the mock team +# E-mail: fuzzyman AT voidspace DOT org DOT uk +# http://www.voidspace.org.uk/python/mock/ + +from mock import __version__ + +import os + + +NAME = 'mock' +MODULES = ['mock'] +DESCRIPTION = 'A Python Mocking and Patching Library for Testing' + +URL = "http://www.voidspace.org.uk/python/mock/" + +readme = os.path.join(os.path.dirname(__file__), 'README.txt') +LONG_DESCRIPTION = open(readme).read() + +CLASSIFIERS = [ + 'Development Status :: 5 - Production/Stable', + 'Environment :: Console', + 'Intended Audience :: Developers', + 'License :: OSI Approved :: BSD License', + 'Programming Language :: Python', + 'Programming Language :: Python :: 2', + 'Programming Language :: Python :: 3', + 'Programming Language :: Python :: 2.4', + 'Programming Language :: Python :: 2.5', + 'Programming Language :: Python :: 2.6', + 'Programming Language :: Python :: 2.7', + 'Programming Language :: Python :: 3.1', + 'Programming Language :: Python :: 3.2', + 'Programming Language :: Python :: Implementation :: CPython', + 'Programming Language :: Python :: Implementation :: PyPy', + 'Programming Language :: Python :: Implementation :: Jython', + 'Operating System :: OS Independent', + 'Topic :: Software Development :: Libraries', + 'Topic :: Software Development :: Libraries :: Python Modules', + 'Topic :: Software Development :: Testing', +] + +AUTHOR = 'Michael Foord' +AUTHOR_EMAIL = 'michael@voidspace.org.uk' +KEYWORDS = ("testing test mock mocking unittest patching " + "stubs fakes doubles").split(' ') + +params = dict( + name=NAME, + version=__version__, + py_modules=MODULES, + + # metadata for upload to PyPI + author=AUTHOR, + author_email=AUTHOR_EMAIL, + description=DESCRIPTION, + long_description=LONG_DESCRIPTION, + keywords=KEYWORDS, + url=URL, + classifiers=CLASSIFIERS, +) + +try: + from setuptools import setup +except ImportError: + from distutils.core import setup +else: + params['tests_require'] = ['unittest2'] + params['test_suite'] = 'unittest2.collector' + +setup(**params) diff --git a/python/mock-1.0.0/tests/__init__.py b/python/mock-1.0.0/tests/__init__.py new file mode 100644 index 000000000..54ddf2ecc --- /dev/null +++ b/python/mock-1.0.0/tests/__init__.py @@ -0,0 +1,3 @@ +# Copyright (C) 2007-2012 Michael Foord & the mock team +# E-mail: fuzzyman AT voidspace DOT org DOT uk +# http://www.voidspace.org.uk/python/mock/ diff --git a/python/mock-1.0.0/tests/_testwith.py b/python/mock-1.0.0/tests/_testwith.py new file mode 100644 index 000000000..0b54780b8 --- /dev/null +++ b/python/mock-1.0.0/tests/_testwith.py @@ -0,0 +1,181 @@ +# Copyright (C) 2007-2012 Michael Foord & the mock team +# E-mail: fuzzyman AT voidspace DOT org DOT uk +# http://www.voidspace.org.uk/python/mock/ + +from __future__ import with_statement + +from tests.support import unittest2, is_instance + +from mock import MagicMock, Mock, patch, sentinel, mock_open, call + +from tests.support_with import catch_warnings, nested + +something = sentinel.Something +something_else = sentinel.SomethingElse + + + +class WithTest(unittest2.TestCase): + + def test_with_statement(self): + with patch('tests._testwith.something', sentinel.Something2): + self.assertEqual(something, sentinel.Something2, "unpatched") + self.assertEqual(something, sentinel.Something) + + + def test_with_statement_exception(self): + try: + with patch('tests._testwith.something', sentinel.Something2): + self.assertEqual(something, sentinel.Something2, "unpatched") + raise Exception('pow') + except Exception: + pass + else: + self.fail("patch swallowed exception") + self.assertEqual(something, sentinel.Something) + + + def test_with_statement_as(self): + with patch('tests._testwith.something') as mock_something: + self.assertEqual(something, mock_something, "unpatched") + self.assertTrue(is_instance(mock_something, MagicMock), + "patching wrong type") + self.assertEqual(something, sentinel.Something) + + + def test_patch_object_with_statement(self): + class Foo(object): + something = 'foo' + original = Foo.something + with patch.object(Foo, 'something'): + self.assertNotEqual(Foo.something, original, "unpatched") + self.assertEqual(Foo.something, original) + + + def test_with_statement_nested(self): + with catch_warnings(record=True): + # nested is deprecated in Python 2.7 + with nested(patch('tests._testwith.something'), + patch('tests._testwith.something_else')) as (mock_something, mock_something_else): + self.assertEqual(something, mock_something, "unpatched") + self.assertEqual(something_else, mock_something_else, + "unpatched") + self.assertEqual(something, sentinel.Something) + self.assertEqual(something_else, sentinel.SomethingElse) + + + def test_with_statement_specified(self): + with patch('tests._testwith.something', sentinel.Patched) as mock_something: + self.assertEqual(something, mock_something, "unpatched") + self.assertEqual(mock_something, sentinel.Patched, "wrong patch") + self.assertEqual(something, sentinel.Something) + + + def testContextManagerMocking(self): + mock = Mock() + mock.__enter__ = Mock() + mock.__exit__ = Mock() + mock.__exit__.return_value = False + + with mock as m: + self.assertEqual(m, mock.__enter__.return_value) + mock.__enter__.assert_called_with() + mock.__exit__.assert_called_with(None, None, None) + + + def test_context_manager_with_magic_mock(self): + mock = MagicMock() + + with self.assertRaises(TypeError): + with mock: + 'foo' + 3 + mock.__enter__.assert_called_with() + self.assertTrue(mock.__exit__.called) + + + def test_with_statement_same_attribute(self): + with patch('tests._testwith.something', sentinel.Patched) as mock_something: + self.assertEqual(something, mock_something, "unpatched") + + with patch('tests._testwith.something') as mock_again: + self.assertEqual(something, mock_again, "unpatched") + + self.assertEqual(something, mock_something, + "restored with wrong instance") + + self.assertEqual(something, sentinel.Something, "not restored") + + + def test_with_statement_imbricated(self): + with patch('tests._testwith.something') as mock_something: + self.assertEqual(something, mock_something, "unpatched") + + with patch('tests._testwith.something_else') as mock_something_else: + self.assertEqual(something_else, mock_something_else, + "unpatched") + + self.assertEqual(something, sentinel.Something) + self.assertEqual(something_else, sentinel.SomethingElse) + + + def test_dict_context_manager(self): + foo = {} + with patch.dict(foo, {'a': 'b'}): + self.assertEqual(foo, {'a': 'b'}) + self.assertEqual(foo, {}) + + with self.assertRaises(NameError): + with patch.dict(foo, {'a': 'b'}): + self.assertEqual(foo, {'a': 'b'}) + raise NameError('Konrad') + + self.assertEqual(foo, {}) + + + +class TestMockOpen(unittest2.TestCase): + + def test_mock_open(self): + mock = mock_open() + with patch('%s.open' % __name__, mock, create=True) as patched: + self.assertIs(patched, mock) + open('foo') + + mock.assert_called_once_with('foo') + + + def test_mock_open_context_manager(self): + mock = mock_open() + handle = mock.return_value + with patch('%s.open' % __name__, mock, create=True): + with open('foo') as f: + f.read() + + expected_calls = [call('foo'), call().__enter__(), call().read(), + call().__exit__(None, None, None)] + self.assertEqual(mock.mock_calls, expected_calls) + self.assertIs(f, handle) + + + def test_explicit_mock(self): + mock = MagicMock() + mock_open(mock) + + with patch('%s.open' % __name__, mock, create=True) as patched: + self.assertIs(patched, mock) + open('foo') + + mock.assert_called_once_with('foo') + + + def test_read_data(self): + mock = mock_open(read_data='foo') + with patch('%s.open' % __name__, mock, create=True): + h = open('bar') + result = h.read() + + self.assertEqual(result, 'foo') + + +if __name__ == '__main__': + unittest2.main() diff --git a/python/mock-1.0.0/tests/support.py b/python/mock-1.0.0/tests/support.py new file mode 100644 index 000000000..1b10c3428 --- /dev/null +++ b/python/mock-1.0.0/tests/support.py @@ -0,0 +1,41 @@ +import sys + +info = sys.version_info +if info[:3] >= (3, 2, 0): + # for Python 3.2 ordinary unittest is fine + import unittest as unittest2 +else: + import unittest2 + + +try: + callable = callable +except NameError: + def callable(obj): + return hasattr(obj, '__call__') + + +inPy3k = sys.version_info[0] == 3 +with_available = sys.version_info[:2] >= (2, 5) + + +def is_instance(obj, klass): + """Version of is_instance that doesn't access __class__""" + return issubclass(type(obj), klass) + + +class SomeClass(object): + class_attribute = None + + def wibble(self): + pass + + +class X(object): + pass + +try: + next = next +except NameError: + def next(obj): + return obj.next() diff --git a/python/mock-1.0.0/tests/support_with.py b/python/mock-1.0.0/tests/support_with.py new file mode 100644 index 000000000..fa286122c --- /dev/null +++ b/python/mock-1.0.0/tests/support_with.py @@ -0,0 +1,93 @@ +from __future__ import with_statement + +import sys + +__all__ = ['nested', 'catch_warnings', 'examine_warnings'] + + +try: + from contextlib import nested +except ImportError: + from contextlib import contextmanager + @contextmanager + def nested(*managers): + exits = [] + vars = [] + exc = (None, None, None) + try: + for mgr in managers: + exit = mgr.__exit__ + enter = mgr.__enter__ + vars.append(enter()) + exits.append(exit) + yield vars + except: + exc = sys.exc_info() + finally: + while exits: + exit = exits.pop() + try: + if exit(*exc): + exc = (None, None, None) + except: + exc = sys.exc_info() + if exc != (None, None, None): + raise exc[1] + +# copied from Python 2.6 +try: + from warnings import catch_warnings +except ImportError: + class catch_warnings(object): + def __init__(self, record=False, module=None): + self._record = record + self._module = sys.modules['warnings'] + self._entered = False + + def __repr__(self): + args = [] + if self._record: + args.append("record=True") + name = type(self).__name__ + return "%s(%s)" % (name, ", ".join(args)) + + def __enter__(self): + if self._entered: + raise RuntimeError("Cannot enter %r twice" % self) + self._entered = True + self._filters = self._module.filters + self._module.filters = self._filters[:] + self._showwarning = self._module.showwarning + if self._record: + log = [] + def showwarning(*args, **kwargs): + log.append(WarningMessage(*args, **kwargs)) + self._module.showwarning = showwarning + return log + else: + return None + + def __exit__(self, *exc_info): + if not self._entered: + raise RuntimeError("Cannot exit %r without entering first" % self) + self._module.filters = self._filters + self._module.showwarning = self._showwarning + + class WarningMessage(object): + _WARNING_DETAILS = ("message", "category", "filename", "lineno", "file", + "line") + def __init__(self, message, category, filename, lineno, file=None, + line=None): + local_values = locals() + for attr in self._WARNING_DETAILS: + setattr(self, attr, local_values[attr]) + self._category_name = None + if category.__name__: + self._category_name = category.__name__ + + +def examine_warnings(func): + def wrapper(): + with catch_warnings(record=True) as ws: + func(ws) + return wrapper diff --git a/python/mock-1.0.0/tests/testcallable.py b/python/mock-1.0.0/tests/testcallable.py new file mode 100644 index 000000000..f7dcd5e1d --- /dev/null +++ b/python/mock-1.0.0/tests/testcallable.py @@ -0,0 +1,158 @@ +# Copyright (C) 2007-2012 Michael Foord & the mock team +# E-mail: fuzzyman AT voidspace DOT org DOT uk +# http://www.voidspace.org.uk/python/mock/ + +from tests.support import is_instance, unittest2, X, SomeClass + +from mock import ( + Mock, MagicMock, NonCallableMagicMock, + NonCallableMock, patch, create_autospec, + CallableMixin +) + + + +class TestCallable(unittest2.TestCase): + + def assertNotCallable(self, mock): + self.assertTrue(is_instance(mock, NonCallableMagicMock)) + self.assertFalse(is_instance(mock, CallableMixin)) + + + def test_non_callable(self): + for mock in NonCallableMagicMock(), NonCallableMock(): + self.assertRaises(TypeError, mock) + self.assertFalse(hasattr(mock, '__call__')) + self.assertIn(mock.__class__.__name__, repr(mock)) + + + def test_heirarchy(self): + self.assertTrue(issubclass(MagicMock, Mock)) + self.assertTrue(issubclass(NonCallableMagicMock, NonCallableMock)) + + + def test_attributes(self): + one = NonCallableMock() + self.assertTrue(issubclass(type(one.one), Mock)) + + two = NonCallableMagicMock() + self.assertTrue(issubclass(type(two.two), MagicMock)) + + + def test_subclasses(self): + class MockSub(Mock): + pass + + one = MockSub() + self.assertTrue(issubclass(type(one.one), MockSub)) + + class MagicSub(MagicMock): + pass + + two = MagicSub() + self.assertTrue(issubclass(type(two.two), MagicSub)) + + + def test_patch_spec(self): + patcher = patch('%s.X' % __name__, spec=True) + mock = patcher.start() + self.addCleanup(patcher.stop) + + instance = mock() + mock.assert_called_once_with() + + self.assertNotCallable(instance) + self.assertRaises(TypeError, instance) + + + def test_patch_spec_set(self): + patcher = patch('%s.X' % __name__, spec_set=True) + mock = patcher.start() + self.addCleanup(patcher.stop) + + instance = mock() + mock.assert_called_once_with() + + self.assertNotCallable(instance) + self.assertRaises(TypeError, instance) + + + def test_patch_spec_instance(self): + patcher = patch('%s.X' % __name__, spec=X()) + mock = patcher.start() + self.addCleanup(patcher.stop) + + self.assertNotCallable(mock) + self.assertRaises(TypeError, mock) + + + def test_patch_spec_set_instance(self): + patcher = patch('%s.X' % __name__, spec_set=X()) + mock = patcher.start() + self.addCleanup(patcher.stop) + + self.assertNotCallable(mock) + self.assertRaises(TypeError, mock) + + + def test_patch_spec_callable_class(self): + class CallableX(X): + def __call__(self): + pass + + class Sub(CallableX): + pass + + class Multi(SomeClass, Sub): + pass + + class OldStyle: + def __call__(self): + pass + + class OldStyleSub(OldStyle): + pass + + for arg in 'spec', 'spec_set': + for Klass in CallableX, Sub, Multi, OldStyle, OldStyleSub: + patcher = patch('%s.X' % __name__, **{arg: Klass}) + mock = patcher.start() + + try: + instance = mock() + mock.assert_called_once_with() + + self.assertTrue(is_instance(instance, MagicMock)) + # inherited spec + self.assertRaises(AttributeError, getattr, instance, + 'foobarbaz') + + result = instance() + # instance is callable, result has no spec + instance.assert_called_once_with() + + result(3, 2, 1) + result.assert_called_once_with(3, 2, 1) + result.foo(3, 2, 1) + result.foo.assert_called_once_with(3, 2, 1) + finally: + patcher.stop() + + + def test_create_autopsec(self): + mock = create_autospec(X) + instance = mock() + self.assertRaises(TypeError, instance) + + mock = create_autospec(X()) + self.assertRaises(TypeError, mock) + + + def test_create_autospec_instance(self): + mock = create_autospec(SomeClass, instance=True) + + self.assertRaises(TypeError, mock) + mock.wibble() + mock.wibble.assert_called_once_with() + + self.assertRaises(TypeError, mock.wibble, 'some', 'args') diff --git a/python/mock-1.0.0/tests/testhelpers.py b/python/mock-1.0.0/tests/testhelpers.py new file mode 100644 index 000000000..e788da844 --- /dev/null +++ b/python/mock-1.0.0/tests/testhelpers.py @@ -0,0 +1,940 @@ +# Copyright (C) 2007-2012 Michael Foord & the mock team +# E-mail: fuzzyman AT voidspace DOT org DOT uk +# http://www.voidspace.org.uk/python/mock/ + +from tests.support import unittest2, inPy3k + +from mock import ( + call, _Call, create_autospec, MagicMock, + Mock, ANY, _CallList, patch, PropertyMock +) + +from datetime import datetime + +class SomeClass(object): + def one(self, a, b): + pass + def two(self): + pass + def three(self, a=None): + pass + + + +class AnyTest(unittest2.TestCase): + + def test_any(self): + self.assertEqual(ANY, object()) + + mock = Mock() + mock(ANY) + mock.assert_called_with(ANY) + + mock = Mock() + mock(foo=ANY) + mock.assert_called_with(foo=ANY) + + def test_repr(self): + self.assertEqual(repr(ANY), '') + self.assertEqual(str(ANY), '') + + + def test_any_and_datetime(self): + mock = Mock() + mock(datetime.now(), foo=datetime.now()) + + mock.assert_called_with(ANY, foo=ANY) + + + def test_any_mock_calls_comparison_order(self): + mock = Mock() + d = datetime.now() + class Foo(object): + def __eq__(self, other): + return False + def __ne__(self, other): + return True + + for d in datetime.now(), Foo(): + mock.reset_mock() + + mock(d, foo=d, bar=d) + mock.method(d, zinga=d, alpha=d) + mock().method(a1=d, z99=d) + + expected = [ + call(ANY, foo=ANY, bar=ANY), + call.method(ANY, zinga=ANY, alpha=ANY), + call(), call().method(a1=ANY, z99=ANY) + ] + self.assertEqual(expected, mock.mock_calls) + self.assertEqual(mock.mock_calls, expected) + + + +class CallTest(unittest2.TestCase): + + def test_call_with_call(self): + kall = _Call() + self.assertEqual(kall, _Call()) + self.assertEqual(kall, _Call(('',))) + self.assertEqual(kall, _Call(((),))) + self.assertEqual(kall, _Call(({},))) + self.assertEqual(kall, _Call(('', ()))) + self.assertEqual(kall, _Call(('', {}))) + self.assertEqual(kall, _Call(('', (), {}))) + self.assertEqual(kall, _Call(('foo',))) + self.assertEqual(kall, _Call(('bar', ()))) + self.assertEqual(kall, _Call(('baz', {}))) + self.assertEqual(kall, _Call(('spam', (), {}))) + + kall = _Call(((1, 2, 3),)) + self.assertEqual(kall, _Call(((1, 2, 3),))) + self.assertEqual(kall, _Call(('', (1, 2, 3)))) + self.assertEqual(kall, _Call(((1, 2, 3), {}))) + self.assertEqual(kall, _Call(('', (1, 2, 3), {}))) + + kall = _Call(((1, 2, 4),)) + self.assertNotEqual(kall, _Call(('', (1, 2, 3)))) + self.assertNotEqual(kall, _Call(('', (1, 2, 3), {}))) + + kall = _Call(('foo', (1, 2, 4),)) + self.assertNotEqual(kall, _Call(('', (1, 2, 4)))) + self.assertNotEqual(kall, _Call(('', (1, 2, 4), {}))) + self.assertNotEqual(kall, _Call(('bar', (1, 2, 4)))) + self.assertNotEqual(kall, _Call(('bar', (1, 2, 4), {}))) + + kall = _Call(({'a': 3},)) + self.assertEqual(kall, _Call(('', (), {'a': 3}))) + self.assertEqual(kall, _Call(('', {'a': 3}))) + self.assertEqual(kall, _Call(((), {'a': 3}))) + self.assertEqual(kall, _Call(({'a': 3},))) + + + def test_empty__Call(self): + args = _Call() + + self.assertEqual(args, ()) + self.assertEqual(args, ('foo',)) + self.assertEqual(args, ((),)) + self.assertEqual(args, ('foo', ())) + self.assertEqual(args, ('foo',(), {})) + self.assertEqual(args, ('foo', {})) + self.assertEqual(args, ({},)) + + + def test_named_empty_call(self): + args = _Call(('foo', (), {})) + + self.assertEqual(args, ('foo',)) + self.assertEqual(args, ('foo', ())) + self.assertEqual(args, ('foo',(), {})) + self.assertEqual(args, ('foo', {})) + + self.assertNotEqual(args, ((),)) + self.assertNotEqual(args, ()) + self.assertNotEqual(args, ({},)) + self.assertNotEqual(args, ('bar',)) + self.assertNotEqual(args, ('bar', ())) + self.assertNotEqual(args, ('bar', {})) + + + def test_call_with_args(self): + args = _Call(((1, 2, 3), {})) + + self.assertEqual(args, ((1, 2, 3),)) + self.assertEqual(args, ('foo', (1, 2, 3))) + self.assertEqual(args, ('foo', (1, 2, 3), {})) + self.assertEqual(args, ((1, 2, 3), {})) + + + def test_named_call_with_args(self): + args = _Call(('foo', (1, 2, 3), {})) + + self.assertEqual(args, ('foo', (1, 2, 3))) + self.assertEqual(args, ('foo', (1, 2, 3), {})) + + self.assertNotEqual(args, ((1, 2, 3),)) + self.assertNotEqual(args, ((1, 2, 3), {})) + + + def test_call_with_kwargs(self): + args = _Call(((), dict(a=3, b=4))) + + self.assertEqual(args, (dict(a=3, b=4),)) + self.assertEqual(args, ('foo', dict(a=3, b=4))) + self.assertEqual(args, ('foo', (), dict(a=3, b=4))) + self.assertEqual(args, ((), dict(a=3, b=4))) + + + def test_named_call_with_kwargs(self): + args = _Call(('foo', (), dict(a=3, b=4))) + + self.assertEqual(args, ('foo', dict(a=3, b=4))) + self.assertEqual(args, ('foo', (), dict(a=3, b=4))) + + self.assertNotEqual(args, (dict(a=3, b=4),)) + self.assertNotEqual(args, ((), dict(a=3, b=4))) + + + def test_call_with_args_call_empty_name(self): + args = _Call(((1, 2, 3), {})) + self.assertEqual(args, call(1, 2, 3)) + self.assertEqual(call(1, 2, 3), args) + self.assertTrue(call(1, 2, 3) in [args]) + + + def test_call_ne(self): + self.assertNotEqual(_Call(((1, 2, 3),)), call(1, 2)) + self.assertFalse(_Call(((1, 2, 3),)) != call(1, 2, 3)) + self.assertTrue(_Call(((1, 2), {})) != call(1, 2, 3)) + + + def test_call_non_tuples(self): + kall = _Call(((1, 2, 3),)) + for value in 1, None, self, int: + self.assertNotEqual(kall, value) + self.assertFalse(kall == value) + + + def test_repr(self): + self.assertEqual(repr(_Call()), 'call()') + self.assertEqual(repr(_Call(('foo',))), 'call.foo()') + + self.assertEqual(repr(_Call(((1, 2, 3), {'a': 'b'}))), + "call(1, 2, 3, a='b')") + self.assertEqual(repr(_Call(('bar', (1, 2, 3), {'a': 'b'}))), + "call.bar(1, 2, 3, a='b')") + + self.assertEqual(repr(call), 'call') + self.assertEqual(str(call), 'call') + + self.assertEqual(repr(call()), 'call()') + self.assertEqual(repr(call(1)), 'call(1)') + self.assertEqual(repr(call(zz='thing')), "call(zz='thing')") + + self.assertEqual(repr(call().foo), 'call().foo') + self.assertEqual(repr(call(1).foo.bar(a=3).bing), + 'call().foo.bar().bing') + self.assertEqual( + repr(call().foo(1, 2, a=3)), + "call().foo(1, 2, a=3)" + ) + self.assertEqual(repr(call()()), "call()()") + self.assertEqual(repr(call(1)(2)), "call()(2)") + self.assertEqual( + repr(call()().bar().baz.beep(1)), + "call()().bar().baz.beep(1)" + ) + + + def test_call(self): + self.assertEqual(call(), ('', (), {})) + self.assertEqual(call('foo', 'bar', one=3, two=4), + ('', ('foo', 'bar'), {'one': 3, 'two': 4})) + + mock = Mock() + mock(1, 2, 3) + mock(a=3, b=6) + self.assertEqual(mock.call_args_list, + [call(1, 2, 3), call(a=3, b=6)]) + + def test_attribute_call(self): + self.assertEqual(call.foo(1), ('foo', (1,), {})) + self.assertEqual(call.bar.baz(fish='eggs'), + ('bar.baz', (), {'fish': 'eggs'})) + + mock = Mock() + mock.foo(1, 2 ,3) + mock.bar.baz(a=3, b=6) + self.assertEqual(mock.method_calls, + [call.foo(1, 2, 3), call.bar.baz(a=3, b=6)]) + + + def test_extended_call(self): + result = call(1).foo(2).bar(3, a=4) + self.assertEqual(result, ('().foo().bar', (3,), dict(a=4))) + + mock = MagicMock() + mock(1, 2, a=3, b=4) + self.assertEqual(mock.call_args, call(1, 2, a=3, b=4)) + self.assertNotEqual(mock.call_args, call(1, 2, 3)) + + self.assertEqual(mock.call_args_list, [call(1, 2, a=3, b=4)]) + self.assertEqual(mock.mock_calls, [call(1, 2, a=3, b=4)]) + + mock = MagicMock() + mock.foo(1).bar()().baz.beep(a=6) + + last_call = call.foo(1).bar()().baz.beep(a=6) + self.assertEqual(mock.mock_calls[-1], last_call) + self.assertEqual(mock.mock_calls, last_call.call_list()) + + + def test_call_list(self): + mock = MagicMock() + mock(1) + self.assertEqual(call(1).call_list(), mock.mock_calls) + + mock = MagicMock() + mock(1).method(2) + self.assertEqual(call(1).method(2).call_list(), + mock.mock_calls) + + mock = MagicMock() + mock(1).method(2)(3) + self.assertEqual(call(1).method(2)(3).call_list(), + mock.mock_calls) + + mock = MagicMock() + int(mock(1).method(2)(3).foo.bar.baz(4)(5)) + kall = call(1).method(2)(3).foo.bar.baz(4)(5).__int__() + self.assertEqual(kall.call_list(), mock.mock_calls) + + + def test_call_any(self): + self.assertEqual(call, ANY) + + m = MagicMock() + int(m) + self.assertEqual(m.mock_calls, [ANY]) + self.assertEqual([ANY], m.mock_calls) + + + def test_two_args_call(self): + args = _Call(((1, 2), {'a': 3}), two=True) + self.assertEqual(len(args), 2) + self.assertEqual(args[0], (1, 2)) + self.assertEqual(args[1], {'a': 3}) + + other_args = _Call(((1, 2), {'a': 3})) + self.assertEqual(args, other_args) + + +class SpecSignatureTest(unittest2.TestCase): + + def _check_someclass_mock(self, mock): + self.assertRaises(AttributeError, getattr, mock, 'foo') + mock.one(1, 2) + mock.one.assert_called_with(1, 2) + self.assertRaises(AssertionError, + mock.one.assert_called_with, 3, 4) + self.assertRaises(TypeError, mock.one, 1) + + mock.two() + mock.two.assert_called_with() + self.assertRaises(AssertionError, + mock.two.assert_called_with, 3) + self.assertRaises(TypeError, mock.two, 1) + + mock.three() + mock.three.assert_called_with() + self.assertRaises(AssertionError, + mock.three.assert_called_with, 3) + self.assertRaises(TypeError, mock.three, 3, 2) + + mock.three(1) + mock.three.assert_called_with(1) + + mock.three(a=1) + mock.three.assert_called_with(a=1) + + + def test_basic(self): + for spec in (SomeClass, SomeClass()): + mock = create_autospec(spec) + self._check_someclass_mock(mock) + + + def test_create_autospec_return_value(self): + def f(): + pass + mock = create_autospec(f, return_value='foo') + self.assertEqual(mock(), 'foo') + + class Foo(object): + pass + + mock = create_autospec(Foo, return_value='foo') + self.assertEqual(mock(), 'foo') + + + def test_autospec_reset_mock(self): + m = create_autospec(int) + int(m) + m.reset_mock() + self.assertEqual(m.__int__.call_count, 0) + + + def test_mocking_unbound_methods(self): + class Foo(object): + def foo(self, foo): + pass + p = patch.object(Foo, 'foo') + mock_foo = p.start() + Foo().foo(1) + + mock_foo.assert_called_with(1) + + + @unittest2.expectedFailure + def test_create_autospec_unbound_methods(self): + # see issue 128 + class Foo(object): + def foo(self): + pass + + klass = create_autospec(Foo) + instance = klass() + self.assertRaises(TypeError, instance.foo, 1) + + # Note: no type checking on the "self" parameter + klass.foo(1) + klass.foo.assert_called_with(1) + self.assertRaises(TypeError, klass.foo) + + + def test_create_autospec_keyword_arguments(self): + class Foo(object): + a = 3 + m = create_autospec(Foo, a='3') + self.assertEqual(m.a, '3') + + @unittest2.skipUnless(inPy3k, "Keyword only arguments Python 3 specific") + def test_create_autospec_keyword_only_arguments(self): + func_def = "def foo(a, *, b=None):\n pass\n" + namespace = {} + exec (func_def, namespace) + foo = namespace['foo'] + + m = create_autospec(foo) + m(1) + m.assert_called_with(1) + self.assertRaises(TypeError, m, 1, 2) + + m(2, b=3) + m.assert_called_with(2, b=3) + + def test_function_as_instance_attribute(self): + obj = SomeClass() + def f(a): + pass + obj.f = f + + mock = create_autospec(obj) + mock.f('bing') + mock.f.assert_called_with('bing') + + + def test_spec_as_list(self): + # because spec as a list of strings in the mock constructor means + # something very different we treat a list instance as the type. + mock = create_autospec([]) + mock.append('foo') + mock.append.assert_called_with('foo') + + self.assertRaises(AttributeError, getattr, mock, 'foo') + + class Foo(object): + foo = [] + + mock = create_autospec(Foo) + mock.foo.append(3) + mock.foo.append.assert_called_with(3) + self.assertRaises(AttributeError, getattr, mock.foo, 'foo') + + + def test_attributes(self): + class Sub(SomeClass): + attr = SomeClass() + + sub_mock = create_autospec(Sub) + + for mock in (sub_mock, sub_mock.attr): + self._check_someclass_mock(mock) + + + def test_builtin_functions_types(self): + # we could replace builtin functions / methods with a function + # with *args / **kwargs signature. Using the builtin method type + # as a spec seems to work fairly well though. + class BuiltinSubclass(list): + def bar(self, arg): + pass + sorted = sorted + attr = {} + + mock = create_autospec(BuiltinSubclass) + mock.append(3) + mock.append.assert_called_with(3) + self.assertRaises(AttributeError, getattr, mock.append, 'foo') + + mock.bar('foo') + mock.bar.assert_called_with('foo') + self.assertRaises(TypeError, mock.bar, 'foo', 'bar') + self.assertRaises(AttributeError, getattr, mock.bar, 'foo') + + mock.sorted([1, 2]) + mock.sorted.assert_called_with([1, 2]) + self.assertRaises(AttributeError, getattr, mock.sorted, 'foo') + + mock.attr.pop(3) + mock.attr.pop.assert_called_with(3) + self.assertRaises(AttributeError, getattr, mock.attr, 'foo') + + + def test_method_calls(self): + class Sub(SomeClass): + attr = SomeClass() + + mock = create_autospec(Sub) + mock.one(1, 2) + mock.two() + mock.three(3) + + expected = [call.one(1, 2), call.two(), call.three(3)] + self.assertEqual(mock.method_calls, expected) + + mock.attr.one(1, 2) + mock.attr.two() + mock.attr.three(3) + + expected.extend( + [call.attr.one(1, 2), call.attr.two(), call.attr.three(3)] + ) + self.assertEqual(mock.method_calls, expected) + + + def test_magic_methods(self): + class BuiltinSubclass(list): + attr = {} + + mock = create_autospec(BuiltinSubclass) + self.assertEqual(list(mock), []) + self.assertRaises(TypeError, int, mock) + self.assertRaises(TypeError, int, mock.attr) + self.assertEqual(list(mock), []) + + self.assertIsInstance(mock['foo'], MagicMock) + self.assertIsInstance(mock.attr['foo'], MagicMock) + + + def test_spec_set(self): + class Sub(SomeClass): + attr = SomeClass() + + for spec in (Sub, Sub()): + mock = create_autospec(spec, spec_set=True) + self._check_someclass_mock(mock) + + self.assertRaises(AttributeError, setattr, mock, 'foo', 'bar') + self.assertRaises(AttributeError, setattr, mock.attr, 'foo', 'bar') + + + def test_descriptors(self): + class Foo(object): + @classmethod + def f(cls, a, b): + pass + @staticmethod + def g(a, b): + pass + + class Bar(Foo): + pass + + class Baz(SomeClass, Bar): + pass + + for spec in (Foo, Foo(), Bar, Bar(), Baz, Baz()): + mock = create_autospec(spec) + mock.f(1, 2) + mock.f.assert_called_once_with(1, 2) + + mock.g(3, 4) + mock.g.assert_called_once_with(3, 4) + + + @unittest2.skipIf(inPy3k, "No old style classes in Python 3") + def test_old_style_classes(self): + class Foo: + def f(self, a, b): + pass + + class Bar(Foo): + g = Foo() + + for spec in (Foo, Foo(), Bar, Bar()): + mock = create_autospec(spec) + mock.f(1, 2) + mock.f.assert_called_once_with(1, 2) + + self.assertRaises(AttributeError, getattr, mock, 'foo') + self.assertRaises(AttributeError, getattr, mock.f, 'foo') + + mock.g.f(1, 2) + mock.g.f.assert_called_once_with(1, 2) + self.assertRaises(AttributeError, getattr, mock.g, 'foo') + + + def test_recursive(self): + class A(object): + def a(self): + pass + foo = 'foo bar baz' + bar = foo + + A.B = A + mock = create_autospec(A) + + mock() + self.assertFalse(mock.B.called) + + mock.a() + mock.B.a() + self.assertEqual(mock.method_calls, [call.a(), call.B.a()]) + + self.assertIs(A.foo, A.bar) + self.assertIsNot(mock.foo, mock.bar) + mock.foo.lower() + self.assertRaises(AssertionError, mock.bar.lower.assert_called_with) + + + def test_spec_inheritance_for_classes(self): + class Foo(object): + def a(self): + pass + class Bar(object): + def f(self): + pass + + class_mock = create_autospec(Foo) + + self.assertIsNot(class_mock, class_mock()) + + for this_mock in class_mock, class_mock(): + this_mock.a() + this_mock.a.assert_called_with() + self.assertRaises(TypeError, this_mock.a, 'foo') + self.assertRaises(AttributeError, getattr, this_mock, 'b') + + instance_mock = create_autospec(Foo()) + instance_mock.a() + instance_mock.a.assert_called_with() + self.assertRaises(TypeError, instance_mock.a, 'foo') + self.assertRaises(AttributeError, getattr, instance_mock, 'b') + + # The return value isn't isn't callable + self.assertRaises(TypeError, instance_mock) + + instance_mock.Bar.f() + instance_mock.Bar.f.assert_called_with() + self.assertRaises(AttributeError, getattr, instance_mock.Bar, 'g') + + instance_mock.Bar().f() + instance_mock.Bar().f.assert_called_with() + self.assertRaises(AttributeError, getattr, instance_mock.Bar(), 'g') + + + def test_inherit(self): + class Foo(object): + a = 3 + + Foo.Foo = Foo + + # class + mock = create_autospec(Foo) + instance = mock() + self.assertRaises(AttributeError, getattr, instance, 'b') + + attr_instance = mock.Foo() + self.assertRaises(AttributeError, getattr, attr_instance, 'b') + + # instance + mock = create_autospec(Foo()) + self.assertRaises(AttributeError, getattr, mock, 'b') + self.assertRaises(TypeError, mock) + + # attribute instance + call_result = mock.Foo() + self.assertRaises(AttributeError, getattr, call_result, 'b') + + + def test_builtins(self): + # used to fail with infinite recursion + create_autospec(1) + + create_autospec(int) + create_autospec('foo') + create_autospec(str) + create_autospec({}) + create_autospec(dict) + create_autospec([]) + create_autospec(list) + create_autospec(set()) + create_autospec(set) + create_autospec(1.0) + create_autospec(float) + create_autospec(1j) + create_autospec(complex) + create_autospec(False) + create_autospec(True) + + + def test_function(self): + def f(a, b): + pass + + mock = create_autospec(f) + self.assertRaises(TypeError, mock) + mock(1, 2) + mock.assert_called_with(1, 2) + + f.f = f + mock = create_autospec(f) + self.assertRaises(TypeError, mock.f) + mock.f(3, 4) + mock.f.assert_called_with(3, 4) + + + def test_skip_attributeerrors(self): + class Raiser(object): + def __get__(self, obj, type=None): + if obj is None: + raise AttributeError('Can only be accessed via an instance') + + class RaiserClass(object): + raiser = Raiser() + + @staticmethod + def existing(a, b): + return a + b + + s = create_autospec(RaiserClass) + self.assertRaises(TypeError, lambda x: s.existing(1, 2, 3)) + s.existing(1, 2) + self.assertRaises(AttributeError, lambda: s.nonexisting) + + # check we can fetch the raiser attribute and it has no spec + obj = s.raiser + obj.foo, obj.bar + + + def test_signature_class(self): + class Foo(object): + def __init__(self, a, b=3): + pass + + mock = create_autospec(Foo) + + self.assertRaises(TypeError, mock) + mock(1) + mock.assert_called_once_with(1) + + mock(4, 5) + mock.assert_called_with(4, 5) + + + @unittest2.skipIf(inPy3k, 'no old style classes in Python 3') + def test_signature_old_style_class(self): + class Foo: + def __init__(self, a, b=3): + pass + + mock = create_autospec(Foo) + + self.assertRaises(TypeError, mock) + mock(1) + mock.assert_called_once_with(1) + + mock(4, 5) + mock.assert_called_with(4, 5) + + + def test_class_with_no_init(self): + # this used to raise an exception + # due to trying to get a signature from object.__init__ + class Foo(object): + pass + create_autospec(Foo) + + + @unittest2.skipIf(inPy3k, 'no old style classes in Python 3') + def test_old_style_class_with_no_init(self): + # this used to raise an exception + # due to Foo.__init__ raising an AttributeError + class Foo: + pass + create_autospec(Foo) + + + def test_signature_callable(self): + class Callable(object): + def __init__(self): + pass + def __call__(self, a): + pass + + mock = create_autospec(Callable) + mock() + mock.assert_called_once_with() + self.assertRaises(TypeError, mock, 'a') + + instance = mock() + self.assertRaises(TypeError, instance) + instance(a='a') + instance.assert_called_once_with(a='a') + instance('a') + instance.assert_called_with('a') + + mock = create_autospec(Callable()) + mock(a='a') + mock.assert_called_once_with(a='a') + self.assertRaises(TypeError, mock) + mock('a') + mock.assert_called_with('a') + + + def test_signature_noncallable(self): + class NonCallable(object): + def __init__(self): + pass + + mock = create_autospec(NonCallable) + instance = mock() + mock.assert_called_once_with() + self.assertRaises(TypeError, mock, 'a') + self.assertRaises(TypeError, instance) + self.assertRaises(TypeError, instance, 'a') + + mock = create_autospec(NonCallable()) + self.assertRaises(TypeError, mock) + self.assertRaises(TypeError, mock, 'a') + + + def test_create_autospec_none(self): + class Foo(object): + bar = None + + mock = create_autospec(Foo) + none = mock.bar + self.assertNotIsInstance(none, type(None)) + + none.foo() + none.foo.assert_called_once_with() + + + def test_autospec_functions_with_self_in_odd_place(self): + class Foo(object): + def f(a, self): + pass + + a = create_autospec(Foo) + a.f(self=10) + a.f.assert_called_with(self=10) + + + def test_autospec_property(self): + class Foo(object): + @property + def foo(self): + return 3 + + foo = create_autospec(Foo) + mock_property = foo.foo + + # no spec on properties + self.assertTrue(isinstance(mock_property, MagicMock)) + mock_property(1, 2, 3) + mock_property.abc(4, 5, 6) + mock_property.assert_called_once_with(1, 2, 3) + mock_property.abc.assert_called_once_with(4, 5, 6) + + + def test_autospec_slots(self): + class Foo(object): + __slots__ = ['a'] + + foo = create_autospec(Foo) + mock_slot = foo.a + + # no spec on slots + mock_slot(1, 2, 3) + mock_slot.abc(4, 5, 6) + mock_slot.assert_called_once_with(1, 2, 3) + mock_slot.abc.assert_called_once_with(4, 5, 6) + + +class TestCallList(unittest2.TestCase): + + def test_args_list_contains_call_list(self): + mock = Mock() + self.assertIsInstance(mock.call_args_list, _CallList) + + mock(1, 2) + mock(a=3) + mock(3, 4) + mock(b=6) + + for kall in call(1, 2), call(a=3), call(3, 4), call(b=6): + self.assertTrue(kall in mock.call_args_list) + + calls = [call(a=3), call(3, 4)] + self.assertTrue(calls in mock.call_args_list) + calls = [call(1, 2), call(a=3)] + self.assertTrue(calls in mock.call_args_list) + calls = [call(3, 4), call(b=6)] + self.assertTrue(calls in mock.call_args_list) + calls = [call(3, 4)] + self.assertTrue(calls in mock.call_args_list) + + self.assertFalse(call('fish') in mock.call_args_list) + self.assertFalse([call('fish')] in mock.call_args_list) + + + def test_call_list_str(self): + mock = Mock() + mock(1, 2) + mock.foo(a=3) + mock.foo.bar().baz('fish', cat='dog') + + expected = ( + "[call(1, 2),\n" + " call.foo(a=3),\n" + " call.foo.bar(),\n" + " call.foo.bar().baz('fish', cat='dog')]" + ) + self.assertEqual(str(mock.mock_calls), expected) + + + def test_propertymock(self): + p = patch('%s.SomeClass.one' % __name__, new_callable=PropertyMock) + mock = p.start() + try: + SomeClass.one + mock.assert_called_once_with() + + s = SomeClass() + s.one + mock.assert_called_with() + self.assertEqual(mock.mock_calls, [call(), call()]) + + s.one = 3 + self.assertEqual(mock.mock_calls, [call(), call(), call(3)]) + finally: + p.stop() + + + def test_propertymock_returnvalue(self): + m = MagicMock() + p = PropertyMock() + type(m).foo = p + + returned = m.foo + p.assert_called_once_with() + self.assertIsInstance(returned, MagicMock) + self.assertNotIsInstance(returned, PropertyMock) + + +if __name__ == '__main__': + unittest2.main() diff --git a/python/mock-1.0.0/tests/testmagicmethods.py b/python/mock-1.0.0/tests/testmagicmethods.py new file mode 100644 index 000000000..ef0f16d82 --- /dev/null +++ b/python/mock-1.0.0/tests/testmagicmethods.py @@ -0,0 +1,486 @@ +# Copyright (C) 2007-2012 Michael Foord & the mock team +# E-mail: fuzzyman AT voidspace DOT org DOT uk +# http://www.voidspace.org.uk/python/mock/ + +from tests.support import unittest2, inPy3k + +try: + unicode +except NameError: + # Python 3 + unicode = str + long = int + +import inspect +import sys +from mock import Mock, MagicMock, _magics + + + +class TestMockingMagicMethods(unittest2.TestCase): + + def test_deleting_magic_methods(self): + mock = Mock() + self.assertFalse(hasattr(mock, '__getitem__')) + + mock.__getitem__ = Mock() + self.assertTrue(hasattr(mock, '__getitem__')) + + del mock.__getitem__ + self.assertFalse(hasattr(mock, '__getitem__')) + + + def test_magicmock_del(self): + mock = MagicMock() + # before using getitem + del mock.__getitem__ + self.assertRaises(TypeError, lambda: mock['foo']) + + mock = MagicMock() + # this time use it first + mock['foo'] + del mock.__getitem__ + self.assertRaises(TypeError, lambda: mock['foo']) + + + def test_magic_method_wrapping(self): + mock = Mock() + def f(self, name): + return self, 'fish' + + mock.__getitem__ = f + self.assertFalse(mock.__getitem__ is f) + self.assertEqual(mock['foo'], (mock, 'fish')) + self.assertEqual(mock.__getitem__('foo'), (mock, 'fish')) + + mock.__getitem__ = mock + self.assertTrue(mock.__getitem__ is mock) + + + def test_magic_methods_isolated_between_mocks(self): + mock1 = Mock() + mock2 = Mock() + + mock1.__iter__ = Mock(return_value=iter([])) + self.assertEqual(list(mock1), []) + self.assertRaises(TypeError, lambda: list(mock2)) + + + def test_repr(self): + mock = Mock() + self.assertEqual(repr(mock), "" % id(mock)) + mock.__repr__ = lambda s: 'foo' + self.assertEqual(repr(mock), 'foo') + + + def test_str(self): + mock = Mock() + self.assertEqual(str(mock), object.__str__(mock)) + mock.__str__ = lambda s: 'foo' + self.assertEqual(str(mock), 'foo') + + + @unittest2.skipIf(inPy3k, "no unicode in Python 3") + def test_unicode(self): + mock = Mock() + self.assertEqual(unicode(mock), unicode(str(mock))) + + mock.__unicode__ = lambda s: unicode('foo') + self.assertEqual(unicode(mock), unicode('foo')) + + + def test_dict_methods(self): + mock = Mock() + + self.assertRaises(TypeError, lambda: mock['foo']) + def _del(): + del mock['foo'] + def _set(): + mock['foo'] = 3 + self.assertRaises(TypeError, _del) + self.assertRaises(TypeError, _set) + + _dict = {} + def getitem(s, name): + return _dict[name] + def setitem(s, name, value): + _dict[name] = value + def delitem(s, name): + del _dict[name] + + mock.__setitem__ = setitem + mock.__getitem__ = getitem + mock.__delitem__ = delitem + + self.assertRaises(KeyError, lambda: mock['foo']) + mock['foo'] = 'bar' + self.assertEqual(_dict, {'foo': 'bar'}) + self.assertEqual(mock['foo'], 'bar') + del mock['foo'] + self.assertEqual(_dict, {}) + + + def test_numeric(self): + original = mock = Mock() + mock.value = 0 + + self.assertRaises(TypeError, lambda: mock + 3) + + def add(self, other): + mock.value += other + return self + mock.__add__ = add + self.assertEqual(mock + 3, mock) + self.assertEqual(mock.value, 3) + + del mock.__add__ + def iadd(mock): + mock += 3 + self.assertRaises(TypeError, iadd, mock) + mock.__iadd__ = add + mock += 6 + self.assertEqual(mock, original) + self.assertEqual(mock.value, 9) + + self.assertRaises(TypeError, lambda: 3 + mock) + mock.__radd__ = add + self.assertEqual(7 + mock, mock) + self.assertEqual(mock.value, 16) + + + @unittest2.skipIf(inPy3k, 'no truediv in Python 3') + def test_truediv(self): + mock = MagicMock() + mock.__truediv__.return_value = 6 + + context = {'mock': mock} + code = 'from __future__ import division\nresult = mock / 7\n' + exec(code, context) + self.assertEqual(context['result'], 6) + + mock.__rtruediv__.return_value = 3 + code = 'from __future__ import division\nresult = 2 / mock\n' + exec(code, context) + self.assertEqual(context['result'], 3) + + + @unittest2.skipIf(not inPy3k, 'truediv is available in Python 2') + def test_no_truediv(self): + self.assertRaises( + AttributeError, getattr, MagicMock(), '__truediv__' + ) + self.assertRaises( + AttributeError, getattr, MagicMock(), '__rtruediv__' + ) + + + def test_hash(self): + mock = Mock() + # test delegation + self.assertEqual(hash(mock), Mock.__hash__(mock)) + + def _hash(s): + return 3 + mock.__hash__ = _hash + self.assertEqual(hash(mock), 3) + + + def test_nonzero(self): + m = Mock() + self.assertTrue(bool(m)) + + nonzero = lambda s: False + if not inPy3k: + m.__nonzero__ = nonzero + else: + m.__bool__ = nonzero + + self.assertFalse(bool(m)) + + + def test_comparison(self): + # note: this test fails with Jython 2.5.1 due to a Jython bug + # it is fixed in jython 2.5.2 + if not inPy3k: + # incomparable in Python 3 + self. assertEqual(Mock() < 3, object() < 3) + self. assertEqual(Mock() > 3, object() > 3) + self. assertEqual(Mock() <= 3, object() <= 3) + self. assertEqual(Mock() >= 3, object() >= 3) + else: + self.assertRaises(TypeError, lambda: MagicMock() < object()) + self.assertRaises(TypeError, lambda: object() < MagicMock()) + self.assertRaises(TypeError, lambda: MagicMock() < MagicMock()) + self.assertRaises(TypeError, lambda: MagicMock() > object()) + self.assertRaises(TypeError, lambda: object() > MagicMock()) + self.assertRaises(TypeError, lambda: MagicMock() > MagicMock()) + self.assertRaises(TypeError, lambda: MagicMock() <= object()) + self.assertRaises(TypeError, lambda: object() <= MagicMock()) + self.assertRaises(TypeError, lambda: MagicMock() <= MagicMock()) + self.assertRaises(TypeError, lambda: MagicMock() >= object()) + self.assertRaises(TypeError, lambda: object() >= MagicMock()) + self.assertRaises(TypeError, lambda: MagicMock() >= MagicMock()) + + mock = Mock() + def comp(s, o): + return True + mock.__lt__ = mock.__gt__ = mock.__le__ = mock.__ge__ = comp + self. assertTrue(mock < 3) + self. assertTrue(mock > 3) + self. assertTrue(mock <= 3) + self. assertTrue(mock >= 3) + + + def test_equality(self): + for mock in Mock(), MagicMock(): + self.assertEqual(mock == mock, True) + self.assertIsInstance(mock == mock, bool) + self.assertEqual(mock != mock, False) + self.assertIsInstance(mock != mock, bool) + self.assertEqual(mock == object(), False) + self.assertEqual(mock != object(), True) + + def eq(self, other): + return other == 3 + mock.__eq__ = eq + self.assertTrue(mock == 3) + self.assertFalse(mock == 4) + + def ne(self, other): + return other == 3 + mock.__ne__ = ne + self.assertTrue(mock != 3) + self.assertFalse(mock != 4) + + mock = MagicMock() + mock.__eq__.return_value = True + self.assertIsInstance(mock == 3, bool) + self.assertEqual(mock == 3, True) + + mock.__ne__.return_value = False + self.assertIsInstance(mock != 3, bool) + self.assertEqual(mock != 3, False) + + + def test_len_contains_iter(self): + mock = Mock() + + self.assertRaises(TypeError, len, mock) + self.assertRaises(TypeError, iter, mock) + self.assertRaises(TypeError, lambda: 'foo' in mock) + + mock.__len__ = lambda s: 6 + self.assertEqual(len(mock), 6) + + mock.__contains__ = lambda s, o: o == 3 + self.assertTrue(3 in mock) + self.assertFalse(6 in mock) + + mock.__iter__ = lambda s: iter('foobarbaz') + self.assertEqual(list(mock), list('foobarbaz')) + + + def test_magicmock(self): + mock = MagicMock() + + mock.__iter__.return_value = iter([1, 2, 3]) + self.assertEqual(list(mock), [1, 2, 3]) + + name = '__nonzero__' + other = '__bool__' + if inPy3k: + name, other = other, name + getattr(mock, name).return_value = False + self.assertFalse(hasattr(mock, other)) + self.assertFalse(bool(mock)) + + for entry in _magics: + self.assertTrue(hasattr(mock, entry)) + self.assertFalse(hasattr(mock, '__imaginery__')) + + + def test_magic_mock_equality(self): + mock = MagicMock() + self.assertIsInstance(mock == object(), bool) + self.assertIsInstance(mock != object(), bool) + + self.assertEqual(mock == object(), False) + self.assertEqual(mock != object(), True) + self.assertEqual(mock == mock, True) + self.assertEqual(mock != mock, False) + + + def test_magicmock_defaults(self): + mock = MagicMock() + self.assertEqual(int(mock), 1) + self.assertEqual(complex(mock), 1j) + self.assertEqual(float(mock), 1.0) + self.assertEqual(long(mock), long(1)) + self.assertNotIn(object(), mock) + self.assertEqual(len(mock), 0) + self.assertEqual(list(mock), []) + self.assertEqual(hash(mock), object.__hash__(mock)) + self.assertEqual(str(mock), object.__str__(mock)) + self.assertEqual(unicode(mock), object.__str__(mock)) + self.assertIsInstance(unicode(mock), unicode) + self.assertTrue(bool(mock)) + if not inPy3k: + self.assertEqual(oct(mock), '1') + else: + # in Python 3 oct and hex use __index__ + # so these tests are for __index__ in py3k + self.assertEqual(oct(mock), '0o1') + self.assertEqual(hex(mock), '0x1') + # how to test __sizeof__ ? + + + @unittest2.skipIf(inPy3k, "no __cmp__ in Python 3") + def test_non_default_magic_methods(self): + mock = MagicMock() + self.assertRaises(AttributeError, lambda: mock.__cmp__) + + mock = Mock() + mock.__cmp__ = lambda s, o: 0 + + self.assertEqual(mock, object()) + + + def test_magic_methods_and_spec(self): + class Iterable(object): + def __iter__(self): + pass + + mock = Mock(spec=Iterable) + self.assertRaises(AttributeError, lambda: mock.__iter__) + + mock.__iter__ = Mock(return_value=iter([])) + self.assertEqual(list(mock), []) + + class NonIterable(object): + pass + mock = Mock(spec=NonIterable) + self.assertRaises(AttributeError, lambda: mock.__iter__) + + def set_int(): + mock.__int__ = Mock(return_value=iter([])) + self.assertRaises(AttributeError, set_int) + + mock = MagicMock(spec=Iterable) + self.assertEqual(list(mock), []) + self.assertRaises(AttributeError, set_int) + + + def test_magic_methods_and_spec_set(self): + class Iterable(object): + def __iter__(self): + pass + + mock = Mock(spec_set=Iterable) + self.assertRaises(AttributeError, lambda: mock.__iter__) + + mock.__iter__ = Mock(return_value=iter([])) + self.assertEqual(list(mock), []) + + class NonIterable(object): + pass + mock = Mock(spec_set=NonIterable) + self.assertRaises(AttributeError, lambda: mock.__iter__) + + def set_int(): + mock.__int__ = Mock(return_value=iter([])) + self.assertRaises(AttributeError, set_int) + + mock = MagicMock(spec_set=Iterable) + self.assertEqual(list(mock), []) + self.assertRaises(AttributeError, set_int) + + + def test_setting_unsupported_magic_method(self): + mock = MagicMock() + def set_setattr(): + mock.__setattr__ = lambda self, name: None + self.assertRaisesRegexp(AttributeError, + "Attempting to set unsupported magic method '__setattr__'.", + set_setattr + ) + + + def test_attributes_and_return_value(self): + mock = MagicMock() + attr = mock.foo + def _get_type(obj): + # the type of every mock (or magicmock) is a custom subclass + # so the real type is the second in the mro + return type(obj).__mro__[1] + self.assertEqual(_get_type(attr), MagicMock) + + returned = mock() + self.assertEqual(_get_type(returned), MagicMock) + + + def test_magic_methods_are_magic_mocks(self): + mock = MagicMock() + self.assertIsInstance(mock.__getitem__, MagicMock) + + mock[1][2].__getitem__.return_value = 3 + self.assertEqual(mock[1][2][3], 3) + + + def test_magic_method_reset_mock(self): + mock = MagicMock() + str(mock) + self.assertTrue(mock.__str__.called) + mock.reset_mock() + self.assertFalse(mock.__str__.called) + + + @unittest2.skipUnless(sys.version_info[:2] >= (2, 6), + "__dir__ not available until Python 2.6 or later") + def test_dir(self): + # overriding the default implementation + for mock in Mock(), MagicMock(): + def _dir(self): + return ['foo'] + mock.__dir__ = _dir + self.assertEqual(dir(mock), ['foo']) + + + @unittest2.skipIf('PyPy' in sys.version, "This fails differently on pypy") + def test_bound_methods(self): + m = Mock() + + # XXXX should this be an expected failure instead? + + # this seems like it should work, but is hard to do without introducing + # other api inconsistencies. Failure message could be better though. + m.__iter__ = [3].__iter__ + self.assertRaises(TypeError, iter, m) + + + def test_magic_method_type(self): + class Foo(MagicMock): + pass + + foo = Foo() + self.assertIsInstance(foo.__int__, Foo) + + + def test_descriptor_from_class(self): + m = MagicMock() + type(m).__str__.return_value = 'foo' + self.assertEqual(str(m), 'foo') + + + def test_iterable_as_iter_return_value(self): + m = MagicMock() + m.__iter__.return_value = [1, 2, 3] + self.assertEqual(list(m), [1, 2, 3]) + self.assertEqual(list(m), [1, 2, 3]) + + m.__iter__.return_value = iter([4, 5, 6]) + self.assertEqual(list(m), [4, 5, 6]) + self.assertEqual(list(m), []) + + +if __name__ == '__main__': + unittest2.main() diff --git a/python/mock-1.0.0/tests/testmock.py b/python/mock-1.0.0/tests/testmock.py new file mode 100644 index 000000000..f3ceea995 --- /dev/null +++ b/python/mock-1.0.0/tests/testmock.py @@ -0,0 +1,1351 @@ +# Copyright (C) 2007-2012 Michael Foord & the mock team +# E-mail: fuzzyman AT voidspace DOT org DOT uk +# http://www.voidspace.org.uk/python/mock/ + +from tests.support import ( + callable, unittest2, inPy3k, is_instance, next +) + +import copy +import pickle +import sys + +import mock +from mock import ( + call, DEFAULT, patch, sentinel, + MagicMock, Mock, NonCallableMock, + NonCallableMagicMock, _CallList, + create_autospec +) + + +try: + unicode +except NameError: + unicode = str + + +class Iter(object): + def __init__(self): + self.thing = iter(['this', 'is', 'an', 'iter']) + + def __iter__(self): + return self + + def next(self): + return next(self.thing) + + __next__ = next + + +class Subclass(MagicMock): + pass + + +class Thing(object): + attribute = 6 + foo = 'bar' + + + +class MockTest(unittest2.TestCase): + + def test_all(self): + # if __all__ is badly defined then import * will raise an error + # We have to exec it because you can't import * inside a method + # in Python 3 + exec("from mock import *") + + + def test_constructor(self): + mock = Mock() + + self.assertFalse(mock.called, "called not initialised correctly") + self.assertEqual(mock.call_count, 0, + "call_count not initialised correctly") + self.assertTrue(is_instance(mock.return_value, Mock), + "return_value not initialised correctly") + + self.assertEqual(mock.call_args, None, + "call_args not initialised correctly") + self.assertEqual(mock.call_args_list, [], + "call_args_list not initialised correctly") + self.assertEqual(mock.method_calls, [], + "method_calls not initialised correctly") + + # Can't use hasattr for this test as it always returns True on a mock + self.assertFalse('_items' in mock.__dict__, + "default mock should not have '_items' attribute") + + self.assertIsNone(mock._mock_parent, + "parent not initialised correctly") + self.assertIsNone(mock._mock_methods, + "methods not initialised correctly") + self.assertEqual(mock._mock_children, {}, + "children not initialised incorrectly") + + + def test_unicode_not_broken(self): + # This used to raise an exception with Python 2.5 and Mock 0.4 + unicode(Mock()) + + + def test_return_value_in_constructor(self): + mock = Mock(return_value=None) + self.assertIsNone(mock.return_value, + "return value in constructor not honoured") + + + def test_repr(self): + mock = Mock(name='foo') + self.assertIn('foo', repr(mock)) + self.assertIn("'%s'" % id(mock), repr(mock)) + + mocks = [(Mock(), 'mock'), (Mock(name='bar'), 'bar')] + for mock, name in mocks: + self.assertIn('%s.bar' % name, repr(mock.bar)) + self.assertIn('%s.foo()' % name, repr(mock.foo())) + self.assertIn('%s.foo().bing' % name, repr(mock.foo().bing)) + self.assertIn('%s()' % name, repr(mock())) + self.assertIn('%s()()' % name, repr(mock()())) + self.assertIn('%s()().foo.bar.baz().bing' % name, + repr(mock()().foo.bar.baz().bing)) + + + def test_repr_with_spec(self): + class X(object): + pass + + mock = Mock(spec=X) + self.assertIn(" spec='X' ", repr(mock)) + + mock = Mock(spec=X()) + self.assertIn(" spec='X' ", repr(mock)) + + mock = Mock(spec_set=X) + self.assertIn(" spec_set='X' ", repr(mock)) + + mock = Mock(spec_set=X()) + self.assertIn(" spec_set='X' ", repr(mock)) + + mock = Mock(spec=X, name='foo') + self.assertIn(" spec='X' ", repr(mock)) + self.assertIn(" name='foo' ", repr(mock)) + + mock = Mock(name='foo') + self.assertNotIn("spec", repr(mock)) + + mock = Mock() + self.assertNotIn("spec", repr(mock)) + + mock = Mock(spec=['foo']) + self.assertNotIn("spec", repr(mock)) + + + def test_side_effect(self): + mock = Mock() + + def effect(*args, **kwargs): + raise SystemError('kablooie') + + mock.side_effect = effect + self.assertRaises(SystemError, mock, 1, 2, fish=3) + mock.assert_called_with(1, 2, fish=3) + + results = [1, 2, 3] + def effect(): + return results.pop() + mock.side_effect = effect + + self.assertEqual([mock(), mock(), mock()], [3, 2, 1], + "side effect not used correctly") + + mock = Mock(side_effect=sentinel.SideEffect) + self.assertEqual(mock.side_effect, sentinel.SideEffect, + "side effect in constructor not used") + + def side_effect(): + return DEFAULT + mock = Mock(side_effect=side_effect, return_value=sentinel.RETURN) + self.assertEqual(mock(), sentinel.RETURN) + + + @unittest2.skipUnless('java' in sys.platform, + 'This test only applies to Jython') + def test_java_exception_side_effect(self): + import java + mock = Mock(side_effect=java.lang.RuntimeException("Boom!")) + + # can't use assertRaises with java exceptions + try: + mock(1, 2, fish=3) + except java.lang.RuntimeException: + pass + else: + self.fail('java exception not raised') + mock.assert_called_with(1,2, fish=3) + + + def test_reset_mock(self): + parent = Mock() + spec = ["something"] + mock = Mock(name="child", parent=parent, spec=spec) + mock(sentinel.Something, something=sentinel.SomethingElse) + something = mock.something + mock.something() + mock.side_effect = sentinel.SideEffect + return_value = mock.return_value + return_value() + + mock.reset_mock() + + self.assertEqual(mock._mock_name, "child", + "name incorrectly reset") + self.assertEqual(mock._mock_parent, parent, + "parent incorrectly reset") + self.assertEqual(mock._mock_methods, spec, + "methods incorrectly reset") + + self.assertFalse(mock.called, "called not reset") + self.assertEqual(mock.call_count, 0, "call_count not reset") + self.assertEqual(mock.call_args, None, "call_args not reset") + self.assertEqual(mock.call_args_list, [], "call_args_list not reset") + self.assertEqual(mock.method_calls, [], + "method_calls not initialised correctly: %r != %r" % + (mock.method_calls, [])) + self.assertEqual(mock.mock_calls, []) + + self.assertEqual(mock.side_effect, sentinel.SideEffect, + "side_effect incorrectly reset") + self.assertEqual(mock.return_value, return_value, + "return_value incorrectly reset") + self.assertFalse(return_value.called, "return value mock not reset") + self.assertEqual(mock._mock_children, {'something': something}, + "children reset incorrectly") + self.assertEqual(mock.something, something, + "children incorrectly cleared") + self.assertFalse(mock.something.called, "child not reset") + + + def test_reset_mock_recursion(self): + mock = Mock() + mock.return_value = mock + + # used to cause recursion + mock.reset_mock() + + + def test_call(self): + mock = Mock() + self.assertTrue(is_instance(mock.return_value, Mock), + "Default return_value should be a Mock") + + result = mock() + self.assertEqual(mock(), result, + "different result from consecutive calls") + mock.reset_mock() + + ret_val = mock(sentinel.Arg) + self.assertTrue(mock.called, "called not set") + self.assertEqual(mock.call_count, 1, "call_count incoreect") + self.assertEqual(mock.call_args, ((sentinel.Arg,), {}), + "call_args not set") + self.assertEqual(mock.call_args_list, [((sentinel.Arg,), {})], + "call_args_list not initialised correctly") + + mock.return_value = sentinel.ReturnValue + ret_val = mock(sentinel.Arg, key=sentinel.KeyArg) + self.assertEqual(ret_val, sentinel.ReturnValue, + "incorrect return value") + + self.assertEqual(mock.call_count, 2, "call_count incorrect") + self.assertEqual(mock.call_args, + ((sentinel.Arg,), {'key': sentinel.KeyArg}), + "call_args not set") + self.assertEqual(mock.call_args_list, [ + ((sentinel.Arg,), {}), + ((sentinel.Arg,), {'key': sentinel.KeyArg}) + ], + "call_args_list not set") + + + def test_call_args_comparison(self): + mock = Mock() + mock() + mock(sentinel.Arg) + mock(kw=sentinel.Kwarg) + mock(sentinel.Arg, kw=sentinel.Kwarg) + self.assertEqual(mock.call_args_list, [ + (), + ((sentinel.Arg,),), + ({"kw": sentinel.Kwarg},), + ((sentinel.Arg,), {"kw": sentinel.Kwarg}) + ]) + self.assertEqual(mock.call_args, + ((sentinel.Arg,), {"kw": sentinel.Kwarg})) + + + def test_assert_called_with(self): + mock = Mock() + mock() + + # Will raise an exception if it fails + mock.assert_called_with() + self.assertRaises(AssertionError, mock.assert_called_with, 1) + + mock.reset_mock() + self.assertRaises(AssertionError, mock.assert_called_with) + + mock(1, 2, 3, a='fish', b='nothing') + mock.assert_called_with(1, 2, 3, a='fish', b='nothing') + + + def test_assert_called_once_with(self): + mock = Mock() + mock() + + # Will raise an exception if it fails + mock.assert_called_once_with() + + mock() + self.assertRaises(AssertionError, mock.assert_called_once_with) + + mock.reset_mock() + self.assertRaises(AssertionError, mock.assert_called_once_with) + + mock('foo', 'bar', baz=2) + mock.assert_called_once_with('foo', 'bar', baz=2) + + mock.reset_mock() + mock('foo', 'bar', baz=2) + self.assertRaises( + AssertionError, + lambda: mock.assert_called_once_with('bob', 'bar', baz=2) + ) + + + def test_attribute_access_returns_mocks(self): + mock = Mock() + something = mock.something + self.assertTrue(is_instance(something, Mock), "attribute isn't a mock") + self.assertEqual(mock.something, something, + "different attributes returned for same name") + + # Usage example + mock = Mock() + mock.something.return_value = 3 + + self.assertEqual(mock.something(), 3, "method returned wrong value") + self.assertTrue(mock.something.called, + "method didn't record being called") + + + def test_attributes_have_name_and_parent_set(self): + mock = Mock() + something = mock.something + + self.assertEqual(something._mock_name, "something", + "attribute name not set correctly") + self.assertEqual(something._mock_parent, mock, + "attribute parent not set correctly") + + + def test_method_calls_recorded(self): + mock = Mock() + mock.something(3, fish=None) + mock.something_else.something(6, cake=sentinel.Cake) + + self.assertEqual(mock.something_else.method_calls, + [("something", (6,), {'cake': sentinel.Cake})], + "method calls not recorded correctly") + self.assertEqual(mock.method_calls, [ + ("something", (3,), {'fish': None}), + ("something_else.something", (6,), {'cake': sentinel.Cake}) + ], + "method calls not recorded correctly") + + + def test_method_calls_compare_easily(self): + mock = Mock() + mock.something() + self.assertEqual(mock.method_calls, [('something',)]) + self.assertEqual(mock.method_calls, [('something', (), {})]) + + mock = Mock() + mock.something('different') + self.assertEqual(mock.method_calls, [('something', ('different',))]) + self.assertEqual(mock.method_calls, + [('something', ('different',), {})]) + + mock = Mock() + mock.something(x=1) + self.assertEqual(mock.method_calls, [('something', {'x': 1})]) + self.assertEqual(mock.method_calls, [('something', (), {'x': 1})]) + + mock = Mock() + mock.something('different', some='more') + self.assertEqual(mock.method_calls, [ + ('something', ('different',), {'some': 'more'}) + ]) + + + def test_only_allowed_methods_exist(self): + for spec in ['something'], ('something',): + for arg in 'spec', 'spec_set': + mock = Mock(**{arg: spec}) + + # this should be allowed + mock.something + self.assertRaisesRegexp( + AttributeError, + "Mock object has no attribute 'something_else'", + getattr, mock, 'something_else' + ) + + + def test_from_spec(self): + class Something(object): + x = 3 + __something__ = None + def y(self): + pass + + def test_attributes(mock): + # should work + mock.x + mock.y + mock.__something__ + self.assertRaisesRegexp( + AttributeError, + "Mock object has no attribute 'z'", + getattr, mock, 'z' + ) + self.assertRaisesRegexp( + AttributeError, + "Mock object has no attribute '__foobar__'", + getattr, mock, '__foobar__' + ) + + test_attributes(Mock(spec=Something)) + test_attributes(Mock(spec=Something())) + + + def test_wraps_calls(self): + real = Mock() + + mock = Mock(wraps=real) + self.assertEqual(mock(), real()) + + real.reset_mock() + + mock(1, 2, fish=3) + real.assert_called_with(1, 2, fish=3) + + + def test_wraps_call_with_nondefault_return_value(self): + real = Mock() + + mock = Mock(wraps=real) + mock.return_value = 3 + + self.assertEqual(mock(), 3) + self.assertFalse(real.called) + + + def test_wraps_attributes(self): + class Real(object): + attribute = Mock() + + real = Real() + + mock = Mock(wraps=real) + self.assertEqual(mock.attribute(), real.attribute()) + self.assertRaises(AttributeError, lambda: mock.fish) + + self.assertNotEqual(mock.attribute, real.attribute) + result = mock.attribute.frog(1, 2, fish=3) + Real.attribute.frog.assert_called_with(1, 2, fish=3) + self.assertEqual(result, Real.attribute.frog()) + + + def test_exceptional_side_effect(self): + mock = Mock(side_effect=AttributeError) + self.assertRaises(AttributeError, mock) + + mock = Mock(side_effect=AttributeError('foo')) + self.assertRaises(AttributeError, mock) + + + def test_baseexceptional_side_effect(self): + mock = Mock(side_effect=KeyboardInterrupt) + self.assertRaises(KeyboardInterrupt, mock) + + mock = Mock(side_effect=KeyboardInterrupt('foo')) + self.assertRaises(KeyboardInterrupt, mock) + + + def test_assert_called_with_message(self): + mock = Mock() + self.assertRaisesRegexp(AssertionError, 'Not called', + mock.assert_called_with) + + + def test__name__(self): + mock = Mock() + self.assertRaises(AttributeError, lambda: mock.__name__) + + mock.__name__ = 'foo' + self.assertEqual(mock.__name__, 'foo') + + + def test_spec_list_subclass(self): + class Sub(list): + pass + mock = Mock(spec=Sub(['foo'])) + + mock.append(3) + mock.append.assert_called_with(3) + self.assertRaises(AttributeError, getattr, mock, 'foo') + + + def test_spec_class(self): + class X(object): + pass + + mock = Mock(spec=X) + self.assertTrue(isinstance(mock, X)) + + mock = Mock(spec=X()) + self.assertTrue(isinstance(mock, X)) + + self.assertIs(mock.__class__, X) + self.assertEqual(Mock().__class__.__name__, 'Mock') + + mock = Mock(spec_set=X) + self.assertTrue(isinstance(mock, X)) + + mock = Mock(spec_set=X()) + self.assertTrue(isinstance(mock, X)) + + + def test_setting_attribute_with_spec_set(self): + class X(object): + y = 3 + + mock = Mock(spec=X) + mock.x = 'foo' + + mock = Mock(spec_set=X) + def set_attr(): + mock.x = 'foo' + + mock.y = 'foo' + self.assertRaises(AttributeError, set_attr) + + + def test_copy(self): + current = sys.getrecursionlimit() + self.addCleanup(sys.setrecursionlimit, current) + + # can't use sys.maxint as this doesn't exist in Python 3 + sys.setrecursionlimit(int(10e8)) + # this segfaults without the fix in place + copy.copy(Mock()) + + + @unittest2.skipIf(inPy3k, "no old style classes in Python 3") + def test_spec_old_style_classes(self): + class Foo: + bar = 7 + + mock = Mock(spec=Foo) + mock.bar = 6 + self.assertRaises(AttributeError, lambda: mock.foo) + + mock = Mock(spec=Foo()) + mock.bar = 6 + self.assertRaises(AttributeError, lambda: mock.foo) + + + @unittest2.skipIf(inPy3k, "no old style classes in Python 3") + def test_spec_set_old_style_classes(self): + class Foo: + bar = 7 + + mock = Mock(spec_set=Foo) + mock.bar = 6 + self.assertRaises(AttributeError, lambda: mock.foo) + + def _set(): + mock.foo = 3 + self.assertRaises(AttributeError, _set) + + mock = Mock(spec_set=Foo()) + mock.bar = 6 + self.assertRaises(AttributeError, lambda: mock.foo) + + def _set(): + mock.foo = 3 + self.assertRaises(AttributeError, _set) + + + def test_subclass_with_properties(self): + class SubClass(Mock): + def _get(self): + return 3 + def _set(self, value): + raise NameError('strange error') + some_attribute = property(_get, _set) + + s = SubClass(spec_set=SubClass) + self.assertEqual(s.some_attribute, 3) + + def test(): + s.some_attribute = 3 + self.assertRaises(NameError, test) + + def test(): + s.foo = 'bar' + self.assertRaises(AttributeError, test) + + + def test_setting_call(self): + mock = Mock() + def __call__(self, a): + return self._mock_call(a) + + type(mock).__call__ = __call__ + mock('one') + mock.assert_called_with('one') + + self.assertRaises(TypeError, mock, 'one', 'two') + + + @unittest2.skipUnless(sys.version_info[:2] >= (2, 6), + "__dir__ not available until Python 2.6 or later") + def test_dir(self): + mock = Mock() + attrs = set(dir(mock)) + type_attrs = set([m for m in dir(Mock) if not m.startswith('_')]) + + # all public attributes from the type are included + self.assertEqual(set(), type_attrs - attrs) + + # creates these attributes + mock.a, mock.b + self.assertIn('a', dir(mock)) + self.assertIn('b', dir(mock)) + + # instance attributes + mock.c = mock.d = None + self.assertIn('c', dir(mock)) + self.assertIn('d', dir(mock)) + + # magic methods + mock.__iter__ = lambda s: iter([]) + self.assertIn('__iter__', dir(mock)) + + + @unittest2.skipUnless(sys.version_info[:2] >= (2, 6), + "__dir__ not available until Python 2.6 or later") + def test_dir_from_spec(self): + mock = Mock(spec=unittest2.TestCase) + testcase_attrs = set(dir(unittest2.TestCase)) + attrs = set(dir(mock)) + + # all attributes from the spec are included + self.assertEqual(set(), testcase_attrs - attrs) + + # shadow a sys attribute + mock.version = 3 + self.assertEqual(dir(mock).count('version'), 1) + + + @unittest2.skipUnless(sys.version_info[:2] >= (2, 6), + "__dir__ not available until Python 2.6 or later") + def test_filter_dir(self): + patcher = patch.object(mock, 'FILTER_DIR', False) + patcher.start() + try: + attrs = set(dir(Mock())) + type_attrs = set(dir(Mock)) + + # ALL attributes from the type are included + self.assertEqual(set(), type_attrs - attrs) + finally: + patcher.stop() + + + def test_configure_mock(self): + mock = Mock(foo='bar') + self.assertEqual(mock.foo, 'bar') + + mock = MagicMock(foo='bar') + self.assertEqual(mock.foo, 'bar') + + kwargs = {'side_effect': KeyError, 'foo.bar.return_value': 33, + 'foo': MagicMock()} + mock = Mock(**kwargs) + self.assertRaises(KeyError, mock) + self.assertEqual(mock.foo.bar(), 33) + self.assertIsInstance(mock.foo, MagicMock) + + mock = Mock() + mock.configure_mock(**kwargs) + self.assertRaises(KeyError, mock) + self.assertEqual(mock.foo.bar(), 33) + self.assertIsInstance(mock.foo, MagicMock) + + + def assertRaisesWithMsg(self, exception, message, func, *args, **kwargs): + # needed because assertRaisesRegex doesn't work easily with newlines + try: + func(*args, **kwargs) + except: + instance = sys.exc_info()[1] + self.assertIsInstance(instance, exception) + else: + self.fail('Exception %r not raised' % (exception,)) + + msg = str(instance) + self.assertEqual(msg, message) + + + def test_assert_called_with_failure_message(self): + mock = NonCallableMock() + + expected = "mock(1, '2', 3, bar='foo')" + message = 'Expected call: %s\nNot called' + self.assertRaisesWithMsg( + AssertionError, message % (expected,), + mock.assert_called_with, 1, '2', 3, bar='foo' + ) + + mock.foo(1, '2', 3, foo='foo') + + + asserters = [ + mock.foo.assert_called_with, mock.foo.assert_called_once_with + ] + for meth in asserters: + actual = "foo(1, '2', 3, foo='foo')" + expected = "foo(1, '2', 3, bar='foo')" + message = 'Expected call: %s\nActual call: %s' + self.assertRaisesWithMsg( + AssertionError, message % (expected, actual), + meth, 1, '2', 3, bar='foo' + ) + + # just kwargs + for meth in asserters: + actual = "foo(1, '2', 3, foo='foo')" + expected = "foo(bar='foo')" + message = 'Expected call: %s\nActual call: %s' + self.assertRaisesWithMsg( + AssertionError, message % (expected, actual), + meth, bar='foo' + ) + + # just args + for meth in asserters: + actual = "foo(1, '2', 3, foo='foo')" + expected = "foo(1, 2, 3)" + message = 'Expected call: %s\nActual call: %s' + self.assertRaisesWithMsg( + AssertionError, message % (expected, actual), + meth, 1, 2, 3 + ) + + # empty + for meth in asserters: + actual = "foo(1, '2', 3, foo='foo')" + expected = "foo()" + message = 'Expected call: %s\nActual call: %s' + self.assertRaisesWithMsg( + AssertionError, message % (expected, actual), meth + ) + + + def test_mock_calls(self): + mock = MagicMock() + + # need to do this because MagicMock.mock_calls used to just return + # a MagicMock which also returned a MagicMock when __eq__ was called + self.assertIs(mock.mock_calls == [], True) + + mock = MagicMock() + mock() + expected = [('', (), {})] + self.assertEqual(mock.mock_calls, expected) + + mock.foo() + expected.append(call.foo()) + self.assertEqual(mock.mock_calls, expected) + # intermediate mock_calls work too + self.assertEqual(mock.foo.mock_calls, [('', (), {})]) + + mock = MagicMock() + mock().foo(1, 2, 3, a=4, b=5) + expected = [ + ('', (), {}), ('().foo', (1, 2, 3), dict(a=4, b=5)) + ] + self.assertEqual(mock.mock_calls, expected) + self.assertEqual(mock.return_value.foo.mock_calls, + [('', (1, 2, 3), dict(a=4, b=5))]) + self.assertEqual(mock.return_value.mock_calls, + [('foo', (1, 2, 3), dict(a=4, b=5))]) + + mock = MagicMock() + mock().foo.bar().baz() + expected = [ + ('', (), {}), ('().foo.bar', (), {}), + ('().foo.bar().baz', (), {}) + ] + self.assertEqual(mock.mock_calls, expected) + self.assertEqual(mock().mock_calls, + call.foo.bar().baz().call_list()) + + for kwargs in dict(), dict(name='bar'): + mock = MagicMock(**kwargs) + int(mock.foo) + expected = [('foo.__int__', (), {})] + self.assertEqual(mock.mock_calls, expected) + + mock = MagicMock(**kwargs) + mock.a()() + expected = [('a', (), {}), ('a()', (), {})] + self.assertEqual(mock.mock_calls, expected) + self.assertEqual(mock.a().mock_calls, [call()]) + + mock = MagicMock(**kwargs) + mock(1)(2)(3) + self.assertEqual(mock.mock_calls, call(1)(2)(3).call_list()) + self.assertEqual(mock().mock_calls, call(2)(3).call_list()) + self.assertEqual(mock()().mock_calls, call(3).call_list()) + + mock = MagicMock(**kwargs) + mock(1)(2)(3).a.b.c(4) + self.assertEqual(mock.mock_calls, + call(1)(2)(3).a.b.c(4).call_list()) + self.assertEqual(mock().mock_calls, + call(2)(3).a.b.c(4).call_list()) + self.assertEqual(mock()().mock_calls, + call(3).a.b.c(4).call_list()) + + mock = MagicMock(**kwargs) + int(mock().foo.bar().baz()) + last_call = ('().foo.bar().baz().__int__', (), {}) + self.assertEqual(mock.mock_calls[-1], last_call) + self.assertEqual(mock().mock_calls, + call.foo.bar().baz().__int__().call_list()) + self.assertEqual(mock().foo.bar().mock_calls, + call.baz().__int__().call_list()) + self.assertEqual(mock().foo.bar().baz.mock_calls, + call().__int__().call_list()) + + + def test_subclassing(self): + class Subclass(Mock): + pass + + mock = Subclass() + self.assertIsInstance(mock.foo, Subclass) + self.assertIsInstance(mock(), Subclass) + + class Subclass(Mock): + def _get_child_mock(self, **kwargs): + return Mock(**kwargs) + + mock = Subclass() + self.assertNotIsInstance(mock.foo, Subclass) + self.assertNotIsInstance(mock(), Subclass) + + + def test_arg_lists(self): + mocks = [ + Mock(), + MagicMock(), + NonCallableMock(), + NonCallableMagicMock() + ] + + def assert_attrs(mock): + names = 'call_args_list', 'method_calls', 'mock_calls' + for name in names: + attr = getattr(mock, name) + self.assertIsInstance(attr, _CallList) + self.assertIsInstance(attr, list) + self.assertEqual(attr, []) + + for mock in mocks: + assert_attrs(mock) + + if callable(mock): + mock() + mock(1, 2) + mock(a=3) + + mock.reset_mock() + assert_attrs(mock) + + mock.foo() + mock.foo.bar(1, a=3) + mock.foo(1).bar().baz(3) + + mock.reset_mock() + assert_attrs(mock) + + + def test_call_args_two_tuple(self): + mock = Mock() + mock(1, a=3) + mock(2, b=4) + + self.assertEqual(len(mock.call_args), 2) + args, kwargs = mock.call_args + self.assertEqual(args, (2,)) + self.assertEqual(kwargs, dict(b=4)) + + expected_list = [((1,), dict(a=3)), ((2,), dict(b=4))] + for expected, call_args in zip(expected_list, mock.call_args_list): + self.assertEqual(len(call_args), 2) + self.assertEqual(expected[0], call_args[0]) + self.assertEqual(expected[1], call_args[1]) + + + def test_side_effect_iterator(self): + mock = Mock(side_effect=iter([1, 2, 3])) + self.assertEqual([mock(), mock(), mock()], [1, 2, 3]) + self.assertRaises(StopIteration, mock) + + mock = MagicMock(side_effect=['a', 'b', 'c']) + self.assertEqual([mock(), mock(), mock()], ['a', 'b', 'c']) + self.assertRaises(StopIteration, mock) + + mock = Mock(side_effect='ghi') + self.assertEqual([mock(), mock(), mock()], ['g', 'h', 'i']) + self.assertRaises(StopIteration, mock) + + class Foo(object): + pass + mock = MagicMock(side_effect=Foo) + self.assertIsInstance(mock(), Foo) + + mock = Mock(side_effect=Iter()) + self.assertEqual([mock(), mock(), mock(), mock()], + ['this', 'is', 'an', 'iter']) + self.assertRaises(StopIteration, mock) + + + def test_side_effect_setting_iterator(self): + mock = Mock() + mock.side_effect = iter([1, 2, 3]) + self.assertEqual([mock(), mock(), mock()], [1, 2, 3]) + self.assertRaises(StopIteration, mock) + side_effect = mock.side_effect + self.assertIsInstance(side_effect, type(iter([]))) + + mock.side_effect = ['a', 'b', 'c'] + self.assertEqual([mock(), mock(), mock()], ['a', 'b', 'c']) + self.assertRaises(StopIteration, mock) + side_effect = mock.side_effect + self.assertIsInstance(side_effect, type(iter([]))) + + this_iter = Iter() + mock.side_effect = this_iter + self.assertEqual([mock(), mock(), mock(), mock()], + ['this', 'is', 'an', 'iter']) + self.assertRaises(StopIteration, mock) + self.assertIs(mock.side_effect, this_iter) + + + def test_side_effect_iterator_exceptions(self): + for Klass in Mock, MagicMock: + iterable = (ValueError, 3, KeyError, 6) + m = Klass(side_effect=iterable) + self.assertRaises(ValueError, m) + self.assertEqual(m(), 3) + self.assertRaises(KeyError, m) + self.assertEqual(m(), 6) + + + def test_assert_has_calls_any_order(self): + mock = Mock() + mock(1, 2) + mock(a=3) + mock(3, 4) + mock(b=6) + mock(b=6) + + kalls = [ + call(1, 2), ({'a': 3},), + ((3, 4),), ((), {'a': 3}), + ('', (1, 2)), ('', {'a': 3}), + ('', (1, 2), {}), ('', (), {'a': 3}) + ] + for kall in kalls: + mock.assert_has_calls([kall], any_order=True) + + for kall in call(1, '2'), call(b=3), call(), 3, None, 'foo': + self.assertRaises( + AssertionError, mock.assert_has_calls, + [kall], any_order=True + ) + + kall_lists = [ + [call(1, 2), call(b=6)], + [call(3, 4), call(1, 2)], + [call(b=6), call(b=6)], + ] + + for kall_list in kall_lists: + mock.assert_has_calls(kall_list, any_order=True) + + kall_lists = [ + [call(b=6), call(b=6), call(b=6)], + [call(1, 2), call(1, 2)], + [call(3, 4), call(1, 2), call(5, 7)], + [call(b=6), call(3, 4), call(b=6), call(1, 2), call(b=6)], + ] + for kall_list in kall_lists: + self.assertRaises( + AssertionError, mock.assert_has_calls, + kall_list, any_order=True + ) + + def test_assert_has_calls(self): + kalls1 = [ + call(1, 2), ({'a': 3},), + ((3, 4),), call(b=6), + ('', (1,), {'b': 6}), + ] + kalls2 = [call.foo(), call.bar(1)] + kalls2.extend(call.spam().baz(a=3).call_list()) + kalls2.extend(call.bam(set(), foo={}).fish([1]).call_list()) + + mocks = [] + for mock in Mock(), MagicMock(): + mock(1, 2) + mock(a=3) + mock(3, 4) + mock(b=6) + mock(1, b=6) + mocks.append((mock, kalls1)) + + mock = Mock() + mock.foo() + mock.bar(1) + mock.spam().baz(a=3) + mock.bam(set(), foo={}).fish([1]) + mocks.append((mock, kalls2)) + + for mock, kalls in mocks: + for i in range(len(kalls)): + for step in 1, 2, 3: + these = kalls[i:i+step] + mock.assert_has_calls(these) + + if len(these) > 1: + self.assertRaises( + AssertionError, + mock.assert_has_calls, + list(reversed(these)) + ) + + + def test_assert_any_call(self): + mock = Mock() + mock(1, 2) + mock(a=3) + mock(1, b=6) + + mock.assert_any_call(1, 2) + mock.assert_any_call(a=3) + mock.assert_any_call(1, b=6) + + self.assertRaises( + AssertionError, + mock.assert_any_call + ) + self.assertRaises( + AssertionError, + mock.assert_any_call, + 1, 3 + ) + self.assertRaises( + AssertionError, + mock.assert_any_call, + a=4 + ) + + + def test_mock_calls_create_autospec(self): + def f(a, b): + pass + obj = Iter() + obj.f = f + + funcs = [ + create_autospec(f), + create_autospec(obj).f + ] + for func in funcs: + func(1, 2) + func(3, 4) + + self.assertEqual( + func.mock_calls, [call(1, 2), call(3, 4)] + ) + + + def test_mock_add_spec(self): + class _One(object): + one = 1 + class _Two(object): + two = 2 + class Anything(object): + one = two = three = 'four' + + klasses = [ + Mock, MagicMock, NonCallableMock, NonCallableMagicMock + ] + for Klass in list(klasses): + klasses.append(lambda K=Klass: K(spec=Anything)) + klasses.append(lambda K=Klass: K(spec_set=Anything)) + + for Klass in klasses: + for kwargs in dict(), dict(spec_set=True): + mock = Klass() + #no error + mock.one, mock.two, mock.three + + for One, Two in [(_One, _Two), (['one'], ['two'])]: + for kwargs in dict(), dict(spec_set=True): + mock.mock_add_spec(One, **kwargs) + + mock.one + self.assertRaises( + AttributeError, getattr, mock, 'two' + ) + self.assertRaises( + AttributeError, getattr, mock, 'three' + ) + if 'spec_set' in kwargs: + self.assertRaises( + AttributeError, setattr, mock, 'three', None + ) + + mock.mock_add_spec(Two, **kwargs) + self.assertRaises( + AttributeError, getattr, mock, 'one' + ) + mock.two + self.assertRaises( + AttributeError, getattr, mock, 'three' + ) + if 'spec_set' in kwargs: + self.assertRaises( + AttributeError, setattr, mock, 'three', None + ) + # note that creating a mock, setting an instance attribute, and + # *then* setting a spec doesn't work. Not the intended use case + + + def test_mock_add_spec_magic_methods(self): + for Klass in MagicMock, NonCallableMagicMock: + mock = Klass() + int(mock) + + mock.mock_add_spec(object) + self.assertRaises(TypeError, int, mock) + + mock = Klass() + mock['foo'] + mock.__int__.return_value =4 + + mock.mock_add_spec(int) + self.assertEqual(int(mock), 4) + self.assertRaises(TypeError, lambda: mock['foo']) + + + def test_adding_child_mock(self): + for Klass in NonCallableMock, Mock, MagicMock, NonCallableMagicMock: + mock = Klass() + + mock.foo = Mock() + mock.foo() + + self.assertEqual(mock.method_calls, [call.foo()]) + self.assertEqual(mock.mock_calls, [call.foo()]) + + mock = Klass() + mock.bar = Mock(name='name') + mock.bar() + self.assertEqual(mock.method_calls, []) + self.assertEqual(mock.mock_calls, []) + + # mock with an existing _new_parent but no name + mock = Klass() + mock.baz = MagicMock()() + mock.baz() + self.assertEqual(mock.method_calls, []) + self.assertEqual(mock.mock_calls, []) + + + def test_adding_return_value_mock(self): + for Klass in Mock, MagicMock: + mock = Klass() + mock.return_value = MagicMock() + + mock()() + self.assertEqual(mock.mock_calls, [call(), call()()]) + + + def test_manager_mock(self): + class Foo(object): + one = 'one' + two = 'two' + manager = Mock() + p1 = patch.object(Foo, 'one') + p2 = patch.object(Foo, 'two') + + mock_one = p1.start() + self.addCleanup(p1.stop) + mock_two = p2.start() + self.addCleanup(p2.stop) + + manager.attach_mock(mock_one, 'one') + manager.attach_mock(mock_two, 'two') + + Foo.two() + Foo.one() + + self.assertEqual(manager.mock_calls, [call.two(), call.one()]) + + + def test_magic_methods_mock_calls(self): + for Klass in Mock, MagicMock: + m = Klass() + m.__int__ = Mock(return_value=3) + m.__float__ = MagicMock(return_value=3.0) + int(m) + float(m) + + self.assertEqual(m.mock_calls, [call.__int__(), call.__float__()]) + self.assertEqual(m.method_calls, []) + + + def test_attribute_deletion(self): + # this behaviour isn't *useful*, but at least it's now tested... + for Klass in Mock, MagicMock, NonCallableMagicMock, NonCallableMock: + m = Klass() + original = m.foo + m.foo = 3 + del m.foo + self.assertEqual(m.foo, original) + + new = m.foo = Mock() + del m.foo + self.assertEqual(m.foo, new) + + + def test_mock_parents(self): + for Klass in Mock, MagicMock: + m = Klass() + original_repr = repr(m) + m.return_value = m + self.assertIs(m(), m) + self.assertEqual(repr(m), original_repr) + + m.reset_mock() + self.assertIs(m(), m) + self.assertEqual(repr(m), original_repr) + + m = Klass() + m.b = m.a + self.assertIn("name='mock.a'", repr(m.b)) + self.assertIn("name='mock.a'", repr(m.a)) + m.reset_mock() + self.assertIn("name='mock.a'", repr(m.b)) + self.assertIn("name='mock.a'", repr(m.a)) + + m = Klass() + original_repr = repr(m) + m.a = m() + m.a.return_value = m + + self.assertEqual(repr(m), original_repr) + self.assertEqual(repr(m.a()), original_repr) + + + def test_attach_mock(self): + classes = Mock, MagicMock, NonCallableMagicMock, NonCallableMock + for Klass in classes: + for Klass2 in classes: + m = Klass() + + m2 = Klass2(name='foo') + m.attach_mock(m2, 'bar') + + self.assertIs(m.bar, m2) + self.assertIn("name='mock.bar'", repr(m2)) + + m.bar.baz(1) + self.assertEqual(m.mock_calls, [call.bar.baz(1)]) + self.assertEqual(m.method_calls, [call.bar.baz(1)]) + + + def test_attach_mock_return_value(self): + classes = Mock, MagicMock, NonCallableMagicMock, NonCallableMock + for Klass in Mock, MagicMock: + for Klass2 in classes: + m = Klass() + + m2 = Klass2(name='foo') + m.attach_mock(m2, 'return_value') + + self.assertIs(m(), m2) + self.assertIn("name='mock()'", repr(m2)) + + m2.foo() + self.assertEqual(m.mock_calls, call().foo().call_list()) + + + def test_attribute_deletion(self): + for mock in Mock(), MagicMock(): + self.assertTrue(hasattr(mock, 'm')) + + del mock.m + self.assertFalse(hasattr(mock, 'm')) + + del mock.f + self.assertFalse(hasattr(mock, 'f')) + self.assertRaises(AttributeError, getattr, mock, 'f') + + + def test_class_assignable(self): + for mock in Mock(), MagicMock(): + self.assertNotIsInstance(mock, int) + + mock.__class__ = int + self.assertIsInstance(mock, int) + + + @unittest2.expectedFailure + def test_pickle(self): + for Klass in (MagicMock, Mock, Subclass, NonCallableMagicMock): + mock = Klass(name='foo', attribute=3) + mock.foo(1, 2, 3) + data = pickle.dumps(mock) + new = pickle.loads(data) + + new.foo.assert_called_once_with(1, 2, 3) + self.assertFalse(new.called) + self.assertTrue(is_instance(new, Klass)) + self.assertIsInstance(new, Thing) + self.assertIn('name="foo"', repr(new)) + self.assertEqual(new.attribute, 3) + + +if __name__ == '__main__': + unittest2.main() diff --git a/python/mock-1.0.0/tests/testpatch.py b/python/mock-1.0.0/tests/testpatch.py new file mode 100644 index 000000000..1ebe67106 --- /dev/null +++ b/python/mock-1.0.0/tests/testpatch.py @@ -0,0 +1,1790 @@ +# Copyright (C) 2007-2012 Michael Foord & the mock team +# E-mail: fuzzyman AT voidspace DOT org DOT uk +# http://www.voidspace.org.uk/python/mock/ + +import os +import sys + +from tests import support +from tests.support import unittest2, inPy3k, SomeClass, is_instance, callable + +from mock import ( + NonCallableMock, CallableMixin, patch, sentinel, + MagicMock, Mock, NonCallableMagicMock, patch, _patch, + DEFAULT, call, _get_target +) + +builtin_string = '__builtin__' +if inPy3k: + builtin_string = 'builtins' + unicode = str + +PTModule = sys.modules[__name__] +MODNAME = '%s.PTModule' % __name__ + + +def _get_proxy(obj, get_only=True): + class Proxy(object): + def __getattr__(self, name): + return getattr(obj, name) + if not get_only: + def __setattr__(self, name, value): + setattr(obj, name, value) + def __delattr__(self, name): + delattr(obj, name) + Proxy.__setattr__ = __setattr__ + Proxy.__delattr__ = __delattr__ + return Proxy() + + +# for use in the test +something = sentinel.Something +something_else = sentinel.SomethingElse + + +class Foo(object): + def __init__(self, a): + pass + def f(self, a): + pass + def g(self): + pass + foo = 'bar' + + class Bar(object): + def a(self): + pass + +foo_name = '%s.Foo' % __name__ + + +def function(a, b=Foo): + pass + + +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) + + + +class PatchTest(unittest2.TestCase): + + def assertNotCallable(self, obj, magic=True): + MockClass = NonCallableMagicMock + if not magic: + MockClass = NonCallableMock + + self.assertRaises(TypeError, obj) + self.assertTrue(is_instance(obj, MockClass)) + self.assertFalse(is_instance(obj, CallableMixin)) + + + def test_single_patchobject(self): + class Something(object): + attribute = sentinel.Original + + @patch.object(Something, 'attribute', sentinel.Patched) + def test(): + self.assertEqual(Something.attribute, sentinel.Patched, "unpatched") + + test() + self.assertEqual(Something.attribute, sentinel.Original, + "patch not restored") + + + def test_patchobject_with_none(self): + class Something(object): + attribute = sentinel.Original + + @patch.object(Something, 'attribute', None) + def test(): + self.assertIsNone(Something.attribute, "unpatched") + + test() + self.assertEqual(Something.attribute, sentinel.Original, + "patch not restored") + + + def test_multiple_patchobject(self): + class Something(object): + attribute = sentinel.Original + next_attribute = sentinel.Original2 + + @patch.object(Something, 'attribute', sentinel.Patched) + @patch.object(Something, 'next_attribute', sentinel.Patched2) + def test(): + self.assertEqual(Something.attribute, sentinel.Patched, + "unpatched") + self.assertEqual(Something.next_attribute, sentinel.Patched2, + "unpatched") + + test() + self.assertEqual(Something.attribute, sentinel.Original, + "patch not restored") + self.assertEqual(Something.next_attribute, sentinel.Original2, + "patch not restored") + + + def test_object_lookup_is_quite_lazy(self): + global something + original = something + @patch('%s.something' % __name__, sentinel.Something2) + def test(): + pass + + try: + something = sentinel.replacement_value + test() + self.assertEqual(something, sentinel.replacement_value) + finally: + something = original + + + def test_patch(self): + @patch('%s.something' % __name__, sentinel.Something2) + def test(): + self.assertEqual(PTModule.something, sentinel.Something2, + "unpatched") + + test() + self.assertEqual(PTModule.something, sentinel.Something, + "patch not restored") + + @patch('%s.something' % __name__, sentinel.Something2) + @patch('%s.something_else' % __name__, sentinel.SomethingElse) + def test(): + self.assertEqual(PTModule.something, sentinel.Something2, + "unpatched") + self.assertEqual(PTModule.something_else, sentinel.SomethingElse, + "unpatched") + + self.assertEqual(PTModule.something, sentinel.Something, + "patch not restored") + self.assertEqual(PTModule.something_else, sentinel.SomethingElse, + "patch not restored") + + # Test the patching and restoring works a second time + test() + + self.assertEqual(PTModule.something, sentinel.Something, + "patch not restored") + self.assertEqual(PTModule.something_else, sentinel.SomethingElse, + "patch not restored") + + mock = Mock() + mock.return_value = sentinel.Handle + @patch('%s.open' % builtin_string, mock) + def test(): + self.assertEqual(open('filename', 'r'), sentinel.Handle, + "open not patched") + test() + test() + + self.assertNotEqual(open, mock, "patch not restored") + + + def test_patch_class_attribute(self): + @patch('%s.SomeClass.class_attribute' % __name__, + sentinel.ClassAttribute) + def test(): + self.assertEqual(PTModule.SomeClass.class_attribute, + sentinel.ClassAttribute, "unpatched") + test() + + self.assertIsNone(PTModule.SomeClass.class_attribute, + "patch not restored") + + + def test_patchobject_with_default_mock(self): + class Test(object): + something = sentinel.Original + something2 = sentinel.Original2 + + @patch.object(Test, 'something') + def test(mock): + self.assertEqual(mock, Test.something, + "Mock not passed into test function") + self.assertIsInstance(mock, MagicMock, + "patch with two arguments did not create a mock") + + test() + + @patch.object(Test, 'something') + @patch.object(Test, 'something2') + def test(this1, this2, mock1, mock2): + self.assertEqual(this1, sentinel.this1, + "Patched function didn't receive initial argument") + self.assertEqual(this2, sentinel.this2, + "Patched function didn't receive second argument") + self.assertEqual(mock1, Test.something2, + "Mock not passed into test function") + self.assertEqual(mock2, Test.something, + "Second Mock not passed into test function") + self.assertIsInstance(mock2, MagicMock, + "patch with two arguments did not create a mock") + self.assertIsInstance(mock2, MagicMock, + "patch with two arguments did not create a mock") + + # A hack to test that new mocks are passed the second time + self.assertNotEqual(outerMock1, mock1, "unexpected value for mock1") + self.assertNotEqual(outerMock2, mock2, "unexpected value for mock1") + return mock1, mock2 + + outerMock1 = outerMock2 = None + outerMock1, outerMock2 = test(sentinel.this1, sentinel.this2) + + # Test that executing a second time creates new mocks + test(sentinel.this1, sentinel.this2) + + + def test_patch_with_spec(self): + @patch('%s.SomeClass' % __name__, spec=SomeClass) + def test(MockSomeClass): + self.assertEqual(SomeClass, MockSomeClass) + self.assertTrue(is_instance(SomeClass.wibble, MagicMock)) + self.assertRaises(AttributeError, lambda: SomeClass.not_wibble) + + test() + + + def test_patchobject_with_spec(self): + @patch.object(SomeClass, 'class_attribute', spec=SomeClass) + def test(MockAttribute): + self.assertEqual(SomeClass.class_attribute, MockAttribute) + self.assertTrue(is_instance(SomeClass.class_attribute.wibble, + MagicMock)) + self.assertRaises(AttributeError, + lambda: SomeClass.class_attribute.not_wibble) + + test() + + + def test_patch_with_spec_as_list(self): + @patch('%s.SomeClass' % __name__, spec=['wibble']) + def test(MockSomeClass): + self.assertEqual(SomeClass, MockSomeClass) + self.assertTrue(is_instance(SomeClass.wibble, MagicMock)) + self.assertRaises(AttributeError, lambda: SomeClass.not_wibble) + + test() + + + def test_patchobject_with_spec_as_list(self): + @patch.object(SomeClass, 'class_attribute', spec=['wibble']) + def test(MockAttribute): + self.assertEqual(SomeClass.class_attribute, MockAttribute) + self.assertTrue(is_instance(SomeClass.class_attribute.wibble, + MagicMock)) + self.assertRaises(AttributeError, + lambda: SomeClass.class_attribute.not_wibble) + + test() + + + def test_nested_patch_with_spec_as_list(self): + # regression test for nested decorators + @patch('%s.open' % builtin_string) + @patch('%s.SomeClass' % __name__, spec=['wibble']) + def test(MockSomeClass, MockOpen): + self.assertEqual(SomeClass, MockSomeClass) + self.assertTrue(is_instance(SomeClass.wibble, MagicMock)) + self.assertRaises(AttributeError, lambda: SomeClass.not_wibble) + test() + + + def test_patch_with_spec_as_boolean(self): + @patch('%s.SomeClass' % __name__, spec=True) + def test(MockSomeClass): + self.assertEqual(SomeClass, MockSomeClass) + # Should not raise attribute error + MockSomeClass.wibble + + self.assertRaises(AttributeError, lambda: MockSomeClass.not_wibble) + + test() + + + def test_patch_object_with_spec_as_boolean(self): + @patch.object(PTModule, 'SomeClass', spec=True) + def test(MockSomeClass): + self.assertEqual(SomeClass, MockSomeClass) + # Should not raise attribute error + MockSomeClass.wibble + + self.assertRaises(AttributeError, lambda: MockSomeClass.not_wibble) + + test() + + + def test_patch_class_acts_with_spec_is_inherited(self): + @patch('%s.SomeClass' % __name__, spec=True) + def test(MockSomeClass): + self.assertTrue(is_instance(MockSomeClass, MagicMock)) + instance = MockSomeClass() + self.assertNotCallable(instance) + # Should not raise attribute error + instance.wibble + + self.assertRaises(AttributeError, lambda: instance.not_wibble) + + test() + + + def test_patch_with_create_mocks_non_existent_attributes(self): + @patch('%s.frooble' % builtin_string, sentinel.Frooble, create=True) + def test(): + self.assertEqual(frooble, sentinel.Frooble) + + test() + self.assertRaises(NameError, lambda: frooble) + + + def test_patchobject_with_create_mocks_non_existent_attributes(self): + @patch.object(SomeClass, 'frooble', sentinel.Frooble, create=True) + def test(): + self.assertEqual(SomeClass.frooble, sentinel.Frooble) + + test() + self.assertFalse(hasattr(SomeClass, 'frooble')) + + + def test_patch_wont_create_by_default(self): + try: + @patch('%s.frooble' % builtin_string, sentinel.Frooble) + def test(): + self.assertEqual(frooble, sentinel.Frooble) + + test() + except AttributeError: + pass + else: + self.fail('Patching non existent attributes should fail') + + self.assertRaises(NameError, lambda: frooble) + + + def test_patchobject_wont_create_by_default(self): + try: + @patch.object(SomeClass, 'frooble', sentinel.Frooble) + def test(): + self.fail('Patching non existent attributes should fail') + + test() + except AttributeError: + pass + else: + self.fail('Patching non existent attributes should fail') + self.assertFalse(hasattr(SomeClass, 'frooble')) + + + def test_patch_with_static_methods(self): + class Foo(object): + @staticmethod + def woot(): + return sentinel.Static + + @patch.object(Foo, 'woot', staticmethod(lambda: sentinel.Patched)) + def anonymous(): + self.assertEqual(Foo.woot(), sentinel.Patched) + anonymous() + + self.assertEqual(Foo.woot(), sentinel.Static) + + + def test_patch_local(self): + foo = sentinel.Foo + @patch.object(sentinel, 'Foo', 'Foo') + def anonymous(): + self.assertEqual(sentinel.Foo, 'Foo') + anonymous() + + self.assertEqual(sentinel.Foo, foo) + + + def test_patch_slots(self): + class Foo(object): + __slots__ = ('Foo',) + + foo = Foo() + foo.Foo = sentinel.Foo + + @patch.object(foo, 'Foo', 'Foo') + def anonymous(): + self.assertEqual(foo.Foo, 'Foo') + anonymous() + + self.assertEqual(foo.Foo, sentinel.Foo) + + + def test_patchobject_class_decorator(self): + class Something(object): + attribute = sentinel.Original + + class Foo(object): + def test_method(other_self): + self.assertEqual(Something.attribute, sentinel.Patched, + "unpatched") + def not_test_method(other_self): + self.assertEqual(Something.attribute, sentinel.Original, + "non-test method patched") + + Foo = patch.object(Something, 'attribute', sentinel.Patched)(Foo) + + f = Foo() + f.test_method() + f.not_test_method() + + self.assertEqual(Something.attribute, sentinel.Original, + "patch not restored") + + + def test_patch_class_decorator(self): + class Something(object): + attribute = sentinel.Original + + class Foo(object): + def test_method(other_self, mock_something): + self.assertEqual(PTModule.something, mock_something, + "unpatched") + def not_test_method(other_self): + self.assertEqual(PTModule.something, sentinel.Something, + "non-test method patched") + Foo = patch('%s.something' % __name__)(Foo) + + f = Foo() + f.test_method() + f.not_test_method() + + self.assertEqual(Something.attribute, sentinel.Original, + "patch not restored") + self.assertEqual(PTModule.something, sentinel.Something, + "patch not restored") + + + def test_patchobject_twice(self): + class Something(object): + attribute = sentinel.Original + next_attribute = sentinel.Original2 + + @patch.object(Something, 'attribute', sentinel.Patched) + @patch.object(Something, 'attribute', sentinel.Patched) + def test(): + self.assertEqual(Something.attribute, sentinel.Patched, "unpatched") + + test() + + self.assertEqual(Something.attribute, sentinel.Original, + "patch not restored") + + + def test_patch_dict(self): + foo = {'initial': object(), 'other': 'something'} + original = foo.copy() + + @patch.dict(foo) + def test(): + foo['a'] = 3 + del foo['initial'] + foo['other'] = 'something else' + + test() + + self.assertEqual(foo, original) + + @patch.dict(foo, {'a': 'b'}) + def test(): + self.assertEqual(len(foo), 3) + self.assertEqual(foo['a'], 'b') + + test() + + self.assertEqual(foo, original) + + @patch.dict(foo, [('a', 'b')]) + def test(): + self.assertEqual(len(foo), 3) + self.assertEqual(foo['a'], 'b') + + test() + + self.assertEqual(foo, original) + + + def test_patch_dict_with_container_object(self): + foo = Container() + foo['initial'] = object() + foo['other'] = 'something' + + original = foo.values.copy() + + @patch.dict(foo) + def test(): + foo['a'] = 3 + del foo['initial'] + foo['other'] = 'something else' + + test() + + self.assertEqual(foo.values, original) + + @patch.dict(foo, {'a': 'b'}) + def test(): + self.assertEqual(len(foo.values), 3) + self.assertEqual(foo['a'], 'b') + + test() + + self.assertEqual(foo.values, original) + + + def test_patch_dict_with_clear(self): + foo = {'initial': object(), 'other': 'something'} + original = foo.copy() + + @patch.dict(foo, clear=True) + def test(): + self.assertEqual(foo, {}) + foo['a'] = 3 + foo['other'] = 'something else' + + test() + + self.assertEqual(foo, original) + + @patch.dict(foo, {'a': 'b'}, clear=True) + def test(): + self.assertEqual(foo, {'a': 'b'}) + + test() + + self.assertEqual(foo, original) + + @patch.dict(foo, [('a', 'b')], clear=True) + def test(): + self.assertEqual(foo, {'a': 'b'}) + + test() + + self.assertEqual(foo, original) + + + def test_patch_dict_with_container_object_and_clear(self): + foo = Container() + foo['initial'] = object() + foo['other'] = 'something' + + original = foo.values.copy() + + @patch.dict(foo, clear=True) + def test(): + self.assertEqual(foo.values, {}) + foo['a'] = 3 + foo['other'] = 'something else' + + test() + + self.assertEqual(foo.values, original) + + @patch.dict(foo, {'a': 'b'}, clear=True) + def test(): + self.assertEqual(foo.values, {'a': 'b'}) + + test() + + self.assertEqual(foo.values, original) + + + def test_name_preserved(self): + foo = {} + + @patch('%s.SomeClass' % __name__, object()) + @patch('%s.SomeClass' % __name__, object(), autospec=True) + @patch.object(SomeClass, object()) + @patch.dict(foo) + def some_name(): + pass + + self.assertEqual(some_name.__name__, 'some_name') + + + def test_patch_with_exception(self): + foo = {} + + @patch.dict(foo, {'a': 'b'}) + def test(): + raise NameError('Konrad') + try: + test() + except NameError: + pass + else: + self.fail('NameError not raised by test') + + self.assertEqual(foo, {}) + + + def test_patch_dict_with_string(self): + @patch.dict('os.environ', {'konrad_delong': 'some value'}) + def test(): + self.assertIn('konrad_delong', os.environ) + + test() + + + @unittest2.expectedFailure + def test_patch_descriptor(self): + # would be some effort to fix this - we could special case the + # builtin descriptors: classmethod, property, staticmethod + class Nothing(object): + foo = None + + class Something(object): + foo = {} + + @patch.object(Nothing, 'foo', 2) + @classmethod + def klass(cls): + self.assertIs(cls, Something) + + @patch.object(Nothing, 'foo', 2) + @staticmethod + def static(arg): + return arg + + @patch.dict(foo) + @classmethod + def klass_dict(cls): + self.assertIs(cls, Something) + + @patch.dict(foo) + @staticmethod + def static_dict(arg): + return arg + + # these will raise exceptions if patching descriptors is broken + self.assertEqual(Something.static('f00'), 'f00') + Something.klass() + self.assertEqual(Something.static_dict('f00'), 'f00') + Something.klass_dict() + + something = Something() + self.assertEqual(something.static('f00'), 'f00') + something.klass() + self.assertEqual(something.static_dict('f00'), 'f00') + something.klass_dict() + + + def test_patch_spec_set(self): + @patch('%s.SomeClass' % __name__, spec_set=SomeClass) + def test(MockClass): + MockClass.z = 'foo' + + self.assertRaises(AttributeError, test) + + @patch.object(support, 'SomeClass', spec_set=SomeClass) + def test(MockClass): + MockClass.z = 'foo' + + self.assertRaises(AttributeError, test) + @patch('%s.SomeClass' % __name__, spec_set=True) + def test(MockClass): + MockClass.z = 'foo' + + self.assertRaises(AttributeError, test) + + @patch.object(support, 'SomeClass', spec_set=True) + def test(MockClass): + MockClass.z = 'foo' + + self.assertRaises(AttributeError, test) + + + def test_spec_set_inherit(self): + @patch('%s.SomeClass' % __name__, spec_set=True) + def test(MockClass): + instance = MockClass() + instance.z = 'foo' + + self.assertRaises(AttributeError, test) + + + def test_patch_start_stop(self): + original = something + patcher = patch('%s.something' % __name__) + self.assertIs(something, original) + mock = patcher.start() + try: + self.assertIsNot(mock, original) + self.assertIs(something, mock) + finally: + patcher.stop() + self.assertIs(something, original) + + + def test_stop_without_start(self): + patcher = patch(foo_name, 'bar', 3) + + # calling stop without start used to produce a very obscure error + self.assertRaises(RuntimeError, patcher.stop) + + + def test_patchobject_start_stop(self): + original = something + patcher = patch.object(PTModule, 'something', 'foo') + self.assertIs(something, original) + replaced = patcher.start() + try: + self.assertEqual(replaced, 'foo') + self.assertIs(something, replaced) + finally: + patcher.stop() + self.assertIs(something, original) + + + def test_patch_dict_start_stop(self): + d = {'foo': 'bar'} + original = d.copy() + patcher = patch.dict(d, [('spam', 'eggs')], clear=True) + self.assertEqual(d, original) + + patcher.start() + try: + self.assertEqual(d, {'spam': 'eggs'}) + finally: + patcher.stop() + self.assertEqual(d, original) + + + def test_patch_dict_class_decorator(self): + this = self + d = {'spam': 'eggs'} + original = d.copy() + + class Test(object): + def test_first(self): + this.assertEqual(d, {'foo': 'bar'}) + def test_second(self): + this.assertEqual(d, {'foo': 'bar'}) + + Test = patch.dict(d, {'foo': 'bar'}, clear=True)(Test) + self.assertEqual(d, original) + + test = Test() + + test.test_first() + self.assertEqual(d, original) + + test.test_second() + self.assertEqual(d, original) + + test = Test() + + test.test_first() + self.assertEqual(d, original) + + test.test_second() + self.assertEqual(d, original) + + + def test_get_only_proxy(self): + class Something(object): + foo = 'foo' + class SomethingElse: + foo = 'foo' + + for thing in Something, SomethingElse, Something(), SomethingElse: + proxy = _get_proxy(thing) + + @patch.object(proxy, 'foo', 'bar') + def test(): + self.assertEqual(proxy.foo, 'bar') + test() + self.assertEqual(proxy.foo, 'foo') + self.assertEqual(thing.foo, 'foo') + self.assertNotIn('foo', proxy.__dict__) + + + def test_get_set_delete_proxy(self): + class Something(object): + foo = 'foo' + class SomethingElse: + foo = 'foo' + + for thing in Something, SomethingElse, Something(), SomethingElse: + proxy = _get_proxy(Something, get_only=False) + + @patch.object(proxy, 'foo', 'bar') + def test(): + self.assertEqual(proxy.foo, 'bar') + test() + self.assertEqual(proxy.foo, 'foo') + self.assertEqual(thing.foo, 'foo') + self.assertNotIn('foo', proxy.__dict__) + + + def test_patch_keyword_args(self): + kwargs = {'side_effect': KeyError, 'foo.bar.return_value': 33, + 'foo': MagicMock()} + + patcher = patch(foo_name, **kwargs) + mock = patcher.start() + patcher.stop() + + self.assertRaises(KeyError, mock) + self.assertEqual(mock.foo.bar(), 33) + self.assertIsInstance(mock.foo, MagicMock) + + + def test_patch_object_keyword_args(self): + kwargs = {'side_effect': KeyError, 'foo.bar.return_value': 33, + 'foo': MagicMock()} + + patcher = patch.object(Foo, 'f', **kwargs) + mock = patcher.start() + patcher.stop() + + self.assertRaises(KeyError, mock) + self.assertEqual(mock.foo.bar(), 33) + self.assertIsInstance(mock.foo, MagicMock) + + + def test_patch_dict_keyword_args(self): + original = {'foo': 'bar'} + copy = original.copy() + + patcher = patch.dict(original, foo=3, bar=4, baz=5) + patcher.start() + + try: + self.assertEqual(original, dict(foo=3, bar=4, baz=5)) + finally: + patcher.stop() + + self.assertEqual(original, copy) + + + def test_autospec(self): + class Boo(object): + def __init__(self, a): + pass + def f(self, a): + pass + def g(self): + pass + foo = 'bar' + + class Bar(object): + def a(self): + pass + + def _test(mock): + mock(1) + mock.assert_called_with(1) + self.assertRaises(TypeError, mock) + + def _test2(mock): + mock.f(1) + mock.f.assert_called_with(1) + self.assertRaises(TypeError, mock.f) + + mock.g() + mock.g.assert_called_with() + self.assertRaises(TypeError, mock.g, 1) + + self.assertRaises(AttributeError, getattr, mock, 'h') + + mock.foo.lower() + mock.foo.lower.assert_called_with() + self.assertRaises(AttributeError, getattr, mock.foo, 'bar') + + mock.Bar() + mock.Bar.assert_called_with() + + mock.Bar.a() + mock.Bar.a.assert_called_with() + self.assertRaises(TypeError, mock.Bar.a, 1) + + mock.Bar().a() + mock.Bar().a.assert_called_with() + self.assertRaises(TypeError, mock.Bar().a, 1) + + self.assertRaises(AttributeError, getattr, mock.Bar, 'b') + self.assertRaises(AttributeError, getattr, mock.Bar(), 'b') + + def function(mock): + _test(mock) + _test2(mock) + _test2(mock(1)) + self.assertIs(mock, Foo) + return mock + + test = patch(foo_name, autospec=True)(function) + + mock = test() + self.assertIsNot(Foo, mock) + # test patching a second time works + test() + + module = sys.modules[__name__] + test = patch.object(module, 'Foo', autospec=True)(function) + + mock = test() + self.assertIsNot(Foo, mock) + # test patching a second time works + test() + + + def test_autospec_function(self): + @patch('%s.function' % __name__, autospec=True) + def test(mock): + function(1) + function.assert_called_with(1) + function(2, 3) + function.assert_called_with(2, 3) + + self.assertRaises(TypeError, function) + self.assertRaises(AttributeError, getattr, function, 'foo') + + test() + + + def test_autospec_keywords(self): + @patch('%s.function' % __name__, autospec=True, + return_value=3) + def test(mock_function): + #self.assertEqual(function.abc, 'foo') + return function(1, 2) + + result = test() + self.assertEqual(result, 3) + + + def test_autospec_with_new(self): + patcher = patch('%s.function' % __name__, new=3, autospec=True) + self.assertRaises(TypeError, patcher.start) + + module = sys.modules[__name__] + patcher = patch.object(module, 'function', new=3, autospec=True) + self.assertRaises(TypeError, patcher.start) + + + def test_autospec_with_object(self): + class Bar(Foo): + extra = [] + + patcher = patch(foo_name, autospec=Bar) + mock = patcher.start() + try: + self.assertIsInstance(mock, Bar) + self.assertIsInstance(mock.extra, list) + finally: + patcher.stop() + + + def test_autospec_inherits(self): + FooClass = Foo + patcher = patch(foo_name, autospec=True) + mock = patcher.start() + try: + self.assertIsInstance(mock, FooClass) + self.assertIsInstance(mock(3), FooClass) + finally: + patcher.stop() + + + def test_autospec_name(self): + patcher = patch(foo_name, autospec=True) + mock = patcher.start() + + try: + self.assertIn(" name='Foo'", repr(mock)) + self.assertIn(" name='Foo.f'", repr(mock.f)) + self.assertIn(" name='Foo()'", repr(mock(None))) + self.assertIn(" name='Foo().f'", repr(mock(None).f)) + finally: + patcher.stop() + + + def test_tracebacks(self): + @patch.object(Foo, 'f', object()) + def test(): + raise AssertionError + try: + test() + except: + err = sys.exc_info() + + result = unittest2.TextTestResult(None, None, 0) + traceback = result._exc_info_to_string(err, self) + self.assertIn('raise AssertionError', traceback) + + + def test_new_callable_patch(self): + patcher = patch(foo_name, new_callable=NonCallableMagicMock) + + m1 = patcher.start() + patcher.stop() + m2 = patcher.start() + patcher.stop() + + self.assertIsNot(m1, m2) + for mock in m1, m2: + self.assertNotCallable(m1) + + + def test_new_callable_patch_object(self): + patcher = patch.object(Foo, 'f', new_callable=NonCallableMagicMock) + + m1 = patcher.start() + patcher.stop() + m2 = patcher.start() + patcher.stop() + + self.assertIsNot(m1, m2) + for mock in m1, m2: + self.assertNotCallable(m1) + + + def test_new_callable_keyword_arguments(self): + class Bar(object): + kwargs = None + def __init__(self, **kwargs): + Bar.kwargs = kwargs + + patcher = patch(foo_name, new_callable=Bar, arg1=1, arg2=2) + m = patcher.start() + try: + self.assertIs(type(m), Bar) + self.assertEqual(Bar.kwargs, dict(arg1=1, arg2=2)) + finally: + patcher.stop() + + + def test_new_callable_spec(self): + class Bar(object): + kwargs = None + def __init__(self, **kwargs): + Bar.kwargs = kwargs + + patcher = patch(foo_name, new_callable=Bar, spec=Bar) + patcher.start() + try: + self.assertEqual(Bar.kwargs, dict(spec=Bar)) + finally: + patcher.stop() + + patcher = patch(foo_name, new_callable=Bar, spec_set=Bar) + patcher.start() + try: + self.assertEqual(Bar.kwargs, dict(spec_set=Bar)) + finally: + patcher.stop() + + + def test_new_callable_create(self): + non_existent_attr = '%s.weeeee' % foo_name + p = patch(non_existent_attr, new_callable=NonCallableMock) + self.assertRaises(AttributeError, p.start) + + p = patch(non_existent_attr, new_callable=NonCallableMock, + create=True) + m = p.start() + try: + self.assertNotCallable(m, magic=False) + finally: + p.stop() + + + def test_new_callable_incompatible_with_new(self): + self.assertRaises( + ValueError, patch, foo_name, new=object(), new_callable=MagicMock + ) + self.assertRaises( + ValueError, patch.object, Foo, 'f', new=object(), + new_callable=MagicMock + ) + + + def test_new_callable_incompatible_with_autospec(self): + self.assertRaises( + ValueError, patch, foo_name, new_callable=MagicMock, + autospec=True + ) + self.assertRaises( + ValueError, patch.object, Foo, 'f', new_callable=MagicMock, + autospec=True + ) + + + def test_new_callable_inherit_for_mocks(self): + class MockSub(Mock): + pass + + MockClasses = ( + NonCallableMock, NonCallableMagicMock, MagicMock, Mock, MockSub + ) + for Klass in MockClasses: + for arg in 'spec', 'spec_set': + kwargs = {arg: True} + p = patch(foo_name, new_callable=Klass, **kwargs) + m = p.start() + try: + instance = m.return_value + self.assertRaises(AttributeError, getattr, instance, 'x') + finally: + p.stop() + + + def test_new_callable_inherit_non_mock(self): + class NotAMock(object): + def __init__(self, spec): + self.spec = spec + + p = patch(foo_name, new_callable=NotAMock, spec=True) + m = p.start() + try: + self.assertTrue(is_instance(m, NotAMock)) + self.assertRaises(AttributeError, getattr, m, 'return_value') + finally: + p.stop() + + self.assertEqual(m.spec, Foo) + + + def test_new_callable_class_decorating(self): + test = self + original = Foo + class SomeTest(object): + + def _test(self, mock_foo): + test.assertIsNot(Foo, original) + test.assertIs(Foo, mock_foo) + test.assertIsInstance(Foo, SomeClass) + + def test_two(self, mock_foo): + self._test(mock_foo) + def test_one(self, mock_foo): + self._test(mock_foo) + + SomeTest = patch(foo_name, new_callable=SomeClass)(SomeTest) + SomeTest().test_one() + SomeTest().test_two() + self.assertIs(Foo, original) + + + def test_patch_multiple(self): + original_foo = Foo + original_f = Foo.f + original_g = Foo.g + + patcher1 = patch.multiple(foo_name, f=1, g=2) + patcher2 = patch.multiple(Foo, f=1, g=2) + + for patcher in patcher1, patcher2: + patcher.start() + try: + self.assertIs(Foo, original_foo) + self.assertEqual(Foo.f, 1) + self.assertEqual(Foo.g, 2) + finally: + patcher.stop() + + self.assertIs(Foo, original_foo) + self.assertEqual(Foo.f, original_f) + self.assertEqual(Foo.g, original_g) + + + @patch.multiple(foo_name, f=3, g=4) + def test(): + self.assertIs(Foo, original_foo) + self.assertEqual(Foo.f, 3) + self.assertEqual(Foo.g, 4) + + test() + + + def test_patch_multiple_no_kwargs(self): + self.assertRaises(ValueError, patch.multiple, foo_name) + self.assertRaises(ValueError, patch.multiple, Foo) + + + def test_patch_multiple_create_mocks(self): + original_foo = Foo + original_f = Foo.f + original_g = Foo.g + + @patch.multiple(foo_name, f=DEFAULT, g=3, foo=DEFAULT) + def test(f, foo): + self.assertIs(Foo, original_foo) + self.assertIs(Foo.f, f) + self.assertEqual(Foo.g, 3) + self.assertIs(Foo.foo, foo) + self.assertTrue(is_instance(f, MagicMock)) + self.assertTrue(is_instance(foo, MagicMock)) + + test() + self.assertEqual(Foo.f, original_f) + self.assertEqual(Foo.g, original_g) + + + def test_patch_multiple_create_mocks_different_order(self): + # bug revealed by Jython! + original_f = Foo.f + original_g = Foo.g + + patcher = patch.object(Foo, 'f', 3) + patcher.attribute_name = 'f' + + other = patch.object(Foo, 'g', DEFAULT) + other.attribute_name = 'g' + patcher.additional_patchers = [other] + + @patcher + def test(g): + self.assertIs(Foo.g, g) + self.assertEqual(Foo.f, 3) + + test() + self.assertEqual(Foo.f, original_f) + self.assertEqual(Foo.g, original_g) + + + def test_patch_multiple_stacked_decorators(self): + original_foo = Foo + original_f = Foo.f + original_g = Foo.g + + @patch.multiple(foo_name, f=DEFAULT) + @patch.multiple(foo_name, foo=DEFAULT) + @patch(foo_name + '.g') + def test1(g, **kwargs): + _test(g, **kwargs) + + @patch.multiple(foo_name, f=DEFAULT) + @patch(foo_name + '.g') + @patch.multiple(foo_name, foo=DEFAULT) + def test2(g, **kwargs): + _test(g, **kwargs) + + @patch(foo_name + '.g') + @patch.multiple(foo_name, f=DEFAULT) + @patch.multiple(foo_name, foo=DEFAULT) + def test3(g, **kwargs): + _test(g, **kwargs) + + def _test(g, **kwargs): + f = kwargs.pop('f') + foo = kwargs.pop('foo') + self.assertFalse(kwargs) + + self.assertIs(Foo, original_foo) + self.assertIs(Foo.f, f) + self.assertIs(Foo.g, g) + self.assertIs(Foo.foo, foo) + self.assertTrue(is_instance(f, MagicMock)) + self.assertTrue(is_instance(g, MagicMock)) + self.assertTrue(is_instance(foo, MagicMock)) + + test1() + test2() + test3() + self.assertEqual(Foo.f, original_f) + self.assertEqual(Foo.g, original_g) + + + def test_patch_multiple_create_mocks_patcher(self): + original_foo = Foo + original_f = Foo.f + original_g = Foo.g + + patcher = patch.multiple(foo_name, f=DEFAULT, g=3, foo=DEFAULT) + + result = patcher.start() + try: + f = result['f'] + foo = result['foo'] + self.assertEqual(set(result), set(['f', 'foo'])) + + self.assertIs(Foo, original_foo) + self.assertIs(Foo.f, f) + self.assertIs(Foo.foo, foo) + self.assertTrue(is_instance(f, MagicMock)) + self.assertTrue(is_instance(foo, MagicMock)) + finally: + patcher.stop() + + self.assertEqual(Foo.f, original_f) + self.assertEqual(Foo.g, original_g) + + + def test_patch_multiple_decorating_class(self): + test = self + original_foo = Foo + original_f = Foo.f + original_g = Foo.g + + class SomeTest(object): + + def _test(self, f, foo): + test.assertIs(Foo, original_foo) + test.assertIs(Foo.f, f) + test.assertEqual(Foo.g, 3) + test.assertIs(Foo.foo, foo) + test.assertTrue(is_instance(f, MagicMock)) + test.assertTrue(is_instance(foo, MagicMock)) + + def test_two(self, f, foo): + self._test(f, foo) + def test_one(self, f, foo): + self._test(f, foo) + + SomeTest = patch.multiple( + foo_name, f=DEFAULT, g=3, foo=DEFAULT + )(SomeTest) + + thing = SomeTest() + thing.test_one() + thing.test_two() + + self.assertEqual(Foo.f, original_f) + self.assertEqual(Foo.g, original_g) + + + def test_patch_multiple_create(self): + patcher = patch.multiple(Foo, blam='blam') + self.assertRaises(AttributeError, patcher.start) + + patcher = patch.multiple(Foo, blam='blam', create=True) + patcher.start() + try: + self.assertEqual(Foo.blam, 'blam') + finally: + patcher.stop() + + self.assertFalse(hasattr(Foo, 'blam')) + + + def test_patch_multiple_spec_set(self): + # if spec_set works then we can assume that spec and autospec also + # work as the underlying machinery is the same + patcher = patch.multiple(Foo, foo=DEFAULT, spec_set=['a', 'b']) + result = patcher.start() + try: + self.assertEqual(Foo.foo, result['foo']) + Foo.foo.a(1) + Foo.foo.b(2) + Foo.foo.a.assert_called_with(1) + Foo.foo.b.assert_called_with(2) + self.assertRaises(AttributeError, setattr, Foo.foo, 'c', None) + finally: + patcher.stop() + + + def test_patch_multiple_new_callable(self): + class Thing(object): + pass + + patcher = patch.multiple( + Foo, f=DEFAULT, g=DEFAULT, new_callable=Thing + ) + result = patcher.start() + try: + self.assertIs(Foo.f, result['f']) + self.assertIs(Foo.g, result['g']) + self.assertIsInstance(Foo.f, Thing) + self.assertIsInstance(Foo.g, Thing) + self.assertIsNot(Foo.f, Foo.g) + finally: + patcher.stop() + + + def test_nested_patch_failure(self): + original_f = Foo.f + original_g = Foo.g + + @patch.object(Foo, 'g', 1) + @patch.object(Foo, 'missing', 1) + @patch.object(Foo, 'f', 1) + def thing1(): + pass + + @patch.object(Foo, 'missing', 1) + @patch.object(Foo, 'g', 1) + @patch.object(Foo, 'f', 1) + def thing2(): + pass + + @patch.object(Foo, 'g', 1) + @patch.object(Foo, 'f', 1) + @patch.object(Foo, 'missing', 1) + def thing3(): + pass + + for func in thing1, thing2, thing3: + self.assertRaises(AttributeError, func) + self.assertEqual(Foo.f, original_f) + self.assertEqual(Foo.g, original_g) + + + def test_new_callable_failure(self): + original_f = Foo.f + original_g = Foo.g + original_foo = Foo.foo + + def crasher(): + raise NameError('crasher') + + @patch.object(Foo, 'g', 1) + @patch.object(Foo, 'foo', new_callable=crasher) + @patch.object(Foo, 'f', 1) + def thing1(): + pass + + @patch.object(Foo, 'foo', new_callable=crasher) + @patch.object(Foo, 'g', 1) + @patch.object(Foo, 'f', 1) + def thing2(): + pass + + @patch.object(Foo, 'g', 1) + @patch.object(Foo, 'f', 1) + @patch.object(Foo, 'foo', new_callable=crasher) + def thing3(): + pass + + for func in thing1, thing2, thing3: + self.assertRaises(NameError, func) + self.assertEqual(Foo.f, original_f) + self.assertEqual(Foo.g, original_g) + self.assertEqual(Foo.foo, original_foo) + + + def test_patch_multiple_failure(self): + original_f = Foo.f + original_g = Foo.g + + patcher = patch.object(Foo, 'f', 1) + patcher.attribute_name = 'f' + + good = patch.object(Foo, 'g', 1) + good.attribute_name = 'g' + + bad = patch.object(Foo, 'missing', 1) + bad.attribute_name = 'missing' + + for additionals in [good, bad], [bad, good]: + patcher.additional_patchers = additionals + + @patcher + def func(): + pass + + self.assertRaises(AttributeError, func) + self.assertEqual(Foo.f, original_f) + self.assertEqual(Foo.g, original_g) + + + def test_patch_multiple_new_callable_failure(self): + original_f = Foo.f + original_g = Foo.g + original_foo = Foo.foo + + def crasher(): + raise NameError('crasher') + + patcher = patch.object(Foo, 'f', 1) + patcher.attribute_name = 'f' + + good = patch.object(Foo, 'g', 1) + good.attribute_name = 'g' + + bad = patch.object(Foo, 'foo', new_callable=crasher) + bad.attribute_name = 'foo' + + for additionals in [good, bad], [bad, good]: + patcher.additional_patchers = additionals + + @patcher + def func(): + pass + + self.assertRaises(NameError, func) + self.assertEqual(Foo.f, original_f) + self.assertEqual(Foo.g, original_g) + self.assertEqual(Foo.foo, original_foo) + + + def test_patch_multiple_string_subclasses(self): + for base in (str, unicode): + Foo = type('Foo', (base,), {'fish': 'tasty'}) + foo = Foo() + @patch.multiple(foo, fish='nearly gone') + def test(): + self.assertEqual(foo.fish, 'nearly gone') + + test() + self.assertEqual(foo.fish, 'tasty') + + + @patch('mock.patch.TEST_PREFIX', 'foo') + def test_patch_test_prefix(self): + class Foo(object): + thing = 'original' + + def foo_one(self): + return self.thing + def foo_two(self): + return self.thing + def test_one(self): + return self.thing + def test_two(self): + return self.thing + + Foo = patch.object(Foo, 'thing', 'changed')(Foo) + + foo = Foo() + self.assertEqual(foo.foo_one(), 'changed') + self.assertEqual(foo.foo_two(), 'changed') + self.assertEqual(foo.test_one(), 'original') + self.assertEqual(foo.test_two(), 'original') + + + @patch('mock.patch.TEST_PREFIX', 'bar') + def test_patch_dict_test_prefix(self): + class Foo(object): + def bar_one(self): + return dict(the_dict) + def bar_two(self): + return dict(the_dict) + def test_one(self): + return dict(the_dict) + def test_two(self): + return dict(the_dict) + + the_dict = {'key': 'original'} + Foo = patch.dict(the_dict, key='changed')(Foo) + + foo =Foo() + self.assertEqual(foo.bar_one(), {'key': 'changed'}) + self.assertEqual(foo.bar_two(), {'key': 'changed'}) + self.assertEqual(foo.test_one(), {'key': 'original'}) + self.assertEqual(foo.test_two(), {'key': 'original'}) + + + def test_patch_with_spec_mock_repr(self): + for arg in ('spec', 'autospec', 'spec_set'): + p = patch('%s.SomeClass' % __name__, **{arg: True}) + m = p.start() + try: + self.assertIn(" name='SomeClass'", repr(m)) + self.assertIn(" name='SomeClass.class_attribute'", + repr(m.class_attribute)) + self.assertIn(" name='SomeClass()'", repr(m())) + self.assertIn(" name='SomeClass().class_attribute'", + repr(m().class_attribute)) + finally: + p.stop() + + + def test_patch_nested_autospec_repr(self): + p = patch('tests.support', autospec=True) + m = p.start() + try: + self.assertIn(" name='support.SomeClass.wibble()'", + repr(m.SomeClass.wibble())) + self.assertIn(" name='support.SomeClass().wibble()'", + repr(m.SomeClass().wibble())) + finally: + p.stop() + + + def test_mock_calls_with_patch(self): + for arg in ('spec', 'autospec', 'spec_set'): + p = patch('%s.SomeClass' % __name__, **{arg: True}) + m = p.start() + try: + m.wibble() + + kalls = [call.wibble()] + self.assertEqual(m.mock_calls, kalls) + self.assertEqual(m.method_calls, kalls) + self.assertEqual(m.wibble.mock_calls, [call()]) + + result = m() + kalls.append(call()) + self.assertEqual(m.mock_calls, kalls) + + result.wibble() + kalls.append(call().wibble()) + self.assertEqual(m.mock_calls, kalls) + + self.assertEqual(result.mock_calls, [call.wibble()]) + self.assertEqual(result.wibble.mock_calls, [call()]) + self.assertEqual(result.method_calls, [call.wibble()]) + finally: + p.stop() + + + def test_patch_imports_lazily(self): + sys.modules.pop('squizz', None) + + p1 = patch('squizz.squozz') + self.assertRaises(ImportError, p1.start) + + squizz = Mock() + squizz.squozz = 6 + sys.modules['squizz'] = squizz + p1 = patch('squizz.squozz') + squizz.squozz = 3 + p1.start() + p1.stop() + self.assertEqual(squizz.squozz, 3) + + + def test_patch_propogrates_exc_on_exit(self): + class holder: + exc_info = None, None, None + + class custom_patch(_patch): + def __exit__(self, etype=None, val=None, tb=None): + _patch.__exit__(self, etype, val, tb) + holder.exc_info = etype, val, tb + stop = __exit__ + + def with_custom_patch(target): + getter, attribute = _get_target(target) + return custom_patch( + getter, attribute, DEFAULT, None, False, None, + None, None, {} + ) + + @with_custom_patch('squizz.squozz') + def test(mock): + raise RuntimeError + + self.assertRaises(RuntimeError, test) + self.assertIs(holder.exc_info[0], RuntimeError) + self.assertIsNotNone(holder.exc_info[1], + 'exception value not propgated') + self.assertIsNotNone(holder.exc_info[2], + 'exception traceback not propgated') + + + def test_create_and_specs(self): + for kwarg in ('spec', 'spec_set', 'autospec'): + p = patch('%s.doesnotexist' % __name__, create=True, + **{kwarg: True}) + self.assertRaises(TypeError, p.start) + self.assertRaises(NameError, lambda: doesnotexist) + + # check that spec with create is innocuous if the original exists + p = patch(MODNAME, create=True, **{kwarg: True}) + p.start() + p.stop() + + + def test_multiple_specs(self): + original = PTModule + for kwarg in ('spec', 'spec_set'): + p = patch(MODNAME, autospec=0, **{kwarg: 0}) + self.assertRaises(TypeError, p.start) + self.assertIs(PTModule, original) + + for kwarg in ('spec', 'autospec'): + p = patch(MODNAME, spec_set=0, **{kwarg: 0}) + self.assertRaises(TypeError, p.start) + self.assertIs(PTModule, original) + + for kwarg in ('spec_set', 'autospec'): + p = patch(MODNAME, spec=0, **{kwarg: 0}) + self.assertRaises(TypeError, p.start) + self.assertIs(PTModule, original) + + + def test_specs_false_instead_of_none(self): + p = patch(MODNAME, spec=False, spec_set=False, autospec=False) + mock = p.start() + try: + # no spec should have been set, so attribute access should not fail + mock.does_not_exist + mock.does_not_exist = 3 + finally: + p.stop() + + + def test_falsey_spec(self): + for kwarg in ('spec', 'autospec', 'spec_set'): + p = patch(MODNAME, **{kwarg: 0}) + m = p.start() + try: + self.assertRaises(AttributeError, getattr, m, 'doesnotexit') + finally: + p.stop() + + + def test_spec_set_true(self): + for kwarg in ('spec', 'autospec'): + p = patch(MODNAME, spec_set=True, **{kwarg: True}) + m = p.start() + try: + self.assertRaises(AttributeError, setattr, m, + 'doesnotexist', 'something') + self.assertRaises(AttributeError, getattr, m, 'doesnotexist') + finally: + p.stop() + + + def test_callable_spec_as_list(self): + spec = ('__call__',) + p = patch(MODNAME, spec=spec) + m = p.start() + try: + self.assertTrue(callable(m)) + finally: + p.stop() + + + def test_not_callable_spec_as_list(self): + spec = ('foo', 'bar') + p = patch(MODNAME, spec=spec) + m = p.start() + try: + self.assertFalse(callable(m)) + finally: + p.stop() + + + def test_patch_stopall(self): + unlink = os.unlink + chdir = os.chdir + path = os.path + patch('os.unlink', something).start() + patch('os.chdir', something_else).start() + + @patch('os.path') + def patched(mock_path): + patch.stopall() + self.assertIs(os.path, mock_path) + self.assertIs(os.unlink, unlink) + self.assertIs(os.chdir, chdir) + + patched() + self.assertIs(os.path, path) + + + +if __name__ == '__main__': + unittest2.main() diff --git a/python/mock-1.0.0/tests/testsentinel.py b/python/mock-1.0.0/tests/testsentinel.py new file mode 100644 index 000000000..981171a45 --- /dev/null +++ b/python/mock-1.0.0/tests/testsentinel.py @@ -0,0 +1,33 @@ +# Copyright (C) 2007-2012 Michael Foord & the mock team +# E-mail: fuzzyman AT voidspace DOT org DOT uk +# http://www.voidspace.org.uk/python/mock/ + +from tests.support import unittest2 + +from mock import sentinel, DEFAULT + + +class SentinelTest(unittest2.TestCase): + + def testSentinels(self): + self.assertEqual(sentinel.whatever, sentinel.whatever, + 'sentinel not stored') + self.assertNotEqual(sentinel.whatever, sentinel.whateverelse, + 'sentinel should be unique') + + + def testSentinelName(self): + self.assertEqual(str(sentinel.whatever), 'sentinel.whatever', + 'sentinel name incorrect') + + + def testDEFAULT(self): + self.assertTrue(DEFAULT is sentinel.DEFAULT) + + def testBases(self): + # If this doesn't raise an AttributeError then help(mock) is broken + self.assertRaises(AttributeError, lambda: sentinel.__bases__) + + +if __name__ == '__main__': + unittest2.main() diff --git a/python/mock-1.0.0/tests/testwith.py b/python/mock-1.0.0/tests/testwith.py new file mode 100644 index 000000000..34529eb9f --- /dev/null +++ b/python/mock-1.0.0/tests/testwith.py @@ -0,0 +1,16 @@ +import sys + +if sys.version_info[:2] >= (2, 5): + from tests._testwith import * +else: + from tests.support import unittest2 + + class TestWith(unittest2.TestCase): + + @unittest2.skip('tests using with statement skipped on Python 2.4') + def testWith(self): + pass + + +if __name__ == '__main__': + unittest2.main() diff --git a/python/mock-1.0.0/tox.ini b/python/mock-1.0.0/tox.ini new file mode 100644 index 000000000..554f87096 --- /dev/null +++ b/python/mock-1.0.0/tox.ini @@ -0,0 +1,40 @@ +[tox] +envlist = py24,py25,py26,py27,py31,pypy,py32,py33,jython + +[testenv] +deps=unittest2 +commands={envbindir}/unit2 discover [] + +[testenv:py26] +commands= + {envbindir}/unit2 discover [] + {envbindir}/sphinx-build -E -b doctest docs html + {envbindir}/sphinx-build -E docs html +deps = + unittest2 + sphinx + +[testenv:py27] +commands= + {envbindir}/unit2 discover [] + {envbindir}/sphinx-build -E -b doctest docs html +deps = + unittest2 + sphinx + +[testenv:py31] +deps = + unittest2py3k + +[testenv:py32] +commands= + {envbindir}/python -m unittest discover [] +deps = + +[testenv:py33] +commands= + {envbindir}/python -m unittest discover [] +deps = + +# note for jython. Execute in tests directory: +# rm `find . -name '*$py.class'` \ No newline at end of file -- cgit v1.2.3