Metadata-Version: 1.1
Name: logex
Version: 2.0.0
Summary: Easily log uncaught exceptions in D-Bus, thread and other functions.
Home-page: https://github.com/insecure/logex
Author: Tobias Hommel
Author-email: software@genoetigt.de
License: BSD
Description: logex
        =====
        
        A python module to easily add logging for unhandled exceptions in D-Bus, thread
        and other functions.
        Although unhandled exceptions get written to STDERR by default and most modules
        provide some mechanism to log these, this is not always sufficient, e.g. when
        inside a daemon which discards all default output.
        Sometimes it may also be desirable to automatically send an email if some
        exception occurs or at least write some kind of audit log.
        
        It comes with a decorator function which can be applied on demand. It provides
        advanced debugging information which gives you the most relevant information
        for each frame in the exception's traceback.
        
        ========
        Settings
        ========
        
        A description of all available settings is available in the source
        documentation of the `log()` function in the `logex.py <logex.py>`_ module.
        
        All settings can be set "globally", e.g. by using:
        
        .. code:: python
        
            import logex
            logex.VIEW_SOURCE = True
        
        or they can be specified when decorating a function or method:
        
        .. code:: python
        
            import logex
            @logex.log(view_source=True)
            def f():
                pass
        
        Currently available module variables and their defaults:
        
        - ``LOGFUNCTION = logging.error``
        - ``TEMPLATE = ('Unhandled exception calling %(funcname)s(%(argsview)s):\n%(traceback)s\n%(sourceview)s')``
        - ``ADVANCED = False``
        - ``LAZY = False``
        - ``RERAISE = True``
        - ``CATCHALL = False``
        - ``VIEW_SOURCE = False``
        - ``DETECT_NESTED = True``
        
        The default behaviour of the log() decorator is to generate a log message using
        ``TEMPLATE`` and pass this to ``LOGFUNCTION``.
        For a list of place holders that are replaced, see the `generate_log_message()`
        function in `logex.py <logex.py>`_.
        
        Setting ``ADVANCED`` to True, gives you the opportunity to use a logging function
        which interprets the exception data itself. For a description of the arguments
        to an advanced logging function, see the `generate_log_message()` function in
        `logex.py <logex.py>`_.
        
        If ``LAZY`` is True, the logging function itself must return another function
        object which is then used as the actual logging function.
        
        ``RERAISE`` can be set to False to only log the exception and continue "normally".
        This will, of course, not resume the decorated function itself, but return to
        the caller of this function and resume execution there.
        
        If ``CATCHALL`` is True, all exceptions are caught, i.e. also KeyboardInterrupt,
        SystemExit and GeneratorExit.
        
        ``VIEW_SOURCE`` can be used to show the source code and local variables for every
        function in the exceptions traceback.
        
        logex will usually detect if an exception occurs in a logex-decorated function
        which, in turn, was called by a logex-decorated function and shorten the output
        so you do not get the same source view twice. ``DETECT_NESTED`` can be used to
        disable this feature and always print the full source view.
        
        =======
        Example
        =======
        Several examples can be found in the ``examples`` directory, so we show just some
        simple usage here:
        
        .. code:: python
        
            #!/usr/bin/python
            import logex
        
            @logex.log
            def my_function():
                raise Exception("something bad happens here")
        
            my_function()
        
        This will simply print the exception traceback, like this:
        
        .. code:: python
        
            ERROR:root:Unhandled exception calling my_function():
            Traceback (most recent call last):
              File "./x.py", line 10, in my_function
                do_something_dangerous()
              File "./x.py", line 5, in do_something_dangerous
                raise Exception("something bad happens here")
            Exception: something bad happens here
            
            
            Traceback (most recent call last):
              File "./x.py", line 13, in <module>
                my_function()
              File "/home/tobi/repos/logex/logex.py", line 318, in wrapper_f
                template, view_source, reraise, wrapper_code=wrapper_code)
              File "/home/tobi/repos/logex/logex.py", line 306, in wrapper_f
                wrapped_f(*args, **kwargs)
              File "./x.py", line 10, in my_function
                do_something_dangerous()
              File "./x.py", line 5, in do_something_dangerous
                raise Exception("something bad happens here")
            Exception: something bad happens here
        
        The second traceback is the one generated because an unhandled exception
        occurs(logex reraises exceptions by default), it also contains some extra
        frames generated by the logex decorator.
        Let's make it a bit more advanced and pleasant to read:
        
        .. code:: python
        
            #!/usr/bin/python
            import logex
        
            @logex.log(view_source=True, reraise=False)
            def my_function():
                x = 1
                raise Exception("something bad happens here")
        
            my_function()
        
        This yields:
        
        .. code:: python
        
            ERROR:root:Unhandled exception calling my_function():
            Traceback (most recent call last):
              File "./x.py", line 10, in my_function
                do_something_dangerous()
              File "./x.py", line 5, in do_something_dangerous
                raise Exception("something bad happens here")
            Exception: something bad happens here
            
            ========== sourcecode ==========
            -------------------------
            -- ./x.py: my_function --
            -------------------------
                7   @logex.log(view_source=True, reraise=False)
                8   def my_function():
                9           x = 1
               10-->        do_something_dangerous()
            ...
            
            Locals when executing line 10:
            * x: 1
            
            ------------------------------------
            -- ./x.py: do_something_dangerous --
            ------------------------------------
                4   def do_something_dangerous():
                5-->        raise Exception("something bad happens here")
            
            ================================
        
        We have several differences here:
        
        - the exception is not reraised, this is probably not always desired, but makes
          some nicer output here ;)
        - a view of the sourcecode for each function in the traceback
        - a list of the current values for local variables, if present
        
Keywords: debug log unhandled exception thread dbus D-Bus
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
