PSASpotter

An automated tool for extracting Platform-Specific API from Git repositories written in Python. The psaspotter (Platform-Specific API Spotter) is primarily designed to be used as a command-line tool. With psaspotter, you can easily extract information about the Platform-Specific APIs and their usages from the Git repository or directory (only python files are analyzed). The set of Platform-Specific APIs are saved in a given CSV file.

PSASpotter is an AST-based tool that detects API usage at the function/method level. Given a Git project, PSASpotter analyzes all Python files and exports details of platform-specific API usage. Specifically, for each usage, PSASpotter reports information about the analyzed project (name and commit), the used API (name and availability), and the usage location (filename, line, and GitHub link). In addition, PSASpotter also reports whether the usage happens within defensive code.

Install

The easiest way to install psaspotter is to install from Pypi

pip install psaspotter

Alternatively, you can install from test environment

pip install --index-url https://test.pypi.org/simple/ --no-deps psaspotter

You may wish to use this tool in a virtual environment. You can use the following commands.

virtualenv psaspotter_venv
source psaspotter_venv/bin/activate
pip install psaspotter

Quick examples

As an example, the following command extracts every platform-specific APIs from the directory repository_local. It also saves various information (line, module, filename ...) in output.csv. Additionally, we can provide information about the project present in the directory provided. For this, the parameters -n and -c can be added to inform the name (my/local) and last commit (da39a3ee5e6b4b0d3255bfef95601890afd80709) of the project. This information will be available in the output file.

psaspotter repository_local -o output.csv -n my/local --commit da39a3ee5e6b4b0d3255bfef95601890afd80709 

Note that the repository does not have to be already cloned, the tool also can fetch it. For example, the GitHub repository https://github.com/ricardojob/PSASpotter will be fetched, saved under the data/PSASpotter directory. Note that, by default all projects are cloned to the data directory.

psaspotter https://github.com/ricardojob/PSASpotter -o output.csv

Usage

After installation, the psaspotter command-line tool should be available in your shell. Otherwise, please replace psaspotter by python -m psaspotter. The explanations in the following stays valid in both cases.

We can use PSASpotter to extract information about the usage of platform-specific in a Git repository:

psaspotter <git_repo> -o <output_file.csv>

The first parameter is the Git repository to be analyzed. The parameter -o represents the name of the CSV output file.

You can use psaspotter with the following arguments:

  -o,                     Output CSV file.
  -c,                     Commit or tag to be analyzed.
  -p,                     Platform-specific API category.

The CSV file given to -o (or that will be written to the standard output by default) will contain the following columns:

• project_name: Respository name
• project_commit: Analyzed commit
• api_name: Name of the used platform-specific API
• api_availability: Availability of the used platform-specific API
• usage_filename: Filename using the platform-specific API
• usage_line: Filename line using the platform-specific API
• usage_github_link: Github link to the filename and line
• defensive_code: Check if the API is used within defensive code

Tool demonstration

The following video presents a demonstration scenario of the tool: video.

License

Distributed under MIT License.

Acknowledgements

The structure of this project was heavily inspired by the gigawork and spotflow projects.