===========================================
pytest-monkeyplus - monkeypatch with extras
===========================================

The ``monkeyplus`` plugin is a funcarg that subclasses ``monkeypatch`` and adds 
a few extra features to it.

Extra features
--------------

``monkeyplus`` has three extra methods: ``patch_osstat``, ``patch_today`` and
``patch_time_ticking``.

``patch_osstat(path, **osstat_attrs)``

Patching ``os.stat`` is tricky because you usually want to patch only one file,
not the whole filesystem. Moreover, to patch it properly, you have to return a
full ``stat_result`` structure. ``patch_osstat`` takes care of this stuff.
Just call it with a path to patch and keyword arguments for the stat attributes
you want, for example::

    monkeyplus.patch_osstat('foo/bar', st_mtime=42)

Arguments that are not specified will be assigned a default value.

``patch_today(year, month, day)``

Patching dates can be tricky because there's a couple of time relates modules,
namely ``datetime`` and ``time``. If you want your patch to affect the whole app
uniformly, you have to patch the ``time`` module, not the ``datetime`` module.
The arithmetics to transform a year/month/day value in a suitable ``time.time``
value are non-trivial, so it can get boring to repeat. Call ``patch_today`` with
the date you'd like the app to be patched to, example::

    monkeyplus.patch_today(2011, 2, 16)

``patch_time_ticking(force_int_diff=False)``

This monkeypatch ensures that all ``time.time()`` calls yield different results (and increasing). On
many platforms, this is already guaranteed, but not on all of them.

If ``force_int_diff`` is True, the patch ensures that all ``int(time.time())`` calls yield different
results. Note that it also means that the patches function will return ``int`` values.

Replacing monkeypatch
---------------------

``monkeyplus`` is a subclass of ``monkeypatch``, so it can be used everywhere
``monkeypatch`` is used. Instead of having to use a different funcarg, you can
replace ``monkeypatch`` by putting this in your ``conftest.py`` file::

    def pytest_funcarg__monkeypatch(request):
        monkeyplus = request.getfuncargvalue('monkeyplus')
        return monkeyplus

Contributions welcome
---------------------

For now, ``monkeyplus`` is a plugin that reflect my own needs, but if you'd like
to contribute new features to it, they're welcome. The source is hosted at http://bitbucket.org/hsoft/pytest-monkeyplus
