Poetry#
Note
This page is a tutorial on how to use Poetry. It is not a tutorial on how to use Python.
Note
In most cases, you will not have to interact with poetry directly. The pyproject.toml
and poetry.lock
files are already set up for you. You can skip this page if you are not interested in learning how to use Poetry.
What is it?#
Poetry is a tool for dependency management and packaging in Python with a virtual environment.
Note
dependencies are libraries that your project depends on. For example, if you are using the requests library, then requests is a dependency of your project.
a virtual environment is a self-contained directory tree that contains a Python installation for a particular version of Python, plus a number of additional packages. Different virtual environments can have different versions of Python, and can have different sets of installed packages. Think of it as a standalone machine in simple terms.
It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.
Runs inside a virtual environment, so you don’t need to manage your own virtual environment.
Why use it?#
“I don’t know why its not working, it runs on my machine!”
It allows us to share code with others without worrying about library versions, since poetry will handle that for us.
It allows us to easily install our dependencies on a new machine.
Since it runs inside a virtual environment, it doesn’t pollute our global python environment.
It will work on every ones computer, since we are all using the same virtual environment.
Poetry vs Pip and Virtualenv#
Note
Pip is the default package manager for Python. It is used to install and manage Python packages.
This is what you use to install libraries like numpy, requests, etc to your computer.
Note
Virtualenv is a tool to create isolated Python environments. It is used to create virtual environments for your projects.
This is what you use to create a virtual environment for your project.
Pip is a package manager, not a dependency manager. It does not handle dependencies for you.
Virtualenv is a tool to create isolated Python environments. It does not handle dependencies for you.
Poetry is a package and dependency manager. It handles dependencies for you.
Poetry runs inside a virtual environment, so you don’t need to manage your own virtual environment.
In simple terms, Poetry is a combination of Pip and Virtualenv that runs seamlessly inside a virtual environment.
Poetry is the recommended tool for managing dependencies in Python With a virtual environment.
How to use it?#
Note
You will need to install Poetry on your machine first. If you have not done so, refer to the :Installation page for instructions on how to install Poetry.
Setup:#
Create a new project folder, or navigate to an existing project folder.
In the terminal, run the command
poetry init
. This will create a new poetry project.The terminal will ask you a series of questions about your project configuration. You can skip most of them by pressing enter.
Once you have finished, you should see a new file called
pyproject.toml
. This is the configuration file for your project.
Adding dependencies:#
to add dependencies, run the command
poetry add <dependency>
. For example,poetry add numpy
will add the numpy library to your project.to install all dependencies, run the command
poetry install
. This will install all dependencies in your project. This will also create a virtual environment for your project.use
poetry lock
to update thepoetry.lock
file. This file contains the exact versions of the dependencies that you are using. This is useful for sharing your project with others.
Important
Do not manually edit the poetry.lock
file. This file is automatically generated by poetry. If you want to update the poetry.lock
file, use poetry lock
.
Running your project:#
to run your project, use
poetry run <command>
. For example,poetry run python main.py
will run themain.py
file in your project. this will run the file inside the virtual environment, so you don’t need to worry about installing the dependencies with pip (though its recommended since autocompletion will not work on IDEs).to open a shell inside the virtual environment, use
poetry shell
. This will open a shell inside the virtual environment, so you can run commands without usingpoetry run
. To exit the shell, useexit
.
Note
a shell is a command line interface that allows you to run commands on your computer. For example, the terminal is a shell. by opening a shell inside the virtual environment, you can run commands without using poetry run
.
Updating dependencies:#
to update a dependency, use
poetry update <dependency>
. For example,poetry update numpy
will update the numpy library to the latest version.to update all dependencies, use
poetry update
. This will update all dependencies to the latest version.
How Choate Robotics uses Poetry:#
We use Poetry to manage dependencies in our projects.
Since all repositories are set up by the same template, all repositories have the same
pyproject.toml
andpoetry.lock
files. Meaning the general dependencies are already installed.We add more dependencies as needed.