Metadata-Version: 1.0
Name: faulthandler
Version: 1.3
Summary: Display the Python backtrace on a crash
Home-page: https://github.com/haypo/faulthandler/wiki/
Author: Victor Stinner
Author-email: victor.stinner@haypocalc.com
License: BSD (2-clause)
Description: +++++++++++++
        Fault handler
        +++++++++++++
        
        Fault handler for SIGSEGV, SIGFPE, SIGBUS and SIGILL signals: display the
        Python backtrace and restore the previous handler. Allocate an alternate stack
        for this handler, if sigaltstack() is available, to be able to allocate memory
        on the stack, even on stack overflow.
        
        Import the module and call faulthandler.enable() to enable the fault handler.
        
        The fault handler is called on catastrophic cases and so it can only use
        signal-safe functions (eg. it doesn't allocate memory on the heap). That's why
        the backtrace is limited: it only supports ASCII encoding (use the
        backslashreplace error handler for non-ASCII characters) and it doesn't print
        the source code in the backtrace (only the filename, the function name and the
        line number).
        
        The Python backtrace is written to the standard error stream. Start your
        graphical applications in a terminal and run your server in foreground to see
        the backtrace.
        
        Website: https://github.com/haypo/faulthandler/wiki/
        
        
        Example
        =======
        
        Example of a segmentation fault on Linux: ::
        
            $ python
            >>> import faulthandler
            >>> faulthandler.enable()
            >>> faulthandler.sigsegv()
            Fatal Python error: Segmentation fault
        
            Traceback (most recent call first):
              File "<stdin>", line 1 in <module>
            Segmentation fault
        
        
        Installation
        ============
        
        To install faulthandler module, type the following command: ::
        
            python setup.py install
        
        Then you can test your setup using the following command: ::
        
            python tests.py
        
        You need a C compiler (eg. gcc) and Python headers to build the faulthandler
        module. Eg. on Fedora, you have to install python-devel package (sudo yum
        install python-devel).
        
        
        faulthandler module API
        =======================
        
        Fault handler state (disabled by default):
        
         * enable(file=sys.stderr): enable the fault handler
         * disable(): disable the fault handler
         * isenabled(): get the status of the fault handler
        
        Dump the current backtrace:
        
         * dumpbacktrace(file=sys.stderr, all_threads=False): dump backtrace of the
           current thread, or of all threads if all_threads is True, into file
         * dumpbacktrace_later(delay, repeat=False, file=sys.stderr, all_threads=False):
           dump the backtrace of the current thread, or of all threads if all_threads
           is True, in delay seconds, or each delay seconds if repeat is True. If the
           function is called twice, the new call replaces previous parameters. Call
           cancel_dumpbacktrace_later() to call the next request.
         * cancel_dumpbacktrace_later(): cancel the previous call to
           dumpbacktrace_later()
        
        dumpbacktrace_later() is implemented using the SIGALRM signal and the alarm()
        function: if the signal handler is called during a system call, the system call
        is interrupted (return EINTR). It it not available on Windows.
        
        enable() and dumpbacktrace_later() keep an internal reference to the output
        file. Use disable() and cancel_dumpbacktrace_later() to clear this reference.
        
        Functions to test the fault handler:
        
         * sigbus(): raise a SIGBUS signal (Bus error)
         * sigfpe(): raise a SIGFPE signal (Floating point exception), do a division by
           zero
         * sigill(): raise a SIGILL signal (Illegal instruction)
         * sigsegv(): raise a SIGSEGV signal (Segmentation fault), read memory from
           NULL (address 0)
        
        sigbus() and sigill() are not available on all operation systems.
        
        The version can be read in the "version" attribute: use "version >> 8" to get
        the major version, and "version & 255" to get the minor version.
        
        
        Changelog
        =========
        
        Version 1.3 (2011-01-31)
        ------------------------
        
         * Don't compile dumpbacktrace_later() and cancel_dumpbacktrace_later() on
           Windows because alarm() is missing
        
        Version 1.2 (2011-01-31)
        ------------------------
        
         * Add dumpbacktrace_later() and cancel_dumpbacktrace_later() function
         * enable() and dumpbacktrace() get an optional file argument
         * Replace dumpbacktrace_threads() function by a new dumpbacktrace() argument:
           dumpbacktrace(all_threads=True)
         * enable() gets the file descriptor of sys.stderr instead of using the file
           descriptor 2
        
        Version 1.1 (2011-01-03)
        ------------------------
        
         * Disable the handler by default, because pkgutil may load the module and so
           enable the handler which is unexpected
         * Add dumpbacktrace() and dumpbacktrace_threads() functions
         * sigill() is available on Windows thanks to Martin's patch
         * Fix dump_ascii() for signed char type (eg. on FreeBSD)
         * Fix tests.py for Python 2.5
        
        Version 1.0 (2010-12-24)
        ------------------------
        
         * First public release
        
        
        Status
        ======
        
         * 2011-01-31: Version 1.2 tested with Python 2.5, 2.6, 2.7, 3.1 and 3.2 on
           Debian Sid
         * 2010-12-24: Tested with Python 2.6, 3.1 and 3.2 on Debian Sid
         * 2010-12-24: Tested with Python 2.6 and 3.1 on Windows XP
        
        
        Similar projects
        ================
        
        Python debuggers:
        
         * tipper: write the backtrace of the current thread into a file on SIGUSR1
           signal: http://pypi.python.org/pypi/tipper/
         * crier: write the backtrace of the current thread into a file
           (eg. /tmp/dump-<pid>) if a "request" file is created (eg. /tmp/crier-<pid>).
           Implemented using a thread. https://gist.github.com/737056
         * Python WAD (Wrapped Application Debugger), not update since 2001:
           http://www.dabeaz.com/papers/Python2001/python.html
        
        Application fault handlers:
        
         * The GNU libc has a fault handler in debug/segfault.c
         * XEmacs has a fault handler displaying the Lisp backtrace
         * RPy has a fault handler
        
        System-wide fault handlers:
        
         * Ubuntu uses Apport: https://wiki.ubuntu.com/Apport
         * The Linux kernel logs also segfaults into /var/log/kern.log (and
           /var/log/syslog). /proc/sys/kernel/core_pattern contols how coredumps are
           created.
         * Windows opens a popup on a fatal error asking if the error should be
           reported to Microsoft
        
        
        See also
        ========
        
         * http://bugs.python.org/issue8863 (may 2010):
           Display Python backtrace on SIGSEGV, SIGFPE and fatal error
         * http://bugs.python.org/issue3999 (sept. 2009):
           Real segmentation fault handler
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Classifier: Programming Language :: C
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
