# Python : Poetry
\[ [pypi](https://pypi.org/project/poetry/) | [src](https://github.com/python-poetry/poetry/) | [docs](https://python-poetry.org/docs) ]
#### Installing Poetry
```bash
curl -sSL https://install.python-poetry.org | python3 -
...installs ~/.local/bin/poetry -> ~/.local/share/pypoetry/venv/bin/poetry
~/.local/share/pypoetry/...
~/.config/pypoetry/poetry.lock
~/.config/pypoetry/pyproject.toml
poetry completions bash >> ~/.bash_completion
poetry self update
```
For existing projects:
```bash
poetry init # interactively create pyproject.toml
```
For new projects:
```bash
poetry new <proj> # creates <proj> directory
<proj>
├── pyproject.toml
├── README.md
├── <proj>
│ └── __init__.py
└── tests
└── __init__.py
```
#### CLI
```bash
poetry install # install packages based on poetry.lock or pyproject.toml
poetry shell # enter venv
poetry add <package> # uses latest version
poetry add <package>@<version>
poetry remove <package>
poetry show # list installed packages
poetry update # upgrade all packages to latest allowable version
poetry lock --no-update # sync poetry.lock to pyproject.toml without upgrades
poetry lock --check
poetry check # validates pyproject.toml
poetry env info
Virtualenv
Python: 3.11.4
Implementation: CPython
Path: /home/ofer/.cache/pypoetry/virtualenvs/tmp-1_SiHPKw-py3.11
Executable: /home/ofer/.cache/pypoetry/virtualenvs/tmp-1_SiHPKw-py3.11/bin/python
Valid: True
System
Platform: linux
OS: posix
Python: 3.11.4
Path: /home/ofer/.pyenv/versions/3.11.4
Executable: /home/ofer/.pyenv/versions/3.11.4/bin/python3.11
poetry env info --path
/home/ofer/.pyenv/versions/3.11.4
```
#### Installing Packages
```bash
# Install all non-optional package groups + the project itself.
# (See pyproject.toml section below for an example of marking a group optional.)
$ poetry install
# Include an optional group.
$ poetry install --with foo
# Exclude a non-optional group.
$ poetry install --without dev
# Only install specific groups.
$ poetry install --only foo
# Disable color and interactin for automatic installs.
$ poetry install --no-ansi --no-interaction
# Ensures the packages in poetry.lock are the only ones present in the environment,
# removing anything that’s not necessary.
$ poetry sync
```
To prevent Poetry from installing the project itself as a package, either:
- use `--no-root` arg
- set `tool.poetry.package-mode = false` in `pyprojet.toml`
#### pyproject.toml
```toml
[ tool.poetry ]
name = "foo"
version = "0.1.0"
description = ""
authors = [ "Ofer Nave <
[email protected]>" ]
license = "WTFPL"
readme = "README.md"
[ tool.poetry.dependencies ] # "main" group dependencies
python = "^3.11"
alembic = "^1.12.1"
Flask = "^3.0.0"
SQLAlchemy = "^2.0.22"
[ tool.poetry.group.dev.dependencies ] # "dev" group dependencies
pytest = "^7.4.3"
[ tool.poetry.group.foo ] # "foo" group
optional = true
[ tool.poetry.group.foo.dependencies ] # "foo" group dependencies
...
[ build-system ]
requires = [ "poetry-core" ]
build-backend = "poetry.core.masonry.api"
```
> [!info]
> The list of link names recognized & assigned special icons by PyPI:
> https://github.com/pypi/warehouse/blob/main/warehouse/templates/packaging/detail.html
#### Version Specifiers
Can specify multiple specifiers separated by commas.
```
# caret
^x.y.z # will not increment left-most non-zero digit
^1.2.3 # equiv to: >=1.2.3, <2.0.0
^0.2.3 # equiv to: >=0.2.3, <0.3.0
# tilde
~x # will only increment y.z
~x.y # will only increment z
~x.y.z # will only increment z
# wildcard
*
x.*
x.y.*
# equality
{== != > >= < <=} x[.y[.z]]
# repo-based
= { git = "
[email protected]:<ORG>/<REPO>.git", branch = "<BRANCH>" }
= { git = "
[email protected]:<ORG>/<REPO>.git", tag = "<TAG>" }
```
## Publishing
```python
# on Ubuntu 22.04, token is stored in OS keyring, not ~/.config/pypoetry/config.toml
poetry config pypi-token.pypi <my-token> # preferred
poetry config http-basic.pypi <username> <password>
poetry build
poetry publish
```
Get API token from: PyPI > Account settings > API tokens
To confirm your token was stored in your OS keyring:
```bash
~/.local/share/pypoetry/venv/bin/python /usr/bin/keyring get poetry-repository-pypi __token__
```