manhole

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, locals, 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.

static check_credentials(client)[source]

Checks credentials for given socket.

static handle(client, locals)[source]

Handles connection. This is a static method so it can be used without a thread (eg: from a signal handler - oneshot_on).

class manhole.ManholeThread(get_socket, sigmask, start_timeout, bind_delay=None, locals=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 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)[source]

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

run()[source]

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

Dumps thread ids and tracebacks to stdout.

manhole.get_peercred(sock)[source]

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

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

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.
manhole.run_repl(locals)[source]

Dumps stacktraces and runs an interactive prompt (REPL).