fastsandpm.install API

Install and manage dependencies into a local library.

This module provides functionality to build and install library dependencies from resolved dependency definitions. It handles installation of different candidate types:

  • Git Candidates: Clones repositories and checks out specified commits with smart directory replacement for dirty/incorrect repos when clean=True.

  • Path Candidates: Creates symlinks to local directories with smart updates when target already exists.

  • PackageIndex Candidates: Not yet implemented.

The main entry point is library_from_manifest() which resolves dependencies from a manifest and installs them into a destination directory. For more direct control, use build_library() with a pre-built dependency definition.

After all dependencies are installed, a library.f file is created that lists the file lists of each dependency in dependency-sorted order, allowing the entire library to be included via a single “-F library.f” directive.

Installation Behavior:

  • Non-existent directories: Cloned/created fresh.

  • Existing with correct state: Updated to specified versions (fetch+checkout for git).

  • Existing with incorrect state: Removed and replaced if clean=True, otherwise skipped with a warning.

  • Dirty repositories or non-git directories: Handled based on the clean flag.

Example

>>> manifest = get_manifest("path/to/manifest.toml")
>>> library_from_manifest(manifest, pathlib.Path("lib/"))

Functions

fastsandpm.install.build_library(definition: ResolveResult, dest: Path, clean: bool = True) → bool[source]

Build a library candidate from a manifest definition.

The library will be placed in the destination directory with each dependency having it’s own directory. A library.f file list will be created which points to the root file-list of each dependency.

For Git Candidates: - If the directory doesn’t exist, it will be cloned and checked out to the correct commit. - If the directory is a git repo with the correct remote and no local changes, it will be checked out to the correct commit. Otherwise, it will be deleted and cloned and checked out to the correct commit. - If the directory is a git repo with an incorrect remote and no local changes or commits, it will be deleted and the new repo cloned and checked out to the correct commit. - If the directory is a git repo with local changes or un-pushed commits, it will be deleted and replaced with the new repo cloned and checked out to the correct commit, if and only if clean is True. Otherwise, a warning will be logged and the method will return False after all other dependencies have been installed. - If the directory is not a git repo, it will be deleted and replaced with the new repo if and only if clean is True. Otherwise, a warning will be logged and the method will return False after all other dependencies have been installed.

For Path Candidates: - If the directory doesn’t exist, a symlink will be created to the correct path. - If the directory exists and is a symlink, the symlink will be updated to the correct path. - If the directory exists and is not a symlink and clean is True, the directory will be deleted and replaced with a symlink to the correct path. - Otherwise a warning will be logged and the method will return False after all other dependencies have been installed.

For PackageIndex Candidates: - NOT CURRENTLY IMPLEMENTED

After all of the candidates have been installed, the library.f file list will be created. This is done by creating an ordered list of dependencies such that any dependency whose manifest includes another dependency appears after that dependency. The library.f file list will then be created such that it is a series of “-F” relative includes which point to the ‘flist’ files of each dependency (if they have a manifest) or the the ‘{name}.f’ of a dependency without a manifest.

Parameters:

  • definition – The resolved dependency definition containing packages and their dependency graph.

  • dest – The destination directory for the library.

  • clean – If True, clean the destination directory before building the library.

Returns:

True if all of the library dependencies were successfully updated or installed. Otherwise False.

fastsandpm.install.library_from_manifest(manifest: Manifest, dest: Path, optional_deps: list[str] | None = None, clean: bool = True) → None[source]

Build a library of dependencies from a manifest.

The library will be placed in the destination directory with each dependency having it’s own directory. A library.f file list will be created which points to the root file-list of each dependency.

Parameters:

  • manifest – The manifest to build the library from.

  • dest – The destination directory for the library.

  • optional_dep – Optional dependency groups to include in the library.

  • clean – If True, clean existing directories when conflicts occur.

Raises:

resolvelib.ResolutionImpossible – If no compatible resolution exists.