[Django] #35511: Documentation uses the py binary in Windows, which may not always be available

[Django]

#35511: Documentation uses the py binary in Windows, which may not always be
available
------------------------------------------------+--------------------------
Reporter: Alex | Owner: Alex
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Keywords: windows
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
------------------------------------------------+--------------------------
In places like the tutorial, the windows version of the command always
uses `py` like, `py -m django --version`.

The `py` binary is available only if python is installed via the
python.org installer. However, if you install python via the Microsoft
Store, the `py`binary is not available.
> When you install Python from the Microsoft Store, the py command is not
included. For Linux, macOS, WSL and the Microsoft Store version of Python,
you should use the python3 (or python3.7) command.
https://learn.microsoft.com/en-us/windows/python/faqs#what-is-py-exe-

The python.org installer adds `py` by default, however, it only adds
`python` if the option "Add python.exe to PATH" is selected in the first
step of the installer.
Without the option, typing `python` or `python3` will launch the
[https://apps.microsoft.com/detail/9pjpw5ldxlz5?hl=en-us&gl=US Microsoft
Store]

I would recommend that in the
[https://docs.djangoproject.com/en/5.0/intro/install/#install-python
install section] have specific instructions for Windows to use the
python.org installer, not the Microsoft Store one. Also explain that the
store one, doesn't have `py`.
--
Ticket URL: <https://code.djangoproject.com/ticket/35511>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#35511: Documentation uses the py binary in Windows, which may not always be
available

--------------------------------------+------------------------------------

Reporter: Alex | Owner: Alex
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev

Severity: Normal | Resolution:
Keywords: windows | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by Sarah Boyce):

* stage: Unreviewed => Accepted

Comment:

I think having a note in the
[https://docs.djangoproject.com/en/dev/howto/windows/ how to install for
Windows] section might be more appropriate.
I think the note can be that `py` may need to be `python` or `python3`
depending on how they installed Python 🤔

Happy to see a PR 👍
--
Ticket URL: <https://code.djangoproject.com/ticket/35511#comment:1>

[Django]

#35511: Documentation uses the py binary in Windows, which may not always be
available
--------------------------------------+------------------------------------
Reporter: Alex | Owner: Alex
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: windows | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------
Changes (by Sarah Boyce):

* cc: Baptiste Mispelon (added)

--
Ticket URL: <https://code.djangoproject.com/ticket/35511#comment:2>

[Django]

#35511: Documentation uses the py binary in Windows, which may not always be
available
--------------------------------------+------------------------------------
Reporter: Alex | Owner: Alex
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: windows | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by Alex):

Replying to [comment:1 Sarah Boyce]:

> I think having a note in the
[https://docs.djangoproject.com/en/dev/howto/windows/ how to install for
Windows] section might be more appropriate.

I was unaware of this page, and I think that's a problem. The
[https://docs.djangoproject.com/en/dev/howto/ how to page] seems like a
catch all for guides, but I doubt most people using windows that follow
the tutorial will find it.

To find it, if you start at the
[https://docs.djangoproject.com/en/dev/intro/install/ install page] of the
tutorial, you have to first click in
[https://docs.djangoproject.com/en/dev/topics/install/ complete
installation guide] and then on
[https://docs.djangoproject.com/en/dev/howto/windows/ How to install
Django on Windows].

The quick install guide, which says "this guide will guide you to a
minimal installation that’ll work while you walk through the
introduction.", has no direct mention of Windows, of the binary
differences.

So while the note in the Windows page would be needed, I think the the
[https://docs.djangoproject.com/en/dev/intro/install/ install] page should
either link very clearly to the windows instructions or have the same or a
similar note to the one that needs to be added in the Windows page. I'm
not sure which of these two options would be better.
--
Ticket URL: <https://code.djangoproject.com/ticket/35511#comment:3>

[Django]

#35511: Documentation uses the py binary in Windows, which may not always be
available
--------------------------------------+------------------------------------
Reporter: Alex | Owner: Alex
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: windows | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by Sarah Boyce):

So on the install page you linked (which is the quick install intro), in
the first paragraph there is a link to the
[https://docs.djangoproject.com/en/dev/topics/install/ complete
installation guide]. On that page, in the first section there is a link to
the Windows installation guide. This is quite logical to me considering we
are talking about specific cases and trouble shooting.
To me, the quick guide should be "quick/light" and not bombard the user
with too much information. They should refer to the complete guide if they
encounter issues
--
Ticket URL: <https://code.djangoproject.com/ticket/35511#comment:4>

[Django]

#35511: Documentation uses the py binary in Windows, which may not always be
available
--------------------------------------+------------------------------------
Reporter: Alex | Owner: Alex
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: windows | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Changes (by Alex):

* has_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/35511#comment:5>

[Django]

#35511: Documentation uses the py binary in Windows, which may not always be
available
--------------------------------------+------------------------------------
Reporter: Alex | Owner: Alex
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: windows | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Changes (by Sarah Boyce):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/35511#comment:6>

[Django]

#35511: Documentation uses the py binary in Windows, which may not always be
available
--------------------------------------+------------------------------------
Reporter: Alex | Owner: Alex
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: windows | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Changes (by Alex):

* needs_better_patch: 1 => 0

--
Ticket URL: <https://code.djangoproject.com/ticket/35511#comment:7>

[Django]

#35511: Documentation uses the py binary in Windows, which may not always be
available

-------------------------------------+-------------------------------------
Reporter: Alex | Owner: Alex
Type: | Status: assigned
Cleanup/optimization |

Component: Documentation | Version: dev
Severity: Normal | Resolution:

Keywords: windows | Triage Stage: Ready for
| checkin

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Sarah Boyce):

* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/35511#comment:8>

[Django]

#35511: Documentation uses the py binary in Windows, which may not always be
available
-------------------------------------+-------------------------------------
Reporter: Alex | Owner: Alex

Type: | Status: closed

Cleanup/optimization |
Component: Documentation | Version: dev

Severity: Normal | Resolution: fixed

Keywords: windows | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce <42296566+sarahboyce@…>):

* resolution: => fixed
* status: assigned => closed

Comment:

In [changeset:"2e47dde438d689199934bca0967152a3b0e8a95f" 2e47dde4]:
{{{#!CommitTicketReference repository=""
revision="2e47dde438d689199934bca0967152a3b0e8a95f"
Fixed #35511 -- Documented when the py binary is unavailable on Windows.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35511#comment:9>

[Django]

#35511: Documentation uses the py binary in Windows, which may not always be
available
-------------------------------------+-------------------------------------
Reporter: Alex | Owner: Alex
Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: windows | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Sarah Boyce <42296566+sarahboyce@…>):

In [changeset:"c4d3434ea093aa75a49f8cc1bbf22536f0c24871" c4d3434]:
{{{#!CommitTicketReference repository=""
revision="c4d3434ea093aa75a49f8cc1bbf22536f0c24871"
[5.1.x] Fixed #35511 -- Documented when the py binary is unavailable on
Windows.

Backport of 2e47dde438d689199934bca0967152a3b0e8a95f from main.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35511#comment:10>