Pythonパッケージを公開するときに便利なツール/サービス
先日ja-timexというPythonパッケージを作成してPyPIに公開したのですが、開発に利用している便利なツールやサービスを紹介します。
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
Mkdocs
パッケージを広く使ってもらうために必要になるのがドキュメントの作成と公開ですが、色々と検討したなかでMkDocsが最も使い勝手が良く、自分のやりたいことをすべて満たしていました。主な特徴は以下の通りです。
- Markdownで書くことができる
- YAMLファイル1つで設定が完結
- テーマが豊富 (MkDocs Themes · mkdocs/mkdocs Wiki)
- CLIでローカル上にサーバを起動させたり、GitHub Pagesへのリリースができる
rstで書かなくて良いんですか！？やったー！という感じですが、それ以外にもとにかくMkdocsに乗っかっておけば、良い感じのデザインで簡単にインターネットに公開できるというのが特徴です。
現在の私のドキュメントサイトは、こんな感じになっています。
- ナビゲーションバー： 検索ボックスやGitHubへの情報表示&リンク
- 左サイドバー: サイト構造とページ一覧
- 右サイドバー: 表示しているページのTOC
- 中央: ページ内容(1つの
.mdファイルの中身)
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の整理とリリース文作成が捗ります。
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になります。
Carbon
最後におまけを1つ。Carbonは、コードを綺麗にハイライトして画像として保存できるサービスです。GitHubのREADMEやTwitterのサムネイルを作る際に便利です。
Discussion