class manhole.Logger[source]

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)[source]

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)[source]

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 manhole.

  • sigmask (list of signal 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.

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


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.

Checks credentials for given socket.


Dumps thread ids and tracebacks to stdout.


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


Alternate connection handler. No output redirection.


Handles connection.


Dumps stacktraces and runs an interactive prompt (REPL).

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

Installs the manhole.

  • 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 because Python will force all the signal handling to be run in the main thread but signalfd doesn’t.
  • socket_path (str) – Use a specific path for the unix domain socket (instead of /tmp/manhole-<pid>). This disables patch_fork as children cannot reuse 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".