compare_versions
Read-onlyIdempotent
Identify changes to a Python standard library symbol between two versions, showing added, removed, changed, or unchanged status with details like deprecation and signature differences.
Instructions
Diff a Python stdlib symbol between two indexed versions. Returns change=added|removed|changed|unchanged with optional new_in, changed_in, deprecated_in, signature_delta (advisory), see_also_added/removed, section_diff, and note fields. Both versions must be indexed; otherwise an actionable error names the available versions.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Qualified Python symbol name, e.g. 'asyncio.TaskGroup' | |
| v1 | Yes | Python version string, e.g. '3.11' | |
| v2 | Yes | Python version string, e.g. '3.11' |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Qualified symbol name being compared | |
| v1 | Yes | Source Python version | |
| v2 | Yes | Target Python version | |
| change | Yes | Diff discriminator: 'added' (symbol new in v2), 'removed' (symbol absent in v2), 'changed' (symbol present in both with a detected delta), or 'unchanged' (symbol present in both, no delta) | |
| new_in | No | Version string extracted from the v2 section text; populated when change == 'added', and may also be set when change == 'changed' if the v2 section carries a versionadded marker for a sub-feature | |
| removed_in | No | Version where the symbol is first absent; populated when change == 'removed' (equals v2) | |
| changed_in | No | Version extracted from the v2 section; populated when change == 'changed' | |
| deprecated_in | No | Version extracted from a deprecation marker in the v2 section | |
| signature_delta | No | Best-effort heuristic: first non-empty diff line between v1 and v2 section text. MAY be a docstring change or prose change rather than a true signature change — treat as advisory, not authoritative. | |
| see_also_added | No | See-also link labels present in v2 but not v1 | |
| see_also_removed | No | See-also link labels present in v1 but not v2 | |
| section_diff | No | Short unified-diff snippet (difflib.unified_diff), truncated to honor the token budget; populated only when change == 'changed' and the diff is non-trivially short | |
| note | No | Optional advisory note about result completeness, e.g. when docs pages could not be fetched for one or both versions and the diff is therefore based on symbol presence alone. |