Decorator for logging function arguments and return value by human-readable way
Project description
logwrap
logwrap is a helper for logging in human-readable format function arguments and call result on function call. Why? Because logging of *args, **kwargs become useless with project grow and you need more details in call log.
Cons:
Log records are not single line.
Pros:
Log records are not single 100500 symbols length line. (Especially actual for testing/development environments and for Kibana users).
Service free: job is done by this library and it’s dependencies. It works at virtualenv
Free software: Apache license
Open Source: https://github.com/penguinolog/logwrap
PyPI packaged: https://pypi.python.org/pypi/logwrap
Self-documented code: docstrings with types in comments
Tested: see bages on top
Support multiple Python versions:
Python 2.7 Python 3.4 Python 3.5 Python 3.6 PyPy PyPy3 3.5+
This package includes helpers:
logwrap - main helper. The same is LogWrap.
LogWrap - class with logwrap implementation. May be used directly.
pretty_repr
pretty_str
PrettyFormat
Usage
logwrap
The main decorator. Could be used as not argumented (@logwrap.logwrap) and argumented (@logwrap.logwrap()). Not argumented usage simple calls with default values for all positions. Argumented usage with arguments from signature:
@logwrap.logwrap(
log=logging.getLogger(__name__), # __name__ = 'logwrap'
log_level=logging.DEBUG,
exc_level=logging.ERROR,
max_indent=20, # forwarded to the pretty_repr
spec=None, # use target callable function for spec
blacklisted_names=None, # list argument names, which should be dropped from log
blacklisted_exceptions=None, # Exceptions to skip in log
log_call_args=True, # Log call arguments before call
log_call_args_on_exc=True, # Log call arguments if exception happens
log_result_obj=True, # Log result object
)
Usage examples:
@logwrap.logwrap()
def foo():
pass
is equal to:
@logwrap.logwrap
def foo():
pass
Get decorator for use without parameters:
get_logs = logwrap.logwrap() # set required parameters via arguments
type(get_logs) == LogWrap # All logic is implemented in LogWrap class starting from version 2.2.0
@get_logs
def foo():
pass
Call example:
import logwrap
@logwrap.logwrap
def example_function1(
arg1: str,
arg2: str='arg2',
*args,
kwarg1: str,
kwarg2: str='kwarg2',
**kwargs
) -> tuple():
return (arg1, arg2, args, kwarg1, kwarg2, kwargs)
example_function1('arg1', kwarg1='kwarg1', kwarg3='kwarg3')
This code during execution will produce log records:
Calling: 'example_function1'( # POSITIONAL_OR_KEYWORD: 'arg1'=u'''arg1''', 'arg2'=u'''arg2''', # VAR_POSITIONAL: 'args'=(), # KEYWORD_ONLY: 'kwarg1'=u'''kwarg1''', 'kwarg2'=u'''kwarg2''', # VAR_KEYWORD: 'kwargs'= dict({ 'kwarg3': u'''kwarg3''', }), ) Done: 'example_function1' with result: tuple(( u'''arg1''', u'''arg2''', (), u'''kwarg1''', u'''kwarg2''', dict({ 'kwarg3': u'''kwarg3''', }), ))
Limitations:
nested wrapping (@logwrap @deco2 …) is not parsed under python 2.7: functools.wraps limitation. Please set logwrap as the first level decorator.
LogWrap
Example construction and read from test:
log_call = logwrap.LogWrap()
log_call.log_level == logging.DEBUG
log_call.exc_level == logging.ERROR
log_call.max_indent == 20
log_call.blacklisted_names == []
log_call.blacklisted_exceptions == []
log_call.log_call_args == True
log_call.log_call_args_on_exc == True
log_call.log_result_obj == True
On object change, variable types is validated.
pretty_repr
This is specified helper for making human-readable repr on complex objects. Signature is self-documenting:
def pretty_repr(
src, # object for repr
indent=0, # start indent
no_indent_start=False, # do not indent the first level
max_indent=20, # maximum allowed indent level
indent_step=4, # step between indents
py2_str=False, # use bytes for python 2 __repr__ and __str__
)
Limitation: Dict like objects is always marked inside {} for readability, even if it is collections.OrderedDict (standard repr as list of tuples).
pretty_str
This is specified helper for making human-readable str on complex objects. Signature is self-documenting:
def pretty_str(
src, # object for __str__
indent=0, # start indent
no_indent_start=False, # do not indent the first level
max_indent=20, # maximum allowed indent level
indent_step=4, # step between indents
py2_str=False, # use bytes for python 2 __repr__ and __str__
)
- Limitations:
Dict like objects is always marked inside {} for readability, even if it is collections.OrderedDict (standard repr as list of tuples).
Iterable types is not declared, only brackets is used.
String and bytes looks the same (its __str__, not __repr__).
PrettyFormat
PrettyFormat is the main formatting implementation class. pretty_repr and pretty_str uses instances of subclasses PrettyRepr and PrettyStr from this class. This class is mostly exposed for typing reasons. Object signature:
def __init__(
self,
max_indent=20, # maximum allowed indent level
indent_step=4, # step between indents
py2_str=False, # use bytes for python 2 __repr__ and __str__
)
Callable object (PrettyFormat instance) signature:
def __call__(
self,
src, # object for repr
indent=0, # start indent
no_indent_start=False # do not indent the first level
)
Adopting your code
pretty_repr behavior could be overridden for your classes by implementing specific magic method:
def __pretty_repr__(
self,
parser # PrettyFormat class instance,
indent # start indent,
no_indent_start # do not indent the first level
):
return ...
This method will be executed instead of __repr__ on your object.
def __pretty_str__(
self,
parser # PrettyFormat class instance,
indent # start indent,
no_indent_start # do not indent the first level
):
return ...
This method will be executed instead of __str__ on your object.
Testing
The main test mechanism for the package logwrap is using tox. Test environments available:
pep8 py27 py34 py35 py36 pypy pypy3 pylint pep257 docs
CI systems
For code checking several CI systems is used in parallel:
Travis CI: is used for checking: PEP8, pylint, bandit, installation possibility and unit tests. Also it’s publishes coverage on coveralls.
coveralls: is used for coverage display.
CD system
Travis CI: is used for package delivery on PyPI.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for logwrap-3.1.0-cp36-cp36m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 539ab11bf1a659ce499ee0e8860318710e24042bbd0f122543b08d181f77f444 |
|
MD5 | 1c6f61b385effe0f505abacf716f6ca4 |
|
BLAKE2b-256 | e67aee0d34d8d76cbc2ba747dfc1ce30552e72fdaf5155019cc5f668f31b9fca |
Hashes for logwrap-3.1.0-cp36-cp36m-manylinux1_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e68aed58549a60c330e1d1c2448dc3860f3393561a072b001f8882fdabe70d42 |
|
MD5 | e9d7212e1a752ef92fa5de153a87d8f1 |
|
BLAKE2b-256 | 4ab2cd84b3e7bf89a33c9cfe46a040eb1d906da318b30bb68f25bccc63e34b5e |
Hashes for logwrap-3.1.0-cp35-cp35m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 54f30ca763ce852629e2507bba5914cef26ef081cc08964395ef740ae0f34ebd |
|
MD5 | db301c0d00f4dc222c14ab4db5c2ff83 |
|
BLAKE2b-256 | 7c1d9bcd1390b90440375d11465ed4b75dd0ea3810ae0d7bdbdb30b66a423708 |
Hashes for logwrap-3.1.0-cp35-cp35m-manylinux1_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ebde4340c9f8452fcb3a6661de4ffe1efa3303e124dbdad17c9cfc2d57943c1f |
|
MD5 | a9f1e33eb4a541bb8c2e5e54515d661d |
|
BLAKE2b-256 | b6f679af6df7132e4263800810e69f98f7494b9d6d18810c0ead089541a24d63 |
Hashes for logwrap-3.1.0-cp34-cp34m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2011aec2d9feac1a865213a980c577c5cf1f574e31c3a037342faf62edee733f |
|
MD5 | 25159cb91f84d7acdfb6b9419bdeaca9 |
|
BLAKE2b-256 | 5ff4ba80207bc49fee39cd00178c5dcca9649418e71bc0573a02822e176e6aa5 |
Hashes for logwrap-3.1.0-cp34-cp34m-manylinux1_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3deef19215f9b5baaefc181194d707054d46269c4f3c2417042f5e114c16ab91 |
|
MD5 | 4e060a6267a94a8b75ab30d76f5d8ea7 |
|
BLAKE2b-256 | 69ffebf6a34ed515974b675e822eb24e7f081b9d3fb84b3512e08340782a52a4 |