Skip to content

Home

Jump to bottom
PCART Bot edited this page Sep 15, 2026 · 10 revisions

PCART Wiki

Welcome to the PCART documentation!

This documentation covers the current cross-platform workflow introduced with PCART v1.4, including isolated run workspaces and structured callsite identities.

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. Discover & Preprocess: PCART discovers calls to the target library, optionally using PCResolve for cross-file symbol tracing when it is installed, and instruments a project copy with recordValue.py 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: For each callsite executed by runCommand, its pkl is loaded in the corresponding environment, the callable is reconstructed, and inspect.signature() extracts the runtime signature.
  4. Static Fallback: For a covered callsite, if dynamic inspection fails because of a built-in API, serialization issue, or unsupported signature, PCART falls back to matching pre-extracted library API definitions. Calls not executed by runCommand are reported with Coverage: No; compatibility analysis is skipped for them.
  5. Compare & Repair: Current and target signatures are compared for 10 change types. PCART attempts AST-level repairs for incompatible calls. If parameter values can be recovered from the pkl, the fix is validated by running the repaired code in targetEnv; otherwise, it undergoes static signature validation.

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