Skip to content

About

VPPDetector: Detect compatibility risks from variadic argument forwarding in Python library APIs

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

What is VPPDetector?

VPPDetector detects compatibility risks from variadic argument forwarding in Python library APIs. A variadic-parameter pitfall (VPP) occurs when a library API's *args or **kwargs propagates to a downstream expansion whose target signature lacks the corresponding variadic parameter. Findings identify the root API, parameter channel, forwarding path and source locations.

VPPDetector provides three Python interfaces:

  • scan_package() scans a whole library version for VPPs.
  • scan_api() scans one API and its downstream forwarding paths on demand.
  • assess_change() analyzes how one supplied parameter deletion or rename is handled for a specific call.

Scan results contain findings and analysis boundaries. An empty findings collection means no VPP was detected within the supported analysis. The coverage collection summarizes recorded limits separately for each variadic channel; no_known_boundary does not certify complete coverage.

Requirements

  • Python 3.9 or newer
  • PCResolve 1.0.8 or newer (pcresolve>=1.0.8)

Install from PyPI:

python -m pip install vppdetector

To install from a source checkout in editable mode, run:

python -m pip install -e .

Installation provides the vppdetector command and the Python package, along with PCResolve and the other declared dependencies. PCResolve supplies program facts and call resolution in the analyzer's Python environment; the analyzed library does not need to be installed or imported.

Quick start

Create the following source layout, with an empty __init__.py:

example_lib/
└── example/
    ├── __init__.py
    └── api.py

Put this code in example_lib/example/api.py:

def target(allowed=0):
    return allowed


def wrapper(**kwargs):
    return target(**kwargs)


def consumed(**kwargs):
    return kwargs.pop("obsolete", 0)

Scan the source and print a JSON report:

vppdetector example_lib

The report includes a finding for wrapper forwarding **kwargs to the fixed signature of target, with has_vpp: true.

Write the report to a file:

vppdetector example_lib --output report.json

Run vppdetector --help for all options. The default forwarding depth is five hops; use --import-root when the library needs an explicit module root. From a source checkout, install the project in editable mode and run the same vppdetector command.

Python API

Python callers receive result objects directly:

from vppdetector import scan_package

report = scan_package("example_lib")
print(report.has_vpp)  # True

Use scan_api() for one API or assess_change() for a selected changed argument and original call. See the API reference for complete examples, source identities and result fields.

Documentation

  • API reference: CLI options, Python interfaces, source location, analysis contexts and returned objects.
  • Design: detection rules, shared analysis core, module responsibilities and the original research scanner.
  • Analysis coverage and limits: supported propagation, assessment states and unresolved analysis boundaries.
  • Fact consumption contract: PCResolve fact validation, supported representations and consumer obligations.

The original scanner and historical outputs are retained; see Version 1.0 research scanner.

Publication

@inproceedings{zhang2024coding,
  title={Coding Pitfalls: Demystifying the Potential API Compatibility Risk of Variadic Parameters in Python},
  author={Zhang, Shuai and He, Gangqiang and Xiao, Guanping},
  booktitle={2024 IEEE 35th International Symposium on Software Reliability Engineering Workshops (ISSREW)},
  pages={105--106},
  year={2024},
  organization={IEEE}
}

License

VPPDetector is licensed under GNU AGPLv3. PCResolve is an MIT-licensed dependency; see THIRD_PARTY_NOTICES.md.

About

VPPDetector: Detect compatibility risks from variadic argument forwarding in Python library APIs

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages