A GitHub action that suggests type annotations for Python using machine learning.
This action makes suggestions within each pull request as suggested edits. You can then directly apply these suggestions to your code or ignore them.
![]() |
![]() |
---|
What are Python type annotations?
Introduced in Python 3.5, type hints
(more traditionally called type annotations) allow users
to annotate their code with the expected types. These annotations are
optionally checked by external tools, such as mypy and pyright,
to prevent type errors; they also facilitate code comprehension and navigation.
The typing
module
provides the core types.
Why use machine learning? Given the dynamic nature of Python, type inference is challenging, especially over partial contexts. To tackle this challenge, we use a graph neural network model that predicts types by probabilistically reasoning over a program’s structure, names, and patterns. This allows us to make suggestions with only a partial context, at the cost of suggesting some false positives.
git clone <your-python-repo> test-repo
cat <<EOF >pr.json
{
"action": "opened",
"pull_request": {
"url": "https://github.com/gitapi/repos/<your-python-repo>/pulls/1",
"review_comments_url": "https://github.com/gitapi/repos/<your-python-repo>/pulls/1/comments",
"head": {
"sha": "ec26c3e57ca3a959ca5aad62de7213c562f8c821"
}
}
}
EOF
docker build -t typilus:v0.9-cli-auth-rename .
docker run -it \
-v "$PWD":/data \
-e TY_DRY_RUN="1" \
-e TY_REPO_PATH=/data/test-repo \
-e GITHUB_USER="<your-github-username>" \
-e GITHUB_TOKEN="<your-personal-access-token>" \
-e GITHUB_EVENT_NAME=pull_request \
-e GITHUB_EVENT_PATH=/data/pr.json \
typilus:v0.9-cli-auth-rename .
pip3 install -r requirements.txt
wget https://github.com/typilus/typilus-action/releases/download/v0.1/typilus20200507.pkl.gz
./typilus.py --model typilus20200507.pkl.gz --repo . --file ./entrypoint.py
To use the GitHub action, create a workflow file. For example,
name: Typilus Type Annotation Suggestions
# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the master branch
on:
pull_request:
branches: [ master ]
jobs:
suggest:
# The type of runner that the job will run on
runs-on: ubuntu-latest
steps:
# Checks-out your repository under $GITHUB_WORKSPACE, so that typilus can access it.
- uses: actions/checkout@v2
- uses: typilus/typilus-action@master
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
MODEL_PATH: path/to/model.pkl.gz # Optional: provide the path of a custom model instead of the pre-trained model.
SUGGESTION_CONFIDENCE_THRESHOLD: 0.8 # Configure this to limit the confidence of suggestions on un-annotated locations. A float in [0, 1]. Default 0.8
DISAGREEMENT_CONFIDENCE_THRESHOLD: 0.95 # Configure this to limit the confidence of suggestions on annotated locations. A float in [0, 1]. Default 0.95
The action uses the GITHUB_TOKEN
to retrieve the diff of the pull request
and to post comments on the analyzed pull request.
This GitHub action is a reimplementation of the Graph2Class model of
Allamanis et al. PLDI 2020 using the
ptgnn
library. Internally, it
uses a Graph Neural Network to predict likely type annotations for Python
code.
This action uses a pre-trained neural network that has been trained on a corpus of open-source repositories that use Python's type annotations. At this point we do not support online adaptation of the model to each project.
You may wish to train your own model and use it in this action. To
do so, please follow the steps in ptgnn
.
Then provide a path to the model in your GitHub action configuration, through the
MODEL_PATH
environment variable.
We welcome external contributions and ideas. Please look at the issues in the repository for ideas and improvements.