#6369 - detailed documentation for the --platform and --python-version options of the pip download command

[Shepard2154]

Fixes #6369

[notatallshaw]

The docs you've writen here don't seem to match the last comment in the thread you are referencing #6369 (comment)

Taking a looking at packaging.tags.get_tags() the fallback is a normalized version of sysconfig.get_platform(), but for Mac, iOS, and Linux there is more complicated logic.

Can you please justify your choices here, or update to reflect the discussion in #6369,

[Shepard2154]

The docs you've writen here don't seem to match the last comment in the thread you are referencing #6369 (comment)

Taking a looking at packaging.tags.get_tags() the fallback is a normalized version of sysconfig.get_platform(), but for Mac, iOS, and Linux there is more complicated logic.

Can you please justify your choices here, or update to reflect the discussion in #6369,

I have delved into the problem in more detail and agree with your comment. I added the command packaging.tags.sys_tags(). Starting with packaging version 21.0, the get_tags() function has been replaced by sys_tags(), which provides similar functionality. Does this resolve the issue?

[notatallshaw]

I've put it on the 25.1 milestone so it doesn't get forgotten, but will need a maintainer to review and accept, I'll try but I can't promise anything.

[pfmoore]

Even though this is "only" a docs change, there seem to be questions about the information given, and personally I'm not that convinced we should get into this much detail (these are advanced options, and cross-platform environment identification is a complex subject that I don't think it's pip's place to explain).

I'm not rejecting this change, but I don't think there's any reason it should be targeted to a specific pip release, so I'm removing the 25.1 milestone. It can go in when it's ready.

[notatallshaw]

I'll review this week.

As a pip user I am occasionally frustrated with options that are not clear to me where the values are derived or validated against.

So I would like to see more documentation either pointing users to standards or detailing pip's implementation choices.

I added the milestone not because I thought it was needed for 25.1 but rather a reminder to address this PR in some way or another, rather than forgetting about it. I'm happy to take responsibility to review, reject, or postpone PRs that I add to a milestone that are otherwise left unreviewed and unmerged.

[pfmoore]

No worries - I'm happy for it to go in or not, as you prefer. But as we get closer to the release, I want the milestone to reflect stuff that I need to ensure gets resolved, and I don't think this falls into that category, which is why I removed it.