PyEnv & Poetry - BFFs 💖

What is this?

This is a resource made, admittedly mostly for myself, that will allow me to recall a method of Python dev environment management I don't dislike. It covers the use of two distinct but important Python environment helpers:

• PyEnv (Docs)
  • Uses path shims to help you manage several versions of Python simultaneously.
• Poetry (Docs)
  • A dependency manager that feels similar in my approximation to a tool like yarn or npm from the Node world, and automates certain tasks (venv creation and activation for example).

Why make this / why read this?

• You find that managing Python projects in a clean, repeatable, and predictable way is less simple (or less fun) than you have found the process to be in other languages.

How do I use / read this?

This is a technical guide not an in depth explanation (though that may be forthcoming) and so I expect this guide to be used primarily as a way to kick start your memory on how to set up Python projects in a way you don't dislike. Best of luck 🍀

Pre-Reqs 🫸

These steps are to be done once per machine and if you've already accomplished these steps you may skip this section.

Install PyEnv & A Modern Python Version 🐍

brew update
brew install pyenv
pyenv --version
# pyenv 2.3.15

pyenv install 3.10.7
# Wait for a bit for install to finish...

pyenv shell 3.10.7
python --version
# Python 3.10.7 🎉

Optional: Set A System Wide Python Version

pyenv global 3.10.7

Install Poetry ✍️

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

Optional: Tell poetry to create virtual environments in the current project directory

poetry config virtualenvs.in-project true
poetry config virtualenvs.in-project
# true

Steps 🧭

• Make a new project directory

cd Desktop/Code/personal/python
mkdir planet-express-api
cd planet-express-api 

• Set a Python version for this project directory

pyenv local 3.10.7
python --version 
# 3.10.7
cat .python-version
# 3.10.7

Note: This command will create a file that pyenv looks for in the current working directory (the folder you are in) whose content will tell pyenv which Python version to use.

• Create a poetry project

# Leave off the -n flag if you wish to add precise data 
# to the pyproject.toml file poetry creates.
poetry init -n
ls | grep pyproject.toml
# pyproject.toml

• Initialize and start your Virtual Environment using poetry

poetry shell
# Creating virtualenv planet-express-api
# bash -c planet-express-api/.venv/bin/activate

• Test it by adding a dependency

# Add a dependency
poetry add pendulum 

# Start a Python REPL
python 

# Use the dependency
import pendulum
now = pendulum.now("Europe/Paris")
now.to_iso8601_string()
# '2023-05-27T19:40:17.452958+02:00'
# Use `ctrl + d` to exit the REPL 

• Stop using the virtual environment

# Exit the virtual environment
deactivate

# Start a Python REPL
python

# Validate the dependency is not available
import pendulum
ModuleNotFoundError: No module named 'pendulum' 

Note: To get back into the virtual environment just use poetry shell again.

Summary

In this article you have used PyEnv and Poetry together to create a project in a desired version of Python (pyenv) whose dependencies and virtual environment are managed by a single robust tool (poetry) cheers to you 🍻