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

class wads.setup_utils.DiagnosticResult(missing_python_deps: List[str], missing_system_deps: List[Dict[str, str]], missing_env_vars: List[str], warnings: List[str], recommendations: List[str])[source]

Result of dependency diagnostics.

class wads.setup_utils.InstallResult(success: bool, package_name: str, message: str, command_executed: str | None = None)[source]

Result of an installation attempt.

wads.setup_utils.check_environment_variables(pyproject_path: str | Path, verbose: bool = True) → Dict[str, str | None][source]

Check required environment variables from pyproject.toml.

Parameters:

  • pyproject_path – Path to pyproject.toml or directory containing it

  • verbose – Print warnings for missing variables

Returns:

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

wads.setup_utils.check_system_dependency(dep_name: str, dep_ops: Dict, platform: str, verbose: bool = True) → bool[source]

Check if a system dependency is installed using check commands.

Parameters:

  • dep_name – Simplified dependency name

  • dep_ops – Operational metadata for the dependency

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

  • verbose – Print check attempts

Returns:

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

wads.setup_utils.diagnose_setup(pyproject_path: str | Path, check_python: bool = True, check_system: bool = True, check_env: bool = True, platform: str | None = None) → DiagnosticResult[source]

Diagnose missing dependencies and configuration issues.

Parameters:

  • pyproject_path – Path to pyproject.toml or directory containing it

  • check_python – Check Python dependencies

  • check_system – Check system dependencies

  • check_env – Check environment variables

  • platform – Platform identifier (auto-detected if None)

Returns:

DiagnosticResult with comprehensive analysis

wads.setup_utils.get_current_platform() → str[source]

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

Returns:

Platform string compatible with wads configuration

wads.setup_utils.get_installed_pip_packages() → Set[str][source]

Get set of installed pip package names.

Returns:

Set of installed package names (lowercase)

wads.setup_utils.install_python_dependencies(pyproject_path: str | Path, exclude: List[str] | None = None, check_importable: bool = True, upgrade: bool = False, allow_downgrade: bool = False, extras: List[str] | None = None, dry_run: bool = False, verbose: bool = True) → List[InstallResult][source]

Install Python dependencies from pyproject.toml.

Parameters:

  • pyproject_path – Path to pyproject.toml or directory containing it

  • exclude – List of package names to exclude from installation

  • check_importable – Only install if package is not already importable

  • upgrade – Pass –upgrade flag to pip

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

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

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

  • verbose – Print detailed progress information

Returns:

List of InstallResult objects

wads.setup_utils.install_system_dependencies(pyproject_path: str | Path, platform: str | None = None, check_first: bool = True, dry_run: bool = False, verbose: bool = True, interactive: bool = True) → List[InstallResult][source]

Install system dependencies based on pyproject.toml configuration.

This is a wrapper around wads.install_system_deps module.

Parameters:

  • pyproject_path – Path to pyproject.toml or directory containing it

  • platform – Platform identifier (auto-detected if None)

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

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

  • verbose – Print detailed progress information

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

Returns:

List of InstallResult objects

wads.setup_utils.is_package_importable(package_name: str) → bool[source]

Check if a Python package can be imported.

Parameters:

package_name – Name of the package to check

Returns:

True if the package is importable

wads.setup_utils.print_diagnostic_report(result: DiagnosticResult)[source]

Print a formatted diagnostic report.

Parameters:

result – DiagnosticResult to display