_dbg module

exception pyflyby._dbg.DebuggerAttachTimeoutError

class pyflyby._dbg.Pty

communicate()

pyflyby._dbg._DebuggerCtx(tty='/dev/tty')

A context manager that sets up the environment (stdio, sys hooks) for a debugger, initializes IPython if necessary, and creates a debugger instance.

Returns:: Context manager that yields a Pdb instance.

pyflyby._dbg._DisplayHookCtx(): Context manager that resets sys.displayhook to the default value upon entry, and restores the pre-context value upon exit.

pyflyby._dbg._ExceptHookCtx(): Context manager that restores sys.excepthook upon exit.

pyflyby._dbg._FdCtx(target_fd, src_fd)

exception pyflyby._dbg._NoTtyError

pyflyby._dbg._StdioCtx(tty='/dev/tty')

Within the context, force fd {0, 1, 2}, sys.__{stdin,stdout,stderr}__, sys.{stdin,stdout,stderr} to fd. This allows us to use the debugger even if stdio is otherwise redirected.

Parameters:: tty (int or str) – Tty to use. Either a file descriptor or a name of a tty.

pyflyby._dbg._abbrev_filename(filename)

pyflyby._dbg._debug_code(arg, globals=None, locals=None, auto_import=True, tty='/dev/tty')

Run code under the debugger.

pyflyby._dbg._debug_exception(*exc_info, **kwargs)

Debug an exception – print a stack trace and enter the debugger.

Suitable to be assigned to sys.excepthook.

pyflyby._dbg._dev_null()

Return a file object opened for reading/writing to /dev/null. Memoized.

Return type:: file

pyflyby._dbg._dev_tty_fd(): Return a file descriptor opened to /dev/tty. Memoized.

pyflyby._dbg._escape_for_gdb(string): Escape a string to make it safe for passing to gdb.

pyflyby._dbg._find_py_commandline()

pyflyby._dbg._get_caller_frame()

Get the closest frame from outside this module.

Return type:: FrameType

pyflyby._dbg._override_excepthook(hook)

Override sys.excepthook with hook but also support resetting.

Users should call this function instead of directly overiding sys.excepthook. This is helpful in resetting sys.excepthook in certain cases.

pyflyby._dbg._prompt_continue_waiting_for_debugger(): Prompt while exiting the debugger to get user opinion on keeping the process waiting for debugger to attach.

pyflyby._dbg._remote_print_stack_to_file(pid, filename)

pyflyby._dbg._reset_excepthook()

pyflyby._dbg._send_email_with_attach_instructions(arg, mailto, originalpid)

pyflyby._dbg._signal_handler_debugger(signal_number, interrupted_frame)

pyflyby._dbg._sigterm_handler(signum, frame)

pyflyby._dbg._sleep_until_debugger_attaches(arg, timeout=86400)

pyflyby._dbg.enable_sigterm_handler(on_existing_handler='raise')

Install a handler for SIGTERM that causes Python to print a stack trace before exiting.

Parameters:

on_existing_handler –

What to do when a SIGTERM handler was already registered.

If "raise", then keep the existing handler and raise an exception.
If "keep_existing", then silently keep the existing handler.
If "warn_and_override", then override the existing handler and log a warning.
If "silently_override", then silently override the existing handler.

pyflyby._dbg.get_executable(pid)

Get the full path for the target process.

Return type:: Filename

pyflyby._dbg.inject(pid, statements, wait=True, show_gdb_output=False)

Execute statements in a running Python process.

Parameters:

pid (int) – Id of target process
statements (Iterable of strings) – Python statements to execute.

Returns:

Then process ID of the gdb process if wait is False; None if wait is True.

pyflyby._dbg.kill_process(pid, kill_signals)

Kill process pid using various signals.

Parameters:: kill_signals – Sequence of (signal, delay) tuples. Each signal is tried in sequence, waiting up to delay seconds before trying the next signal.

pyflyby._dbg.process_exists(pid)

Return whether pid exists.

Return type:: bool

pyflyby._dbg.setraw_but_sigint(fd, when=2): Put terminal into a raw mode.

pyflyby._dbg.syscall_marker(msg): Execute a dummy syscall that is visible in truss/strace.

pyflyby._dbg.tty_is_usable()

Return whether /dev/tty is usable.

In interactive sessions, /dev/tty is usable; in non-interactive sessions, /dev/tty is not usable:

$ ssh -t localhost py -q pyflyby._dbg.tty_is_usable
True

$ ssh -T localhost py -q pyflyby._dbg.tty_is_usable
False

tty_is_usable() is useful for deciding whether we are in an interactive terminal. In an interactive terminal we can enter the debugger directly; in a non-interactive terminal, we need to wait_for_debugger_to_attach.

Note that this is different from doing e.g. isatty(0). isatty would return False if a program was piped, even though /dev/tty is usable.

pyflyby._dbg.wait_for_debugger_to_attach(arg, mailto=None, background=False, timeout=86400)

Send email to user and wait for debugger to attach.

Parameters:

arg – What to debug. Should be a sys.exc_info() result or a sys._getframe() result.
mailto – Recipient to email. Defaults to $USER or current user.
background – If True, fork a child process. The parent process continues immediately without waiting. The child process waits for a debugger to attach, and exits when the debugging session completes.
timeout – Maximum number of seconds to wait for user to attach debugger.