euporie.hub.app

Run euporie as a multi-client SSH server.

Functions

`add_setting`(name, default, help_, description)	Register a new config item.
`entry_points`(**params)	Return EntryPoint objects for all installed packages.
`get_event_loop`()	Return an asyncio event loop.
`setup_logs`([config])	Configure the logger for euporie.

Classes

`BaseApp`([title, set_title, leave_graphics, ...])	All euporie apps.
`EuporieSSHServer`(app_cls)	Launch euporie hub, which serves a euporie app over SSH.
`HubApp`([title, set_title, leave_graphics, ...])	Hub App.
`PromptToolkitSSHSession`(interact, *, enable_cpr)
`UPath`(args, *kwargs)

class euporie.hub.app.EuporieSSHServer(app_cls: type[euporie.core.app.BaseApp])

Bases: asyncssh.server.SSHServer

Launch euporie hub, which serves a euporie app over SSH.

Launch euporie hub, a multi-client SSH server running euporie, which allows multiple users to connect and run instances of a euporie app.

auth_completed() → None

Authentication was completed successfully

This method is called when authentication has completed succesfully. Applications may use this method to perform processing based on the authenticated username or options in the authorized keys list or certificate associated with the user before any sessions are opened or forwarding requests are handled.

begin_auth(username: str) → bool | Awaitable[bool]: Perform authentication in the SSH server.

change_password(username: str, old_password: str, new_password: str) → Union[bool, Awaitable[bool]]

Handle a request to change a user’s password

This method is called when a user makes a request to change their password. It should first validate that the old password provided is correct and then attempt to change the user’s password to the new value.

If the old password provided is valid and the change to the new password is successful, this method should return True. If the old password is not valid or password changes are not supported, it should return False. It may also raise PasswordChangeRequired to request that the client try again if the new password is not acceptable for some reason.

If blocking operations need to be performed to determine the validity of the old password or to change to the new password, this method may be defined as a coroutine.

By default, this method returns False, rejecting all password changes.

Parameters

username (str) – The user whose password should be changed
old_password (str) – The user’s current password
new_password (str) – The new password being requested

Returns

A bool indicating if the password change is successful or not

Raises

PasswordChangeRequired if the new password is not acceptable and the client should be asked to provide another

connection_lost(exc: Optional[Exception]) → None

Called when a connection is lost or closed

This method is called when a connection is closed. If the connection is shut down cleanly, exc will be None. Otherwise, it will be an exception explaining the reason for the disconnect.

connection_made(conn: SSHServerConnection) → None

Called when a connection is made

This method is called when a new TCP connection is accepted. The conn parameter should be stored if needed for later use.

Parameters: conn (SSHServerConnection) – The connection which was successfully opened

connection_requested(dest_host: str, dest_port: int, orig_host: str, orig_port: int) → Union[bool, SSHTCPSession, Callable[[SSHReader, SSHWriter], Union[None, Awaitable[None]]], Tuple[SSHTCPChannel, SSHTCPSession], Tuple[SSHTCPChannel, Callable[[SSHReader, SSHWriter], Union[None, Awaitable[None]]]]]

Handle a direct TCP/IP connection request

This method is called when a direct TCP/IP connection request is received by the server. Applications wishing to accept such connections must override this method.

To allow standard port forwarding of data on the connection to the requested destination host and port, this method should return True.

To reject this request, this method should return False to send back a “Connection refused” response or raise an ChannelOpenError exception with the reason for the failure.

If the application wishes to process the data on the connection itself, this method should return either an SSHTCPSession object which can be used to process the data received on the channel or a tuple consisting of of an SSHTCPChannel object created with create_tcp_channel() and an SSHTCPSession, if the application wishes to pass non-default arguments when creating the channel.

If blocking operations need to be performed before the session can be created, a coroutine which returns an SSHTCPSession object can be returned instead of the session iself. This can be either returned directly or as a part of a tuple with an SSHTCPChannel object.

By default, all connection requests are rejected.

Parameters

dest_host (str) – The address the client wishes to connect to
dest_port (int) – The port the client wishes to connect to
orig_host (str) – The address the connection was originated from
orig_port (int) – The port the connection was originated from

Returns

One of the following:

An SSHTCPSession object or a coroutine which returns an SSHTCPSession
A tuple consisting of an SSHTCPChannel and the above
A callable or coroutine handler function which takes AsyncSSH stream objects for reading from and writing to the connection
A tuple consisting of an SSHTCPChannel and the above
True to request standard port forwarding
False to refuse the connection

Raises

ChannelOpenError if the connection shouldn’t be accepted

debug_msg_received(msg: str, lang: str, always_display: bool) → None

A debug message was received on this connection

This method is called when the other end of the connection sends a debug message. Applications should implement this method if they wish to process these debug messages.

Parameters

msg (str) – The debug message sent
lang (str) – The language the message is in
always_display (bool) – Whether or not to display the message

get_kbdint_challenge(username: str, lang: str, submethods: str) → Union[bool, Tuple[str, str, str, Sequence[Tuple[str, bool]]], Awaitable[Union[bool, Tuple[str, str, str, Sequence[Tuple[str, bool]]]]]]

Return a keyboard-interactive auth challenge

This method should return True if authentication should succeed without any challenge, False if authentication should fail without any challenge, or an auth challenge consisting of a challenge name, instructions, a language tag, and a list of tuples containing prompt strings and booleans indicating whether input should be echoed when a value is entered for that prompt.

If blocking operations need to be performed to determine the challenge to issue, this method may be defined as a coroutine.

Parameters

username (str) – The user being authenticated
lang (str) – The language requested by the client for the challenge
submethods (str) – A comma-separated list of the types of challenges the client can support, or the empty string if the server should choose

Returns

An authentication challenge as described above

host_based_auth_supported() → bool

Return whether or not host-based authentication is supported

This method should return True if client host-based authentication is supported. Applications wishing to support it must have this method return True and implement validate_host_public_key() and/or validate_host_ca_key() to return whether or not the key provided by the client is valid for the client host being authenticated.

By default, it returns False indicating the client host based authentication is not supported.

Returns: A bool indicating if host-based authentication is supported or not

kbdint_auth_supported() → bool

Return whether or not keyboard-interactive authentication is supported

This method should return True if keyboard-interactive authentication is supported. Applications wishing to support it must have this method return True and implement get_kbdint_challenge() and validate_kbdint_response() to generate the apporiate challenges and validate the responses for the user being authenticated.

By default, this method returns NotImplemented tying this authentication to password authentication. If the application implements password authentication and this method is not overridden, keyboard-interactive authentication will be supported by prompting for a password and passing that to the password authentication callbacks.

Returns: A bool indicating if keyboard-interactive authentication is supported or not

password_auth_supported() → bool

Return whether or not password authentication is supported

This method should return True if password authentication is supported. Applications wishing to support it must have this method return True and implement validate_password() to return whether or not the password provided by the client is valid for the user being authenticated.

By default, this method returns False indicating that password authentication is not supported.

Returns: A bool indicating if password authentication is supported or not

public_key_auth_supported() → bool

Return whether or not public key authentication is supported

This method should return True if client public key authentication is supported. Applications wishing to support it must have this method return True and implement validate_public_key() and/or validate_ca_key() to return whether or not the key provided by the client is valid for the user being authenticated.

By default, it returns False indicating the client public key authentication is not supported.

Returns: A bool indicating if public key authentication is supported or not

server_requested(listen_host: str, listen_port: int) → Union[bool, asyncssh.listener.SSHListener, Awaitable[Union[bool, asyncssh.listener.SSHListener]]]

Handle a request to listen on a TCP/IP address and port

This method is called when a client makes a request to listen on an address and port for incoming TCP connections. The port to listen on may be 0 to request a dynamically allocated port. Applications wishing to allow TCP/IP connection forwarding must override this method.

To set up standard port forwarding of connections received on this address and port, this method should return True.

If the application wishes to manage listening for incoming connections itself, this method should return an SSHListener object that listens for new connections and calls create_connection on each of them to forward them back to the client or return None if the listener can’t be set up.

If blocking operations need to be performed to set up the listener, a coroutine which returns an SSHListener can be returned instead of the listener itself.

To reject this request, this method should return False.

By default, this method rejects all server requests.

Parameters

listen_host (str) – The address the server should listen on
listen_port (int) – The port the server should listen on, or the value 0 to request that the server dynamically allocate a port

Returns

One of the following:

An SSHListener object
True to set up standard port forwarding
False to reject the request
A coroutine object which returns one of the above

session_requested() → prompt_toolkit.contrib.ssh.server.PromptToolkitSSHSession: Return an SSH session.

unix_connection_requested(dest_path: str) → Union[bool, SSHUNIXSession, Callable[[SSHReader, SSHWriter], Union[None, Awaitable[None]]], Tuple[SSHUNIXChannel, SSHUNIXSession], Tuple[SSHUNIXChannel, Callable[[SSHReader, SSHWriter], Union[None, Awaitable[None]]]]]

Handle a direct UNIX domain socket connection request

This method is called when a direct UNIX domain socket connection request is received by the server. Applications wishing to accept such connections must override this method.

To allow standard path forwarding of data on the connection to the requested destination path, this method should return True.

To reject this request, this method should return False to send back a “Connection refused” response or raise an ChannelOpenError exception with the reason for the failure.

If the application wishes to process the data on the connection itself, this method should return either an SSHUNIXSession object which can be used to process the data received on the channel or a tuple consisting of of an SSHUNIXChannel object created with create_unix_channel() and an SSHUNIXSession, if the application wishes to pass non-default arguments when creating the channel.

If blocking operations need to be performed before the session can be created, a coroutine which returns an SSHUNIXSession object can be returned instead of the session iself. This can be either returned directly or as a part of a tuple with an SSHUNIXChannel object.

By default, all connection requests are rejected.

Parameters

dest_path (str) – The path the client wishes to connect to

Returns

One of the following:

An SSHUNIXSession object or a coroutine which returns an SSHUNIXSession
A tuple consisting of an SSHUNIXChannel and the above
A callable or coroutine handler function which takes AsyncSSH stream objects for reading from and writing to the connection
A tuple consisting of an SSHUNIXChannel and the above
True to request standard path forwarding
False to refuse the connection

Raises

ChannelOpenError if the connection shouldn’t be accepted

unix_server_requested(listen_path: str) → Union[bool, asyncssh.listener.SSHListener, Awaitable[Union[bool, asyncssh.listener.SSHListener]]]

Handle a request to listen on a UNIX domain socket

This method is called when a client makes a request to listen on a path for incoming UNIX domain socket connections. Applications wishing to allow UNIX domain socket forwarding must override this method.

To set up standard path forwarding of connections received on this path, this method should return True.

If the application wishes to manage listening for incoming connections itself, this method should return an SSHListener object that listens for new connections and calls create_unix_connection on each of them to forward them back to the client or return None if the listener can’t be set up.

If blocking operations need to be performed to set up the listener, a coroutine which returns an SSHListener can be returned instead of the listener itself.

To reject this request, this method should return False.

By default, this method rejects all server requests.

Parameters

listen_path (str) – The path the server should listen on

Returns

One of the following:

An SSHListener object or a coroutine which returns an SSHListener or False if the listener can’t be opened
True to set up standard path forwarding
False to reject the request

validate_ca_key(username: str, key: asyncssh.public_key.SSHKey) → Union[bool, Awaitable[bool]]

Return whether key is an authorized CA key for this user

Certificate based client authentication can be supported by passing authorized CA keys in the authorized_client_keys argument of create_server(), or by calling set_authorized_keys on the server connection from the begin_auth() method. However, for more flexibility in matching on the allowed set of keys, this method can be implemented by the application to do the matching itself. It should return True if the specified key is a valid certificate authority key for the user being authenticated.

This method may be called multiple times with different keys provided by the client. Applications should precompute as much as possible in the begin_auth() method so that this function can quickly return whether the key provided is in the list.

If blocking operations need to be performed to determine the validity of the key, this method may be defined as a coroutine.

By default, this method returns False for all CA keys.

Note

This function only needs to report whether the public key provided is a valid CA key for this user. If it is, AsyncSSH will verify that the certificate is valid, that the user is one of the valid principals for the certificate, and that the client possesses the private key corresponding to the public key in the certificate before allowing the authentication to succeed.

Parameters

username (str) – The user being authenticated
key (SSHKey public key) – The public key which signed the certificate sent by the client

Returns

A bool indicating if the specified key is a valid CA key for the user being authenticated

validate_gss_principal(username: str, user_principal: str, host_principal: str) → Union[bool, Awaitable[bool]]

Return whether a GSS principal is valid for this user

This method should return True if the specified user principal is valid for the user being authenticated. It can be overridden by applications wishing to perform their own authentication.

If blocking operations need to be performed to determine the validity of the principal, this method may be defined as a coroutine.

By default, this method will return True only when the name in the user principal exactly matches the username and the domain of the user principal matches the domain of the host principal.

Parameters

username (str) – The user being authenticated
user_principal (str) – The user principal sent by the client
host_principal (str) – The host principal sent by the server

Returns

A bool indicating if the specified user principal is valid for the user being authenticated

validate_host_based_user(username: str, client_host: str, client_username: str) → Union[bool, Awaitable[bool]]

Return whether remote host and user is authorized for this user

This method should return True if the specified client host and user is valid for the user being authenticated. It can be overridden by applications wishing to enforce restrictions on which remote users are allowed to authenticate as particular local users.

If blocking operations need to be performed to determine the validity of the client host and user, this method may be defined as a coroutine.

By default, this method will return True when the client username matches the name of the user being authenticated.

Parameters

username (str) – The user being authenticated
client_host (str) – The hostname of the client host making the request
client_username (str) – The username of the user on the client host

Returns

A bool indicating if the specified client host and user is valid for the user being authenticated

validate_host_ca_key(client_host: str, client_addr: str, client_port: int, key: asyncssh.public_key.SSHKey) → bool

Return whether key is an authorized CA key for this client host

Certificate based client host authentication can be supported by passing authorized host CA keys in the known_client_hosts argument of create_server(). However, for more flexibility in matching on the allowed set of keys, this method can be implemented by the application to do the matching itself. It should return True if the specified key is a valid certificate authority key for the client host being authenticated.

This method may be called multiple times with different keys provided by the client. Applications should precompute as much as possible in the begin_auth() method so that this function can quickly return whether the key provided is in the list.

By default, this method returns False for all CA keys.

Note

This function only needs to report whether the public key provided is a valid CA key for this client host. If it is, AsyncSSH will verify that the certificate is valid, that the client host is one of the valid principals for the certificate, and that the client possesses the private key corresponding to the public key in the certificate before allowing the authentication to succeed.

Parameters

client_host (str) – The hostname of the client host
client_addr (str) – The IP address of the client host
client_port (int) – The port number on the client host
key (SSHKey public key) – The public key which signed the certificate sent by the client

Returns

A bool indicating if the specified key is a valid CA key for the client host being authenticated

validate_host_public_key(client_host: str, client_addr: str, client_port: int, key: asyncssh.public_key.SSHKey) → bool

Return whether key is an authorized host key for this client host

Host key based client authentication can be supported by passing authorized host keys in the known_client_hosts argument of create_server(). However, for more flexibility in matching on the allowed set of keys, this method can be implemented by the application to do the matching itself. It should return True if the specified key is a valid host key for the client host being authenticated.

This method may be called multiple times with different keys provided by the client. Applications should precompute as much as possible in the begin_auth() method so that this function can quickly return whether the key provided is in the list.

By default, this method returns False for all client host keys.

Note

This function only needs to report whether the public key provided is a valid key for this client host. If it is, AsyncSSH will verify that the client possesses the corresponding private key before allowing the authentication to succeed.

Parameters

client_host (str) – The hostname of the client host
client_addr (str) – The IP address of the client host
client_port (int) – The port number on the client host
key (SSHKey public key) – The host public key sent by the client

Returns

A bool indicating if the specified key is a valid key for the client host being authenticated

validate_kbdint_response(username: str, responses: Sequence[str]) → Union[bool, Tuple[str, str, str, Sequence[Tuple[str, bool]]], Awaitable[Union[bool, Tuple[str, str, str, Sequence[Tuple[str, bool]]]]]]

Return whether the keyboard-interactive response is valid for this user

This method should validate the keyboard-interactive responses provided and return True if authentication should succeed with no further challenge, False if authentication should fail, or an additional auth challenge in the same format returned by get_kbdint_challenge(). Any series of challenges can be returned this way. To print a message in the middle of a sequence of challenges without prompting for additional data, a challenge can be returned with an empty list of prompts. After the client acknowledges this message, this function will be called again with an empty list of responses to continue the authentication.

If blocking operations need to be performed to determine the validity of the response or the next challenge to issue, this method may be defined as a coroutine.

Parameters

username (str) – The user being authenticated
responses (list of str) – A list of responses to the last challenge

Returns

True, False, or the next challenge

validate_password(username: str, password: str) → Union[bool, Awaitable[bool]]

Return whether password is valid for this user

This method should return True if the specified password is a valid password for the user being authenticated. It must be overridden by applications wishing to support password authentication.

If the password provided is valid but expired, this method may raise PasswordChangeRequired to request that the client provide a new password before authentication is allowed to complete. In this case, the application must override change_password() to handle the password change request.

This method may be called multiple times with different passwords provided by the client. Applications may wish to limit the number of attempts which are allowed. This can be done by having password_auth_supported() begin returning False after the maximum number of attempts is exceeded.

If blocking operations need to be performed to determine the validity of the password, this method may be defined as a coroutine.

By default, this method returns False for all passwords.

Parameters

username (str) – The user being authenticated
password (str) – The password sent by the client

Returns

A bool indicating if the specified password is valid for the user being authenticated

Raises

PasswordChangeRequired if the password provided is expired and needs to be changed

validate_public_key(username: str, key: asyncssh.public_key.SSHKey) → Union[bool, Awaitable[bool]]

Return whether key is an authorized client key for this user

Key based client authentication can be supported by passing authorized keys in the authorized_client_keys argument of create_server(), or by calling set_authorized_keys on the server connection from the begin_auth() method. However, for more flexibility in matching on the allowed set of keys, this method can be implemented by the application to do the matching itself. It should return True if the specified key is a valid client key for the user being authenticated.

This method may be called multiple times with different keys provided by the client. Applications should precompute as much as possible in the begin_auth() method so that this function can quickly return whether the key provided is in the list.

If blocking operations need to be performed to determine the validity of the key, this method may be defined as a coroutine.

By default, this method returns False for all client keys.

Note

This function only needs to report whether the public key provided is a valid client key for this user. If it is, AsyncSSH will verify that the client possesses the corresponding private key before allowing the authentication to succeed.

Parameters

username (str) – The user being authenticated
key (SSHKey public key) – The public key sent by the client

Returns

A bool indicating if the specified key is a valid client key for the user being authenticated

class euporie.hub.app.HubApp(title: str | None = None, set_title: bool = True, leave_graphics: FilterOrBool = True, extend_renderer_height: FilterOrBool = False, extend_renderer_width: FilterOrBool = False, **kwargs: Any)

Bases: euporie.core.app.BaseApp

Hub App.

An app which runs as a multi-user SSH server.

This app never actually gets run, but is used to run another app in an SSH server.

async cancel_and_wait_for_background_tasks() → None

Cancel all background tasks, and wait for the cancellation to complete. If any of the background tasks raised an exception, this will also propagate the exception.

(If we had nurseries like Trio, this would be the __aexit__ of a nursery.)

cleanup(signum: int, frame: FrameType | None) → None: Restore the state of the terminal on unexpected exit.

cleanup_closed_tab(tab: Tab) → None

Remove a tab container from the current instance of the app.

Parameters: tab – The closed instance of the tab container

clipboard: Clipboard

close_tab(tab: Tab | None = None) → None

Close a notebook tab.

Parameters: tab – The instance of the tab to close. If None, the currently selected tab will be closed.

property color_depth: prompt_toolkit.output.color_depth.ColorDepth

The active ColorDepth.

The current value is determined as follows:

If a color depth was given explicitly to this application, use that value.
Otherwise, fall back to the color depth that is reported by the Output implementation. If the Output class was created using output.defaults.create_output, then this value is coming from the $PROMPT_TOOLKIT_COLOR_DEPTH environment variable.

color_palette: ColorPalette

context: contextvars.Context | None

cpr_not_supported_callback() → None: Called when we don’t receive the cursor position response in time.

create_background_task(coroutine: Coroutine[Any, Any, None]) → _asyncio.Task[None]

Start a background task (coroutine) for the running application. When the Application terminates, unfinished background tasks will be cancelled.

Given that we still support Python versions before 3.11, we can’t use task groups (and exception groups), because of that, these background tasks are not allowed to raise exceptions. If they do, we’ll call the default exception handler from the event loop.

If at some point, we have Python 3.11 as the minimum supported Python version, then we can use a TaskGroup (with the lifetime of Application.run_async(), and run run the background tasks in there.

This is not threadsafe.

create_merged_style() → prompt_toolkit.styles.base.BaseStyle

Generate a new merged style for the application.

Using a dynamic style has serious performance issues, so instead we update the style on the renderer directly when it changes in self.update_style

Returns: Return a combined style to use for the application

property current_buffer: prompt_toolkit.buffer.Buffer

The currently focused Buffer.

(This returns a dummy Buffer when none of the actual buffers has the focus. In this case, it’s really not practical to check for None values or catch exceptions every time.)

property current_search_state: prompt_toolkit.search.SearchState: Return the current SearchState. (The one for the focused BufferControl.)

dialogs: dict[str, Dialog]

draw(render_as_done: bool = True) → None: Draw the app without focus, leaving the cursor below the drawn output.

exit(result: Optional[prompt_toolkit.application.application._AppResult] = None, exception: BaseException | type[BaseException] | None = None, style: str = '') → None

Exit application.

Note

If Application.exit is called before Application.run() is called, then the Application won’t exit (because the Application.future doesn’t correspond to the current run). Use a pre_run hook and an event to synchronize the closing if there’s a chance this can happen.

Parameters

result – Set this result for the application.
exception – Set this exception as the result for an application. For a prompt, this is often EOFError or KeyboardInterrupt.
style – Apply this style on the whole content when quitting, often this is ‘class:exiting’ for a prompt. (Used when erase_when_done is not set.)

focus_tab(tab: Tab) → None: Make a tab visible and focuses it.

focused_element: FocusableElement | None

full_screen: bool

future: Future[_AppResult] | None

get_edit_mode() → prompt_toolkit.enums.EditingMode: Return the editing mode enum defined in the configuration.

get_file_tab(path: Path) → type[Tab] | None: Return the tab to use for a file path.

get_file_tabs(path: Path) → list[type[Tab]]: Return the tab to use for a file path.

get_used_style_strings() → list[str]: Return a list of used style strings. This is helpful for debugging, and for writing a new Style.

graphics: WeakSet[Float]

async classmethod interact(ssh_session: PromptToolkitSSHSession) → None: Run the app asynchronously for the hub SSH server.

invalidate() → None: Thread safe way of sending a repaint trigger to the input event loop.

property invalidated: bool: True when a redraw operation has been scheduled.

property is_done: bool

property is_running: bool: True when the application is currently active/running.

key_processor: The InputProcessor instance.

classmethod launch() → None: Launch the HubApp SSH server.

load_container() → prompt_toolkit.layout.containers.FloatContainer

Load the root container for this application.

Returns: The root container for this app

classmethod load_input() → Input

Create the input for this application to use.

Ensures the TUI app always tries to run in a TTY.

Returns: A prompt-toolkit input instance

load_key_bindings() → None: Load the application’s key bindings.

classmethod load_output() → Output

Create the output for this application to use.

Ensures the TUI app always tries to run in a TTY.

Returns: A prompt-toolkit output instance

log_stdout_level: str = 'CRITICAL'

loop: AbstractEventLoop | None

menus: dict[str, Float]

mouse_limits: WritePosition | None

mouse_position: Point

name: str = 'hub'

need_mouse_support: bool = False

open_file(path: Path, read_only: bool = False, tab_class: type[Tab] | None = None) → None

Create a tab for a file.

Parameters

path – The file path of the notebook file to open
read_only – If true, the file should be opened read_only
tab_class – The tab type to use to open the file

open_files() → None: Open the files defined in the configuration.

pager: Pager | None

pause_rendering() → None

Block rendering, but allows input to be processed.

The first line prevents the display being drawn, and the second line means the key processor continues to process keys. We need this as we need to wait for the results of terminal queries which come in as key events.

This is used to prevent flicker when we update the styles based on terminal feedback.

post_load() → None: Allow subclasses to define additional loading steps.

post_load_callables: list[Callable[[], None]]

pre_run(app: prompt_toolkit.application.application.Application | None = None) → None: Call during the ‘pre-run’ stage of application loading.

pre_run_callables: list[Callable[[], None]]

print_text(text: AnyFormattedText, style: BaseStyle | None = None) → None

Print a list of (style_str, text) tuples to the output. (When the UI is running, this method has to be called through run_in_terminal, otherwise it will destroy the UI.)

Parameters

text – List of (style_str, text) tuples.
style – Style class to use. Defaults to the active style in the CLI.

quoted_insert: Quoted insert. This flag is set if we go into quoted insert mode.

refresh() → None: Reet all tabs.

render_counter: Render counter. This one is increased every time the UI is rendered. It can be used as a key for caching certain information during one rendering.

reset() → None: Reset everything, for reading the next input.

resume_rendering() → None: Reume rendering the app.

run(pre_run: Optional[Callable[[], None]] = None, set_exception_handler: bool = True, handle_sigint: bool = True, in_thread: bool = False) → prompt_toolkit.application.application._AppResult

A blocking ‘run’ call that waits until the UI is finished.

This will start the current asyncio event loop. If no loop is set for the current thread, then it will create a new loop. If a new loop was created, this won’t close the new loop (if in_thread=False).

Parameters

pre_run – Optional callable, which is called right after the “reset” of the application.
set_exception_handler – When set, in case of an exception, go out of the alternate screen and hide the application, display the exception, and wait for the user to press ENTER.
in_thread – When true, run the application in a background thread, and block the current thread until the application terminates. This is useful if we need to be sure the application won’t use the current event loop (asyncio does not support nested event loops). A new event loop will be created in this background thread, and that loop will also be closed when the background thread terminates. When this is used, it’s especially important to make sure that all asyncio background tasks are managed through get_appp().create_background_task(), so that unfinished tasks are properly cancelled before the event loop is closed. This is used for instance in ptpython.
handle_sigint – Handle SIGINT signal. Call the key binding for Keys.SIGINT. (This only works in the main thread.)

async run_async(pre_run: Optional[Callable[[], None]] = None, set_exception_handler: bool = True, handle_sigint: bool = True, slow_callback_duration: float = 0.5) → prompt_toolkit.application.application._AppResult

Run the prompt_toolkit Application until exit() has been called. Return the value that was passed to exit().

This is the main entry point for a prompt_toolkit Application and usually the only place where the event loop is actually running.

Parameters

pre_run – Optional callable, which is called right after the “reset” of the application.
set_exception_handler – When set, in case of an exception, go out of the alternate screen and hide the application, display the exception, and wait for the user to press ENTER.
handle_sigint – Handle SIGINT signal if possible. This will call the <sigint> key binding when a SIGINT is received. (This only works in the main thread.)
slow_callback_duration – Display warnings if code scheduled in the asyncio event loop takes more time than this. The asyncio default of 0.1 is sometimes not sufficient on a slow system, because exceptionally, the drawing of the app, which happens in the event loop, can take a bit longer from time to time.

async run_system_command(command: str, wait_for_enter: bool = True, display_before_text: AnyFormattedText = '', wait_text: str = 'Press ENTER to continue...') → None

Run system command (While hiding the prompt. When finished, all the output will scroll above the prompt.)

Parameters

command – Shell command to be executed.
wait_for_enter – FWait for the user to press enter, when the command is finished.
display_before_text – If given, text to be displayed before the command executes.

Returns

A Future object.

search_bar: SearchBar | None

suspend_to_background(suspend_group: bool = True) → None

(Not thread safe – to be called from inside the key bindings.) Suspend process.

Parameters: suspend_group – When true, suspend the whole process group. (This is the default, and probably what you want.)

property tab: Tab | None: Return the currently selected tab container object.

property tab_idx: int: Get the current tab index.

tabs: list[Tab]

timeoutlen: Like Vim’s timeoutlen option. This can be None or a float. For instance, suppose that we have a key binding AB and a second key binding A. If the uses presses A and then waits, we don’t handle this binding yet (unless it was marked ‘eager’), because we don’t know what will follow. This timeout is the maximum amount of time that we wait until we call the handlers anyway. Pass None to disable this timeout.

property title: str: The application’s title.

ttimeoutlen: When to flush the input (For flushing escape keys.) This is important on terminals that use vt100 input. We can’t distinguish the escape key from for instance the left-arrow key, if we don’t know what follows after “x1b”. This little timer will consider “x1b” to be escape if nothing did follow in this time span. This seems to work like the ttimeoutlen option in Vim.

update_edit_mode(setting: Setting | None = None) → None: Set the keybindings for editing mode.

update_style(query: TerminalQuery | Setting | None = None) → None: Update the application’s style when the syntax theme is changed.

vi_state: Vi state. (For Vi key bindings.)