Add utility to select things with compatible tags

[sbidoul]

Coming from #1092 (comment), this PR proposes a utility to select things that best match an ordered list of tags.

It works like this, for instance, to select compatible wheel filenames:

    >>> filenames = ["foo-1.0-py3-none-any.whl", "foo-1.0-py2-none-any.whl"]
    >>> selector = create_compatible_tags_selector(tags.sys_tags())
    >>> compatible_filenames = list(selector([
    ...     (filename, parse_wheel_filename(filename)[-1]) for filename in filenames
    ... ]))
    ["foo-1.0-py3-none-any.whl"]

[sbidoul]

@brettcannon how do you like this one?

[sbidoul]

I made it return an iterator to allow for possible future optimizations.

So obtaining the best compatible wheel looks like this:

    >>> filenames = ["foo-1.0-py3-none-any.whl", "foo-1.0-py2-none-any.whl"]
    >>> selector = create_compatible_tags_selector(tags.sys_tags())
    >>> next(selector([
    ...     (filename, parse_wheel_filename(filename)[-1]) for filename in filenames
    ... ]), None)
    "foo-1.0-py3-none-any.whl"

[sbidoul]

The first question here is if this seems worthwhile as a public API. If yes, we can refine it. If not, or if in doubt for now, I'll include this as a private API in #1092.

[brettcannon]

I think it makes sent to make this public! I had one small improvement, otherwise LGTM!

[henryiii]

Does this work with manylinux / linux correctly? In the past, manylinx/musllinux was placed at the wrong place in tags, causing the general manylinux to come before the specific linux tag, which means this would pick a generic manylinux wheel over a local compile.

If so, it should probably come with a warning in the docs at least?

[brettcannon]

I think this is just missing docs.

[henryiii]

I think you'll automatically get docs if you add it to __all__.

[sbidoul]

Does this work with manylinux / linux correctly? In the past, manylinx/musllinux was placed at the wrong place in tags, causing the general manylinux to come before the specific linux tag, which means this would pick a generic manylinux wheel over a local compile.

It indeed seems tags.sys_tags() returns manylinux tags before corresponding linux tags.

If so, it should probably come with a warning in the docs at least?

So in the docs of sys_tags() ?

[sbidoul]

I think you'll automatically get docs if you add it to __all__.

@henryiii docs/tags.rst is not prepared for that yet? Although I was sure to have seen a PR (from you?) to improve that but I don't find it now.

[brettcannon]

Does this work with manylinux / linux correctly? In the past, manylinx/musllinux was placed at the wrong place in tags, causing the general manylinux to come before the specific linux tag, which means this would pick a generic manylinux wheel over a local compile.

If so, it should probably come with a warning in the docs at least?

That's #160 so I think it's a separate issue from this PR.

[brettcannon]

I think you'll automatically get docs if you add it to __all__.

@henryiii docs/tags.rst is not prepared for that yet? Although I was sure to have seen a PR (from you?) to improve that but I don't find it now.

@sbidoul did you want to wait for something like that or do a quick doc change by copying the docstring?

[henryiii]

I did some of them, I can see about that one.

[sbidoul]

I updated tags.rst and fixed the doctest.

[henryiii]

Made #1130.

[sbidoul]

Thanks! Docs updated.