finished py launcher section, finishing Windows guide reorg

python-discord · wookie184 · Nov 17, 2022 · Nov 5, 2022 · Nov 5, 2022 · Nov 6, 2022
commit 790d076ac2416062466092763b07b22540dee937
diff --git a/...s/content/resources/guides/python-guides/windows/installing-and-using-python.md b/...s/content/resources/guides/python-guides/windows/installing-and-using-python.md
@@ -6,8 +6,8 @@ toc: 3
 ---
 
 Our recommended way of installing Python on a Windows operating system is using the full installer from the official
-[python.org Downloads page](https://www.python.org/downloads/) (the main yellow button) using the default options, except
-making sure to check the "Add python.exe to PATH" checkbox. Getting Python from the [Microsoft
+[python.org Downloads page](https://www.python.org/downloads/) (the main yellow button) using the default options,
+except making sure to check the "Add python.exe to PATH" checkbox. Getting Python from the [Microsoft
 Store](https://apps.microsoft.com/store/search/python) is _not_ recommended as [it can cause various
 issues](../microsoft-store).
 
@@ -27,10 +27,10 @@ Follow the steps below to install the latest version of Python on Windows.
 (The instructions were written with Windows 10 and Python 3.11.0 in mind, but should be nearly or fully identical with
 Windows 11 or other modern versions of Python.)
 
-> If you want a fresh start, you may want to first uninstall any other versions of Python on your PC, including those from
-> the Microsoft Store, if you have any. This can be done in the ["Apps & features" Windows
-> settings](/static/images/content/python-on-windows/ms_store_uninstall.png) (type "apps and features" into the Start Menu
-> to find it). Though it's fine to have multiple versions of Python installed at once. It can be useful for testing
+> If you want a fresh start, you may want to first uninstall any other versions of Python on your PC, including those
+> from the Microsoft Store, if you have any. This can be done in the ["Apps & features" Windows
+> settings](/static/images/content/python-on-windows/ms_store_uninstall.png) (type "apps and features" into the Start
+> Menu to find it). Though it's fine to have multiple versions of Python installed at once. It can be useful for testing
 > version compatibility or for working on projects made in a certain version. Only uninstall things if you want to.
 
 1.  Go to [python.org/downloads](https://www.python.org/downloads) and click the big yellow "Download Python 3.x.x"
@@ -70,16 +70,16 @@ and run some code like `print("Hello, World!")`.
 
 [![Testing Python console](/static/images/content/python-on-windows/recommended_install_7.png)](/static/images/content/python-on-windows/recommended_install_7.png)
 
-Or try the more usual way of running Python by typing `py` or `python` in a new terminal window to open up the Python
+Or try the more usual way of running Python by typing `python` in a new terminal window to open up the Python
 [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop), or use `python somefile.py` to run some
-Python file (if `py` runs the wrong version of Python, [see below](#the-py-launcher) for how to change the default). Use
-whichever terminal you prefer: Command Prompt, PowerShell, an IDE-integrated terminal, [Windows
+Python file. Use whichever terminal you prefer: Command Prompt, PowerShell, an IDE-integrated terminal, [Windows
 Terminal](https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701). It just has to be a freshly opened
 terminal or the commands may not be recognized.
 
 [![Testing py and python](/static/images/content/python-on-windows/recommended_install_8.png)](/static/images/content/python-on-windows/recommended_install_8.png)
 
-You can double check what versions of Python and [pip](https://pip.pypa.io/en/stable/) were installed by running `python -V` or `pip -V` in a terminal:
+You can double check what versions of Python and [pip](https://pip.pypa.io/en/stable/) were installed by running
+`python -V` or `pip -V` in a terminal:
 
 [![Checking python and pip versions](/static/images/content/python-on-windows/testing_path_worked_1.png)](/static/images/content/python-on-windows/testing_path_worked_1.png)
 
@@ -152,15 +152,58 @@ search "About your PC" in the Start Menu and open the Settings page. Then look f
 
 ## The py Launcher
 
-dg:TODO
+By default, when you install Python on Windows from a [python.org installer](https://www.python.org/downloads/windows/),
+it comes with the "py launcher". The py launcher is a command line tool you invoke using the `py` command and it helps
+you run a specific version of Python when you have multiple versions installed.
+
+The `py` command is not merely shorthand for the `python` command. They are separate programs as can be seen in the
+"Apps & features" Windows settings. Though running either of them with no arguments will start the Python
+[REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop).
+
+The py launcher provides the `py -0` command (or `py --list`) which lists the Python versions you have installed.
+`py -0p` does the same but includes the paths to the Python executables.
+
+For example, on my PC I have Python 3.11 and 3.10 installed, and the py launcher shows it:
+
+![py launcher list command](/static/images/content/python-on-windows/py_launcher_1.png)
+
+The versions are ordered from newest to oldest, and the asterisk (`*`) indicates which version running `py` will
+currently call by default (3.11 in my case). Exactly which version that is depends on the following requirements, and
+may not be the same version you get from running `python` (if you get any).
+
+> If an exact version is not given to `py`, using the latest version can be overridden by the following, (in
+> priority order):
+>
+> -   An active virtual environment/
+> -   A [shebang](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) line in the script (if present).
+> -   With a `-2` or `-3` flag and matching PY_PYTHON2 or PY_PYTHON3 environment variable.
+> -   A PY_PYTHON environment variable.
+> -   From `[defaults]` in py.ini in your `%LOCALAPPDATA%` folder.
+> -   From `[defaults]` in py.ini beside py.exe (usually in `C:\Windows`, use `where.exe py` to locate).
+
+You can give the py launcher an exact version of Python to run (assuming you have it installed) by specifying the major
+and minor versions. For example, to invoke Python 3.7, you could run `py -3.7`. You can then pass any arguments on top
+of that, for example `py -3.7 myscript.py` to run `myscript.py`, or `py -3.7 -m pip install numpy` to invoke `pip` to
+install [NumPy](https://numpy.org/) into Python 3.7.
+
+If you want can always use `py` instead of `python` and not have any Python versions on the Windows Path at all (check
+out [this guide](<(../putting-python-on-path)>) to learn about the Windows Path). Though, once in a while third party
+software may want to invoke `python`, so keeping it on the Path is handy. We recommend having your "main" Python version
+on the Path so you can invoke it with `python`, and then using `py -X.Y` whenever you want a different version, e.g. `py -3.10`.
+
+The official documentation of the `py launcher` can be found
+[here](https://docs.python.org/3/using/windows.html#python-launcher-for-windows).
+
+The py launcher is not available on Unix-based platforms such as macOS, but there is [an unofficial version by Brett
+Cannon](https://github.com/brettcannon/python-launcher).
 
 ## Virtual Environments
 
 Virtual environments ("venvs") are a way of giving each of your Python projects their own space to install dependencies
 in, so different projects can have different versions of the same dependencies. For example, suppose you are working on
-two websites that both use the Python web-framework [Django](https://www.djangoproject.com/download/). One site is older and
-requires Django 3.2, and the other is newer and requires Django 4.1. If you install Django globally, no matter if you
-install 3.2 or 4.1, one or the or the other of the projects will have the wrong version. But if you make a virtual
+two websites that both use the Python web-framework [Django](https://www.djangoproject.com/download/). One site is older
+and requires Django 3.2, and the other is newer and requires Django 4.1. If you install Django globally, no matter if
+you install 3.2 or 4.1, one or the or the other of the projects will have the wrong version. But if you make a virtual
 environment for each project you can install the required Django version for each separately.
 
 Virtual environments are not exclusive to Windows, but the commands to use them can differ a bit across operating

diff --git a/pydis_site/static/images/content/python-on-windows/py_launcher_1.png b/pydis_site/static/images/content/python-on-windows/py_launcher_1.png