- How to install Poetry
- How to customize Poetry
- How to create your first project
- How to work with pyproject.toml
- How to initialize a virtual environment
- Conclusions
In all projects in the Python profession, we suggest using the poetry tool. It can help you can manage dependencies. It is one of the most essential tools used by Python developers today.
Poetry is a simple and handy tool that makes it easy to maintain and develop projects. We advise you to design each learning experiment as a poetry project so that you get used to professional tools faster.
In this lesson, we'll look at how to work with Poetry. We'll go through the following steps:
- Installation
- Setting up
- Creating your first poetry project
- Working with
pyproject.toml
- Initializing a virtual environment
How to install Poetry
Poetry creators wrote it in Python, but it's not the usual Python program you install using pip install
. In the introductory section of the Poetry documentation you'll find commands to install the program on your operating system.
When you install Poetry, it'll be available as a separate command in the shell:
poetry --version
Poetry version …
That's all about installing the program. Before we create our first project, let's set up the tool to make it more convenient for us to work.
How to customize Poetry
If you ask for a list of Poetry settings immediately after installation, you'll see the following:
poetry config --list
cache-dir = "/…/…/.cache/pypoetry"
virtualenvs.create = true
virtualenvs.in-project = null
virtualenvs.path = "{cache-dir}/virtualenvs" # /home/astynax/.cache/pypoetry/virtualenvs
Poetry works with virtual environments. And it's initially set up in a way that means you'll have many different versions of Python. For this reason, the tool creates virtual environments for projects in an unusual location - note the virtualenvs.path
setting.
You can use the default settings, but Python developers usually store the virtual environment for each project in the project directory, specifically in the .venv
subdirectory.
Remember how you created environments with the python3 -m venv .venv
command. In Poetry, you should do the same:
poetry config virtualenvs.in-project true
Now every poetry project will have a virtual environment. For example, you can transfer a project from one machine to another by copying the directory.
Once we set up Poetry, it'll be ready for us to create our first project.
How to create your first project
Create a poetry project with the command poetry new NAME
. Before running Poetry, check if the python3
command is available in the system.
Suppose you entered the poetry new first
command first. It is what the result will look like:
poetry new first
Created package first in first
cd first # Navigate to the created directory
tree
.
├── first
│ └── __init__.py
├── pyproject.toml
├── README.md
└── tests
└── __init__.py
2 directories, 4 files
The message Created package first in first
package first in first means that a package called first
was created in a directory called first
with a corresponding __init__.py
. Any Poetry project will always contain at least one package. In addition to the first
package, the project already has a tests
package. We don't need it yet, but it's worth knowing that real projects always have a test package.
You'll also have a README.md
file in the actual project, which should contain the project description. This file has the .md
— extension, which means it's a Markdown file. It is a popular markup format. By the way, we wrote this lesson in it.
The most important file in the poetry project is pyproject.toml
. It is the file format TOML. You can read more about it here. The pyproject.toml
file contains the project configuration. The information from this file is needed so that Poetry can:
- Manage project dependencies
- Run code for execution
- Run development tools
- Build a distribution and publish it on PyPI
The more you work with Poetry, the better you are at publishing projects. You'll gradually get used to the fact that every package must have a description, a proper structure, and a specified version. We advise you to design projects according to these standards, even if you don't intend to publish the project in the index.
We've created our first project. Now we need to deal with pyproject.toml
.
How to work with pyproject.toml
The configuration file for a new project looks something like this:
[tool.poetry]
name = "first"
version = "0.1.0"
description = ""
authors = ["…"]
readme = "README.md"
[tool.poetry.dependencies]
python = "^3.10"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
Lines like [tool.poetry]
describe sections with key = value
pairs.
We cannot place most keys in other sections. You can study the keys in more detail and find out where they belong in the documentation. Here we'll look at lines like these:
tool.poetry
— describes the project from Poetry's perspective, where we store theversion
,description
, and thename
of the projecttool.poetry.dependencies
— stores a list of dependencies required for the code to work. Python itself will always be listed here. We can't run the code without it
The build-system
section indicates that we have a project managed by Poetry. That said, there are other tools to manage projects. The build-system
section looks different for them. All that's left is to deal with the last step - the initialization of the virtual environment.
How to initialize a virtual environment
Poetry realizes that it's time to create or update the environment. In this case, you can call poetry install
:
poetry install
Updating dependencies
Resolving dependencies...
Writing lock file
…
Installing the current project: first (0.1.0)
This command installs all dependencies in the environment in the .venv
directory inside the project.
The environment is activated with the command poetry shell
and terminated with exit
:
# Here is the list of packages installed in the system
pip list
Package Version
-------------------- ---------------
asciinema 2.2.0
attrs 22.1.0
blinker 1.4
# Here's a continuation of the big list
...
# As you can see, there are quite a few packages already in the system
# So we might run into a version conflict when installing the new package
# To avoid this, we use virtual environments
# We see the list of packages in the environment
Spawning shell within /../first/.venv
pip list
# The new environment has only the bare minimum necessary for Poetry to work
Package Version
---------- -------
pip 22.2.2
setuptools 65.3.0
wheel 0.37.1
It's often not necessary to activate the environment. Poetry offers a run
command which executes programs from within the environment. For example, it's customary within the project to launch the REPL with the poetry run python
command.
It is what working with Poetry looks like. It is a handy tool, so we recommend using it. Make your experiments look like Poetry projects. It will help you learn how to use Poetry faster.
Conclusions
- Poetry is a handy tool that simplifies project development and maintenance
- Poetry isn't installed via
pip install
, we use special commands found in the Poetry documentation to install it - Every project needs to have a virtual environment. Poetry needs to be pre-configured for this
- Each package must have a description and the correct structure and version assigned
Recommended materials
Are there any more questions? Ask them in the Discussion section.
The Hexlet support team or other students will answer you.
For full access to the course you need a professional subscription.
A professional subscription will give you full access to all Hexlet courses, projects and lifetime access to the theory of lessons learned. You can cancel your subscription at any time.