AexPy /eɪkspaɪ/ is Api EXplorer in PYthon for detecting API breaking changes in Python packages.
Project description
AexPy /eɪkspaɪ/ is Api EXplorer in PYthon for detecting API breaking changes in Python packages.
[!NOTE] AexPy is the prototype implementation of the conference paper "AexPy: Detecting API Breaking Changes in Python Packages" in Proceedings of the 33rd IEEE International Symposium on Software Reliability Engineering (ISSRE 2022), Charlotte, North Carolina, USA, October 31 - November 3, 2022.
If you use our approach or results in your work, please cite it according to the citation file.
X. Du and J. Ma, "AexPy: Detecting API Breaking Changes in Python Packages," 2022 IEEE 33rd International Symposium on Software Reliability Engineering (ISSRE), 2022, pp. 470-481, doi: 10.1109/ISSRE55969.2022.00052.
- How AexPy works? Approach Design & Evaluation are in AexPy's conference paper, see also talk & slides.
- How we implement AexPy? Source Code & Implemetation are in AexPy's repository, see also system design (zh-cn).
- How to use AexPy? Detailed Document & Data are in AexPy's documents, see also demo video and online AexPy (viewer only).
graph LR;
Package-->Version-1;
Package-->Version-2;
Version-1-->Preprocessing-1;
Version-2-->Preprocessing-2;
Preprocessing-1-->Extraction-1;
Preprocessing-2-->Extraction-2;
Extraction-1-->Difference;
Extraction-2-->Difference;
Difference-->Evaluation;
Evaluation-->Breaking-Changes;
AexPy also provides a framework to process Python packages, extract APIs, and detect changes, which is designed for easily reusing and customizing. See the following "Advanced Tools" section and the source code for details.
[!NOTE] For AexPy v0.1.x Users We have removed web front-end support in AexPy's Python package, and are focusing on command-line interface for now. The web interfaces are provided as online AexPy (viewer only) now. For the old available version, see v0.1.2.
Quick Start
Diff generator-oj-problem v0.0.1 and v0.0.2.
- Save API descriptions to
cache/api1.json
andcache/api2.json
- Output report to
report.txt
pip install aexpy
mkdir -p cache
aexpy preprocess -r -p generator-oj-problem@0.0.1 ./cache - | aexpy extract - ./cache/api1.json
aexpy preprocess -r -p generator-oj-problem@0.0.2 ./cache - | aexpy extract - ./cache/api2.json
aexpy diff ./cache/api1.json ./cache/api2.json - | aexpy report - - | aexpy view - > report.txt
View results on online AexPy.
- generator-oj-problem@0.0.1 Distribution and API
- generator-oj-problem@0.0.2 Distribution and API
- Changes and Report
Features
- Preprocessing
- Download packages and get source code, or use existing code base.
- Count package file sizes and lines of code.
- Read package metadata and detect top modules.
- Extracting
- Extract APIs from Python packages, including modules, classes, functions, attributes.
- Collect detailed APIs, including parameters, instance attributes.
- Detect API aliases and build call graphs.
- Enrich type information for APIs by static type analyzers.
- Diffing
- Detect API changes after pairing APIs between two versions.
- Grade changes by their severities.
- Reporting
- Generate a human-readable report for API change detection results.
- Framework
- Customize processors and implementation details.
- Process Python packages in AexPy's general pipeline with logging and caching.
- Generate portable data in JSON for API descriptions, changes, and so on.
- Execute processing and view data by AexPy's command-line, with stdin/stdout supported.
Install
We provide the Python package on PyPI. Use pip to install the package.
python -m pip install --upgrade aexpy
aexpy --help
[!IMPORTANT] Please ensure your Python interpreter works in UTF-8 mode.
We also provide the Docker image to avoid environment errors.
docker pull stardustdl/aexpy:latest
docker run --rm stardustdl/aexpy:latest --help
# or the image from the main branch
docker pull stardustdl/aexpy:main
Usage
[!TIP] All results produced by AexPy are in JSON format, so you could modify it in any text editor.
Preprocess
Preprocess a distribution for a package release.
AexPy provide four preprocessing mode:
-r
,--release
: download and unpack the package wheel and automatically load from dist-info-w
,--wheel
: Unpack existing package wheel file and automatically load from dist-info-d
,--dist
: Automatically load from unpacked wheel, and its dist-info-s
,--src
: (default) Use given distribution information (path to code, package name, modules)
AexPy will automatically load package name, version, top-level modules, and dependencies from dist-info.
There are also options to specify fields in the distribution:
-p
,--project
: Package name and its version, e.g.project@version
.-m
,--module
: (multiple) Top-level module names.-D
,--depends
: (multiple) Package dependencies.-R
,--requirements
: Packagerequirements.txt
file path, to load dependencies.-P
,--pyversion
: Specify Python version for this distribution, supported Python 3.8+.
[!TIP] You could modify the generated distribution file in a text editor to change field values.
# download the package wheel and unpack into ./cache
# output the distribution file to ./cache/distribution.json
aexpy preprocess -r -p generator-oj-problem@0.0.1 ./cache ./cache/distribution.json
# or output the distribution file to stdout
aexpy preprocess -r -p generator-oj-problem@0.0.1 ./cache -
# use existing wheel file
aexpy preprocess -w ./cache/generator_oj_problem-0.0.1-py3-none-any.whl ./cache/distribution.json
# use existing unpacked wheel directory, auto load metadata from .dist-info directory
aexpy preprocess -d ./cache/generator_oj_problem-0.0.1-py3-none-any ./cache/distribution.json
# use existing source code directory, given the package's name, version, and top-level modules
aexpy preprocess ./cache/generator_oj_problem-0.0.1-py3-none-any ./cache/distribution.json -p generator-oj-problem@0.0.1 -m generator_oj_problem
View results at AexPy Online.
Extract
Extract the API description from a distribution.
[!IMPORTANT] About Dependencies AexPy would dynamically import the target module to detect all available APIs. So please ensure all dependencies have been installed in the extraction environment, or specify the
dependencies
field in the distribution, and AexPy will install them into the extraction environment.If the
wheelFile
field is valid (i.e. the target file exists), AexPy will firstly try to install the wheel and ignore thedependencies
field (used when the wheel installation fails).
[!TIP] About Environment AexPy use micromamba as default environment manager. Use
AEXPY_ENV_PROVIDER
environment variable to specifyconda
,mamba
, ormicromamba
.
- Use flag
--no-temp
to let AexPy use the current Python environment (as same as AexPy) as the extraction environment (the default behavior of the installed AexPy package).- Use flag
--temp
to let AexPy create a temporary mamba(conda) environment that matches the distribution's pyverion field (the default behavior of our docker image).- Use option
-e
,--env
to specify an existing mamba(conda) env name as the extraction environment (will ignore the temp flag).
aexpy extract ./cache/distribution.json ./cache/api.json
# or input the distribution file from stdin
# (this feature is also supported in other commands)
aexpy extract - ./cache/api.json
# or output the api description file to stdout
aexpy extract ./cache/distribution.json -
# Use a env named demo-env
aexpy extract ./cache/distribution.json - -e demo-env
# Create a temporary env
aexpy extract ./cache/distribution.json - --temp
View results at AexPy Online.
Diff
Diff two API descriptions and detect changes.
aexpy diff ./cache/api1.json ./cache/api2.json ./cache/diff.json
View results at AexPy Online.
Report
Generate report from detect changes.
aexpy report ./cache/diff.json ./cache/report.json
View results at AexPy Online.
View
View produced data.
aexpy view ./cache/distribution1.json
aexpy view ./cache/distribution2.json
aexpy view ./cache/api1.json
aexpy view ./cache/api2.json
aexpy view ./cache/diff.json
aexpy view ./cache/report.json
Docker Image
The docker image keeps the same command-line interface, only need a volume mapping to /data
for file access.
[!TIP] Since the container runs in non-root user, please use root user to allow the container writing to the mounted directory.
docker run -v $pwd/cache:/data -u root aexpy/aexpy extract /data/distribution.json /data/api.json
Advanced Tools
Logging
The processing may cost time, you can use multiple -v
for verbose logs (which are outputed to stderr).
aexpy -vvv view ./cache/report.json
Interactive
Add -i
or --interact
to enable interactive mode, every command will create an interactive Python shell after finishing processing. Here are some useful variable you could use in the interactive Python shell.
result
: The produced data objectcontext
: The producing context, useexception
to access the exception if failing to process
aexpy -i view ./cache/report.json
[!TIP] Feel free to use
locals()
anddir()
to explore the interactive environment.
Pipeline
AexPy has four loosely-coupled stages in its pipeline. The adjacent stages transfer data by JSON, defined in models directory. You can easily write your own implementation for every stage, and combine your implementation into the pipeline. See third directory for an example on how to implement stages and integrate other tools.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.