Documentation update and failing test for create_autospec

6 files changed, 106 insertions, 51 deletions

diff --git a/README.txt b/README.txt
index fd45eba..db11006 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 ec3283a..f08d4a7 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 0000000..eff9a01
--- /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 2a4a862..fab4601 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 8a5ae60..03e649c 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 6e2530c..c9c4050 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')