poetry-playground

📚 Learning and exploring Poetry, the Python package manager.

Python packaging and dependency management made easy.

-- https://python-poetry.org

NOTE: This project was developed on macOS. It is designed for my own personal use.

Overview

This repository is for me to learn Poetry and have working example code and configuration that I can look back on in my future development in the Python ecosystem. Personally, I like to use JetBrains IDEs, and I'm using PyCharm for this project. PyCharm has built-in support for Poetry. Let's explore Poetry.

Instructions

Follow these instructions to build and run the example project.

1. Pre-requisite: Poetry
   • I'm using Poetry 1.8.3 which I installed via pipx.
2. Pre-requisite: Python
   • I'm using Python 3.12.3 which is available on my PATH as python3 and python3.12.
3. Create a virtual environment

   • poetry env use python3.12

   • This will create a virtual environment tied to the Python interpreter pointed to by python3.12 executable (or symlink) in a global cache directory that Poetry manages. Use the following command to see details about the virtual environment you just created.

   • poetry env info

   • For me, the output shows that the Python interpreter is located at /opt/homebrew/opt/python@3.12/Frameworks/Python.framework/Versions/3.12/bin/python3.12. Manually creating a virtual environment in this way is actually not necessary. The first time you run poetry install, Poetry will automatically search for and use a Python interpreter matching the version specified in pyproject.toml. If it finds one (I don't know the algorithm it uses, but I suppose it just looks for executables on the PATH named python3.11, python3.12, etc.) then it creates the virtual environment before running the rest of the command.
4. Install dependencies

   • poetry install

5. Run the example program

   • poetry run python -m poetry_playground

6. Build a wheel distribution

   • poetry build

   • This will create a dist directory with a .whl file in it.
7. Install the wheel distribution

   • pipx install dist/poetry_playground-0.1.0-py3-none-any.whl

   • It should successfully install an app/executable named readme-word-count. This name comes from the tool.poetry.scripts section in pyproject.toml. The output of the installation will look something like the following.

   • $ pipx install dist/poetry_playground-0.1.0-py3-none-any.whl
     installed package poetry-playground 0.1.0, installed using Python 3.12.4
     These apps are now globally available
     - readme-word-count
     done! ✨ 🌟 ✨
     

8. Try the readme-word-count command

   • readme-word-count

Notes

This is not the first time I've dipped my toes into developing in the Python ecosystem, but in some ways it has the same energy as that because I have to re-learn the various tools: pip, pipx, virtual environments, Poetry, etc. The goal is not to learn them all in-depth but the goal is to learn enough to be able to support a project that supports my ability to go in-depth on Python development itself. In other words, I want to learn Pandas, NumPy, Jupyter, and I don't want to learn so much about the build tools.

Below are some stream of consciousness notes:

• brew install pipx
• pipx install argcomplete
• (Nushell) register-python-argcomplete pipx | save ~/.local/share/bash-completion/completions/pipx
• pipx install poetry
• (Nushell) poetry completions bash | save ~/.local/share/bash-completion/completions/poetry
• poetry init
• poetry lock

Wish List

General clean-ups, TODOs and things I wish to implement for this project:

• DONE Do a small "hello world" thing using a library.
  • I want to do a word count of my README.md into a Pandas DataFrame.
• DONE What does packaging look like? Pretty sure pipx is in the picture. UPDATE: Actually there is a Poetry-native way to do this: poetry-plugin-bundle. But, it's a bit niche which makes me hesitate. On the other hands, the pipx way is not capturing the precision of the locked dependencies that Poetry provides and is reflect in the poetry.lock file. Instead I'm seeing a very broad Requires-Dist: pandas (>=2.2.2,<2.3.0) in the METADATA file in the wheel.
• DONE Use the __main__.py pattern so that we can run the project with -m instead of pointing to a file.
• DONE Explore how Poetry interfaces with virtual environment.

Reference

• Poetry official docs

  • Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. Poetry offers a lockfile to ensure repeatable installs, and can build your project for distribution.