📦

Pythonパッケージを公開するときに便利なツール/サービス

3 min read

先日ja-timexというPythonパッケージを作成してPyPIに公開したのですが、開発に利用している便利なツールやサービスを紹介します。

https://zenn.dev/yag_ays/articles/efa19302e842b6

Poetry

Pythonのパッケージ管理/依存解決ツールとして広く利用されはじめているPoetryですが、パッケージとして公開するための機能も優れています。

具体的には、以下の3ステップでPyPIにリリースすることができます。

$ poetry config pypi-token.pypi $pypi-token # 最初だけ
$ poetry build
$ poetry publish

従来setup.pyに記載していたパッケージ公開用の各種メタ情報はpyproject.tomlに記載します。

また、PyPIのテスト環境へのリリースもサポートしています。PyPIの本番環境では同じバーション番号のファイルをリリースできないため、ちょっとでも不具合があると1つバージョンを上げなければいけません。そういったミスを防ぐためにもtest.pypiで試すことは重要で、その負荷が少ないのも便利です。

$ poetry publish -r testpypi

https://github.com/python-poetry/poetry

https://python-poetry.org/docs/libraries

Mkdocs

パッケージを広く使ってもらうために必要になるのがドキュメントの作成と公開ですが、色々と検討したなかでMkDocsが最も使い勝手が良く、自分のやりたいことをすべて満たしていました。主な特徴は以下の通りです。

  • Markdownで書くことができる
  • YAMLファイル1つで設定が完結
  • テーマが豊富 (MkDocs Themes · mkdocs/mkdocs Wiki)
  • CLIでローカル上にサーバを起動させたり、GitHub Pagesへのリリースができる

rstで書かなくて良いんですか!?やったー!という感じですが、それ以外にもとにかくMkdocsに乗っかっておけば、良い感じのデザインで簡単にインターネットに公開できるというのが特徴です。

現在の私のドキュメントサイトは、こんな感じになっています。

  • ナビゲーションバー: 検索ボックスやGitHubへの情報表示&リンク
  • 左サイドバー: サイト構造とページ一覧
  • 右サイドバー: 表示しているページのTOC
  • 中央: ページ内容(1つの.mdファイルの中身)

https://www.mkdocs.org/

https://dev.classmethod.jp/articles/mkdocs-and-material-for-mkdocs-tips-matome/

GitHub Actions

GitHubのCI/CDで、色々な作業をGitを使った開発と紐付けて実行してくれます。ここからはGitHub Actions関連です。

Release Drafter

GitHubでのリリース作成をサポートしてくれるツールです。マージされたPull Requestのリストを出力してDraft Releaseとして作成してくれます。また、テンプレートを使った出力テキストの編集ができたり、Pull Requestに付いたタグを元にリストのカテゴリ分けができたりと、GitHubによるPull Requestを基本とした開発に乗っかることでリリース作業が大幅に軽減できます。

こんな感じのDraftを自動作成してくれます。

また、ブランチ名や変更ファイルを元にPull Requestに自動でタグを付与してくれるautolabelerという機能もあり、こちらと連携するとよりPull Requestの整理とリリース文作成が捗ります。

https://github.com/release-drafter/release-drafter

PyPIへの自動リリース

PoetryはPyPIリリースに便利!という話でしたが、GitHub Actionsと連携しておくと、GitHubからリリースタグを打つだけで何も考えずにリリース作業が完了します。

on:
  release:
    types: [published]
[中略]
      - name: Build and publish
        env:
          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
        run: |
          poetry config pypi-token.pypi $PYPI_TOKEN
          poetry build
          poetry publish

MkDocsの自動リリース

MkDocsもなるべく手動によるリリースから開放されたいので、docs/20210806といった何もコミットしていないブランチを作成してプッシュすると、自動でMkDocsのビルド&リリースができます。

on:
  push:
    branches:
      - 'docs/*'
[中略]
      - name: Run mkdocs to build
        run: cd docs; poetry run mkdocs build
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.PERSONAL_TOKEN_DOCS }}
          external_repository: ja-timex/docs
          publish_branch: master
          publish_dir: docs/site

今回はソースコードとドキュメントを同じレポジトリに含めておきたかったのと、GitHub PagesのURLをいい感じにしたかったので上記のような構成になっています。

ここではyagays/ja-timexレポジトリでMkDocsのビルドをして作成された静的ファイルをja-timex/docsレポジトリにコミットして公開しています。こうすることでhttps://ja-timex.github.io/docs/というURLになります。

https://futureys.tokyo/lets-deploy-document-built-by-mkdocs-to-github-pages-by-using-github-actions/

Carbon

最後におまけを1つ。Carbonは、コードを綺麗にハイライトして画像として保存できるサービスです。GitHubのREADMEやTwitterのサムネイルを作る際に便利です。

https://carbon.now.sh/

Discussion

ログインするとコメントできます