interaction

dev_tool.tools.interaction

log = logging.getLogger(__name__) module-attribute

copy_to_clipboard

A function that copies text to the system clipboard.

Parameters:

• text (str) –

  The text to copy to the clipboard.

Returns:

• bool –

  True if successful, False otherwise.

Source code in dev_tool/tools/interaction.py

def copy_to_clipboard(text: str) -> bool:
    """
    A function that copies text to the system clipboard.

    :param text: The text to copy to the clipboard.
    :return: True if successful, False otherwise.
    """

    if not text:
        return False

    try:
        if sys.platform == OperatingSystem.WINDOWS:
            command = ['clip']

            process = subprocess.Popen(command, stdin=subprocess.PIPE)
            process.communicate(text.encode('utf-8'))
        elif sys.platform == OperatingSystem.MAC:
            command = ['pbcopy']

            process = subprocess.Popen(command, stdin=subprocess.PIPE)
            process.communicate(text.encode('utf-8'))
        else:
            command = ['xclip', '-selection', 'clipboard']

            process = subprocess.Popen(command, stdin=subprocess.PIPE)
            process.communicate(text.encode('utf-8'))
    except Exception:
        return False
    else:
        return True

get_input_and_clear_terminal

A function that gets user input and clears the terminal.

Parameters:

• prompt (str) –

  The prompt to display to the user.

Returns:

• str –

  The user's input.

Source code in dev_tool/tools/interaction.py

def get_input_and_clear_terminal(prompt: str) -> str:
    """
    A function that gets user input and clears the terminal.

    :param prompt: The prompt to display to the user.
    :return: The user's input.
    """

    response = input(prompt).strip().lower()
    clear_terminal()

    return response

get_user_confirmation

A function that gets a yes/no confirmation from the user.

Parameters:

• prompt (str) –

  The prompt to display to the user.

Returns:

• bool –

  True if the user confirmed, False otherwise.

Source code in dev_tool/tools/interaction.py

def get_user_confirmation(prompt: str) -> bool:
    """
    A function that gets a yes/no confirmation from the user.

    :param prompt: The prompt to display to the user.
    :return: True if the user confirmed, False otherwise.
    """

    choice = input(f'{prompt} [y/n]: ').strip()
    return bool(choice.lower() == 'y' or choice.lower() == 'yes')

get_user_input

A function that gets user input.

Parameters:

• prompt (str) –

  The prompt to display to the user.

Returns:

• str –

  The user's input as a string.

Source code in dev_tool/tools/interaction.py

def get_user_input(prompt: str) -> str:
    """
    A function that gets user input.

    :param prompt: The prompt to display to the user.
    :return: The user's input as a string.
    """

    return input(prompt + '\n').strip()

open_directory_in_explorer

A function that opens a directory in the system file explorer.

Parameters:

• path (Path) –

  The path to the directory to open.

Source code in dev_tool/tools/interaction.py

def open_directory_in_explorer(path: Path) -> None:
    """
    A function that opens a directory in the system file explorer.

    :param path: The path to the directory to open.
    """

    directory = str(path)

    try:
        if sys.platform == OperatingSystem.WINDOWS:
            command = ['explorer', directory]
            subprocess.run(command, check=False)
        elif sys.platform == OperatingSystem.MAC:
            command = ['open', directory]
            subprocess.run(command, check=True)
        else:
            command = ['xdg-open', directory]
            subprocess.run(command, check=True)
    except Exception:
        message = 'An error occurred while trying to open the directory'
        emit_warning(message)

        log.exception(message)

open_url_in_browser

A function that opens a URL in the default web browser.

Parameters:

• url (str) –

  The URL to open.

Source code in dev_tool/tools/interaction.py

def open_url_in_browser(url: str) -> None:
    """
    A function that opens a URL in the default web browser.

    :param url: The URL to open.
    """

    try:
        webbrowser.open(url)
    except Exception:
        message = 'An error occurred while trying to open the URL'
        emit_warning(message)

        log.exception(message)

wait_for_enter

A function that waits for Enter key using blessed's input handling.

This function uses blessed's inkey() to properly handle input, first draining any buffered input, then waiting for an Enter keypress.

Parameters:

• terminal (Terminal) –

  The blessed Terminal instance for input handling.

• message (str) –

  The message to display while waiting for input.

Source code in dev_tool/tools/interaction.py

def wait_for_enter(terminal: Terminal, message: str) -> None:
    """
    A function that waits for Enter key using blessed's input handling.

    This function uses blessed's inkey() to properly handle input,
    first draining any buffered input, then waiting for an Enter keypress.

    :param terminal: The blessed Terminal instance for input handling.
    :param message: The message to display while waiting for input.
    """

    print(message, end='', flush=True)  # noqa: T201

    waiting = True

    with TerminalSuspension(terminal) as suspension:
        while waiting:
            with terminal.cbreak():
                while waiting and not suspension.resumed:
                    key = terminal.inkey(timeout=INPUT_POLL_SECONDS)
                    if not key:
                        continue

                    if key.name in (Key.ENTER, Key.LINE_FEED, Key.CARRIAGE_RETURN):
                        waiting = False

            if suspension.acknowledge():
                print(message, end='', flush=True)  # noqa: T201

wait_for_stop

A function that polls the keyboard until a stop is requested.

The loop ends when the stop event is set or, when an is_running check is given, when it reports False. Ctrl+R calls the restart callback. The terminal is kept in cbreak mode so a keystroke is delivered without Enter, and it is entered again after a suspension, which leaves the shell's modes in place.

Parameters:

• terminal (Terminal) –

  The blessed Terminal instance for input handling.

• stop_event (Event) –

  The event that signals the loop to stop.

• restart (Callable[[], None]) –

  The callback invoked when Ctrl+R is pressed.

• is_running (Callable[[], bool] | None, default: None ) –

  An optional check that reports whether the watched process is still alive.

Source code in dev_tool/tools/interaction.py

def wait_for_stop(
    terminal: Terminal,
    stop_event: threading.Event,
    restart: Callable[[], None],
    is_running: Callable[[], bool] | None = None
) -> None:
    """
    A function that polls the keyboard until a stop is requested.

    The loop ends when the stop event is set or, when an is_running check is
    given, when it reports False. Ctrl+R calls the restart callback. The
    terminal is kept in cbreak mode so a keystroke is delivered without Enter,
    and it is entered again after a suspension, which leaves the shell's modes
    in place.

    :param terminal: The blessed Terminal instance for input handling.
    :param stop_event: The event that signals the loop to stop.
    :param restart: The callback invoked when Ctrl+R is pressed.
    :param is_running: An optional check that reports whether the watched process is still alive.
    """

    with TerminalSuspension(terminal) as suspension:
        while not stop_event.is_set():
            with terminal.cbreak():
                while not stop_event.is_set() and not suspension.resumed:
                    if is_running is not None and not is_running():
                        return

                    key = terminal.inkey(timeout=INPUT_POLL_SECONDS)

                    if key == Key.RESTART:
                        restart()

            suspension.acknowledge()