Pants: python_binary doesn't have the singular `source=` argument documented

[cosmicexplorer]

See https://www.pantsbuild.org/build_dictionary.html#bdict_python_binary. sources is documented, but not source, which isn't deprecated.

[cosmicexplorer]

Note from @Eric-Arellano -- this is actually true for all targets, not just python_binary(). We should either have this on every target definition (good idea), or figure out some way to make it clear that source is always a stand-in for singular sources (unclear how this would work yet).

[Eric-Arellano]

source doesn't play well with the Target API, which is very Field centric. There isn't (currently) a very strong story around two fields being tightly coupled to each other. I'm sure we could figure something out, but it likely wouldn't be ideal.

My other concern is that sources can now be globs, and that means that source can also be a glob. For example, it's possible to say source='*.py'. Semantically, that does not make sense because *.py almost certainly means multiple source files.

--

What do you all think about deprecating source?

The reasons I think we should:

1. Avoids the semantic weirdness of source="*.py".
2. Reduces the number of concepts for users.
3. Makes the Target API much cleaner.

We can throw together a trivial script to rewrite source to sources to distribute to users via migration-support.

If the concern is needing the two extra characters of [], we could allow sources to be Union[str, Iterable[str]], just like compatibility is, and call ensure_str_list. Although, I would strongly discourage that.

cc @benjyw @jsirois @illicitonion @stuhood @blorente

[illicitonion]

I'm cool with deprecating source.

I'd rather not allow strings as values for sources (i.e. I'd rather require a list/iterable).

[benjyw]

Yeah, I'd prefer to get rid of source= entirely, it was just a convenience so you could infer the entry_point.