poetry new

新規にパッケージを作成する場合は poetry newする

$ poetry new poetry-demo
$ tree poetry-demo/
poetry-demo/
├── README.rst
├── poetry_demo
│   └── __init__.py
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_poetry_demo.py

• poetry-demoというディレクトリが作成される
• その下にパッケージ用（poetry_demo）とテスト用（tests）のディレクトリが作成される。パッケージ名の - は自動的に _ に変換されるみたい
• README.rstが空の状態で作成される。README.mdに変更してもよい
• pyproject.tomlが作成される。今後いろいろ変更を追加していく設定ファイル

poetry init

既存のディレクトリをpoetryでパッケージ化する場合は poetry init する

$ cd ディレクトリ名
$ poetry init

This command will guide you through creating your pyproject.toml config.

• pyproject.toml を作成するためのダイアログが表示されるので、聞かれたことに従って内容を入力する。pyproject.tomlの内容は、あとで直接編集できるので、間違えてしまっても気にしなくてよい。
• ディレクトリの構造は poetry new した時のディレクトリ構造と同じになっているとよい

poetry add

パッケージの動作に必要な外部パッケージをインストールする場合は poetry add する

$ poetry add pandas
$ poetry add plotly
$ poetry add kaleido==0.2.1

• 仮想環境に外部パッケージがインストールされる
  • poetry.lockが作成される
• pyproject.tomlの[tool.poetry.dependencies]セクションにパッケージ名が追加される
  • 基本的に最新のバージョンが追加される
  • バージョンを指定して追加することもできる
• 開発時にしか使わないモジュールは poetry add -Dを使う

poetry run

作成したスクリプトを実行する場合は poetry run する

$ poetry run python raw2csv.py
$ poetry run ./raw2csv.py
$ poetry run pytest

• 仮想環境の外から実行する場合に poetry run をつける必要がある
• スクリプトに実行権限が付いている場合は、直接引数に指定すればOK
• 外部パッケージのコマンドも同様に使うことができる
• 仮想環境内のシェルを起動する場合は poetry shell する

poetry install

依存するパッケージをすべてインストールする場合は poetry install する

$ poetry install

• poetry.lockの内容に書かれたファイルをインストールする
• poetry.lockがない場合は、pyproject.tomlに書いてあるパッケージ（とバージョン）をインストールする
• デフォルトでは自作パッケージもインストールされる
  • このとき、ディレクトリ構造が poetry newしたときと同じ構造でないとエラー（No file / folder found for pakage パッケージ名）がでて、正しくインストールできない
• 自作パッケージをインストールしたくない場合は poetry install --no-rootする

poetry.lock

• poetryを使っってインストールしたパッケージ情報を管理するためのロックファイル
• このファイルを共有することで、異なる端末にも同様の開発環境（パッケージとバージョン）を整えることができる
• gitリポジトリにコミットしておくとよい

poetry update

パッケージの依存関係を更新する場合は poetry update する

$ poetry show --outdated

• 更新が必要なパッケージを確認できる

$ poetry update

• pyproject.tomlに書いてあるパッケージに該当するバージョン（の最新の版）を取得して、poetry.lockを更新する
• ドキュメントによるとpoetry.lockを削除して、再度poetry installするのと同様のことをしているそう

pyproject.toml

poetryの設定は[tool.poetry]セクションに追記する

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

[tool.poetry]
name = "パッケージ名"（必須）
version = "0.1.0"（必須）
description = ""（必須）
license = "MIT"
authors = "名前 <メールアドレス>"（必須）
maintainers = ""
readme = "README.md"
homepage = ""
repository = ""
documentation = ""
keywords = ""
classifiers = []
packages = []
include = []
exclude = []

• （必須）と書いた項目以外はオプショナル
• それぞれの項目の設定内容はあとで調べる

コマンドラインツール化

作成したパッケージをコマンドラインツールとして使いたい場合はpyproject.tomlの[tool.poetry.scripts]セクションに追加する

[tool.poetry.scripts]
snapsheets = "snapsheets.core:cli"
snapsheets-next = "snapsheets.next:cli"

• パッケージにあるファイル名:関数名を設定する
• 上記の設定だと snapsheets/core.pyのcli()という名前の関数が、snapsheetsというコマンドで実行できるようになる
• コマンドは複数設定することができる。上の例では、次のリリースに向けていろいろ試している snapsheets-next を追加している

poetry check

pyproject.tomlの内容に書き間違いがないかpoetry checkする

$ poetry check
All set!

poetry build

PyPIにアップロードするファイルをビルドするには poetry buildする

$ poetry build
Building haniwers (0.0.5)
  - Building sdist
  - Built haniwers-0.0.5.tar.gz
  - Building wheel
  - Built haniwers-0.0.5-py3-none-any.whl

• wheel形式とsdist形式のファイルが dist/ に作成される
  • 削除する場合は rm -r distする
• -f [wheel/sdist] でビルド形式を指定することができる

poetry publish

PyPIやTestPyPIにパッケージを公開するには poetry publish する

$ poetry publish
$ poetry publish -r testpypi

• デフォルトの公開先は PyPI になっている
• -r リポジトリ名で公開先を指定することができる
• リポジトリ名は以下のようにして設定する

$ poetry config repositories.testpypi https://test.pypi.org/legacy/

poetry config

poetryの設定を確認したり、変更したりするには poetry config する

$ poetry config --list
cache-dir = "/Users/shotakaha/Library/Caches/pypoetry"
experimental.new-installer = false
installer.parallel = true
virtualenvs.create = true
virtualenvs.in-project = null
virtualenvs.path = "{cache-dir}/virtualenvs"  # /Users/shotakaha/Library/Caches/pypoetry/virtualenvs

• デフォルトの設定は上記のようになっている
• 設定は ~/Library/Application Support/pypoetry/config.toml に書いてある
• PyPI / TestPyPI の設定はここに表示されないみたい（どこにいったんだろう？）

poetry env

現在の仮想環境で使っている Pythonのバージョンなどを確認したり、変更したりする場合は poetry env する

$ poetry env info

Virtualenv
Python:         3.9.13
Implementation: CPython
Path:           /Users/shotakaha/Library/Caches/pypoetry/virtualenvs/snapsheets-mU0WpA-6-py3.9
Valid:          True

System
Platform: darwin
OS:       posix
Python:   /opt/homebrew/opt/python@3.9/Frameworks/Python.framework/Versions/3.9

virtualenvsの作り方

$ poetry config virtualenvs.options.no-pip true
$ poetry config virtualenvs.options.no-setuptools true
$ poetry config virtualenvs.options.system-site-packages true

• 仮想環境を作成するときにvirtualenvs --no-pipオプションが渡される。poetryはvertualenvsに組み込まれたpipを使っているが、仮想環境に他のパッケージを追加したくない場合はtrueにするとよい。合わせてno-setuptools=trueにするとよい。
• 仮想環境を作成するときにvirtualenvs --no-setuptoolsオプションが渡される。setuptoolsがインストールされなくなる。Poetryにとっては問題ない。
• システムにインストールしたパッケージを使えるようにしたいのでsystem-site-packages=trueにした。