Mastering Python Packaging with uv and pyproject.toml: A Step-by-Step Guide

The Problem

Have you ever struggled with packaging and deploying your Python projects, only to encounter compatibility issues, performance problems, and security vulnerabilities? I certainly have, and it's a frustrating experience that can be avoided by using the right tools and techniques. In this tutorial, we'll explore how to use uv and pyproject.toml to efficiently package and deploy Python projects, using the JSONPlaceholder Todos API as a sample dataset.

Step 1: Setting Up the Project Structure

The first step in mastering Python packaging is to set up a basic project structure, including setting up the pyproject.toml file and installing the required dependencies using uv. This involves creating a new project directory and initializing it with uv using the command

uv init

. We also need to install the required dependencies, such as requests, using

uv install requests

. For example, to install requests, we can use the following code snippet:

import subprocess
subprocess.run(["uv", "install", "requests"])

.

Step 2: Configuring pyproject.toml

Next, we need to configure the pyproject.toml file to specify project dependencies, scripts, and other metadata. This involves adding the required dependencies to the pyproject.toml file, such as

[tool.poetry.dependencies]
requests = "^2.28.1"

. We also need to specify the project scripts, such as

[tool.poetry.scripts]
main = "main:main"

. For example, to configure the pyproject.toml file, we can use the following code snippet:

import toml
pyproject = toml.load("pyproject.toml")
pyproject["tool"]["poetry"]["dependencies"]["requests"] = "^2.28.1"
toml.dump(pyproject, open("pyproject.toml", "w"))

.

Step 3: Packaging the Project

With the project structure and pyproject.toml file in place, we can now package the project using uv. This involves creating a source distribution using

uv build

and a wheel distribution using

uv build -f wheel

. For example, to package the project, we can use the following code snippet:

import subprocess
subprocess.run(["uv", "build"])
subprocess.run(["uv", "build", "-f", "wheel"])

.

Step 4: Deploying the Project

Once the project is packaged, we can deploy it to a production environment. This involves setting up a virtual environment and installing the dependencies using

uv install

. We can then run the project using

uv run

. For example, to deploy the project, we can use the following code snippet:

import subprocess
subprocess.run(["uv", "install"])
subprocess.run(["uv", "run"])

.

Step 5: Handling Errors and Edge Cases

Finally, we need to handle errors and edge cases that may arise during the packaging and deployment process. This involves using try-except blocks to catch and handle exceptions, such as dependency conflicts and compatibility issues. For example, to handle errors and edge cases, we can use the following code snippet:

try:
    # code to package and deploy the project
except subprocess.CalledProcessError as e:
    print(f"Error: {e}")
except Exception as e:
    print(f"An error occurred: {e}")

.

Complete Script

The full runnable script combining all steps:

#!/usr/bin/env python3
import subprocess
import toml
import requests

def load_data():
    response = requests.get("https://jsonplaceholder.typicode.com/todos")
    return response.json()

def analyze(data):
    # analyze the data
    return data

def package_project():
    subprocess.run(["uv", "init"])
    subprocess.run(["uv", "install", "requests"])
    pyproject = toml.load("pyproject.toml")
    pyproject["tool"]["poetry"]["dependencies"]["requests"] = "^2.28.1"
    toml.dump(pyproject, open("pyproject.toml", "w"))
    subprocess.run(["uv", "build"])
    subprocess.run(["uv", "build", "-f", "wheel"])

def deploy_project():
    subprocess.run(["uv", "install"])
    subprocess.run(["uv", "run"])

if __name__ == "__main__":
    try:
        data = load_data()
        result = analyze(data)
        package_project()
        deploy_project()
        print(result)
    except subprocess.CalledProcessError as e:
        print(f"Error: {e}")
    except Exception as e:
        print(f"An error occurred: {e}")

Expected Output

When you run the script, you should see the packaged and deployed project, along with the analyzed data.

What I'd Change

In conclusion, while uv and pyproject.toml provide a powerful way to package and deploy Python projects, there are still some limitations and areas for improvement. For example, the packaging process can be slow and cumbersome, and the error handling can be improved. Therefore, I would recommend using other tools and techniques, such as pip and setup.py, to package and deploy Python projects. Additionally, I would recommend using more advanced error handling techniques, such as logging and exception handling, to improve the robustness and reliability of the packaging and deployment process.