fastsandpm.dependencies.candidates API

Candidate generation for dependency resolution.

This module provides classes representing dependency candidates and factory functions to generate candidates from requirements. Candidates represent concrete versions of dependencies that can satisfy requirements.

Classes:

Candidate: Abstract base class for all candidate types.
PackageIndexCandidate: Candidate from a package index registry.
PathCandidate: Candidate from a local filesystem path.
GitCandidate: Candidate from a git repository.

Functions:

candidate_factory(): Singledispatch function to create candidates from requirements.

Functions

fastsandpm.dependencies.candidates.candidate_factory(req: PackageIndexRequirement, registries: Registries) → Generator[PackageIndexCandidate, None, None]

fastsandpm.dependencies.candidates.candidate_factory(req: PathRequirement, registries: Registries) → Generator[PathCandidate, None, None]

fastsandpm.dependencies.candidates.candidate_factory(req: GitRequirement, registries: Registries) → Generator[GitCandidate, None, None]

Generate candidates from a requirement using available registries.

This is a singledispatch function that dispatches to specialized implementations based on the requirement type. Each implementation generates zero or more candidates that could potentially satisfy the requirement.

Parameters:

req – The requirement to generate candidates for.
registries – The available registries to search for candidates.

Yields:

Candidate objects that could satisfy the requirement.

Note

The base implementation yields no candidates. Specialized implementations are registered for each concrete requirement type through the singledispatch.

Note

Package index registries are not yet implemented, so this currently yields no candidates.

Classes

class fastsandpm.dependencies.candidates.Candidate(name: str, version: LibraryVersion | None)[source]

Bases: ABC

Abstract base class for dependency resolution candidates.

A candidate represents a concrete version of a dependency that can potentially satisfy one or more requirements. During dependency resolution, candidates are generated from requirements and evaluated for compatibility.

abstractmethod get_manifest() → Manifest | None[source]

Retrieve the manifest for this candidate.

Returns:: The parsed Manifest object for this candidate, or None if no manifest exists or cannot be retrieved.

Check if this candidate satisfies the given requirement.

A candidate satisfies a requirement when:

The requirement name and candidate name match
If the requirement specifies a version, the candidate’s version matches

Parameters:: requirement – The requirement to check against.
Returns:: True if this candidate satisfies the requirement, False otherwise.

name: str: The name of the dependency package.

version: LibraryVersion | None: The semantic version of this candidate, or None if not versioned.

class fastsandpm.dependencies.candidates.GitCandidate(name: str, version: LibraryVersion | None, remote: str, commit_hash: str, corresponding_heads: frozenset[str], corresponding_tags: frozenset[str])[source]

Bases: Candidate

A candidate from a git repository.

Git candidates represent dependencies available from remote git repositories. They are identified by a commit hash and include metadata about corresponding branches and tags for that commit.

get_manifest() → Manifest | None[source]

Retrieve the manifest for this git candidate.

Results are cached by (remote, commit_hash) to avoid repeated network calls during dependency resolution. First attempts to fetch only the manifest file using the hosting provider’s API (GitHub/GitLab), which is significantly faster than a full clone. If that fails, falls back to a full clone.

Returns:: The parsed Manifest object, or None if no manifest exists or fetching fails.

Check if this git candidate satisfies the given requirement.

A git candidate satisfies a requirement when:

The requirement name and candidate name match
If the requirement specifies a version, the candidate’s version matches
For PackageIndexRequirement: only if no specific index is required
PathRequirement: never satisfied by git candidates
For CommitGitRequirement: commit hash matches (prefix match allowed)
For BranchGitRequirement: candidate’s heads include the required branch
For TaggedGitRequirement: candidate’s tags include the required tag
For VersionedGitRequirement: any tag satisfies the version constraint

Parameters:: requirement – The requirement to check against.
Returns:: True if this candidate satisfies the requirement, False otherwise.

commit_hash: str: The full SHA commit hash this candidate corresponds to.

corresponding_heads: frozenset[str]: Set of branch names pointing to this commit.

corresponding_tags: frozenset[str]: Set of tag names pointing to this commit.

remote: str: The fully qualified URL to the git repository.

class fastsandpm.dependencies.candidates.PackageIndexCandidate(name: str, version: LibraryVersion | None)[source]

Bases: Candidate

A candidate from a package index registry.

Package index candidates are resolved from package registries like JFrog Artifactory. This implementation is currently a placeholder as package index registries are not yet fully implemented.

Warning

Package index registry support is under development and is not currently implemented.

get_manifest() → Manifest | None[source]

Retrieve the manifest for this package index candidate.

Returns:: The parsed Manifest object, or None. Currently always returns None as package index registries are not yet implemented.

Check if this candidate satisfies the given requirement.

Parameters:: requirement – The requirement to check against.
Returns:: True if this candidate satisfies the requirement, False otherwise.

class fastsandpm.dependencies.candidates.PathCandidate(name: str, version: LibraryVersion | None, path: Path)[source]

Bases: Candidate

A candidate from a local filesystem path.

Path candidates represent dependencies available at a local directory. They are useful for monorepo setups or local development where dependencies are checked out alongside the main project.

get_manifest() → Manifest | None[source]

Retrieve the manifest from the candidate’s local path.

Returns:: The parsed Manifest object if a proj.toml file exists at the path, or None if no manifest file is found.

Check if this path candidate satisfies the given requirement.

A path candidate satisfies a requirement when the requirement name and candidate name match, and type-specific conditions are met:

For PackageIndexRequirement: the candidate’s version matches the specifier
For PathRequirement: the candidate path ends with the requirement path
For Git requirements: the path is a git repo and HEAD complies with the requirement’s constraints (commit, branch, tag, or version)

Parameters:: requirement – The requirement to check against.
Returns:: True if this candidate satisfies the requirement, False otherwise.

path: Path: The absolute resolved path to the candidate directory.