Python Poetry is an open-source tool that assists developers with constructing and managing a Python application or library. It offers a command line interface for quickly installing and managing packages, and additionally takes charge of the dependencies and packages of a project. Moreover, Poetry integrates with virtual environments, granting developers the ability to manage both the environment and packages with one program. This guarantees that each project will have its own distinct set of dependencies and packages, while diminishing the possibilities of compatibility or conflict issues.

Install Poetry using pip by simply running:

$ pip install --user poetry

or

$ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python

This will install the latest version of poetry on your local machine.

To create a new project using poetry run:

$ poetry new project-name

This will create a directory with the given name with following files and sub-directory in bellow structure:

project-name/
├── README.rst
├── project_name
│   └── __init__.py
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_project_name.py

If you already have your project and want to initial poetry do:

$ cd existing-project
$ poetry init

This will create just the `pyproject.toml`. pyproject.toml is a configuration file used by Poetry, a package manager for Python. This file contains information about the project and its dependencies, as well as other configuration settings for Poetry. The pyproject.toml file is created in the root directory of a project when using Poetry, and it stores information such as the project name, version, description, author, and license. It also lists the dependencies of the project, including their versions and any additional information needed to manage them.

With pyproject.toml, developers can specify all the information needed for a project in a single file, making it easier to manage and share the project with others. The file can be used by Poetry to create a virtual environment, install dependencies, and build and distribute packages.

This is a sample pyproject.toml file content:

[tool.poetry]
name = "project-name"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]
readme = "README.md"
packages = [{include = "project_name"}]

[tool.poetry.dependencies]
python = "^3.10"
requests = "^2.28.2"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

• [tool.poetry]: This is a set of basic project metadata like name, version description, and author. This information is necessary if you would like to publish your project as a package on PyPI.
• [tool.poetry.dependencies]: This is a list of project dependencies. On fresh projects, it lists only the Python version but can also include all package versions that normally would be described in the requirements.txt file.
• [tool.poetry.dev-dependencies]: This is a list of dependencies that require local development, like testing frameworks or productivity tools. It is common practice to have a separate list of such dependencies as they are usually not required in production environments.
• [build-system]: Describes Poetry as a build system used to manage the project.

To add new package for your project run:

$ poetry add <pakcage-name>

This will download, install this package and add its name as an entry in [tool.poetry.dependencies]

To freeze the Python dependencies when you are satisfy about your working project do:

$ poetry lock

This will create the file poetry.lock and store all required dependencies and their transitive dependencies we well.

Install update dependencies

Once there is a pyproject.toml file you can install/update all the specified dependencies.

$ poetry install
$ poetry update

# for production
$ poetry install --no-dev

Create and publish packages

You can use poetry to build python packages with:

$ poetry build

This will create both a whl and .tar.gz files. And then you can also upload it to PyPI with:

$ poetry publish

Conclusion

Poetry makes it easier for developers to deploy and publish their applications. It is fast at creating .lock files compared to pipenv. Writing setup.py/setup.cfg for the Python modules is also not required anymore.

poetry is a tool that every Python developer need. To know more about Poetry see its official documentation and source code:

• Poetry documentation
• https://github.com/python-poetry/poetry