Better documentation on using --platform and --python-version

[paddymul]

What's the problem this feature will solve?
I want to use pip to download linux packages onto a mac.

I know that I need to use some combination of --platform, --python-version, --only-binary=:all:. but I don't know the proper values for these options.

Describe the solution you'd like
I would like the documentation from the command line tool to be clear, or the package documentation on pypi to be clear for each package what values were used for these options.

I am specifically trying to install pandas and sklearn for this example, but I think the issue is with the documentation.

for --platform I have tried linux linux_x86_64
for --python-version I have tried 3, 37, 3.7, cp37

I'm not sure if any of these are correct. I would expect the tool to offer example values ie

 cp37 is not a valid option for --python-platform try (3, 37, py37) instead

I am downloading these packages in order to package them into an AWS lambda function. I would rather not spin up a linux VM just to download packages.

Alternative Solutions

I also tried

pip search -vvv pandas

I would expect that command to list all possible platform/python-version options that are applicable for the package.

Thank you

[cjerdonek]

or the package documentation on pypi to be clear for each package what values were used for these options.

Have you tried looking at the downloadable files page for each package? e.g. https://pypi.org/project/pandas/#files
Does that help you more?

[paddymul]

I was just digging through the source code as you made this comment.

I eventually figured out that the arguments I wanted were
manylinux1_x86_64 and 37

These were completely non-obvious.
I looked at the files again and along with the source realized that manylinux1_x86_64 was the proper name.

This has solved my problem, but I still think that users could get very lost and confused when trying to use these options.

[cjerdonek]

It seems like if one looks at the page of downloadable files for a package, this shouldn't be too hard provided one has an understanding of what the wheel filenames mean (which is documented in PEP 425).

But I'd like to know how this can be made easier. I'm also not sure if it's more a pip issue or a Warehouse (PyPI) issue.

[pradyunsg]

But I'd like to know how this can be made easier. I'm also not sure if it's more a pip issue or a Warehouse (PyPI) issue.

+1

One of the things we could do is have a more friendly explainer of Wheel Tags somewhere and link to it. Perhaps packaging.python.org is the right place for such a document?

[ojasdeshpande10]

hey I would like to get some more insight into this issue

[uranusjr]

I think there are two areas we can improve here:

1. Add some documentation around --platform, --python-version, --implementaion, and --abi (I believe they are in the same category). Explain what they do (they control what wheels are selected from the index) and provide some examples of valid inputs.
2. Improve the error message when the user provides something wrong to any of those flags. It would be helpful to provide the user’s platform default as an example input.

Since these flags are for wheel selection, valid inputs are described in the wheel spec (PEP 427). It would be helpful to provide a short write-up in the documentation and link to the PEP and PyPA’s page for platform tags.

[joesinghh]

I would like to work on this issue , please assign me this issue . @uranusjr

[uranusjr]

@Joe-Sin7h GitHub does not allow assigning arbitrary users to an issue (not sure what the criterion is), so please feel free to go ahead and create a PR when you’re ready.

[MohsenAAkeel]

@uranusjr

I think there are two areas we can improve here:

1. Add some documentation around --platform, --python-version, --implementaion, and --abi (I believe they are in the same category). Explain what they do (they control what wheels are selected from the index) and provide some examples of valid inputs.
2. Improve the error message when the user provides something wrong to any of those flags. It would be helpful to provide the user’s platform default as an example input.

Since these flags are for wheel selection, valid inputs are described in the wheel spec (PEP 427). It would be helpful to provide a short write-up in the documentation and link to the PEP and PyPA’s page for platform tags.

I've written up a txt with documentation on tags, but am unsure where to add this or where to fold its content in. I'd also be happy to contribute on point 2, but am unsure where in the src to start.

[uranusjr]

I think @pradyunsg you can probably answer the documentation part better.

For point 2, you want to start in pip._internal.cli.cmdoptions, which holds the command option parsing logic. Look for how each options are passed. If you need cross-option validation, I think they are in pip._internal.commands, this pulls in stuffs from .cli to construct the actual commands. Look for the common base class that imports the options, and do validation in that class’s run().

[pradyunsg]

I've written up a txt with documentation on tags
I think @pradyunsg you can probably answer the documentation part better.

File a PR adding it to the User Guide for now? Once I'm able to see the content, I'll be able to better judge if we should keep it there or move it into a Topic Guide or something else.

[sandeepkiran-js]

Hi , is the issue still open & up for someone to contribute

[uranusjr]

Please go ahead and open a pull request.

[wcgonzal]

Evening everyone,
I'd like to help with this Issue. To make sure I understand, improvement is intended to use the command
pip search -vvv pandas (for example)
to in turn
output >>a list of all possible platform and pandas options that are applicable for the python-version the CPU currently has in place?

This is with the intention of adding it as part of the User Guide in the pip repository. Any resources or clarification is appreciated. :)

[pfmoore]

I would suggest that we simply add a note to the documentation for --platform and --python-version saying that in order to find the correct value to use, you need to query the target system, looking at packaging.tags.platform_tags() and sys.version respectively.