python-peps/peps/pep-0417.rst

PEP: 417
Title: Including mock in the Standard Library
Version: $Revision$
Last-Modified: $Date$
Author: Michael Foord <michael@python.org>
Status: Final
Type: Standards Track
Content-Type: text/x-rst
Created: 12-Mar-2012
Python-Version: 3.3
Post-History: 12-Mar-2012
Resolution: https://mail.python.org/pipermail/python-dev/2012-March/117507.html


Abstract
========

This PEP proposes adding the mock [1]_ testing library
to the Python standard library as ``unittest.mock``.


Rationale
=========

Creating mock objects for testing is a common need in Python.
Many developers create ad-hoc mocks, as needed, in their test
suites. This is currently what we do in the Python test suite,
where a standardised mock object library would be helpful.

There are many mock object libraries available for Python [2]_.
Of these, mock is overwhelmingly the most popular, with as many
downloads on PyPI as the other mocking libraries combined.

An advantage of mock is that it is a mocking library and not a
framework. It provides a configurable and flexible mock object,
without being opinionated about how you write your tests. The
mock api is now well battle-tested and stable.

mock also handles safely monkeypatching and unmonkeypatching
objects during the scope of a test. This is hard to do safely
and many developers / projects mimic this functionality
(often incorrectly). A standardised way to do this, handling
the complexity of patching in the presence of the descriptor
protocol (etc) is useful. People are asking for a "patch" [3]_
feature to unittest. Doing this via mock.patch is preferable
to re-implementing part of this functionality in unittest.


Background
==========

Addition of mock to the Python standard library was discussed
and agreed to at the Python Language Summit 2012.


Open Issues
===========

As of release 0.8, which is current at the time of writing,
mock is compatible with Python 2.4-3.2. Moving into the Python
standard library will allow for the removal of some Python 2
specific "compatibility hacks".

mock 0.8 introduced a new feature, "auto-speccing", obsoletes
an older mock feature called "mocksignature". The
"mocksignature" functionality can be removed from mock
altogether prior to inclusion.


References
==========

.. [1] `mock library on PyPI <http://pypi.python.org/pypi/mock>`_
.. [2] http://pypi.python.org/pypi?%3Aaction=search&term=mock&submit=search
.. [3] http://bugs.python.org/issue11664


Copyright
=========

This document has been placed in the public domain.


..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   coding: utf-8
   End:
-												Adding PEP 417 'Adding mock to the standard library'

											
										
										
											2012-03-12 18:00:48 -04:00
+								PEP: 417
 								Title: Including mock in the Standard Library
 								Version: $Revision$
 								Last-Modified: $Date$
 								Author: Michael Foord <michael@python.org>
-												Move the mock and buffer protocol PEPs to Final

											
										
										
											2012-05-01 09:37:34 -04:00
+								Status: Final
-												Adding PEP 417 'Adding mock to the standard library'

											
										
										
											2012-03-12 18:00:48 -04:00
+								Type: Standards Track
-												Convert PEP 417 to rst.

											
										
										
											2012-03-12 18:33:12 -04:00
+								Content-Type: text/x-rst
-												Adding PEP 417 'Adding mock to the standard library'

											
										
										
											2012-03-12 18:00:48 -04:00
+								Created: 12-Mar-2012
 								Python-Version: 3.3
 								Post-History: 12-Mar-2012
-												promote m.p.o links to https

											
										
										
											2017-06-11 15:02:39 -04:00
+								Resolution: https://mail.python.org/pipermail/python-dev/2012-March/117507.html
-												Adding PEP 417 'Adding mock to the standard library'

											
										
										
											2012-03-12 18:00:48 -04:00
 								Abstract
-												Convert PEP 417 to rst.

											
										
										
											2012-03-12 18:33:12 -04:00
+								========
-												Adding PEP 417 'Adding mock to the standard library'

											
										
										
											2012-03-12 18:00:48 -04:00
-												Convert PEP 417 to rst.

											
										
										
											2012-03-12 18:33:12 -04:00
+								This PEP proposes adding the mock [1]_ testing library
 								to the Python standard library as ``unittest.mock``.
-												Adding PEP 417 'Adding mock to the standard library'

											
										
										
											2012-03-12 18:00:48 -04:00
 								Rationale
-												Convert PEP 417 to rst.

											
										
										
											2012-03-12 18:33:12 -04:00
+								=========
-												Adding PEP 417 'Adding mock to the standard library'

											
										
										
											2012-03-12 18:00:48 -04:00
-												Convert PEP 417 to rst.

											
										
										
											2012-03-12 18:33:12 -04:00
+								Creating mock objects for testing is a common need in Python.
 								Many developers create ad-hoc mocks, as needed, in their test
 								suites. This is currently what we do in the Python test suite,
 								where a standardised mock object library would be helpful.
 								There are many mock object libraries available for Python [2]_.
 								Of these, mock is overwhelmingly the most popular, with as many
 								downloads on PyPI as the other mocking libraries combined.
 								An advantage of mock is that it is a mocking library and not a
 								framework. It provides a configurable and flexible mock object,
 								without being opinionated about how you write your tests. The
 								mock api is now well battle-tested and stable.
 								mock also handles safely monkeypatching and unmonkeypatching
 								objects during the scope of a test. This is hard to do safely
 								and many developers / projects mimic this functionality
 								(often incorrectly). A standardised way to do this, handling
 								the complexity of patching in the presence of the descriptor
 								protocol (etc) is useful. People are asking for a "patch" [3]_
 								feature to unittest. Doing this via mock.patch is preferable
 								to re-implementing part of this functionality in unittest.
-												Adding PEP 417 'Adding mock to the standard library'

											
										
										
											2012-03-12 18:00:48 -04:00
 								Background
-												Convert PEP 417 to rst.

											
										
										
											2012-03-12 18:33:12 -04:00
+								==========
 								Addition of mock to the Python standard library was discussed
 								and agreed to at the Python Language Summit 2012.
-												Addition of 'open issues' to PEP 417

											
										
										
											2012-03-12 18:13:48 -04:00
 								Open Issues
-												Convert PEP 417 to rst.

											
										
										
											2012-03-12 18:33:12 -04:00
+								===========
 								As of release 0.8, which is current at the time of writing,
 								mock is compatible with Python 2.4-3.2. Moving into the Python
 								standard library will allow for the removal of some Python 2
 								specific "compatibility hacks".
 								mock 0.8 introduced a new feature, "auto-speccing", obsoletes
 								an older mock feature called "mocksignature". The
 								"mocksignature" functionality can be removed from mock
 								altogether prior to inclusion.
-												Remove trailing spaces. (#232)

Changes made automatically by the following command:
```
egrep -l ' +$' *.txt | xargs sed -i -re 's/ +$//'
```
											
										
										
											2017-03-24 17:11:33 -04:00
-												Adding PEP 417 'Adding mock to the standard library'

											
										
										
											2012-03-12 18:00:48 -04:00
 								References
-												Convert PEP 417 to rst.

											
										
										
											2012-03-12 18:33:12 -04:00
+								==========
-												Adding PEP 417 'Adding mock to the standard library'

											
										
										
											2012-03-12 18:00:48 -04:00
-												Convert PEP 417 to rst.

											
										
										
											2012-03-12 18:33:12 -04:00
+								.. [1] `mock library on PyPI <http://pypi.python.org/pypi/mock>`_
 								.. [2] http://pypi.python.org/pypi?%3Aaction=search&term=mock&submit=search
 								.. [3] http://bugs.python.org/issue11664
-												Adding PEP 417 'Adding mock to the standard library'

											
										
										
											2012-03-12 18:00:48 -04:00
 								Copyright
-												Convert PEP 417 to rst.

											
										
										
											2012-03-12 18:33:12 -04:00
+								=========
-												Adding PEP 417 'Adding mock to the standard library'

											
										
										
											2012-03-12 18:00:48 -04:00
-												Convert PEP 417 to rst.

											
										
										
											2012-03-12 18:33:12 -04:00
+								This document has been placed in the public domain.
-												Adding PEP 417 'Adding mock to the standard library'

											
										
										
											2012-03-12 18:00:48 -04:00
-												Convert PEP 417 to rst.

											
										
										
											2012-03-12 18:33:12 -04:00
+								..
 								   Local Variables:
 								   mode: indented-text
 								   indent-tabs-mode: nil
 								   sentence-end-double-space: t
 								   fill-column: 70
 								   coding: utf-8
 								   End: