def run(
    args: str | list[str],
    *,
    log_run_to_stderr: bool = True,
    abbreviate_non_option_arguments: bool = False,
    check: bool = True,
    text: bool = True,
    **subprocess_run_kwargs,
) -> subprocess.CompletedProcess:
    """Call subprocess.run with an option to log executed command to stderr.

    Args:
        args: The arguments for launching the process.  This may be a list
            or a string.  The string type may need to be used with
            ``shell=True`` to allow invocation as a shell command;
            otherwise the string is used as a command name with no arguments.
        log_run_to_stderr: Determines whether the fact that this command
            was executed is logged to sys.stderr or not.
        abbreviate_non_option_arguments: When logging to stderr, this cuts off
            the potentially-huge tail of the command listing off e.g. hundreds
            of file paths. No effect if log_run_to_stderr is not set.
        check: Raise the CalledProcessError exception if this flag is
            set and the process returns a non-zero exit code.  This sets
            the default check argument for the `subprocess.run` to True.
        text: Use text mode for the stdout and stderr streams from the
            process.  This changes the default text argument to the
            `subprocess.run` call to True.
        **subprocess_run_kwargs: Arguments passed to `subprocess.run`.
            See `subprocess.run` for a full detail of supported arguments.

    Returns:
        subprocess.CompletedProcess: The return value from `subprocess.run`.

    Raises:
        subprocess.CalledProcessError: The process returned a non-zero error
            code and the check argument was set.
    """
    # setup our default for subprocess.run flag arguments
    subprocess_run_kwargs.update(check=check, text=text)
    if log_run_to_stderr:
        cmd_desc: tuple[str, ...] = (args,) if isinstance(args, str) else tuple(args)
        if abbreviate_non_option_arguments:
            cmd_desc = abbreviate_command_arguments_after_switches(cmd_desc)
        print('run:', cmd_desc, file=sys.stderr)
    return subprocess.run(args, **subprocess_run_kwargs)
Call subprocess.run with an option to log executed command to stderr.

    Args:
        args: The arguments for launching the process.  This may be a list
            or a string.  The string type may need to be used with
            ``shell=True`` to allow invocation as a shell command;
            otherwise the string is used as a command name with no arguments.
        log_run_to_stderr: Determines whether the fact that this command
            was executed is logged to sys.stderr or not.
        abbreviate_non_option_arguments: When logging to stderr, this cuts off
            the potentially-huge tail of the command listing off e.g. hundreds
            of file paths. No effect if log_run_to_stderr is not set.
        check: Raise the CalledProcessError exception if this flag is
            set and the process returns a non-zero exit code.  This sets
            the default check argument for the `subprocess.run` to True.
        text: Use text mode for the stdout and stderr streams from the
            process.  This changes the default text argument to the
            `subprocess.run` call to True.
        **subprocess_run_kwargs: Arguments passed to `subprocess.run`.
            See `subprocess.run` for a full detail of supported arguments.

    Returns:
        subprocess.CompletedProcess: The return value from `subprocess.run`.

    Raises:
        subprocess.CalledProcessError: The process returned a non-zero error
            code and the check argument was set.
    
dev_tools/shell_tools.py