Add PEP 723 inline script metadata support by gilgamezh · Pull Request #452 · PyAr/fades

gilgamezh · 2026-06-18T09:34:00Z

Closes #423

PEP 723 defines a standard # /// script comment block (TOML) for declaring a single-file script's dependencies and requires-python. It's implemented by pipx, pip-run and uv. This adds support to fades so it can run scripts written for other runners — and so scripts written for fades can run on them.

What it does

dependencies: parsed from the block and merged like every other dependency source (inline # fades marks, docstrings, -r files, -d flags).
requires-python: honored by selecting a suitable interpreter — the currently selected one (--python or fades' own) if it satisfies the specifier, otherwise an auto-discovered pythonX.Y on PATH, failing cleanly if none is available. An explicit --python that conflicts is reported rather than silently overridden, so the user stays in control.
TOML parsing: stdlib tomllib on Python 3.11+, falling back to tomli on older versions (conditional dependency in setup.py).
Robust errors: malformed metadata (bad TOML, invalid requirement string, bad/non-string requires-python, non-list dependencies, multiple script blocks) raises a clean FadesError with an explanatory log line instead of dumping a traceback.

Example:

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

import requests
from rich.pretty import pprint

⚠️ Point for review: `requires-python` behavior

This goes beyond pipx and pip-run, which both ignore requires-python (only uv honors it, via its own interpreter management). Since fades has no interpreter management, the chosen behavior is:

selected interpreter satisfies the specifier → use it;
it doesn't, and no explicit --python → discover a matching pythonX.Y on PATH, else fail;
it doesn't, and --python was given → fail (don't override the user's explicit choice).

Discovery is best-effort over PATH (python3.6–python3.29, python3, python). Happy to dial this back to validate-only if preferred.

Tests

New tests/test_parsing/test_pep723.py plus fixtures, interpreter-selection/version-probe tests in test_helpers.py, and a consolidate_dependencies test in test_main.py. Full suite green (./test), flake8 clean. Docs updated in README.rst and man/fades.1.

🤖 Generated with Claude Code

gilgamezh · 2026-06-18T09:43:07Z

Did run tests here because we only run them when target is master

https://github.com/PyAr/fades/actions/runs/27750679594

should be executed when we change the target branch

Closes #423. fades now understands the PEP 723 `# /// script` metadata block, so it can run scripts written for other runners (pipx, pip-run, uv) and vice versa. - parse the block's `dependencies` and merge them like any other source - honor `requires-python`: keep the selected interpreter if it satisfies the specifier, otherwise auto-discover a suitable one on PATH (failing cleanly if none is available); an explicit --python that conflicts is reported instead of being silently overridden - malformed metadata (bad TOML, bad requirement, bad/non-string requires-python, non-list dependencies, multiple script blocks) raises a clean FadesError with an explanatory log line instead of dumping a traceback - use stdlib tomllib on 3.11+, falling back to tomli on older Pythons Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The PyPI availability pre-check built a version-specific URL whenever a dependency had any specifier, using the first specifier's version. For range specifiers like 'requests<3' this queried a non-existent version (requests/3) and wrongly reported the package as missing. PEP 723 scripts commonly use such range specifiers, so the bug surfaced there. Only use the version-specific URL for exact pins (== / ===); check by package name otherwise. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Cover previously-untested cases: - requires-python bounded ranges (>=3.10,<3.12) in parsing and in interpreter selection/discovery (pick highest within the range) - exact micro-version pins (==3.11.4) satisfying or not - merging PEP 723 deps with comment-style and other dependency sources - end-to-end wiring of requires-python into interpreter resolution (the parse_pep723 -> get_interpreter_for_requirement flow from main.go) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

facundobatista

Great work, thanks for this! I annotated some details and comments for stuff we need to think about...

facundobatista · 2026-06-25T00:29:23Z

+    candidate_names += ["python3", "python"]
+
+    found = {}  # path -> Version, to avoid probing the same interpreter twice
+    for name in candidate_names:


It feels a little clumsy to run an external subprocess 25 times just in case to find something.

What about exploring the PATH to see what's out there? See this code, for example, in my machine it produces:

('/usr/bin/python3.12', '3.12.3') ('/usr/bin/python3.14', '3.14.6') ('/usr/bin/python3.13', '3.13.14') ('/usr/bin/python3.14t', '3.14.6') ('/usr/bin/python3.11', '3.11.15')

We can work from there...

facundobatista · 2026-06-25T01:23:09Z

+        logger.error(msg)
+        raise FadesError(msg)
+
+    # nothing was explicitly requested and fades' own python doesn't satisfy the spec:


this is a little confusing... if nothing was explicitly requested, what is "the spec"?

facundobatista · 2026-06-25T01:35:43Z

+    # non-existent "version" and wrongly conclude the package is missing.
+    exact_specs = [spec for spec in dependency.specifier if spec.operator in ("==", "===")]
+    if exact_specs:
+        version = exact_specs[0].version


This may be a bug we have... but this code is not the solution at all.

The bug I think we have: "if you declare a version X not using ==, this will check for X anyway"

The bug this is introducing: "if you declare a version X not using ==, this will just check if the package exists (not caring the version)".

You should open a GH issue (if not there already) and let's handle separately,

facundobatista · 2026-06-25T01:36:53Z


+    # honor a PEP 723 'requires-python' (this may pick a different interpreter than the one
+    # explicitly requested with --python or fades' own)
+    _, requires_python = parsing.parse_pep723(analyzable_child_program)


Can we avoid the duplicate parsing?

facundobatista · 2026-06-25T01:41:50Z

@@ -1,4 +1,4 @@
-# Copyright 2015-2026 Facundo Batista, Nicolás Demarchi
+# Copyright 2014-2026 Facundo Batista, Nicolás Demarchi


Why are you changing the "from" in this copyright?

facundobatista · 2026-06-25T01:43:49Z

@@ -0,0 +1,13 @@
+# Copyright 2014-2026 Facundo Batista, Nicolás Demarchi


New files (here and all below) should start with copyright in current year. And they're missing the rest of the header.

facundobatista · 2026-06-26T17:43:59Z

+        # PEP 723 dependencies are standard PEP 508 strings (including 'name @ url' direct
+        # references that pip understands), so they all go to the PyPI repo.
+        try:
+            deps[REPO_PYPI] = [Requirement(dep) for dep in dependencies]


Dependencies from other backends should not go in REPO_PYPI, and should not be wrapped in a Requirement (because there are glitches in the comparison later, that's why we use VCSDependency and such) ... take a look at parse_fade_requirement

facundobatista · 2026-06-26T17:50:22Z

+    return candidates[-1][1]
+
+
+def get_interpreter_for_requirement(requires_python, requested_python):


These names are very confusing. I know requires_python is PEP723 naming, but both names almost mean the same.

What about being explicit and call them python_toml and python_args or similar?

gilgamezh requested a review from facundobatista June 18, 2026 09:36

gilgamezh changed the base branch from master to change_run_old June 18, 2026 09:37

gilgamezh changed the base branch from change_run_old to master June 20, 2026 09:06

gilgamezh force-pushed the pep723-support branch from b2b8b22 to 55c4e93 Compare June 20, 2026 09:09

gilgamezh and others added 2 commits June 20, 2026 11:17

gilgamezh mentioned this pull request Jun 20, 2026

Unify PEP 508 marker handling across all dependency sources (incl. PEP 723) and fix marker passing to pip #456

Open

facundobatista requested changes Jun 29, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add PEP 723 inline script metadata support#452

Add PEP 723 inline script metadata support#452
gilgamezh wants to merge 3 commits into
masterfrom
pep723-support

gilgamezh commented Jun 18, 2026 •

edited

Loading

Uh oh!

gilgamezh commented Jun 18, 2026

Uh oh!

facundobatista left a comment

Uh oh!

facundobatista Jun 25, 2026

Uh oh!

facundobatista Jun 25, 2026

Uh oh!

facundobatista Jun 25, 2026

Uh oh!

facundobatista Jun 25, 2026

Uh oh!

facundobatista Jun 25, 2026

Uh oh!

facundobatista Jun 25, 2026

Uh oh!

facundobatista Jun 26, 2026

Uh oh!

facundobatista Jun 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -1,4 +1,4 @@
		# Copyright 2015-2026 Facundo Batista, Nicolás Demarchi
		# Copyright 2014-2026 Facundo Batista, Nicolás Demarchi

		@@ -0,0 +1,13 @@
		# Copyright 2014-2026 Facundo Batista, Nicolás Demarchi

		return candidates[-1][1]


		def get_interpreter_for_requirement(requires_python, requested_python):

Uh oh!

Conversation

gilgamezh commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What it does

⚠️ Point for review: requires-python behavior

Tests

Uh oh!

gilgamezh commented Jun 18, 2026

Uh oh!

facundobatista left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gilgamezh commented Jun 18, 2026 •

edited

Loading

⚠️ Point for review: `requires-python` behavior