Synchronous API

This section details the synchronous components of the pipmaster library, primarily found within the pipmaster.package_manager module.

Synchronous Package Manager using pip.

Provides a class and functions to interact with pip for package management within the current environment or a specified Python environment.

Author: ParisNeo Created: 01/04/2024 Last Updated: 23/04/2025

class pipmaster.package_manager.PackageManager(python_executable: str | None = None, pip_command_base: List[str] | None = None)[source]

Bases: object

Manages Python package installations and queries using pip.

Allows targeting different Python environments via the python_executable parameter.

__init__(python_executable: str | None = None, pip_command_base: List[str] | None = None)[source]

Initializes the PackageManager.

Parameters:

python_executable (str, optional) – Path to the Python executable of the target environment. Defaults to sys.executable (current env).
pip_command_base (List[str], optional) – Advanced: Override the base command list (e.g., [‘/custom/python’, ‘-m’, ‘pip’]). Overrides python_executable. Use with caution.

install(package: str, index_url: str | None = None, force_reinstall: bool = False, upgrade: bool = True, extra_args: List[str] | None = None, dry_run: bool = False, verbose: bool = False) → bool[source]

Installs or upgrades a single package.

Parameters:

package (str) – The package name, optionally with version specifier.
index_url (str, optional) – Custom index URL.
force_reinstall (bool) – If True, use –force-reinstall.
upgrade (bool) – If True, use –upgrade (pip default behavior).
extra_args (List[str], optional) – Additional arguments for pip.
dry_run (bool) – If True, simulate the command.
verbose (bool) – If True, show pip’s output directly (if not capturing).

Returns:

True on success or successful dry run, False otherwise.

Return type:

bool

install_if_missing(package: str, version: str | None = None, enforce_version: bool = False, always_update: bool = False, index_url: str | None = None, extra_args: List[str] | None = None, version_specifier: str | None = None, dry_run: bool = False, verbose: bool = False) → bool[source]

Installs a package conditionally based on presence and version requirements.

Parameters:

package (str) – Name of the package (e.g., “numpy”). Can include specifier.
version (str, optional) – DEPRECATED. Use version_specifier.
enforce_version (bool) – DEPRECATED. Use version_specifier=”==x.y.z”.
always_update (bool) – If True and package is installed, update to latest.
index_url (str, optional) – Custom index URL for pip.
extra_args (List[str], optional) – Additional arguments for pip.
version_specifier (str, optional) – A PEP 440 specifier (e.g., “>=1.2”, “==1.3.4”). Takes precedence over version/enforce_version.
dry_run (bool) – If True, simulate the command.
verbose (bool) – If True, show pip’s output directly (if not capturing).

Returns:

True if installation was successful, not needed, or dry run ok. False otherwise.

Return type:

bool

install_multiple(packages: List[str], index_url: str | None = None, force_reinstall: bool = False, upgrade: bool = True, extra_args: List[str] | None = None, dry_run: bool = False, verbose: bool = False) → bool[source]: Installs or upgrades multiple packages.

install_multiple_if_not_installed(packages: List[str], index_url: str | None = None, extra_args: List[str] | None = None, dry_run: bool = False, verbose: bool = False) → bool[source]: Installs multiple packages only if they are not already installed. Does not check version compatibility, only presence. Use ensure_packages for that.

install_version(package: str, version: str, index_url: str | None = None, force_reinstall: bool = False, extra_args: List[str] | None = None, dry_run: bool = False) → bool[source]: Installs a specific version of a package.

is_installed(package_name: str, version_specifier: str | None = None) → bool[source]

Checks if a package is installed, optionally checking version compatibility.

Parameters:

package_name (str) – The name of the package (without specifier).
version_specifier (str, optional) – A PEP 440 specifier (e.g., “>=1.2”). If provided, checks version compatibility.

Returns:

True if installed (and meets specifier if provided), False otherwise.

Return type:

bool

get_installed_version(package_name: str) → str | None[source]: Gets the installed version of a package using importlib.metadata.

get_current_package_version(package_name: str) → str | None[source]

Gets the installed version of a package. Alias for get_installed_version.

This method provides a more explicit name for querying the version of a package that is currently installed in the target environment.

Parameters:: package_name (str) – The name of the package.
Returns:: The installed version string or None if the package is not found.
Return type:: Optional[str]

is_version_compatible(package_name: str, version_specifier: str, _dist: Distribution | None = None) → bool[source]

Checks if the installed version of a package meets a version specifier.

Parameters:

package_name (str) – The name of the package.
version_specifier (str) – A PEP 440 version specifier string (e.g., “>=1.0”).
_dist (Distribution, optional) – Pre-fetched distribution object.

Returns:

True if installed and meets specifier, False otherwise.

Return type:

bool

get_package_info(package_name: str) → str | None[source]: Runs pip show to get package details.

install_or_update(package: str, index_url: str | None = None, force_reinstall: bool = False, extra_args: List[str] | None = None, dry_run: bool = False) → bool[source]: Installs a package if missing, or updates it if installed.

uninstall(package: str, extra_args: List[str] | None = None, dry_run: bool = False, verbose: bool = False) → bool[source]: Uninstalls a single package.

uninstall_multiple(packages: List[str], extra_args: List[str] | None = None, dry_run: bool = False, verbose: bool = False) → bool[source]: Uninstalls multiple packages.

install_or_update_multiple(packages: List[str], index_url: str | None = None, force_reinstall: bool = False, extra_args: List[str] | None = None, dry_run: bool = False) → bool[source]: Installs or updates multiple packages.

install_edit(path: str, index_url: str | None = None, extra_args: List[str] | None = None, dry_run: bool = False) → bool[source]: Installs a package in editable mode.

install_requirements(requirements_file: str, index_url: str | None = None, extra_args: List[str] | None = None, dry_run: bool = False) → bool[source]: Installs packages from a requirements file.

check_vulnerabilities(package_name: str | None = None, requirements_file: str | None = None, extra_args: List[str] | None = None) → Tuple[bool, str][source]

Checks for vulnerabilities using pip-audit. Requires ‘pip-audit’ to be installed.

Checks the current environment targeted by this PackageManager instance. Provide EITHER package_name OR requirements_file to check specific targets, otherwise the whole environment is checked.

Parameters:

package_name (str, optional) – Check a specific package.
requirements_file (str, optional) – Check dependencies in a requirements file.
extra_args (List[str], optional) – Additional arguments for pip-audit.

Returns:

(vulnerabilities_found, audit_output_or_error): Note: vulnerabilities_found is True if pip-audit finds issues.

Return type:

Tuple[bool, str]

Ensures that required packages are installed and meet version requirements.

This is the most efficient method for managing a set of dependencies, as it checks all requirements first and then performs a single ‘pip install’ command for only those packages that need to be installed or updated.

Parameters:

requirements (Union[str, Dict[str, Optional[str]], List[str]]) –
- str: A single package requirement string (e.g., “requests>=2.25”).
- List[str]: A list of package requirement strings.
- Dict[str, Optional[str]]: A dictionary mapping package names to optional PEP 440 version specifiers.
index_url (str, optional) – Custom index URL for installations.
extra_args (List[str], optional) – Additional arguments for the pip install command.
dry_run (bool) – If True, simulate installations without making changes.
verbose (bool) – If True, show pip’s output directly during installation.

Returns:

True if all requirements were met initially or successfully: resolved/installed/updated, False if any installation failed.

Return type:

bool

pipmaster.package_manager.get_pip_manager(python_executable: str | None = None) → PackageManager[source]

Gets a PackageManager instance, potentially targeting a specific Python environment.

Parameters:: python_executable (str, optional) – Path to the Python executable of the target environment. Defaults to sys.executable (current env).
Returns:: An instance configured for the target environment.
Return type:: PackageManager

pipmaster.package_manager.install(package: str, index_url: str | None = None, force_reinstall: bool = False, upgrade: bool = True, extra_args: List[str] | None = None, dry_run: bool = False, verbose: bool = False) → bool[source]

Installs or upgrades a single package using the default PackageManager.

Parameters:

package (str) – The package name, optionally with version specifier.
index_url (str, optional) – Custom index URL.
force_reinstall (bool) – If True, use –force-reinstall.
upgrade (bool) – If True, use –upgrade (pip default behavior).
extra_args (List[str], optional) – Additional arguments for pip.
dry_run (bool) – If True, simulate the command.
verbose (bool) – If True, shows pip’s output directly (if not capturing).

Returns:

True on success or successful dry run, False otherwise.

Return type:

bool

(Delegates to PackageManager.install)

pipmaster.package_manager.install_if_missing(package: str, version: str | None = None, enforce_version: bool = False, always_update: bool = False, index_url: str | None = None, extra_args: List[str] | None = None, version_specifier: str | None = None, dry_run: bool = False, verbose: bool = False) → bool[source]

Installs a package conditionally using the default PackageManager.

Parameters:

package (str) – Name of the package (e.g., “numpy”). Can include specifier.
version (str, optional) – DEPRECATED. Use version_specifier.
enforce_version (bool) – DEPRECATED. Use version_specifier=”==x.y.z”.
always_update (bool) – If True and package is installed, update to latest.
index_url (str, optional) – Custom index URL for pip.
extra_args (List[str], optional) – Additional arguments for pip.
version_specifier (str, optional) – A PEP 440 specifier (e.g., “>=1.2”, “==1.3.4”).
dry_run (bool) – If True, simulate the command.
verbose (bool) – If True, shows pip’s output directly (if not capturing).

Returns:

True if installation was successful, not needed, or dry run ok. False otherwise.

Return type:

bool

(Delegates to PackageManager.install_if_missing)

pipmaster.package_manager.install_edit(path: str, index_url: str | None = None, extra_args: List[str] | None = None, dry_run: bool = False) → bool[source]

Installs a package in editable mode using the default PackageManager.

Parameters:

path (str) – Path to the local package source directory.
index_url (str, optional) – Custom index URL.
extra_args (List[str], optional) – Additional arguments for pip.
dry_run (bool) – If True, simulate the command.

Returns:

True on success or successful dry run, False otherwise.

Return type:

bool

(Delegates to PackageManager.install_edit)

pipmaster.package_manager.install_requirements(requirements_file: str, index_url: str | None = None, extra_args: List[str] | None = None, dry_run: bool = False) → bool[source]

Installs packages from a requirements file using the default PackageManager.

Parameters:

requirements_file (str) – Path to the requirements file.
index_url (str, optional) – Custom index URL.
extra_args (List[str], optional) – Additional arguments for pip.
dry_run (bool) – If True, simulate the command.

Returns:

True on success or successful dry run, False otherwise.

Return type:

bool

(Delegates to PackageManager.install_requirements)

pipmaster.package_manager.install_multiple(packages: List[str], index_url: str | None = None, force_reinstall: bool = False, upgrade: bool = True, extra_args: List[str] | None = None, dry_run: bool = False, verbose: bool = False) → bool[source]

Installs or upgrades multiple packages using the default PackageManager.

Args:
packages (List[str]): A list of package names/specifiers. index_url (str, optional): Custom index URL. force_reinstall (bool): If True, use –force-reinstall. upgrade (bool): If True, use –upgrade. extra_args (List[str], optional): Additional arguments for pip. dry_run (bool): If True, simulate the command. verbose (bool): If True, show pip’s output.

Returns:: True on success or successful dry run, False otherwise.
Return type:: bool

(Delegates to PackageManager.install_multiple)

pipmaster.package_manager.install_multiple_if_not_installed(packages: List[str], index_url: str | None = None, extra_args: List[str] | None = None, dry_run: bool = False, verbose: bool = False) → bool[source]

Installs multiple packages only if they are not already installed, using the default PackageManager. Does not check version compatibility, only presence.

Parameters:

packages (List[str]) – A list of package names/specifiers to check/install.
index_url (str, optional) – Custom index URL for installing missing packages.
extra_args (List[str], optional) – Additional arguments for pip install command.
dry_run (bool) – If True, simulate the command for missing packages.
verbose (bool) – If true, shows information about packages being skipped.

Returns:

True if all originally missing packages installed successfully or dry run ok, False otherwise.

Return type:

bool

(Delegates to PackageManager.install_multiple_if_not_installed)

pipmaster.package_manager.install_version(package: str, version: str, index_url: str | None = None, force_reinstall: bool = False, extra_args: List[str] | None = None, dry_run: bool = False) → bool[source]

Installs a specific version of a package using the default PackageManager.

Parameters:

package (str) – The name of the package.
version (str) – The exact version string to install (e.g., “1.2.3”).
index_url (str, optional) – Custom index URL.
force_reinstall (bool) – If True, use –force-reinstall.
extra_args (List[str], optional) – Additional arguments for pip.
dry_run (bool) – If True, simulate the command.

Returns:

True on success or successful dry run, False otherwise.

Return type:

bool

(Delegates to PackageManager.install_version)

pipmaster.package_manager.is_installed(package_name: str, version_specifier: str | None = None) → bool[source]

Checks if a package is installed in the current environment, optionally checking version.

Parameters:

package_name (str) – The name of the package (without specifier).
version_specifier (str, optional) – A PEP 440 specifier (e.g., “>=1.2”).

Returns:

True if installed (and meets specifier if provided), False otherwise.

Return type:

bool

(Delegates to PackageManager.is_installed)

pipmaster.package_manager.get_installed_version(package_name: str) → str | None[source]

Gets the installed version of a package in the current environment.

Parameters:: package_name (str) – The name of the package.
Returns:: The installed version string or None if not found.
Return type:: Optional[str]

(Delegates to PackageManager.get_installed_version)

pipmaster.package_manager.get_current_package_version(package_name: str) → str | None[source]

Gets the installed version of a package in the current environment. Alias for get_installed_version.

Parameters:: package_name (str) – The name of the package.
Returns:: The installed version string or None if not found.
Return type:: Optional[str]

(Delegates to PackageManager.get_current_package_version)

pipmaster.package_manager.is_version_compatible(package_name: str, version_specifier: str) → bool[source]

Checks if the installed version in the current environment meets a version specifier.

Parameters:

package_name (str) – The name of the package.
version_specifier (str) – A PEP 440 version specifier string (e.g., “>=1.0”).

Returns:

True if installed and meets specifier, False otherwise.

Return type:

bool

(Delegates to PackageManager.is_version_compatible)

pipmaster.package_manager.get_package_info(package_name: str) → str | None[source]

Runs pip show for a package in the current environment.

Parameters:: package_name (str) – The name of the package.
Returns:: The output of pip show or None on error.
Return type:: Optional[str]

(Delegates to PackageManager.get_package_info)

pipmaster.package_manager.install_or_update(package: str, index_url: str | None = None, force_reinstall: bool = False, extra_args: List[str] | None = None, dry_run: bool = False, verbose: bool = False) → bool[source]

Installs a package if missing, or updates it if installed, using the default PackageManager.

Parameters:

package (str) – The package name, optionally with version specifier.
index_url (str, optional) – Custom index URL.
force_reinstall (bool) – If True, use –force-reinstall during update/install.
extra_args (List[str], optional) – Additional arguments for pip.
dry_run (bool) – If True, simulate the command.
verbose (bool) – If True, shows pip’s output.

Returns:

True on success or successful dry run, False otherwise.

Return type:

bool

(Delegates to PackageManager.install_or_update)

pipmaster.package_manager.uninstall(package: str, extra_args: List[str] | None = None, dry_run: bool = False, verbose: bool = False) → bool[source]

Uninstalls a single package from the current environment.

Parameters:

package (str) – The name of the package to uninstall.
extra_args (List[str], optional) – Additional arguments for pip uninstall.
dry_run (bool) – If True, simulate the command.
verbose (bool) – If True, show pip’s output.

Returns:

True on success or successful dry run, False otherwise.

Return type:

bool

(Delegates to PackageManager.uninstall)

pipmaster.package_manager.uninstall_multiple(packages: List[str], extra_args: List[str] | None = None, dry_run: bool = False, verbose: bool = False) → bool[source]

Uninstalls multiple packages from the current environment.

Parameters:

packages (List[str]) – A list of package names to uninstall.
extra_args (List[str], optional) – Additional arguments for pip uninstall.
dry_run (bool) – If True, simulate the command.
verbose (bool) – If True, show pip’s output.

Returns:

True on success or successful dry run, False otherwise.

Return type:

bool

(Delegates to PackageManager.uninstall_multiple)

pipmaster.package_manager.install_or_update_multiple(packages: List[str], index_url: str | None = None, force_reinstall: bool = False, extra_args: List[str] | None = None, dry_run: bool = False, verbose: bool = False) → bool[source]

Installs or updates multiple packages using the default PackageManager.

Parameters:

packages (List[str]) – A list of package names/specifiers.
index_url (str, optional) – Custom index URL.
force_reinstall (bool) – If True, use –force-reinstall.
extra_args (List[str], optional) – Additional arguments for pip.
dry_run (bool) – If True, simulate the command.
verbose (bool) – If True, show pip’s output.

Returns:

True on success or successful dry run, False otherwise.

Return type:

bool

(Delegates to PackageManager.install_or_update_multiple)

pipmaster.package_manager.check_vulnerabilities(package_name: str | None = None, requirements_file: str | None = None, extra_args: List[str] | None = None) → Tuple[bool, str][source]

Checks for vulnerabilities in the current environment using pip-audit.

Requires ‘pip-audit’ to be installed (e.g., pip install pipmaster[audit]). Provide EITHER package_name OR requirements_file for specific checks, otherwise the whole environment is checked.

Parameters:

package_name (str, optional) – Check a specific package (support limited).
requirements_file (str, optional) – Check dependencies in a requirements file.
extra_args (List[str], optional) – Additional arguments for pip-audit.

Returns:

(vulnerabilities_found, audit_output_or_error)

Return type:

Tuple[bool, str]

(Delegates to PackageManager.check_vulnerabilities)

pipmaster.package_manager.ensure_packages(requirements: Dict[str, str | None] | List[str], index_url: str | None = None, extra_args: List[str] | None = None, dry_run: bool = False, verbose: bool = False) → bool[source]

Ensures packages meet requirements in the current environment using the default PackageManager.

Checks each requirement from the dictionary or list. Installs or updates packages efficiently in a single batch if needed.

Parameters:

requirements (Union[Dict[str, Optional[str]], List[str]]) – Either a dictionary mapping package names to optional PEP 440 version specifiers (e.g., {“requests”: “>=2.25”, “numpy”: None}) OR a list of package strings (e.g., [“requests>=2.25”, “numpy”]). If a list item has no specifier, the latest version is assumed.
index_url (str, optional) – Custom index URL for installations.
extra_args (List[str], optional) – Additional arguments for the pip install command.
dry_run (bool) – If True, simulate installations without making changes.
verbose (bool) – If True, show pip’s output directly during installation.

Returns:

True if all requirements were met initially or successfully resolved,: False if any installation failed.

Return type:

bool

(Delegates to PackageManager.ensure_packages)

pipmaster.package_manager.is_version_higher(package_name: str, required_version: str) → bool[source]: DEPRECATED: Use is_version_compatible(package, f’>={required_version}’)

pipmaster.package_manager.is_version_exact(package_name: str, required_version: str) → bool[source]: DEPRECATED: Use is_version_compatible(package, f’=={required_version}’)

class pipmaster.package_manager.UvPackageManager(environment_path: str | None = None)[source]

Bases: object

Manages Python environments and packages using uv. Requires the ‘uv’ executable to be in the system’s PATH.

__init__(environment_path: str | None = None)[source]

Initializes the UvPackageManager.

Parameters:: environment_path (str, optional) – The path to the uv virtual environment. If not provided, some methods like install/uninstall will fail until an environment is created and targeted.

create_env(path: str, python_version: str | None = None) → bool[source]: Creates a new virtual environment at the specified path.

install(package: str, extra_args: List[str] | None = None, verbose: bool = False) → bool[source]: Installs a package into the configured environment.

install_multiple(packages: List[str], extra_args: List[str] | None = None, verbose: bool = False) → bool[source]: Installs multiple packages into the configured environment.

uninstall(package: str, extra_args: List[str] | None = None, verbose: bool = False) → bool[source]: Uninstalls a package from the configured environment.

run_with_uvx(command: List[str], verbose: bool = False) → bool[source]

Executes a tool in a temporary environment using uv tool run (the long form of uvx), which is the correct command for this purpose.

Parameters:

command (List[str]) – The command and its arguments. The first element is assumed to be the tool/package name.
verbose (bool) – If True, show command’s output on the console.

class pipmaster.package_manager.CondaPackageManager(environment_name_or_path: str | None = None)[source]: Bases: object

pipmaster.package_manager.get_uv_manager(environment_path: str | None = None) → UvPackageManager[source]

Gets a UV Package Manager instance.

Parameters:: environment_path (str, optional) – The path to the uv virtual environment to be managed.
Returns:: An instance configured for the specified environment.
Return type:: UvPackageManager

pipmaster.package_manager.get_conda_manager(environment_name_or_path: str | None = None) → Any[source]: Gets a Conda Package Manager instance (Not Implemented).

Note

Many functions documented here (like install, is_installed, etc.) are also exposed directly at the top level (e.g., pipmaster.install). These are convenience wrappers around the methods of a default PackageManager instance targeting the current Python environment. Use the top-level imports for simplicity or instantiate PackageManager directly (often via get_pip_manager()) for more control, especially when targeting different environments.