fastmcp.utilities.versions

Version comparison utilities for component versioning.

This module provides utilities for comparing component versions. Versions are strings that are first attempted to be parsed as PEP 440 versions (using the packaging library), falling back to lexicographic string comparison.

Examples: - "1", "2", "10" → parsed as PEP 440, compared semantically (1 < 2 < 10) - "1.0", "2.0" → parsed as PEP 440 - "v1.0" → 'v' prefix stripped, parsed as "1.0" - "2025-01-15" → not valid PEP 440, compared as strings - None → sorts lowest (unversioned components)

Functions

parse_version_key ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L190" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

parse_version_key(version: str | None) -> VersionKey

Parse a version string into a sortable key.

Args:

• version: The version string, or None for unversioned.

Returns:

• A VersionKey suitable for sorting.

version_sort_key ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L202" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

version_sort_key(component: FastMCPComponent) -> VersionKey

Get a sort key for a component based on its version.

Use with sorted() or max() to order components by version.

Args:

• component: The component to get a sort key for.

Returns:

• A sortable VersionKey.

compare_versions ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L222" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

compare_versions(a: str | None, b: str | None) -> int

Compare two version strings.

Args:

• a: First version string (or None).
• b: Second version string (or None).

Returns:

• -1 if a < b, 0 if a == b, 1 if a > b.

is_version_greater ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L244" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

is_version_greater(a: str | None, b: str | None) -> bool

Check if version a is greater than version b.

Args:

• a: First version string (or None).
• b: Second version string (or None).

Returns:

• True if a > b, False otherwise.

max_version ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L257" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

max_version(a: str | None, b: str | None) -> str | None

Return the greater of two versions.

Args:

• a: First version string (or None).
• b: Second version string (or None).

Returns:

• The greater version, or None if both are None.

min_version ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L274" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

min_version(a: str | None, b: str | None) -> str | None

Return the lesser of two versions.

Args:

• a: First version string (or None).
• b: Second version string (or None).

Returns:

• The lesser version, or None if both are None.

dedupe_with_versions ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L291" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

dedupe_with_versions(components: Sequence[C], key_fn: Callable[[C], str]) -> list[C]

Deduplicate components by key, keeping highest version.

Groups components by key, selects the highest version from each group, and injects available versions into meta if any component is versioned.

Args:

• components: Sequence of components to deduplicate.
• key_fn: Function to extract the grouping key from a component.

Returns:

• Deduplicated list with versions injected into meta.

Classes

VersionSpec ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Specification for filtering components by version.

Used by transforms and providers to filter components to a specific version or version range. Unversioned components (version=None) always match any spec.

Args:

• gte: If set, only versions >= this value match.
• lt: If set, only versions < this value match.
• eq: If set, only this exact version matches (gte/lt ignored).

Methods:

matches ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

matches(self, version: str | None) -> bool

Check if a version matches this spec.

Args:

• version: The version to check, or None for unversioned.
• match_none: Whether unversioned (None) components match. Defaults to True for backward compatibility with retrieval operations. Set to False when filtering (e.g., enable/disable) to exclude unversioned components from version-specific rules.

Returns:

• True if the version matches the spec.

intersect ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

intersect(self, other: VersionSpec | None) -> VersionSpec

Return a spec that satisfies both this spec and other.

Used by transforms to combine caller constraints with filter constraints. For example, if a VersionFilter has lt="3.0" and caller requests eq="1.0", the intersection validates "1.0" is in range and returns the exact spec.

Args:

• other: Another spec to intersect with, or None.

Returns:

• A VersionSpec that matches only versions satisfying both specs.

VersionKey ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

A comparable version key that handles None, PEP 440 versions, and strings.

Comparison order:

1. None (unversioned) sorts lowest
2. PEP 440 versions sort by semantic version order
3. Invalid versions (strings) sort lexicographically
4. When comparing PEP 440 vs string, PEP 440 comes first