bpo-29688: document and test pathlib.Path.absolute().

Author: barneygale

Doc/library/pathlib.rst

@@ -1052,6 +1052,20 @@ call fails (for example because the path doesn't exist).
       Added return value, return the new Path instance.
 
 
+.. method:: Path.absolute()
+
+   Make the path absolute, without resolving symlinks, and return a new path
+   object.  This is equivalent to prepending the current directory::
+
+      >>> p = Path('..')
+      >>> p
+      PosixPath('..')
+      >>> p.absolute()
+      PosixPath('/home/antoine/pathlib/..')
+      >>> Path.cwd() / p
+      PosixPath('/home/antoine/pathlib/..')
+
+
 .. method:: Path.resolve(strict=False)
 
    Make the path absolute, resolving any symlinks.  A new path object is
@@ -1239,13 +1253,14 @@ Below is a table mapping various :mod:`os` functions to their corresponding
 
    Not all pairs of functions/methods below are equivalent. Some of them,
    despite having some overlapping use-cases, have different semantics. They
-   include :func:`os.path.abspath` and :meth:`Path.resolve`,
+   include :func:`os.path.abspath` and :meth:`Path.absolute`,
    :func:`os.path.relpath` and :meth:`PurePath.relative_to`.
 
 ====================================   ==============================
 :mod:`os` and :mod:`os.path`           :mod:`pathlib`
 ====================================   ==============================
-:func:`os.path.abspath`                :meth:`Path.resolve` [#]_
+:func:`os.path.abspath`                :meth:`Path.absolute` [#]_
+:func:`os.path.realpath`               :meth:`Path.resolve`
 :func:`os.chmod`                       :meth:`Path.chmod`
 :func:`os.mkdir`                       :meth:`Path.mkdir`
 :func:`os.makedirs`                    :meth:`Path.mkdir`
@@ -1278,5 +1293,5 @@ Below is a table mapping various :mod:`os` functions to their corresponding
 
 .. rubric:: Footnotes
 
-.. [#] :func:`os.path.abspath` does not resolve symbolic links while :meth:`Path.resolve` does.
+.. [#] :func:`os.path.abspath` normalizes the resulting path, which may change its meaning in the presence of symlinks.
 .. [#] :meth:`Path.relative_to` requires ``self`` to be the subpath of the argument, but :func:`os.path.relpath` does not.

Lib/pathlib.py

@@ -1046,24 +1046,19 @@ def rglob(self, pattern):
             yield p
 
     def absolute(self):
-        """Return an absolute version of this path.  This function works
-        even if the path doesn't point to anything.
+        """Return an absolute version of this path by prepending the current
+        working directory. No normalization or symlink resolution is performed.
 
-        No normalization is done, i.e. all '.' and '..' will be kept along.
         Use resolve() to get the canonical path to a file.
         """
-        # XXX untested yet!
         if self.is_absolute():
             return self
-        # FIXME this must defer to the specific flavour (and, under Windows,
-        # use nt._getfullpathname())
         return self._from_parts([self._accessor.getcwd()] + self._parts)
 
     def resolve(self, strict=False):
         """
         Make the path absolute, resolving all symlinks on the way and also
-        normalizing it (for example turning slashes into backslashes under
-        Windows).
+        normalizing it.
         """
 
         def check_eloop(e):

Lib/test/test_pathlib.py

@@ -1456,6 +1456,39 @@ def test_cwd(self):
         p = self.cls.cwd()
         self._test_cwd(p)
 
+    def _test_absolute(self):
+        P = self.cls
+
+        # Simple absolute paths
+        self.assertEqualNormCase(str(P('/').absolute()), '/')
+        self.assertEqualNormCase(str(P('/a').absolute()), '/a')
+        self.assertEqualNormCase(str(P('/a/b').absolute()), '/a/b')
+        self.assertEqualNormCase(str(P('//a/b').absolute()), '//a/b')
+
+        # Simple relative paths
+        self.assertEqualNormCase(str(P().absolute()), BASE)
+        self.assertEqualNormCase(str(P('.').absolute()), BASE)
+        self.assertEqualNormCase(str(P('a').absolute()), os.path.join(BASE, 'a'))
+        self.assertEqualNormCase(str(P('a', 'b', 'c').absolute()), os.path.join(BASE, 'a', 'b', 'c'))
+
+        # Symlinks should not be resolved
+        self.assertEqualNormCase(str(P('linkB', 'fileB').absolute()), os.path.join(BASE, 'linkB', 'fileB'))
+        self.assertEqualNormCase(str(P('brokenLink').absolute()), os.path.join(BASE, 'brokenLink'))
+        self.assertEqualNormCase(str(P('brokenLinkLoop').absolute()), os.path.join(BASE, 'brokenLinkLoop'))
+
+        # '..' entries should be preserved and not normalised
+        self.assertEqualNormCase(str(P('..').absolute()), os.path.join(BASE, '..'))
+        self.assertEqualNormCase(str(P('a', '..').absolute()), os.path.join(BASE, 'a', '..'))
+        self.assertEqualNormCase(str(P('..', 'b').absolute()), os.path.join(BASE, '..', 'b'))
+
+    def test_absolute(self):
+        old_path = os.getcwd()
+        os.chdir(BASE)
+        try:
+            self._test_absolute()
+        finally:
+            os.chdir(old_path)
+
     def _test_home(self, p):
         q = self.cls(os.path.expanduser('~'))
         self.assertEqual(p, q)