Bump version to 1.2.3

Add support for Ansible zipped source files

.travis.yml

@@ -3,11 +3,12 @@ language: python
 
 python:
 - 2.7
-- 3.4
 - 3.5
 - 3.6
 - 3.7
-- 3.8-dev
+- 3.8
+- 3.9
+- 3.10-dev
 - pypy2.7-6.0
 - pypy3.5
 
@@ -26,6 +27,7 @@ matrix:
   - env: TOXENV=flake8
   - env: TOXENV=pylint
   - env: TOXENV=bandit
+  - python: 3.10-dev
 
 jobs:
   include:

ADVANCED_USAGE.md

@@ -0,0 +1,98 @@
+# Advanced Usage #
+
+Use `watch_explode` to expand values to see all their attributes or items of lists/dictionaries:
+
+```python
+@pysnooper.snoop(watch_explode=('foo', 'self'))
+```
+
+`watch_explode` will automatically guess how to expand the expression passed to it based on its class. You can be more specific by using one of the following classes:
+
+```python
+import pysnooper
+
+@pysnooper.snoop(watch=(
+    pysnooper.Attrs('x'),    # attributes
+    pysnooper.Keys('y'),     # mapping (e.g. dict) items
+    pysnooper.Indices('z'),  # sequence (e.g. list/tuple) items
+))
+```
+
+Exclude specific keys/attributes/indices with the `exclude` parameter, e.g. `Attrs('x', exclude=('_foo', '_bar'))`.
+
+Add a slice after `Indices` to only see the values within that slice, e.g. `Indices('z')[-3:]`.
+
+```console
+$ export PYSNOOPER_DISABLED=1 # This makes PySnooper not do any snooping
+```
+
+This will output lines like:
+
+```
+Modified var:.. foo[2] = 'whatever'
+New var:....... self.baz = 8
+```
+
+Start all snoop lines with a prefix, to grep for them easily:
+
+```python
+@pysnooper.snoop(prefix='ZZZ ')
+```
+
+Remove all machine-related data (paths, timestamps, memory addresses) to compare with other traces easily:
+
+```python
+@pysnooper.snoop(normalize=True)
+```
+
+On multi-threaded apps identify which thread are snooped in output:
+
+```python
+@pysnooper.snoop(thread_info=True)
+```
+
+PySnooper supports decorating generators.
+
+If you decorate a class with `snoop`, it'll automatically apply the decorator to all the methods. (Not including properties and other special cases.)
+
+You can also customize the repr of an object:
+
+```python
+def large(l):
+    return isinstance(l, list) and len(l) > 5
+
+def print_list_size(l):
+    return 'list(size={})'.format(len(l))
+
+def print_ndarray(a):
+    return 'ndarray(shape={}, dtype={})'.format(a.shape, a.dtype)
+
+@pysnooper.snoop(custom_repr=((large, print_list_size), (numpy.ndarray, print_ndarray)))
+def sum_to_x(x):
+    l = list(range(x))
+    a = numpy.zeros((10,10))
+    return sum(l)
+
+sum_to_x(10000)
+```
+
+You will get `l = list(size=10000)` for the list, and `a = ndarray(shape=(10, 10), dtype=float64)` for the ndarray.
+The `custom_repr` are matched in order, if one condition matches, no further conditions will be checked.
+
+Variables and exceptions get truncated to 100 characters by default. You
+can customize that:
+
+```python
+    @pysnooper.snoop(max_variable_length=200)
+```
+
+You can also use `max_variable_length=None` to never truncate them.
+
+Use `relative_time=True` to show timestamps relative to start time rather than
+wall time.
+
+The output is colored for easy viewing by default, except on Windows. Disable colors like so:
+
+```python
+    @pysnooper.snoop(color=False)
+````

AUTHORS

@@ -17,3 +17,14 @@ Hervé Beraud
 Diego Volpatto
 Alexander Bersenev
 Xiang Gao
+pikez
+Jonathan Reichelt Gjertsen
+Guoqiang Ding
+Itamar.Raviv
+iory
+Mark Blakeney
+Yael Mintz
+Lumír 'Frenzy' Balhar
+Lukas Klenk
+sizhky
+Andrej730

MANIFEST.in

@@ -2,3 +2,5 @@ include README.md
 include LICENSE
 include requirements.in
 include requirements.txt
+recursive-include tests *.txt *.py
+prune tests/.pytest_cache

README.md

@@ -1,10 +1,8 @@
-# PySnooper - Never use print for debugging again #
+# PySnooper - Never use print for debugging again
 
-[![Travis CI](https://img.shields.io/travis/cool-RR/PySnooper/master.svg)](https://travis-ci.org/cool-RR/PySnooper)
+**PySnooper** is a poor man's debugger. If you've used Bash, it's like `set -x` for Python, except it's fancier.
 
-**PySnooper** is a poor man's debugger.
-
-You're trying to figure out why your Python code isn't doing what you think it should be doing. You'd love to use a full-fledged debugger with breakpoints and watches, but you can't be bothered to set one up right now.
+Your story: You're trying to figure out why your Python code isn't doing what you think it should be doing. You'd love to use a full-fledged debugger with breakpoints and watches, but you can't be bothered to set one up right now.
 
 You want to know which lines are running and which aren't, and what the values of the local variables are.
 
@@ -14,7 +12,7 @@ Most people would use `print` lines, in strategic locations, some of them showin
 
 What makes **PySnooper** stand out from all other code intelligence tools? You can use it in your shitty, sprawling enterprise codebase without having to do any setup. Just slap the decorator on, as shown below, and redirect the output to a dedicated log file by specifying its path as the first argument.
 
-# Example #
+## Example
 
 We're writing a function that converts a number to binary, by returning a list of bits. Let's snoop on it by adding the `@pysnooper.snoop()` decorator:
 
@@ -36,34 +34,7 @@ number_to_bits(6)
 ```
 The output to stderr is:
 
-```
-Starting var:.. number = 6
-15:29:11.327032 call         4 def number_to_bits(number):
-15:29:11.327032 line         5     if number:
-15:29:11.327032 line         6         bits = []
-New var:....... bits = []
-15:29:11.327032 line         7         while number:
-15:29:11.327032 line         8             number, remainder = divmod(number, 2)
-New var:....... remainder = 0
-Modified var:.. number = 3
-15:29:11.327032 line         9             bits.insert(0, remainder)
-Modified var:.. bits = [0]
-15:29:11.327032 line         7         while number:
-15:29:11.327032 line         8             number, remainder = divmod(number, 2)
-Modified var:.. number = 1
-Modified var:.. remainder = 1
-15:29:11.327032 line         9             bits.insert(0, remainder)
-Modified var:.. bits = [1, 0]
-15:29:11.327032 line         7         while number:
-15:29:11.327032 line         8             number, remainder = divmod(number, 2)
-Modified var:.. number = 0
-15:29:11.327032 line         9             bits.insert(0, remainder)
-Modified var:.. bits = [1, 1, 0]
-15:29:11.327032 line         7         while number:
-15:29:11.327032 line        10         return bits
-15:29:11.327032 return      10         return bits
-Return value:.. [1, 1, 0]
-```
+![](https://i.imgur.com/TrF3VVj.jpg)
 
 Or if you don't want to trace an entire function, you can wrap the relevant part in a `with` block:
 
@@ -98,9 +69,10 @@ New var:....... upper = 832
 74 453.0 832
 New var:....... mid = 453.0
 09:37:35.882486 line        13         print(lower, mid, upper)
+Elapsed time: 00:00:00.000344
 ```
 
-# Features #
+## Features
 
 If stderr is not easily accessible for you, you can redirect the output to a file:
 
@@ -116,146 +88,67 @@ See values of some expressions that aren't local variables:
 @pysnooper.snoop(watch=('foo.bar', 'self.x["whatever"]'))
 ```
 
-Expand values to see all their attributes or items of lists/dictionaries:
-
-```python
-@pysnooper.snoop(watch_explode=('foo', 'self'))
-```
-
-This will output lines like:
-
-```
-Modified var:.. foo[2] = 'whatever'
-New var:....... self.baz = 8
-```
-
-(see [Advanced Usage](#advanced-usage) for more control)
-
 Show snoop lines for functions that your function calls:
 
 ```python
 @pysnooper.snoop(depth=2)
 ```
 
-Start all snoop lines with a prefix, to grep for them easily:
+**See [Advanced Usage](https://github.com/cool-RR/PySnooper/blob/master/ADVANCED_USAGE.md) for more options.** <------
 
-```python
-@pysnooper.snoop(prefix='ZZZ ')
-```
 
-On multi-threaded apps identify which thread are snooped in output:
+## Installation with Pip
 
-```python
-@pysnooper.snoop(thread_info=True)
-```
+The best way to install **PySnooper** is with Pip:
 
-PySnooper supports decorating generators.
-
-You can also customize the repr of an object:
-
-```python
-def large(l):
-    return isinstance(l, list) and len(l) > 5
-
-def print_list_size(l):
-    return 'list(size={})'.format(len(l))
-
-def print_ndarray(a):
-    return 'ndarray(shape={}, dtype={})'.format(a.shape, a.dtype)
-
-@pysnooper.snoop(custom_repr=((large, print_list_size), (numpy.ndarray, print_ndarray)))
-def sum_to_x(x):
-    l = list(range(x))
-    a = numpy.zeros((10,10))
-    return sum(l)
-
-sum_to_x(10000)
-```
-
-You will get `l = list(size=10000)` for the list, and `a = ndarray(shape=(10, 10), dtype=float64)` for the ndarray.
-The `custom_repr` are matched in order, if one condition matches, no further conditions will be checked.
-
-# Installation #
-
-You can install **PySnooper** by:
-
-* pip:
 ```console
 $ pip install pysnooper
 ```
 
-* conda with conda-forge channel:
+## Other installation options
+
+Conda with conda-forge channel:
+
 ```console
 $ conda install -c conda-forge pysnooper
 ```
 
-# Advanced Usage #
-
-`watch_explode` will automatically guess how to expand the expression passed to it based on its class. You can be more specific by using one of the following classes:
-
-```python
-import pysnooper
-
-@pysnooper.snoop(watch=(
-    pysnooper.Attrs('x'),    # attributes
-    pysnooper.Keys('y'),     # mapping (e.g. dict) items
-    pysnooper.Indices('z'),  # sequence (e.g. list/tuple) items
-))
-```
-
-Exclude specific keys/attributes/indices with the `exclude` parameter, e.g. `Attrs('x', exclude=('_foo', '_bar'))`.
-
-Add a slice after `Indices` to only see the values within that slice, e.g. `Indices('z')[-3:]`.
-
-# Contribute #
-
-[Pull requests](https://github.com/cool-RR/PySnooper/pulls) are always welcome!
-Please, write tests and run them with [Tox](https://tox.readthedocs.io/).
-
-Tox installs all dependencies automatically. You only need to install Tox itself:
+Arch Linux:
 
 ```console
-$ pip install tox
+$ yay -S python-pysnooper
 ```
 
-List all environments `tox` would run:
+Fedora Linux:
 
 ```console
-$ tox -lv
+$ dnf install python3-pysnooper
 ```
 
-If you want to run tests against all target Python versions use [pyenv](
-https://github.com/pyenv/pyenv) to install them. Otherwise, you can run
-only linters and the ones you have already installed on your machine:
 
-```console
-# run only some environments
-$ tox -e flake8,pylint,bandit,py27,py36
+## Citing PySnooper
+
+If you use PySnooper in academic work, please use this citation format:
+
+```bibtex
+@software{rachum2019pysnooper,
+    title={PySnooper: Never use print for debugging again},
+    author={Rachum, Ram and Hall, Alex and Yanokura, Iori and others},
+    year={2019},
+    month={jun},
+    publisher={PyCon Israel},
+    doi={10.5281/zenodo.10462459},
+    url={https://github.com/cool-RR/PySnooper}
+}
 ```
 
-Or just install project in developer mode with test dependencies:
 
-``` bash
-$ pip install -e path/to/PySnooper[tests]
-```
-
-And run tests:
-
-``` bash
-$ pytest
-```
-
-Tests should pass before you push your code. They will be run again on Travis CI.
-
-# License #
+## License
 
 Copyright (c) 2019 Ram Rachum and collaborators, released under the MIT license.
 
-I provide [Development services in Python and Django](https://chipmunkdev.com
-) and I [give Python workshops](http://pythonworkshops.co/) to teach people
-Python and related topics.
 
-# Media Coverage #
+## Media Coverage
 
 [Hacker News thread](https://news.ycombinator.com/item?id=19717786)
 and [/r/Python Reddit thread](https://www.reddit.com/r/Python/comments/bg0ida/pysnooper_never_use_print_for_debugging_again/) (22 April 2019)

misc/IDE files/PySnooper.wpr

@@ -1,26 +1,27 @@
 #!wing
-#!version=7.0
+#!version=11.0
 ##################################################################
 # Wing project file                                              #
 ##################################################################
 [project attributes]
 proj.directory-list = [{'dirloc': loc('../..'),
-                        'excludes': [u'PySnooper.egg-info',
-                                     u'dist',
-                                     u'build'],
+                        'excludes': ['dist',
+                                     '.tox',
+                                     'htmlcov',
+                                     'build',
+                                     '.ipynb_checkpoints',
+                                     'PySnooper.egg-info'],
                         'filter': '*',
                         'include_hidden': False,
                         'recursive': True,
                         'watch_for_changes': True}]
 proj.file-type = 'shared'
 proj.home-dir = loc('../..')
-proj.launch-config = {loc('../../../../../../../Program Files/Python37/Scripts/pasteurize-script.py'): ('p'\
-        'roject',
-        (u'"c:\\Users\\Administrator\\Documents\\Python Projects\\PySnooper\\pysnooper" "c:\\Users\\Administrator\\Documents\\Python Projects\\PySnooper\\tests"',
+proj.launch-config = {loc('../../../../../../Program Files/Python37/Scripts/pasteurize-script.py'): ('project',
+        ('"c:\\Users\\Administrator\\Documents\\Python Projects\\PySnooper\\pysnooper" "c:\\Users\\Administrator\\Documents\\Python Projects\\PySnooper\\tests"',
          '')),
-                      loc('../../../../../Dropbox/Scripts and shortcuts/_simplify3d_add_m600.py'): ('p'\
-        'roject',
-        (u'"C:\\Users\\Administrator\\Dropbox\\Desktop\\foo.gcode"',
+                      loc('../../../../../Dropbox/Scripts and shortcuts/_simplify3d_add_m600.py'): ('project',
+        ('"C:\\Users\\Administrator\\Dropbox\\Desktop\\foo.gcode"',
          ''))}
 testing.auto-test-file-specs = (('regex',
                                  'pysnooper/tests.*/test[^./]*.py.?$'),)

misc/generate_authors.py

@@ -19,6 +19,11 @@ You probably want to run it this way:
 import subprocess
 import sys
 
+# This is used for people who show up more than once:
+deny_list = frozenset((
+    'Lumir Balhar',
+))
+
 
 def drop_recurrences(iterable):
     s = set()
@@ -28,26 +33,30 @@ def drop_recurrences(iterable):
             yield item
 
 
-def iterate_authors_by_chronological_order():
+def iterate_authors_by_chronological_order(branch):
     log_call = subprocess.run(
         (
-            'git', 'log', 'master', '--encoding=utf-8', '--full-history',
+            'git', 'log', branch, '--encoding=utf-8', '--full-history',
             '--reverse', '--format=format:%at;%an;%ae'
         ),
         stdout=subprocess.PIPE, stderr=subprocess.PIPE,
     )
     log_lines = log_call.stdout.decode('utf-8').split('\n')
-
-    return drop_recurrences(
-        (line.strip().split(";")[1] for line in log_lines)
-    )
+    
+    authors = tuple(line.strip().split(";")[1] for line in log_lines)
+    authors = (author for author in authors if author not in deny_list)
+    return drop_recurrences(authors)
 
 
-def print_authors():
-    for author in iterate_authors_by_chronological_order():
+def print_authors(branch):
+    for author in iterate_authors_by_chronological_order(branch):
         sys.stdout.buffer.write(author.encode())
         sys.stdout.buffer.write(b'\n')
 
 
 if __name__ == '__main__':
-    print_authors()
+    try:
+        branch = sys.argv[1]
+    except IndexError:
+        branch = 'master'
+    print_authors(branch)

pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"

pysnooper/__init__.py

@@ -24,7 +24,7 @@ import collections
 __VersionInfo = collections.namedtuple('VersionInfo',
                                        ('major', 'minor', 'micro'))
 
-__version__ = '0.1.0'
+__version__ = '1.2.3'
 __version_info__ = __VersionInfo(*(map(int, __version__.split('.'))))
 
 del collections, __VersionInfo # Avoid polluting the namespace

pysnooper/pycompat.py

@@ -6,6 +6,7 @@ import abc
 import os
 import inspect
 import sys
+import datetime as datetime_module
 
 PY3 = (sys.version_info[0] == 3)
 PY2 = not PY3
@@ -47,10 +48,51 @@ try:
 except AttributeError:
     iscoroutinefunction = lambda whatever: False # Lolz
 
+try:
+    isasyncgenfunction = inspect.isasyncgenfunction
+except AttributeError:
+    isasyncgenfunction = lambda whatever: False # Lolz
+
 
 if PY3:
     string_types = (str,)
     text_type = str
+    binary_type = bytes
 else:
     string_types = (basestring,)
     text_type = unicode
+    binary_type = str
+
+
+try:
+    from collections import abc as collections_abc
+except ImportError: # Python 2.7
+    import collections as collections_abc
+
+if sys.version_info[:2] >= (3, 6):
+    time_isoformat = datetime_module.time.isoformat
+else:
+    def time_isoformat(time, timespec='microseconds'):
+        assert isinstance(time, datetime_module.time)
+        if timespec != 'microseconds':
+            raise NotImplementedError
+        result = '{:02d}:{:02d}:{:02d}.{:06d}'.format(
+            time.hour, time.minute, time.second, time.microsecond
+        )
+        assert len(result) == 15
+        return result
+
+
+def timedelta_format(timedelta):
+    time = (datetime_module.datetime.min + timedelta).time()
+    return time_isoformat(time, timespec='microseconds')
+
+def timedelta_parse(s):
+    hours, minutes, seconds, microseconds = map(
+        int,
+        s.replace('.', ':').split(':')
+    )
+    return datetime_module.timedelta(hours=hours, minutes=minutes,
+                                     seconds=seconds,
+                                     microseconds=microseconds)
+

pysnooper/tracer.py

@@ -4,6 +4,7 @@
 import functools
 import inspect
 import opcode
+import os
 import sys
 import re
 import collections
@@ -19,18 +20,28 @@ if pycompat.PY2:
 
 
 ipython_filename_pattern = re.compile('^<ipython-input-([0-9]+)-.*>$')
+ansible_filename_pattern = re.compile(r'^(.+\.zip)[/|\\](ansible[/|\\]modules[/|\\].+\.py)$')
+ipykernel_filename_pattern = re.compile(r'^/var/folders/.*/ipykernel_[0-9]+/[0-9]+.py$')
+RETURN_OPCODES = {
+    'RETURN_GENERATOR', 'RETURN_VALUE', 'RETURN_CONST',
+    'INSTRUMENTED_RETURN_GENERATOR', 'INSTRUMENTED_RETURN_VALUE',
+    'INSTRUMENTED_RETURN_CONST', 'YIELD_VALUE', 'INSTRUMENTED_YIELD_VALUE'
+}
 
 
-def get_local_reprs(frame, watch=(), custom_repr=()):
+def get_local_reprs(frame, watch=(), custom_repr=(), max_length=None, normalize=False):
     code = frame.f_code
-    vars_order = code.co_varnames + code.co_cellvars + code.co_freevars + tuple(frame.f_locals.keys())
+    vars_order = (code.co_varnames + code.co_cellvars + code.co_freevars +
+                  tuple(frame.f_locals.keys()))
 
-    result_items = [(key, utils.get_shortish_repr(value, custom_repr=custom_repr)) for key, value in frame.f_locals.items()]
+    result_items = [(key, utils.get_shortish_repr(value, custom_repr,
+                                                  max_length, normalize))
+                    for key, value in frame.f_locals.items()]
     result_items.sort(key=lambda key_value: vars_order.index(key_value[0]))
     result = collections.OrderedDict(result_items)
 
     for variable in watch:
-        result.update(sorted(variable.items(frame)))
+        result.update(sorted(variable.items(frame, normalize)))
     return result
 
 
@@ -39,16 +50,16 @@ class UnavailableSource(object):
         return u'SOURCE IS UNAVAILABLE'
 
 
-source_cache = {}
+source_and_path_cache = {}
 
 
-def get_source_from_frame(frame):
+def get_path_and_source_from_frame(frame):
     globs = frame.f_globals or {}
     module_name = globs.get('__name__')
     file_name = frame.f_code.co_filename
     cache_key = (module_name, file_name)
     try:
-        return source_cache[cache_key]
+        return source_and_path_cache[cache_key]
     except KeyError:
         pass
     loader = globs.get('__loader__')
@@ -63,7 +74,16 @@ def get_source_from_frame(frame):
             source = source.splitlines()
     if source is None:
         ipython_filename_match = ipython_filename_pattern.match(file_name)
-        if ipython_filename_match:
+        ansible_filename_match = ansible_filename_pattern.match(file_name)
+        ipykernel_filename_match = ipykernel_filename_pattern.match(file_name)
+        if ipykernel_filename_match:
+            try:
+                import linecache
+                _, _, source, _ = linecache.cache.get(file_name)
+                source = [line.rstrip() for line in source] # remove '\n' at the end
+            except Exception:
+                pass
+        elif ipython_filename_match:
             entry_number = int(ipython_filename_match.group(1))
             try:
                 import IPython
@@ -73,13 +93,22 @@ def get_source_from_frame(frame):
                 source = source_chunk.splitlines()
             except Exception:
                 pass
+        elif ansible_filename_match:
+            try:
+                import zipfile
+                archive_file = zipfile.ZipFile(ansible_filename_match.group(1), 'r')
+                source = archive_file.read(ansible_filename_match.group(2).replace('\\', '/')).splitlines()
+            except Exception:
+                pass
         else:
             try:
                 with open(file_name, 'rb') as fp:
                     source = fp.read().splitlines()
             except utils.file_reading_errors:
                 pass
-    if source is None:
+    if not source:
+        # We used to check `if source is None` but I found a rare bug where it
+        # was empty, but not `None`, so now we check `if not source`.
         source = UnavailableSource()
 
     # If we just read the source from a file, or if the loader did not
@@ -97,8 +126,9 @@ def get_source_from_frame(frame):
         source = [pycompat.text_type(sline, encoding, 'replace') for sline in
                   source]
 
-    source_cache[cache_key] = source
-    return source
+    result = (file_name, source)
+    source_and_path_cache[cache_key] = result
+    return result
 
 
 def get_write_function(output, overwrite):
@@ -139,7 +169,7 @@ class FileWriter(object):
 
 
 thread_global = threading.local()
-
+DISABLED = bool(os.getenv('PYSNOOPER_DISABLED', ''))
 
 class Tracer:
     '''
@@ -181,20 +211,32 @@ class Tracer:
 
     Customize how values are represented as strings::
 
-        @pysnooper.snoop(custom_repr=((type1, custom_repr_func1), (condition2, custom_repr_func2), ...))
+        @pysnooper.snoop(custom_repr=((type1, custom_repr_func1),
+                         (condition2, custom_repr_func2), ...))
+
+    Variables and exceptions get truncated to 100 characters by default. You
+    can customize that:
+
+        @pysnooper.snoop(max_variable_length=200)
+
+    You can also use `max_variable_length=None` to never truncate them.
+
+    Show timestamps relative to start time rather than wall time::
+
+        @pysnooper.snoop(relative_time=True)
+
+    The output is colored for easy viewing by default, except on Windows
+    (but can be enabled by setting `color=True`).
+
+    Disable colors like so:
+
+        @pysnooper.snoop(color=False)
 
     '''
-    def __init__(
-            self,
-            output=None,
-            watch=(),
-            watch_explode=(),
-            depth=1,
-            prefix='',
-            overwrite=False,
-            thread_info=False,
-            custom_repr=(),
-    ):
+    def __init__(self, output=None, watch=(), watch_explode=(), depth=1,
+                 prefix='', overwrite=False, thread_info=False, custom_repr=(),
+                 max_variable_length=100, normalize=False, relative_time=False,
+                 color=sys.platform in ('linux', 'linux2', 'cygwin', 'darwin')):
         self._write = get_write_function(output, overwrite)
 
         self.watch = [
@@ -205,6 +247,7 @@ class Tracer:
              for v in utils.ensure_tuple(watch_explode)
         ]
         self.frame_to_local_reprs = {}
+        self.start_times = {}
         self.depth = depth
         self.prefix = prefix
         self.thread_info = thread_info
@@ -213,9 +256,62 @@ class Tracer:
         self.target_codes = set()
         self.target_frames = set()
         self.thread_local = threading.local()
+        if len(custom_repr) == 2 and not all(isinstance(x,
+                      pycompat.collections_abc.Iterable) for x in custom_repr):
+            custom_repr = (custom_repr,)
         self.custom_repr = custom_repr
+        self.last_source_path = None
+        self.max_variable_length = max_variable_length
+        self.normalize = normalize
+        self.relative_time = relative_time
+        self.color = color and (output is None)
 
-    def __call__(self, function):
+        if self.color:
+            self._FOREGROUND_BLUE = '\x1b[34m'
+            self._FOREGROUND_CYAN = '\x1b[36m'
+            self._FOREGROUND_GREEN = '\x1b[32m'
+            self._FOREGROUND_MAGENTA = '\x1b[35m'
+            self._FOREGROUND_RED = '\x1b[31m'
+            self._FOREGROUND_RESET = '\x1b[39m'
+            self._FOREGROUND_YELLOW = '\x1b[33m'
+            self._STYLE_BRIGHT = '\x1b[1m'
+            self._STYLE_DIM = '\x1b[2m'
+            self._STYLE_NORMAL = '\x1b[22m'
+            self._STYLE_RESET_ALL = '\x1b[0m'
+        else:
+            self._FOREGROUND_BLUE = ''
+            self._FOREGROUND_CYAN = ''
+            self._FOREGROUND_GREEN = ''
+            self._FOREGROUND_MAGENTA = ''
+            self._FOREGROUND_RED = ''
+            self._FOREGROUND_RESET = ''
+            self._FOREGROUND_YELLOW = ''
+            self._STYLE_BRIGHT = ''
+            self._STYLE_DIM = ''
+            self._STYLE_NORMAL = ''
+            self._STYLE_RESET_ALL = ''
+
+    def __call__(self, function_or_class):
+        if DISABLED:
+            return function_or_class
+
+        if inspect.isclass(function_or_class):
+            return self._wrap_class(function_or_class)
+        else:
+            return self._wrap_function(function_or_class)
+
+    def _wrap_class(self, cls):
+        for attr_name, attr in cls.__dict__.items():
+            # Coroutines are functions, but snooping them is not supported
+            # at the moment
+            if pycompat.iscoroutinefunction(attr):
+                continue
+
+            if inspect.isfunction(attr):
+                setattr(cls, attr_name, self._wrap_function(attr))
+        return cls
+
+    def _wrap_function(self, function):
         self.target_codes.add(function.__code__)
 
         @functools.wraps(function)
@@ -239,7 +335,8 @@ class Tracer:
                     method, incoming = gen.throw, e
 
         if pycompat.iscoroutinefunction(function):
-            # return decorate(function, coroutine_wrapper)
+            raise NotImplementedError
+        if pycompat.isasyncgenfunction(function):
             raise NotImplementedError
         elif inspect.isgeneratorfunction(function):
             return generator_wrapper
@@ -251,22 +348,49 @@ class Tracer:
         self._write(s)
 
     def __enter__(self):
+        if DISABLED:
+            return
+        thread_global.__dict__.setdefault('depth', -1)
         calling_frame = inspect.currentframe().f_back
         if not self._is_internal_frame(calling_frame):
             calling_frame.f_trace = self.trace
             self.target_frames.add(calling_frame)
 
-        stack = self.thread_local.__dict__.setdefault('original_trace_functions', [])
+        stack = self.thread_local.__dict__.setdefault(
+            'original_trace_functions', []
+        )
         stack.append(sys.gettrace())
+        self.start_times[calling_frame] = datetime_module.datetime.now()
         sys.settrace(self.trace)
 
     def __exit__(self, exc_type, exc_value, exc_traceback):
+        if DISABLED:
+            return
         stack = self.thread_local.original_trace_functions
         sys.settrace(stack.pop())
         calling_frame = inspect.currentframe().f_back
         self.target_frames.discard(calling_frame)
         self.frame_to_local_reprs.pop(calling_frame, None)
 
+        ### Writing elapsed time: #############################################
+        #                                                                     #
+        _FOREGROUND_YELLOW = self._FOREGROUND_YELLOW
+        _STYLE_DIM = self._STYLE_DIM
+        _STYLE_NORMAL = self._STYLE_NORMAL
+        _STYLE_RESET_ALL = self._STYLE_RESET_ALL
+
+        start_time = self.start_times.pop(calling_frame)
+        duration = datetime_module.datetime.now() - start_time
+        elapsed_time_string = pycompat.timedelta_format(duration)
+        indent = ' ' * 4 * (thread_global.depth + 1)
+        self.write(
+            '{indent}{_FOREGROUND_YELLOW}{_STYLE_DIM}'
+            'Elapsed time: {_STYLE_NORMAL}{elapsed_time_string}'
+            '{_STYLE_RESET_ALL}'.format(**locals())
+        )
+        #                                                                     #
+        ### Finished writing elapsed time. ####################################
+
     def _is_internal_frame(self, frame):
         return frame.f_code.co_filename == Tracer.__enter__.__code__.co_filename
 
@@ -276,7 +400,6 @@ class Tracer:
                                        current_thread_len)
         return thread_info.ljust(self.thread_info_padding)
 
-
     def trace(self, frame, event, arg):
 
         ### Checking whether we should trace this line: #######################
@@ -304,43 +427,90 @@ class Tracer:
                 else:
                     return None
 
-        thread_global.__dict__.setdefault('depth', -1)
+        #                                                                     #
+        ### Finished checking whether we should trace this line. ##############
+
         if event == 'call':
             thread_global.depth += 1
         indent = ' ' * 4 * thread_global.depth
 
+        _FOREGROUND_BLUE = self._FOREGROUND_BLUE
+        _FOREGROUND_CYAN = self._FOREGROUND_CYAN
+        _FOREGROUND_GREEN = self._FOREGROUND_GREEN
+        _FOREGROUND_MAGENTA = self._FOREGROUND_MAGENTA
+        _FOREGROUND_RED = self._FOREGROUND_RED
+        _FOREGROUND_RESET = self._FOREGROUND_RESET
+        _FOREGROUND_YELLOW = self._FOREGROUND_YELLOW
+        _STYLE_BRIGHT = self._STYLE_BRIGHT
+        _STYLE_DIM = self._STYLE_DIM
+        _STYLE_NORMAL = self._STYLE_NORMAL
+        _STYLE_RESET_ALL = self._STYLE_RESET_ALL
+
+        ### Making timestamp: #################################################
         #                                                                     #
-        ### Finished checking whether we should trace this line. ##############
+        if self.normalize:
+            timestamp = ' ' * 15
+        elif self.relative_time:
+            try:
+                start_time = self.start_times[frame]
+            except KeyError:
+                start_time = self.start_times[frame] = \
+                                                 datetime_module.datetime.now()
+            duration = datetime_module.datetime.now() - start_time
+            timestamp = pycompat.timedelta_format(duration)
+        else:
+            timestamp = pycompat.time_isoformat(
+                datetime_module.datetime.now().time(),
+                timespec='microseconds'
+            )
+        #                                                                     #
+        ### Finished making timestamp. ########################################
+
+        line_no = frame.f_lineno
+        source_path, source = get_path_and_source_from_frame(frame)
+        source_path = source_path if not self.normalize else os.path.basename(source_path)
+        if self.last_source_path != source_path:
+            self.write(u'{_FOREGROUND_YELLOW}{_STYLE_DIM}{indent}Source path:... '
+                       u'{_STYLE_NORMAL}{source_path}'
+                       u'{_STYLE_RESET_ALL}'.format(**locals()))
+            self.last_source_path = source_path
+        source_line = source[line_no - 1]
+        thread_info = ""
+        if self.thread_info:
+            if self.normalize:
+                raise NotImplementedError("normalize is not supported with "
+                                          "thread_info")
+            current_thread = threading.current_thread()
+            thread_info = "{ident}-{name} ".format(
+                ident=current_thread.ident, name=current_thread.name)
+        thread_info = self.set_thread_info_padding(thread_info)
 
         ### Reporting newish and modified variables: ##########################
         #                                                                     #
         old_local_reprs = self.frame_to_local_reprs.get(frame, {})
         self.frame_to_local_reprs[frame] = local_reprs = \
-                                       get_local_reprs(frame, watch=self.watch, custom_repr=self.custom_repr)
+                                       get_local_reprs(frame,
+                                                       watch=self.watch, custom_repr=self.custom_repr,
+                                                       max_length=self.max_variable_length,
+                                                       normalize=self.normalize,
+                                                       )
 
         newish_string = ('Starting var:.. ' if event == 'call' else
                                                             'New var:....... ')
 
         for name, value_repr in local_reprs.items():
             if name not in old_local_reprs:
-                self.write('{indent}{newish_string}{name} = {value_repr}'.format(
-                                                                       **locals()))
+                self.write('{indent}{_FOREGROUND_GREEN}{_STYLE_DIM}'
+                           '{newish_string}{_STYLE_NORMAL}{name} = '
+                           '{value_repr}{_STYLE_RESET_ALL}'.format(**locals()))
             elif old_local_reprs[name] != value_repr:
-                self.write('{indent}Modified var:.. {name} = {value_repr}'.format(
-                                                                   **locals()))
+                self.write('{indent}{_FOREGROUND_GREEN}{_STYLE_DIM}'
+                           'Modified var:.. {_STYLE_NORMAL}{name} = '
+                           '{value_repr}{_STYLE_RESET_ALL}'.format(**locals()))
 
         #                                                                     #
         ### Finished newish and modified variables. ###########################
 
-        now_string = datetime_module.datetime.now().time().isoformat()
-        line_no = frame.f_lineno
-        source_line = get_source_from_frame(frame)[line_no - 1]
-        thread_info = ""
-        if self.thread_info:
-            current_thread = threading.current_thread()
-            thread_info = "{ident}-{name} ".format(
-                ident=current_thread.ident, name=current_thread.getName())
-        thread_info = self.set_thread_info_padding(thread_info)
 
         ### Dealing with misplaced function definition: #######################
         #                                                                     #
@@ -349,8 +519,7 @@ class Tracer:
             # function definition is found.
             for candidate_line_no in itertools.count(line_no):
                 try:
-                    candidate_source_line = \
-                            get_source_from_frame(frame)[candidate_line_no - 1]
+                    candidate_source_line = source[candidate_line_no - 1]
                 except IndexError:
                     # End of source file reached without finding a function
                     # definition. Fall back to original source line.
@@ -373,30 +542,38 @@ class Tracer:
         ended_by_exception = (
                 event == 'return'
                 and arg is None
-                and (opcode.opname[code_byte]
-                     not in ('RETURN_VALUE', 'YIELD_VALUE'))
+                and opcode.opname[code_byte] not in RETURN_OPCODES
         )
 
         if ended_by_exception:
-            self.write('{indent}Call ended by exception'.
+            self.write('{_FOREGROUND_RED}{indent}Call ended by exception{_STYLE_RESET_ALL}'.
                        format(**locals()))
         else:
-            self.write(u'{indent}{now_string} {thread_info}{event:9} '
-                       u'{line_no:4} {source_line}'.format(**locals()))
+            self.write(u'{indent}{_STYLE_DIM}{timestamp} {thread_info}{event:9} '
+                       u'{line_no:4}{_STYLE_RESET_ALL} {source_line}'.format(**locals()))
 
         if event == 'return':
-            del self.frame_to_local_reprs[frame]
+            self.frame_to_local_reprs.pop(frame, None)
+            self.start_times.pop(frame, None)
             thread_global.depth -= 1
 
             if not ended_by_exception:
-                return_value_repr = utils.get_shortish_repr(arg, custom_repr=self.custom_repr)
-                self.write('{indent}Return value:.. {return_value_repr}'.
+                return_value_repr = utils.get_shortish_repr(arg,
+                                                            custom_repr=self.custom_repr,
+                                                            max_length=self.max_variable_length,
+                                                            normalize=self.normalize,
+                                                            )
+                self.write('{indent}{_FOREGROUND_CYAN}{_STYLE_DIM}'
+                           'Return value:.. {_STYLE_NORMAL}{return_value_repr}'
+                           '{_STYLE_RESET_ALL}'.
                            format(**locals()))
 
         if event == 'exception':
             exception = '\n'.join(traceback.format_exception_only(*arg[:2])).strip()
-            exception = utils.truncate(exception, utils.MAX_EXCEPTION_LENGTH)
-            self.write('{indent}{exception}'.
-                       format(**locals()))
+            if self.max_variable_length:
+                exception = utils.truncate(exception, self.max_variable_length)
+            self.write('{indent}{_FOREGROUND_RED}Exception:..... '
+                       '{_STYLE_BRIGHT}{exception}'
+                       '{_STYLE_RESET_ALL}'.format(**locals()))
 
         return self.trace

pysnooper/utils.py

@@ -2,12 +2,10 @@
 # This program is distributed under the MIT license.
 
 import abc
+import re
 
 import sys
-from .pycompat import ABC, string_types
-
-MAX_VARIABLE_LENGTH = 100
-MAX_EXCEPTION_LENGTH = 200
+from .pycompat import ABC, string_types, collections_abc
 
 def _check_methods(C, *methods):
     mro = C.__mro__
@@ -58,29 +56,43 @@ def get_repr_function(item, custom_repr):
     return repr
 
 
-def get_shortish_repr(item, custom_repr=()):
+DEFAULT_REPR_RE = re.compile(r' at 0x[a-f0-9A-F]{4,}')
+
+
+def normalize_repr(item_repr):
+    """Remove memory address (0x...) from a default python repr"""
+    return DEFAULT_REPR_RE.sub('', item_repr)
+
+
+def get_shortish_repr(item, custom_repr=(), max_length=None, normalize=False):
     repr_function = get_repr_function(item, custom_repr)
     try:
         r = repr_function(item)
     except Exception:
         r = 'REPR FAILED'
     r = r.replace('\r', '').replace('\n', '')
-    r = truncate(r, MAX_VARIABLE_LENGTH)
+    if normalize:
+        r = normalize_repr(r)
+    if max_length:
+        r = truncate(r, max_length)
     return r
 
 
 def truncate(string, max_length):
-    if len(string) > max_length:
+    if (max_length is None) or (len(string) <= max_length):
+        return string
+    else:
         left = (max_length - 3) // 2
         right = max_length - 3 - left
-        string = u'{}...{}'.format(string[:left], string[-right:])
-    return string
+        return u'{}...{}'.format(string[:left], string[-right:])
 
 
 def ensure_tuple(x):
-    if isinstance(x, string_types):
-        x = (x,)
-    return tuple(x)
+    if isinstance(x, collections_abc.Iterable) and \
+                                               not isinstance(x, string_types):
+        return tuple(x)
+    else:
+        return (x,)
 
 
 

pysnooper/variables.py

@@ -1,6 +1,9 @@
 import itertools
 import abc
-from collections import Mapping, Sequence
+try:
+    from collections.abc import Mapping, Sequence
+except ImportError:
+    from collections import Mapping, Sequence
 from copy import deepcopy
 
 from . import utils
@@ -24,21 +27,32 @@ class BaseVariable(pycompat.ABC):
         else:
             self.unambiguous_source = source
 
-    def items(self, frame):
+    def items(self, frame, normalize=False):
         try:
             main_value = eval(self.code, frame.f_globals or {}, frame.f_locals)
         except Exception:
             return ()
-        return self._items(main_value)
+        return self._items(main_value, normalize)
 
     @abc.abstractmethod
-    def _items(self, key):
+    def _items(self, key, normalize=False):
         raise NotImplementedError
 
+    @property
+    def _fingerprint(self):
+        return (type(self), self.source, self.exclude)
+
+    def __hash__(self):
+        return hash(self._fingerprint)
+
+    def __eq__(self, other):
+        return (isinstance(other, BaseVariable) and
+                                       self._fingerprint == other._fingerprint)
+
 
 class CommonVariable(BaseVariable):
-    def _items(self, main_value):
-        result = [(self.source, utils.get_shortish_repr(main_value))]
+    def _items(self, main_value, normalize=False):
+        result = [(self.source, utils.get_shortish_repr(main_value, normalize=normalize))]
         for key in self._safe_keys(main_value):
             try:
                 if key in self.exclude:
@@ -108,7 +122,7 @@ class Indices(Keys):
 
 
 class Exploding(BaseVariable):
-    def _items(self, main_value):
+    def _items(self, main_value, normalize=False):
         if isinstance(main_value, Mapping):
             cls = Keys
         elif isinstance(main_value, Sequence):
@@ -116,4 +130,4 @@ class Exploding(BaseVariable):
         else:
             cls = Attrs
 
-        return cls(self.source, self.exclude)._items(main_value)
+        return cls(self.source, self.exclude)._items(main_value, normalize)

setup.cfg

@@ -0,0 +1,37 @@
+[metadata]
+name = PySnooper
+version = attr: pysnooper.__version__
+author = Ram Rachum
+author_email = ram@rachum.com
+description = A poor man's debugger for Python.
+url = https://github.com/cool-RR/PySnooper
+long_description = file: README.md
+long_description_content_type = text/markdown
+classifiers =
+    Environment :: Console
+    Intended Audience :: Developers
+    Programming Language :: Python :: 2.7
+    Programming Language :: Python :: 3.4
+    Programming Language :: Python :: 3.5
+    Programming Language :: Python :: 3.6
+    Programming Language :: Python :: 3.7
+    Programming Language :: Python :: 3.8
+    Programming Language :: Python :: 3.9
+    Programming Language :: Python :: 3.10
+    Programming Language :: Python :: 3.11
+    Programming Language :: Python :: 3.12
+    Programming Language :: Python :: Implementation :: CPython
+    Programming Language :: Python :: Implementation :: PyPy
+    License :: OSI Approved :: MIT License
+    Operating System :: OS Independent
+    Topic :: Software Development :: Debuggers
+
+[options]
+packages = find:
+install_requires = file: requirements.in
+
+[options.packages.find]
+exclude = tests*
+
+[options.extras_require]
+tests = pytest

setup.py

@@ -20,12 +20,11 @@ setuptools.setup(
     long_description=read_file('README.md'),
     long_description_content_type='text/markdown',
     url='https://github.com/cool-RR/PySnooper',
-    packages=setuptools.find_packages(exclude=['tests']),
+    packages=setuptools.find_packages(exclude=['tests*']),
     install_requires=read_file('requirements.in'),
     extras_require={
         'tests': {
             'pytest',
-            'python-toolbox',
         },
     },
     classifiers=[
@@ -37,6 +36,9 @@ setuptools.setup(
         'Programming Language :: Python :: 3.6',
         'Programming Language :: Python :: 3.7',
         'Programming Language :: Python :: 3.8',
+        'Programming Language :: Python :: 3.9',
+        'Programming Language :: Python :: 3.10',
+        'Programming Language :: Python :: 3.11',
         'Programming Language :: Python :: Implementation :: CPython',
         'Programming Language :: Python :: Implementation :: PyPy',
         'License :: OSI Approved :: MIT License',

tests/mini_toolbox/__init__.py

@@ -0,0 +1,254 @@
+# Copyright 2019 Ram Rachum and collaborators.
+# This program is distributed under the MIT license.
+
+import tempfile
+import shutil
+import io
+import sys
+from . import pathlib
+from . import contextlib
+
+
+
+@contextlib.contextmanager
+def BlankContextManager():
+    yield
+
+@contextlib.contextmanager
+def create_temp_folder(prefix=tempfile.template, suffix='',
+                       parent_folder=None, chmod=None):
+    '''
+    Context manager that creates a temporary folder and deletes it after usage.
+
+    After the suite finishes, the temporary folder and all its files and
+    subfolders will be deleted.
+
+    Example:
+
+        with create_temp_folder() as temp_folder:
+
+            # We have a temporary folder!
+            assert temp_folder.is_dir()
+
+            # We can create files in it:
+            (temp_folder / 'my_file').open('w')
+
+        # The suite is finished, now it's all cleaned:
+        assert not temp_folder.exists()
+
+    Use the `prefix` and `suffix` string arguments to dictate a prefix and/or a
+    suffix to the temporary folder's name in the filesystem.
+
+    If you'd like to set the permissions of the temporary folder, pass them to
+    the optional `chmod` argument, like this:
+
+        create_temp_folder(chmod=0o550)
+
+    '''
+    temp_folder = pathlib.Path(tempfile.mkdtemp(prefix=prefix, suffix=suffix,
+                                                dir=parent_folder))
+    try:
+        if chmod is not None:
+            temp_folder.chmod(chmod)
+        yield temp_folder
+    finally:
+        shutil.rmtree(str(temp_folder))
+
+
+class NotInDict:
+    '''Object signifying that the key was not found in the dict.'''
+
+
+class TempValueSetter(object):
+    '''
+    Context manager for temporarily setting a value to a variable.
+
+    The value is set to the variable before the suite starts, and gets reset
+    back to the old value after the suite finishes.
+    '''
+
+    def __init__(self, variable, value, assert_no_fiddling=True):
+        '''
+        Construct the `TempValueSetter`.
+
+        `variable` may be either an `(object, attribute_string)`, a `(dict,
+        key)` pair, or a `(getter, setter)` pair.
+
+        `value` is the temporary value to set to the variable.
+        '''
+
+        self.assert_no_fiddling = assert_no_fiddling
+
+
+        #######################################################################
+        # We let the user input either an `(object, attribute_string)`, a
+        # `(dict, key)` pair, or a `(getter, setter)` pair. So now it's our job
+        # to inspect `variable` and figure out which one of these options the
+        # user chose, and then obtain from that a `(getter, setter)` pair that
+        # we could use.
+
+        bad_input_exception = Exception(
+            '`variable` must be either an `(object, attribute_string)` pair, '
+            'a `(dict, key)` pair, or a `(getter, setter)` pair.'
+        )
+
+        try:
+            first, second = variable
+        except Exception:
+            raise bad_input_exception
+        if hasattr(first, '__getitem__') and hasattr(first, 'get') and \
+           hasattr(first, '__setitem__') and hasattr(first, '__delitem__'):
+            # `first` is a dictoid; so we were probably handed a `(dict, key)`
+            # pair.
+            self.getter = lambda: first.get(second, NotInDict)
+            self.setter = lambda value: (first.__setitem__(second, value) if
+                                         value is not NotInDict else
+                                         first.__delitem__(second))
+            ### Finished handling the `(dict, key)` case. ###
+
+        elif callable(second):
+            # `second` is a callable; so we were probably handed a `(getter,
+            # setter)` pair.
+            if not callable(first):
+                raise bad_input_exception
+            self.getter, self.setter = first, second
+            ### Finished handling the `(getter, setter)` case. ###
+        else:
+            # All that's left is the `(object, attribute_string)` case.
+            if not isinstance(second, str):
+                raise bad_input_exception
+
+            parent, attribute_name = first, second
+            self.getter = lambda: getattr(parent, attribute_name)
+            self.setter = lambda value: setattr(parent, attribute_name, value)
+            ### Finished handling the `(object, attribute_string)` case. ###
+
+        #
+        #
+        ### Finished obtaining a `(getter, setter)` pair from `variable`. #####
+
+
+        self.getter = self.getter
+        '''Getter for getting the current value of the variable.'''
+
+        self.setter = self.setter
+        '''Setter for Setting the the variable's value.'''
+
+        self.value = value
+        '''The value to temporarily set to the variable.'''
+
+        self.active = False
+
+
+    def __enter__(self):
+
+        self.active = True
+
+        self.old_value = self.getter()
+        '''The old value of the variable, before entering the suite.'''
+
+        self.setter(self.value)
+
+        # In `__exit__` we'll want to check if anyone changed the value of the
+        # variable in the suite, which is unallowed. But we can't compare to
+        # `.value`, because sometimes when you set a value to a variable, some
+        # mechanism modifies that value for various reasons, resulting in a
+        # supposedly equivalent, but not identical, value. For example this
+        # happens when you set the current working directory on Mac OS.
+        #
+        # So here we record the value right after setting, and after any
+        # possible processing the system did to it:
+        self._value_right_after_setting = self.getter()
+
+        return self
+
+
+    def __exit__(self, exc_type, exc_value, exc_traceback):
+
+        if self.assert_no_fiddling:
+            # Asserting no-one inside the suite changed our variable:
+            assert self.getter() == self._value_right_after_setting
+
+        self.setter(self.old_value)
+
+        self.active = False
+
+class OutputCapturer(object):
+    '''
+    Context manager for catching all system output generated during suite.
+
+    Example:
+
+        with OutputCapturer() as output_capturer:
+            print('woo!')
+
+        assert output_capturer.output == 'woo!\n'
+
+    The boolean arguments `stdout` and `stderr` determine, respectively,
+    whether the standard-output and the standard-error streams will be
+    captured.
+    '''
+    def __init__(self, stdout=True, stderr=True):
+        self.string_io = io.StringIO()
+
+        if stdout:
+            self._stdout_temp_setter = \
+                TempValueSetter((sys, 'stdout'), self.string_io)
+        else: # not stdout
+            self._stdout_temp_setter = BlankContextManager()
+
+        if stderr:
+            self._stderr_temp_setter = \
+                TempValueSetter((sys, 'stderr'), self.string_io)
+        else: # not stderr
+            self._stderr_temp_setter = BlankContextManager()
+
+    def __enter__(self):
+        '''Manage the `OutputCapturer`'s context.'''
+        self._stdout_temp_setter.__enter__()
+        self._stderr_temp_setter.__enter__()
+        return self
+
+    def __exit__(self, exc_type, exc_value, exc_traceback):
+        # Not doing exception swallowing anywhere here.
+        self._stderr_temp_setter.__exit__(exc_type, exc_value, exc_traceback)
+        self._stdout_temp_setter.__exit__(exc_type, exc_value, exc_traceback)
+
+    output = property(lambda self: self.string_io.getvalue(),
+                      doc='''The string of output that was captured.''')
+
+
+class TempSysPathAdder(object):
+    '''
+    Context manager for temporarily adding paths to `sys.path`.
+
+    Removes the path(s) after suite.
+
+    Example:
+
+        with TempSysPathAdder('path/to/fubar/package'):
+            import fubar
+            fubar.do_stuff()
+
+    '''
+    def __init__(self, addition):
+        self.addition = [str(addition)]
+
+
+    def __enter__(self):
+        self.entries_not_in_sys_path = [entry for entry in self.addition if
+                                        entry not in sys.path]
+        sys.path += self.entries_not_in_sys_path
+        return self
+
+
+    def __exit__(self, *args, **kwargs):
+
+        for entry in self.entries_not_in_sys_path:
+
+            # We don't allow anyone to remove it except for us:
+            assert entry in sys.path
+
+            sys.path.remove(entry)
+
+

tests/mini_toolbox/contextlib.py

@@ -0,0 +1,436 @@
+"""contextlib2 - backports and enhancements to the contextlib module"""
+
+import sys
+import warnings
+from collections import deque
+from functools import wraps
+
+__all__ = ["contextmanager", "closing", "ContextDecorator", "ExitStack",
+           "redirect_stdout", "redirect_stderr", "suppress"]
+
+# Backwards compatibility
+__all__ += ["ContextStack"]
+
+class ContextDecorator(object):
+    "A base class or mixin that enables context managers to work as decorators."
+
+    def refresh_cm(self):
+        """Returns the context manager used to actually wrap the call to the
+        decorated function.
+
+        The default implementation just returns *self*.
+
+        Overriding this method allows otherwise one-shot context managers
+        like _GeneratorContextManager to support use as decorators via
+        implicit recreation.
+
+        DEPRECATED: refresh_cm was never added to the standard library's
+                    ContextDecorator API
+        """
+        warnings.warn("refresh_cm was never added to the standard library",
+                      DeprecationWarning)
+        return self._recreate_cm()
+
+    def _recreate_cm(self):
+        """Return a recreated instance of self.
+
+        Allows an otherwise one-shot context manager like
+        _GeneratorContextManager to support use as
+        a decorator via implicit recreation.
+
+        This is a private interface just for _GeneratorContextManager.
+        See issue #11647 for details.
+        """
+        return self
+
+    def __call__(self, func):
+        @wraps(func)
+        def inner(*args, **kwds):
+            with self._recreate_cm():
+                return func(*args, **kwds)
+        return inner
+
+
+class _GeneratorContextManager(ContextDecorator):
+    """Helper for @contextmanager decorator."""
+
+    def __init__(self, func, args, kwds):
+        self.gen = func(*args, **kwds)
+        self.func, self.args, self.kwds = func, args, kwds
+        # Issue 19330: ensure context manager instances have good docstrings
+        doc = getattr(func, "__doc__", None)
+        if doc is None:
+            doc = type(self).__doc__
+        self.__doc__ = doc
+        # Unfortunately, this still doesn't provide good help output when
+        # inspecting the created context manager instances, since pydoc
+        # currently bypasses the instance docstring and shows the docstring
+        # for the class instead.
+        # See http://bugs.python.org/issue19404 for more details.
+
+    def _recreate_cm(self):
+        # _GCM instances are one-shot context managers, so the
+        # CM must be recreated each time a decorated function is
+        # called
+        return self.__class__(self.func, self.args, self.kwds)
+
+    def __enter__(self):
+        try:
+            return next(self.gen)
+        except StopIteration:
+            raise RuntimeError("generator didn't yield")
+
+    def __exit__(self, type, value, traceback):
+        if type is None:
+            try:
+                next(self.gen)
+            except StopIteration:
+                return
+            else:
+                raise RuntimeError("generator didn't stop")
+        else:
+            if value is None:
+                # Need to force instantiation so we can reliably
+                # tell if we get the same exception back
+                value = type()
+            try:
+                self.gen.throw(type, value, traceback)
+                raise RuntimeError("generator didn't stop after throw()")
+            except StopIteration as exc:
+                # Suppress StopIteration *unless* it's the same exception that
+                # was passed to throw().  This prevents a StopIteration
+                # raised inside the "with" statement from being suppressed.
+                return exc is not value
+            except RuntimeError as exc:
+                # Don't re-raise the passed in exception
+                if exc is value:
+                    return False
+                # Likewise, avoid suppressing if a StopIteration exception
+                # was passed to throw() and later wrapped into a RuntimeError
+                # (see PEP 479).
+                if _HAVE_EXCEPTION_CHAINING and exc.__cause__ is value:
+                    return False
+                raise
+            except:
+                # only re-raise if it's *not* the exception that was
+                # passed to throw(), because __exit__() must not raise
+                # an exception unless __exit__() itself failed.  But throw()
+                # has to raise the exception to signal propagation, so this
+                # fixes the impedance mismatch between the throw() protocol
+                # and the __exit__() protocol.
+                #
+                if sys.exc_info()[1] is not value:
+                    raise
+
+
+def contextmanager(func):
+    """@contextmanager decorator.
+
+    Typical usage:
+
+        @contextmanager
+        def some_generator(<arguments>):
+            <setup>
+            try:
+                yield <value>
+            finally:
+                <cleanup>
+
+    This makes this:
+
+        with some_generator(<arguments>) as <variable>:
+            <body>
+
+    equivalent to this:
+
+        <setup>
+        try:
+            <variable> = <value>
+            <body>
+        finally:
+            <cleanup>
+
+    """
+    @wraps(func)
+    def helper(*args, **kwds):
+        return _GeneratorContextManager(func, args, kwds)
+    return helper
+
+
+class closing(object):
+    """Context to automatically close something at the end of a block.
+
+    Code like this:
+
+        with closing(<module>.open(<arguments>)) as f:
+            <block>
+
+    is equivalent to this:
+
+        f = <module>.open(<arguments>)
+        try:
+            <block>
+        finally:
+            f.close()
+
+    """
+    def __init__(self, thing):
+        self.thing = thing
+    def __enter__(self):
+        return self.thing
+    def __exit__(self, *exc_info):
+        self.thing.close()
+
+
+class _RedirectStream(object):
+
+    _stream = None
+
+    def __init__(self, new_target):
+        self._new_target = new_target
+        # We use a list of old targets to make this CM re-entrant
+        self._old_targets = []
+
+    def __enter__(self):
+        self._old_targets.append(getattr(sys, self._stream))
+        setattr(sys, self._stream, self._new_target)
+        return self._new_target
+
+    def __exit__(self, exctype, excinst, exctb):
+        setattr(sys, self._stream, self._old_targets.pop())
+
+
+class redirect_stdout(_RedirectStream):
+    """Context manager for temporarily redirecting stdout to another file.
+
+        # How to send help() to stderr
+        with redirect_stdout(sys.stderr):
+            help(dir)
+
+        # How to write help() to a file
+        with open('help.txt', 'w') as f:
+            with redirect_stdout(f):
+                help(pow)
+    """
+
+    _stream = "stdout"
+
+
+class redirect_stderr(_RedirectStream):
+    """Context manager for temporarily redirecting stderr to another file."""
+
+    _stream = "stderr"
+
+
+class suppress(object):
+    """Context manager to suppress specified exceptions
+
+    After the exception is suppressed, execution proceeds with the next
+    statement following the with statement.
+
+         with suppress(FileNotFoundError):
+             os.remove(somefile)
+         # Execution still resumes here if the file was already removed
+    """
+
+    def __init__(self, *exceptions):
+        self._exceptions = exceptions
+
+    def __enter__(self):
+        pass
+
+    def __exit__(self, exctype, excinst, exctb):
+        # Unlike isinstance and issubclass, CPython exception handling
+        # currently only looks at the concrete type hierarchy (ignoring
+        # the instance and subclass checking hooks). While Guido considers
+        # that a bug rather than a feature, it's a fairly hard one to fix
+        # due to various internal implementation details. suppress provides
+        # the simpler issubclass based semantics, rather than trying to
+        # exactly reproduce the limitations of the CPython interpreter.
+        #
+        # See http://bugs.python.org/issue12029 for more details
+        return exctype is not None and issubclass(exctype, self._exceptions)
+
+
+# Context manipulation is Python 3 only
+_HAVE_EXCEPTION_CHAINING = sys.version_info[0] >= 3
+if _HAVE_EXCEPTION_CHAINING:
+    def _make_context_fixer(frame_exc):
+        def _fix_exception_context(new_exc, old_exc):
+            # Context may not be correct, so find the end of the chain
+            while 1:
+                exc_context = new_exc.__context__
+                if exc_context is old_exc:
+                    # Context is already set correctly (see issue 20317)
+                    return
+                if exc_context is None or exc_context is frame_exc:
+                    break
+                new_exc = exc_context
+            # Change the end of the chain to point to the exception
+            # we expect it to reference
+            new_exc.__context__ = old_exc
+        return _fix_exception_context
+
+    def _reraise_with_existing_context(exc_details):
+        try:
+            # bare "raise exc_details[1]" replaces our carefully
+            # set-up context
+            fixed_ctx = exc_details[1].__context__
+            raise exc_details[1]
+        except BaseException:
+            exc_details[1].__context__ = fixed_ctx
+            raise
+else:
+    # No exception context in Python 2
+    def _make_context_fixer(frame_exc):
+        return lambda new_exc, old_exc: None
+
+    # Use 3 argument raise in Python 2,
+    # but use exec to avoid SyntaxError in Python 3
+    def _reraise_with_existing_context(exc_details):
+        exc_type, exc_value, exc_tb = exc_details
+        exec ("raise exc_type, exc_value, exc_tb")
+
+# Handle old-style classes if they exist
+try:
+    from types import InstanceType
+except ImportError:
+    # Python 3 doesn't have old-style classes
+    _get_type = type
+else:
+    # Need to handle old-style context managers on Python 2
+    def _get_type(obj):
+        obj_type = type(obj)
+        if obj_type is InstanceType:
+            return obj.__class__ # Old-style class
+        return obj_type # New-style class
+
+# Inspired by discussions on http://bugs.python.org/issue13585
+class ExitStack(object):
+    """Context manager for dynamic management of a stack of exit callbacks
+
+    For example:
+
+        with ExitStack() as stack:
+            files = [stack.enter_context(open(fname)) for fname in filenames]
+            # All opened files will automatically be closed at the end of
+            # the with statement, even if attempts to open files later
+            # in the list raise an exception
+
+    """
+    def __init__(self):
+        self._exit_callbacks = deque()
+
+    def pop_all(self):
+        """Preserve the context stack by transferring it to a new instance"""
+        new_stack = type(self)()
+        new_stack._exit_callbacks = self._exit_callbacks
+        self._exit_callbacks = deque()
+        return new_stack
+
+    def _push_cm_exit(self, cm, cm_exit):
+        """Helper to correctly register callbacks to __exit__ methods"""
+        def _exit_wrapper(*exc_details):
+            return cm_exit(cm, *exc_details)
+        _exit_wrapper.__self__ = cm
+        self.push(_exit_wrapper)
+
+    def push(self, exit):
+        """Registers a callback with the standard __exit__ method signature
+
+        Can suppress exceptions the same way __exit__ methods can.
+
+        Also accepts any object with an __exit__ method (registering a call
+        to the method instead of the object itself)
+        """
+        # We use an unbound method rather than a bound method to follow
+        # the standard lookup behaviour for special methods
+        _cb_type = _get_type(exit)
+        try:
+            exit_method = _cb_type.__exit__
+        except AttributeError:
+            # Not a context manager, so assume its a callable
+            self._exit_callbacks.append(exit)
+        else:
+            self._push_cm_exit(exit, exit_method)
+        return exit # Allow use as a decorator
+
+    def callback(self, callback, *args, **kwds):
+        """Registers an arbitrary callback and arguments.
+
+        Cannot suppress exceptions.
+        """
+        def _exit_wrapper(exc_type, exc, tb):
+            callback(*args, **kwds)
+        # We changed the signature, so using @wraps is not appropriate, but
+        # setting __wrapped__ may still help with introspection
+        _exit_wrapper.__wrapped__ = callback
+        self.push(_exit_wrapper)
+        return callback # Allow use as a decorator
+
+    def enter_context(self, cm):
+        """Enters the supplied context manager
+
+        If successful, also pushes its __exit__ method as a callback and
+        returns the result of the __enter__ method.
+        """
+        # We look up the special methods on the type to match the with statement
+        _cm_type = _get_type(cm)
+        _exit = _cm_type.__exit__
+        result = _cm_type.__enter__(cm)
+        self._push_cm_exit(cm, _exit)
+        return result
+
+    def close(self):
+        """Immediately unwind the context stack"""
+        self.__exit__(None, None, None)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc_details):
+        received_exc = exc_details[0] is not None
+
+        # We manipulate the exception state so it behaves as though
+        # we were actually nesting multiple with statements
+        frame_exc = sys.exc_info()[1]
+        _fix_exception_context = _make_context_fixer(frame_exc)
+
+        # Callbacks are invoked in LIFO order to match the behaviour of
+        # nested context managers
+        suppressed_exc = False
+        pending_raise = False
+        while self._exit_callbacks:
+            cb = self._exit_callbacks.pop()
+            try:
+                if cb(*exc_details):
+                    suppressed_exc = True
+                    pending_raise = False
+                    exc_details = (None, None, None)
+            except:
+                new_exc_details = sys.exc_info()
+                # simulate the stack of exceptions by setting the context
+                _fix_exception_context(new_exc_details[1], exc_details[1])
+                pending_raise = True
+                exc_details = new_exc_details
+        if pending_raise:
+            _reraise_with_existing_context(exc_details)
+        return received_exc and suppressed_exc
+
+# Preserve backwards compatibility
+class ContextStack(ExitStack):
+    """Backwards compatibility alias for ExitStack"""
+
+    def __init__(self):
+        warnings.warn("ContextStack has been renamed to ExitStack",
+                      DeprecationWarning)
+        super(ContextStack, self).__init__()
+
+    def register_exit(self, callback):
+        return self.push(callback)
+
+    def register(self, callback, *args, **kwds):
+        return self.callback(callback, *args, **kwds)
+
+    def preserve(self):
+        return self.pop_all()

tests/samples/exception.py

@@ -13,7 +13,7 @@ def bar():
         raise
 
 
-@pysnooper.snoop(depth=3)
+@pysnooper.snoop(depth=3, color=False)
 def main():
     try:
         bar()
@@ -22,6 +22,7 @@ def main():
 
 
 expected_output = '''
+Source path:... Whatever
 12:18:08.017782 call        17 def main():
 12:18:08.018142 line        18     try:
 12:18:08.018181 line        19         bar()
@@ -45,4 +46,5 @@ TypeError: bad
 12:18:08.018787 line        21         pass
 12:18:08.018813 return      21         pass
 Return value:.. None
+Elapsed time: 00:00:00.000885
 '''

tests/samples/indentation.py

@@ -1,7 +1,7 @@
 import pysnooper
 
 
-@pysnooper.snoop(depth=2)
+@pysnooper.snoop(depth=2, color=False)
 def main():
     f2()
 
@@ -14,7 +14,7 @@ def f3():
     f4()
 
 
-@pysnooper.snoop(depth=2)
+@pysnooper.snoop(depth=2, color=False)
 def f4():
     f5()
 
@@ -24,10 +24,12 @@ def f5():
 
 
 expected_output = '''
+Source path:... Whatever
 21:10:42.298924 call         5 def main():
 21:10:42.299158 line         6     f2()
     21:10:42.299205 call         9 def f2():
     21:10:42.299246 line        10     f3()
+        Source path:... Whatever
         21:10:42.299305 call        18 def f4():
         21:10:42.299348 line        19     f5()
             21:10:42.299386 call        22 def f5():
@@ -36,8 +38,10 @@ expected_output = '''
             Return value:.. None
         21:10:42.299509 return      19     f5()
         Return value:.. None
+        Elapsed time: 00:00:00.000134
     21:10:42.299577 return      10     f3()
     Return value:.. None
 21:10:42.299627 return       6     f2()
 Return value:.. None
+Elapsed time: 00:00:00.000885
 '''

tests/samples/recursion.py

@@ -1,7 +1,7 @@
 import pysnooper
 
 
-@pysnooper.snoop(depth=2)
+@pysnooper.snoop(depth=2, color=False)
 def factorial(x):
     if x <= 1:
         return 1
@@ -14,48 +14,53 @@ def mul(a, b):
 
 def main():
     factorial(4)
-    
+
 expected_output = '''
+Source path:... Whatever
 Starting var:.. x = 4
-20:28:17.875295 call         5 def factorial(x):
-20:28:17.875509 line         6     if x <= 1:
-20:28:17.875550 line         8     return mul(x, factorial(x - 1))
+09:31:32.691599 call         5 def factorial(x):
+09:31:32.691722 line         6     if x <= 1:
+09:31:32.691746 line         8     return mul(x, factorial(x - 1))
     Starting var:.. x = 3
-    20:28:17.875624 call         5 def factorial(x):
-    20:28:17.875668 line         6     if x <= 1:
-    20:28:17.875703 line         8     return mul(x, factorial(x - 1))
+    09:31:32.691781 call         5 def factorial(x):
+    09:31:32.691806 line         6     if x <= 1:
+    09:31:32.691823 line         8     return mul(x, factorial(x - 1))
         Starting var:.. x = 2
-        20:28:17.875771 call         5 def factorial(x):
-        20:28:17.875813 line         6     if x <= 1:
-        20:28:17.875849 line         8     return mul(x, factorial(x - 1))
+        09:31:32.691852 call         5 def factorial(x):
+        09:31:32.691875 line         6     if x <= 1:
+        09:31:32.691892 line         8     return mul(x, factorial(x - 1))
             Starting var:.. x = 1
-            20:28:17.875913 call         5 def factorial(x):
-            20:28:17.875953 line         6     if x <= 1:
-            20:28:17.875987 line         7         return 1
-            20:28:17.876021 return       7         return 1
+            09:31:32.691918 call         5 def factorial(x):
+            09:31:32.691941 line         6     if x <= 1:
+            09:31:32.691961 line         7         return 1
+            09:31:32.691978 return       7         return 1
             Return value:.. 1
+            Elapsed time: 00:00:00.000092
             Starting var:.. a = 2
             Starting var:.. b = 1
-            20:28:17.876111 call        11 def mul(a, b):
-            20:28:17.876151 line        12     return a * b
-            20:28:17.876190 return      12     return a * b
+            09:31:32.692025 call        11 def mul(a, b):
+            09:31:32.692055 line        12     return a * b
+            09:31:32.692075 return      12     return a * b
             Return value:.. 2
-        20:28:17.876235 return       8     return mul(x, factorial(x - 1))
+        09:31:32.692102 return       8     return mul(x, factorial(x - 1))
         Return value:.. 2
+        Elapsed time: 00:00:00.000283
         Starting var:.. a = 3
         Starting var:.. b = 2
-        20:28:17.876320 call        11 def mul(a, b):
-        20:28:17.876359 line        12     return a * b
-        20:28:17.876397 return      12     return a * b
+        09:31:32.692147 call        11 def mul(a, b):
+        09:31:32.692174 line        12     return a * b
+        09:31:32.692193 return      12     return a * b
         Return value:.. 6
-    20:28:17.876442 return       8     return mul(x, factorial(x - 1))
+    09:31:32.692216 return       8     return mul(x, factorial(x - 1))
     Return value:.. 6
+    Elapsed time: 00:00:00.000468
     Starting var:.. a = 4
     Starting var:.. b = 6
-    20:28:17.876525 call        11 def mul(a, b):
-    20:28:17.876563 line        12     return a * b
-    20:28:17.876601 return      12     return a * b
+    09:31:32.692259 call        11 def mul(a, b):
+    09:31:32.692285 line        12     return a * b
+    09:31:32.692304 return      12     return a * b
     Return value:.. 24
-20:28:17.876646 return       8     return mul(x, factorial(x - 1))
+09:31:32.692326 return       8     return mul(x, factorial(x - 1))
 Return value:.. 24
+Elapsed time: 00:00:00.000760
 '''

tests/test_chinese.py

@@ -9,7 +9,6 @@ import types
 import sys
 
 from pysnooper.utils import truncate
-from python_toolbox import sys_tools, temp_file_tools
 import pytest
 
 import pysnooper
@@ -17,14 +16,17 @@ from pysnooper import pycompat
 from pysnooper.variables import needs_parentheses
 from .utils import (assert_output, assert_sample_output, VariableEntry,
                     CallEntry, LineEntry, ReturnEntry, OpcodeEntry,
-                    ReturnValueEntry, ExceptionEntry)
+                    ReturnValueEntry, ExceptionEntry, ExceptionValueEntry,
+                    SourcePathEntry, CallEndedByExceptionEntry,
+                    ElapsedTimeEntry)
+from . import mini_toolbox
 
 
 
 def test_chinese():
-    with temp_file_tools.create_temp_folder(prefix='pysnooper') as folder:
+    with mini_toolbox.create_temp_folder(prefix='pysnooper') as folder:
         path = folder / 'foo.log'
-        @pysnooper.snoop(path)
+        @pysnooper.snoop(path, color=False)
         def foo():
             a = 1
             x = '失败'
@@ -36,6 +38,7 @@ def test_chinese():
         assert_output(
             output,
             (
+                SourcePathEntry(),
                 CallEntry(),
                 LineEntry(),
                 VariableEntry('a'),
@@ -43,6 +46,7 @@ def test_chinese():
                 VariableEntry(u'x', (u"'失败'" if pycompat.PY3 else None)),
                 LineEntry(),
                 ReturnEntry(),
-                ReturnValueEntry('7')
+                ReturnValueEntry('7'),
+                ElapsedTimeEntry(),
             ),
         )

tests/test_mini_toolbox.py

@@ -0,0 +1,12 @@
+# Copyright 2019 Ram Rachum and collaborators.
+# This program is distributed under the MIT license.
+
+import pytest
+
+from . import mini_toolbox
+
+
+def test_output_capturer_doesnt_swallow_exceptions():
+    with pytest.raises(ZeroDivisionError):
+        with mini_toolbox.OutputCapturer():
+            1 / 0

tests/test_multiple_files/multiple_files/bar.py

@@ -0,0 +1,6 @@
+# Copyright 2019 Ram Rachum and collaborators.
+# This program is distributed under the MIT license.
+
+def bar_function(y):
+    x = 7 * y
+    return x

tests/test_multiple_files/multiple_files/foo.py

@@ -0,0 +1,11 @@
+# Copyright 2019 Ram Rachum and collaborators.
+# This program is distributed under the MIT license.
+
+import pysnooper
+
+from .bar import bar_function
+
+@pysnooper.snoop(depth=2, color=False)
+def foo_function():
+    z = bar_function(3)
+    return z

tests/test_multiple_files/test_multiple_files.py

@@ -0,0 +1,54 @@
+# Copyright 2019 Ram Rachum and collaborators.
+# This program is distributed under the MIT license.
+
+import io
+import textwrap
+import threading
+import types
+import os
+import sys
+
+from pysnooper.utils import truncate
+import pytest
+
+import pysnooper
+from pysnooper.variables import needs_parentheses
+from ..utils import (assert_output, assert_sample_output, VariableEntry,
+                    CallEntry, LineEntry, ReturnEntry, OpcodeEntry,
+                    ReturnValueEntry, ExceptionEntry, ExceptionValueEntry,
+                    SourcePathEntry, CallEndedByExceptionEntry,
+                    ElapsedTimeEntry)
+from .. import mini_toolbox
+from .multiple_files import foo
+
+
+def test_multiple_files():
+    with mini_toolbox.OutputCapturer(stdout=False,
+                                     stderr=True) as output_capturer:
+        result = foo.foo_function()
+    assert result == 21
+    output = output_capturer.string_io.getvalue()
+    assert_output(
+        output,
+        (
+            SourcePathEntry(source_path_regex=r'.*foo\.py$'),
+            CallEntry(),
+            LineEntry(),
+            SourcePathEntry(source_path_regex=r'.*bar\.py$'),
+            VariableEntry(),
+            CallEntry(),
+            LineEntry(),
+            VariableEntry(),
+            LineEntry(),
+            ReturnEntry(),
+            ReturnValueEntry(),
+            SourcePathEntry(source_path_regex=r'.*foo\.py$'),
+            VariableEntry(),
+            LineEntry(),
+            ReturnEntry(),
+            ReturnValueEntry(),
+            ElapsedTimeEntry(),
+        )
+    )
+
+

tests/test_not_implemented.py

@@ -0,0 +1,61 @@
+# Copyright 2019 Ram Rachum and collaborators.
+# This program is distributed under the MIT license.
+
+import io
+import textwrap
+import threading
+import collections
+import types
+import os
+import sys
+
+from pysnooper.utils import truncate
+import pytest
+
+import pysnooper
+from pysnooper.variables import needs_parentheses
+from pysnooper import pycompat
+from .utils import (assert_output, assert_sample_output, VariableEntry,
+                    CallEntry, LineEntry, ReturnEntry, OpcodeEntry,
+                    ReturnValueEntry, ExceptionEntry, ExceptionValueEntry,
+                    SourcePathEntry, CallEndedByExceptionEntry,
+                    ElapsedTimeEntry)
+from . import mini_toolbox
+
+
+def test_rejecting_coroutine_functions():
+    if sys.version_info[:2] <= (3, 4):
+        pytest.skip()
+
+    code = textwrap.dedent('''
+    async def foo(x):
+        return 'lol'
+    ''')
+    namespace = {}
+    exec(code, namespace)
+    foo = namespace['foo']
+
+    assert pycompat.iscoroutinefunction(foo)
+    assert not pycompat.isasyncgenfunction(foo)
+    with pytest.raises(NotImplementedError):
+        pysnooper.snoop(color=False)(foo)
+
+
+def test_rejecting_async_generator_functions():
+    if sys.version_info[:2] <= (3, 6):
+        pytest.skip()
+
+    code = textwrap.dedent('''
+    async def foo(x):
+        yield 'lol'
+    ''')
+    namespace = {}
+    exec(code, namespace)
+    foo = namespace['foo']
+
+    assert not pycompat.iscoroutinefunction(foo)
+    assert pycompat.isasyncgenfunction(foo)
+    with pytest.raises(NotImplementedError):
+        pysnooper.snoop(color=False)(foo)
+
+

tests/test_utils/test_ensure_tuple.py

@@ -0,0 +1,19 @@
+# Copyright 2019 Ram Rachum and collaborators.
+# This program is distributed under the MIT license.
+
+import pysnooper
+from pysnooper.utils import ensure_tuple
+
+def test_ensure_tuple():
+    x1 = ('foo', ('foo',), ['foo'], {'foo'})
+    assert set(map(ensure_tuple, x1)) == {('foo',)}
+
+    x2 = (pysnooper.Keys('foo'), (pysnooper.Keys('foo'),),
+          [pysnooper.Keys('foo')], {pysnooper.Keys('foo')})
+
+    assert set(map(ensure_tuple, x2)) == {(pysnooper.Keys('foo'),)}
+
+
+
+
+

tests/test_utils/test_regex.py

@@ -0,0 +1,72 @@
+# Copyright 2022 Ram Rachum and collaborators.
+# This program is distributed under the MIT license.
+
+import pysnooper
+from pysnooper.tracer import ansible_filename_pattern
+
+def test_ansible_filename_pattern():
+    archive_file = '/tmp/ansible_my_module_payload_xyz1234/ansible_my_module_payload.zip'
+    source_code_file = 'ansible/modules/my_module.py'
+    file_name = '%s/%s' % (archive_file, source_code_file)
+    assert ansible_filename_pattern.match(file_name).group(1) == archive_file
+    assert ansible_filename_pattern.match(file_name).group(2) == source_code_file
+
+    archive_file = '/tmp/ansible_my_module_payload_xyz1234/ansible_my_module_with.zip_name.zip'
+    source_code_file = 'ansible/modules/my_module.py'
+    file_name = '%s/%s' % (archive_file, source_code_file)
+    assert ansible_filename_pattern.match(file_name).group(1) == archive_file
+    assert ansible_filename_pattern.match(file_name).group(2) == source_code_file
+    
+    archive_file = '/my/new/path/payload.zip'
+    source_code_file = 'ansible/modules/my_module.py'
+    file_name = '%s/%s' % (archive_file, source_code_file)
+    assert ansible_filename_pattern.match(file_name).group(1) == archive_file
+    assert ansible_filename_pattern.match(file_name).group(2) == source_code_file
+
+    archive_file = '/tmp/ansible_my_module_payload_xyz1234/ansible_my_module_payload.zip'
+    source_code_file = 'ansible/modules/in/new/path/my_module.py'
+    file_name = '%s/%s' % (archive_file, source_code_file)
+    assert ansible_filename_pattern.match(file_name).group(1) == archive_file
+    assert ansible_filename_pattern.match(file_name).group(2) == source_code_file
+    
+    archive_file = '/tmp/ansible_my_module_payload_xyz1234/ansible_my_module_payload.zip'
+    source_code_file = 'ansible/modules/my_module_is_called_.py.py'
+    file_name = '%s/%s' % (archive_file, source_code_file)
+    assert ansible_filename_pattern.match(file_name).group(1) == archive_file
+    assert ansible_filename_pattern.match(file_name).group(2) == source_code_file
+
+    archive_file = 'C:\\Users\\vagrant\\AppData\\Local\\Temp\\pysnooperw5c2lg35\\valid.zip'
+    source_code_file = 'ansible\\modules\\my_valid_zip_module.py'
+    file_name = '%s\\%s' % (archive_file, source_code_file)
+    assert ansible_filename_pattern.match(file_name).group(1) == archive_file
+    assert ansible_filename_pattern.match(file_name).group(2) == source_code_file
+
+    archive_file = '/tmp/ansible_my_module_payload_xyz1234/ansible_my_module_payload.zip'
+    source_code_file = 'ANSIBLE/modules/my_module.py'
+    file_name = '%s/%s' % (archive_file, source_code_file)
+    assert ansible_filename_pattern.match(file_name) is None
+
+    archive_file = '/tmp/ansible_my_module_payload_xyz1234/ansible_my_module_payload.zip'
+    source_code_file = 'ansible/modules/my_module.PY'
+    file_name = '%s/%s' % (archive_file, source_code_file)
+    assert ansible_filename_pattern.match(file_name) is None
+
+    archive_file = '/tmp/ansible_my_module_payload_xyz1234/ansible_my_module_payload.Zip'
+    source_code_file = 'ansible/modules/my_module.py'
+    file_name = '%s/%s' % (archive_file, source_code_file)
+    assert ansible_filename_pattern.match(file_name) is None
+
+    archive_file = '/tmp/ansible_my_module_payload_xyz1234/ansible_my_module_payload.zip'
+    source_code_file = 'ansible/my_module.py'
+    file_name = '%s/%s' % (archive_file, source_code_file)
+    assert ansible_filename_pattern.match(file_name) is None
+
+    archive_file = '/tmp/ansible_my_module_payload_xyz1234/ansible_my_module_payload.zip'
+    source_code_file = ''
+    file_name = '%s/%s' % (archive_file, source_code_file)
+    assert ansible_filename_pattern.match(file_name) is None
+
+    archive_file = ''
+    source_code_file = 'ansible/modules/my_module.py'
+    file_name = '%s/%s' % (archive_file, source_code_file)
+    assert ansible_filename_pattern.match(file_name) is None

tests/utils.py

@@ -1,16 +1,19 @@
 # Copyright 2019 Ram Rachum and collaborators.
 # This program is distributed under the MIT license.
-
+import os
 import re
 import abc
 import inspect
+import sys
+
+from pysnooper.utils import DEFAULT_REPR_RE
 
 try:
     from itertools import zip_longest
 except ImportError:
     from itertools import izip_longest as zip_longest
 
-from python_toolbox import caching, sys_tools
+from . import mini_toolbox
 
 import pysnooper.pycompat
 
@@ -28,13 +31,24 @@ def get_function_arguments(function, exclude=()):
 
 
 class _BaseEntry(pysnooper.pycompat.ABC):
-    def __init__(self, prefix=''):
+    def __init__(self, prefix='', min_python_version=None, max_python_version=None):
         self.prefix = prefix
+        self.min_python_version = min_python_version
+        self.max_python_version = max_python_version
 
     @abc.abstractmethod
     def check(self, s):
         pass
 
+    def is_compatible_with_current_python_version(self):
+        compatible = True
+        if self.min_python_version and self.min_python_version > sys.version_info:
+            compatible = False
+        if self.max_python_version and self.max_python_version < sys.version_info:
+            compatible = False
+
+        return compatible
+
     def __repr__(self):
         init_arguments = get_function_arguments(self.__init__,
                                                 exclude=('self',))
@@ -51,8 +65,11 @@ class _BaseEntry(pysnooper.pycompat.ABC):
 
 
 class _BaseValueEntry(_BaseEntry):
-    def __init__(self, prefix=''):
-        _BaseEntry.__init__(self, prefix=prefix)
+    def __init__(self, prefix='', min_python_version=None,
+                 max_python_version=None):
+        _BaseEntry.__init__(self, prefix=prefix,
+                            min_python_version=min_python_version,
+                            max_python_version=max_python_version)
         self.line_pattern = re.compile(
             r"""^%s(?P<indent>(?: {4})*)(?P<preamble>[^:]*):"""
             r"""\.{2,7} (?P<content>.*)$""" % (re.escape(self.prefix),)
@@ -75,10 +92,53 @@ class _BaseValueEntry(_BaseEntry):
                                                   self._check_content(content))
 
 
+class ElapsedTimeEntry(_BaseEntry):
+    def __init__(self, elapsed_time_value=None, tolerance=0.2, prefix='',
+                 min_python_version=None, max_python_version=None):
+        _BaseEntry.__init__(self, prefix=prefix,
+                            min_python_version=min_python_version,
+                            max_python_version=max_python_version)
+        self.line_pattern = re.compile(
+            r"""^%s(?P<indent>(?: {4})*)Elapsed time: (?P<time>.*)""" % (
+                re.escape(self.prefix),
+            )
+        )
+        self.elapsed_time_value = elapsed_time_value
+        self.tolerance = tolerance
+
+    def check(self, s):
+        match = self.line_pattern.match(s)
+        if not match:
+            return False
+        timedelta = pysnooper.pycompat.timedelta_parse(match.group('time'))
+        if self.elapsed_time_value:
+            return abs(timedelta.total_seconds() - self.elapsed_time_value) \
+                                                              <= self.tolerance
+        else:
+            return True
+
+
+
+class CallEndedByExceptionEntry(_BaseEntry):
+    # Todo: Looking at this class, we could rework the hierarchy.
+    def __init__(self, prefix=''):
+        _BaseEntry.__init__(self, prefix=prefix)
+
+    def check(self, s):
+        return re.match(
+            r'''(?P<indent>(?: {4})*)Call ended by exception''',
+            s
+        )
+
+
+
 class VariableEntry(_BaseValueEntry):
     def __init__(self, name=None, value=None, stage=None, prefix='',
-                 name_regex=None, value_regex=None):
-        _BaseValueEntry.__init__(self, prefix=prefix)
+                 name_regex=None, value_regex=None, min_python_version=None,
+                 max_python_version=None):
+        _BaseValueEntry.__init__(self, prefix=prefix,
+                                 min_python_version=min_python_version,
+                                 max_python_version=max_python_version)
         if name is not None:
             assert name_regex is None
         if value is not None:
@@ -139,9 +199,12 @@ class VariableEntry(_BaseValueEntry):
             return stage == self.stage
 
 
-class ReturnValueEntry(_BaseValueEntry):
-    def __init__(self, value=None, value_regex=None, prefix=''):
-        _BaseValueEntry.__init__(self, prefix=prefix)
+class _BaseSimpleValueEntry(_BaseValueEntry):
+    def __init__(self, value=None, value_regex=None, prefix='',
+                 min_python_version=None, max_python_version=None):
+        _BaseValueEntry.__init__(self, prefix=prefix,
+                                 min_python_version=min_python_version,
+                                 max_python_version=max_python_version)
         if value is not None:
             assert value_regex is None
 
@@ -149,10 +212,6 @@ class ReturnValueEntry(_BaseValueEntry):
         self.value_regex = (None if value_regex is None else
                             re.compile(value_regex))
 
-    _preamble_pattern = re.compile(
-        r"""^Return value$"""
-    )
-
     def _check_preamble(self, preamble):
         return bool(self._preamble_pattern.match(preamble))
 
@@ -167,17 +226,55 @@ class ReturnValueEntry(_BaseValueEntry):
         else:
             return True
 
+class ReturnValueEntry(_BaseSimpleValueEntry):
+    _preamble_pattern = re.compile(
+        r"""^Return value$"""
+    )
+
+class ExceptionValueEntry(_BaseSimpleValueEntry):
+    _preamble_pattern = re.compile(
+        r"""^Exception$"""
+    )
+
+class SourcePathEntry(_BaseValueEntry):
+    def __init__(self, source_path=None, source_path_regex=None, prefix=''):
+        _BaseValueEntry.__init__(self, prefix=prefix)
+        if source_path is not None:
+            assert source_path_regex is None
+
+        self.source_path = source_path
+        self.source_path_regex = (None if source_path_regex is None else
+                            re.compile(source_path_regex))
+
+    _preamble_pattern = re.compile(
+        r"""^Source path$"""
+    )
+
+    def _check_preamble(self, preamble):
+        return bool(self._preamble_pattern.match(preamble))
+
+    def _check_content(self, source_path):
+        if self.source_path is not None:
+            return source_path == self.source_path
+        elif self.source_path_regex is not None:
+            return self.source_path_regex.match(source_path)
+        else:
+            return True
+
 
 class _BaseEventEntry(_BaseEntry):
     def __init__(self, source=None, source_regex=None, thread_info=None,
-                 thread_info_regex=None, prefix=''):
-        _BaseEntry.__init__(self, prefix=prefix)
+                 thread_info_regex=None, prefix='', min_python_version=None,
+                 max_python_version=None):
+        _BaseEntry.__init__(self, prefix=prefix,
+                            min_python_version=min_python_version,
+                            max_python_version=max_python_version)
         if type(self) is _BaseEventEntry:
             raise TypeError
         if source is not None:
             assert source_regex is None
         self.line_pattern = re.compile(
-            r"""^%s(?P<indent>(?: {4})*)[0-9:.]{15} """
+            r"""^%s(?P<indent>(?: {4})*)(?:(?:[0-9:.]{15})|(?: {15})) """
             r"""(?P<thread_info>[0-9]+-[0-9A-Za-z_-]+[ ]+)?"""
             r"""(?P<event_name>[a-z_]*) +(?P<line_number>[0-9]*) """
             r"""+(?P<source>.*)$""" % (re.escape(self.prefix,))
@@ -190,7 +287,7 @@ class _BaseEventEntry(_BaseEntry):
         self.thread_info_regex = (None if thread_info_regex is None else
                              re.compile(thread_info_regex))
 
-    @caching.CachedProperty
+    @property
     def event_name(self):
         return re.match('^[A-Z][a-z_]*', type(self).__name__).group(0).lower()
 
@@ -244,24 +341,57 @@ class OutputFailure(Exception):
     pass
 
 
-def assert_output(output, expected_entries, prefix=None):
+def verify_normalize(lines, prefix):
+    time_re = re.compile(r"[0-9:.]{15}")
+    src_re = re.compile(r'^(?: *)Source path:\.\.\. (.*)$')
+    for line in lines:
+        if DEFAULT_REPR_RE.search(line):
+            msg = "normalize is active, memory address should not appear"
+            raise OutputFailure(line, msg)
+        no_prefix = line.replace(prefix if prefix else '', '').strip()
+        if time_re.match(no_prefix):
+            msg = "normalize is active, time should not appear"
+            raise OutputFailure(line, msg)
+        m = src_re.match(line)
+        if m:
+            if not os.path.basename(m.group(1)) == m.group(1):
+                msg = "normalize is active, path should be only basename"
+                raise OutputFailure(line, msg)
+
+
+def assert_output(output, expected_entries, prefix=None, normalize=False):
     lines = tuple(filter(None, output.split('\n')))
+    if expected_entries and not lines:
+        raise OutputFailure("Output is empty")
 
     if prefix is not None:
         for line in lines:
             if not line.startswith(prefix):
                 raise OutputFailure(line)
 
+    if normalize:
+        verify_normalize(lines, prefix)
+
+    # Filter only entries compatible with the current Python
+    filtered_expected_entries = []
+    for expected_entry in expected_entries:
+        if isinstance(expected_entry, _BaseEntry):
+            if expected_entry.is_compatible_with_current_python_version():
+                filtered_expected_entries.append(expected_entry)
+        else:
+            filtered_expected_entries.append(expected_entry)
+
+    expected_entries_count = len(filtered_expected_entries)
     any_mismatch = False
     result = ''
     template = u'\n{line!s:%s}   {expected_entry}  {arrow}' % max(map(len, lines))
-    for expected_entry, line in zip_longest(expected_entries, lines, fillvalue=""):
+    for expected_entry, line in zip_longest(filtered_expected_entries, lines, fillvalue=""):
         mismatch = not (expected_entry and expected_entry.check(line))
         any_mismatch |= mismatch
         arrow = '<===' * mismatch
         result += template.format(**locals())
 
-    if len(lines) != len(expected_entries):
+    if len(lines) != expected_entries_count:
         result += '\nOutput has {} lines, while we expect {} lines.'.format(
                 len(lines), len(expected_entries))
 
@@ -270,15 +400,23 @@ def assert_output(output, expected_entries, prefix=None):
 
 
 def assert_sample_output(module):
-    with sys_tools.OutputCapturer(stdout=False,
-                                  stderr=True) as output_capturer:
+    with mini_toolbox.OutputCapturer(stdout=False,
+                                     stderr=True) as output_capturer:
         module.main()
 
-    time = '21:10:42.298924'
-    time_pattern = re.sub(r'\d', r'\\d', time)
+    placeholder_time = '00:00:00.000000'
+    time_pattern = '[0-9:.]{15}'
 
     def normalise(out):
-        return re.sub(time_pattern, time, out).strip()
+        out = re.sub(time_pattern, placeholder_time, out).strip()
+        out = re.sub(
+            r'^( *)Source path:\.\.\. .*$',
+            r'\1Source path:... Whatever',
+            out,
+            flags=re.MULTILINE
+        )
+        return out
+
 
     output = output_capturer.string_io.getvalue()
 
@@ -290,3 +428,5 @@ def assert_sample_output(module):
     except AssertionError:
         print('\n\nActual Output:\n\n' + output)  # to copy paste into expected_output
         raise  # show pytest diff (may need -vv flag to see in full)
+
+

tox.ini

@@ -6,7 +6,7 @@ envlist =
     flake8
     pylint
     bandit
-    py{27,34,35,36,37,38,py,py3}
+    py{27,34,35,36,37,38,39,310,py,py3}
     readme
     requirements
     clean
@@ -15,11 +15,8 @@ envlist =
 description = Unit tests
 deps =
     pytest
-    python_toolbox
-commands = pytest
-setenv =
-    # until python_toolbox is fixed
-    PYTHONWARNINGS = ignore::DeprecationWarning
+    py34: typing
+commands = pytest {posargs}
 
 [testenv:bandit]
 description = PyCQA security linter
@@ -62,4 +59,4 @@ targets = .
 exclude = .tox,build,dist,pysnooper.egg-info
 
 [pytest]
-addopts = --strict
+addopts = --strict-markers