wads.setup_utils

Utilities for setting up packages based on pyproject.toml configuration.

This module provides tools for users to:

• Install Python dependencies with various options

• Install system dependencies based on OS and toml specs

• Validate environment variables

• Diagnose missing dependencies and provide instructions

Functions

check_environment_variables(pyproject_path)	Check required environment variables from pyproject.toml.
check_system_dependency(dep_name, dep_ops, ...)	Check if a system dependency is installed using check commands.
diagnose_setup(pyproject_path[, ...])	Diagnose missing dependencies and configuration issues.
get_current_platform()	Get current platform identifier (linux, macos, windows).
get_installed_pip_packages()	Get set of installed pip package names.
install_python_dependencies(pyproject_path)	Install Python dependencies from pyproject.toml.
install_system_dependencies(pyproject_path)	Install system dependencies based on pyproject.toml configuration.
is_package_importable(package_name)	Check if a Python package can be imported.
print_diagnostic_report(result)	Print a formatted diagnostic report.

Classes

DiagnosticResult(missing_python_deps, ...)	Result of dependency diagnostics.
InstallResult(success, package_name, message)	Result of an installation attempt.

class wads.setup_utils.DiagnosticResult(missing_python_deps, missing_system_deps, missing_env_vars, warnings, recommendations)

Bases: object

Result of dependency diagnostics.

class wads.setup_utils.InstallResult(success, package_name, message, command_executed=None)

Bases: object

Result of an installation attempt.

wads.setup_utils.check_environment_variables(pyproject_path, verbose=True)

Check required environment variables from pyproject.toml.

Parameters:

• pyproject_path (str | Path) – Path to pyproject.toml or directory containing it

• verbose (bool) – Print warnings for missing variables

Return type:

Dict[str, Optional[str]]

Returns:

Dict mapping variable names to their values (None if missing)

wads.setup_utils.check_system_dependency(dep_name, dep_ops, platform, verbose=True)

Check if a system dependency is installed using check commands.

Parameters:

• dep_name (str) – Simplified dependency name

• dep_ops (Dict) – Operational metadata for the dependency

• platform (str) – Platform identifier (linux, macos, windows)

• verbose (bool) – Print check attempts

Return type:

bool

Returns:

True if dependency is installed (or no check command available)

wads.setup_utils.diagnose_setup(pyproject_path, check_python=True, check_system=True, check_env=True, platform=None)

Diagnose missing dependencies and configuration issues.

Parameters:

• pyproject_path (str | Path) – Path to pyproject.toml or directory containing it

• check_python (bool) – Check Python dependencies

• check_system (bool) – Check system dependencies

• check_env (bool) – Check environment variables

• platform (Optional[str]) – Platform identifier (auto-detected if None)

Return type:

DiagnosticResult

Returns:

DiagnosticResult with comprehensive analysis

wads.setup_utils.get_current_platform()

Get current platform identifier (linux, macos, windows).

Return type:

str

Returns:

Platform string compatible with wads configuration

wads.setup_utils.get_installed_pip_packages()

Get set of installed pip package names.

Return type:

Set[str]

Returns:

Set of installed package names (lowercase)

wads.setup_utils.install_python_dependencies(pyproject_path, exclude=None, check_importable=True, upgrade=False, allow_downgrade=False, extras=None, dry_run=False, verbose=True)

Install Python dependencies from pyproject.toml.

Parameters:

• pyproject_path (str | Path) – Path to pyproject.toml or directory containing it

• exclude (Optional[List[str]]) – List of package names to exclude from installation

• check_importable (bool) – Only install if package is not already importable

• upgrade (bool) – Pass –upgrade flag to pip

• allow_downgrade (bool) – Allow pip to downgrade packages (adds –force-reinstall)

• extras (Optional[List[str]]) – List of extras to install (e.g., [‘dev’, ‘test’])

• dry_run (bool) – If True, only show what would be installed

• verbose (bool) – Print detailed progress information

Return type:

List[InstallResult]

Returns:

List of InstallResult objects

wads.setup_utils.install_system_dependencies(pyproject_path, platform=None, check_first=True, dry_run=False, verbose=True, interactive=True)

Install system dependencies based on pyproject.toml configuration.

This is a wrapper around wads.install_system_deps module.

Parameters:

• pyproject_path (str | Path) – Path to pyproject.toml or directory containing it

• platform (Optional[str]) – Platform identifier (auto-detected if None)

• check_first (bool) – Use check commands to verify if already installed (ignored in dry_run)

• dry_run (bool) – If True, only show what would be installed

• verbose (bool) – Print detailed progress information

• interactive (bool) – Ask for confirmation before installing (not yet implemented)

Return type:

List[InstallResult]

Returns:

List of InstallResult objects

wads.setup_utils.is_package_importable(package_name)

Check if a Python package can be imported.

Parameters:

package_name (str) – Name of the package to check

Return type:

bool

Returns:

True if the package is importable

wads.setup_utils.print_diagnostic_report(result)

Print a formatted diagnostic report.

Parameters:

result (DiagnosticResult) – DiagnosticResult to display