manhole

class manhole.Logger

Internal object used for logging.

Initially this is not configured. Until you call manhole.install() this logger object won’t work (will raise NotInstalled).

time() → floating point number

Return the current time in seconds since the Epoch. Fractions of a second may be present if the system clock provides them.

class manhole.ManholeConnectionThread(client, connection_handler, daemon=False)

Manhole thread that handles the connection. This thread is a normal thread (non-daemon) - it won’t exit if the main thread exits.

class manhole.ManholeThread(get_socket, sigmask, start_timeout, connection_handler, bind_delay=None, daemon_connection=False)

Thread that runs the infamous “Manhole”. This thread is a daemon thread - it will exit if the main thread exits.

On connect, a different, non-daemon thread will be started - so that the process won’t exit while there’s a connection to the manole.

Parameters:

• sigmask (list of singal numbers) – Signals to block in this thread.
• start_timeout (float) – Seconds to wait for the thread to start. Emits a message if the thread is not running when calling start().
• bind_delay (float) – Seconds to delay socket binding. Default: no delay.
• daemon_connection (bool) – The connection thread is daemonic (dies on app exit). Default: False.

clone(**kwargs)

Make a fresh thread with the same options. This is usually used on dead threads.

run()

Runs the manhole loop. Only accepts one connection at a time because:

• This thread is a daemon thread (exits when main thread exists).
• The connection need exclusive access to stdin, stderr and stdout so it can redirect inputs and outputs.

manhole.check_credentials(client)

Checks credentials for given socket.

manhole.dump_stacktraces()

Dumps thread ids and tracebacks to stdout.

manhole.get_peercred(sock)

Gets the (pid, uid, gid) for the client on the given connected socket.

manhole.handle_connection_exec(client)

Alternate connection handler. No output redirection.

manhole.handle_connection_repl(client)

Handles connection.

manhole.handle_repl(locals)

Dumps stacktraces and runs an interactive prompt (REPL).

manhole.install(verbose=True, verbose_destination=2, strict=True, **kwargs)

Installs the manhole.

Parameters:

• verbose (bool) – Set it to False to squelch the logging.
• verbose_destination (file descriptor or handle) – Destination for verbose messages. Default is unbuffered stderr (stderr 2 file descriptor).
• patch_fork (bool) – Set it to False if you don’t want your os.fork and os.forkpy monkeypatched
• activate_on (int or signal name) – set to "USR1", "USR2" or some other signal name, or a number if you want the Manhole thread to start when this signal is sent. This is desireable in case you don’t want the thread active all the time.
• oneshot_on (int or signal name) – Set to "USR1", "USR2" or some other signal name, or a number if you want the Manhole to listen for connection in the signal handler. This is desireable in case you don’t want threads at all.
• thread (bool) – Start the always-on ManholeThread. Default: True. Automatically switched to False if oneshort_on or activate_on are used.
• sigmask (list of ints or signal names) – Will set the signal mask to the given list (using signalfd.sigprocmask). No action is done if signalfd is not importable. NOTE: This is done so that the Manhole thread doesn’t steal any signals; Normally that is fine cause Python will force all the signal handling to be run in the main thread but signalfd doesn’t.
• socket_path (str) – Use a specifc path for the unix domain socket (instead of /tmp/manhole-<pid>). This disables patch_fork as children cannot resuse the same path.
• reinstall_delay (float) – Delay the unix domain socket creation reinstall_delay seconds. This alleviates cleanup failures when using fork+exec patterns.
• locals (dict) – Names to add to manhole interactive shell locals.
• daemon_connection (bool) – The connection thread is daemonic (dies on app exit). Default: False.
• redirect_stderr (bool) – Redirect output from stderr to manhole console. Default: True.
• connection_handler (function) – Connection handler to use. Use "exec" for simple implementation without output redirection or your own function. (warning: this is for advanced users). Default: "repl".