みんなのPython勉強会#77 パッケージングしよう
0 likes3,941 views
2022/01/27 みんなのPython勉強会#77 「パッケージングしよう」の発表資料です
![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']](https://image.slidesharecdn.com/slide-220127113224/85/Python-77-13-320.jpg)
![setuptools, wheel パッケージャー
▶ 配布物を作成する
▶ PEP517 に対応しているため build で配布物を作成可能
▶ PEP517 対応 (pyproject.toml) については後述
[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"](https://image.slidesharecdn.com/slide-220127113224/85/Python-77-14-320.jpg)
![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](https://image.slidesharecdn.com/slide-220127113224/85/Python-77-22-320.jpg)
![setup.cfg options
▶ 配布物のオプションを書く
▶ 主に依存関係
[options]
packages = find:
install_requires =
pyramid
pyramid_jinja2](https://image.slidesharecdn.com/slide-220127113224/85/Python-77-23-320.jpg)
![setup.cfg extras_require
▶ 追加の依存関係
[options.extras_require]
testing =
pytest
pytest-randomly
doc =
sphinx](https://image.slidesharecdn.com/slide-220127113224/85/Python-77-24-320.jpg)
![setup.cfg find
▶ インストール対象のモジュールに関する情報
▶ ここでの package とは Python モジュールをまとめた
__init__.py を持つディレクトリのほう
[options.packages.find]
exclude =
tests
examples](https://image.slidesharecdn.com/slide-220127113224/85/Python-77-25-320.jpg)
![pyproject.toml
▶ PEP517 のビルドフローで setuptools を利用するための設定
[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"](https://image.slidesharecdn.com/slide-220127113224/85/Python-77-27-320.jpg)
![README を setup.cfg に活かす
▶ README{.md,.rst} の内容をメタデータの description に使う
[metadata]
...
description = file: README.md
description_content_type = text/markdown](https://image.slidesharecdn.com/slide-220127113224/85/Python-77-30-320.jpg)
![LICENSE
▶ 必ずつけましょう
▶ メタデータにも書いておきましょう
▶ ライセンスごとの identifier は spdx を参照してください
[metadata]
...
license = MIT](https://image.slidesharecdn.com/slide-220127113224/85/Python-77-32-320.jpg)
![setuptools_scm
▶ scm(git など) で管理しているファイルを sdist に含めるよう
になる
▶ scm(git など) のタグやリビジョンを元に version を生成して
くれる
# pyproject.toml
[build-system]
requires = ["setuptools>=45", "wheel", "setuptools_scm>=6.2
[tool.setuptools_scm]](https://image.slidesharecdn.com/slide-220127113224/85/Python-77-35-320.jpg)
![package data
▶ こういうソースコード以外のファイルもありますよね？
▶ HTML テンプレート
▶ サンプルデータやシード
▶ setuptools_scm を使わない場合、MANIFEST.in に書かないと
sdist に入らないので結果的にインストールされません
▶ ２箇所あるので気をつけましょう
▶ MANIFEST.in で sdist に含める
▶ setup.cfg で options.include_package_data を True にする
[options]
include_package_data = True](https://image.slidesharecdn.com/slide-220127113224/85/Python-77-36-320.jpg)
![配布物を作る前に
▶ テストはしておきましょう
▶ テスト用の依存関係は testing などの名前で extras-require に
しておくと楽です
▶ 様々な python バージョンに対してテストする場合は tox や
nox の利用を検討しましょう
$ pip install -e .[testing]
$ pytest](https://image.slidesharecdn.com/slide-220127113224/85/Python-77-41-320.jpg)
みんなのPython勉強会#77 パッケージングしよう
- 1. パッケージングしよう Start Python Club みんなの Python 勉強会#77 Atsushi Odagiri 2022-01-27
- 2. はじめに
- 3. お前誰よ ▶ aodag ▶ Atsushi Odagiri ▶ 株式会社オープンコレクター ▶ python1.5 とかから
- 4. アジェンダ ▶ Python パッケージングのエコシステム ▶ パッケージングして配布する
- 6. PyPA ▶ Python Packaging Authority ▶ パッケージング関連の PEP(Python Enhancement Proposal) を提案 ▶ パッケージング関連ツールの保守
- 7. PyPA が提供するツール ▶ pip ▶ setuptools ▶ wheel ▶ twine ▶ build, pep517.build ▶ PyPI(warehouse)
- 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 = [email protected] 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