fastmcp/docs/python-sdk/fastmcp-utilities-versions.mdx

---
title: versions
sidebarTitle: versions
---

# `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` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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 &lt; b, 0 if a == b, 1 if a &gt; b.


### `is_version_greater` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>


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` <sup><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></sup>

```python
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` <sup><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></sup>

```python
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` <sup><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></sup>


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