RFC: Clarify that the direct_url.json url field must be a spec-compliant url

[konstin]

Clarify that the url field in direct_url.json must be a valid url. This was prompted by a case where the url field contained a value that was not a url (astral-sh/uv#1744). I'm not sure what the best venue to discuss this change is, so i'm putting it up as a PR here.

Relatedly, would it make sense to write a json schem for direct_url.json? A machine readable spec would allow tooling to generate types and would simplify verification.

Post on discuss.python.org

Closes #1510 (link check fix)

---

Thanks to whoever set up nox + sphinx-autobuild, nox -s preview is great!

---

📚 Documentation preview 📚: https://python-packaging-user-guide--1506.org.readthedocs.build/en/1506/

[sbidoul]

@konstin thanks for this!

Could you also announce this PR on discuss.python.org/packaging. Since this could be considered a spec change, it is worth announcing broadly (I personally don't think this change requires a PEP, but better check).

[konstin]

Could you also announce this PR on discuss.python.org/packaging. Since this could be considered a spec change, it is worth announcing broadly (I personally don't think this change requires a PEP, but better check).

Sure: https://discuss.python.org/t/clarify-that-the-direct-url-json-url-field-must-be-a-spec-compliant-url/46518

[radoering]

I wonder if this is too restricted regarding to git urls. If I understand correctly, you can't just convert a scp-like url to a valid url, cf servo/rust-url#220 and linked issues for example. If you can't convert it what should an installer that supports scp-like urls write into direct_url.json? Or does this change mean that installers should not support scp-like urls?

[konstin]

Wouldn't prefixing them with ssh:// make them valid urls?

[radoering]

I assume for github they are equivalent, but if this statement is correct they are not always equivalent:

However, the user@host and ssh:// url forms are not equivalent--in the user@host form, the path is usually relative to the user's homedir, while in the ssh:// form, the path is relative to root. (This is the behaviour when pulling over a vanilla ssh+shell setup--obviously hosting tools can make their own choices.)

(from https://secure.phabricator.com/T11004)

I have no idea how common that is. Maybe, that's just an edge case that can be neglected?

[radoering]

FYI: We decided to do the normalization in Poetry for now even if it might not always be equivalent in theory.

[chrysle]

@konstin Could you rebase?

[chrysle]

By the way, this document seems to fix the order of fields in the data structure, but I think that is misleading? At least I have seen valid direct_url.json files where it has been swapped.

[chrysle]

Thank you!