michael@0: .. currentmodule:: mock michael@0: michael@0: michael@0: CHANGELOG michael@0: ========= michael@0: michael@0: 2012/10/07 Version 1.0.0 michael@0: ------------------------ michael@0: michael@0: No changes since 1.0.0 beta 1. This version has feature parity with michael@0: `unittest.mock michael@0: `_ michael@0: in Python 3.3. michael@0: michael@0: Full list of changes since 0.8: michael@0: michael@0: * `mocksignature`, along with the `mocksignature` argument to `patch`, removed michael@0: * Support for deleting attributes (accessing deleted attributes will raise an michael@0: `AttributeError`) michael@0: * Added the `mock_open` helper function for mocking the builtin `open` michael@0: * `__class__` is assignable, so a mock can pass an `isinstance` check without michael@0: requiring a spec michael@0: * Addition of `PropertyMock`, for mocking properties michael@0: * `MagicMocks` made unorderable by default (in Python 3). The comparison michael@0: methods (other than equality and inequality) now return `NotImplemented` michael@0: * Propagate traceback info to support subclassing of `_patch` by other michael@0: libraries michael@0: * `create_autospec` works with attributes present in results of `dir` that michael@0: can't be fetched from the object's class. Contributed by Konstantine Rybnikov michael@0: * Any exceptions in an iterable `side_effect` will be raised instead of michael@0: returned michael@0: * In Python 3, `create_autospec` now supports keyword only arguments michael@0: * Added `patch.stopall` method to stop all active patches created by `start` michael@0: * BUGFIX: calling `MagicMock.reset_mock` wouldn't reset magic method mocks michael@0: * BUGFIX: calling `reset_mock` on a `MagicMock` created with autospec could michael@0: raise an exception michael@0: * BUGFIX: passing multiple spec arguments to patchers (`spec` , `spec_set` and michael@0: `autospec`) had unpredictable results, now it is an error michael@0: * BUGFIX: using `spec=True` *and* `create=True` as arguments to patchers could michael@0: result in using `DEFAULT` as the spec. Now it is an error instead michael@0: * BUGFIX: using `spec` or `autospec` arguments to patchers, along with michael@0: `spec_set=True` did not work correctly michael@0: * BUGFIX: using an object that evaluates to False as a spec could be ignored michael@0: * BUGFIX: a list as the `spec` argument to a patcher would always result in a michael@0: non-callable mock. Now if `__call__` is in the spec the mock is callable michael@0: michael@0: michael@0: 2012/07/13 Version 1.0.0 beta 1 michael@0: -------------------------------- michael@0: michael@0: * Added `patch.stopall` method to stop all active patches created by `start` michael@0: * BUGFIX: calling `MagicMock.reset_mock` wouldn't reset magic method mocks michael@0: * BUGFIX: calling `reset_mock` on a `MagicMock` created with autospec could michael@0: raise an exception michael@0: michael@0: michael@0: 2012/05/04 Version 1.0.0 alpha 2 michael@0: -------------------------------- michael@0: michael@0: * `PropertyMock` attributes are now standard `MagicMocks` michael@0: * `create_autospec` works with attributes present in results of `dir` that michael@0: can't be fetched from the object's class. Contributed by Konstantine Rybnikov michael@0: * Any exceptions in an iterable `side_effect` will be raised instead of michael@0: returned michael@0: * In Python 3, `create_autospec` now supports keyword only arguments michael@0: michael@0: michael@0: 2012/03/25 Version 1.0.0 alpha 1 michael@0: -------------------------------- michael@0: michael@0: The standard library version! michael@0: michael@0: * `mocksignature`, along with the `mocksignature` argument to `patch`, removed michael@0: * Support for deleting attributes (accessing deleted attributes will raise an michael@0: `AttributeError`) michael@0: * Added the `mock_open` helper function for mocking the builtin `open` michael@0: * `__class__` is assignable, so a mock can pass an `isinstance` check without michael@0: requiring a spec michael@0: * Addition of `PropertyMock`, for mocking properties michael@0: * `MagicMocks` made unorderable by default (in Python 3). The comparison michael@0: methods (other than equality and inequality) now return `NotImplemented` michael@0: * Propagate traceback info to support subclassing of `_patch` by other michael@0: libraries michael@0: * BUGFIX: passing multiple spec arguments to patchers (`spec` , `spec_set` and michael@0: `autospec`) had unpredictable results, now it is an error michael@0: * BUGFIX: using `spec=True` *and* `create=True` as arguments to patchers could michael@0: result in using `DEFAULT` as the spec. Now it is an error instead michael@0: * BUGFIX: using `spec` or `autospec` arguments to patchers, along with michael@0: `spec_set=True` did not work correctly michael@0: * BUGFIX: using an object that evaluates to False as a spec could be ignored michael@0: * BUGFIX: a list as the `spec` argument to a patcher would always result in a michael@0: non-callable mock. Now if `__call__` is in the spec the mock is callable michael@0: michael@0: michael@0: 2012/02/13 Version 0.8.0 michael@0: ------------------------ michael@0: michael@0: The only changes since 0.8rc2 are: michael@0: michael@0: * Improved repr of :data:`sentinel` objects michael@0: * :data:`ANY` can be used for comparisons against :data:`call` objects michael@0: * The return value of `MagicMock.__iter__` method can be set to michael@0: any iterable and isn't required to be an iterator michael@0: michael@0: Full List of changes since 0.7: michael@0: michael@0: mock 0.8.0 is the last version that will support Python 2.4. michael@0: michael@0: * Addition of :attr:`~Mock.mock_calls` list for *all* calls (including magic michael@0: methods and chained calls) michael@0: * :func:`patch` and :func:`patch.object` now create a :class:`MagicMock` michael@0: instead of a :class:`Mock` by default michael@0: * The patchers (`patch`, `patch.object` and `patch.dict`), plus `Mock` and michael@0: `MagicMock`, take arbitrary keyword arguments for configuration michael@0: * New mock method :meth:`~Mock.configure_mock` for setting attributes and michael@0: return values / side effects on the mock and its attributes michael@0: * New mock assert methods :meth:`~Mock.assert_any_call` and michael@0: :meth:`~Mock.assert_has_calls` michael@0: * Implemented :ref:`auto-speccing` (recursive, lazy speccing of mocks with michael@0: mocked signatures for functions/methods), as the `autospec` argument to michael@0: `patch` michael@0: * Added the :func:`create_autospec` function for manually creating michael@0: 'auto-specced' mocks michael@0: * :func:`patch.multiple` for doing multiple patches in a single call, using michael@0: keyword arguments michael@0: * Setting :attr:`~Mock.side_effect` to an iterable will cause calls to the mock michael@0: to return the next value from the iterable michael@0: * New `new_callable` argument to `patch` and `patch.object` allowing you to michael@0: pass in a class or callable object (instead of `MagicMock`) that will be michael@0: called to replace the object being patched michael@0: * Addition of :class:`NonCallableMock` and :class:`NonCallableMagicMock`, mocks michael@0: without a `__call__` method michael@0: * Addition of :meth:`~Mock.mock_add_spec` method for adding (or changing) a michael@0: spec on an existing mock michael@0: * Protocol methods on :class:`MagicMock` are magic mocks, and are created michael@0: lazily on first lookup. This means the result of calling a protocol method is michael@0: a `MagicMock` instead of a `Mock` as it was previously michael@0: * Addition of :meth:`~Mock.attach_mock` method michael@0: * Added :data:`ANY` for ignoring arguments in :meth:`~Mock.assert_called_with` michael@0: calls michael@0: * Addition of :data:`call` helper object michael@0: * Improved repr for mocks michael@0: * Improved repr for :attr:`Mock.call_args` and entries in michael@0: :attr:`Mock.call_args_list`, :attr:`Mock.method_calls` and michael@0: :attr:`Mock.mock_calls` michael@0: * Improved repr for :data:`sentinel` objects michael@0: * `patch` lookup is done at use time not at decoration time michael@0: * In Python 2.6 or more recent, `dir` on a mock will report all the dynamically michael@0: created attributes (or the full list of attributes if there is a spec) as michael@0: well as all the mock methods and attributes. michael@0: * Module level :data:`FILTER_DIR` added to control whether `dir(mock)` filters michael@0: private attributes. `True` by default. michael@0: * `patch.TEST_PREFIX` for controlling how patchers recognise test methods when michael@0: used to decorate a class michael@0: * Support for using Java exceptions as a :attr:`~Mock.side_effect` on Jython michael@0: * `Mock` call lists (`call_args_list`, `method_calls` & `mock_calls`) are now michael@0: custom list objects that allow membership tests for "sub lists" and have michael@0: a nicer representation if you `str` or `print` them michael@0: * Mocks attached as attributes or return values to other mocks have calls michael@0: recorded in `method_calls` and `mock_calls` of the parent (unless a name is michael@0: already set on the child) michael@0: * Improved failure messages for `assert_called_with` and michael@0: `assert_called_once_with` michael@0: * The return value of the :class:`MagicMock` `__iter__` method can be set to michael@0: any iterable and isn't required to be an iterator michael@0: * Added the Mock API (`assert_called_with` etc) to functions created by michael@0: :func:`mocksignature` michael@0: * Tuples as well as lists can be used to specify allowed methods for `spec` & michael@0: `spec_set` arguments michael@0: * Calling `stop` on an unstarted patcher fails with a more meaningful error michael@0: message michael@0: * Renamed the internal classes `Sentinel` and `SentinelObject` to prevent abuse michael@0: * BUGFIX: an error creating a patch, with nested patch decorators, won't leave michael@0: patches in place michael@0: * BUGFIX: `__truediv__` and `__rtruediv__` not available as magic methods on michael@0: mocks in Python 3 michael@0: * BUGFIX: `assert_called_with` / `assert_called_once_with` can be used with michael@0: `self` as a keyword argument michael@0: * BUGFIX: when patching a class with an explicit spec / spec_set (not a michael@0: boolean) it applies "spec inheritance" to the return value of the created michael@0: mock (the "instance") michael@0: * BUGFIX: remove the `__unittest` marker causing traceback truncation michael@0: * Removal of deprecated `patch_object` michael@0: * Private attributes `_name`, `_methods`, '_children', `_wraps` and `_parent` michael@0: (etc) renamed to reduce likelihood of clash with user attributes. michael@0: * Added license file to the distribution michael@0: michael@0: michael@0: 2012/01/10 Version 0.8.0 release candidate 2 michael@0: -------------------------------------------- michael@0: michael@0: * Removed the `configure` keyword argument to `create_autospec` and allow michael@0: arbitrary keyword arguments (for the `Mock` constructor) instead michael@0: * Fixed `ANY` equality with some types in `assert_called_with` calls michael@0: * Switched to a standard Sphinx theme (compatible with michael@0: `readthedocs.org `_) michael@0: michael@0: michael@0: 2011/12/29 Version 0.8.0 release candidate 1 michael@0: -------------------------------------------- michael@0: michael@0: * `create_autospec` on the return value of a mocked class will use `__call__` michael@0: for the signature rather than `__init__` michael@0: * Performance improvement instantiating `Mock` and `MagicMock` michael@0: * Mocks used as magic methods have the same type as their parent instead of michael@0: being hardcoded to `MagicMock` michael@0: michael@0: Special thanks to Julian Berman for his help with diagnosing and improving michael@0: performance in this release. michael@0: michael@0: michael@0: 2011/10/09 Version 0.8.0 beta 4 michael@0: ------------------------------- michael@0: michael@0: * `patch` lookup is done at use time not at decoration time michael@0: * When attaching a Mock to another Mock as a magic method, calls are recorded michael@0: in mock_calls michael@0: * Addition of `attach_mock` method michael@0: * Renamed the internal classes `Sentinel` and `SentinelObject` to prevent abuse michael@0: * BUGFIX: various issues around circular references with mocks (setting a mock michael@0: return value to be itself etc) michael@0: michael@0: michael@0: 2011/08/15 Version 0.8.0 beta 3 michael@0: ------------------------------- michael@0: michael@0: * Mocks attached as attributes or return values to other mocks have calls michael@0: recorded in `method_calls` and `mock_calls` of the parent (unless a name is michael@0: already set on the child) michael@0: * Addition of `mock_add_spec` method for adding (or changing) a spec on an michael@0: existing mock michael@0: * Improved repr for `Mock.call_args` and entries in `Mock.call_args_list`, michael@0: `Mock.method_calls` and `Mock.mock_calls` michael@0: * Improved repr for mocks michael@0: * BUGFIX: minor fixes in the way `mock_calls` is worked out, michael@0: especially for "intermediate" mocks in a call chain michael@0: michael@0: michael@0: 2011/08/05 Version 0.8.0 beta 2 michael@0: ------------------------------- michael@0: michael@0: * Setting `side_effect` to an iterable will cause calls to the mock to return michael@0: the next value from the iterable michael@0: * Added `assert_any_call` method michael@0: * Moved `assert_has_calls` from call lists onto mocks michael@0: * BUGFIX: `call_args` and all members of `call_args_list` are two tuples of michael@0: `(args, kwargs)` again instead of three tuples of `(name, args, kwargs)` michael@0: michael@0: michael@0: 2011/07/25 Version 0.8.0 beta 1 michael@0: ------------------------------- michael@0: michael@0: * `patch.TEST_PREFIX` for controlling how patchers recognise test methods when michael@0: used to decorate a class michael@0: * `Mock` call lists (`call_args_list`, `method_calls` & `mock_calls`) are now michael@0: custom list objects that allow membership tests for "sub lists" and have michael@0: an `assert_has_calls` method for unordered call checks michael@0: * `callargs` changed to *always* be a three-tuple of `(name, args, kwargs)` michael@0: * Addition of `mock_calls` list for *all* calls (including magic methods and michael@0: chained calls) michael@0: * Extension of `call` object to support chained calls and `callargs` for better michael@0: comparisons with or without names. `call` object has a `call_list` method for michael@0: chained calls michael@0: * Added the public `instance` argument to `create_autospec` michael@0: * Support for using Java exceptions as a `side_effect` on Jython michael@0: * Improved failure messages for `assert_called_with` and michael@0: `assert_called_once_with` michael@0: * Tuples as well as lists can be used to specify allowed methods for `spec` & michael@0: `spec_set` arguments michael@0: * BUGFIX: Fixed bug in `patch.multiple` for argument passing when creating michael@0: mocks michael@0: * Added license file to the distribution michael@0: michael@0: michael@0: 2011/07/16 Version 0.8.0 alpha 2 michael@0: -------------------------------- michael@0: michael@0: * `patch.multiple` for doing multiple patches in a single call, using keyword michael@0: arguments michael@0: * New `new_callable` argument to `patch` and `patch.object` allowing you to michael@0: pass in a class or callable object (instead of `MagicMock`) that will be michael@0: called to replace the object being patched michael@0: * Addition of `NonCallableMock` and `NonCallableMagicMock`, mocks without a michael@0: `__call__` method michael@0: * Mocks created by `patch` have a `MagicMock` as the `return_value` where a michael@0: class is being patched michael@0: * `create_autospec` can create non-callable mocks for non-callable objects. michael@0: `return_value` mocks of classes will be non-callable unless the class has michael@0: a `__call__` method michael@0: * `autospec` creates a `MagicMock` without a spec for properties and slot michael@0: descriptors, because we don't know the type of object they return michael@0: * Removed the "inherit" argument from `create_autospec` michael@0: * Calling `stop` on an unstarted patcher fails with a more meaningful error michael@0: message michael@0: * BUGFIX: an error creating a patch, with nested patch decorators, won't leave michael@0: patches in place michael@0: * BUGFIX: `__truediv__` and `__rtruediv__` not available as magic methods on michael@0: mocks in Python 3 michael@0: * BUGFIX: `assert_called_with` / `assert_called_once_with` can be used with michael@0: `self` as a keyword argument michael@0: * BUGFIX: autospec for functions / methods with an argument named self that michael@0: isn't the first argument no longer broken michael@0: * BUGFIX: when patching a class with an explicit spec / spec_set (not a michael@0: boolean) it applies "spec inheritance" to the return value of the created michael@0: mock (the "instance") michael@0: * BUGFIX: remove the `__unittest` marker causing traceback truncation michael@0: michael@0: michael@0: 2011/06/14 Version 0.8.0 alpha 1 michael@0: -------------------------------- michael@0: michael@0: mock 0.8.0 is the last version that will support Python 2.4. michael@0: michael@0: * The patchers (`patch`, `patch.object` and `patch.dict`), plus `Mock` and michael@0: `MagicMock`, take arbitrary keyword arguments for configuration michael@0: * New mock method `configure_mock` for setting attributes and return values / michael@0: side effects on the mock and its attributes michael@0: * In Python 2.6 or more recent, `dir` on a mock will report all the dynamically michael@0: created attributes (or the full list of attributes if there is a spec) as michael@0: well as all the mock methods and attributes. michael@0: * Module level `FILTER_DIR` added to control whether `dir(mock)` filters michael@0: private attributes. `True` by default. Note that `vars(Mock())` can still be michael@0: used to get all instance attributes and `dir(type(Mock())` will still return michael@0: all the other attributes (irrespective of `FILTER_DIR`) michael@0: * `patch` and `patch.object` now create a `MagicMock` instead of a `Mock` by michael@0: default michael@0: * Added `ANY` for ignoring arguments in `assert_called_with` calls michael@0: * Addition of `call` helper object michael@0: * Protocol methods on `MagicMock` are magic mocks, and are created lazily on michael@0: first lookup. This means the result of calling a protocol method is a michael@0: MagicMock instead of a Mock as it was previously michael@0: * Added the Mock API (`assert_called_with` etc) to functions created by michael@0: `mocksignature` michael@0: * Private attributes `_name`, `_methods`, '_children', `_wraps` and `_parent` michael@0: (etc) renamed to reduce likelihood of clash with user attributes. michael@0: * Implemented auto-speccing (recursive, lazy speccing of mocks with mocked michael@0: signatures for functions/methods) michael@0: michael@0: Limitations: michael@0: michael@0: - Doesn't mock magic methods or attributes (it creates MagicMocks, so the michael@0: magic methods are *there*, they just don't have the signature mocked nor michael@0: are attributes followed) michael@0: - Doesn't mock function / method attributes michael@0: - Uses object traversal on the objects being mocked to determine types - so michael@0: properties etc may be triggered michael@0: - The return value of mocked classes (the 'instance') has the same call michael@0: signature as the class __init__ (as they share the same spec) michael@0: michael@0: You create auto-specced mocks by passing `autospec=True` to `patch`. michael@0: michael@0: Note that attributes that are None are special cased and mocked without a michael@0: spec (so any attribute / method can be used). This is because None is michael@0: typically used as a default value for attributes that may be of some other michael@0: type, and as we don't know what type that may be we allow all access. michael@0: michael@0: Note that the `autospec` option to `patch` obsoletes the `mocksignature` michael@0: option. michael@0: michael@0: * Added the `create_autospec` function for manually creating 'auto-specced' michael@0: mocks michael@0: * Removal of deprecated `patch_object` michael@0: michael@0: michael@0: 2011/05/30 Version 0.7.2 michael@0: ------------------------ michael@0: michael@0: * BUGFIX: instances of list subclasses can now be used as mock specs michael@0: * BUGFIX: MagicMock equality / inequality protocol methods changed to use the michael@0: default equality / inequality. This is done through a `side_effect` on michael@0: the mocks used for `__eq__` / `__ne__` michael@0: michael@0: michael@0: 2011/05/06 Version 0.7.1 michael@0: ------------------------ michael@0: michael@0: Package fixes contributed by Michael Fladischer. No code changes. michael@0: michael@0: * Include template in package michael@0: * Use isolated binaries for the tox tests michael@0: * Unset executable bit on docs michael@0: * Fix DOS line endings in getting-started.txt michael@0: michael@0: michael@0: 2011/03/05 Version 0.7.0 michael@0: ------------------------ michael@0: michael@0: No API changes since 0.7.0 rc1. Many documentation changes including a stylish michael@0: new `Sphinx theme `_. michael@0: michael@0: The full set of changes since 0.6.0 are: michael@0: michael@0: * Python 3 compatibility michael@0: * Ability to mock magic methods with `Mock` and addition of `MagicMock` michael@0: with pre-created magic methods michael@0: * Addition of `mocksignature` and `mocksignature` argument to `patch` and michael@0: `patch.object` michael@0: * Addition of `patch.dict` for changing dictionaries during a test michael@0: * Ability to use `patch`, `patch.object` and `patch.dict` as class decorators michael@0: * Renamed ``patch_object`` to `patch.object` (``patch_object`` is michael@0: deprecated) michael@0: * Addition of soft comparisons: `call_args`, `call_args_list` and `method_calls` michael@0: now return tuple-like objects which compare equal even when empty args michael@0: or kwargs are skipped michael@0: * patchers (`patch`, `patch.object` and `patch.dict`) have start and stop michael@0: methods michael@0: * Addition of `assert_called_once_with` method michael@0: * Mocks can now be named (`name` argument to constructor) and the name is used michael@0: in the repr michael@0: * repr of a mock with a spec includes the class name of the spec michael@0: * `assert_called_with` works with `python -OO` michael@0: * New `spec_set` keyword argument to `Mock` and `patch`. If used, michael@0: attempting to *set* an attribute on a mock not on the spec will raise an michael@0: `AttributeError` michael@0: * Mocks created with a spec can now pass `isinstance` tests (`__class__` michael@0: returns the type of the spec) michael@0: * Added docstrings to all objects michael@0: * Improved failure message for `Mock.assert_called_with` when the mock michael@0: has not been called at all michael@0: * Decorated functions / methods have their docstring and `__module__` michael@0: preserved on Python 2.4. michael@0: * BUGFIX: `mock.patch` now works correctly with certain types of objects that michael@0: proxy attribute access, like the django settings object michael@0: * BUGFIX: mocks are now copyable (thanks to Ned Batchelder for reporting and michael@0: diagnosing this) michael@0: * BUGFIX: `spec=True` works with old style classes michael@0: * BUGFIX: ``help(mock)`` works now (on the module). Can no longer use ``__bases__`` michael@0: as a valid sentinel name (thanks to Stephen Emslie for reporting and michael@0: diagnosing this) michael@0: * BUGFIX: ``side_effect`` now works with ``BaseException`` exceptions like michael@0: ``KeyboardInterrupt`` michael@0: * BUGFIX: `reset_mock` caused infinite recursion when a mock is set as its own michael@0: return value michael@0: * BUGFIX: patching the same object twice now restores the patches correctly michael@0: * with statement tests now skipped on Python 2.4 michael@0: * Tests require unittest2 (or unittest2-py3k) to run michael@0: * Tested with `tox `_ on Python 2.4 - 3.2, michael@0: jython and pypy (excluding 3.0) michael@0: * Added 'build_sphinx' command to setup.py (requires setuptools or distribute) michael@0: Thanks to Florian Bauer michael@0: * Switched from subversion to mercurial for source code control michael@0: * `Konrad Delong `_ added as co-maintainer michael@0: michael@0: michael@0: 2011/02/16 Version 0.7.0 RC 1 michael@0: ----------------------------- michael@0: michael@0: Changes since beta 4: michael@0: michael@0: * Tested with jython, pypy and Python 3.2 and 3.1 michael@0: * Decorated functions / methods have their docstring and `__module__` michael@0: preserved on Python 2.4 michael@0: * BUGFIX: `mock.patch` now works correctly with certain types of objects that michael@0: proxy attribute access, like the django settings object michael@0: * BUGFIX: `reset_mock` caused infinite recursion when a mock is set as its own michael@0: return value michael@0: michael@0: michael@0: 2010/11/12 Version 0.7.0 beta 4 michael@0: ------------------------------- michael@0: michael@0: * patchers (`patch`, `patch.object` and `patch.dict`) have start and stop michael@0: methods michael@0: * Addition of `assert_called_once_with` method michael@0: * repr of a mock with a spec includes the class name of the spec michael@0: * `assert_called_with` works with `python -OO` michael@0: * New `spec_set` keyword argument to `Mock` and `patch`. If used, michael@0: attempting to *set* an attribute on a mock not on the spec will raise an michael@0: `AttributeError` michael@0: * Attributes and return value of a `MagicMock` are `MagicMock` objects michael@0: * Attempting to set an unsupported magic method now raises an `AttributeError` michael@0: * `patch.dict` works as a class decorator michael@0: * Switched from subversion to mercurial for source code control michael@0: * BUGFIX: mocks are now copyable (thanks to Ned Batchelder for reporting and michael@0: diagnosing this) michael@0: * BUGFIX: `spec=True` works with old style classes michael@0: * BUGFIX: `mocksignature=True` can now patch instance methods via michael@0: `patch.object` michael@0: michael@0: michael@0: 2010/09/18 Version 0.7.0 beta 3 michael@0: ------------------------------- michael@0: michael@0: * Using spec with :class:`MagicMock` only pre-creates magic methods in the spec michael@0: * Setting a magic method on a mock with a ``spec`` can only be done if the michael@0: spec has that method michael@0: * Mocks can now be named (`name` argument to constructor) and the name is used michael@0: in the repr michael@0: * `mocksignature` can now be used with classes (signature based on `__init__`) michael@0: and callable objects (signature based on `__call__`) michael@0: * Mocks created with a spec can now pass `isinstance` tests (`__class__` michael@0: returns the type of the spec) michael@0: * Default numeric value for MagicMock is 1 rather than zero (because the michael@0: MagicMock bool defaults to True and 0 is False) michael@0: * Improved failure message for :meth:`~Mock.assert_called_with` when the mock michael@0: has not been called at all michael@0: * Adding the following to the set of supported magic methods: michael@0: michael@0: - ``__getformat__`` and ``__setformat__`` michael@0: - pickle methods michael@0: - ``__trunc__``, ``__ceil__`` and ``__floor__`` michael@0: - ``__sizeof__`` michael@0: michael@0: * Added 'build_sphinx' command to setup.py (requires setuptools or distribute) michael@0: Thanks to Florian Bauer michael@0: * with statement tests now skipped on Python 2.4 michael@0: * Tests require unittest2 to run on Python 2.7 michael@0: * Improved several docstrings and documentation michael@0: michael@0: michael@0: 2010/06/23 Version 0.7.0 beta 2 michael@0: ------------------------------- michael@0: michael@0: * :func:`patch.dict` works as a context manager as well as a decorator michael@0: * ``patch.dict`` takes a string to specify dictionary as well as a dictionary michael@0: object. If a string is supplied the name specified is imported michael@0: * BUGFIX: ``patch.dict`` restores dictionary even when an exception is raised michael@0: michael@0: michael@0: 2010/06/22 Version 0.7.0 beta 1 michael@0: ------------------------------- michael@0: michael@0: * Addition of :func:`mocksignature` michael@0: * Ability to mock magic methods michael@0: * Ability to use ``patch`` and ``patch.object`` as class decorators michael@0: * Renamed ``patch_object`` to :func:`patch.object` (``patch_object`` is michael@0: deprecated) michael@0: * Addition of :class:`MagicMock` class with all magic methods pre-created for you michael@0: * Python 3 compatibility (tested with 3.2 but should work with 3.0 & 3.1 as michael@0: well) michael@0: * Addition of :func:`patch.dict` for changing dictionaries during a test michael@0: * Addition of ``mocksignature`` argument to ``patch`` and ``patch.object`` michael@0: * ``help(mock)`` works now (on the module). Can no longer use ``__bases__`` michael@0: as a valid sentinel name (thanks to Stephen Emslie for reporting and michael@0: diagnosing this) michael@0: * Addition of soft comparisons: `call_args`, `call_args_list` and `method_calls` michael@0: now return tuple-like objects which compare equal even when empty args michael@0: or kwargs are skipped michael@0: * Added docstrings. michael@0: * BUGFIX: ``side_effect`` now works with ``BaseException`` exceptions like michael@0: ``KeyboardInterrupt`` michael@0: * BUGFIX: patching the same object twice now restores the patches correctly michael@0: * The tests now require `unittest2 `_ michael@0: to run michael@0: * `Konrad Delong `_ added as co-maintainer michael@0: michael@0: michael@0: 2009/08/22 Version 0.6.0 michael@0: ------------------------ michael@0: michael@0: * New test layout compatible with test discovery michael@0: * Descriptors (static methods / class methods etc) can now be patched and michael@0: restored correctly michael@0: * Mocks can raise exceptions when called by setting ``side_effect`` to an michael@0: exception class or instance michael@0: * Mocks that wrap objects will not pass on calls to the underlying object if michael@0: an explicit return_value is set michael@0: michael@0: michael@0: 2009/04/17 Version 0.5.0 michael@0: ------------------------ michael@0: michael@0: * Made DEFAULT part of the public api. michael@0: * Documentation built with Sphinx. michael@0: * ``side_effect`` is now called with the same arguments as the mock is called with and michael@0: if returns a non-DEFAULT value that is automatically set as the ``mock.return_value``. michael@0: * ``wraps`` keyword argument used for wrapping objects (and passing calls through to the wrapped object). michael@0: * ``Mock.reset`` renamed to ``Mock.reset_mock``, as reset is a common API name. michael@0: * ``patch`` / ``patch_object`` are now context managers and can be used with ``with``. michael@0: * A new 'create' keyword argument to patch and patch_object that allows them to patch michael@0: (and unpatch) attributes that don't exist. (Potentially unsafe to use - it can allow michael@0: you to have tests that pass when they are testing an API that doesn't exist - use at michael@0: your own risk!) michael@0: * The methods keyword argument to Mock has been removed and merged with spec. The spec michael@0: argument can now be a list of methods or an object to take the spec from. michael@0: * Nested patches may now be applied in a different order (created mocks passed michael@0: in the opposite order). This is actually a bugfix. michael@0: * patch and patch_object now take a spec keyword argument. If spec is michael@0: passed in as 'True' then the Mock created will take the object it is replacing michael@0: as its spec object. If the object being replaced is a class, then the return michael@0: value for the mock will also use the class as a spec. michael@0: * A Mock created without a spec will not attempt to mock any magic methods / attributes michael@0: (they will raise an ``AttributeError`` instead). michael@0: michael@0: michael@0: 2008/10/12 Version 0.4.0 michael@0: ------------------------ michael@0: michael@0: * Default return value is now a new mock rather than None michael@0: * return_value added as a keyword argument to the constructor michael@0: * New method 'assert_called_with' michael@0: * Added 'side_effect' attribute / keyword argument called when mock is called michael@0: * patch decorator split into two decorators: michael@0: michael@0: - ``patch_object`` which takes an object and an attribute name to patch michael@0: (plus optionally a value to patch with which defaults to a mock object) michael@0: - ``patch`` which takes a string specifying a target to patch; in the form michael@0: 'package.module.Class.attribute'. (plus optionally a value to michael@0: patch with which defaults to a mock object) michael@0: michael@0: * Can now patch objects with ``None`` michael@0: * Change to patch for nose compatibility with error reporting in wrapped functions michael@0: * Reset no longer clears children / return value etc - it just resets michael@0: call count and call args. It also calls reset on all children (and michael@0: the return value if it is a mock). michael@0: michael@0: Thanks to Konrad Delong, Kevin Dangoor and others for patches and suggestions. michael@0: michael@0: michael@0: 2007/12/03 Version 0.3.1 michael@0: ------------------------- michael@0: michael@0: ``patch`` maintains the name of decorated functions for compatibility with nose michael@0: test autodiscovery. michael@0: michael@0: Tests decorated with ``patch`` that use the two argument form (implicit mock michael@0: creation) will receive the mock(s) passed in as extra arguments. michael@0: michael@0: Thanks to Kevin Dangoor for these changes. michael@0: michael@0: michael@0: 2007/11/30 Version 0.3.0 michael@0: ------------------------- michael@0: michael@0: Removed ``patch_module``. ``patch`` can now take a string as the first michael@0: argument for patching modules. michael@0: michael@0: The third argument to ``patch`` is optional - a mock will be created by michael@0: default if it is not passed in. michael@0: michael@0: michael@0: 2007/11/21 Version 0.2.1 michael@0: ------------------------- michael@0: michael@0: Bug fix, allows reuse of functions decorated with ``patch`` and ``patch_module``. michael@0: michael@0: michael@0: 2007/11/20 Version 0.2.0 michael@0: ------------------------- michael@0: michael@0: Added ``spec`` keyword argument for creating ``Mock`` objects from a michael@0: specification object. michael@0: michael@0: Added ``patch`` and ``patch_module`` monkey patching decorators. michael@0: michael@0: Added ``sentinel`` for convenient access to unique objects. michael@0: michael@0: Distribution includes unit tests. michael@0: michael@0: michael@0: 2007/11/19 Version 0.1.0 michael@0: ------------------------- michael@0: michael@0: Initial release. michael@0: michael@0: michael@0: TODO and Limitations michael@0: ==================== michael@0: michael@0: Contributions, bug reports and comments welcomed! michael@0: michael@0: Feature requests and bug reports are handled on the issue tracker: michael@0: michael@0: * `mock issue tracker `_ michael@0: michael@0: `wraps` is not integrated with magic methods. michael@0: michael@0: `patch` could auto-do the patching in the constructor and unpatch in the michael@0: destructor. This would be useful in itself, but violates TOOWTDI and would be michael@0: unsafe for IronPython & PyPy (non-deterministic calling of destructors). michael@0: Destructors aren't called in CPython where there are cycles, but a weak michael@0: reference with a callback can be used to get round this. michael@0: michael@0: `Mock` has several attributes. This makes it unsuitable for mocking objects michael@0: that use these attribute names. A way round this would be to provide methods michael@0: that *hide* these attributes when needed. In 0.8 many, but not all, of these michael@0: attributes are renamed to gain a `_mock` prefix, making it less likely that michael@0: they will clash. Any outstanding attributes that haven't been modified with michael@0: the prefix should be changed. michael@0: michael@0: If a patch is started using `patch.start` and then not stopped correctly then michael@0: the unpatching is not done. Using weak references it would be possible to michael@0: detect and fix this when the patch object itself is garbage collected. This michael@0: would be tricky to get right though. michael@0: michael@0: When a `Mock` is created by `patch`, arbitrary keywords can be used to set michael@0: attributes. If `patch` is created with a `spec`, and is replacing a class, then michael@0: a `return_value` mock is created. The keyword arguments are not applied to the michael@0: child mock, but could be. michael@0: michael@0: When mocking a class with `patch`, passing in `spec=True` or `autospec=True`, michael@0: the mock class has an instance created from the same spec. Should this be the michael@0: default behaviour for mocks anyway (mock return values inheriting the spec michael@0: from their parent), or should it be controlled by an additional keyword michael@0: argument (`inherit`) to the Mock constructor? `create_autospec` does this, so michael@0: an additional keyword argument to Mock is probably unnecessary. michael@0: michael@0: The `mocksignature` argument to `patch` with a non `Mock` passed into michael@0: `new_callable` will *probably* cause an error. Should it just be invalid? michael@0: michael@0: Note that `NonCallableMock` and `NonCallableMagicMock` still have the unused michael@0: (and unusable) attributes: `return_value`, `side_effect`, `call_count`, michael@0: `call_args` and `call_args_list`. These could be removed or raise errors on michael@0: getting / setting. They also have the `assert_called_with` and michael@0: `assert_called_once_with` methods. Removing these would be pointless as michael@0: fetching them would create a mock (attribute) that could be called without michael@0: error. michael@0: michael@0: Some outstanding technical debt. The way autospeccing mocks function michael@0: signatures was copied and modified from `mocksignature`. This could all be michael@0: refactored into one set of functions instead of two. The way we tell if michael@0: patchers are started and if a patcher is being used for a `patch.multiple` michael@0: call are both horrible. There are now a host of helper functions that should michael@0: be rationalised. (Probably time to split mock into a package instead of a michael@0: module.) michael@0: michael@0: Passing arbitrary keyword arguments to `create_autospec`, or `patch` with michael@0: `autospec`, when mocking a *function* works fine. However, the arbitrary michael@0: attributes are set on the created mock - but `create_autospec` returns a michael@0: real function (which doesn't have those attributes). However, what is the use michael@0: case for using autospec to create functions with attributes that don't exist michael@0: on the original? michael@0: michael@0: `mocksignature`, plus the `call_args_list` and `method_calls` attributes of michael@0: `Mock` could all be deprecated.