fastsandpm.versioning.specifier API

Version specifier classes for dependency constraints.

This module provides classes for representing and evaluating version constraints used in dependency specifications. It supports various constraint formats commonly used in package managers.

Supported Specifier Formats:

Direct: "1.0.0" (exact version match)
Caret: "^1.2.3" (semver-compatible updates)
Comparison: ">=1.0.0", "<=2.0.0", ">1.0.0", "<2.0.0"
Range: ">=1.0.0,<2.0.0" (multiple constraints)

Classes:

VersionSpecifier: Abstract base class for all specifiers.
DirectVersionSpecifier: Matches a single exact version.
CaretVersionSpecifier: Matches semver-compatible versions.
ComparisonVersionSpecifier: Matches using comparison operators.
RangeVersionSpecifier: Matches versions within a range.

Functions:

meets_constraints(): Check if a version satisfies all constraints.
find_compatible_version(): Find the latest compatible version.
version_specifier_from_str(): Parse a specifier string into an object.

Type Aliases:

ComparisonOperator: Literal type for valid comparison operators.

Example

>>> from fastsandpm.versioning.specifier import version_specifier_from_str
>>> spec = version_specifier_from_str("^1.2.0")
>>> spec.satisfied_by(LibraryVersion("1.5.0"))
True
>>> spec.satisfied_by(LibraryVersion("2.0.0"))
False

Module Attributes

specifier.ComparisonOperator: alias of Literal[‘>=’, ‘<=’, ‘>’, ‘<’]

Functions

fastsandpm.versioning.specifier.find_compatible_version(versions: list[str] | list[LibraryVersion], constraints: Sequence[VersionSpecifier]) → LibraryVersion[source]

Find the latest matching version from the list of versions that meets the constraints.

Parameters:

versions – A list of available versions (strings or LibraryVersion objects).
constraints – A sequence of version specifiers that must be satisfied.

Returns:

The latest LibraryVersion that meets all constraints.

Raises:

ValueError – If no compatible version is found or versions list is empty.

fastsandpm.versioning.specifier.meets_constraints(version: str | LibraryVersion, constraints: Sequence[VersionSpecifier]) → bool[source]

Determine if the provided version meets all of the constraints provided.

Parameters:

version – The version to check (string or LibraryVersion).
constraints – A sequence of version specifiers to check against.

Returns:

True if the version meets all constraints, False otherwise. Returns True if constraints list is empty.

fastsandpm.versioning.specifier.version_specifier_from_str(version_specifier_str: str) → VersionSpecifier[source]

Create a version specifier from a string.

Parses the string and returns the appropriate VersionSpecifier subclass: - Direct version: “1.0.0” -> DirectVersionSpecifier - Caret requirement: “^1.2.3” -> CaretVersionSpecifier - Comparison requirement: “>=1.0.0” -> ComparisonVersionSpecifier - Range requirement: “>=1.0.0,<2.0.0” -> RangeVersionSpecifier

Parameters:: version_specifier_str – The version specifier string to parse.
Returns:: A VersionSpecifier instance appropriate for the given string.
Raises:: ValueError – If the string is empty or cannot be parsed.

Classes

class fastsandpm.versioning.specifier.CaretVersionSpecifier(version: LibraryVersion)[source]

Bases: VersionSpecifier

Version specifier for semver-compatible caret requirements (^x.y.z).

Caret requirements allow updates that do not modify the left-most non-zero digit, following semantic versioning compatibility rules:

^1.2.3 allows >=1.2.3, <2.0.0
^0.2.3 allows >=0.2.3, <0.3.0 (0.x treats minor as breaking)
^0.0.3 allows >=0.0.3, <0.0.4 (0.0.x treats patch as breaking)

version: The base version for the caret requirement.

Example

>>> spec = CaretVersionSpecifier(LibraryVersion("1.2.0"))
>>> spec.satisfied_by(LibraryVersion("1.9.9"))
True
>>> spec.satisfied_by(LibraryVersion("2.0.0"))
False

classmethod from_string(value: str) → Self[source]

Create a CaretVersionSpecifier from a caret requirement string.

Parameters:: value – A caret requirement string (e.g., “^1.2.3”).
Returns:: A new CaretVersionSpecifier for the parsed version.
Raises:: ValueError – If the string doesn’t start with ‘^’ or the version is invalid.

satisfied_by(version: LibraryVersion) → bool[source]

Check if a version meets the caret specification.

Parameters:: version – The version to check.
Returns:: True if the version is semver-compatible, False otherwise.

class fastsandpm.versioning.specifier.ComparisonVersionSpecifier(operator: Literal['>=', '<=', '>', '<'], version: LibraryVersion)[source]

Bases: VersionSpecifier

Version specifier for comparison requirements (>=, <=, >, <).

Compares versions using a single comparison operator. Supports greater-than, less-than, and their inclusive variants.

Example

>>> spec = ComparisonVersionSpecifier(">=", LibraryVersion("1.0.0"))
>>> spec.satisfied_by(LibraryVersion("1.5.0"))
True
>>> spec.satisfied_by(LibraryVersion("0.9.0"))
False

classmethod from_string(value: str) → Self[source]

Create a ComparisonVersionSpecifier from a comparison string.

Parses strings like “>=1.0.0” or “<2.0.0” into specifier objects.

Parameters:: value – A comparison requirement string (e.g., “>=1.2.3”).
Returns:: A new ComparisonVersionSpecifier with the parsed operator and version.
Raises:: ValueError – If the string doesn’t start with a valid operator or the version is invalid.

satisfied_by(version: LibraryVersion) → bool[source]

Check if a version meets the comparison specification.

Parameters:: version – The version to check.
Returns:: True if the version satisfies the comparison, False otherwise.

VALID_OPERATORS: set[str] = {'<', '<=', '>', '>='}: Valid comparison operator strings.

class fastsandpm.versioning.specifier.DirectVersionSpecifier(version: LibraryVersion)[source]

Bases: VersionSpecifier

Version specifier that matches a single exact version.

This specifier requires an exact match with the specified version. Pre-release stages and numbers must also match exactly.

version: The exact version that must be matched.

Example

>>> spec = DirectVersionSpecifier(LibraryVersion("1.2.3"))
>>> spec.satisfied_by(LibraryVersion("1.2.3"))
True
>>> spec.satisfied_by(LibraryVersion("1.2.4"))
False

classmethod from_string(value: str) → Self[source]

Create a DirectVersionSpecifier from a version string.

Parameters:: value – A version string (e.g., “1.2.3”).
Returns:: A new DirectVersionSpecifier for the parsed version.
Raises:: ValueError – If the string cannot be parsed as a valid version.

satisfied_by(version: LibraryVersion) → bool[source]

Check if a version meets the specification.

Parameters:: version – The version to check.
Returns:: True if the version matches exactly, False otherwise.

class fastsandpm.versioning.specifier.RangeVersionSpecifier(c1: ComparisonVersionSpecifier, c2: ComparisonVersionSpecifier)[source]

Bases: VersionSpecifier

Version specifier for range requirements (e.g., >=1.0.0,<2.0.0).

Combines exactly two comparison constraints. A version must satisfy both constraints to meet the specification. Typically used to specify a minimum and maximum version bound.

Example

>>> spec = RangeVersionSpecifier.from_string(">=1.0.0,<2.0.0")
>>> spec.satisfied_by(LibraryVersion("1.5.0"))
True
>>> spec.satisfied_by(LibraryVersion("2.0.0"))
False

classmethod from_string(range_str: str) → Self[source]

Create a RangeVersionSpecifier from a comma-separated range string.

Parses strings like “>=1.0.0,<2.0.0” into a specifier with two comparison constraints.

Parameters:: range_str – A comma-separated string containing exactly two comparison requirements (e.g., “>=1.0.0,<2.0.0”).
Returns:: A new RangeVersionSpecifier with the parsed constraints.
Raises:: ValueError – If the string doesn’t contain exactly two constraints or if any constraint is invalid.

satisfied_by(version: LibraryVersion) → bool[source]

Check if a version meets all range constraints.

Parameters:: version – The version to check.
Returns:: True if the version satisfies all constraints, False otherwise.

constraints: tuple[ComparisonVersionSpecifier, ComparisonVersionSpecifier]: A tuple of two ComparisonVersionSpecifier objects.

class fastsandpm.versioning.specifier.VersionSpecifier[source]

Bases: ABC

Abstract base class for version specifications.

Version specifiers define constraints on acceptable versions. Subclasses implement specific constraint types (exact match, comparison, range, etc.).

All specifiers must implement the satisfied_by method to check if a given version meets the specification’s constraints.

abstractmethod satisfied_by(version: LibraryVersion) → bool[source]

Check if a version satisfies this specification.

Parameters:: version – The LibraryVersion to check against this specifier.
Returns:: True if the version satisfies all constraints defined by this specifier, False otherwise.