docs: 📝 Decision post on why to use poetry

why-poetry.qmd

@@ -0,0 +1,105 @@
+---
+title: "Why Poetry"
+description: "Our reasons for using Poetry for managing Python package dependencies when building Django and Python projects."
+author: "Luke W. Johnston"
+date: last-modified
+categories:
+- package dependencies
+- virtual environments
+- python
+---
+
+## Context and Problem Statement
+
+Managing the packages we depend on (e.g. Django) in Python isn't "simply" installing it on your computer. The issue with installing Python packages on your computer is dependency conflicts that occur, where the "dependency trees" of one package require a different dependency tree than another one. So installing a package that requires a specific version of one package, while another package you already have installed requires another version can cause system problems.
+
+The solution to this problem is by using "virtual environments" in Python. These are environments that are separate from the rest of the system and can install any packages without impacting other environments.
+
+There multiple ways of creating these virtual environments and managing package dependencies, and the optional solution depends on the project.
+
+## Decision Drivers
+
+- Package dependency management is a critical task, so we need a tool for it.
+- Ensuring we have some way of building our Python projects in a way that is less likely to be a "it works on my computer" issue.
+
+## Considered Options
+
+There are (unfortunately) multiple tools to manage package dependencies in Python, for example, listed at [Python Packaging User Guide](https://packaging.python.org/en/latest/tutorials/managing-dependencies/#other-tools-for-application-dependency-management) and at [Awesome Python](https://python.libhunt.com/poetry-alternatives). There are also comparison sites like [Ritza Articles](https://ritza.co/articles/gen-articles/pipenv-vs-virtualenv-vs-poetry-vs-pyenv-vs-pip/), [warp](https://www.warp.dev/blog/prose-about-poetry), and [this](https://dev.to/adamghill/python-package-manager-comparison-1g98), and [this](https://dev.to/frostming/a-review-pipenv-vs-poetry-vs-pdm-39b4) at [dev.to](https://dev.to/) that go into more detail about many of these tools.
+
+We'll only cover these more popular tools:
+
+- [Pipenv](https://pipenv.pypa.io/en/latest/index.html)
+- [Poetry](https://python-poetry.org/)
+- [Hatch](https://hatch.pypa.io/latest/version/)
+- [PDM](https://pdm-project.org/latest/usage/dependency/)
+
+### Pipenv
+
+[Pipenv](https://pipenv.pypa.io/en/latest/index.html) was designed to combine the existing functionality of `pip` and `virtualenv`, rather than being designed and built specifically for the purpose of package management.
+
+- **Pros**:
+    - Is very popular and widely used
+    - Has been around for a while
+    - Only handles package dependencies (no other features)
+- **Cons**:
+    - Design is a bit older and not as intuitive/clear to use
+    - Documentation is a bit too verbose/technical
+    - Package caching doesn't seem to be well designed/robust, so packages could get unnecessarily re-installed
+    - Only handles package dependency management, which means we need another tool to develop software (like a Python package)
+
+### Poetry
+
+[Poetry](https://python-poetry.org/) was built and designed to address some of the short comings of pipenv and is specifically designed with package management and project development in mind.
+
+- **Pros**:
+    - Popular and widely used
+    - Very well designed website and documentation
+    - Handles package dependencies with lock files (detailed list of packages and versioning)
+    - Can set up and help manage a Python project (e.g. Python package)
+    - Designed from the ground up to consider the needs of package development and dependency resolution
+    - Allows for external plug-ins for further customization
+    - Similar dependency management to other languages
+    - Installable with `pipx`
+    - Integrates well with existing IDE/editors (PyCharm and VSCode)
+- **Cons**:
+    - Installation and resolving package dependency trees (so there are no conflicts) can be a bit slow
+    - Not completely PEP compliant (not yet support [PEP 621](https://peps.python.org/pep-0621/), but an Issue on it is [here](https://github.com/python-poetry/roadmap/issues/3)), though this isn't a critical problem
+
+### Hatch
+
+[Hatch](https://hatch.pypa.io/latest/version/), like Poetry, was designed to manage package dependencies and Python projects.
+
+- **Pros**:
+    - Very similar to Poetry
+    - Is fully PEP-compliant
+    - Is relatively new
+    - Is very opinionated
+    - Good documentation
+    - Now maintained under the official PyPA
+    - Because of being PEP-compliant and hosted by PyPA, may be the better option in the future
+- **Cons**:
+    - Is very opinionated
+    - Is relatively new, so might still be working through things
+    - Not as widely used compared to the others
+
+### PDM
+
+[PDM](https://pdm-project.org/latest/usage/dependency/), like both Poetry and Hatch, is designed for managing packages and Python projects.
+
+- **Pros**:
+    - Fully PEP-compliant
+    - Decent documentation
+- **Cons**:
+    - Relatively new
+    - Not as widely used or as popular
+    - Doesn't have distribution specific installation builds (need to use `curl` to install, which isn't the most secure way of installing)
+    - Can't install through `pipx`
+
+## Decision Outcome
+
+We decided on Poetry because it has amazing documentation, is well-designed, and is very popular and widely used.
+
+### Consequences
+
+- Because Poetry isn't fully PEP compliant, we might encounter some issues
+- Doesn't have the "official" support (hosted on the GitHub PyPA organization) that Hatch has, so we might reconsider the decision to use Poetry at a future date