Core Utilities API

tdmake_gui_wrapper.core

Core utilities for process execution and 3dm binary discovery.

This module centralizes platform-specific behavior used by the GUI layer:

• locating the 3dm executable
• resolving configuration locations
• running commands with streamed or blocking output collection
• optionally adding packaged install directories to the user PATH

find_3dm_binary

find_3dm_binary() -> str | None

Locate the 3dm binary using environment and platform heuristics.

Search order:

1. THREE_DM_PATH environment variable (file or directory).
2. PATH lookup via :func:shutil.which.
3. Common installation directories on Linux, macOS, and Windows.

Returns:

Type	Description
str or None	Absolute executable path if found, otherwise None.

get_3dmake_config_dir

get_3dmake_config_dir() -> Path

Return the active 3dmake configuration directory.

Resolution precedence:

1. THREEDMAKE_CONFIG_DIR environment variable
2. Platform default location

Returns:

Type	Description
Path	Absolute or user-home-relative configuration path.

get_3dmake_defaults_toml_path

get_3dmake_defaults_toml_path() -> Path

Return the expected defaults.toml path for 3dmake.

Returns:

Type	Description
Path	Path formed by get_3dmake_config_dir() / 'defaults.toml'.

get_packaged_executable_dir

get_packaged_executable_dir() -> Path | None

Return the directory of the packaged executable, when available.

Returns:

Type	Description
Path or None	The resolved parent directory of sys.executable when running from a frozen/packaged build (for example, PyInstaller). Returns None when running from source.

install_directory_to_user_path

install_directory_to_user_path(target_dir: Path) -> tuple[bool, str]

Add an installation directory to the current user's PATH.

Parameters:

Name	Type	Description	Default
target_dir	Path	Directory to add.	required

Returns:

Type	Description
tuple[bool, str]	(success, message) describing whether the operation completed.

is_directory_on_path

is_directory_on_path(target_dir: Path) -> bool

Check whether a directory already exists on PATH.

Parameters:

Name	Type	Description	Default
target_dir	Path	Directory to check.	required

Returns:

Type	Description
bool	True if the normalized target directory matches an entry in PATH; otherwise False.

launch_in_terminal

launch_in_terminal(cmd: str | Sequence[str], cwd: str | None = None) -> bool

Launch a command in a new terminal window.

Parameters:

Name	Type	Description	Default
cmd	str or sequence of str	Command to execute. An argument list is quoted safely for the target shell.	required
cwd	str or None	Directory the terminal should start in.	None

Returns:

Type	Description
bool	True when a compatible terminal launcher is found and started; False when no launcher is available or the command is empty.

resolve_3dm_binary_path

resolve_3dm_binary_path(path_value: str) -> str | None

Resolve a user-supplied path to a concrete 3dm executable.

Parameters:

Name	Type	Description	Default
path_value	str	Path-like string that may point directly to a binary or to a directory containing one.	required

Returns:

Type	Description
str or None	Absolute path to a detected 3dm binary, or None if no suitable executable can be found.

run_command_async async

run_command_async(cmd: str | Sequence[str], cwd: str | None = None, env: dict[str, str] | None = None) -> AsyncIterator[str]

Run a command and asynchronously stream process output lines.

Parameters:

Name	Type	Description	Default
cmd	str or sequence of str	An argument list is executed directly with no shell (preferred, immune to quoting/injection problems). A plain string is run through the shell for backwards compatibility.	required
env	dict or None	Extra environment variables merged over the current environment.	None
cwd	str or None	Working directory used for subprocess execution.	None

Yields:

Type	Description
str	Output records prefixed with [stdout] or [stderr]. The final record is always [done] <returncode>.

Notes

Output is multiplexed through an asyncio.Queue so stdout and stderr can be consumed without blocking each other.

run_command_sync

run_command_sync(cmd: str | Sequence[str], cwd: str | None = None) -> tuple[str, str, int]

Run a shell command synchronously and collect captured output.

Parameters:

Name	Type	Description	Default
cmd	str	Shell command to execute.	required
cwd	str or None	Working directory used for command execution.	None

Returns:

Type	Description
tuple[str, str, int]	(stdout, stderr, returncode) in text mode.

options: members: true show_root_full_path: false