Skip to content

Home

Jump to bottom
PCART Bot edited this page May 25, 2026 · 9 revisions

PCART Wiki

Welcome to the PCART documentation!

What is PCART?

PCART is an automated tool designed to detect and repair Python API parameter compatibility issues. It is the first to achieve a fully automated process (end-to-end) that includes API extraction, code instrumentation, mapping, compatibility analysis, and repair and validation. PCART specializes in addressing API compatibility issues arising from parameter addition, removal, renaming, reordering, and the conversion of positional parameters to keyword parameters.

Features

  • Fully Automated: End-to-end automation from API extraction to repair validation
  • Comprehensive Detection: Detects 10 types of parameter change types
  • Multi-Platform: Supports Linux and Windows
  • Multi-Library: Works with PyTorch, NumPy, SciPy, Pillow, scikit-learn, and more

Supported Parameter Change Types

Dictionary Key Type Name Description Support
delete Deletion Parameter removed ✅ Full
typeChange Type Change Parameter type altered ⚠️ Partial
rename Renaming Parameter name changed ✅ Full
posChange Position Change Parameter position altered ✅ Full
replace Replacement Parameter replaced at same position ✅ Full
pos2key Positional to Keyword Positional-only changed to keyword-only ✅ Full
addPos Add Positional New positional parameter added ✅ Full
addKey Add Keyword New keyword parameter added ✅ Full
key2pos Keyword to Positional Keyword changed to positional ✅ Full
value Default Value Change Parameter default value changed ❌ Not implemented

Total: 10 parameter change types

⚠️ Note: typeChange only checks if the old type is identical to or a subset of the new type for complex annotations (Union/Optional/|).

Quick Navigation

Runtime Environments

PCART runs with one tool environment and two configured project environments:

Environment Role Requirements
Tool environment Runs PCART itself Python 3.9 + dill
currentEnv Runs the project with the current library version for API mapping and baseline checks Python 3.x + current library version + project requirements + dill
targetEnv Runs the project with the target library version for API mapping and repair validation Python 3.x + target library version + project requirements + dill

Only currentEnv and targetEnv are configuration fields. The tool environment is the Python environment used to run main.py.

How It Works (Brief)

  1. Preprocess: PCART instruments the project code, injecting recordValue.py wrappers around every API call to capture runtime receiver objects and parameter values.
  2. Generate pkls: The instrumented project runs in currentEnv — each API call's runtime data is saved as a pkl file (with callsite-based naming to distinguish same-name APIs at different source locations).
  3. Dynamic Match: Each pkl is loaded in the corresponding environment, the callable is reconstructed, and inspect.signature() extracts the actual parameter signature.
  4. Static Fallback: If dynamic matching fails (no coverage, built-in API, or serialization error), PCART falls back to fuzzy-matching against pre-extracted library API definitions.
  5. Compare & Repair: Current vs target signatures are compared for 10 change types. All incompatible calls are fixed at the AST level. If parameter values can be recovered from the pkl, the fix is validated by running the repaired code in targetEnv; otherwise, the fix undergoes static signature validation only.

For full details, see How-It-Works.

Citation

If PCART supports your research or development work, please cite the following publication:

@article{PCART_TSE2025,
  author={Zhang, Shuai and Xiao, Guanping and Wang, Jun and Lei, Huashan and He, Gangqiang and Liu, Yepang and Zheng, Zheng},
  journal={IEEE Transactions on Software Engineering},
  title={PCART: Automated Repair of Python API Parameter Compatibility Issues},
  year={2026},
  volume={52},
  number={3},
  pages={723-753},
  doi={10.1109/TSE.2025.3646150}
}

Links

Clone this wiki locally