EXE003 and uv run?

[fschulze]

Should EXE003 be extended for uv run?

I used the following she-bang:

#!/usr/bin/env uv run

Maybe another she-bang would work better?

[MichaReiser]

@zanieb @charliermarsh, how official is the use of uv run in shebang?

[ngnpope]

It'd be really nice to be able to do this for a fully distributable script, but note that it will need the -S flag.

Using the example from here:

#!/usr/bin/env -S uv run --quiet

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests<3",
#     "rich",
# ]
# ///

import requests
from rich.pretty import pprint

resp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])

This makes it usable as truly standalone executable, e.g. ./list-peps.py instead of uv run list-peps.py:

$ ./list-peps.py 
[
│   ('1', 'PEP Purpose and Guidelines'),
│   ('2', 'Procedure for Adding New Modules'),
│   ('3', 'Guidelines for Handling Bug Reports'),
│   ('4', 'Deprecation of Standard Modules'),
│   ('5', 'Guidelines for Language Evolution'),
│   ('6', 'Bug Fix Releases'),
│   ('7', 'Style Guide for C Code'),
│   ('8', 'Style Guide for Python Code'),
│   ('9', 'Sample Plaintext PEP Template'),
│   ('10', 'Voting Guidelines')
]

And adding --quiet allows hiding the extra noise at the beginning:

Reading inline script metadata from: ./list-peps.py

---

As a curious aside, if I wanted to drop the .py extension, uv gets confused and gets stuck in an recursive loop.

This is with switching --quiet for --verbose:

$ ./list-peps
DEBUG uv 0.3.0
DEBUG No project found; searching for Python interpreter
DEBUG Searching for Python interpreter in managed installations or system path
DEBUG Searching for managed installations at `.local/share/uv/python`
DEBUG Found `cpython-3.12.4-linux-x86_64-gnu` at `/home/nick/.pyenv/shims/python3` (search path)
DEBUG Using Python 3.12.4 interpreter at: /usr/bin/python3
DEBUG Running `./list-peps`
DEBUG uv 0.3.0
DEBUG No project found; searching for Python interpreter
DEBUG Searching for Python interpreter in managed installations or system path
DEBUG Searching for managed installations at `.local/share/uv/python`
DEBUG Found `cpython-3.12.4-linux-x86_64-gnu` at `/usr/bin/python3` (search path)
DEBUG Using Python 3.12.4 interpreter at: /usr/bin/python3
DEBUG Running `./list-peps`
...

So it doesn't seem to realise that it's a Python script and so doesn't look for the PEP 723 metadata and then attempts to call itself. I've not got around to reporting this yet.

[fschulze]

Hmm, it seems like /usr/bin/env isn't as portable as I thought:
https://stackoverflow.com/a/16365367/3748142

[PaarthShah]

@fschulze That answer is very, very outdated (from 2013, edited 2018). It's far more portable nowadays.

[martimlobao]

This is a @charliermarsh -sanctioned way of running uv scripts, clearly this rule needs to be updated 😏

[charliermarsh]

That's true!

[Avasam]

Just hit this in typeshed, trying to promote usage of uv run to help new contributors who'd forget to enable (or don't want to handle) their virtual environment! python/typeshed#13599

Also, would the --active flag be allowed here? Would any flag even be restricted (ie: just check for uv run)?

[andrei-korshikov]

Would any flag even be restricted (ie: just check for uv run)?

I don't think that uv run options should be restricted—it would reduce flexibility. Sometimes I use --offline, for example.

Also don't forget, that uv run might not have space on the left:

#! /usr/bin/env --split-string=uv run --script

[hyperknot]

I also come here to say that please embrace the uv shebang. This is currently the best way to work with Python scripts, yet it's totally unofficial / you have to ask on Discord level hidden.

I recommend the following:

1. Please agree on an official uv shebang line. Just in this thread there are quite a few alternatives. I'm personally using

#!/usr/bin/env -S uv run

2. Advertise it everywhere, in the FAQ, in the uv init scripts, etc.

3. Modify EXE003 rule to allow this.