Manage Your Python Project Using Poetry

Things under legendu.net/outdated are outdated technologies that the author does not plan to update any more. Please look for better alternatives.

uv (implemented in Rust) is the new cool kid now and is prefer to poetry.

Tips and Traps¶

Python Poetry is current the best project management tool for Python!
Python Poetry supports Python package dependencies on GitHub. For example, if a Python package depends on https://github.com/dclong/dsutil, then you can add it using the following.
```
 :::bash
 poetry add git+https://github.com/dclong/dsutil.git
```
Or
```
 :::bash
 poetry add git+ssh://git@github.com/dclong/dsutil.git
```
For more details, please refer to poetry add and git dependencies .
poetry install removes non needed libraries. A tricky situation is that if you have dependency A which depends on dependency B, and you have specified both A and B in pyproject.toml. Removing dependency B from pyrpoject.toml and then running poetry install won’t remove the library B from the virtual environment as B is still needed by A.
Poetry has lots of issues in Windows currently. It is suggested that you avoid using poetry in Windows.
If you encounter the following error message when running poetry install,
[Errno 2] No such file or directory: ‘/path/to/readme.md’
it means that you have specified tool.poetry.readme to be readme.md in pyproject.toml but readme.md does not exists under root directory of the project.

Install Python Poetry¶

Follow the official tutorial.

Using xinstall.

 :::bash
 # install xinstall if it hasn't been installed
 sudo pip3 install -U git+https://github.com/dclong/xinstall@master
 # install poetry using xinstall
 xinstall pt -ic

Updating Python Poetry¶

Updating poetry to the latest stable version is as simple as calling the self:update command.

:::bash
poetry self:update

If you want to install prerelease versions, you can use the --preview option.

:::bash
poetry self:update --preview

Usage¶

Create/Initialize a New Project¶

Create a new Python project using poetry.
```
 :::bash
 poetry new proj
```
Initialize an existing Python project using poetry.
```
 :::bash
 poetry init
```

Install Dependencies¶

Installl all dependencies.
```
 :::bash
 poetry install 
```
Installl all but dev dependencies.
```
 :::bash
 poetry install  --no-dev
```

Export Dependencies¶

Export the lock file to requirements.txt so that the dependency can be installed using pip.
```
 :::bash
 poetry export -f requirements.txt > requirements.txt
```

Run Commands in the Virtual Environment¶

poetry run cmd is a quick to run cmd using the virtual environment managed by poetry. Another way is to manually set PATHbefore you invokecmd`. For example,

:::bash
PATH=.venv/bin:$PATH cmd

Run test suits using pytest.
```
 :::bash
 poetry run pytest
```
Or if you want to make it specific to collect test suits from the test directory under the root directory of the project.
```
 :::bash
 poetry run pytest test
```
Run pytype.
```
 :::bash
 poetry run pytype .
```

User Tasks¶

sdispater/poetry#591

sdispater/poetry#241

Configuration¶

https://python-poetry.org/docs/cli/#config

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

Pleaser refer to pyproject.toml for examples of configuration for Python Poetry.

Restrict Operating Systems in Python Poetry¶

How can I specify dependencies on operating system in Python Poetry?

[tool.poetry]
# ...
classifiers = [
    "Operating System :: POSIX :: Linux",
]

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

https://pypi.org/classifiers/

python-poetry/poetry#738

python-poetry/poetry#3356

References¶

https://codingdose.info/2018/08/02/develop-and-publish-with-poetry/

https://hackersandslackers.com/poetic-python-project-packaging/