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:#

  1. Create a new project folder, or navigate to an existing project folder.

  2. In the terminal, run the command poetry init. This will create a new poetry project.

  3. The terminal will ask you a series of questions about your project configuration. You can skip most of them by pressing enter.

  4. Once you have finished, you should see a new file called pyproject.toml. This is the configuration file for your project.

Adding dependencies:#

  1. to add dependencies, run the command poetry add <dependency>. For example, poetry add numpy will add the numpy library to your project.

  2. 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.

  3. use poetry lock to update the poetry.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:#

  1. to run your project, use poetry run <command>. For example, poetry run python main.py will run the main.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).

  2. 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 using poetry run. To exit the shell, use exit.

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:#

  1. to update a dependency, use poetry update <dependency>. For example, poetry update numpy will update the numpy library to the latest version.

  2. to update all dependencies, use poetry update. This will update all dependencies to the latest version.

How to share your project with others?#

  1. to share your project with others, you need to share the pyproject.toml and poetry.lock files. These files contain the configuration and dependencies of your project.

  2. When someone else wants to run your project, they need to run poetry install. This will install all dependencies in the poetry.lock file. This will also create a virtual environment for your project.

  3. They can now run your project using poetry run <command>.

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 and poetry.lock files. Meaning the general dependencies are already installed.

  • We add more dependencies as needed.