diff --git a/README.rst b/README.rst index 05345a1219f056a8b84e9232c8fb76f0d55fb368..89bfb042f71bda49459fdfc7e66041f9f5339007 100644 --- a/README.rst +++ b/README.rst @@ -95,7 +95,31 @@ all over the place, discretely, without resorting to a separate agency. self.spy_on(weather.start_raining) -3. Using a context manager +3. Using a decorator +-------------------- + +If you're creating a spy that calls a fake function, you can simplify some +things by using the ``spy_for`` decorator: + + +.. code-block:: python + + from kgb import SpyAgency + + + class TopSecretTests(SpyAgency, unittest.TestCase): + def test_doomsday_device(self): + dd = DoomsdayDevice() + + @self.spy_for(dd.kaboom) + def _save_world(*args, **kwargs) + print('Sprinkles and ponies!') + + # Give it your best shot, doomsday device. + dd.kaboom() + + +4. Using a context manager -------------------------- If you just want a spy for a quick job, without all that hassle of a full @@ -151,10 +175,18 @@ Creating a spy that reroutes to a fake function .. code-block:: python + def _my_fake_function(some_param, *args, **kwargs): + ... + agency.spy_on(obj.function, call_fake=my_fake_function) + # Or, in KGB 6+ + @agency.spy_for(obj.function) + def _my_fake_function(some_param, *args, **kwargs): + ... + -Fake return values or operations without anybody knowing. +Fake the return values or operations without anybody knowing. Stopping a spy operation @@ -337,14 +369,15 @@ Call the original function result = obj.function.call_original('foo', bar='baz') -Super, super useful if you want to use ``call_fake=`` to wrap a function -and track or influence some part of it, but still want the original function -to do its thing. For instance: +Super, super useful if you want to use ``call_fake=`` or ``@agency.spy_for`` +to wrap a function and track or influence some part of it, but still want the +original function to do its thing. For instance: .. code-block:: python stored_results = [] + @agency.spy_for(obj.function) def my_fake_function(*args, **kwargs): kwargs['bar'] = 'baz' result = obj.function.call_original(*args, **kwargs) @@ -352,8 +385,6 @@ to do its thing. For instance: return result - agency.spy_on(obj.function, call_fake=my_fake_function) - FAQ === diff --git a/kgb/agency.py b/kgb/agency.py index 9b83215897850c85af1c80925d30ae2b3e47cfa7..7f295347b5b6365cfeb59a26ac09cc6d1eb7b1fc 100644 --- a/kgb/agency.py +++ b/kgb/agency.py @@ -4,6 +4,7 @@ from __future__ import unicode_literals from pprint import pformat +from kgb.signature import _UNSET_ARG from kgb.spies import FunctionSpy, SpyCall from unittest.util import safe_repr @@ -78,6 +79,46 @@ class SpyAgency(object): self.spies.add(spy) return spy + def spy_for(self, func, owner=_UNSET_ARG): + """Decorate a function that should be a spy for another function. + + This is a convenience over declaring a function and using + :py:meth:`spy_on` with ``call_fake=``. It's used to quickly and + easily create a fake function spy for another function. + + Version Added: + 6.0 + + Args: + func (callable): + The function or method to spy on. + + owner (type or object, optional): + The owner of the function or method. + + If spying on an unbound method, this **must** be set to the + class that owns it. + + If spying on a bound method that identifies as a plain + function (which may happen if the method is decorated and + dynamically returns a new function on access), this should + be the instance of the object you're spying on. + + Example: + @self.spy_for(get_doomsday): + def _fake_get_doomsday(): + return datetime(year=2038, month=12, day=5, + hour=1, minute=2, second=3) + """ + def _wrap(call_fake): + self.spy_on(func, + owner=owner, + call_fake=call_fake) + + return call_fake + + return _wrap + def unspy(self, func): """Stop spying on a function. diff --git a/kgb/tests/test_spy_agency.py b/kgb/tests/test_spy_agency.py index 7a9a3e9d737ae1495df74abaf562b4b54ff999cb..07600f594b6726255c9222493ad28208d35f1015 100644 --- a/kgb/tests/test_spy_agency.py +++ b/kgb/tests/test_spy_agency.py @@ -5,6 +5,7 @@ from __future__ import unicode_literals from contextlib import contextmanager from kgb.agency import SpyAgency +from kgb.signature import FunctionSig from kgb.tests.base import MathClass, TestCase @@ -18,6 +19,25 @@ class SpyAgencyTests(TestCase): spy = self.agency.spy_on(obj.do_math) self.assertEqual(self.agency.spies, set([spy])) + def test_spy_for(self): + """Testing SpyAgency.spy_for""" + obj = MathClass() + + @self.agency.spy_for(obj.do_math, owner=obj) + def my_func(_self, a=None, b=None, *args, **kwargs): + """Some docs.""" + return 123 + + self.assertEqual(obj.do_math(), 123) + self.assertEqual(my_func(obj), 123) + self.assertIs(obj.do_math.spy.func, my_func) + + # Make sure we decorated correctly. + sig = FunctionSig(my_func) + self.assertEqual(sig.func_name, 'my_func') + self.assertEqual(sig.func_type, FunctionSig.TYPE_FUNCTION) + self.assertEqual(my_func.__doc__, 'Some docs.') + def test_unspy(self): """Testing SpyAgency.unspy""" obj = MathClass() @@ -67,6 +87,25 @@ class TestCaseMixinTests(SpyAgency, TestCase): result = obj.do_math() self.assertEqual(result, 3) + def test_spy_for(self): + """Testing SpyAgency mixed in with spy_for""" + obj = MathClass() + + @self.spy_for(obj.do_math) + def my_func(_self, a=None, b=None, *args, **kwargs): + """Some docs.""" + return 123 + + self.assertEqual(obj.do_math(), 123) + self.assertEqual(my_func(obj), 123) + self.assertIs(obj.do_math.spy.func, my_func) + + # Make sure we decorated correctly. + sig = FunctionSig(my_func) + self.assertEqual(sig.func_name, 'my_func') + self.assertEqual(sig.func_type, FunctionSig.TYPE_FUNCTION) + self.assertEqual(my_func.__doc__, 'Some docs.') + def test_tear_down(self): """Testing SpyAgency mixed in with tearDown""" obj = MathClass()