poetry¶

TL;DR: poetry makes versioning your tools and distributing them super easy.

When we're building tools, we often depend on dozens of libraries. Those libraries can change! If you return to your tool in 2 years, you may find that installing newer versions of the dependencies breaks your original work.

So how do we ensure our work is future proof?

We have to ensure that our tools come with a list of requirements. This is usually kept in a pyproject.toml file, or sometimes a requirements.txt. Package managers like pip can usually parse these files and get you the right versions.

But, keeping up with those requirements is a pain.

Luckily poetry solves this for us. You can read more about poetry here, but I'll sum it up for you: https://python-poetry.org/

Using poetry is similar to using a virtual environment. All the packages are stored in a directory within your project, so you won't be able to use those versions outside.

1. Starting a new project with Poetry¶

Starting a new project with poetry is really easy. If you want to start completely from scratch

poetry new

will create some handy files and directory structures for you (e.g. a README, a src directory etc)

If you have an existing structure, you can use

poetry init

Both these commands will give you a pyproject.toml and a poetry.lock file. If anything, you will only ever interact with the pyproject.toml file. These files are tracking the specific dependencies of your project, and ensuring they all match and don't collide with each other.

2. Adding a new dependency¶

If you have a dependency in your project, e.g. numpy, you can add this dependency using

poetry add numpy

This is installing numpy for you, in a new directory. poetry will not use your normal install of numpy, it will use the one installed for this project.

You can specify particular versions when adding, you can also specify github urls to install tools.

If you have a dependency that is just for developing tools, you can make it a "development" dependency

poetry add -D numpy

You'll get errors if

• Your added packages don't work with the Python version you're using
• Your added packages don't work with each other (e.g. requiring different versions of dependencies)

3. Installing your package¶

If you want to use your package, you'll have to use the install command

poetry install

This will install everything that isn't already installed. If you have cloned a repo with a pyproject.toml and poetry.lock file, you can install the package and all the dependencies poetry install. Remember poetry is like a virtual environment, so this will only install the tools in this directory.

4. Using tools¶

Poetry is making a sort of virtual environment for you, where all the packages are seperate from the rest of your machine. So how do you use it? If you execute the following in a terminal

poetry add lightkurve
python
import lightkurve as lk

This will result in an error. It's going to use your local version of Python, and local installs. If you try to import any of the libraries you've set up with poetry add, you won't be able to access them, because they're not in your local installs.

Instead, we have to expressly as for poetry to run the command.

poetry add lightkurve
poetry run python
import lightkurve as lk

Specifying that poetry needs to run the command will let you use all the packages you added and installed with poetry. You need to do this with all commands you want to use your libraries. If, for example you wanted to use jupyter-lab, you would have to use

poetry add jupyterlab lightkurve
poetry run jupyter-lab

5. Distributing tools¶

This is where poetry is super handy. You can publish to PyPI, straight from your directory. When you're done with your development use

poetry publish

This will ask for your PyPI credentials, and will then publish your package to PyPI! Handy.

One thing to watch out for is versioning. Make sure you update your package version number before publishing, otherwise poetry will tell you that you can't overwrite the current version on PyPI.