Exec APIs - Launching Subprocesses

These API calls are used to launch subprocesses. You can launch Python files or any type of executable file. In these calls is where you invoke the editor and file explorer that was specified in the PySimpleGUI Global Settings.

execute_command_subprocess

Runs the specified command as a subprocess. By default the call is non-blocking. The function will immediately return without waiting for the process to complete running. You can use the returned Popen object to communicate with the subprocess and get the results. Returns a subprocess Popen object.

execute_command_subprocess(
    command,
    args = *<1 or N objects>,
    wait = False,
    cwd = None,
    pipe_output = False,
    merge_stderr_with_stdout = True,
    stdin = None
)

Parameter Descriptions

Name	Type	Default	Description
*args	Any		Variable number of arguments that are passed to the program being started as command line parms
command	str		The command/file to execute. What you would type at a console to run a program or shell command.
cwd	str	None	Working directory to use when executing the subprocess
merge_stderr_with_stdout	bool	True	If True then output from the subprocess stderr will be merged with stdout. The result is ALL output will be on stdout.
pipe_output	bool	False	If True then output from the subprocess will be piped. You MUST empty the pipe by calling execute_get_results or your subprocess will block until no longer full
stdin	bool	None	Value passed to the Popen call. Defaults to subprocess.DEVNULL so that the pyinstaller created executable work correctly
wait	bool	False	If True then wait for the subprocess to finish
RETURN	(subprocess.Popen)		Popen object

execute_editor

Runs the editor that was configured in the global settings and opens the file to a specific line number. Two global settings keys are used. '-editor program-' the command line used to startup your editor. It's set in the global settings window or by directly manipulating the PySimpleGUI settings object '-editor format string-' a string containing 3 "tokens" that describes the command that is executed

execute_editor(
    file_to_edit,
    line_number = None
)

Parameter Descriptions

Name	Type	Default	Description
file_to_edit	str		the full path to the file to edit
line_number	int	None	optional line number to place the cursor
RETURN	(subprocess.Popen) or None		Popen object

execute_file_explorer

The global settings has a setting called - "-explorer program-" It defines the program to run when this function is called. The optional folder paramter specified which path should be opened.

execute_file_explorer(
    folder_to_open = ""
)

Parameter Descriptions

Name	Type	Default	Description
folder_to_open	str		The path to open in the explorer program
RETURN	(subprocess.Popen) or None		Popen object

execute_find_callers_filename

Returns the first filename found in a traceback that is not the name of this file (file) Used internally with the debugger for example.

execute_find_callers_filename()

Parameter Descriptions

Name	Type	Default	Description
RETURN	str		filename of the caller, assumed to be the first non PySimpleGUI file

execute_get_editor

Get the path to the editor based on user settings or on PySimpleGUI's global settings

execute_get_editor()

Parameter Descriptions

Name	Type	Default	Description
RETURN	str		Path to the editor

execute_get_results

Get the text results of a previously executed execute call Returns a tuple of the strings (stdout, stderr)

execute_get_results(
    subprocess_id,
    timeout = None
)

Parameter Descriptions

Name	Type	Default	Description
subprocess_id	(subprocess.Popen)		a Popen subprocess ID returned from a previous execute call
timeout	(None or float)	None	Time in fractions of a second to wait. Returns '','' if timeout. Default of None means wait forever

execute_pip_check_package_is_installed

Checks to see if a package is installed. Note that currently the interpreter cannot chosen. The check will happen using the currently running version of Python

execute_pip_check_package_is_installed(
    package
)

Parameter Descriptions

Name	Type	Default	Description
package	str		The name used on the import statement, NOT the name used to pip install

execute_pip_get_pypi_package_version

Returns the newest version number of a package located on PyPI

execute_pip_get_pypi_package_version(
    package
)

Parameter Descriptions

Name	Type	Default	Description
package	str		Name of the package

execute_pip_get_local_package_version

Retturns the version number of a given package that has been pip installed. If a window is provided, then the function will run threaded due to a possible long delay. When the thead completes, they key provided in the paramters will be returned as an event and the value will be the version

execute_pip_get_local_package_version(
    package,
    interpreter = None,
    window = None,
    key = None
)

Parameter Descriptions

Name	Type	Default	Description
interpreter	str	None	The interpreter to use to check. If none specified, then the currently running interpreter is used
key	str or int or tuple or object	None	key that will be sent to Window when operation completes
package	str		The name of the package to get version of
window	Window	None	Optional Window. If provided, the operation is run as a thread and the results passed to the window as an event
RETURN	(str or None)		String with the version number or None is package wasn't found or if a window is provided (the return value wiil lbe sent to window)

execute_pip_install_package

Pip installs a package using the currently running interpreter

execute_pip_install_package(
    package,
    interpreter = None,
    force_reinstall = False,
    upgrade_pip = False
)

Parameter Descriptions

Name	Type	Default	Description
force_reinstall	bool	False	If True package will be uninstalled before installing
interpreter	str	None	The interpreter to use for the install. If none specified, then the currently running interpreter is used
package	str		The name of the package to install
upgrade_pip	bool	False	If True pip will first be upgraded

execute_py_file

Executes a Python file. The interpreter to use is chosen based on this priority order: 1. interpreter_command paramter 2. global setting "-python command-" 3. the interpreter running running PySimpleGUI

execute_py_file(
    pyfile,
    parms = None,
    cwd = None,
    interpreter_command = None,
    wait = False,
    pipe_output = False,
    merge_stderr_with_stdout = True
)

Parameter Descriptions

Name	Type	Default	Description
cwd	str	None	the working directory to use
interpreter_command	str	None	the command used to invoke the Python interpreter
merge_stderr_with_stdout	bool	True	If True then output from the subprocess stderr will be merged with stdout. The result is ALL output will be on stdout.
parms	str	None	parameters to pass on the command line
pipe_output	bool	False	If True then output from the subprocess will be piped. You MUST empty the pipe by calling execute_get_results or your subprocess will block until no longer full
pyfile	str		the file to run
wait	bool	False	the working directory to use
RETURN	(subprocess.Popen) or None		Popen object

execute_py_get_interpreter

Returns Python Interpreter from the system settings. If none found in the settings file then the currently running interpreter is returned.

execute_py_get_interpreter()

Parameter Descriptions

Name	Type	Default	Description
RETURN	str		Full path to python interpreter (uses settings file or sys.executable)

execute_py_get_running_interpreter

Returns the command that is currently running.

execute_py_get_running_interpreter()

Parameter Descriptions

Name	Type	Default	Description
RETURN	str		Full path to python interpreter (uses sys.executable)

execute_restart

Restarts your program. The currently running process is exited and a new one is started. NOTE - this function calls exit and thus will not return

execute_restart(
    your_filename,
    parms = ""
)

Parameter Descriptions

Name	Type	Default	Description
parms	str		Parameters to pass to your program when it's restarted
your_filename	str		Set this parm to file

execute_subprocess_still_running

Returns True is the subprocess ID provided is for a process that is still running

execute_subprocess_still_running(
    subprocess_id
)

Parameter Descriptions

Name	Type	Default	Description
subprocess_id	(subprocess.Popen)		ID previously returned from Exec API calls that indicate this value is returned
RETURN	bool		True if the subproces is running