Confusing documentation for "py -V"

[serhiy-storchaka]

Documentation

The example in the documentation for the -V option in py.exe looks confusing:

   $> py -V:Distributor\1.0 ...

Is it supposed to use a forward slash for company "Distributor" and tag "1.0", or tag "Distributor\1.0" with default company "PythonCore"?

cc @zooba

Linked PRs

• gh-148488: Clarify that both / and \ slashes are accepted in py -V:company/tag #148856
• gh-148488: Clarify py -V documentation examples #153308

[zooba]

Either slash is fine, though backslash is canonical because it derives from Windows registry paths.

Is it just the choice of slash that's confusing? Or is there something else that could be changed to make it more clear what's going on here (without making it seem like we only support our own distributions)?

[serhiy-storchaka]

The code only handles the forward slash. -V:Distributor\1.0 is parsed as tag "Distributor\1.0". If it was supposed to be company "Distributor" and tag "1.0", then there is an error in the documentation, it should use -V:Distributor/1.0. If this supposed to be tag "Distributor\1.0", the documentation is confusing, because it does not clearly explain this.

[zooba]

This is the legacy launcher then?

Which documentation are you looking at? It was completely rewritten for the deprecation in 3.14 and the new Python install manager, so it shouldn't be possible for this to apply to 3.13 and also 3.14.

[serhiy-storchaka]

Doc/using/windows.rst

cpython/Doc/using/windows.rst

Line 172 in d22922c

$> py -V:Distributor\1.0 ...

[zooba]

This is where the forward/backslash gets handled, then:

https://github.com/python/pymanager/blob/bf5407e7337fb5b997d55120003139da40cf8563/src/manage/tagutils.py#L176

[serhiy-storchaka]

Then it should be explicitly stated that both slashes are accepted. When you read "slash", this usually only means "/".

Also, should not there be the versionchanged directive, because this feature was not in older Python?

[zooba]

This feature isn't in Python at all, it's in the install manager, so the versionchanged is implied by changing tool. And "slash" on Windows typically allows either, since it has compatibility handling everywhere for POSIX users.

There's a lot that's accepted that isn't specified - these are user docs, not a specification. I don't think it's worth making the initial language more complex to accommodate that level of detail.

If we need a specification other than source code, it probably is best to be a markdown file in the pymanager repo.

[serhiy-storchaka]

This is is in Python docs now, and the documentation is confusing. It says about slash, but the example contains the backslash, and it is not explained how it will be parsed.