1====================================
2 Mock - Mocking and Testing Library
3====================================
4
5:Version: |release|
6:Date: |today|
7:Homepage: `Mock Homepage`_
8:Download: `Mock on PyPI`_
9:Documentation: `Python Docs`_
10:License: `BSD License`_
11:Support: `Mailing list (testing-in-python@lists.idyll.org)
12 <http://lists.idyll.org/listinfo/testing-in-python>`_
13:Issue tracker: `GitHub Issues
14 <https://github.com/testing-cabal/mock/issues>`_
15:Last sync: cb6aab1248c4aec4dd578bea717854505a6fb55d
16
17.. _Mock Homepage: https://github.com/testing-cabal/mock
18.. _BSD License: http://github.com/testing-cabal/mock/blob/master/LICENSE.txt
19.. _Python Docs: https://docs.python.org/dev/library/unittest.mock.html
20
21.. module:: mock
22   :synopsis: Mock object and testing library.
23
24.. index:: introduction
25
26TOC
27+++
28
29.. toctree::
30   :maxdepth: 2
31
32   changelog
33
34Introduction
35++++++++++++
36
37mock is a library for testing in Python. It allows you to replace parts of
38your system under test with mock objects and make assertions about how they
39have been used.
40
41mock is now part of the Python standard library, available as
42``unittest.mock`` in Python 3.3 onwards. However, if you are writing code that
43runs on multiple versions of Python the ``mock`` package is better, as you get
44the newest features from the latest release of Python available for all
45Pythons.
46
47The ``mock`` package contains a rolling backport of the standard library mock
48code compatible with Python 2.7 and 3.3 and up.
49
50* Python 2.6 is supported by mock 2.0.0 and below.
51
52* Python 3.2 is supported by mock 1.3.0 and below - with pip no longer
53supporting 3.2, we cannot test against that version anymore.
54
55Please see the standard library documentation for usage details.
56
57.. index:: installing
58.. _installing:
59
60Installing
61++++++++++
62
63The current version is |release|. Mock is stable and widely used.
64
65* `mock on PyPI <http://pypi.python.org/pypi/mock>`_
66
67.. index:: repository
68.. index:: git
69
70You can checkout the latest development version from GitHub
71repository with the following command:
72
73    ``git clone https://github.com/testing-cabal/mock``
74
75
76.. index:: pip
77
78You can install mock with pip:
79
80    | ``pip install -U mock``
81
82Alternatively you can download the mock distribution from PyPI and after
83unpacking run:
84
85   ``python setup.py install``
86
87
88.. index:: bug reports
89
90Bug Reports
91+++++++++++
92
93Mock uses `unittest2 <http://pypi.python.org/pypi/unittest2>`_ for its own
94Issues with the backport process, such as compatibility with a particular
95Python, should be reported to the `bug tracker
96<https://github.com/testing-cabal/mock/issues>`_. Feature requests and issues
97with Mock functionality should be reported to the `Python bug tracker
98<https://bugs.python.org>`_.
99
100.. index:: python changes
101
102Python Changes
103++++++++++++++
104
105Python NEWS entries from cPython:
106
107.. include:: ../NEWS
108
109.. index:: older versions
110
111Older Versions of Python
112++++++++++++++++++++++++
113
114Version 1.0.1 is the last version compatible with Python < 2.6.
115
116Version 2.0.0 is the last version compatible with Python 2.6.
117
118.. index:: maintainer notes
119
120Maintainer Notes
121++++++++++++++++
122
123Development
124===========
125
126Checkout from git (see :ref:`installing`) and submit pull requests.
127
128Committers can just push as desired: since all semantic development takes
129place in cPython, the backport process is as lightweight as we can make it.
130
131mock is CI tested using Travis-CI on Python versions 2.7, 3.3, 3.4,
1323.5, nightly Python 3 builds, pypy, pypy3. Jython support is desired, if
133someone could contribute a patch to .travis.yml to support it that would be
134excellent.
135
136Releasing
137=========
138
139NB: please use semver. Bump the major component on API breaks, minor on all
140non-bugfix changes, patch on bugfix only changes.
141
1421. tag -s, push --tags origin master
1432. setup.py sdist bdist_wheel upload -s
144
145
146Backporting rules
147=================
148
149isinstance checks in cPython to ``type`` need to check ``ClassTypes``.
150Code calling ``obj.isidentifier`` needs to change to ``_isidentifier(obj)``.
151
152Backporting process
153===================
154
1551. Patch your git am with `my patch <https://github.com/rbtcollins/git>`_.
1562. Install the applypatch-transform hook from tools/ to your .git hooks dir.
1573. Configure a pre-applypatch hook to test at least all the cPython versions
158   we support on each patch that is applied. I use containers, and a sample
159   script is in tools/pre-applypatch.
1604. Pull down the cPython git mirror: https://github.com/python/cpython.git
1615. Export the new revisions since the ``Last sync`` at the top of this
162   document::
163
164     revs=${lastsync}
165     rm migrate-export
166     git log --pretty="format:%H " $revs.. -- Lib/unittest/mock.py \
167       Lib/unittest/test/testmock/ > migrate-revs
168     tac migrate-revs > migrate-sorted-revs
169     for rev in $(< migrate-sorted-revs); do
170           git format-patch -1 $rev -k --stdout >> migrate-export;
171           done
172     echo NEW SYNC POINT: $(git rev-parse HEAD)
173
1746. Import into mock::
175
176     git am -k --reject $path-to-cpython/migrate-export
177
178   This will transform the patches automatically. Currently it will error
179   on every NEWS change as I haven't gotten around to making those patches
180   automatic. Fixup any errors that occur. When the patch is ready, do a ``git
181   add -u`` to update the index and then ``git am --continue`` to move onto
182   the next patch. If the patch is inappropriate e.g. the patch removing
183   __ne__ which would break older pythons, then either do ``git reset --hard;
184   git am --skip`` to discard any partially applied changes and skip over it,
185   or, if it has a NEWS entry thats worth preserving, edit it down to just
186   that, with a note such as we have for the ``__ne__`` patch, and continue on
187   from there.
188
189   The goal is that every patch work at all times.
190
1917. After the import is complete, update this document with the new sync point.
192
1938. Push to a personal branch and propose a PR to the main repo. This will make
194   Travis-CI test it. If it works, push to the main repo.
195