2022/01/27 みんなのPython勉強会#77 「パッケージングしよう」の発表資料です

1. パッケージングしよう
Start Python Club みんなの Python 勉強会#77
Atsushi Odagiri
2022-01-27

2. はじめに

3. お前誰よ
▶ aodag
▶ Atsushi Odagiri
▶ 株式会社オープンコレクター
▶ python1.5 とかから

4. アジェンダ
▶ Python パッケージングのエコシステム
▶ パッケージングして配布する

5. Python パッケージングのエコシステム

6. PyPA
▶ Python Packaging Authority
▶ パッケージング関連の PEP(Python Enhancement Proposal)
を提案
▶ パッケージング関連ツールの保守

7. PyPA が提供するツール
▶ pip
▶ setuptools
▶ wheel
▶ twine
▶ build, pep517.build
▶ PyPI(warehouse)

8. PyPA が提供するツール

9. 配布物の形式
▶ ソースディストリビューション (sdist)
▶ tar ball
▶ zip
▶ バイナリディストリビューション (bdist)
▶ wheel

10. sdist
▶ ソースコードやドキュメントやメタデータファイルなどその
まま含まれる
▶ ビルド前の外部言語によるソース
▶ wheel を作成するための情報
▶ インストールされないドキュメントなどの情報
▶ テストコード

11. bdist
▶ 今は wheel のことだけ考えといてください
▶ そのまま zip 解凍などで展開するだけの状態
▶ インストールされるファイルだけが入っている

12. pip インストーラー
▶ PyPI や find-links から配布物 (sdist や bdist) をダウンロードし
てインストール
$ python get-pip.py
$ pip install pyramid

13. pip がどこにインストールするか
▶ pip の場所を pip --version で確認
▶ pip が入っている site-packages ディレクトリにインストー
ルされるはずです
▶ python で site.getsitepackages() も確認
▶ pip が入っている site-packages ディレクトリが含まれてい
ることを確認しましょう
$ pip --version
pip 21.3.1 from /home/aodag/works/.venv/lib/python3.9/site-
packages/pip (python 3.9)
$ python -c "import site;print(site.getsitepackages())"
['/home/aodag/works/.venv/lib/python3.9/site-packages', '/h
packages', '/home/aodag/works/.venv/lib/python3/dist-
packages', '/home/aodag/works/.venv/lib/python3.9/dist-
packages']

14. setuptools, wheel パッケージャー
▶ 配布物を作成する
▶ PEP517 に対応しているため build で配布物を作成可能
▶ PEP517 対応 (pyproject.toml) については後述
[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

15. build, pep517.build ビルダー
▶ 配布物を作成する
▶ プロジェクトごとに異なる作成方法に対応する
▶ pyproject.toml に書かれているツールを呼び出す
$ pip install build
$ python -m build .

16. twine アップローダー
▶ PyPI に配布物をアップロードする
▶ アップロード前のチェックや PyPI へのプロジェクト登録な
どもこれで
$ pip install twine
$ twine check `dist/*`
$ twine register `dist/*.whl`
$ twine upload `dist/*`

17. PyPI パッケージインデックス
▶ Python Package Index
▶ 配布物のインデックスや配布物自体をホスティング
▶ 昔はインデックスだけで別途ホスティングしてある配布物の
ダウンロードリンクを登録していた
▶ https://pypi.python.org

18. パッケージングして配布する

19. 配布物を作る（パッケージング）
▶ メタデータが必要
▶ sdist と bdist(wheel) の両方を PyPI に上げてくれるとユー
ザーはうれしい
▶ C 拡張を含む話はしません

20. ファイル
▶ 実際に配布したい Python モジュール以外に必要なファイル
▶ setup.py
▶ setup.cfg
▶ pyproject.toml
▶ MANIFEST.in
▶ README.{md,rst}
▶ LICENSE

21. setup.py
▶ 昔はここにメタデータを含めて必要なことを全部書いていた
▶ もうこれで十分
from setuptools import setup
setup()

22. setup.cfg metadata
▶ パッケージメタデータを書く
[metadata]
name = aodag_super_util
version = 0.1
author = Atsushi Odagiri
author_email = aodagx@gmail.com
url = https://git.example.com/aodag/super_util
license = MIT
description = file: README.md
description-content-type = text/markdown

23. setup.cfg options
▶ 配布物のオプションを書く
▶ 主に依存関係
[options]
packages = find:
install_requires =
pyramid
pyramid_jinja2

24. setup.cfg extras_require
▶ 追加の依存関係
[options.extras_require]
testing =
pytest
pytest-randomly
doc =
sphinx

25. setup.cfg find
▶ インストール対象のモジュールに関する情報
▶ ここでの package とは Python モジュールをまとめた
__init__.py を持つディレクトリのほう
[options.packages.find]
exclude =
tests
examples

26. 依存関係
install_requires
▶ 依存ライブラリを書く
▶ バージョンを直接指定しないように
▶ 最低限必要なバージョンなどの範囲指定に留めましょう
extras_require
▶ 追加機能としての依存ライブラリを書く
▶ デフォルトとしてインストールされない
▶ 開発時に利用する依存ライブラリもここに書いちゃう

27. pyproject.toml
▶ PEP517 のビルドフローで setuptools を利用するための設定
[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

28. MANIFEST.in
▶ sdist に含めたい (含めたくない) ファイルを設定
recursive-include aodag/specialutils/templates *.html
exclude *.swp *~

29. MANIFEST.in のオプション
▶ 主なものだけ distutils から抜粋
Command Description
include pat1 pat2 … マッチするファイルを全部含める
exclude pat1 pat2 … マッチするファイルを全部除外する
recursive-include
dir pat1 pat2 …
指定ディレクトリ以下のマッチする
ファイルを再帰的に含める
recursive-exclude
dir pat1 pat2 …
指定ディレクトリ以下のマッチする
ファイルを再帰的に除外する

30. README を setup.cfg に活かす
▶ README{.md,.rst} の内容をメタデータの description に使う
[metadata]
...
description = file: README.md
description_content_type = text/markdown

31. README{.md,.rst}
▶ markdown か reStructured text か？
▶ デフォルトは reStructured text
▶ PEP 566 でフォーマットを指定できるようになった
▶ PyPI では markdown を利用できるようになった
▶ お好きな方でどうぞ

32. LICENSE
▶ 必ずつけましょう
▶ メタデータにも書いておきましょう
▶ ライセンスごとの identifier は spdx を参照してください
[metadata]
...
license = MIT

33. どうしてこんなにファイルが必要？
▶ 歴史的経緯 です＞＜
▶ distutils から setuptools 導入当初 setup.py に全部書く
▶ setuptools の改善 メタデータは setup.cfg に書く
▶ PEP517 対応 pyproject.toml に build 設定を書く

34. もういらない？
▶ setup.py
▶ editable インストールに必要
▶ PEP660 で解決される予定
▶ setup.cfg
▶ パッケージメタデータを書くのに必要
▶ PEP621, PEP631 で解決される予定
▶ MANIFEST.in
▶ setuptools_scm を使うことで不要になる
▶ バージョン管理下のファイルは全部 sdist に入れてしまえ

35. setuptools_scm
▶ scm(git など) で管理しているファイルを sdist に含めるよう
になる
▶ scm(git など) のタグやリビジョンを元に version を生成して
くれる
# pyproject.toml
[build-system]
requires = ["setuptools>=45", "wheel", "setuptools_scm>=6.2
[tool.setuptools_scm]

36. package data
▶ こういうソースコード以外のファイルもありますよね？
▶ HTML テンプレート
▶ サンプルデータやシード
▶ setuptools_scm を使わない場合、MANIFEST.in に書かないと
sdist に入らないので結果的にインストールされません
▶ ２箇所あるので気をつけましょう
▶ MANIFEST.in で sdist に含める
▶ setup.cfg で options.include_package_data を True にする
[options]
include_package_data = True

37. package data を参照する方法
▶ pkg_resource を使う
▶ pkg_resources は setuptools に含まれることに注意
▶ __file__ からファイルパスを導出する

38. package data を pkg_resources で読み込む
▶ pkg_resources の resource_string や resource_stream
を使って読み込む
▶ pkg_resources は setuptools に含まれるモジュールであ
ることに注意
▶ 依存関係に setuptools を含めることになります
import pkg_resources
hello_html = pkg_resources.resource_string(__name__, "templ

39. package data を __file__ を使って読み込む
▶ __file__ を使うなら標準モジュールのみで実現できます
▶ pathlib を使うのも良いでしょう
here = os.path.dirname(__file__)
with open(os.path.join(here, "templates", "hello.html")) as
hello_html = f.read()

40. editable インストール
▶ 開発対象のソースコードが site-packages にコピーされな
いようにします
▶ 開発中は editable install で依存ライブラリをインストールで
きます
$ pip install -e .
$ pip freeze

41. 配布物を作る前に
▶ テストはしておきましょう
▶ テスト用の依存関係は testing などの名前で extras-require に
しておくと楽です
▶ 様々な python バージョンに対してテストする場合は tox や
nox の利用を検討しましょう
$ pip install -e .[testing]
$ pytest

42. build で配布物を作る
▶ build を使って配布物を作成します
▶ dist ディレクトリ以下に sdist と wheel が作成されます
$ python -m build .
$ ls dist

43. 配布する
▶ 大きく公開する場合は twine を使って PyPI にアップロードし
ます
▶ 事前に PyPI アカウントを作っておきましょう
▶ プライベートリリースなどでは simple repository にすると面
倒が減るかもしれません
▶ 今回は説明しません
$ python -m twine upload dist/*.whl

44. まとめ

45. まとめ
▶ パッケージングのアクションごとに別々のツールが提供され
ている
▶ PEP 標準に準拠するように setuptools もがんばっている
▶ setuptools が持っていた機能を PEP で練り直して標準化して
いる

46. 参考文献
▶ Python Packaging User Guide
▶ setuptools Documentation
▶ Distributing Python Modules (Legacy version)
▶ SPDX License List
▶ PEPs
▶ PEP 427 – The Wheel Binary Package Format 1.0
▶ PEP 503 – Simple Repository API
▶ PEP 517 – A build-system independent format for source trees
▶ PEP 518 – Specifying Minimum Build System Requirements for
Python Projects
▶ PEP 621 – Storing project metadata in pyproject.toml
▶ PEP 566 – Metadata for Python Software Packages 2.1
▶ Welcome to the tox automation project
▶ Welcome to Nox