bpo-36264: Updates documentation for change to expanduser on Windows (GH-12294)

Doc/library/os.path.rst

@@ -172,10 +172,10 @@ the :mod:`glob` module.)
    password directory through the built-in module :mod:`pwd`. An initial ``~user``
    is looked up directly in the password directory.
 
-   On Windows, :envvar:`HOME` and :envvar:`USERPROFILE` will be used if set,
-   otherwise a combination of :envvar:`HOMEPATH` and :envvar:`HOMEDRIVE` will be
-   used.  An initial ``~user`` is handled by stripping the last directory component
-   from the created user path derived above.
+   On Windows, :envvar:`USERPROFILE` will be used if set, otherwise a combination
+   of :envvar:`HOMEPATH` and :envvar:`HOMEDRIVE` will be used.  An initial
+   ``~user`` is handled by stripping the last directory component from the created
+   user path derived above.
 
    If the expansion fails or if the path does not begin with a tilde, the path is
    returned unchanged.
@@ -183,6 +183,9 @@ the :mod:`glob` module.)
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
 
+   .. versionchanged:: 3.8
+      No longer uses :envvar:`HOME` on Windows.
+
 .. index::
    single: $ (dollar); environment variables expansion
    single: % (percent); environment variables expansion (Windows)

Doc/whatsnew/3.8.rst

@@ -236,6 +236,10 @@ now return ``False`` instead of raising :exc:`ValueError` or its subclasses
 characters or bytes unrepresentable at the OS level.
 (Contributed by Serhiy Storchaka in :issue:`33721`.)
 
+:func:`~os.path.expanduser` on Windows now prefers the :envvar:`USERPROFILE`
+environment variable and does not use :envvar:`HOME`, which is not normally set
+for regular user accounts.
+
 
 ncurses
 -------
@@ -672,6 +676,10 @@ Changes in the Python API
   :exc:`dbm.gnu.error` or :exc:`dbm.ndbm.error`) instead of :exc:`KeyError`.
   (Contributed by Xiang Zhang in :issue:`33106`.)
 
+* :func:`~os.path.expanduser` on Windows now prefers the :envvar:`USERPROFILE`
+  environment variable and does not use :envvar:`HOME`, which is not normally
+  set for regular user accounts.
+
 
 CPython bytecode changes
 ------------------------