1===================================
2 Mock - Mocking and Testing Library
3===================================
4
5.. include:: ../README.rst
6
7.. module:: mock
8   :synopsis: Mock object and testing library.
9
10.. index:: introduction
11
12.. toctree::
13   :hidden:
14
15   changelog
16
17Python Version Compatibility
18++++++++++++++++++++++++++++
19
20* Version 1.0.1 is the last version compatible with Python < 2.6.
21
22* Version 1.3.0 is the last version compatible with Python 3.2.
23
24* Version 2.0.0 is the last version compatible with Python 2.6.
25
26* Version 2.0.0 is the last version offering official Jython support.
27
28.. index:: installing
29.. _installing:
30
31Installing
32++++++++++
33
34.. index:: repository
35.. index:: git
36
37You can checkout the latest development version from GitHub
38repository with the following command:
39
40    ``git clone https://github.com/testing-cabal/mock.git``
41
42
43.. index:: pip
44
45You can install mock with pip:
46
47    | ``pip install -U mock``
48
49.. index:: bug reports
50
51Bug Reports
52+++++++++++
53
54Issues with the backport process, such as compatibility with a particular
55Python, should be reported to the `bug tracker
56<https://github.com/testing-cabal/mock/issues>`_. Feature requests and issues
57with Mock functionality should be reported to the `Python bug tracker
58<https://bugs.python.org>`_.
59
60.. index:: python changes
61
62Changelog
63+++++++++
64
65See the :doc:`change log <changelog>`.
66
67.. index:: maintainer notes
68
69Maintainer Notes
70++++++++++++++++
71
72Development
73-----------
74
75Checkout from git (see :ref:`installing`) and submit pull requests.
76
77Committers can just push as desired: since all semantic development takes
78place in cPython, the backport process is as lightweight as we can make it.
79
80mock is CI tested using Travis-CI on Python versions 2.7, 3.4,
813.5, 3.6, pypy, pypy3.
82
83If you end up fixing anything backport-specific, please add an entry
84to the top of ``CHANGELOG.rst`` so it shows up in the next release
85notes.
86
87Releasing
88---------
89
90NB: please use semver. Bump the major component on API breaks, minor on all
91non-bugfix changes, patch on bugfix only changes.
92
931. Run ``release.py [major|minor|bugfix]`` which will roll out new
94   NEWS items, bump the version number and create a commit for the release.
95
962. Review that commit, feel free to amend it if you want to note anything
97   manually in ``CHANGELOG.rst``.
98
993. Push to the ``master`` branch on
100   https://github.com/testing-cabal/mock.git and the Circle CI
101   automation will take care of pushing releases to PyPI and
102   creating a tag.
103
104Backporting rules
105-----------------
106
107- ``isinstance`` checks in cPython to ``type`` need to check ``ClassTypes``.
108  Code calling ``obj.isidentifier`` needs to change to ``_isidentifier(obj)``.
109
110- f-strings need to be rewritten using some other string substitution.
111
112- ``assertRaisesRegex`` needs to be ``assertRaisesRegexp`` for Python 2.
113
114- If test code won't compile on a particular version of Python, move it to
115  a matching ``_py{version}.py`` file. If ``{version}`` isn't 3, adjust
116  ``conftest.py``.
117
118- If code such as this causes coverage checking to drop below 100%:
119
120  .. code-block:: python
121
122      def will_never_be_called():
123          pass
124
125  It should be adjusted to the following pattern, preferably upstream,
126  so that the ``.coveragerc`` in this repo knows to ignore it:
127
128  .. code-block:: python
129
130      def will_never_be_called(): pass
131
132Backporting process
133-------------------
134
1351. Clone cpython and mock into the same directory, eg:
136
137   .. code-block:: bash
138
139       mkdir vcs
140       cd vcs
141       git clone https://github.com/python/cpython.git
142       git clone https://github.com/testing-cabal/mock.git
143
144   Make sure they both on master and up to date!
145
1462. Create a branch in your ``mock`` clone and switch to it.
147
1483. Make sure you build a suitable virtualenv for Mock development
149   and activate it. For backporting, this should use Python 3.7+.
150
1514. Run ``backport.py``:
152
153   .. code-block:: bash
154
155       cd vcs/mock
156       python backport.py
157
158   This will find the next cpython patch that needs to be applied, munge it
159   and attempt to apply it with ``git am``.
160
161   If it succeeds, run the tests and/or push your branch up to a fork and
162   do a pull request into the master branch of the main repo to kick off
163   the continuous integration tests.
164
165   If it fails, you'll have to manually work with what ``git status`` shows
166   to get the patch committed.
167
168   If it turns out that there's nothing that should be applied from the failed commit,
169   run ``python backport.py --skip-current``, maybe with ``--skip-reason``.
170
171   If you have to make changes, please do a ``git commit --amend`` and add notes
172   about what needed doing below the ``Signed-off-by`` block.
173
174   If you have to make changes because tests fail with an applied patch, please
175   make those changes in a followup commit and take note of the "Backporting rules"
176   above.
177
1785. Rinse and repeat until ``backport.py`` reports no more patches need applying.
179
1806. If ``backport.py`` has updated ``lastsync.txt``, now would be a good time
181   to commit that change.
182