Support inline script metadata (PEP 723) in python hooks

[potiuk]

One thing we discussed in Airlfow in one of the PRs, it would be great if prek supported inline script metadata https://packaging.python.org/en/latest/specifications/inline-script-metadata/ in python hooks.,

That would allow to keep the dependency + script in the same place (not decoupled between .pre-commit-config.yaml and the script implicit dependencies) and we often now copy dependencies in both places to allow also to run the prek hook as regular script with uv run for example.

It probably means that prek would not have to manage the venv for such inline-project matadata hooks, but it could entirely run on uv run running the scripts. The venv used by uv are "throw-away" but also this reflects uv philosophy where the venvs are created and destroyed extremely fast because of aggressive caching and hard-linking by default.

Discussed initially in apache/airflow#54656 (comment)

[ashb]

Does prek need to support this, or could the command to run be ["uv", "run", "myscript.py"]?

[j178]

Or maybe use uv as the shebang: https://akrabat.com/using-uv-as-your-shebang-line/

But prek currently does not expose its internal used uv to hooks, this relies on the system installed uv.

[potiuk]

Or maybe use uv as the shebang: https://akrabat.com/using-uv-as-your-shebang-line/

But prek currently does not expose its internal used uv to hooks, this relies on the system installed uv.

Or maybe there should be a new hook type "python-script" ? Maybe that's simplest?. I think "system" prek hook with uv would likely run fine, but I somehow feel it's wrong to specify in the script that it should be run with uv in shebang, where PEP-723 is standard and pretty much any other tool can run the script.

But that already diverges from pre-commit and I guess you would like to avoid it for quite a while?

[potiuk]

Does prek need to support this, or could the command to run be ["uv", "run", "myscript.py"]?

I would also hate to repeat ["uv", "run", ...] in hook definitions :)

[j178]

But that already diverges from pre-commit and I guess you would like to avoid it for quite a while?

Yeah, I’m trying to avoid adding a new language for now. Calling it python_script could get confusing next to python and script, since their differences are pretty subtle.

I’m thinking of building this into language: python. Since we’re already parsing script shebangs, we could look for the PEP 723 script pattern and run the script with uv. Just like prek automatically adding the shebang #!/usr/bin/env -S uv run --script for that script.

[potiuk]

I’m thinking of building this into language: python. Since we’re already parsing script shebangs, we could look for the PEP 723 script pattern and run the script with uv. Just like prek automatically adding the shebang #!/usr/bin/env -S uv run --script for that script.

Yeah. That would likely be the best choice.

[j178]

I added PEP 723 script support in #529, with a few design choices:

• The first part of the entry field must be a path to the Python script.
• If you specified additional_dependencies in .pre-commit-config.yaml, script metadata will not be read.
• Setting both the language_version in .pre-commit-config.yaml and requires-python in the script metadata, the language_version will be ignored.
• Only the top-level fields dependencies and requires-python in script metadata are supported, other fields like tool.uv are all ignored.

[potiuk]

I added PEP 723 script support in #529, with a few design choices:

• The first part of the entry field must be a path to the Python script.
• If you specified additional_dependencies in .pre-commit-config.yaml, script metadata will not be read.
• Setting both the language_version in .pre-commit-config.yaml and requiest-python in the script metadata, the language_version will be ignored.
• Only the top-level fields dependencies and requires-python in script metadata are supported, other fields like tool.uv are all ignored.

Very sensible choices.