From 8cd04345069f4e10165d2c0e07fcf579d953115b Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Tue, 15 Apr 2025 12:32:34 +0200 Subject: [PATCH 1/3] refactor: :recycle: revise to recommend uv, not poetry --- why-poetry/index.qmd | 161 +++++++++++++++++++++++++++++-------------- 1 file changed, 108 insertions(+), 53 deletions(-) diff --git a/why-poetry/index.qmd b/why-poetry/index.qmd index eef6fa9..e29cf03 100644 --- a/why-poetry/index.qmd +++ b/why-poetry/index.qmd @@ -1,7 +1,8 @@ --- -title: "Why Poetry" -description: "Our reasons for using Poetry for managing Python package dependencies when building Django and Python projects." +title: "Why uv" +description: "Python projects need a tool to manage dependencies and virtual environments. This post describes our reasons for using uv for those tasks." date: "2024-01-29" +date-modified: "2025-04-15" categories: - dependencies - develop @@ -10,7 +11,7 @@ categories: ## Context and problem statement -Managing the packages we depend on (e.g. Django) in Python isn't +Managing the packages we depend on when building Python packages 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 @@ -25,7 +26,10 @@ environments. There are multiple ways of creating these virtual environments and managing package dependencies, and the optional solution depends on the -project. +project. So the question is: + +*What package dependency management tool should we use for our Python +projects?* ## Decision drivers @@ -36,26 +40,23 @@ project. ## 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: +There are (unfortunately) multiple tools to manage package dependencies. +See the list of resources below for all the different options available. +We'll only cover these more popular tools as they fit our basic +principles the most: - [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/) +There's also a very new tool that isn't listed on many comparison pages +but has already gained a lot of attention and been adopted by many +projects because of how well designed it is and the problems it solves. +So we will also consider it: + +- [uv](https://docs.astral.sh/uv/) + ### Pipenv [Pipenv](https://pipenv.pypa.io/en/latest/index.html) was designed to @@ -63,26 +64,26 @@ combine the existing functionality of `pip` and `virtualenv`, rather than being designed and built specifically for the purpose of package management. -::: columns +::::: columns ::: column #### Benefits -- Is very popular and widely used -- Has been around for a while -- Only handles package dependencies (no other features) - +- Is very popular and widely used +- Has been around for a while +- Only handles package dependencies (no other features) ::: ::: column #### Drawbacks -- Design is a bit older and not as intuitive/clear to use -- document 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) - -::: +- Design is a bit older and not as intuitive/clear to use +- document 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 @@ -90,36 +91,41 @@ management. some of the short comings of pipenv and is specifically designed with package management and project development in mind. -::: columns +::::: columns ::: column #### Benefits -- 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) +- 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) +- Versions below 2.0.0 were 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)), + but after 2.0.0 it is PEP-compliant ::: ::: column #### Drawbacks -- 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 - -::: +- Installation and resolving package dependency trees (so there are no + conflicts) can be a bit slow ::: +::::: ### Hatch [Hatch](https://hatch.pypa.io/latest/version/), like Poetry, was designed to manage package dependencies and Python projects. -::: columns +::::: columns ::: column #### Benefits @@ -140,14 +146,14 @@ designed to manage package dependencies and Python projects. - 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. -::: columns +::::: columns ::: column #### Benefits @@ -164,17 +170,66 @@ Poetry and Hatch, is designed for managing packages and Python projects. `curl` to install, which isn't the most secure way of installing) - Can't install through `pipx` ::: +::::: + +### uv + +[uv](https://docs.astral.sh/uv/) is a new tool that was designed from +the ground up to directly solve many of the dependency management issues +found in Python, rather than try to refactor existing tools. It is also +written in Rust and is extremely fast. + +::::: columns +::: column +#### Benefits + +- Has all the same benefits as Poetry above +- The command line interface is very simple and easy to use +- Is very fast at resolving dependencies and installing the necessary + packages +- Can install Python from its interface +- Will automatically detected the Python version need for a project in + the `pyproject.toml` file and install the needed version. +- Fully PEP-compliant from the start +- It simplifies many of the common project management tasks, often + doing them automatically in the process of doing other tasks +- Is designed to be an easy replace for common tools like `pip` +::: + +::: column +#### Drawbacks + +- Because it is still new, it doesn't have as many packaging features + that are found in Poetry, though the developers of uv have these + features in their roadmap ::: +::::: ## Decision outcome -We decided on Poetry because it has amazing documentation, is -well-designed, and is very popular and widely used. +We decided on uv because it has amazing documentation, is fast, is very +well-designed, and is already being recommended by many in the community +to be used over other tools. ### 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 +- It is still fairly new, but seems to already be very well designed. + So we may encounter issues because it is still new, but we expect + that it will be well supported and maintained in the future. + +## Resources used for this post + +- [Poetry vs uv vs + pip](https://envelope.dev/blog/poetry-vs-uv-vs-pip-choosing-the-right-package-installer) +- [Python Packaging User + Guide](https://packaging.python.org/en/latest/tutorials/managing-dependencies/#other-tools-for-application-dependency-management) +- [Awesome Python: Poetry + alternatives](https://python.libhunt.com/poetry-alternatives). +- [Ritza Articles: Comparisons of + tools](https://ritza.co/articles/gen-articles/pipenv-vs-virtualenv-vs-poetry-vs-pyenv-vs-pip/), +- [warp: Prose about + Poetry](https://www.warp.dev/blog/prose-about-poetry) +- [Python Package Manager + Comparison](https://dev.to/adamghill/python-package-manager-comparison-1g98) +- [A review of pipenv vs poetry vs + PDM](https://dev.to/frostming/a-review-pipenv-vs-poetry-vs-pdm-39b4) From 45b5a24760e0b0bc484b854e5553d8e34f085d9e Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Tue, 15 Apr 2025 12:32:53 +0200 Subject: [PATCH 2/3] chore: :truck: rename to `why-uv` --- {why-poetry => why-uv}/index.qmd | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename {why-poetry => why-uv}/index.qmd (100%) diff --git a/why-poetry/index.qmd b/why-uv/index.qmd similarity index 100% rename from why-poetry/index.qmd rename to why-uv/index.qmd From 71569f4b1aa05bc77be90c65e62c4df139e99773 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Tue, 13 May 2025 11:17:42 +0200 Subject: [PATCH 3/3] fix: :pencil2: small editorial fixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Signe Kirk Brødbæk <40836345+signekb@users.noreply.github.com> --- why-uv/index.qmd | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/why-uv/index.qmd b/why-uv/index.qmd index e29cf03..0c873eb 100644 --- a/why-uv/index.qmd +++ b/why-uv/index.qmd @@ -109,7 +109,7 @@ package management and project development in mind. - Versions below 2.0.0 were 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)), - but after 2.0.0 it is PEP-compliant + but after 2.0.0 it is PEP compliant ::: ::: column @@ -130,12 +130,11 @@ designed to manage package dependencies and Python projects. #### Benefits - Very similar to Poetry -- Is fully PEP-compliant -- Is relatively new +- Is fully PEP compliant - Is very opinionated - Good documentation - Now maintained under the official PyPA -- Because of being PEP-compliant and hosted by PyPA, may be the better +- Because of being PEP compliant and hosted by PyPA, may become the recommended option in the future ::: @@ -157,15 +156,14 @@ Poetry and Hatch, is designed for managing packages and Python projects. ::: column #### Benefits -- Fully PEP-compliant +- Fully PEP compliant - Decent documentation ::: ::: column #### Drawbacks -- Relatively new -- Not as widely used or as popular +- Not as widely used or as popular as the other options considered here - 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` @@ -190,7 +188,7 @@ written in Rust and is extremely fast. - Can install Python from its interface - Will automatically detected the Python version need for a project in the `pyproject.toml` file and install the needed version. -- Fully PEP-compliant from the start +- Fully PEP compliant - It simplifies many of the common project management tasks, often doing them automatically in the process of doing other tasks - Is designed to be an easy replace for common tools like `pip`