Poetry, A Better Version of Python Pipenv

What is Poetry

Poetry is similar to Pipenv. It is a Python virtual environment and dependency management tool. In addition, it also provides package management functions, such as packaging and publishing. You can think of it as a superset of Pipenv and Flit. It allows you to use Poetry to manage Python libraries and Python programs at the same time.

• Homepage

• Source code

• Documentation

Installation

The official recommended installation command is to use the built-in get-poetry.py script, using curl:

$ curl -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py | python
Retrieving Poetry metadata
...
Poetry(1.1.12) is installed now. Great!

To configure your current shell, run `source $HOME/.poetry/env`

Or download the installation script get-poetry.py directly and execute it locally.

After installation, you can use the following command to confirm the installation is successful:

$ poetry --version
Poetry 1.1.12

Basic Usage

The usage of Poetry is very simple, most of the commands are similar to Pipenv. However, we need to understand some basic concepts and tips first:

• Use the new standard pyproject.toml file introduced by PEP 518 to manage the dependency list and various meta information of the project, which is used to replace various configuration files such as Pipfile, requirements.txt, setup.py, setup.cfg, MANIFEST.in, etc.

• There are two types of dependencies, production environment, and development dependencies.

• Instead of updating your locked dependency version at any time like Pipenv, the locked dependency is stored in the poetry.lock file (this file will be automatically generated). So, remember to put your poetry.lock file into version control.

• Execute poetry or poetry list command to view all available commands.

Existing Project

If you are using Poetry in an existing project, you only need to execute the poetry init command to create a pyproject.toml file:

$ poetry init

Enter your project information according to its prompts, press Enter to use the default value if you are uncertain, and you can also manually update it later. The link of specifying dependencies can be skipped, and manual installation will be more efficient.

New Project

If you want to create a new Python project, use the poetry new command to create a project template:

$ poetry new foo

The above command will create the following project structure:

If you want to use the src folder, you can add the --src option, which will nest the package in the src folder.

Create Virtual Env

Use the poetry install command to create a virtual environment (make sure there is a pyproject.toml file in the current directory):

$ poetry install

The output looks like

This command will read all dependencies (including development dependencies) in pyproject.toml and install them. If you don't want to install development dependencies, you can add the--no-dev option. If there is a poetry.lock file in the root directory of the project, the locked version of the dependencies listed in this file will be installed. If the virtual environment is not detected when the add/remove command is executed, the virtual environment will be automatically created for the current directory.

Activate Virtual Env

Executing the command at the beginning of poetry does not need to activate the virtual environment, because it will automatically detect the current virtual environment. If you want to quickly execute commands in the virtual environment corresponding to the current directory, you can use the poetry run command, for example:

$ poetry run python app.py

If you want to activate the virtual environment explicitly, use the poetry shell command:

$ poetry shell

Install Packages

Use the poetry add command to install the package:

$ poetry add flask

Adding the --dev parameter can be specified as a development dependency:

$ poetry add pytest --dev

Tracking & Update Package

Use the poetry show command to view all installed dependencies (you can pass the package name as a parameter to view the information of a specific package):

$ poetry show

Add --tree option to view dependencies:

$ poetry show --tree

Add --outdated to view the dependencies that can be updated:

$ poetry show --outdated

Execute the poetry update command to update the dependencies of all locked versions:

$ poetry update

If you want to update a specific dependency, pass the package name as a parameter:

$ poetry update foo

Uninstall package

Use poetry remove <package name> to uninstall a package:

$ poetry remove foo

Build and Publish

It is mainly used to package python files. The packaged product has two package formats: sdist is the source code format; wheel is the compiled format.

$ poetry build

To publish:

$ poetry config http-basic.pypi username password
$ poetry publish

If your company has its own private repository, you can upload it in the following way:

$ poetry config repositories.foo https://foo.bar/simple/
$ poetry config http-basic.foo username password
$ poetry publish -r my-repository

Conclusion

List some of the advantages and disadvantages I have learned:

Advantages

• Use standard pyproject.toml file, no need to write multiple configuration files

• Supports management of Python programs and Python libraries at the same time

• More intuitive default design, such as not updating the dependencies of locked versions casually

• Clean and concise command line output

• When uninstalling the package, you directly uninstall the isolated sub-dependency, you don’t need to execute pipenv clean again like Pipenv.

Disadvantages

• The word “poetry” is a bit hard to type

• There will be some potential bugs

• The management control of the virtual environment is somewhat weak, and there is no such thing as Pipenv to delete the virtual environment and clear dependencies.

• Lack of a stable maintenance team, there are a large number of issues and PRs waiting to be processed, but the situation is getting better

Of course, you can still choose to continue to use basic tools such as virtualenv/venv and pip until a perfect solution appears. Or, you can choose to try something new, and then try to improve it.

And that’s it for this topic. Thank you for reading.