Skip to content

Python Poetry

Poetry is a dependency management and package building tool for Python projects. It simplifies the creation and management of virtual environments, as well as allowing for the specification and installation of dependencies in a simple way.

1. Installing Poetry

1.1. Using the Installer

To install Poetry, you can use the following command in your terminal:

curl -sSL https://install.python-poetry.org | python3 -

1.2. Verifying the Installation

After installation, verify that Poetry was installed correctly with:

poetry --version

2. Poetry Structure

2.1. Project Directory

When you create a new project with Poetry, it generates a directory structure with a pyproject.toml file, which is the main configuration file for your project.

2.2. pyproject.toml File

The pyproject.toml file is where you define your project's settings, including metadata and dependencies.

[tool.poetry]
name = "my_project"
version = "0.1.0"
description = "A brief description of my project."
authors = ["Your Name <your.email@example.com>"]
license = "MIT"
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.25.1"
flask = "^2.0.1"

[tool.poetry.dev-dependencies]
pytest = "^6.2.4"
black = "^21.6b0"

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

Field Explanation

  • [tool.poetry]: Main section where project information is configured.
  • name: Project name.
  • version: Project version.
  • description: A brief description of what the project does.
  • authors: List of project authors.
  • license: Project license.

  • readme: Path to the project's README file.

  • [tool.poetry.dependencies]: List of project dependencies.

  • python: Specifies the required Python version.
  • requests: Example of a project dependency.

  • flask: Another dependency example.

  • [tool.poetry.dev-dependencies]: Dependencies needed only for development.

  • pytest: Testing tool.

  • black: Code formatter.

  • [build-system]: Defines the project's build system.

  • requires: Dependencies required to build the project.
  • build-backend: Specifies the build backend to be used.

3. Basic Poetry Commands

3.1. Creating a New Project

To create a new project, use:

poetry new project-name

This will create a basic directory structure:

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

3.2. Adding Dependencies

To add a dependency to your project, use:

poetry add package-name

For example, to add the requests package:

poetry add requests

3.2.1. Adding Development Dependencies

To add a dependency for development only, use the --dev flag:

poetry add --dev package-name

3.3. Removing Dependencies

To remove a dependency, use:

poetry remove package-name

3.4. Installing Dependencies

To install all dependencies listed in pyproject.toml, use:

poetry install

3.5. Updating Dependencies

To update the project's dependencies, use:

poetry update

4. Managing Virtual Environments

Poetry automatically creates a virtual environment for your project. To activate the virtual environment, use:

poetry shell

To run a command inside the virtual environment without activating it, you can use:

poetry run command-name

5. Execution Scripts

You can define scripts in your pyproject.toml file to run custom commands. For example:

[tool.poetry.scripts]
my_script = "module:function"

To run the script, use:

poetry run my_script

6. Publishing Packages

If you want to distribute your package, you can publish it to PyPI:

  1. First, make sure the information in pyproject.toml is correct.
  2. Log in to your PyPI account:
poetry config pypi-token.pypi <TOKEN>
  1. Publish your package:
poetry publish

7. Conclusion

Poetry simplifies dependency management and package building in Python projects. For more information and detailed documentation, you can visit the official Poetry documentation.

8. Additional Resources

These resources can help you delve deeper into using Poetry and its features.