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