Evolution of Deprecated APIs and Their Replacements in Python Libraries

2026-09-26

AI Summary

This study addresses the limited understanding of relationships between deprecated and replacement APIs across library versions. For the first time, it integrates source code definitions with raw invocation perspectives to investigate 830 deprecation mappings across 33 Python libraries. Through similarity ranking tracking, version-by-version execution testing, and source code analysis, this work systematically examines replacement locality, parameter discrepancies, and lifecycle states. The findings quantitatively reveal complex correlations between dependency granularity and release contexts, alongside distinct replacement distribution patterns. Ultimately, this research provides empirical foundations for evolution-aware API recommendation and automated migration.

Abstract

Context: API deprecation is common in library evolution, but migration requires finding replacements and adapting calls. Prior studies examine deprecation, replacement identification, and client migration separately, leaving deprecated API-replacement API relationships across releases and lifecycle states insufficiently understood. Objective: We examine replacement locality, parameter-interface differences, changes in replacement rankings across versions, and post-deprecation lifecycles from source-definition and original-invocation perspectives. Method: We construct 830 maintainer-specified mappings from 33 Python libraries, covering classes, functions, and methods. We compare definitions, track similarity-based rankings under two migration scenarios, and identify lifecycle events through source inspection and release-by-release execution. Results: Same-module replacements account for 39.1%, 55.6%, and 79.9% of class, function, and method mappings, respectively. Most mappings have no parameter changes, but function mappings show more frequent and diverse changes. Rankings vary across releases and code representations, and the applicable methods agree on the overall trend in only about 60% of cases. Other-candidate effects are dominant or mixed in 49.0% of key versions. After deprecation, 56.4% of mappings retain the source definition and 68.6% retain an executable original invocation. Among 753 mappings with at least one observed ending event, 25.2% are source-first or invocation-first rather than same-release. Of these cases, 77.4% are source-first. Conclusions: Deprecated API-replacement API relationships depend on API granularity, release context, code representation, candidate competition, and lifecycle state. These results support evolution-aware replacement API recommendation and automated API migration.

Problem

• API deprecation
• replacement API
• library evolution
• API migration
• lifecycle

Innovation

• API deprecation
• API migration
• replacement recommendation
• software evolution
• Python libraries