Add some notes on OS differences

Author: barneygale

Doc/library/os.path.rst

@@ -354,6 +354,14 @@ the :mod:`glob` module.)
    is raised. If *strict* is ``False``, the path is resolved as far as possible
    and any remainder is appended without checking whether it exists.
 
+   .. note::
+      This function emulates the operating system's procedure for making a path
+      canonical, which differs slightly between Windows and UNIX with respect
+      to how links and subsequent path components interact.
+
+      Operating system APIs make paths canonical as needed, so it's not
+      normally necessary to call this function.
+
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
 

Lib/test/test_ntpath.py

@@ -368,6 +368,9 @@ def test_realpath_symlink_loops(self):
         self.assertRaises(OSError, ntpath.realpath, ABSTFN + "1")
         self.assertRaises(OSError, ntpath.realpath, ABSTFN + "2")
         self.assertRaises(OSError, ntpath.realpath, ABSTFN + "1\\x")
+
+        # Windows eliminates '..' components before resolving links, so the
+        # following 3 realpath() calls are not expected to raise.
         self.assertPathEqual(ntpath.realpath(ABSTFN + "1\\.."),
                              ntpath.dirname(ABSTFN))
         self.assertPathEqual(ntpath.realpath(ABSTFN + "1\\..\\x"),