CIの上でPythonパッケージのDocString報道を追跡する方法

数ヶ月前、共同研究者はPythonパッケージのDocStringカバレッジを追跡する方法を求めました.私たちのコードのdocstringの現在の範囲を測定して、プル要求がその値を減少させないようにしたかったです.
この問題を解決するには、次の要件を満たすためのワークフローが必要です.

カバレッジがベースブランチのスコアより低い場合、ワークフローは失敗しますpull requests ) または前のコミットpush ), そして、仕事を失敗させたファイルは非難されるべきです.

メインブランチへのプッシュは、プロジェクトの現在のカバレッジを更新し、良いバッジに結果を表示する必要があります.

それから、私は優れた docstr-coverage 私たちのニーズのほとんどに適したパッケージであり、Githubアクションと組み合わせて実装されています.shields.io and jsonbin.org 解決策を思いついた.

鍾乳ビン
jsonbin.org サービスとして個人キー/値JSONストアです.
この場合、我々はこのサービスを使用してshields.io endpoint . 小さなJSONの辞書は、エンドポイントに渡され、バッジは、外出先で作成されます.したがって、カバレッジが変更されるたびに新しいバッジをリポジトリにプッシュすることを避けます.

{
  "schemaVersion": 1,
  "label": "docstr-cov",
  "message": "75%",
  "color": "green"
}

あなたはあなたのGitHubアカウントでJSONBINにログインする必要がありますJSONBIN_APIKEY .

設定ファイル
ファイルを置く.docstr.yml リポジトリのルートで.

paths:
  - your_package
verbose: 2 # int (0-3)
skip_magic: True
skip_file_doc: True
skip_init: True
skip_class_def: False
skip_private: True
follow_links: True
percentage_only: False

詳細はpackage documentation .

ワークフロー
このワークフローはボックスを操作します.環境変数を微調整する必要はありませんが、RANGE .
例えば、RANGE of 50..75 以下のカバレッジ50 赤バッジ、上に表示されます75 緑のもの.それはCoDecovのように正確に動作します!

name: docstr-cov

on:
  push:
    branches:
    - main

  pull_request:
    branches:
    - main

env:
  RANGE: 50..75
  ENDPOINT: https://jsonbin.org/${{ github.repository_owner }}/${{ github.event.repository.name }}
  TOKEN: ${{ secrets.JSONBIN_APIKEY }}

ジョブレベルでは、次の手順は簡単です.

比較するコミットするHEAD and BASE ) イベントトリガに応じて選択されます.HEAD 枝の対前のコミットpush イベントHEAD PRの対ベースのベースのpull_request .

カバレッジスコアBASE and HEAD . ヘッドスコアが低い場合に失敗します.

ファイルを無効にします.

jobs:
  check:
    runs-on: ubuntu-latest
    steps:

      - uses: actions/[email protected]
        with:
          fetch-depth: 0

      - name: Setup Python
        uses: actions/[email protected]
        with:
          python-version: 3.x

      - name: Install docstr-coverage
        run: pip install docstr-coverage

      - name: Get SHAs
        run: |
          if [[ ${{ github.event_name }} == 'push' ]]; then
            echo "BASE=$(git rev-parse HEAD^)" >> $GITHUB_ENV
            echo "HEAD=$(git rev-parse HEAD)" >> $GITHUB_ENV

          elif [[ ${{ github.event_name }} == 'pull_request' ]]; then
            echo "BASE=${{ github.event.pull_request.base.sha }}" >> $GITHUB_ENV
            echo "HEAD=${{ github.event.pull_request.head.sha }}" >> $GITHUB_ENV

          else
            echo "Unexpected event trigger"
            exit 1
          fi

      - name: Get base coverage
        run: |
          git checkout $BASE
          echo "BASE_COV=$(docstr-coverage -p)" >> $GITHUB_ENV

      - name: Test head coverage
        run: |
          git checkout $HEAD
          docstr-coverage --fail-under=$BASE_COV

      - name: Blame
        run: |
          git diff --name-only $(git merge-base $BASE $HEAD) | \
          xargs docstr-coverage --accept-empty
        if: failure()

オンリーオンpush イベント

カバレッジを得る

色のラベルをRANGE .

JSONBINへのポスト結果.

エンドポイントを公開します.

バッジURLを出力します.

      - name: Get new coverage
        run: echo "NEW_COV=$(printf "%.f" $(docstr-coverage -p))" >> $GITHUB_ENV
        if: always() && github.event_name == 'push'

      - name: Set label color
        run: |
          if [[ $NEW_COV -ge $(echo {${{ env.RANGE }}} | awk '{print $NF;}') ]]; then
            echo "COLOR=green" >> $GITHUB_ENV
          elif [[ $NEW_COV -lt $(echo {${{ env.RANGE }}} | awk '{print $1;}') ]]; then
            echo "COLOR=red" >> $GITHUB_ENV
          else
            echo "COLOR=orange" >> $GITHUB_ENV
          fi
        if: always() && github.event_name == 'push'

      - name: Post results
        run: |
          curl -X POST $ENDPOINT/badges/docstr-cov \
          -H "authorization: token $TOKEN" \
          -d "{ \"schemaVersion\": 1, \"label\": \"docstr-cov\", \
                \"message\": \"$NEW_COV%\", \"color\": \"$COLOR\" }"
        if: always() && github.event_name == 'push'

      - name: Set public endpoint
        run: |
          curl -X PUT $ENDPOINT/_perms -H "authorization: token $TOKEN"
        if: always() && github.event_name == 'push'

      - name: Show badge URL
        run: echo "https://img.shields.io/endpoint?url=$ENDPOINT/badges/docstr-cov"
        if: always() && github.event_name == 'push'

バッジはすべてのプッシュに動的に更新する必要がありますmain . READMEに追加してください.MD

コードを得る

epassaro / docstr-cov-workflow
GithubアクションによるPythonパッケージのdocstring範囲を測定する
ワークフロー
GithubアクションによるPythonパッケージのdocstring範囲を測定する
用途

コピー.github/workflows/docstr-cov.yml and .docstr.yaml あなたの倉庫に.

次の設定ファイルを調整しますpackage documentation .

ログインhttps://jsonbin.org リポジトリの秘密としてAPIキーを保存するJSONBIN_APIKEY .

カバレッジがベースブランチのスコアより低い場合、ワークフローは失敗するpull_request ) または前のコミットpush ), そして、仕事を失敗させたファイルは非難されるでしょう.

プッシュmain 支店更新プログラムは、素敵なバッジを更新することにより、現在のカバレッジ.

あなたが調整してバッジの色の範囲を変更することができますRANGE ワークフローの先頭にある変数.例えば、50..75 以下のカバレッジ50 赤バッジ、上に表示されます75 緑のもの.

readmeにバッジを追加してください.MD

例

変更を加えるexample/base.py ワークフローをご覧ください.
View on GitHub