_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_w()

Return a file object opened for 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._remote_print_stack_to_file(pid, filename)
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.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.