blob: 4e8bc17d6d177bb9350d2562bad6348e1182bc1b [file] [log] [blame]
Mock - Mocking and Testing Library
.. include:: ../README.rst
.. module:: mock
:synopsis: Mock object and testing library.
.. index:: introduction
.. toctree::
Python Version Compatibility
* Version 1.0.1 is the last version compatible with Python < 2.6.
* Version 1.3.0 is the last version compatible with Python 3.2.
* Version 2.0.0 is the last version compatible with Python 2.6.
* Version 2.0.0 is the last version offering official Jython support.
.. index:: installing
.. _installing:
.. index:: repository
.. index:: git
You can checkout the latest development version from GitHub
repository with the following command:
``git clone``
.. index:: pip
You can install mock with pip:
| ``pip install -U mock``
.. index:: bug reports
Bug Reports
Issues with the backport process, such as compatibility with a particular
Python, should be reported to the `bug tracker
<>`_. Feature requests and issues
with Mock functionality should be reported to the `Python bug tracker
.. index:: python changes
See the :doc:`change log <changelog>`.
.. index:: maintainer notes
Maintainer Notes
Checkout from git (see :ref:`installing`) and submit pull requests.
Committers can just push as desired: since all semantic development takes
place in cPython, the backport process is as lightweight as we can make it.
mock is CI tested using Travis-CI on Python versions 2.7, 3.4,
3.5, 3.6, pypy, pypy3.
If you end up fixing anything backport-specific, please add an entry
to the top of ``CHANGELOG.rst`` so it shows up in the next release
NB: please use semver. Bump the major component on API breaks, minor on all
non-bugfix changes, patch on bugfix only changes.
1. Run `` [major|minor|bugfix]`` which will roll out new
NEWS items, bump the version number and create a commit for the release.
2. Review that commit, feel free to amend it if you want to note anything
manually in ``CHANGELOG.rst``.
3. Push to the ``master`` branch on and the Circle CI
automation will take care of pushing releases to PyPI and
creating a tag.
Backporting rules
- ``isinstance`` checks in cPython to ``type`` need to check ``ClassTypes``.
Code calling ``obj.isidentifier`` needs to change to ``_isidentifier(obj)``.
- f-strings need to be rewritten using some other string substitution.
- ``assertRaisesRegex`` needs to be ``assertRaisesRegexp`` for Python 2.
- If test code won't compile on a particular version of Python, move it to
a matching ``_py{version}.py`` file. If ``{version}`` isn't 3, adjust
- If code such as this causes coverage checking to drop below 100%:
.. code-block:: python
def will_never_be_called():
It should be adjusted to the following pattern, preferably upstream,
so that the ``.coveragerc`` in this repo knows to ignore it:
.. code-block:: python
def will_never_be_called(): pass
Backporting process
1. Clone cpython and mock into the same directory, eg:
.. code-block:: bash
mkdir vcs
cd vcs
git clone
git clone
Make sure they both on master and up to date!
2. Create a branch in your ``mock`` clone and switch to it.
3. Make sure you build a suitable virtualenv for Mock development
and activate it. For backporting, this should use Python 3.7+.
4. Run ````:
.. code-block:: bash
cd vcs/mock
This will find the next cpython patch that needs to be applied, munge it
and attempt to apply it with ``git am``.
If it succeeds, run the tests and/or push your branch up to a fork and
do a pull request into the master branch of the main repo to kick off
the continuous integration tests.
If it fails, you'll have to manually work with what ``git status`` shows
to get the patch committed.
If it turns out that there's nothing that should be applied from the failed commit,
run ``python --skip-current``, maybe with ``--skip-reason``.
If you have to make changes, please do a ``git commit --amend`` and add notes
about what needed doing below the ``Signed-off-by`` block.
If you have to make changes because tests fail with an applied patch, please
make those changes in a followup commit and take note of the "Backporting rules"
5. Rinse and repeat until ```` reports no more patches need applying.
6. If ```` has updated ``lastsync.txt``, now would be a good time
to commit that change.