diff options
Diffstat (limited to 'third_party/python/mock-1.0.0/docs')
| -rw-r--r-- | third_party/python/mock-1.0.0/docs/changelog.txt | 725 | ||||
| -rw-r--r-- | third_party/python/mock-1.0.0/docs/compare.txt | 628 | ||||
| -rw-r--r-- | third_party/python/mock-1.0.0/docs/conf.py | 209 | ||||
| -rw-r--r-- | third_party/python/mock-1.0.0/docs/examples.txt | 1063 | ||||
| -rw-r--r-- | third_party/python/mock-1.0.0/docs/getting-started.txt | 479 | ||||
| -rw-r--r-- | third_party/python/mock-1.0.0/docs/helpers.txt | 583 | ||||
| -rw-r--r-- | third_party/python/mock-1.0.0/docs/index.txt | 411 | ||||
| -rw-r--r-- | third_party/python/mock-1.0.0/docs/magicmock.txt | 258 | ||||
| -rw-r--r-- | third_party/python/mock-1.0.0/docs/mock.txt | 842 | ||||
| -rw-r--r-- | third_party/python/mock-1.0.0/docs/patch.txt | 636 | ||||
| -rw-r--r-- | third_party/python/mock-1.0.0/docs/sentinel.txt | 58 |
11 files changed, 5892 insertions, 0 deletions
diff --git a/third_party/python/mock-1.0.0/docs/changelog.txt b/third_party/python/mock-1.0.0/docs/changelog.txt new file mode 100644 index 0000000000..a605be3d97 --- /dev/null +++ b/third_party/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 +<http://docs.python.org/py3k/library/unittest.mock.html#module-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 <http://mock.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 <https://github.com/coordt/ADCtheme/>`_. + +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 <http://pypi.python.org/pypi/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 <http://konryd.blogspot.com/>`_ 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 <http://pypi.python.org/pypi/unittest2>`_ + to run +* `Konrad Delong <http://konryd.blogspot.com/>`_ 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 <http://code.google.com/p/mock/issues/list>`_ + +`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/third_party/python/mock-1.0.0/docs/compare.txt b/third_party/python/mock-1.0.0/docs/compare.txt new file mode 100644 index 0000000000..41555308e2 --- /dev/null +++ b/third_party/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 <http://pypi.python.org/pypi/flexmock>`_ +* `mox <http://pypi.python.org/pypi/mox>`_ +* `Mocker <http://niemeyer.net/mocker>`_ +* `dingus <http://pypi.python.org/pypi/dingus>`_ +* `fudge <http://pypi.python.org/pypi/fudge>`_ + +Popular python mocking frameworks not yet represented here include +`MiniMock <http://pypi.python.org/pypi/MiniMock>`_. + +`pMock <http://pmock.sourceforge.net/>`_ (last release 2004 and doesn't import +in recent versions of Python) and +`python-mock <http://python-mock.sourceforge.net/>`_ (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 + <http://garybernhardt.github.com/python-mock-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 <https://code.google.com/p/mock/issues/list>`_. + +This comparison page was originally created by the `Mox project +<https://code.google.com/p/pymox/wiki/MoxComparison>`_ and then extended for +`flexmock and mock <http://has207.github.com/flexmock/compare.html>`_ by +Herman Sheremetyev. Dingus examples written by `Gary Bernhadt +<http://garybernhardt.github.com/python-mock-comparison/>`_. fudge examples +provided by `Kumar McMillan <http://farmdev.com/>`_. + +.. 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("<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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doctest:: + + >>> # 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 +~~~~~~~~~~~~~~~~~~ + +.. 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() + <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 +~~~~~~~~~~~~~~~~~~~~ + +.. 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/third_party/python/mock-1.0.0/docs/conf.py b/third_party/python/mock-1.0.0/docs/conf.py new file mode 100644 index 0000000000..62f0491cca --- /dev/null +++ b/third_party/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 +# "<project> v<release> 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/<name>. +#html_copy_source = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> 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/third_party/python/mock-1.0.0/docs/examples.txt b/third_party/python/mock-1.0.0/docs/examples.txt new file mode 100644 index 0000000000..ecb994b156 --- /dev/null +++ b/third_party/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 <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 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: + +.. 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() +<http://docs.python.org/library/datetime.html#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 <patch>` 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 <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 +<http://williamjohnbert.com/2011/07/how-to-unit-testing-in-django-with-mocking-and-patching/>`_. + + +Mocking a Generator Method +========================== + +A Python generator is a function or method that uses the `yield statement +<http://docs.python.org/reference/simple_stmts.html#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__ +<http://docs.python.org/library/stdtypes.html#container.__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 + <http://www.dabeaz.com/coroutines/index.html>`_ 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 + <http://www.dabeaz.com/generators/>`_. + + +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 +<http://pypi.python.org/pypi/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 +<http://docs.python.org/library/copy.html#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 + <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 :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 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` +[#]_. 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 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 +<https://code.google.com/p/mock/issues/detail?id=105>`_ is subclassing mock to +created a `Twisted adaptor +<http://twistedmatrix.com/documents/11.0.0/api/twisted.python.components.html>`_. +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 + <MagicMock name='mock.foo' id='...'> + >>> 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() + ... + <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: + +.. doctest:: + + >>> 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: + +.. doctest:: + + >>> 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 :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 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: + +.. 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() + ... + <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 +: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() + <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`: + +.. 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: ((<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 +<http://pypi.python.org/pypi/PyHamcrest>`_ provides similar functionality, +that may be useful here, in the form of its equality matcher +(`hamcrest.library.integration.match_equality +<http://packages.python.org/PyHamcrest/integration.html#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/third_party/python/mock-1.0.0/docs/getting-started.txt b/third_party/python/mock-1.0.0/docs/getting-started.txt new file mode 100644 index 0000000000..1b5d289ebe --- /dev/null +++ b/third_party/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') + <MagicMock name='method()' id='...'> + +Once our mock has been used (`real.method` in this example) it has methods +and attributes that allow you to make assertions about how it has been used. + +.. note:: + + In most of these examples the :class:`Mock` and :class:`MagicMock` classes + are interchangeable. As the `MagicMock` is the more capable class it makes + a sensible one to use by default. + +Once the mock has been called its :attr:`~Mock.called` attribute is set to +`True`. More importantly we can use the :meth:`~Mock.assert_called_with` or +:meth:`~Mock.assert_called_once_with` method to check that it was called with +the correct arguments. + +This example tests that calling `ProductionClass().method` results in a call to +the `something` method: + +.. 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 + <MagicMock name='foo' id='...'> + >>> mock.method + <MagicMock name='foo.method' id='...'> + + +Tracking all Calls +------------------ + +Often you want to track more than a single call to a method. The +:attr:`~Mock.mock_calls` attribute records all calls +to child attributes of the mock - and also to their children. + +.. doctest:: + + >>> mock = MagicMock() + >>> mock.method() + <MagicMock name='mock.method()' id='...'> + >>> mock.attribute.method(10, x=53) + <MagicMock name='mock.attribute.method()' id='...'> + >>> mock.mock_calls + [call.method(), call.attribute.method(10, x=53)] + +If you make an assertion about `mock_calls` and any unexpected methods +have been called, then the assertion will fail. This is useful because as well +as asserting that the calls you expected have been made, you are also checking +that they were made in the right order and with no additional calls: + +You use the :data:`call` object to construct lists for comparing with +`mock_calls`: + +.. 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 <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/third_party/python/mock-1.0.0/docs/helpers.txt b/third_party/python/mock-1.0.0/docs/helpers.txt new file mode 100644 index 0000000000..571b71d5eb --- /dev/null +++ b/third_party/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) + <MagicMock name='mock().method().other()()' id='...'> + >>> kall = call(1).method(arg='foo').other('bar')(2.0) + >>> kall.call_list() + [call(1), + call().method(arg='foo'), + call().method().other('bar'), + call().method().other()(2.0)] + >>> m.mock_calls == kall.call_list() + True + +.. _calls-as-tuples: + +A `call` object is either a tuple of (positional args, keyword args) or +(name, positional args, keyword args) depending on how it was constructed. When +you construct them yourself this isn't particularly interesting, but the `call` +objects that are in the :attr:`Mock.call_args`, :attr:`Mock.call_args_list` and +:attr:`Mock.mock_calls` attributes can be introspected to get at the individual +arguments they contain. + +The `call` objects in :attr:`Mock.call_args` and :attr:`Mock.call_args_list` +are two-tuples of (positional args, keyword args) whereas the `call` objects +in :attr:`Mock.mock_calls`, along with ones you construct yourself, are +three-tuples of (name, positional args, keyword args). + +You can use their "tupleness" to pull out the individual arguments for more +complex introspection and assertions. The positional arguments are a tuple +(an empty tuple if there are no positional arguments) and the keyword +arguments are a dictionary: + +.. 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') + <MagicMock name='mock.foo()' id='...'> + >>> kall = m.mock_calls[0] + >>> name, args, kwargs = kall + >>> name + 'foo' + >>> args + (4, 5, 6) + >>> kwargs + {'arg2': 'three', 'arg': 'two'} + >>> name is m.mock_calls[0][0] + True + + +create_autospec +=============== + +.. function:: create_autospec(spec, spec_set=False, instance=False, **kwargs) + + Create a mock object using another object as a spec. Attributes on the + mock will use the corresponding attribute on the `spec` object as their + spec. + + Functions or methods being mocked will have their arguments checked to + ensure that they are called with the correct signature. + + If `spec_set` is `True` then attempting to set attributes that don't exist + on the spec object will raise an `AttributeError`. + + If a class is used as a spec then the return value of the mock (the + instance of the class) will have the same spec. You can use a class as the + spec for an instance object by passing `instance=True`. The returned mock + will only be callable if instances of the mock are callable. + + `create_autospec` also takes arbitrary keyword arguments that are passed to + the constructor of the created mock. + +See :ref:`auto-speccing` for examples of how to use auto-speccing with +`create_autospec` and the `autospec` argument to :func:`patch`. + + +ANY +=== + +.. data:: ANY + +Sometimes you may need to make assertions about *some* of the arguments in a +call to mock, but either not care about some of the arguments or want to pull +them individually out of :attr:`~Mock.call_args` and make more complex +assertions on them. + +To ignore certain arguments you can pass in objects that compare equal to +*everything*. Calls to :meth:`~Mock.assert_called_with` and +:meth:`~Mock.assert_called_once_with` will then succeed no matter what was +passed in. + +.. 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.Mock object at 0x...> + >>> mock.has_data.assret_called_with() + +Auto-speccing solves this problem. You can either pass `autospec=True` to +`patch` / `patch.object` or use the `create_autospec` function to create a +mock with a spec. If you use the `autospec=True` argument to `patch` then the +object that is being replaced will be used as the spec object. Because the +speccing is done "lazily" (the spec is created as attributes on the mock are +accessed) you can use it with very complex or deeply nested objects (like +modules that import modules that import modules) without a big performance +hit. + +Here's an example of it in use: + +.. doctest:: + + >>> import urllib2 + >>> patcher = patch('__main__.urllib2', autospec=True) + >>> mock_urllib2 = patcher.start() + >>> urllib2 is mock_urllib2 + True + >>> urllib2.Request + <MagicMock name='urllib2.Request' spec='Request' id='...'> + +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: <lambda>() 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 + <NonCallableMagicMock name='urllib2.Request()' spec='Request' id='...'> + +`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') + <MagicMock name='urllib2.Request().add_header()' id='...'> + >>> req.add_header.assret_called_with + Traceback (most recent call last): + ... + AttributeError: Mock object has no attribute 'assret_called_with' + >>> req.add_header.assert_called_with('spam', 'eggs') + +In many cases you will just be able to add `autospec=True` to your existing +`patch` calls and then be protected against bugs due to typos and api +changes. + +As well as using `autospec` through `patch` there is a +:func:`create_autospec` for creating autospecced mocks directly: + +.. doctest:: + + >>> import urllib2 + >>> mock_urllib2 = create_autospec(urllib2) + >>> mock_urllib2.Request('foo', 'bar') + <NonCallableMagicMock name='mock.Request()' spec='Request' id='...'> + +This isn't without caveats and limitations however, which is why it is not +the default behaviour. In order to know what attributes are available on the +spec object, autospec has to introspect (access attributes) the spec. As you +traverse attributes on the mock a corresponding traversal of the original +object is happening under the hood. If any of your specced objects have +properties or descriptors that can trigger code execution then you may not be +able to use autospec. On the other hand it is much better to design your +objects so that introspection is safe [#]_. + +A more serious problem is that it is common for instance attributes to be +created in the `__init__` method and not to exist on the class at all. +`autospec` can't know about any dynamically created attributes and restricts +the api to visible attributes. + +.. 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() + <MagicMock name='mock.member.foo.bar.baz()' id='...'> + +If modifying your production classes to add defaults isn't to your liking +then there are more options. One of these is simply to use an instance as the +spec rather than the class. The other is to create a subclass of the +production class and add the defaults to the subclass without affecting the +production class. Both of these require you to use an alternative object as +the spec. Thankfully `patch` supports this - you can simply pass the +alternative object as the `autospec` argument: + +.. 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 + <NonCallableMagicMock name='Something.a' spec='int' id='...'> + +.. 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: <lambda>() 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 + <http://docs.python.org/dev/library/inspect.html#inspect.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/third_party/python/mock-1.0.0/docs/index.txt b/third_party/python/mock-1.0.0/docs/index.txt new file mode 100644 index 0000000000..7e4a8daca6 --- /dev/null +++ b/third_party/python/mock-1.0.0/docs/index.txt @@ -0,0 +1,411 @@ +==================================== + Mock - Mocking and Testing Library +==================================== + +.. currentmodule:: mock + +:Author: `Michael Foord + <http://www.voidspace.org.uk/python/weblog/index.shtml>`_ +:Version: |release| +:Date: 2012/10/07 +:Homepage: `Mock Homepage`_ +:Download: `Mock on PyPI`_ +:Documentation: `PDF Documentation + <http://www.voidspace.org.uk/downloads/mock-1.0.0.pdf>`_ +:License: `BSD License`_ +:Support: `Mailing list (testing-in-python@lists.idyll.org) + <http://lists.idyll.org/listinfo/testing-in-python>`_ +:Issue tracker: `Google code project + <http://code.google.com/p/mock/issues/list>`_ + +.. _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 +<http://docs.python.org/py3k/library/unittest.mock.html#module-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 <http://pypi.python.org/pypi/unittest2>`_. 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 <http://pypi.python.org/pypi/mock>`_ +* `mock documentation as PDF + <http://www.voidspace.org.uk/downloads/mock-1.0.0.pdf>`_ +* `Google Code Home & Mercurial Repository <http://code.google.com/p/mock/>`_ + +.. 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 <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 <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>`. +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: <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. + + +.. 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 + <https://github.com/carljm/django-testing-slides/blob/master/models/30_no_database.md>`_ +* `mock-django: tools for mocking the Django ORM and models + <https://github.com/dcramer/mock-django>`_ +* `PyCon 2011 Video: Testing with mock <https://blip.tv/file/4881513>`_ +* `Mock objects in Python + <http://noopenblockers.com/2012/01/06/mock-objects-in-python/>`_ +* `Python: Injecting Mock Objects for Powerful Testing + <http://blueprintforge.com/blog/2012/01/08/python-injecting-mock-objects-for-powerful-testing/>`_ +* `Python Mock: How to assert a substring of logger output + <http://www.michaelpollmeier.com/python-mock-how-to-assert-a-substring-of-logger-output/>`_ +* `Mocking Django <http://www.mattjmorrison.com/2011/09/mocking-django.html>`_ +* `Mocking dates and other classes that can't be modified + <http://williamjohnbert.com/2011/07/how-to-unit-testing-in-django-with-mocking-and-patching/>`_ +* `Mock recipes <http://konryd.blogspot.com/2010/06/mock-recipies.html>`_ +* `Mockity mock mock - some love for the mock module + <http://konryd.blogspot.com/2010/05/mockity-mock-mock-some-love-for-mock.html>`_ +* `Coverage and Mock (with django) + <http://mattsnider.com/python/mock-and-coverage/>`_ +* `Python Unit Testing with Mock <http://www.insomnihack.com/?p=194>`_ +* `Getting started with Python Mock + <http://myadventuresincoding.wordpress.com/2011/02/26/python-python-mock-cheat-sheet/>`_ +* `Smart Parameter Checks with mock + <http://tobyho.com/2011/03/24/smart-parameter-checks-in/>`_ +* `Python mock testing techniques and tools + <http://agiletesting.blogspot.com/2009/07/python-mock-testing-techniques-and.html>`_ +* `How To Test Django Template Tags + <http://techblog.ironfroggy.com/2008/10/how-to-test.html>`_ +* `A presentation on Unit Testing with Mock + <http://pypap.blogspot.com/2008/10/newbie-nugget-unit-testing-with-mock.html>`_ +* `Mocking with Django and Google AppEngine + <http://michael-a-nelson.blogspot.com/2008/09/mocking-with-django-and-google-app.html>`_ + + +.. index:: tests +.. index:: unittest2 + +Tests +===== + +Mock uses `unittest2 <http://pypi.python.org/pypi/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 <http://pypi.python.org/pypi/distribute>`_ 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 <http://www.voidspace.org.uk/python/mock/0.8/>`_ +* `mock 0.7 <http://www.voidspace.org.uk/python/mock/0.7/>`_ +* `mock 0.6 <http://www.voidspace.org.uk/python/mock/0.6.0/>`_ + +Docs from the in-development version of `mock` can be found at +`mock.readthedocs.org <http://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 +<http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html>`_ +:class:`mock.Mock` is a `spy <http://xunitpatterns.com/Test%20Spy.html>`_ 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 +<http://martinfowler.com/articles/mocksArentStubs.html>`_. 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/third_party/python/mock-1.0.0/docs/magicmock.txt b/third_party/python/mock-1.0.0/docs/magicmock.txt new file mode 100644 index 0000000000..42b2ed9db1 --- /dev/null +++ b/third_party/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 +<http://www.ironpythoninaction.com/magic-methods.html>`_. This allows mock +objects to replace containers or other objects that implement Python +protocols. + +Because magic methods are looked up differently from normal methods [#]_, this +support has been specially implemented. This means that only specific magic +methods are supported. The supported list includes *almost* all of them. If +there are any missing that you need please let us know! + +You mock magic methods by setting the method you are interested in to a function +or a mock instance. If you are using a function then it *must* take ``self`` as +the first argument [#]_. + +.. doctest:: + + >>> def __str__(self): + ... return 'fooble' + ... + >>> mock = Mock() + >>> mock.__str__ = __str__ + >>> str(mock) + 'fooble' + + >>> mock = Mock() + >>> mock.__str__ = Mock() + >>> mock.__str__.return_value = 'fooble' + >>> str(mock) + 'fooble' + + >>> mock = Mock() + >>> mock.__iter__ = Mock(return_value=iter([])) + >>> list(mock) + [] + +One use case for this is for mocking objects used as context managers in a +`with` statement: + +.. doctest:: + + >>> mock = Mock() + >>> mock.__enter__ = Mock(return_value='foo') + >>> mock.__exit__ = Mock(return_value=False) + >>> with mock as m: + ... assert m == 'foo' + ... + >>> mock.__enter__.assert_called_with() + >>> mock.__exit__.assert_called_with(None, None, None) + +Calls to magic methods do not appear in :attr:`~Mock.method_calls`, but they +are recorded in :attr:`~Mock.mock_calls`. + +.. note:: + + If you use the `spec` keyword argument to create a mock then attempting to + set a magic method that isn't in the spec will raise an `AttributeError`. + +The full list of supported magic methods is: + +* ``__hash__``, ``__sizeof__``, ``__repr__`` and ``__str__`` +* ``__dir__``, ``__format__`` and ``__subclasses__`` +* ``__floor__``, ``__trunc__`` and ``__ceil__`` +* Comparisons: ``__cmp__``, ``__lt__``, ``__gt__``, ``__le__``, ``__ge__``, + ``__eq__`` and ``__ne__`` +* Container methods: ``__getitem__``, ``__setitem__``, ``__delitem__``, + ``__contains__``, ``__len__``, ``__iter__``, ``__getslice__``, + ``__setslice__``, ``__reversed__`` and ``__missing__`` +* Context manager: ``__enter__`` and ``__exit__`` +* Unary numeric methods: ``__neg__``, ``__pos__`` and ``__invert__`` +* The numeric methods (including right hand and in-place variants): + ``__add__``, ``__sub__``, ``__mul__``, ``__div__``, + ``__floordiv__``, ``__mod__``, ``__divmod__``, ``__lshift__``, + ``__rshift__``, ``__and__``, ``__xor__``, ``__or__``, and ``__pow__`` +* Numeric conversion methods: ``__complex__``, ``__int__``, ``__float__``, + ``__index__`` and ``__coerce__`` +* Descriptor methods: ``__get__``, ``__set__`` and ``__delete__`` +* Pickling: ``__reduce__``, ``__reduce_ex__``, ``__getinitargs__``, + ``__getnewargs__``, ``__getstate__`` and ``__setstate__`` + + +The following methods are supported in Python 2 but don't exist in Python 3: + +* ``__unicode__``, ``__long__``, ``__oct__``, ``__hex__`` and ``__nonzero__`` +* ``__truediv__`` and ``__rtruediv__`` + +The following methods are supported in Python 3 but don't exist in Python 2: + +* ``__bool__`` and ``__next__`` + +The following methods exist but are *not* supported as they are either in use by +mock, can't be set dynamically, or can cause problems: + +* ``__getattr__``, ``__setattr__``, ``__init__`` and ``__new__`` +* ``__prepare__``, ``__instancecheck__``, ``__subclasscheck__``, ``__del__`` + + + +Magic Mock +========== + +There are two `MagicMock` variants: `MagicMock` and `NonCallableMagicMock`. + + +.. class:: MagicMock(*args, **kw) + + ``MagicMock`` is a subclass of :class:`Mock` with default implementations + of most of the magic methods. You can use ``MagicMock`` without having to + configure the magic methods yourself. + + The constructor parameters have the same meaning as for :class:`Mock`. + + If you use the `spec` or `spec_set` arguments then *only* magic methods + that exist in the spec will be created. + + +.. class:: NonCallableMagicMock(*args, **kw) + + A non-callable version of `MagicMock`. + + The constructor parameters have the same meaning as for + :class:`MagicMock`, with the exception of `return_value` and + `side_effect` which have no meaning on a non-callable mock. + +The magic methods are setup with `MagicMock` objects, so you can configure them +and use them in the usual way: + +.. doctest:: + + >>> mock = MagicMock() + >>> mock[3] = 'fish' + >>> mock.__setitem__.assert_called_with(3, 'fish') + >>> mock.__getitem__.return_value = 'result' + >>> mock[2] + 'result' + +By default many of the protocol methods are required to return objects of a +specific type. These methods are preconfigured with a default return value, so +that they can be used without you having to do anything if you aren't interested +in the return value. You can still *set* the return value manually if you want +to change the default. + +Methods and their defaults: + +* ``__lt__``: NotImplemented +* ``__gt__``: NotImplemented +* ``__le__``: NotImplemented +* ``__ge__``: NotImplemented +* ``__int__`` : 1 +* ``__contains__`` : False +* ``__len__`` : 1 +* ``__iter__`` : iter([]) +* ``__exit__`` : False +* ``__complex__`` : 1j +* ``__float__`` : 1.0 +* ``__bool__`` : True +* ``__nonzero__`` : True +* ``__oct__`` : '1' +* ``__hex__`` : '0x1' +* ``__long__`` : long(1) +* ``__index__`` : 1 +* ``__hash__`` : default hash for the mock +* ``__str__`` : default str for the mock +* ``__unicode__`` : default unicode for the mock +* ``__sizeof__``: default sizeof for the mock + +For example: + +.. doctest:: + + >>> mock = MagicMock() + >>> int(mock) + 1 + >>> len(mock) + 0 + >>> hex(mock) + '0x1' + >>> list(mock) + [] + >>> object() in mock + False + +The two equality method, `__eq__` and `__ne__`, are special (changed in +0.7.2). They do the default equality comparison on identity, using a side +effect, unless you change their return value to return something else: + +.. doctest:: + + >>> MagicMock() == 3 + False + >>> MagicMock() != 3 + True + >>> mock = MagicMock() + >>> mock.__eq__.return_value = True + >>> mock == 3 + True + +In `0.8` the `__iter__` also gained special handling implemented with a +side effect. The return value of `MagicMock.__iter__` can be any iterable +object and isn't required to be an iterator: + +.. doctest:: + + >>> mock = MagicMock() + >>> mock.__iter__.return_value = ['a', 'b', 'c'] + >>> list(mock) + ['a', 'b', 'c'] + >>> list(mock) + ['a', 'b', 'c'] + +If the return value *is* an iterator, then iterating over it once will consume +it and subsequent iterations will result in an empty list: + +.. doctest:: + + >>> mock.__iter__.return_value = iter(['a', 'b', 'c']) + >>> list(mock) + ['a', 'b', 'c'] + >>> list(mock) + [] + +``MagicMock`` has all of the supported magic methods configured except for some +of the obscure and obsolete ones. You can still set these up if you want. + +Magic methods that are supported but not setup by default in ``MagicMock`` are: + +* ``__cmp__`` +* ``__getslice__`` and ``__setslice__`` +* ``__coerce__`` +* ``__subclasses__`` +* ``__dir__`` +* ``__format__`` +* ``__get__``, ``__set__`` and ``__delete__`` +* ``__reversed__`` and ``__missing__`` +* ``__reduce__``, ``__reduce_ex__``, ``__getinitargs__``, ``__getnewargs__``, + ``__getstate__`` and ``__setstate__`` +* ``__getformat__`` and ``__setformat__`` + + + +------------ + +.. [#] Magic methods *should* be looked up on the class rather than the + instance. Different versions of Python are inconsistent about applying this + rule. The supported protocol methods should work with all supported versions + of Python. +.. [#] The function is basically hooked up to the class, but each ``Mock`` + instance is kept isolated from the others. diff --git a/third_party/python/mock-1.0.0/docs/mock.txt b/third_party/python/mock-1.0.0/docs/mock.txt new file mode 100644 index 0000000000..58712b21a6 --- /dev/null +++ b/third_party/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 name='mock.method()' id='...'> + >>> mock.method.assert_called_with(1, 2, 3, test='wow') + + + .. method:: assert_called_once_with(*args, **kwargs) + + Assert that the mock was called exactly once and with the specified + arguments. + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock('foo', bar='baz') + >>> mock.assert_called_once_with('foo', bar='baz') + >>> mock('foo', bar='baz') + >>> mock.assert_called_once_with('foo', bar='baz') + Traceback (most recent call last): + ... + AssertionError: Expected to be called once. Called 2 times. + + + .. method:: assert_any_call(*args, **kwargs) + + assert the mock has been called with the specified arguments. + + The assert passes if the mock has *ever* been called, unlike + :meth:`assert_called_with` and :meth:`assert_called_once_with` that + only pass if the call is the most recent one. + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock(1, 2, arg='thing') + >>> mock('some', 'thing', 'else') + >>> mock.assert_any_call(1, 2, arg='thing') + + + .. method:: assert_has_calls(calls, any_order=False) + + assert the mock has been called with the specified calls. + The `mock_calls` list is checked for the calls. + + If `any_order` is False (the default) then the calls must be + sequential. There can be extra calls before or after the + specified calls. + + If `any_order` is True then the calls can be in any order, but + they must all appear in :attr:`mock_calls`. + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock(1) + >>> mock(2) + >>> mock(3) + >>> mock(4) + >>> calls = [call(2), call(3)] + >>> mock.assert_has_calls(calls) + >>> calls = [call(4), call(2), call(3)] + >>> mock.assert_has_calls(calls, any_order=True) + + + .. method:: reset_mock() + + The reset_mock method resets all the call attributes on a mock object: + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock('hello') + >>> mock.called + True + >>> mock.reset_mock() + >>> mock.called + False + + This can be useful where you want to make a series of assertions that + reuse the same object. Note that `reset_mock` *doesn't* clear the + return value, :attr:`side_effect` or any child attributes you have + set using normal assignment. Child mocks and the return value mock + (if any) are reset as well. + + + .. method:: mock_add_spec(spec, spec_set=False) + + Add a spec to a mock. `spec` can either be an object or a + list of strings. Only attributes on the `spec` can be fetched as + attributes from the mock. + + If `spec_set` is `True` then only attributes on the spec can be set. + + + .. method:: attach_mock(mock, attribute) + + Attach a mock as an attribute of this one, replacing its name and + parent. Calls to the attached mock will be recorded in the + :attr:`method_calls` and :attr:`mock_calls` attributes of this one. + + + .. method:: configure_mock(**kwargs) + + Set attributes on the mock through keyword arguments. + + Attributes plus return values and side effects can be set on child + mocks using standard dot notation and unpacking a dictionary in the + method call: + + .. doctest:: + + >>> mock = Mock() + >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} + >>> mock.configure_mock(**attrs) + >>> mock.method() + 3 + >>> mock.other() + Traceback (most recent call last): + ... + KeyError + + The same thing can be achieved in the constructor call to mocks: + + .. doctest:: + + >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} + >>> mock = Mock(some_attribute='eggs', **attrs) + >>> mock.some_attribute + 'eggs' + >>> mock.method() + 3 + >>> mock.other() + Traceback (most recent call last): + ... + KeyError + + `configure_mock` exists to make it easier to do configuration + after the mock has been created. + + + .. method:: __dir__() + + `Mock` objects limit the results of `dir(some_mock)` to useful results. + For mocks with a `spec` this includes all the permitted attributes + for the mock. + + See :data:`FILTER_DIR` for what this filtering does, and how to + switch it off. + + + .. method:: _get_child_mock(**kw) + + Create the child mocks for attributes and return value. + By default child mocks will be the same type as the parent. + Subclasses of Mock may want to override this to customize the way + child mocks are made. + + For non-callable mocks the callable variant will be used (rather than + any custom subclass). + + + .. attribute:: called + + A boolean representing whether or not the mock object has been called: + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock.called + False + >>> mock() + >>> mock.called + True + + .. attribute:: call_count + + An integer telling you how many times the mock object has been called: + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock.call_count + 0 + >>> mock() + >>> mock() + >>> mock.call_count + 2 + + + .. attribute:: return_value + + Set this to configure the value returned by calling the mock: + + .. doctest:: + + >>> mock = Mock() + >>> mock.return_value = 'fish' + >>> mock() + 'fish' + + The default return value is a mock object and you can configure it in + the normal way: + + .. doctest:: + + >>> mock = Mock() + >>> mock.return_value.attribute = sentinel.Attribute + >>> mock.return_value() + <Mock name='mock()()' id='...'> + >>> mock.return_value.assert_called_with() + + `return_value` can also be set in the constructor: + + .. doctest:: + + >>> mock = Mock(return_value=3) + >>> mock.return_value + 3 + >>> mock() + 3 + + + .. attribute:: side_effect + + This can either be a function to be called when the mock is called, + or an exception (class or instance) to be raised. + + If you pass in a function it will be called with same arguments as the + mock and unless the function returns the :data:`DEFAULT` singleton the + call to the mock will then return whatever the function returns. If the + function returns :data:`DEFAULT` then the mock will return its normal + value (from the :attr:`return_value`. + + An example of a mock that raises an exception (to test exception + handling of an API): + + .. doctest:: + + >>> mock = Mock() + >>> mock.side_effect = Exception('Boom!') + >>> mock() + Traceback (most recent call last): + ... + Exception: Boom! + + Using `side_effect` to return a sequence of values: + + .. doctest:: + + >>> mock = Mock() + >>> mock.side_effect = [3, 2, 1] + >>> mock(), mock(), mock() + (3, 2, 1) + + The `side_effect` function is called with the same arguments as the + mock (so it is wise for it to take arbitrary args and keyword + arguments) and whatever it returns is used as the return value for + the call. The exception is if `side_effect` returns :data:`DEFAULT`, + in which case the normal :attr:`return_value` is used. + + .. doctest:: + + >>> mock = Mock(return_value=3) + >>> def side_effect(*args, **kwargs): + ... return DEFAULT + ... + >>> mock.side_effect = side_effect + >>> mock() + 3 + + `side_effect` can be set in the constructor. Here's an example that + adds one to the value the mock is called with and returns it: + + .. doctest:: + + >>> side_effect = lambda value: value + 1 + >>> mock = Mock(side_effect=side_effect) + >>> mock(3) + 4 + >>> mock(-8) + -7 + + Setting `side_effect` to `None` clears it: + + .. doctest:: + + >>> from mock import Mock + >>> m = Mock(side_effect=KeyError, return_value=3) + >>> m() + Traceback (most recent call last): + ... + KeyError + >>> m.side_effect = None + >>> m() + 3 + + + .. attribute:: call_args + + This is either `None` (if the mock hasn't been called), or the + arguments that the mock was last called with. This will be in the + form of a tuple: the first member is any ordered arguments the mock + was called with (or an empty tuple) and the second member is any + keyword arguments (or an empty dictionary). + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> print mock.call_args + None + >>> mock() + >>> mock.call_args + call() + >>> mock.call_args == () + True + >>> mock(3, 4) + >>> mock.call_args + call(3, 4) + >>> mock.call_args == ((3, 4),) + True + >>> mock(3, 4, 5, key='fish', next='w00t!') + >>> mock.call_args + call(3, 4, 5, key='fish', next='w00t!') + + `call_args`, along with members of the lists :attr:`call_args_list`, + :attr:`method_calls` and :attr:`mock_calls` are :data:`call` objects. + These are tuples, so they can be unpacked to get at the individual + arguments and make more complex assertions. See + :ref:`calls as tuples <calls-as-tuples>`. + + + .. attribute:: call_args_list + + This is a list of all the calls made to the mock object in sequence + (so the length of the list is the number of times it has been + called). Before any calls have been made it is an empty list. The + :data:`call` object can be used for conveniently constructing lists of + calls to compare with `call_args_list`. + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock() + >>> mock(3, 4) + >>> mock(key='fish', next='w00t!') + >>> mock.call_args_list + [call(), call(3, 4), call(key='fish', next='w00t!')] + >>> expected = [(), ((3, 4),), ({'key': 'fish', 'next': 'w00t!'},)] + >>> mock.call_args_list == expected + True + + Members of `call_args_list` are :data:`call` objects. These can be + unpacked as tuples to get at the individual arguments. See + :ref:`calls as tuples <calls-as-tuples>`. + + + .. attribute:: method_calls + + As well as tracking calls to themselves, mocks also track calls to + methods and attributes, and *their* methods and attributes: + + .. doctest:: + + >>> mock = Mock() + >>> mock.method() + <Mock name='mock.method()' id='...'> + >>> mock.property.method.attribute() + <Mock name='mock.property.method.attribute()' id='...'> + >>> mock.method_calls + [call.method(), call.property.method.attribute()] + + Members of `method_calls` are :data:`call` objects. These can be + unpacked as tuples to get at the individual arguments. See + :ref:`calls as tuples <calls-as-tuples>`. + + + .. attribute:: mock_calls + + `mock_calls` records *all* calls to the mock object, its methods, magic + methods *and* return value mocks. + + .. doctest:: + + >>> mock = MagicMock() + >>> result = mock(1, 2, 3) + >>> mock.first(a=3) + <MagicMock name='mock.first()' id='...'> + >>> mock.second() + <MagicMock name='mock.second()' id='...'> + >>> int(mock) + 1 + >>> result(1) + <MagicMock name='mock()()' id='...'> + >>> expected = [call(1, 2, 3), call.first(a=3), call.second(), + ... call.__int__(), call()(1)] + >>> mock.mock_calls == expected + True + + Members of `mock_calls` are :data:`call` objects. These can be + unpacked as tuples to get at the individual arguments. See + :ref:`calls as tuples <calls-as-tuples>`. + + + .. attribute:: __class__ + + Normally the `__class__` attribute of an object will return its type. + For a mock object with a `spec` `__class__` returns the spec class + instead. This allows mock objects to pass `isinstance` tests for the + object they are replacing / masquerading as: + + .. doctest:: + + >>> mock = Mock(spec=3) + >>> isinstance(mock, int) + True + + `__class__` is assignable to, this allows a mock to pass an + `isinstance` check without forcing you to use a spec: + + .. doctest:: + + >>> mock = Mock() + >>> mock.__class__ = dict + >>> isinstance(mock, dict) + True + +.. class:: NonCallableMock(spec=None, wraps=None, name=None, spec_set=None, **kwargs) + + A non-callable version of `Mock`. The constructor parameters have the same + meaning of `Mock`, with the exception of `return_value` and `side_effect` + which have no meaning on a non-callable mock. + +Mock objects that use a class or an instance as a `spec` or `spec_set` are able +to pass `isintance` tests: + +.. doctest:: + + >>> mock = Mock(spec=SomeClass) + >>> isinstance(mock, SomeClass) + True + >>> mock = Mock(spec_set=SomeClass()) + >>> isinstance(mock, SomeClass) + True + +The `Mock` classes have support for mocking magic methods. See :ref:`magic +methods <magic-methods>` for the full details. + +The mock classes and the :func:`patch` decorators all take arbitrary keyword +arguments for configuration. For the `patch` decorators the keywords are +passed to the constructor of the mock being created. The keyword arguments +are for configuring attributes of the mock: + +.. doctest:: + + >>> m = MagicMock(attribute=3, other='fish') + >>> m.attribute + 3 + >>> m.other + 'fish' + +The return value and side effect of child mocks can be set in the same way, +using dotted notation. As you can't use dotted names directly in a call you +have to create a dictionary and unpack it using `**`: + +.. doctest:: + + >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} + >>> mock = Mock(some_attribute='eggs', **attrs) + >>> mock.some_attribute + 'eggs' + >>> mock.method() + 3 + >>> mock.other() + Traceback (most recent call last): + ... + KeyError + + +.. class:: PropertyMock(*args, **kwargs) + + A mock intended to be used as a property, or other descriptor, on a class. + `PropertyMock` provides `__get__` and `__set__` methods so you can specify + a return value when it is fetched. + + Fetching a `PropertyMock` instance from an object calls the mock, with + no args. Setting it calls the mock with the value being set. + + .. doctest:: + + >>> class Foo(object): + ... @property + ... def foo(self): + ... return 'something' + ... @foo.setter + ... def foo(self, value): + ... pass + ... + >>> with patch('__main__.Foo.foo', new_callable=PropertyMock) as mock_foo: + ... mock_foo.return_value = 'mockity-mock' + ... this_foo = Foo() + ... print this_foo.foo + ... this_foo.foo = 6 + ... + mockity-mock + >>> mock_foo.mock_calls + [call(), call(6)] + +Because of the way mock attributes are stored you can't directly attach a +`PropertyMock` to a mock object. Instead you can attach it to the mock type +object: + +.. doctest:: + + >>> m = MagicMock() + >>> p = PropertyMock(return_value=3) + >>> type(m).foo = p + >>> m.foo + 3 + >>> p.assert_called_once_with() + + +.. index:: __call__ +.. index:: calling + +Calling +======= + +Mock objects are callable. The call will return the value set as the +:attr:`~Mock.return_value` attribute. The default return value is a new Mock +object; it is created the first time the return value is accessed (either +explicitly or by calling the Mock) - but it is stored and the same one +returned each time. + +Calls made to the object will be recorded in the attributes +like :attr:`~Mock.call_args` and :attr:`~Mock.call_args_list`. + +If :attr:`~Mock.side_effect` is set then it will be called after the call has +been recorded, so if `side_effect` raises an exception the call is still +recorded. + +The simplest way to make a mock raise an exception when called is to make +:attr:`~Mock.side_effect` an exception class or instance: + +.. doctest:: + + >>> m = MagicMock(side_effect=IndexError) + >>> m(1, 2, 3) + Traceback (most recent call last): + ... + IndexError + >>> m.mock_calls + [call(1, 2, 3)] + >>> m.side_effect = KeyError('Bang!') + >>> m('two', 'three', 'four') + Traceback (most recent call last): + ... + KeyError: 'Bang!' + >>> m.mock_calls + [call(1, 2, 3), call('two', 'three', 'four')] + +If `side_effect` is a function then whatever that function returns is what +calls to the mock return. The `side_effect` function is called with the +same arguments as the mock. This allows you to vary the return value of the +call dynamically, based on the input: + +.. doctest:: + + >>> def side_effect(value): + ... return value + 1 + ... + >>> m = MagicMock(side_effect=side_effect) + >>> m(1) + 2 + >>> m(2) + 3 + >>> m.mock_calls + [call(1), call(2)] + +If you want the mock to still return the default return value (a new mock), or +any set return value, then there are two ways of doing this. Either return +`mock.return_value` from inside `side_effect`, or return :data:`DEFAULT`: + +.. doctest:: + + >>> m = MagicMock() + >>> def side_effect(*args, **kwargs): + ... return m.return_value + ... + >>> m.side_effect = side_effect + >>> m.return_value = 3 + >>> m() + 3 + >>> def side_effect(*args, **kwargs): + ... return DEFAULT + ... + >>> m.side_effect = side_effect + >>> m() + 3 + +To remove a `side_effect`, and return to the default behaviour, set the +`side_effect` to `None`: + +.. doctest:: + + >>> m = MagicMock(return_value=6) + >>> def side_effect(*args, **kwargs): + ... return 3 + ... + >>> m.side_effect = side_effect + >>> m() + 3 + >>> m.side_effect = None + >>> m() + 6 + +The `side_effect` can also be any iterable object. Repeated calls to the mock +will return values from the iterable (until the iterable is exhausted and +a `StopIteration` is raised): + +.. doctest:: + + >>> m = MagicMock(side_effect=[1, 2, 3]) + >>> m() + 1 + >>> m() + 2 + >>> m() + 3 + >>> m() + Traceback (most recent call last): + ... + StopIteration + +If any members of the iterable are exceptions they will be raised instead of +returned: + +.. doctest:: + + >>> iterable = (33, ValueError, 66) + >>> m = MagicMock(side_effect=iterable) + >>> m() + 33 + >>> m() + Traceback (most recent call last): + ... + ValueError + >>> m() + 66 + + +.. _deleting-attributes: + +Deleting Attributes +=================== + +Mock objects create attributes on demand. This allows them to pretend to be +objects of any type. + +You may want a mock object to return `False` to a `hasattr` call, or raise an +`AttributeError` when an attribute is fetched. You can do this by providing +an object as a `spec` for a mock, but that isn't always convenient. + +You "block" attributes by deleting them. Once deleted, accessing an attribute +will raise an `AttributeError`. + +.. doctest:: + + >>> mock = MagicMock() + >>> hasattr(mock, 'm') + True + >>> del mock.m + >>> hasattr(mock, 'm') + False + >>> del mock.f + >>> mock.f + Traceback (most recent call last): + ... + AttributeError: f + + +Attaching Mocks as Attributes +============================= + +When you attach a mock as an attribute of another mock (or as the return +value) it becomes a "child" of that mock. Calls to the child are recorded in +the :attr:`~Mock.method_calls` and :attr:`~Mock.mock_calls` attributes of the +parent. This is useful for configuring child mocks and then attaching them to +the parent, or for attaching mocks to a parent that records all calls to the +children and allows you to make assertions about the order of calls between +mocks: + +.. doctest:: + + >>> parent = MagicMock() + >>> child1 = MagicMock(return_value=None) + >>> child2 = MagicMock(return_value=None) + >>> parent.child1 = child1 + >>> parent.child2 = child2 + >>> child1(1) + >>> child2(2) + >>> parent.mock_calls + [call.child1(1), call.child2(2)] + +The exception to this is if the mock has a name. This allows you to prevent +the "parenting" if for some reason you don't want it to happen. + +.. doctest:: + + >>> mock = MagicMock() + >>> not_a_child = MagicMock(name='not-a-child') + >>> mock.attribute = not_a_child + >>> mock.attribute() + <MagicMock name='not-a-child()' id='...'> + >>> mock.mock_calls + [] + +Mocks created for you by :func:`patch` are automatically given names. To +attach mocks that have names to a parent you use the :meth:`~Mock.attach_mock` +method: + +.. doctest:: + + >>> thing1 = object() + >>> thing2 = object() + >>> parent = MagicMock() + >>> with patch('__main__.thing1', return_value=None) as child1: + ... with patch('__main__.thing2', return_value=None) as child2: + ... parent.attach_mock(child1, 'child1') + ... parent.attach_mock(child2, 'child2') + ... child1('one') + ... child2('two') + ... + >>> parent.mock_calls + [call.child1('one'), call.child2('two')] + + +----- + +.. [#] The only exceptions are magic methods and attributes (those that have + leading and trailing double underscores). Mock doesn't create these but + instead of raises an ``AttributeError``. This is because the interpreter + will often implicitly request these methods, and gets *very* confused to + get a new Mock object when it expects a magic method. If you need magic + method support see :ref:`magic methods <magic-methods>`. diff --git a/third_party/python/mock-1.0.0/docs/patch.txt b/third_party/python/mock-1.0.0/docs/patch.txt new file mode 100644 index 0000000000..3d56264fbb --- /dev/null +++ b/third_party/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 + <http://pypi.python.org/pypi/unittest2>`_ cleanup functions make this + easier. + + .. doctest:: + + >>> class MyTest(TestCase): + ... def setUp(self): + ... patcher = patch('package.module.Class') + ... self.MockClass = patcher.start() + ... self.addCleanup(patcher.stop) + ... + ... def test_something(self): + ... assert package.module.Class is self.MockClass + ... + >>> MyTest('test_something').run() + + As an added bonus you no longer need to keep a reference to the `patcher` + object. + +It is also possible to stop all patches which have been started by using +`patch.stopall`. + +.. function:: patch.stopall + + Stop all active patches. Only stops patches started with `start`. + + +TEST_PREFIX +=========== + +All of the patchers can be used as class decorators. When used in this way +they wrap every test method on the class. The patchers recognise methods that +start with `test` as being test methods. This is the same way that the +`unittest.TestLoader` finds test methods by default. + +It is possible that you want to use a different prefix for your tests. You can +inform the patchers of the different prefix by setting `patch.TEST_PREFIX`: + +.. doctest:: + + >>> patch.TEST_PREFIX = 'foo' + >>> value = 3 + >>> + >>> @patch('__main__.value', 'not three') + ... class Thing(object): + ... def foo_one(self): + ... print value + ... def foo_two(self): + ... print value + ... + >>> + >>> Thing().foo_one() + not three + >>> Thing().foo_two() + not three + >>> value + 3 + + +Nesting Patch Decorators +======================== + +If you want to perform multiple patches then you can simply stack up the +decorators. + +You can stack up multiple patch decorators using this pattern: + +.. doctest:: + + >>> @patch.object(SomeClass, 'class_method') + ... @patch.object(SomeClass, 'static_method') + ... def test(mock1, mock2): + ... assert SomeClass.static_method is mock1 + ... assert SomeClass.class_method is mock2 + ... SomeClass.static_method('foo') + ... SomeClass.class_method('bar') + ... return mock1, mock2 + ... + >>> mock1, mock2 = test() + >>> mock1.assert_called_once_with('foo') + >>> mock2.assert_called_once_with('bar') + + +Note that the decorators are applied from the bottom upwards. This is the +standard way that Python applies decorators. The order of the created mocks +passed into your test function matches this order. + +Like all context-managers patches can be nested using contextlib's nested +function; *every* patching will appear in the tuple after "as": + +.. doctest:: + + >>> from contextlib import nested + >>> with nested( + ... patch('package.module.ClassName1'), + ... patch('package.module.ClassName2') + ... ) as (MockClass1, MockClass2): + ... assert package.module.ClassName1 is MockClass1 + ... assert package.module.ClassName2 is MockClass2 + ... + + +.. _where-to-patch: + +Where to patch +============== + +`patch` works by (temporarily) changing the object that a *name* points to with +another one. There can be many names pointing to any individual object, so +for patching to work you must ensure that you patch the name used by the system +under test. + +The basic principle is that you patch where an object is *looked up*, which +is not necessarily the same place as where it is defined. A couple of +examples will help to clarify this. + +Imagine we have a project that we want to test with the following structure:: + + a.py + -> Defines SomeClass + + b.py + -> from a import SomeClass + -> some_function instantiates SomeClass + +Now we want to test `some_function` but we want to mock out `SomeClass` using +`patch`. The problem is that when we import module b, which we will have to +do then it imports `SomeClass` from module a. If we use `patch` to mock out +`a.SomeClass` then it will have no effect on our test; module b already has a +reference to the *real* `SomeClass` and it looks like our patching had no +effect. + +The key is to patch out `SomeClass` where it is used (or where it is looked up +). In this case `some_function` will actually look up `SomeClass` in module b, +where we have imported it. The patching should look like: + + `@patch('b.SomeClass')` + +However, consider the alternative scenario where instead of `from a import +SomeClass` module b does `import a` and `some_function` uses `a.SomeClass`. Both +of these import forms are common. In this case the class we want to patch is +being looked up on the a module and so we have to patch `a.SomeClass` instead: + + `@patch('a.SomeClass')` + + +Patching Descriptors and Proxy Objects +====================================== + +Since version 0.6.0 both patch_ and patch.object_ have been able to correctly +patch and restore descriptors: class methods, static methods and properties. +You should patch these on the *class* rather than an instance. + +Since version 0.7.0 patch_ and patch.object_ work correctly with some objects +that proxy attribute access, like the `django setttings object +<http://www.voidspace.org.uk/python/weblog/arch_d7_2010_12_04.shtml#e1198>`_. + +.. note:: + + In django `import settings` and `from django.conf import settings` + return different objects. If you are using libraries / apps that do both you + may have to patch both. Grrr... diff --git a/third_party/python/mock-1.0.0/docs/sentinel.txt b/third_party/python/mock-1.0.0/docs/sentinel.txt new file mode 100644 index 0000000000..1c5223da0e --- /dev/null +++ b/third_party/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 + + |