docs: mention that python requirements need to be specified using full address from the root

[AlexTereshenkov]

It may be not so obvious that referring to the Python requirements using their "regular" path produced by the list goal will not be compatible with the format expected in the [tool].requirements field, see https://www.pantsbuild.org/2.21/reference/subsystems/ruff#requirements:

$ pants list 3rdparty/python | grep "flake8"
3rdparty/python:flake8#flake8
...

The target should be referred to as requirements = ["//3rdparty/python:flake8"]. If it's not (e.g. using 3rdparty/python:flake8), then an error is raised:

$ pants lint ::
...
ValueError: Invalid requirement '3rdparty/python:flake8': Parse error at "'/python'": Expected string_end

[huonw]

Thanks for the patch. Seems reasonable to document the current behaviour... but, why do we have this behaviour? Can we allow path/to:requirement to work too, not just //path/to:requirement?

[AlexTereshenkov]

Thanks for the patch. Seems reasonable to document the current behaviour... but, why do we have this behaviour? Can we allow path/to:requirement to work too, not just //path/to:requirement?

I've extended the help to clarify why this is necessary. The reqs might be in the form of VCS requirements that resembles the addresses (with colons in between), see https://pip.pypa.io/en/stable/topics/vcs-support/. So the // prefix is to help to differentiate between those.

pants/src/python/pants/backend/python/util_rules/pex.py

Lines 476 to 491 in 7ac339a

	async def get_req_strings(pex_reqs: PexRequirements) -> PexRequirementsInfo:
	addrs: list[Address] = []
	specs: list[str] = []
	req_strings: list[str] = []
	find_links: set[str] = set()
	for req_str_or_addr in pex_reqs.req_strings_or_addrs:
	if isinstance(req_str_or_addr, Address):
	addrs.append(req_str_or_addr)
	else:
	assert isinstance(req_str_or_addr, str)
	# Require a `//` prefix, to distinguish address specs from
	# local or VCS requirements.
	if req_str_or_addr.startswith(os.path.sep * 2):
	specs.append(req_str_or_addr)
	else:
	req_strings.append(req_str_or_addr)

[huonw]

Ah, cool, nice find and good thinking to explain the background in the docs 👍