Return args (#87)

* return the args of debug()

* test for generators

* adding docs for returning

* linting

Author: samuelcolvin

devtools/debug.py

@@ -10,8 +10,7 @@
 MYPY = False
 if MYPY:
     from types import FrameType
-    from typing import Generator, List, Optional
-
+    from typing import Any, Generator, List, Optional
 
 pformat = PrettyFormat(
     indent_step=int(os.getenv('PY_DEVTOOLS_INDENT', 4)),
@@ -107,10 +106,16 @@ def __init__(self, *, warnings: 'Optional[bool]' = None, highlight: 'Optional[bo
         self._show_warnings = env_bool(warnings, 'PY_DEVTOOLS_WARNINGS', True)
         self._highlight = highlight
 
-    def __call__(self, *args, file_=None, flush_=True, **kwargs) -> None:
+    def __call__(self, *args, file_=None, flush_=True, **kwargs) -> 'Any':
         d_out = self._process(args, kwargs)
         s = d_out.str(use_highlight(self._highlight, file_))
         print(s, file=file_, flush=flush_)
+        if kwargs:
+            return (*args, kwargs)
+        elif len(args) == 1:
+            return args[0]
+        else:
+            return args
 
     def format(self, *args, **kwargs) -> DebugOutput:
         return self._process(args, kwargs)

docs/examples/return_args.py

@@ -0,0 +1,6 @@
+from devtools import debug
+
+assert debug('foo') == 'foo'
+assert debug('foo', 'bar') == ('foo', 'bar')
+assert debug('foo', 'bar', spam=123) == ('foo', 'bar', {'spam': 123})
+assert debug(spam=123) == ({'spam': 123},)

docs/index.md

@@ -15,3 +15,5 @@
 ```
 
 {!examples/example.html!}
+
+Python devtools can do much more, see [Usage](./usage.md) for examples.

docs/usage.md

@@ -26,6 +26,22 @@ A more complex example of `debug` shows more of what it can do.
 
 {!examples/complex.html!}
 
+### Returning the arguments
+
+`debug` will return the arguments passed to it meaning you can insert `debug(...)` into code.
+
+The returned arguments work as follows:
+
+* if one non-keyword argument is passed to `debug()`, it is returned as-is
+* if multiple arguments are passed to `debug()`, they are returned as a tuple
+* if keyword arguments are passed to `debug()`, the `kwargs` dictionary is added to the returned tuple
+
+```py
+{!examples/return_args.py!}
+```
+
+{!examples/return_args.html!}
+
 ## Other debug tools
 
 The debug namespace includes a number of other useful functions:

tests/test_main.py

@@ -1,5 +1,6 @@
 import re
 import sys
+from collections.abc import Generator
 from pathlib import Path
 from subprocess import PIPE, run
 
@@ -8,12 +9,13 @@
 from devtools import Debug, debug
 from devtools.ansi import strip_ansi
 
+pytestmark = pytest.mark.xfail(sys.platform == 'win32', reason='as yet unknown windows problem')
+
 
-@pytest.mark.xfail(sys.platform == 'win32', reason='yet unknown windows problem')
 def test_print(capsys):
     a = 1
     b = 2
-    debug(a, b)
+    result = debug(a, b)
     stdout, stderr = capsys.readouterr()
     print(stdout)
     assert re.sub(r':\d{2,}', ':<line no>', stdout) == (
@@ -22,9 +24,44 @@ def test_print(capsys):
         '    b: 2 (int)\n'
     )
     assert stderr == ''
+    assert result == (1, 2)
+
+
+def test_print_kwargs(capsys):
+    a = 1
+    b = 2
+    result = debug(a, b, foo=[1, 2, 3])
+    stdout, stderr = capsys.readouterr()
+    print(stdout)
+    assert re.sub(r':\d{2,}', ':<line no>', stdout) == (
+        'tests/test_main.py:<line no> test_print_kwargs\n'
+        '    a: 1 (int)\n'
+        '    b: 2 (int)\n'
+        '    foo: [1, 2, 3] (list) len=3\n'
+    )
+    assert stderr == ''
+    assert result == (1, 2, {'foo': [1, 2, 3]})
+
+
+def test_print_generator(capsys):
+    gen = (i for i in [1, 2])
+
+    result = debug(gen)
+    stdout, stderr = capsys.readouterr()
+    print(stdout)
+    assert re.sub(r':\d{2,}', ':<line no>', stdout) == (
+        'tests/test_main.py:<line no> test_print_generator\n'
+        '    gen: (\n'
+        '        1,\n'
+        '        2,\n'
+        '    ) (generator)\n'
+    )
+    assert stderr == ''
+    assert isinstance(result, Generator)
+    # the generator got evaluated and is now empty, that's correct currently
+    assert list(result) == []
 
 
-@pytest.mark.xfail(sys.platform == 'win32', reason='yet unknown windows problem')
 def test_format():
     a = b'i might bite'
     b = "hello this is a test"
@@ -38,7 +75,6 @@ def test_format():
     )
 
 
-@pytest.mark.xfail(sys.platform == 'win32', reason='yet unknown windows problem')
 def test_print_subprocess(tmpdir):
     f = tmpdir.join('test.py')
     f.write("""\
@@ -68,7 +104,6 @@ def test_func(v):
     )
 
 
-@pytest.mark.xfail(sys.platform == 'win32', reason='yet unknown windows problem')
 def test_odd_path(mocker):
     # all valid calls
     mocked_relative_to = mocker.patch('pathlib.Path.relative_to')
@@ -92,7 +127,6 @@ def test_small_call_frame():
     )
 
 
-@pytest.mark.xfail(sys.platform == 'win32', reason='yet unknown windows problem')
 def test_small_call_frame_warning():
     debug_ = Debug()
     v = debug_.format(
@@ -109,7 +143,6 @@ def test_small_call_frame_warning():
     )
 
 
-@pytest.mark.xfail(sys.platform == 'win32', reason='yet unknown windows problem')
 @pytest.mark.skipif(sys.version_info < (3, 6), reason='kwarg order is not guaranteed for 3.5')
 def test_kwargs():
     a = 'variable'
@@ -123,7 +156,6 @@ def test_kwargs():
     )
 
 
-@pytest.mark.xfail(sys.platform == 'win32', reason='yet unknown windows problem')
 def test_kwargs_orderless():
     # for python3.5
     a = 'variable'
@@ -136,7 +168,6 @@ def test_kwargs_orderless():
     }
 
 
-@pytest.mark.xfail(sys.platform == 'win32', reason='yet unknown windows problem')
 def test_simple_vars():
     v = debug.format('test', 1, 2)
     s = re.sub(r':\d{2,}', ':<line no>', str(v))
@@ -206,7 +237,6 @@ def test_exec(capsys):
     assert stderr == ''
 
 
-@pytest.mark.xfail(sys.platform == 'win32', reason='yet unknown windows problem')
 def test_colours():
     v = debug.format(range(6))
     s = re.sub(r':\d{2,}', ':<line no>', v.str(True))
@@ -240,7 +270,6 @@ def test_breakpoint(mocker):
     assert mocked_set_trace.called
 
 
-@pytest.mark.xfail(sys.platform == 'win32', reason='yet unknown windows problem')
 def test_starred_kwargs():
     v = {'foo': 1, 'bar': 2}
     v = debug.format(**v)
@@ -252,7 +281,6 @@ def test_starred_kwargs():
     }
 
 
-@pytest.mark.xfail(sys.platform == 'win32', reason='yet unknown windows problem')
 @pytest.mark.skipif(sys.version_info < (3, 7), reason='error repr different before 3.7')
 def test_pretty_error():
     class BadPretty:
@@ -279,3 +307,12 @@ def test_multiple_debugs():
         'tests/test_main.py:<line no> test_multiple_debugs\n'
         '    [i * 2 for i in range(2)]: [0, 2] (list) len=2'
     )
+
+
+def test_return_args(capsys):
+    assert debug('foo') == 'foo'
+    assert debug('foo', 'bar') == ('foo', 'bar')
+    assert debug('foo', 'bar', spam=123) == ('foo', 'bar', {'spam': 123})
+    assert debug(spam=123) == ({'spam': 123},)
+    stdout, stderr = capsys.readouterr()
+    print(stdout)