API¶

def dump_exception(exc: Exception, filename: str = DEFAULT_DUMP_NAME,
                   start_from: str = None) -> None:
    """Dump exception object and corresponding crash information into a file.

    Arguments:
        exc: Exception object with traceback.
        filename: Target file name or path.
        start_from: Name of the source file to be considered as topmost.
    """

    report = report_header()
    report['exceptions'] = exception_stack_info(exc)
    if start_from:
        last_exc = report['exceptions'][-1]
        while last_exc:
            if last_exc[0]._filename == start_from:
                break
            del last_exc[0]

    with open(filename, 'wb') as f:
        pickler.dump(report, f)

def set_excepthook(filename: str = DEFAULT_DUMP_NAME, replace: bool = True,
                   silent: bool = False) -> None:
    """Install tbdump as an exception handler.

    Arguments:
        filename: File name or path to the dump file.
        replace: Set `False` to call original exception handler after tbdump.
        silent: Set `True` to suppress messages.
    """

    old_excepthook = sys.excepthook

    if silent:
        say = lambda text: None
    else:
        say = lambda text: print(text, file=sys.stderr)

    def tbdump_except_hook(exctype, exc, traceback):
        say(exctype.__name__ + ': ' + str(exc))
        try:
            dump_exception(exc, filename)
            say('Traceback dumped into: ' + filename)
        except Exception:
            if config.debug:
                raise
            say('Failed to dump traceback')

        if not replace:
            old_excepthook(exctype, exc, traceback)

    sys.excepthook = tbdump_except_hook

def load(filename: str = DEFAULT_DUMP_NAME) -> dict:
    """Load crash information from a dump file.

    Arguments:
        filename: File name or path to be loded.

    Returns:
        Crash information.
    """
    with DummyModuleFactory():
        with open(filename, 'rb') as f:
            return pickler.load(f)