Overhaul docs.
- Document backporting
- Reference the cPython dev docs for everything else.
- Test docs and package summary.
diff --git a/.gitignore b/.gitignore
index 8502ec1..93d1155 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,3 +15,6 @@
.*.swp
AUTHORS
ChangeLog
+.eggs
+README.saved
+README.html
diff --git a/.travis.yml b/.travis.yml
index ebc499f..7619dac 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -5,13 +5,19 @@
- "3.2"
- "3.3"
- "3.4"
- - "nightly"
- pypy
- pypy3
-# command to install dependencies
+matrix:
+ include:
+# Travis nightly look to be 3.5.0a4, b3 is out and the syntax error we see
+# doesn't happen in trunk.
+ - python: "nightly"
+ env: SKIP_DOCS=1
install:
- pip install -U pip
- pip install -U wheel setuptools
- - pip install .[test]
-# command to run tests
-script: unit2
+ - pip install -U .[docs,test]
+script:
+ - unit2
+ - if [ -z "$SKIP_DOCS" ]; then python setup.py build_sphinx; fi
+ - rst2html.py README.txt README.html
diff --git a/NEWS b/NEWS
index ab72135..2aa442a 100644
--- a/NEWS
+++ b/NEWS
@@ -7,7 +7,7 @@
- Issue #23581: Add matmul support to MagicMock. Patch by Håkan Lövdahl.
- Issue #23326: Removed __ne__ implementations. Since fixing default __ne__
- implementation in issue #21408 they are redundant. **** NOT BACKPORTED ****
+ implementation in issue #21408 they are redundant. *** NOT BACKPORTED ***
- Issue #21270: We now override tuple methods in mock.call objects so that
they can be used as normal call attributes.
diff --git a/README.txt b/README.txt
index b76a615..efb563a 100644
--- a/README.txt
+++ b/README.txt
@@ -11,32 +11,19 @@
Please see the standard library documentation for more details.
-mock is CI tested using Travis-CI on Python versions 2.7, 3.2, 3.3, 3.4, 3.5,
-nightly Python 3 builds, pypy, pypy3. Jython support is desired, if
-someone could contribute a patch to .travis.jml to support it that would be
-excellent.
+:Homepage: `Mock Homepage`_
+:Download: `Mock on PyPI`_
+:Documentation: `Python Docs`_
+:License: `BSD License`_
+:Support: `Mailing list (testing-in-python@lists.idyll.org)
+ <http://lists.idyll.org/listinfo/testing-in-python>`_
+:Issue tracker: `Github Issues
+ <https://github.com/testing-cabal/mock/issues>`_
+:Build status:
+ .. image:: https://travis-ci.org/testing-cabal/mock.svg?branch=master
+ :target: https://travis-ci.org/testing-cabal/mock
-The last release of mock to support 2.6 was 1.0.1. mock 1.1.0 and above require
-Python 2.7 or higher.
-
-NEWS entries from cPython:
-
-.. include:: NEWS
-
-Notes for maintainers
----------------------
-
-Releasing
-=========
-
-2. tag -s, push --tags origin master
-3. setup.py sdist bdist_wheel upload -s
-
-Backporting rules
-=================
-
-type -> ClassTypes
-__self__ -> self
-name.isidentifier() -> _isidentifier(name)
-super -> _super
-
+.. _Mock Homepage: https://github.com/testing-cabal/mock
+.. _BSD License: http://github.com/testing-cabal/mock/blob/master/LICENSE.txt
+.. _Python Docs: https://docs.python.org/dev/library/unittest.mock.html
+.. _mock on PyPI: http://pypi.python.org/pypi/mock
diff --git a/docs/changelog.txt b/docs/changelog.txt
deleted file mode 100644
index 823341a..0000000
--- a/docs/changelog.txt
+++ /dev/null
@@ -1,737 +0,0 @@
-.. currentmodule:: mock
-
-
-CHANGELOG
-=========
-
-2012/11/05 Version 1.0.1
-------------------------
-
-* Functions decorated with `patch` variants have a `__wrapped__` attribute
- pointing to the original function. This brings compatibility with the
- default behaviour in Python 3.3 (due to a new feature in `functools.wraps`).
-
-Note that due to changes in `tox`, `mock` is no longer tested with Python 2.4.
-The compatibility code has not been removed so it probably still works, but
-tests are no longer run.
-
-
-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/docs/changelog.txt b/docs/changelog.txt
new file mode 120000
index 0000000..22ec9b8
--- /dev/null
+++ b/docs/changelog.txt
@@ -0,0 +1 @@
+../ChangeLog
\ No newline at end of file
diff --git a/docs/compare.txt b/docs/compare.txt
deleted file mode 100644
index 4155530..0000000
--- a/docs/compare.txt
+++ /dev/null
@@ -1,628 +0,0 @@
-=========================
- 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/docs/conf.py b/docs/conf.py
index 62f0491..912c891 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -13,7 +13,6 @@
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
@@ -66,21 +65,21 @@
# General substitutions.
project = u'Mock'
-copyright = u'2007-2012, Michael Foord & the mock team'
+copyright = u'2007-2015, Michael Foord & the mock team'
# The default replacements for |version| and |release|, also used in various
-# other places throughout the built documents.
+# other places throughout the built documents. Supplied by pbr.
#
# The short X.Y version.
-version = __version__[:3]
+version = None
# The full version, including alpha/beta/rc tags.
-release = __version__
+release = None
# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
+# non-false value, then it is used: (Set from pbr)
+today = ''
# Else, today_fmt is used as the format for a strftime call.
-today_fmt = '%B %d, %Y'
+# today_fmt = '%B %d, %Y'
# List of documents that shouldn't be included in the build.
#unused_docs = []
@@ -206,4 +205,4 @@
#latex_appendices = []
# If false, no module index is generated.
-latex_use_modindex = False
\ No newline at end of file
+latex_use_modindex = False
diff --git a/docs/examples.txt b/docs/examples.txt
deleted file mode 100644
index ecb994b..0000000
--- a/docs/examples.txt
+++ /dev/null
@@ -1,1063 +0,0 @@
-.. _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/docs/getting-started.txt b/docs/getting-started.txt
deleted file mode 100644
index 1b5d289..0000000
--- a/docs/getting-started.txt
+++ /dev/null
@@ -1,479 +0,0 @@
-===========================
- 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/docs/helpers.txt b/docs/helpers.txt
deleted file mode 100644
index 571b71d..0000000
--- a/docs/helpers.txt
+++ /dev/null
@@ -1,583 +0,0 @@
-=========
- 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/docs/index.txt b/docs/index.txt
index fe89925..b840f45 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -2,129 +2,76 @@
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
+:Date: |today|
:Homepage: `Mock Homepage`_
:Download: `Mock on PyPI`_
-:Documentation: `PDF Documentation
- <http://www.voidspace.org.uk/downloads/mock-1.0.1.pdf>`_
+:Documentation: `Python Docs`_
: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>`_
+:Issue tracker: `Github Issues
+ <https://github.com/testing-cabal/mock/issues>`_
+:Last sync: 95211209f6c499f2f92b01a3372f9961d480abad
-.. _Mock Homepage: http://www.voidspace.org.uk/python/mock/
-.. _BSD License: http://www.voidspace.org.uk/python/license.shtml
-
-
-.. currentmodule:: mock
+.. _Mock Homepage: https://github.com/testing-cabal/mock
+.. _BSD License: http://github.com/testing-cabal/mock/blob/master/LICENSE.txt
+.. _Python Docs: https://docs.python.org/dev/library/unittest.mock.html
.. module:: mock
:synopsis: Mock object and testing library.
.. index:: introduction
+TOC
++++
+
+.. toctree::
+ :maxdepth: 2
+
+ changelog
+
+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 is now part of the Python standard library, available as
+``unittest.mock`` in Python 3.3 onwards. However, if you are writing code that
+runs on multiple versions of Python the ``mock`` package is better, as you get
+the newest features from the latest release of Python available for all
+Pythons.
-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.
+The ``mock`` package contains a rolling backport of the standard library mock
+code compatible with Python 2.7 and up, and 3.2 and up.
-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
-
+Please see the standard library documentation for usage details.
.. index:: installing
+.. _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.
+The current version is |release|. Mock is stable and widely used.
* `mock on PyPI <http://pypi.python.org/pypi/mock>`_
-* `mock documentation as PDF
- <http://www.voidspace.org.uk/downloads/mock-1.0.1.pdf>`_
-* `Google Code Home & Mercurial Repository <http://code.google.com/p/mock/>`_
.. index:: repository
-.. index:: hg
+.. index:: git
-You can checkout the latest development version from the Google Code Mercurial
+You can checkout the latest development version from Github
repository with the following command:
- ``hg clone https://mock.googlecode.com/hg/ mock``
+ ``git clone https://github.com/testing-cabal/mock``
.. index:: pip
-.. index:: easy_install
-.. index:: setuptools
-If you have pip, setuptools or distribute you can install mock with:
+You can install mock with pip:
- | ``easy_install -U mock``
| ``pip install -U mock``
Alternatively you can download the mock distribution from PyPI and after
@@ -133,279 +80,108 @@
``python setup.py install``
-Quick Guide
-===========
+.. index:: bug reports
-: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
-=====
+Bug Reports
++++++++++++
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:
+Issues with the backport process, such as compatibility with a particular
+Python, should be reported to the `bug tracker
+<https://github.com/testing-cabal/mock/issues>`_. Feature requests and issues
+with Mock functionality should be reported to the `Python bug tracker
+<https://bugs.python.org>`_.
- `unit2 discover`
+.. index:: python changes
-If you have `setuptools <http://pypi.python.org/pypi/distribute>`_ as well as
-unittest2 you can run:
+Python Changes
+++++++++++++++
- ``python setup.py test``
+Python NEWS entries from cPython:
-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.
-
+.. include:: ../NEWS
.. index:: older versions
Older Versions
-==============
+++++++++++++++
-Documentation for older versions of mock:
+Version 1.0.1 is the last version compatible with Python 2.6.
-* `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/>`_
+.. index:: maintainer notes
-Docs from the in-development version of `mock` can be found at
-`mock.readthedocs.org <http://mock.readthedocs.org>`_.
+Maintainer Notes
+++++++++++++++++
-
-Terminology
+Development
===========
-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.
+Checkout from git (see :ref:`installing`) and submit pull requests.
-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.
+Committers can just push as desired: since all semantic development takes
+place in cPython, the backport process is as lightweight as we can make it.
-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.
+mock is CI tested using Travis-CI on Python versions 2.7, 3.2, 3.3, 3.4, 3.5,
+nightly Python 3 builds, pypy, pypy3. Jython support is desired, if
+someone could contribute a patch to .travis.jml to support it that would be
+excellent.
-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.
+The last release of mock to support 2.6 was 1.0.1. mock 1.1.0 and above require
+Python 2.7 or higher.
-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!
+Releasing
+=========
-How about a simpler definition: a "mock object" is an object used to replace a
-real one in a system under test.
+1. tag -s, push --tags origin master
+2. setup.py sdist bdist_wheel upload -s
-.. [#] This pattern is called "AAA" by some members of the testing community;
- "Arrange - Act - Assert".
+
+Backporting rules
+=================
+
+isinstance checks in cPython to ``type`` need to check ``ClassTypes``.
+Code calling ``obj.isidentifier`` needs to change to ``_isidentifier(obj)``.
+
+Backporting process
+===================
+
+1. Patch your git am with `my patch <https://github.com/rbtcollins/git>`_.
+2. Install the applypatch-transform hook from tools/ to your .git hooks dir.
+3. Configure a pre-applypatch hook to test at least all the cPython versions
+ we support on each patch that is applied. I use containers, and a sample
+ script is in tools/pre-applypatch.
+4. Pull down the cPython git mirror: https://github.com/python/cpython.git
+5. Export the new revisions since the ``Last sync`` at the top of this
+ document::
+
+ revs=${lastsync}..
+ rm migrate-export
+ git log --pretty="format:%H " $revs -- Lib/unittest/mock.py \
+ Lib/unittest/test/testmock/ > migrate-revs
+ tac migrate-revs > migrate-sorted-revs
+ for rev in $(< migrate-sorted-revs); do
+ git format-patch -1 $rev -k --stdout >> migrate-export;
+ done
+ echo NEW SYNC POINT: $(git rev-parse HEAD)
+
+6. Import into mock::
+
+ git am -k --reject $path-to-cpython/migrate-export
+
+ This will transform the patches automatically. Currently it will error
+ on every NEWS change as I haven't gotten around to making those patches
+ automatic. Fixup any errors that occur. When the patch is ready, do a ``git
+ add -u`` to update the index and then ``git am --continue`` to move onto
+ the next patch. If the patch is inappropriate e.g. the patch removing
+ __ne__ which would break older pythons, then either do ``git reset --hard;
+ git am --skip`` to discard any partially applied changes and skip over it,
+ or, if it has a NEWS entry thats worth preserving, edit it down to just
+ that, with a note such as we have for the ``__ne__`` patch, and continue on
+ from there.
+
+ The goal is that every patch work at all times.
+
+7. After the import is complete, update this document with the new sync point.
+
+8. Push to a personal branch and propose a PR to the main repo. This will make
+ Travis-CI test it. If it works, push to the main repo.
diff --git a/docs/magicmock.txt b/docs/magicmock.txt
deleted file mode 100644
index 42b2ed9..0000000
--- a/docs/magicmock.txt
+++ /dev/null
@@ -1,258 +0,0 @@
-
-.. 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/docs/mock.txt b/docs/mock.txt
deleted file mode 100644
index 27a9c59..0000000
--- a/docs/mock.txt
+++ /dev/null
@@ -1,861 +0,0 @@
-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
-
-
-Mock names and the name attribute
-=================================
-
-Since "name" is an argument to the :class:`Mock` constructor, if you want your
-mock object to have a "name" attribute you can't just pass it in at creation
-time. There are two alternatives. One option is to use
-:meth:`~Mock.configure_mock`::
-
- >>> mock = MagicMock()
- >>> mock.configure_mock(name='my_name')
- >>> mock.name
- 'my_name'
-
-A simpler option is to simply set the "name" attribute after mock creation::
-
- >>> mock = MagicMock()
- >>> mock.name = "foo"
-
-
-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/docs/patch.txt b/docs/patch.txt
deleted file mode 100644
index 3d56264..0000000
--- a/docs/patch.txt
+++ /dev/null
@@ -1,636 +0,0 @@
-==================
- 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/docs/sentinel.txt b/docs/sentinel.txt
deleted file mode 100644
index 1c5223d..0000000
--- a/docs/sentinel.txt
+++ /dev/null
@@ -1,58 +0,0 @@
-==========
- Sentinel
-==========
-
-
-.. currentmodule:: mock
-
-.. testsetup::
-
- class ProductionClass(object):
- def something(self):
- return self.method()
-
- class Test(unittest2.TestCase):
- def testSomething(self):
- pass
- self = Test('testSomething')
-
-
-.. data:: sentinel
-
- The ``sentinel`` object provides a convenient way of providing unique
- objects for your tests.
-
- Attributes are created on demand when you access them by name. Accessing
- the same attribute will always return the same object. The objects
- returned have a sensible repr so that test failure messages are readable.
-
-
-.. data:: DEFAULT
-
- The `DEFAULT` object is a pre-created sentinel (actually
- `sentinel.DEFAULT`). It can be used by :attr:`~Mock.side_effect`
- functions to indicate that the normal return value should be used.
-
-
-Sentinel Example
-================
-
-Sometimes when testing you need to test that a specific object is passed as an
-argument to another method, or returned. It can be common to create named
-sentinel objects to test this. `sentinel` provides a convenient way of
-creating and testing the identity of objects like this.
-
-In this example we monkey patch `method` to return
-`sentinel.some_object`:
-
-.. doctest::
-
- >>> real = ProductionClass()
- >>> real.method = Mock(name="method")
- >>> real.method.return_value = sentinel.some_object
- >>> result = real.method()
- >>> assert result is sentinel.some_object
- >>> sentinel.some_object
- sentinel.some_object
-
-
diff --git a/setup.cfg b/setup.cfg
index 40b96e9..0736fbd 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -31,6 +31,11 @@
[extras]
test =
unittest2>=1.1.0
+docs =
+ jinja2<2.7:python_version<"3.3" and python_version>="3"
+ Pygments<2:python_version<"3.3" and python_version>="3"
+ sphinx<1.3:python_version<"3.3" and python_version>="3"
+ sphinx:python_version<"3" or python_version>="3.3"
[files]
packages = mock
diff --git a/tools/applypatch-transform b/tools/applypatch-transform
new file mode 100755
index 0000000..52fcd93
--- /dev/null
+++ b/tools/applypatch-transform
@@ -0,0 +1,38 @@
+#!/bin/sh
+#
+# An example hook script to transform a patch taken from an email
+# by git am.
+#
+# The hook should exit with non-zero status after issuing an
+# appropriate message if it wants to stop the commit. The hook is
+# allowed to edit the patch file.
+#
+# To enable this hook, rename this file to "applypatch-transform".
+#
+# This example changes the path of Lib/unittest/mock.py to mock.py
+# Lib/unittest/tests/testmock to tests and Misc/NEWS to NEWS, and
+# finally skips any patches that did not alter mock.py or its tests.
+
+set -eux
+
+patch_path=$1
+
+# Pull out mock.py
+filterdiff --clean --strip 3 --addprefix=a/mock/ -i 'a/Lib/unittest/mock.py' -i 'b/Lib/unittest/mock.py' $patch_path > $patch_path.mock
+# And the tests
+filterdiff --clean --strip 5 --addprefix=a/mock/tests/ -i 'a/Lib/unittest/test/testmock/*.py' -i 'b/Lib/unittest/test/testmock/*.py' $patch_path > $patch_path.tests
+# Lastly we want to pick up any NEWS entries.
+filterdiff --strip 2 --addprefix=a/ -i a/Misc/NEWS -i b/Misc/NEWS $patch_path > $patch_path.NEWS
+cp $patch_path $patch_path.orig
+# bash
+cat $patch_path.mock $patch_path.tests > $patch_path
+filtered=$(cat $patch_path)
+if [ -n "${filtered}" ]; then
+ cat $patch_path.NEWS >> $patch_path
+ exitcode=0
+else
+ exitcode=1
+fi
+
+rm $patch_path.mock $patch_path.tests $patch_path.NEWS
+exit $exitcode
diff --git a/tools/pre-applypatch b/tools/pre-applypatch
new file mode 100755
index 0000000..cc6afac
--- /dev/null
+++ b/tools/pre-applypatch
@@ -0,0 +1,37 @@
+#!/bin/bash
+#
+# An example hook script to verify what is about to be committed
+# by applypatch from an e-mail message.
+#
+# The hook should exit with non-zero status after issuing an
+# appropriate message if it wants to stop the commit.
+#
+# To enable this hook, rename this file to "pre-applypatch".
+
+set -eu
+
+#. git-sh-setup
+echo "** in hook **"
+
+function test_version {
+ version=$1
+ host=$(ls ~/.virtualenvs/mock-$version-* -d | sed -e "s/^.*mock-$version-//")
+ if [ -z "$host" ]; then
+ echo "No host found for $version"
+ return 1
+ fi
+ echo testing $version in virtualenv mock-$version-$host on ssh host $host
+ ssh $host "cd work/mock && . ~/.virtualenvs/mock-$version-$host/bin/activate && pip install .[test] && unit2"
+}
+
+find . -name "*.pyc" -exec rm "{}" \;
+
+test_version 2.7
+test_version 3.2
+test_version 3.3
+test_version 3.4
+test_version 3.5
+test_version cpython
+test_version pypy
+
+echo '** pre-apply complete and successful **'
