diff --git a/README.txt b/README.txt
index fd45eba46bc22aea6cedded66c7bc7d7d72a7908..db11006d5759afb220a1c5f9ad71f7591913978e 100644
--- a/README.txt
+++ b/README.txt
@@ -1,8 +1,12 @@
-mock is a Python module that provides a core Mock class. It removes the need
-to create a host of stubs throughout your test suite. After performing an
-action, you can make assertions about which methods / attributes were used and
-arguments they were called with. You can also specify return values and set
-needed attributes in the normal way.
+mock is 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 provides a core Mock class removing the need to create a host of stubs
+throughout your test suite. After performing an action, you can make
+assertions about which methods / attributes were used and arguments they were
+called with. You can also specify return values and set needed attributes in
+the normal way.
mock is tested on Python versions 2.4-2.7 and Python 3. mock is also tested
with the latest versions of Jython and pypy.
@@ -37,29 +41,31 @@ how they have been used::
3
>>> real.method.assert_called_with(3, 4, 5, key='value')
-``side_effect`` allows you to perform side effects, return different values or
+`side_effect` allows you to perform side effects, return different values or
raise an exception when a mock is called::
- >>> from mock import Mock
>>> mock = Mock(side_effect=KeyError('foo'))
>>> mock()
Traceback (most recent call last):
...
KeyError: 'foo'
- >>> values = [1, 2, 3]
- >>> def side_effect():
- ... return values.pop()
+ >>> values = {'a': 1, 'b': 2, 'c': 3}
+ >>> def side_effect(arg):
+ ... return values[arg]
...
>>> mock.side_effect = side_effect
- >>> mock(), mock(), mock()
+ >>> mock('a'), mock('b'), mock('c')
(3, 2, 1)
+ >>> mock.side_effect = [5, 4, 3, 2, 1]
+ >>> mock(), mock(), mock()
+ (5, 4, 3)
Mock has many other ways you can configure it and control its behaviour. For
-example the ``spec`` argument configures the mock to take its specification from
+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``.
+don't exist on the spec will fail with an `AttributeError`.
-The ``patch`` decorator / context manager makes it easy to mock classes or
+The `patch` decorator / context manager makes it easy to mock classes or
objects in a module under test. The object you specify will be replaced with a
mock (or other object) during the test and restored when the test ends::
@@ -109,7 +115,7 @@ test ends::
>>> assert foo == original
Mock now supports the mocking of Python magic methods. The easiest way of
-using magic methods is with the ``MagicMock`` class. It allows you to do
+using magic methods is with the `MagicMock` class. It allows you to do
things like::
>>> from mock import MagicMock
@@ -134,26 +140,30 @@ class::
>>> str(mock)
'wheeeeee'
-`mocksignature` is a useful companion to Mock and patch. It creates
-copies of functions that delegate to a mock, but have the same signature as the
-original function. This ensures that your mocks will fail in the same way as
-your production code if they are called incorrectly::
+For ensuring that the mock objects your tests use have the same api as the
+objects they are replacing, you can use "auto-speccing". Auto-speccing can
+be done through the `autospec` argument to patch, or the `create_autospec`
+function. Auto-speccing creates mock objects that have the same attributes
+and methods as the objects they are replacing, and any functions and methods
+(including constructors) have the same call signature as the real object.
+
+This ensures that your mocks will fail in the same way as your production
+code if they are used incorrectly::
- >>> from mock import mocksignature
+ >>> from mock import create_autospec
>>> def function(a, b, c):
... pass
...
- >>> function2 = mocksignature(function)
- >>> function2.mock.return_value = 'fishy'
- >>> function2(1, 2, 3)
+ >>> mock_function = create_autospec(function, return_value='fishy')
+ >>> mock_function(1, 2, 3)
'fishy'
- >>> function2.mock.assert_called_with(1, 2, 3)
- >>> function2('wrong arguments')
+ >>> 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)
-`mocksignature` can also be used on classes, where it copies the signature of
+`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.
diff --git a/docs/changelog.txt b/docs/changelog.txt
index ec3283af59baa6ecc9c7138b3b504bc36d74e8fa..f08d4a71fb5e59848de48f74fe22469d30260af3 100644
--- a/docs/changelog.txt
+++ b/docs/changelog.txt
@@ -116,7 +116,7 @@ mock 0.8.0 is the last version that will support Python 2.4.
* Improved repr for mocks
* Improved repr for `Mock.call_args` and entries in `Mock.call_args_list`,
`Mock.method_calls` and `Mock.mock_calls`
-* patch lookup is done at use time not at decoration time
+* `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.
@@ -158,10 +158,17 @@ mock 0.8.0 is the last version that will support Python 2.4.
* Added license file to the distribution
+2011/XX/XX Version 0.8.0 release candidate 1
+--------------------------------------------
+
+* `create_autospec` on the return value of a mock class will use `__call__`
+ for the signature rather than `__init__`
+
+
2011/10/09 Version 0.8.0 beta 4
-------------------------------
-* patch lookup is done at use time not at decoration time
+* `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
diff --git a/docs/helpers.txt b/docs/helpers.txt
new file mode 100644
index 0000000000000000000000000000000000000000..eff9a01866f516cbe468425ebc78d556816fd635
--- /dev/null
+++ b/docs/helpers.txt
@@ -0,0 +1,23 @@
+=========
+ Helpers
+=========
+
+.. currentmodule:: mock
+
+.. testsetup::
+
+ import sys, unittest2
+ from mock import MagicMock, Mock, patch
+
+
+call
+====
+
+create_autospec
+===============
+
+
+
+ANY
+===
+
diff --git a/docs/index.txt b/docs/index.txt
index 2a4a8620e6a194f7d8da73c385238eb34a5832d5..fab4601ad12b684f5029fde0b9149db79bad44c0 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -29,24 +29,29 @@
.. index:: introduction
-mock is a Python module that provides a core :class:`Mock` class. It removes
-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 module also 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 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 provides a core :class:`Mock` class removing the need to create a host
+of stubs throughout your test suite. After performing an action, you can make
+assertions about which methods / attributes were used and arguments they were
+called with. You can also specify return values and set needed attributes in
+the normal way.
+
+Additionally, mock provides a :func:`patch` decorator that handles patching
+module and class level attributes within the scope of a test, along with
+:const:`sentinel` for creating unique objects. See the `quick guide`_ for
+some examples of how to use :class:`Mock`, :class:`MagicMock` and
+:func:`patch`.
Mock is very easy to use and is designed for use with
`unittest <http://pypi.python.org/pypi/unittest2>`_. Mock is based on
the 'action -> assertion' pattern instead of `'record -> replay'` used by many
mocking frameworks.
-mock is tested on Python versions 2.4-2.7 and Python 3. mock is also tested with
-the latest versions of Jython and pypy.
+mock is tested on Python versions 2.4-2.7 and Python 3. mock is also tested
+with the latest versions of Jython and pypy.
.. testsetup::
@@ -70,6 +75,7 @@ API Documentation
mock
patch
+ helpers
sentinel
magicmock
mocksignature
@@ -86,6 +92,7 @@ User Guide
compare
changelog
+
.. index:: installing
Installing
@@ -127,10 +134,10 @@ unpacking run:
Quick Guide
===========
-:class:`Mock` objects create all attributes and methods as you access them and store
-details of how they have been used. You can configure them, to specify return
-values or limit what attributes are available, and then make assertions about
-how they have been used:
+: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::
@@ -151,13 +158,16 @@ values or raise an exception when a mock is called:
Traceback (most recent call last):
...
KeyError: 'foo'
- >>> values = [1, 2, 3]
- >>> def side_effect():
- ... return values.pop()
+ >>> values = {'a': 1, 'b': 2, 'c': 3}
+ >>> def side_effect(arg):
+ ... return values[arg]
...
>>> mock.side_effect = side_effect
- >>> mock(), mock(), mock()
+ >>> mock('a'), mock('b'), mock('c')
(3, 2, 1)
+ >>> mock.side_effect = [5, 4, 3, 2, 1]
+ >>> mock(), mock(), mock()
+ (5, 4, 3)
Mock has many other ways you can configure it and control its behaviour. For
example the ``spec`` argument configures the mock to take its specification from
diff --git a/docs/patch.txt b/docs/patch.txt
index 8a5ae60d7fc8472f4071dee5890a8016e04bd67b..03e649cb84f31f44dea1e188e33b1a3892b19121 100644
--- a/docs/patch.txt
+++ b/docs/patch.txt
@@ -280,9 +280,9 @@ 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 *used*, which is not
-necessarily the same place as where it is defined. A couple of examples will
-help to clarify this.
+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::
diff --git a/tests/testhelpers.py b/tests/testhelpers.py
index 6e2530c6ed5d4420522df3a1950339e31e1fb895..c9c405044830e2f3a6e3cb15d00ed69b8bcad483 100644
--- a/tests/testhelpers.py
+++ b/tests/testhelpers.py
@@ -646,6 +646,11 @@ class SpecSignatureTest(unittest2.TestCase):
mock.assert_called_once_with()
self.assertRaises(TypeError, mock, 'a')
+ instance = mock()
+ self.assertRaises(TypeError, instance)
+ instance(a='a')
+ instance.assert_called_once_with(a='a')
+
mock = create_autospec(Callable())
mock(a='a')
mock.assert_called_once_with(a='a')