Repository: pypa/pip
Pull request: doc: Explain how to query values for --platform and --python-version 
Fixes https://github.com/pypa/pip/issues/6369

Problem statement:
Better documentation on using --platform and --python-version
**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
```

<!-- Provide examples of real world use cases that this would enable and how it solves the problem described above. -->

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

Hints from issue discussion:
> 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?
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.


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](https://www.python.org/dev/peps/pep-0425/)).

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.

 
> 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?
hey I would like to get some more insight into this issue
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](https://www.python.org/dev/peps/pep-0427/#file-name-convention)). 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](https://packaging.python.org/specifications/platform-compatibility-tags/).
I would like to work on this issue , please assign me this issue . @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.
@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](https://www.python.org/dev/peps/pep-0427/#file-name-convention)). 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](https://packaging.python.org/specifications/platform-compatibility-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.
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()`.

Commit message: fix: changed command sysconfig.get_platform() by packaging.tags.sys_tags()

Patch to review:
diff --git a/docs/html/cli/pip_download.rst b/docs/html/cli/pip_download.rst
index d247c51ccfb..03117136997 100644
--- a/docs/html/cli/pip_download.rst
+++ b/docs/html/cli/pip_download.rst
@@ -47,7 +47,16 @@ constrained download requirement. If some of your dependencies are not
 available as binaries, you can build them manually for your target platform
 and let pip download know where to find them using ``--find-links``.
 
+.. note::
 
+   To determine the appropriate values for ``--python-version`` and ``--platform``, you can query the target system using the following commands:
+
+   - For the Python version, use :func:`sysconfig.get_python_version() <sysconfig.get_python_version>`.
+   - For the platform, use :func:`packaging.tags.sys_tags() <packaging.tags.sys_tags>`.
+
+   Refer to the official Python documentation for more details:
+   - `sysconfig.get_python_version() <https://docs.python.org/3/library/sysconfig.html#sysconfig.get_python_version>`_
+   - `packaging.tags.sys_tags() <https://packaging.pypa.io/en/latest/tags.html>`_
 
 Options
 =======
diff --git a/news/6369.doc.rst b/news/6369.doc.rst
new file mode 100644
index 00000000000..00742e20ff5
--- /dev/null
+++ b/news/6369.doc.rst
@@ -0,0 +1 @@
+Provided information about the --platform and --python-version options of the ``pip download`` command


Code review comments:
diff_hunk: @@ -47,7 +47,16 @@ constrained download requirement. If some of your dependencies are not
 available as binaries, you can build them manually for your target platform
 and let pip download know where to find them using ``--find-links``.
 
+.. note::
 
+   To determine the appropriate values for ``--python-version`` and ``--platform``, you can query the target system using the following commands:
+
+   - For the Python version, use :func:`sysconfig.get_python_version() <sysconfig.get_python_version>`.
+   - For the platform, use :func:`packaging.tags.sys_tags() <packaging.tags.sys_tags>`.
+
+   Refer to the official Python documentation for more details:
+   - `sysconfig.get_python_version() <https://docs.python.org/3/library/sysconfig.html#sysconfig.get_python_version>`_
+   - `packaging.tags.sys_tags() <https://packaging.pypa.io/en/latest/tags.html>`_
path: docs/html/cli/pip_download.rst
text: @user1:
This should be `platform_tags()` not `sys_tags()`.

@user1:
Btw, I think this was my fault, @user2 original comment said `platform_tags()` and somehow I got confused and wrote `get_tags()` in https://github.com/pypa/pip/pull/13251#issuecomment-2709024464

@author:
> This should be `platform_tags()` not `sys_tags()`.

done