fastsandpm.dependencies.provider API

Dependency resolution provider for resolvelib integration.

This module provides the FastSandProvider class that implements the resolvelib AbstractProvider interface. It handles candidate discovery, preference ordering, and dependency extraction during the resolution process.

Classes:

FastSandProvider: The main dependency resolution provider.

Functions:

resolve(): Convenience function to resolve dependencies for a manifest.

Type Aliases:

FastSandReqInfo: FastSandReqInfo: Type alias for requirement information tuples.
FastSandReporter: Type alias for the resolution reporter.

Module Attributes

provider.FastSandReqInfo: alias of RequirementInformation[PackageIndexRequirement | PathRequirement | CommitGitRequirement | BranchGitRequirement | TaggedGitRequirement | VersionedGitRequirement | GitRequirement, Candidate]

provider.FastSandReporter: alias of BaseReporter[PackageIndexRequirement | PathRequirement | CommitGitRequirement | BranchGitRequirement | TaggedGitRequirement | VersionedGitRequirement | GitRequirement, Candidate, str]

Functions

fastsandpm.dependencies.provider.resolve(manifest: Manifest, optional_deps: list[str] | None = None) → ResolveResult[source]

Resolve all dependencies for a manifest.

Creates a FastSandProvider with the manifest’s registries and runs the resolvelib resolver to find a compatible set of candidates for all declared dependencies.

Parameters:

manifest – The manifest containing dependencies to resolve.
optional_deps – Optional dependency groups to include in the library.

Returns:

A ResolveResult containing the resolved packages, their dependency graph, and the set of direct dependencies.

Raises:

resolvelib.ResolutionImpossible – If no compatible resolution exists.

Example

>>> from fastsandpm import get_manifest
>>> from fastsandpm.dependencies.provider import resolve
>>> manifest = get_manifest("./my-project")
>>> resolved = resolve(manifest)
>>> for name, candidate in resolved.items():
...     print(f"{name}: {candidate.version}")

Classes

class fastsandpm.dependencies.provider.FastSandProvider(registries: Registries)[source]

Dependency resolution provider implementing the resolvelib interface.

This provider handles the core dependency resolution logic, including candidate discovery, preference ordering, and requirement satisfaction checking. It uses the configured registries to find candidate packages.

_registries: The registries used for candidate discovery.

find_matches(identifier: str, requirements: Mapping[str, Iterator[PackageIndexRequirement | PathRequirement | CommitGitRequirement | BranchGitRequirement | TaggedGitRequirement | VersionedGitRequirement | GitRequirement]], incompatibilities: Mapping[str, Iterator[Candidate]]) → Iterable[Candidate] | Callable[[], Iterable[Candidate]][source]

Find all possible candidates that satisfy the given constraints.

Gets all candidates for all requirements of the identifier. Then filters out the Candidates previously marked as incompatible.

Parameters:

identifier – An identifier as returned by identify(). All candidates returned by this method should produce the same identifier.
requirements – A mapping of requirements that all returned candidates must satisfy. Each key is an identifier, and the value an iterator of requirements for that dependency.
incompatibilities – A mapping of known incompatibile candidates of each dependency. Each key is an identifier, and the value an iterator of incompatibilities known to the resolver. All incompatibilities must be excluded from the return value.

Get the dependencies declared by a candidate.

Retrieves the candidate’s manifest and extracts its declared dependencies. Also merges any registries declared in the candidate’s manifest into the provider’s registry list.

Parameters:: candidate – The candidate to get dependencies for.
Returns:: A list of requirements declared as dependencies by the candidate. Returns an empty list if the candidate has no manifest.

get_preference(identifier: str, resolutions: Mapping[str, Candidate], candidates: Mapping[str, Iterator[Candidate]], information: Mapping[str, Iterator[FastSandReqInfo]], backtrack_causes: Sequence[FastSandReqInfo]) → Preference[source]

Produce a sort key for given requirement based on preference.

The lower the return value is, the more preferred this group of arguments is.

Currently fastsandpm considers the following in order:

Any requirement that is a path
Any requirement that is “git” and “direct”, e.g., points to an explicit URL.
Any requirement that is “git” and “pinned”, i.e., points to a specific tag or version or == without a wildcard.
Any requirement that imposes an upper version limit, i.e., contains the operator <, <=, or ^ with a wildcard. Because fastsand prioritizes the latest version, preferring explicit upper bounds can rule out infeasible candidates sooner. This does not imply that upper bounds are good practice; they can make dependency management and resolution harder.
Order user-specified requirements as they are specified, placing other requirements afterward.
Any “non-free” requirement, i.e., one that contains at least one operator, such as >= or !=.
Alphabetical order for consistency (aids debuggability).

Return the identifier for a requirement or candidate.

The identifier is used to group related requirements and candidates during resolution.

Parameters:: requirement_or_candidate – The requirement or candidate to identify.
Returns:: The name of the package, which serves as its unique identifier.

Check if a candidate satisfies a requirement.

Parameters:

requirement – The requirement to check.
candidate – The candidate to evaluate.

Returns:

True if the candidate satisfies the requirement, False otherwise.

narrow_requirement_selection(identifiers: Iterable[str], resolutions: Mapping[str, Candidate], candidates: Mapping[str, Iterator[Candidate]], information: Mapping[str, Iterator[RequirementInformation[PackageIndexRequirement | PathRequirement | CommitGitRequirement | BranchGitRequirement | TaggedGitRequirement | VersionedGitRequirement | GitRequirement, Candidate]]], backtrack_causes: Sequence[RequirementInformation[PackageIndexRequirement | PathRequirement | CommitGitRequirement | BranchGitRequirement | TaggedGitRequirement | VersionedGitRequirement | GitRequirement, Candidate]]) → list[str][source]

Narrow down which requirements to resolve next.

This method can be used to optimize the resolution order by filtering or reordering the identifiers. Currently passes through to the base implementation without modification.

Parameters:

identifiers – Iterable of requirement identifiers to consider.
resolutions – Mapping of already-resolved identifiers to candidates.
candidates – Mapping of identifiers to their candidate iterators.
information – Mapping of identifiers to requirement information.
backtrack_causes – Sequence of requirements that caused backtracking.

Returns:

A filtered/reordered list of identifiers to process next.

class fastsandpm.dependencies.provider.ResolveResult(mapping: dict[str, Candidate], graph: dict[str, set[str]], direct_dependencies: frozenset[str])[source]

Bases: object

Result of dependency resolution, containing resolved packages and their dependency graph.

The mapping contains all resolved packages keyed by name. The graph preserves the dependency relationships computed by the resolver, avoiding the need to re-read manifests from disk to reconstruct them.

items() → ItemsView[str, Candidate][source]: Return items view of the mapping, for dict-like iteration.

topological_order() → list[str][source]

Return package names in topological order (dependencies first).

Packages that have no dependencies on other resolved packages appear first, followed by packages whose dependencies have already appeared. Ties are broken alphabetically for deterministic output.

Returns:: List of package names sorted so that every package appears after all of its dependencies.

direct_dependencies: frozenset[str]: The set of package names that were direct (user-specified) dependencies, as opposed to transitive dependencies.

graph: dict[str, set[str]]: Dictionary mapping each package name to the set of package names it depends on. Only includes dependencies that are themselves in the resolved set.

mapping: dict[str, Candidate]: Dictionary mapping package names to their resolved Candidate objects.