poetry¶

Package management tool. Manages dependencies, package setup and building using the standardized pyproject.toml file. This replaces the need for setup.py, requirements.txt, MANIFEST.in and Pipfile.*. Poetry isolates the virtualenv from the project.

New¶

Action	Code	Details
Start a new Python project	`poetry new --src $pkg`
Initialize poetry for pre-existing project	`poetry init`

Info¶

Action	Code	Details
List installed packages	`poetry show`
Get info about installed package	`poetry show $pkg`	Add `-v` for more info
Get path to package	`poetry run python -c "import $pkg; print($pkg.__file__)`

Add packages¶

Action	Code	Details
Add specific package(s)	`poetry add $pkg1 $pkg2`
Add package(s), force install latest	`poetry add $pkg1@latest`
Add a package for a specific version	`poetry add $pkg==1.0.1`
Add git dependency	`poetry add git+https://github.com/niekdt/actionsheets.git`
Add git dependency with version	`poetry add git+https://github.com/niekdt/actionsheets.git#0.1.0`
Add git dependency on branch	`poetry add git+https://github.com/niekdt/actionsheets.git#main`
Add local dependency	`poetry add ./my-package/`
Add local dependency archive	`poetry add ../my-package/dist/my-package-0.1.0.tar.gz`
Add a dev package	`poetry add -D $pkg`

Update packages¶

Action	Code	Details
Update poetry	`poetry self update`
Update specific package(s)	`poetry update $pkg1 $pkg2`
Update all packages	`poetry update`
Update all packages, including packages from (private) Git-SSH repositories with passphrase	`poetry update -vv`	Without the `-vv` option, poetry runs forever if a password is required for the SSH key

Remove packages¶

Action	Code	Details
Remove package(s)	`poetry remove $pkg1 $pkg2`
Remove dependencies not specified in lock file	`poetry install --sync`

Save state¶

Action	Code	Details
Generate lock file	`poetry lock`
Export environment as requirements.txt	`poetry export -f requirements.txt > requirements.txt`	Requires a plugin, install via: `poetry self add poetry-plugin-export`
Export environment as requirements.txt without hashes	`poetry export --without-hashes -f requirements.txt > requirements.txt`	Requires a plugin, install via: `poetry self add poetry-plugin-export`

Restore state¶

Action	Code	Details
Install all dependencies, but not the root project	`poetry install --no-root`	For `package.mode=false`, you can just run `poetry install`
Install the project (if package), and all dependencies defined in the lock or project file	`poetry install`
Install the project (if package), and all required dependencies, and remove unused dependencies (sync)	`poetry install --sync`
Install the project with dev dependencies	`poetry install --with dev`
Install the project (if package), and all dependencies, including optional dep group(s)	`poetry install --with docs,tests`
Install the project with verbose output for troubleshooting	`poetry -vvv install`

Continuous integration¶

For configuring authentication, see the Authentication section

Action	Code	Details
Install poetry and restore package project	`pip install poetry poetry install --with dev`
Use poetry with lockfile-based caching	`- uses: actions/cache@v3 with: path: ~/.cache/pypoetry key: ${{ hashFiles('poetry.lock') }}`
Run flake8	`poetry run flake8`
Run pytest	`poetry run pytest`

Config¶

Action	Code	Details
Use system Git client instead of Dulwich	`poetry config experimental.system-git-client true`
Use system Git client instead of Dulwich	`export POETRY_EXPERIMENTAL_SYSTEM_GIT_CLIENT = true`

Authentication¶

Authentication for private repository or package access

HTTPS¶

Action Code Details

Set access token for private GitHub package foo installed via HTTPS

poetry config repositories.foo https://github.com/my_private_org/foo.git
poetry config http-basic.foo x-token-auth ${{ secrets.MY_TOKEN }}

Doesn't always work (??)

Set access token for private GitHub package foo installed via HTTPS

export POETRY_REPOSITORIES_FOO_URL = https://github.com/my_private_org/foo.git
export POETRY_HTTP_BASIC_FOO_USERNAME = x-token-auth
export POETRY_HTTP_BASIC_FOO_PASSWORD = ${{ secrets.MY_TOKEN }}

Set access token for private GitHub package foo installed via HTTPS

git config --global url."https://x-token-auth:${{ secrets.MY_TOKEN }}@github.com/my_private_org/foo".insteadOf "https://github.com/my_private_org/foo"

Fallback option

SSH¶

Action	Code	Details
Set access token for GitHub package installed via SSH (git@)	`?`	A solution is suggested in https://stackoverflow.com/a/78074270/22638740, but no supporting documentation
Use HTTPS access token for private GitHub packages from my_private_org that were added via SSH	`git config --global url."https://x-token-auth:${{ secrets.MY_TOKEN }}@github.com/my_private_org/".insteadOf "ssh://git@github.com/my_private_org/"`