docs/index.txt

===================================
 Mock - Mocking and Testing Library
===================================

:Version: |release|
:Date: |today|
:Homepage: `Mock Homepage`_
:Download: `Mock on PyPI`_
:Documentation: `Python Docs`_
:License: `BSD License`_
:Support: `Mailing list (testing-in-python@lists.idyll.org)
 <http://lists.idyll.org/listinfo/testing-in-python>`_
:Issue tracker: `GitHub Issues
 <https://github.com/testing-cabal/mock/issues>`_

.. _Mock Homepage: https://github.com/testing-cabal/mock
.. _BSD License: https://github.com/testing-cabal/mock/blob/master/LICENSE.txt
.. _Python Docs: https://docs.python.org/dev/library/unittest.mock.html

.. module:: mock
   :synopsis: Mock object and testing library.

.. index:: introduction

TOC
+++

.. toctree::
   :maxdepth: 2

   changelog

Introduction
++++++++++++

mock is a library for testing in Python. It allows you to replace parts of
your system under test with mock objects and make assertions about how they
have been used.

mock is now part of the Python standard library, available as
``unittest.mock`` in Python 3.3 onwards. However, if you are writing code that
runs on multiple versions of Python the ``mock`` package is better, as you get
the newest features from the latest release of Python available for all
Pythons.

The ``mock`` package contains a rolling backport of the standard library mock
code compatible with Python 2.7 and 3.4 and up.

* Python 2.6 and 3.3 are supported by mock 2.0.0 and below.

* Python 3.2 is supported by mock 1.3.0 and below - with pip no longer
  supporting 3.2, we cannot test against that version anymore.

Please see the standard library documentation for usage details.

.. index:: installing
.. _installing:

Installing
++++++++++

The current version is |release|. Mock is stable and widely used.

* `mock on PyPI <https://pypi.org/project/mock/>`_

.. index:: repository
.. index:: git

You can checkout the latest development version from GitHub
repository with the following command:

    ``git clone https://github.com/testing-cabal/mock.git``


.. index:: pip

You can install mock with pip:

    | ``pip install -U mock``

.. index:: bug reports

Bug Reports
+++++++++++

Mock uses `unittest <https://docs.python.org/3/library/unittest.html>`_ for its own
Issues with the backport process, such as compatibility with a particular
Python, should be reported to the `bug tracker
<https://github.com/testing-cabal/mock/issues>`_. Feature requests and issues
with Mock functionality should be reported to the `Python bug tracker
<https://bugs.python.org>`_.

.. index:: python changes

Python Changes
++++++++++++++

Python NEWS entries from cPython:

.. include:: ../NEWS

.. index:: older versions

Older Versions of Python
++++++++++++++++++++++++

Version 1.0.1 is the last version compatible with Python < 2.6.

Version 2.0.0 is the last version compatible with Python 2.6.

.. index:: maintainer notes

Maintainer Notes
++++++++++++++++

Development
-----------

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, nightly Python 3 builds, pypy, pypy3. Jython support is desired, if
someone could contribute a patch to .travis.yml to support it that would be
excellent.

Releasing
---------

NB: please use semver. Bump the major component on API breaks, minor on all
non-bugfix changes, patch on bugfix only changes.

1. tag -s, push --tags origin master
2. setup.py sdist bdist_wheel upload -s


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.

Backporting process
-------------------

1. Clone cpython and mock into the same directory, eg:

   .. code-block:: bash

       mkdir vcs
       cd vcs
       git clone https://github.com/python/cpython.git
       git clone https://github.com/testing-cabal/mock.git

   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 ``backport.py``:

   .. code-block:: bash

       cd vcs/mock
       python backport.py

   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 backport.py --skip-current``.

   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"
   above.

5. Rinse and repeat until ``backport.py`` reports no more patches need applying.

6. If ``backport.py`` has updated ``lastsync.txt``, now would be a good time
   to commit that change.