  Developers heavily rely on Application Programming Interfaces (APIs) from
libraries to build their software. As software evolves, developers may need to
replace the used libraries with alternate libraries, a process known as library
migration. Doing this manually can be tedious, time-consuming, and prone to
errors. Automated migration techniques can help alleviate some of this burden.
However, designing effective automated migration techniques requires
understanding the types of code changes required to transform client code that
used the old library to the new library. This paper contributes an empirical
study that provides a holistic view of Python library migrations, both in terms
of the code changes required in a migration and the typical development effort
involved. We manually label 3,096 migration-related code changes in 335 Python
library migrations from 311 client repositories spanning 141 library pairs from
35 domains. Based on our labeled data, we derive a taxonomy for describing
migration-related code changes, PyMigTax. Leveraging PyMigTax and our labeled
data, we investigate various characteristics of Python library migrations, such
as the types of program elements and properties of API mappings, the
combinations of types of migration-related code changes in a migration, and the
typical development effort required for a migration. Our findings highlight
various potential shortcomings of current library migration tools. For example,
we find that 40% of library pairs have API mappings that involve non-function
program elements, while most library migration techniques typically assume that
function calls from the source library will map into (one or more) function
calls from the target library. As an approximation for the development effort
involved, we find that, on average, a developer needs to learn about 4 APIs and
2 API mappings to perform a migration, and ... (truncated)
