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) -> bool

Launch a command in a new terminal window.

Parameters:

Name	Type	Description	Default
cmd	str	Command string to execute.	required

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, cwd: str | None = None) -> AsyncIterator[str]

Run a shell command and asynchronously stream process output lines.

Parameters:

Name	Type	Description	Default
cmd	str	Shell command to execute.	required
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, 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