Building One-Shot Python Tools with Claude and uv run

In the world of rapid prototyping and debugging, one-shot tools can save a lot of time. Simon Willison, a seasoned developer, has been exploring how to create these tools using a combination of Claude (an AI assistant) and uv run (a dependency management tool). This approach allows you to generate and run Python scripts on the fly without worrying about environment setup.

The One-Shot Prompt

A "one-shot" prompt in LLM jargon is one that produces the desired result on the first attempt. Simon recently used this technique to create a Python CLI tool for debugging Amazon S3 access issues. Here’s how it went down:

The Problem: Debugging S3 Access

Simon was struggling with an S3 bucket where a file couldn't be accessed via a public URL. Frustrated, he turned to Claude and provided the following prompt (full transcript available here):

I can't access the file at EXAMPLE_S3_URL. Write me a Python CLI tool using Click and boto3 which takes a URL of that form and then uses EVERY single boto3 trick in the book to try and debug why the file is returning a 404

The Solution: A One-Shot Python Script

Claude generated a script that did exactly what Simon needed. Here’s a snippet of the script:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "click",
#     "boto3",
#     "urllib3",
#     "rich",
# ]
# ///

import click
import boto3
from urllib.parse import urlparse
from rich.console import Console

console = Console()

@click.command()
@click.argument('url')
def debug_s3_access(url):
    parsed_url = urlparse(url)
    bucket_name = parsed_url.netloc.split('.')[0]
    key = parsed_url.path.lstrip('/')
    
    s3 = boto3.client('s3')
    
    try:
        response = s3.get_object(Bucket=bucket_name, Key=key)
        console.print(f"File found: {url}")
    except s3.exceptions.NoSuchKey:
        console.print(f"Error: File not found at {url}", style="red")
    except Exception as e:
        console.print(f"Error: {e}", style="red")

if name == 'main': debug_s3_access()

### Running the Script with `uv run`

The magic happens when you use `uv run` to execute the script. Here’s how Simon ran it:

```sh
uv run debug_s3_access.py \
  https://test-public-bucket-simonw.s3.us-east-1.amazonaws.com/0f550b7b28264d7ea2b3d360e3381a95.jpg

You can view the text output here.

Inline Dependencies with uv run

The key to this seamless experience is the inline dependency declaration at the top of the script:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "click",
#     "boto3",
#     "urllib3",
#     "rich",
# ]
# ///

This is an example of inline script dependencies, a feature described in PEP 723 and implemented by uv run. When you run the script with uv run, it automatically creates a temporary virtual environment with the specified dependencies installed. This process is quick, taking just a few milliseconds once the uv cache has been populated.

Why It Matters

This approach to creating one-shot Python tools offers several advantages:

• Rapid Prototyping: You can quickly generate and test scripts without setting up environments.
• Dependency Management: Inline dependencies ensure that all required packages are installed automatically.
• Reproducibility: The script is self-contained