Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 1 | ==================================== |
| 2 | Mock - Mocking and Testing Library |
| 3 | ==================================== |
| 4 | |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 5 | :Version: |release| |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 6 | :Date: |today| |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 7 | :Homepage: `Mock Homepage`_ |
| 8 | :Download: `Mock on PyPI`_ |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 9 | :Documentation: `Python Docs`_ |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 10 | :License: `BSD License`_ |
| 11 | :Support: `Mailing list (testing-in-python@lists.idyll.org) |
| 12 | <http://lists.idyll.org/listinfo/testing-in-python>`_ |
Hugo | b67fe8a | 2017-10-28 16:01:45 +0300 | [diff] [blame] | 13 | :Issue tracker: `GitHub Issues |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 14 | <https://github.com/testing-cabal/mock/issues>`_ |
Robert Collins | 74eae17 | 2016-03-23 19:08:40 +1300 | [diff] [blame] | 15 | :Last sync: cb6aab1248c4aec4dd578bea717854505a6fb55d |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 16 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 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 |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 20 | |
| 21 | .. module:: mock |
| 22 | :synopsis: Mock object and testing library. |
| 23 | |
| 24 | .. index:: introduction |
| 25 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 26 | TOC |
| 27 | +++ |
| 28 | |
| 29 | .. toctree:: |
| 30 | :maxdepth: 2 |
| 31 | |
| 32 | changelog |
| 33 | |
| 34 | Introduction |
| 35 | ++++++++++++ |
| 36 | |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 37 | mock is a library for testing in Python. It allows you to replace parts of |
| 38 | your system under test with mock objects and make assertions about how they |
| 39 | have been used. |
| 40 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 41 | mock 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 |
| 43 | runs on multiple versions of Python the ``mock`` package is better, as you get |
| 44 | the newest features from the latest release of Python available for all |
| 45 | Pythons. |
Michael Foord | 2df6611 | 2012-10-07 18:33:12 +0100 | [diff] [blame] | 46 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 47 | The ``mock`` package contains a rolling backport of the standard library mock |
Hugo | b67fe8a | 2017-10-28 16:01:45 +0300 | [diff] [blame] | 48 | code 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 |
| 53 | supporting 3.2, we cannot test against that version anymore. |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 54 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 55 | Please see the standard library documentation for usage details. |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 56 | |
| 57 | .. index:: installing |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 58 | .. _installing: |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 59 | |
| 60 | Installing |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 61 | ++++++++++ |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 62 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 63 | The current version is |release|. Mock is stable and widely used. |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 64 | |
| 65 | * `mock on PyPI <http://pypi.python.org/pypi/mock>`_ |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 66 | |
| 67 | .. index:: repository |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 68 | .. index:: git |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 69 | |
Hugo | b67fe8a | 2017-10-28 16:01:45 +0300 | [diff] [blame] | 70 | You can checkout the latest development version from GitHub |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 71 | repository with the following command: |
| 72 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 73 | ``git clone https://github.com/testing-cabal/mock`` |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 74 | |
| 75 | |
| 76 | .. index:: pip |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 77 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 78 | You can install mock with pip: |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 79 | |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 80 | | ``pip install -U mock`` |
| 81 | |
| 82 | Alternatively you can download the mock distribution from PyPI and after |
| 83 | unpacking run: |
| 84 | |
| 85 | ``python setup.py install`` |
| 86 | |
| 87 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 88 | .. index:: bug reports |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 89 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 90 | Bug Reports |
| 91 | +++++++++++ |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 92 | |
| 93 | Mock uses `unittest2 <http://pypi.python.org/pypi/unittest2>`_ for its own |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 94 | Issues with the backport process, such as compatibility with a particular |
| 95 | Python, should be reported to the `bug tracker |
| 96 | <https://github.com/testing-cabal/mock/issues>`_. Feature requests and issues |
| 97 | with Mock functionality should be reported to the `Python bug tracker |
| 98 | <https://bugs.python.org>`_. |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 99 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 100 | .. index:: python changes |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 101 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 102 | Python Changes |
| 103 | ++++++++++++++ |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 104 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 105 | Python NEWS entries from cPython: |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 106 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 107 | .. include:: ../NEWS |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 108 | |
| 109 | .. index:: older versions |
| 110 | |
Robert Collins | dff3a7b | 2015-08-04 09:28:39 +1200 | [diff] [blame] | 111 | Older Versions of Python |
| 112 | ++++++++++++++++++++++++ |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 113 | |
Robert Collins | dff3a7b | 2015-08-04 09:28:39 +1200 | [diff] [blame] | 114 | Version 1.0.1 is the last version compatible with Python < 2.6. |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 115 | |
Hugo | b67fe8a | 2017-10-28 16:01:45 +0300 | [diff] [blame] | 116 | Version 2.0.0 is the last version compatible with Python 2.6. |
| 117 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 118 | .. index:: maintainer notes |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 119 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 120 | Maintainer Notes |
| 121 | ++++++++++++++++ |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 122 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 123 | Development |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 124 | =========== |
| 125 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 126 | Checkout from git (see :ref:`installing`) and submit pull requests. |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 127 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 128 | Committers can just push as desired: since all semantic development takes |
| 129 | place in cPython, the backport process is as lightweight as we can make it. |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 130 | |
Hugo | b67fe8a | 2017-10-28 16:01:45 +0300 | [diff] [blame] | 131 | mock is CI tested using Travis-CI on Python versions 2.7, 3.3, 3.4, |
Darragh Bailey | 0cba1ba | 2015-07-10 17:58:22 +0100 | [diff] [blame] | 132 | 3.5, nightly Python 3 builds, pypy, pypy3. Jython support is desired, if |
lord63 | 05a0ef0 | 2015-09-23 10:47:31 +0800 | [diff] [blame] | 133 | someone could contribute a patch to .travis.yml to support it that would be |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 134 | excellent. |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 135 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 136 | Releasing |
| 137 | ========= |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 138 | |
Robert Collins | e795a4a | 2015-07-10 14:32:36 +1200 | [diff] [blame] | 139 | NB: please use semver. Bump the major component on API breaks, minor on all |
| 140 | non-bugfix changes, patch on bugfix only changes. |
| 141 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 142 | 1. tag -s, push --tags origin master |
| 143 | 2. setup.py sdist bdist_wheel upload -s |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 144 | |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 145 | |
| 146 | Backporting rules |
| 147 | ================= |
| 148 | |
| 149 | isinstance checks in cPython to ``type`` need to check ``ClassTypes``. |
| 150 | Code calling ``obj.isidentifier`` needs to change to ``_isidentifier(obj)``. |
| 151 | |
| 152 | Backporting process |
| 153 | =================== |
| 154 | |
| 155 | 1. Patch your git am with `my patch <https://github.com/rbtcollins/git>`_. |
| 156 | 2. Install the applypatch-transform hook from tools/ to your .git hooks dir. |
| 157 | 3. 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. |
| 160 | 4. Pull down the cPython git mirror: https://github.com/python/cpython.git |
| 161 | 5. Export the new revisions since the ``Last sync`` at the top of this |
| 162 | document:: |
| 163 | |
Robert Collins | e34a7cb | 2015-07-24 07:52:01 +1200 | [diff] [blame] | 164 | revs=${lastsync} |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 165 | rm migrate-export |
Robert Collins | cce4e5b | 2015-07-14 14:13:20 +1200 | [diff] [blame] | 166 | git log --pretty="format:%H " $revs.. -- Lib/unittest/mock.py \ |
Robert Collins | 18c9bbd | 2015-07-10 14:00:11 +1200 | [diff] [blame] | 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 | |
| 174 | 6. 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 | |
| 191 | 7. After the import is complete, update this document with the new sync point. |
| 192 | |
| 193 | 8. 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. |