Debugging and profiling decorator for functions and classes that logs caller name(s), args+values, execution time, and more. Eliminates reams of boilerplate code.
log_calls is a Python 3.3+ decorator that can print a lot of useful information about calls to decorated functions, methods and properties. The decorator can write to stdout, to another stream or file, or to a logger. log_calls provides methods for writing your own debug messages, and for easily “dumping” variables and expressions paired with their values. It can decorate individual functions, methods and properties; but it can also programmatically decorate callable members of entire classes and class hierarchies, even of entire modules, with just a single line — which can greatly expedite learning a new codebase.
In short, log_calls can save you from writing, rewriting, copying, pasting and tweaking a lot of ad hoc, debug-only, boilerplate code — and it can keep your codebase free of that clutter.
For each call to a decorated function or method, log_calls can show you:
- the caller (in fact, the complete call chain back to another log_calls-decorated caller so there are no gaps in chains displayed)
- the arguments passed to the function or method, and any default values used
- nesting of calls, using indentation
- the number of the call (whether it’s the 1st call, the 2nd, the 103rd, …)
- the return value
- the time it took to execute
- and more!
These and other features are optional and configurable settings, which can be specified for each decorated callable via keyword parameters, as well as en masse for a group of callables all sharing the same settings. You can examine and change these settings on the fly using attributes with the same names as the keywords, or using a dict-like interface whose keys are the keywords.
log_calls can also collect profiling data and statistics, accessible at runtime, such as:
- the number of calls to a function
- total time taken by the function
- the function’s entire call history (arguments, time elapsed, return values, callers, and more), available as text in CSV format and, if Pandas is installed, as a DataFrame.
The package contains two other decorators:
- record_history, a stripped-down version of log_calls, only collects call history and statistics, and outputs no messages;
- used_unused_keywords lets a function or method easily determine, per-call, which of its keyword parameters were actually supplied by the caller, and which received their default values.
NOTE: This package requires the CPython implementation, as it makes assumptions about stack frame internals which may not be valid in other interpreters.
See the documentation online at http://www.pythonhosted.org/log_calls/, or in the log_calls/docs/ directory, for usage, details, examples and tips und tricks.